Setting Up the ESB Samples

This section describes the prerequisites and instructions on how to start the ESB with the sample configurations, how to start the Axis2 server and deploy the sample back-end services to the Axis2 server as well as how to set up any listeners and transports that are required by the samples.

Once you have set up the samples, you can run them using the sample clients.

Prerequisites

1. Install all the required software as described in the Installation Prerequisites section.

   • To run the samples, you must have the correct version of the Java Development Kit/JRE as well as Apache Ant installed .

   • To run the JMS samples, you must have ActiveMQ or another JMS provider installed.

2. Open a command prompt (or a shell in Linux) and go to the <ESB_HOME>\bin directory. Then run the ant command as shown below to build the build.xml file.

   Open

   

3. Run the ESB in the DEBUG mode. To switch from the default INFO log messages to DEBUG log messages, edit the <ESB_HOME>/repository/conf/log4j.properties file and change the line log4j.category.org.apache.synapse=INFO to log4j.category.org.apache.synapse=DEBUG.

Understanding the samples

The ESB samples use several sample clients, ESB configurations and sample back-end services in order to explain different use cases. The diagram below depicts the interaction between these sample clients, the ESB and the services at a high level. The clients are able to send SOAP/REST or POX messages over transports such as HTTP/HTTPS or JMS with WS-Addressing, or WS-Security. They can send binary optimized content using MTOM, SwA, binary or plain text JMS messages. After mediation through the ESB, the requests are passed over to sample services.

Open

Starting the ESB with a sample configuration

To start the WSO2 ESB with a selected sample configuration

1. Open a command prompt (or a shell in Linux) and go to the <ESB_HOME>\bin directory.

2. Execute one of the following commands,  where <n> denotes the number assigned to the sample.

   • On Windows: wso2esb-samples.bat -sn <n>
     

   • On Linux/Solaris: ./wso2esb-samples.sh -sn <n>

For example, to start the ESB with the Sample 0 configuration on Linux/Solaris, run the following command:

The <ESB_HOME>/repository/samples directory contains all the configuration files of the ESB samples as synapse_sample_<n>.xml files. Here again <n> denotes the sample number of the sample you are running.

For example, the configuration file for Sample 0 is synapse_sample_0.xml.

Deploying sample back-end services

The sample back-end services come with a pre-configured Axis2 server. These sample services demonstrate in-only and in-out SOAP/REST or POX messaging over HTTP/HTTPS and JMS transports using WS-Addressing, and WS-Security. The samples handle binary content using MTOM and SwA.

Each back-end sample service can be found in a separate folder in the <ESB_HOME>/samples/axis2Server/src directory. You need to compile, build and deploy each back-end service to the Axis2 server.

To build and deploy a back-end service

1. Open a command prompt (or a shell in Linux) and go to the required sample folder in the <ESB_HOME>/samples/axis2Server/src directory.

2. Run ant from the selected sample directory.
   
   For example, to build and deploy SimpleStockQuoteService, run the ant command from the  <ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService directory, as follows:

   user@host:/tmp/wso2esb-2.0/samples/axis2Server/src/SimpleStockQuoteService$ ant Buildfile: build.xml ... build-service: .... [jar] Building jar: /tmp/wso2esb-2.0/samples/axis2Server/repository/services/SimpleStockQuoteService.aar BUILD SUCCESSFUL Total time: 3 seconds

Sample back-end services explained

1. SimpleStockQuoteService

   This service has four operations:

   • getQuote (in-out) - Generates a sample stock quote for a given symbol.

   • getFullQuote (in-out) - Generates a history of stock quotes for a symbol for a number of days.

   • getMarketActivity (in-out) - Returns stock quotes for a list of given symbols.

   • placeOrder (in-only) - Accepts a one way message for an order.

2. SecureStockQuoteService
   

   This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled as well as an attached security policy for signing and encrypting messages.

3. MTOMSwASampleService

   This service has three operations:

   • uploadFileUsingMTOM (in-out) - Accepts a binary image from the SOAP request as MTOM, and returns this image back again as the response.

   • uploadFileUsingSwA (in-out) - Accepts a binary image from the SOAP request as SwA, and returns this image back again as the response.

   • oneWayUploadUsingMTOM (in-only) - Saves the request message to the disk.

Starting the Axis2 server

For the ESB samples, a standalone Apache Axis2 Web services engine is used as the back-end server, which is bundled with the WSO2 ESB distribution by default.

Once each back-end service is deployed to the Axis2 server, you need to start the Axis2 server before executing the sample client.

To start the Axis2 server

1. Open a command prompt (or a shell in Linux) and go to the <ESB_HOME>/samples/axis2Server directory.

2. Execute one of the following commands 

   • On Windows: axis2server.bat

   • On Linux/Solaris:   ./axis2server.sh

This starts the Axis2 server with the HTTP transport listener on port 9000 and HTTPS on port 9002 respectively.

If you want to start multiple instances of the Axis2 server on different ports, run the following commands.  Give unique names to each server.