xBus

Example

In the XBUS_HOME/etc directory there are two examplary standard.conf files to show the configuration of the xBus. Each of the two files contains some examplary data flows, with different technical ways and different protocols.

  • standard_sample_simple.conf is a more simple one. It can be used with the binary and the source distribution, without additional services like database or message queue server.
  • standard_sample_full.conf (plain) / (commented) is a more complex one. It can be used with the all-inclusive distribution and makes use of the database, the message queue server and the servlet engine.
These two examples should be a good starting point for your configuration, since they show how to configure most of the features of the xBus. Some more examples for the configuration and the use of the xBus can be found in the directory of the automated tests (XBUS_HOME/test/standard.conf).

To see how the xBus works, you can start the examples. The input and output files are located in XBUS_HOME/sample. The examplary input files have to be renamed to meet the filenames of the configuration. E.g. copy the file Example1Infile.xml.sic to Example1Infile.xml. Which receiver has to be started is explained below for the particular examples. After processing the files, you can inspect:

  • the output files in XBUS_HOME/sample
  • the Journal, either in the file XBUS_HOME/log/journal_*.log or in the database (see Remote Administration), depending on the configuration
  • the different log files in XBUS_HOME/log

The next sections will explain the example configuration in detail. You will find the corresponding headings in the example configuration files.

 Example 1: XML with simple routing

Dataflow Example1

Two interfaces (called systems) are defined: Example1InFile and Example1OutFile. Both are files that are located in XBUS_HOME/sample.

The router is configured to route all messages from Example1InFile to Example1OutFile. Since both interfaces use XML messages, the XSLT transformer will be started in between.

This is also an example of validating a XML message against a DTD: The incoming XML file contains the name of a DTD and XML validation is activated in the configuration (System_Example1InFile_XMLValidating=true). When receiving the XML message, the content of the DTD is read in XBUS_HOME/etc/dtd and the XML message is checked against this DTD.

To process Example1InFile, the background service or the servlet engine must be started, because the FileReceiverThread is configured as the receiver.

 Example 2: RecordTypes with fixed field length

Dataflow Example2

The second example has some significant differences compared to the first one:

  • The incoming data will be routed into two different files.
  • The data format of the incoming data and one of the outgoing files is a record type format. Record types are typically used by mainframe applications.
  • The second outgoing file contains the internal XML representation of the incoming data.

To process Example2PartsOrderIncoming, the shell script for processing single messages must be started, because the FileReceiver is configured as the receiver. In a Windows command window type receiversingle Example2PartsOrderIncoming, in a Unix shell type receiversingle.sh Example2PartsOrderIncoming to start the processing of this example.

 Example 3: XML with complex routing

Dataflow Example3

This example has a more complex data flow:

  1. The incoming XML data will be read out of a file.
  2. It will internally transformed into another XML format.
  3. This other XML format will be reversed by calling a Java application.
  4. This data will be reversed again by calling the same Java application.
  5. The outcome will be written into two message queues. Here the data will be transformed to the xBus-specific XML format, which serves as a container.
  6. Each message queue will be read and the message will be sent to HTTP destinations.
  7. From both HTTP destinations the message will be received and written to a file.

To process this example, the background service or the servlet engine must be started, because the FileReceiverThread is configured as the first receiver.

This is also an example of validating a XML message against a XML Schema: The Schema validation is activated by specifying the name of the Schema in the configuration (System_Example3InFile_XMLSchema=Address.xsd). When receiving the XML message, the content of the Schema is read in XBUS_HOME/etc/Schema and the XML message is checked against this Schema.

In standard_sample_simple.conf, the two steps with the message queues and the HTTP destinations are omitted. After the two reverse steps, the data is written directly to the files.

 Example 4: JavaReceiver

Dataflow Example4

You can process this example by starting the script XBUS_HOME/bin/javareceiversample(.sh).

A java program will be started, which will call the JavaReceiverService. See Starting for more details on invoking the xBus integrated in Java applications. The xBus delivers a response, which is a reversed string.

The reversion of the string is done with the use of an individual transformer. Normally the xBus reads the needed transformer out of xbus.conf, using the two participating messages (from / to). But it is possible to overrule this behavior, by explicitly defining which tranformer to use. Every transformer may be used, that supports the dataformats of the two participating messages.

The JavaTransformer used in this example needs two further configuration entries, to define which Java class and method to use for transforming the message.

 Example 5: DatabaseSender (only in standard_sample_full.conf)

Dataflow Example5

The fifth example shows, how to access databases with the DatabaseSender. It uses a table named example5 specially designed for this example. This table is already setup in the all-inclusive distribution. For the other distributions, you will find create statements in XBUS_HOME/src/sql to setup the example5 table. When there is no file for your database, you have to edit an existing one. Please be aware, that the first column (number) must be an automatically incrementing datatype.

First an XML file is read by the FileReceiver. This file contains three SQL statements:

  • The first statement inserts a row in the database.
  • The second and third statement select the whole content of the table, with different sorting.

The SQL statements will be sent to the database, the result is returned in a XML format and written into a file. The XML formats of the request and response are described here.

In a Windows command window type receiversingle Example5InFile, in a Unix shell type receiversingle.sh Example5InFile to start the processing of this example.

 Definition of connections (only in standard_sample_full.conf)
To connect to databases, message queue servers and for HTTPS connections some parameters are necessary. These parameters are gathered here.
 Notification of critical errors (only in standard_sample_full.conf)

When a message cannot be processed, an error message is written to the Trace and the Journal. Additionally it is possible to actively notify an administrator about the error, to be able of immediate reaction. Writing an email with the SMTP sender is a common way to do this.

 Basic definitions

Some basic definitions are necessary for the operation of the xBus:

  • The amount and the destination of the Trace
  • The amount and the destination of the Journal
  • Retry parameters