This guide demonstrates two sample applications covering the basic and the most common usage scenarios of the WSO2 ESB, which are Message mediation and Service mediation (using Proxy services). You will be guided through a step-by-step approach to build, execute, and analyze these mediation configurations using the ESB management console, which is an AJAX based Web console for configuring and monitoring your ESB.
You should have the following pre-requisites installed on your system to follow this guide.
Note: To use the bundled HTTPS transport, you will need a Java 2 SE runtime version 1.5 or later. If you are using a J2SE below 1.5 and does not require the HTTPS transport, you may comment out the following section from your conf/axis2.xml and samples/axis2Server/repository/conf/axis2.xml configuration files.
... <transportReceiver name="https"...
...
</transportReceiver> ... <transportSender name="https"...
...
</transportSender> ....
In this example, ESB will be used to filter and log the messages passing through it. Although this simple scenario only performs simple filtering and logging, it demonstrates the basics of message mediation, where this simple functionality could be replaced with any combination of advanced mediations such as transformations, and content based routing as well as bridging between different communication protocols. So, let's start with the basics.
Our first task is to download the WSO2 ESB. Open a Web browser and access the following URL: http://dist.wso2.org/products/esb/java/. You will then see the list of available releases. Click on the 1.0 version, and you will be directed to the WSO2 ESB 1.0 release download page. Now download the binary distribution ZIP or tar.gz archive compatible with your operating system.
WSO2 ESB can be installed by extracting the downloaded binary archive. A directory named wso2esb-1.0 will be created in the selected parent directory, containing all the files required for the ESB. We will refer to this directory as <esb-home> from now on.
WSO2 ESB acts as the intermediary between the client and the server. Hence, you will need to run three programs to get an idea of message mediation. The destination server that hosts the ultimate service that has to be invoked to service the client, the client itself, and the WSO2 ESB, which sits in between to perform the mediation.
Let's first start the WSO2 ESB. Set the log level of org.apache.synapse and org.wso2.esb to DEBUG by editing the lib/log4j.properties file. This will cause the ESB to output debug messages for the actions it is performing. We can inspect these logs later using the management console. Then go to the <esb-home>/bin folder and execute the following command.
Linux: . wso2-esb.sh Windows: wso2-esb.bat
You will see the following messages on the console to indicate that the ESB started successfully.
Using Bouncy castle JAR for Java 1.5 Starting WSO2 Enterprise Service Bus ... Using ESB_HOME: /home/chathura/work/e2/wso2esb-SNAPSHOT Using JAVA_HOME: /opt/programs/jdk1.5.0_06 Using SYNAPSE_XML: -Dsynapse.xml=/home/chathura/work/e2/wso2esb-SNAPSHOT/conf/synapse.xml INFO [15 May 14:58:26] ServiceBusConfiguration - Service Bus Configuration loaded from : conf/server.xml INFO [15 May 14:58:26] ServiceBus - Using Repository /home/chathura/work/e2/wso2esb-SNAPSHOT/./repository INFO [15 May 14:58:28] ServiceBusManager - Database server started on localhost over port 1528 INFO [15 May 14:58:28] ModuleDeployer - Deploying module: sandesha2-mar INFO [15 May 14:58:29] ModuleDeployer - Deploying module: wso2statistics INFO [15 May 14:58:29] ModuleDeployer - Deploying module: synapse-1.0 INFO [15 May 14:58:29] ModuleDeployer - Deploying module: rampart INFO [15 May 14:58:29] ModuleDeployer - Deploying module: authentication INFO [15 May 14:58:29] ModuleDeployer - Deploying module: addressing INFO [15 May 14:58:29] SynapseModule - Initializing the Synapse configuration ... INFO [15 May 14:58:29] XMLConfigurationBuilder - Generating the Synapse configuration model by parsing the XML configuration INFO [15 May 14:58:29] SynapseConfigurationBuilder - Loaded Synapse configuration from : /home/chathura/work/e2/wso2esb-SNAPSHOT/conf/synapse.xml INFO [15 May 14:58:29] SynapseModule - Deploying the Synapse service.. INFO [15 May 14:58:29] SynapseModule - Initializing Sandesha 2... INFO [15 May 14:58:29] SynapseModule - Deploying Proxy services... INFO [15 May 14:58:30] SynapseModule - Synapse initialized successfully...! INFO [15 May 14:58:30] HttpCoreNIOSender - HTTPS Sender starting INFO [15 May 14:58:30] HttpCoreNIOSender - HTTP Sender starting INFO [15 May 14:58:34] ServiceDeployer - Deploying Web service: ESBAdmin.aar INFO [15 May 14:58:35] HttpCoreNIOListener - HTTPS Listener starting on port : 8443 INFO [15 May 14:58:35] HttpCoreNIOListener - HTTP Listener starting on port : 8080 INFO [15 May 14:58:37] JettyServer - Console listener started on port 9443 over HTTPS. Connect to https://10.100.1.121:9443/ INFO [15 May 14:58:37] ServiceBus - WSO2 ESB started in 11980 ms
After starting the ESB, we have to configure it to perform the required message mediation. WSO2 ESB starts with a default configuration, which is sufficient for our first scenario. Later on, we will change this configuration using the management console to build different mediations. Now examine the default configuration using the ESB console. Open a Web browser and point it to the URL https://localhost:9443. You will be directed to the log- in screen of the management console shown below.
The management console ships with a default username and password called "admin". Type "admin" in both the username and password fields and click Sign In. You will be directed to the main page of the ESB management console, which displays information about the ESB as well as brief descriptions about its core features. Click on the "System Information" link on the left panel of the console to view more information about the system on which the ESB is running. Click on the "System Logs" link on the same panel to display log messages of the system. You will see the same set of log messages displayed in the command line, when starting the ESB. Now click on the "Statistics" link to view runtime statistics of the system. You will notice that currently there are no runtime statistics as no message mediation has happened.
Now it is time to examine the mediation configuration visually. Click on the "Sequences" link on the left panel. You will see that two sequences named "fault" and "main" are currently available. These two sequences are generated automatically by the ESB at start up. We can add any number of sequences using this page to suit our mediation requirement. However these pre-defined sequences are sufficient for this sample application. Let's analyze what happens to the messages inside the main sequence by clicking on the "main" link. You will see a set of mediators listed for the main sequence as shown below.
You will see there are two mediators named "In Mediator" and "Out Mediator" at the top level. These two mediators handle request messages and response messages respectively. Inside the In Mediator, two mediators named Log Mediator and Filter Mediator are listed as children. Therefore, incoming messages will flow through these two mediators.
You will notice that Log Mediator is configured to log all the details of the messages (i.e. full log level) and Filter Mediator is configured only to pass through messages containing "http://localhost:9000" in the WS-Addressing header. You can change this default configuration by clicking the Edit icon (denoted by a pencil) near the corresponding mediator and selecting different values. Then a Send Mediator is listed as the child of the Filter Mediator. Therefore, filtered messages will be sent to the specified WS-Addressing destination. That's all we do for the request messages. Now let's look at the Out Mediator. There is only a Send Mediator defined in the Out Mediator by default. This will just send response messages back to the client.
Now we have a basic understanding about the message flow inside the ESB. We are going to make a small modification to the main sequence to enable statistics monitoring and tracing. Just click on the "Manage sequences" link at the top of the page to display all the available sequences as shown below.
Now select the last two icons under the Actions heading for the "main" sequence. If you are not sure about the icons, move the mouse over them, which will display a tooltip explaining its functionality. Now we are done with the ESB configuration. It's time to continue the rest of the steps and see it in action.
Here we are using a standalone Apache Axis2 Web services engine as the server. You don't have to get it now, as it is already bundled with your ESB distribution. We have to deploy a sample service to which the client can send requests. Go to <esb-home>/samples/axis2Server/src/SimpleStockQuoteService directory. Run "ant" to build and deploy this service to the sample Axis2 server.
user@host:~/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService$ ant Buildfile: build.xml clean: [delete] Deleting directory /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp init: [mkdir] Created dir: /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp [mkdir] Created dir: /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes compile-all: [javac] Compiling 9 source files to /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes build-service: [mkdir] Created dir: /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [mkdir] Created dir: /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 1 file to /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 1 file to /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 9 files to /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [jar] Building jar: /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/repository/services/SimpleStockQuoteService.aar BUILD SUCCESSFUL Total time: 3 seconds
Now go to <esb-home>/samples/axis2Server directory and start the server using the following command. This will start Axis2 server on port 9000 (HTTP).
You will see the following messages on the console.
user@host:~/work/e2/wso2esb-SNAPSHOT/samples/axis2Server$ . axis2server.sh Using Bouncy castle JAR for Java 1.5 Using JAVA_HOME: /opt/programs/jdk1.5.0_06 Using AXIS2 Repository : /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/repository Using AXIS2 Configuration : /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml INFO [15 May 16:31:54] SimpleHTTPServer - [SimpleAxisServer] Starting [SimpleAxisServer] Using the Axis2 Repository : /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/repository [SimpleAxisServer] Using the Axis2 Configuration File : /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml INFO [15 May 16:31:55] ModuleDeployer - Deploying module: sandesha2-mar INFO [15 May 16:31:56] ModuleDeployer - Deploying module: rampart INFO [15 May 16:31:56] ModuleDeployer - Deploying module: addressing INFO [15 May 16:31:56] HttpCoreNIOSender - HTTPS Sender starting INFO [15 May 16:31:56] HttpCoreNIOSender - HTTP Sender starting INFO [15 May 16:31:57] ServiceDeployer - Deploying Web service: SimpleStockQuoteService.aar INFO [15 May 16:31:57] HttpCoreNIOListener - HTTPS Listener starting on port : 9002 INFO [15 May 16:31:57] HttpCoreNIOListener - HTTP Listener starting on port : 9000 INFO [15 May 16:31:57] SimpleHTTPServer - [SimpleAxisServer] Started
The final step is running the client. Go to <esb-home>/samples/axis2Client directory and type the following command.
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080 -Dsymbol=IBM -Dmode=quote
You can see the following output with the quote price sent by the server.
Buildfile: build.xml init: compile: stockquote: [java] INFO [15 May 16:37:45] DeploymentEngine - No services directory was found under /home/chathura/work/e2/wso2esb-SNAPSHOT/samples/axis2Client/client_repo. [java] INFO [15 May 16:37:45] ModuleDeployer - Deploying module: sandesha2-mar [java] INFO [15 May 16:37:46] ModuleDeployer - Deploying module: rampart [java] INFO [15 May 16:37:46] ModuleDeployer - Deploying module: addressing [java] Standard :: Stock price = $145.97361636782804 BUILD SUCCESSFUL Total time: 5 seconds
This sends a request for a stock quote for the symbol IBM, sets the transport URL to the ESB (http://localhost:8080), and the WS-Addressing EPR set to the actual server (http://localhost:9000/soap/SimpleStockQuoteService). The actual wire level HTTP message sent by the client is as follows, and is sent over port 8080 to the ESB instance on the localhost.
POST / HTTP/1.1 Content-Type: text/xml; charset=UTF-8 SOAPAction: "urn:getQuote" User-Agent: Axis2 Host: 127.0.0.1 Transfer-Encoding: chunked 218 <?xml version='1.0' encoding='UTF-8'?> <soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To> <wsa:MessageID>urn:uuid:D538B21E30B32BB8291177589283717</wsa:MessageID> <wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header> <soapenv:Body> <m0:getQuote xmlns:m0="http://services.samples/xsd"> <m0:request> <m0:symbol>IBM</m0:symbol> </m0:request> </m0:getQuote> </soapenv:Body> </soapenv:Envelope>0
We have just performed a message mediation using the WSO2 ESB. Now let's analyse how ESB has behaved by looking at the various visual monitoring tools provided by the ESB. First click on System Logs to see the log messages produced by the ESB. You will see a log messages view as shown below, displaying the actions performed by the ESB in the mediation process.
Now click on Trace Messages to view the trace messages emitted by the ESB. You will see trace messages as listed in the following screen shot.
Now let's move on to the most interesting part, system statistics. Click on Statistics to view the overall runtime statistics graphically using pie charts. You will see the updated statistics reflecting the message mediation we have just performed.
Top left box displays the mediated messages per server. In our sample, there were two messages (request and response) for a single server (127.0.0.1). Bottom right box displays the messages per sequence. According the displayed statistics, both messages were mediated through the main sequence.
Now let's go deeper into the statistics console and get more information about the runtime statistics. First click on the Server Statistics Summary link in the top left box. You will be presented with a summary of the server statistics containing total messages, average response time, etc.
In the same way, you will be able to view summarized statistics for sequences by clicking on the Sequence Statistics Summary link in the bottom right box. You have successfully completed the first part of this guide. Now let's look at the next scenario, proxy services.
As the name implies, a proxy service acts as a service hosted in the WSO2 ESB, and typically fronts an existing service endpoint. A proxy service can be created and exposed on a different transport, schema, WSDL, or QoS (such as WS-Security, WS-Reliable Messaging) aspect than the real service, and can mediate the messages before being delivered to the actual endpoint, and the responses before they reach the client.
Clients can send requests for proxy services directly to the ESB, as the client sees it as being hosted on it. For example it can perform ?wsdl and view the WSDL of the virtual proxy service. In the ESB configuration, such requests can be handled in anyway you like. The most obvious thing would be to process the message and send it to the actual service, probably running on a different computer, but it is not necessary to always send the message to the actual service. You may list any combination of tasks to be performed on the messages received for the proxy service and terminate the flow or send some message back to the client even without sending it to an actual service. Let's explore a simple proxy services scenario to get a better understanding. As you have downloaded and installed the WSO2 ESB in the previous section, now you can start directly on the sample application.
As in the previous section, there should be three entities running to demonstrate proxy services, the server, client, and the ESB. Let's start with configuring the ESB with a proxy service to suit our scenario.
Start the ESB as the previous section and log in to the management console. Click "Proxy Services" on the left panel. You will see that currently no proxy services have been defined. Let's add a new proxy service by clicking "Add" . You will be directed to the basic proxy service configuration page as shown below.
First give a name to the new proxy service. In this sample type "StockQuoteProxy" as the name of the proxy service. Next we will add a target endpoint to handle request messages and a target out sequence to handle response messages. To add a target endpoint, click on the button next to the target endpoint. In the displayed sub menu select "Specify as Anonymous". In the next sub menu select "Address Endpoint". A pop up window will be displayed to configure the new endpoint. Type the EPR of the target endpoint in the Address field. In this case it is "http://localhost:9000/soap/SimpleStockQuoteService". Address endpoint editor with entered values is shown below. Keep other fields unchanged and click "Save" to add the endpoint to the proxy service.
The next step is to add an out sequence to the proxy service. We just want to send the response messages back to the client in this out sequence. Click on the button next to the Target out-sequence and select "Specify as Anonymous" in the displayed sub menu. You will be presented with a sequence editor. Click on the Add Mediator icon and select Core and then Send, from the sub menu. A send mediator with default configuration will be added. The Sequence editor after adding the send mediator is shown below. Click "Save" to save the out sequence configuration.
Next we are going to specify a WSDL for this proxy service. It can be displayed using the ?wsdl operation with an actual service. Click on the "Advanced" button to access the advanced configuration options. The first page displays the transport configuration options. You can see that our proxy service is exposed on both HTTP and HTTPS transports by default. Click Next to view the next page. It displays the QoS configuration for this proxy service. We do not worry about these things at this stage. So just click Next to skip this. Next is the miscellaneous configuration shown below. Click on the button next to the Specify WSDL label. Select "Specify URL" in the displayed submenu. You will be prompted with a text box to enter the URL of the WSDL. Type file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl and click Finish to complete the proxy service configuration. You will be directed to the Manage Proxy Services page with the newly created proxy service listed.
On the Manage Proxy Services page you will see the actions that can be performed on our new proxy service. Enable the statistics and tracing for the proxy service by clicking on the appropriate icons.
We have finished configuring the proxy service for our sample. Now let's continue the rest of the sample.
As you have built and deployed the SimpleStockQuote service in the previous section, you can simply start the server by switching to the <esb-home>/samples/axis2Server directory and running the following command.
Linux / Unix: . axis2server.sh
Windows: axis2server.bat
You can see the console messages as in the previous section.
Go to the <esb-home>/samples/axis2Clients directory and type the following command:
The above command sends a stockquote request directly to the provided transport endpoint at: http://localhost:8080/soap/StockQuoteProxy. You will see the response from the server displayed on the console as follows:
As with the previous message mediation sample, you will be able to monitor log messages, trace messages, and statistics for the proxy services based mediation. We will look only at the statistics section, which is going to be different from the previous sample. Click Statistics. You will be directed to the overall statistics page.
Note that two messages were mediated through proxy services. To get more information about proxy service statistics click on the Proxy Service Statistics Summary link in the top right box. You will see the summarized statistics for the StockQuoteProxy service, we have created in this example.
This quick guide illustrates the visual construction of a proxy service and a simple use case. Please refer to samples #100 and above in the Samples guide, for indepth coverage of more advanced use cases. You don't have to worry about the configuration language too much when reading the samples. You can build all those samples visually using the ESB management console without editing any file at all.
Yes, you are done with a quick look at the WSO2 ESB. Now it is time to go deeper and reveal the advanced features of it. You can browse through the samples of interested areas. If you have any issue regarding the ESB as a user, feel free to let us know through the WSO2 ESB user mailing list (esb-java-user@wso2.org).