There are four different ways to start the processing of messages by the xBus:

1. Starting it with a shell script to process one message or a set of messages. In conjunction with a scheduler (e.g. cron) this can be very powerful.
2. Running the xBus as a background service, to continuously receive messages.
3. Running inside a servlet engine, for example Tomcat.
4. Calling it directly from another Java application.

Which one to choose depends on the type of technical communication on one hand and on the requirements on the other hand.

This is the easiest way to start the processing of one or more messages.

Starting the shell script receiversingle with the names of some interfaces as parameters starts the appropriate receivers, as configured in standard.conf, to receive and process messages. After that, the process will terminate.

The following receivers can be started this way:

• FileXXXReceiver
• FTPReceiver
• AS400XXXReceiver

The script can be started either from the command line or by a scheduler, e.g. cron on Unix servers.

Sometimes it is more meaningful to run the xBus as a service in the background, to continuously wait for messages to process. The service can start the following receivers:

• FileXXXReceiverThread
• MQReceiverThread
• POP3XXXReceiverThread

For every interface where one of these receivers is configured, one thread is started. So all interface will be processed in parallel.

There are two options to start the background service:

• The script receiverservice_startup starts the background service. receiverservice_shutdown will stop it.
• On Windows servers, the background service can be installed as a Windows-Service, that is started automatically after booting the server. install_receiverservice installs the Windows-Service, uninstall_receiverservice removes it.

With the JMX remote administration there are some possibilities to control the service:

• Viewing the state of the background receiver and the Java Virtual Machine.
• Starting and stopping particular background receivers.
• Restarting the complete receiver service, i.e. stopping all background receivers, initialization of the configuration and restarting the background receivers.
• Stopping the receiver service completely. The Java Virtual Machine will be terminated, so the receiver service cannot be restarted by the remote administration.

When messages shall be received via HTTP, the xBus must be run inside a servlet engine. Read here how to install it. When the servlet engine is started after the installation, it will process the interfaces for the following receivers:

• HTTPXXXReceiver
• FileXXXReceiverThread
• MQReceiverThread
• POP3XXXReceiverThread

As you can see, when the xBus is running inside a servlet engine, the background service is not needed.

When you have downloaded the all-inclusive distribution, you can start or install the Tomcat servlet engine, the HSQLDB database and the OpenJMS message queue server:

• The script services_startup starts the three services. services_shutdown will stop them.
• On Windows servers, the services can be installed as Windows-Services, that are started automatically after booting the server. install_services installs the Windows-Services, uninstall_services removes them.

With the HTML remote administration or the JMX remote administration there are some possibilities to control the background receivers running inside the servlet engine:

• Viewing the state of the background receiver and the Java Virtual Machine.
• Starting and stopping particular background receivers.
• Restarting the complete receiver service, i.e. stopping all background receivers, initialization of the configuration and restarting the background receivers.

The fourth way of starting the xBus is integrated in another Java application:

The class
net.sf.xbus.bootstrap.JavaReceiverBootstrap
provides the method
public Object receive(String system, Object request) throws XException

Calling this method by a Java application will process the given request for the given system and return the result according to the configuration of the xBus. If the request cannot be processed, a XException is thrown.

Prerequisites:

• XBUS_HOME/lib/xbus-bootstrap.jar must be in the CLASSPATH.
• The environment variable XBUS_HOME must be given to the calling Java application. Specify the parameter -Dxbus.home="%XBUS_HOME%" (Windows) resp. -Dxbus.home="${XBUS_HOME}" (Unix) when starting the application.

A lot of scripts are available for the different tasks of the xBus, which can be found in the directory XBUS_HOME/bin. There are two versions of all scripts:

• the Windows versions with the suffix .cmd
• the Unix versions with the suffix .sh

Script	Parameters	Description
receiverservice_startup	-	Starting the ReceiverService to process messages in the background.
receiverservice_shutdown	-	Stopping the ReceiverService.
receiversingle	Up to 9 logical names of systems to be processed, separated by spaces.	Starting a single datatransfer for the given systems.
services_startup	-	(only in the all-inclusive distribution) Starting database (HSQLDB), message queue server (OpenJMS) and servlet engine (Tomcat).
services_shutdown	-	(only in the all-inclusive distribution) Stopping database (HSQLDB), message queue server (OpenJMS) and servlet engine (Tomcat).
install_receiverservice	-	(only Windows NT/2000/XP) Installing the ReceiverService as a Windows-Service. The service named xBus_ReceiverService will be started automatically after booting the server.
uninstall_receiverservice	-	(only Windows NT/2000/XP) Uninstalling the Windows-Service named xBus_ReceiverService.
install_services	-	(only in the all-inclusive distribution, only Windows NT/2000/XP) Installing database (HSQLDB), message queue server (OpenJMS) and servlet engine (Tomcat) as Windows-Services. The services will be started automatically after booting the server.
uninstall_services	-	(only in the all-inclusive distribution, only Windows NT/2000/XP) Uninstalling the Windows-Services database (HSQLDB), message queue server (OpenJMS) and servlet engine (Tomcat).
soap_restart	host: e.g. localhost port: typically 8080	(only in the all-inclusive distribution) Restarting the xBus running inside a servlet engine by calling a web service.
setenv	-	This script is called internally by the other scripts. It sets some common used parameters like the CLASSPATH.
traceFileRenamer	-	This script calls the TraceFileRenamer to rename the trace file if its size exceeds a configured limit.