This document contains important information you need to know how to install and setup the xBus on your server and to understand its directory structure.

The installation procedure depends on the type of distribution you have downloaded.

1. A Java virtual machine Version 1.4 or higher must be installed. For installing the binary distribution, the runtime environment (JRE) of the standard edition (J2SE) is sufficient. If it is not currently installed on your system, you can download it here. Please make sure that the java command is in your environment path ($PATH).
2. Create a new subdirectory where you want to install the xBus. This directory will be referred as XBUS_HOME in the rest of the documentation.
3. Unpack the delivered archive file into this directory. As a result, the directory structure described below has been created.
4. Set the XBUS_HOME environment variable to point to the directory where you have installed xBus. Here are examples how can you do it for Unix or Windows platform.
5. The next step is the configuration. Go to the directory XBUS_HOME/etc and open the file standard.conf in your favourite editor.

   See Config Files to understand the syntax and semantics of the entries from this file. The Configuration Tips will help you to determine which entries are necessary to perform specific tasks.

6. After doing all configurations you can start the receivers of the xBus. Read in Starting how to do this.

1. A Java virtual machine Version 1.4 or higher must be installed. For installing the source distribution, you need the the development kit (JDK) of the standard edition (J2SE). If it is not currently installed on your system, you can download it here. Please make sure that the java command is in your environment path ($PATH).
2. To compile the sources, Ant Version 1.5 or higher must also be installed properly.
3. Create a new subdirectory where you want to install the xBus. This directory will be referred as XBUS_HOME in the rest of the documentation.
4. Unpack the delivered archive file into this directory. As a result, the directory structure described below has been created.
5. Set the XBUS_HOME environment variable to point to the directory where you have installed xBus. Here are examples how can you do it for Unix or Windows platform.
6. The ant-script build.xml for compiling the sources is in XBUS_HOME/etc. Run it without parameters to build the xBus.
7. The next step is the configuration. Go to the directory XBUS_HOME/etc and open the file standard.conf in your favourite editor.

   See Config Files to understand the syntax and semantics of the entries from this file. The Configuration Tips will help you to determine which entries are necessary to perform specific tasks.

8. After doing all configurations you can start the receivers of the xBus. Read in Starting how to do this.

The installation of the all-inclusive distribution is exactly the same as installing the binary distribution.

When the Journal shall be written to a database, 4 prerequisites are necessary:

1. A database with an existing JDBC driver must be installed.
2. In XBUS_HOME/src/sql you will find create statements to setup the Journal table and indexes. 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.
3. The JDBC driver for the used database must be copied to the directory XBUS_HOME/lib/runtime.
4. Edit XBUS_HOME/etc/standard.conf. See Journal Definitions and Connection Definitions how the entries must look like.

When the HTTPReceiver shall be used, a servlet-engine must be installed. Tomcat Version 5.5 is recommended. The following describes how to setup the installation of the xBus together with Tomcat, if you do not use the all-inclusive distribution:

1. Tomcat must be installed and the environment variable CATALINA_HOME must be set.
2. The environment variable XBUS_HOME must be made visible to Tomcat. Edit the file CATALINA_HOME/bin/catalina.[bat|sh] and insert -Dxbus.home="%XBUS_HOME%" (Windows) or -Dxbus.home="$XBUS_HOME" (Unix) in all lines that start Tomcat.
3. Run ant servlet in the directory XBUS_HOME/etc. It creates the directory CATALINA_HOME/webapps/xbus and copies all necessary files to this directory.

The complete xBus can be run inside the servlet engine, including other receivers like the MQReceiverThread. Read more about how to do this in Starting.

The xBus is able to receive/send messages from/to message queues. It has been tested with SonicMQ, FioranoMQ, SwiftMQ and OpenJMS. But it will work with any other message queue server with a driver implementing the JMS 1.0.2 API. The next lines will describe, how to setup xBus and a message queue server to work together:

1. The message queue server must be installed.
2. The JMS driver for the used message queue server must be copied to the directory XBUS_HOME/lib/runtime.
3. Edit XBUS_HOME/etc/standard.conf. See Systems Definitions and Connection Definitions how the entries must look like.

To ensure that all environment variables are set properly and consistently, xBus provides a mechanism for setting all necessary environment variables by invoking the sentenv script from each other running script, see Starting for more details. Only one variable (XBUS_HOME), which specifies the directory where the xBus is installed on the server, is required to be set manually.

For your information here is the list with all environment variables used by xBus:

XBUS_HOME - This variable points the directory where the xBus is installed. It must always be set before starting the scripts.

JAVA_HOME - The variable JAVA_HOME must be set to the root directory of the Java installation.

CLASSPATH - The CLASSPATH is used by the java interpreter to locate the libraries which are required to run the java programs. The setenv script will set this variable automatically when starting any script, it must not be set before.

xBus has a specific directory structure to organize its libraries and files. In either Windows or Unix platform, unpacking the delivered archive file will create these directories:

Directory	Content
bin	All Scripts for starting tasks of the xBus, mainly to start the receivers.
classes	Only in the source installation after compilation. This directory holds all classes of the xBus.
doc	This directory contains the HTML documentation of the xBus
etc	Various files for the operation and configuration of xBus (for example the file standard.conf) are placed in this directory and some subdirectories.
lib	Contains all necessary libraries.
log	Both Journal and Trace can be written into files. These files will be located in the log directory.
sample	Some input files to test the xBus with the delivered example configuration. See Example for more.
services	(only in the all-inclusive distribution) A database (HSQLDB), a message queue server (OpenJMS) and a servlet engine (Tomcat), intended for testing the xBus and as a development environment.
src	Java source files (only in the source distribution) and SQL scripts for setting up the Journal database.
web	Necessary files to let xBus work together with a servlet-engine.