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 prerequisites installed on your system to follow this guide.
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://wso2.org/downloads/esb. You will then see the list of available releases. Click on the latest release version, and you will be directed to the WSO2 ESB latest release download page. Now download the binary distribution ZIP or tar.gz archive compatible with your operating system.
WSO2 ESB can be installed by simply extracting the downloaded binary archive. A directory named wso2esb with the version number will be created in the selected parent directory, containing all the files required by 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 <esb-home>/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: ./wso2server.sh Windows: wso2server.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/upul/wso2esb Using JAVA_HOME: /usr/java Using SYNAPSE_XML: -Dsynapse.xml=/home/upul/wso2esb/webapp/WEB-INF/classes/conf/synapse.xml 2007-11-08 17:57:45,904 [-] [main] INFO ServiceBusConfiguration Configuration loaded from : /home/upul/wso2esb/webapp/WEB-INF/classes/conf/server.xml 2007-11-08 17:57:48,361 [-] [main] INFO ServiceBusManager Database server started on localhost over port 1528 2007-11-08 17:57:48,365 [-] [main] INFO ServerManager Using the Axis2 Repository /home/upul/wso2esb/repository 2007-11-08 17:57:49,630 [-] [main] INFO SynapseInitializationModule Initializing Synapse at : Thu Nov 08 17:57:49 LKT 2007 2007-11-08 17:57:49,630 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Loading mediator extensions... 2007-11-08 17:57:54,097 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Initializing the Synapse configuration ... 2007-11-08 17:57:54,099 [127.0.1.1-upul] [main] INFO XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration 2007-11-08 17:57:54,235 [127.0.1.1-upul] [main] INFO SynapseConfigurationBuilder Loaded Synapse configuration from : /home/upul/wso2esb/webapp/WEB-INF/classes/conf/synapse.xml 2007-11-08 17:57:54,246 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Deploying the Synapse service.. 2007-11-08 17:57:54,250 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Initializing Sandesha 2... 2007-11-08 17:57:54,331 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Deploying Proxy services... 2007-11-08 17:57:54,331 [127.0.1.1-upul] [main] INFO SynapseInitializationModule Synapse initialized successfully...! 2007-11-08 17:57:54,528 [127.0.1.1-upul] [main] INFO HttpCoreNIOSender HTTPS Sender starting 2007-11-08 17:57:54,530 [127.0.1.1-upul] [main] INFO HttpCoreNIOSender HTTP Sender starting 2007-11-08 17:57:54,871 [127.0.1.1-upul] [main] INFO HttpCoreNIOListener HTTPS Listener starting on port : 4433 2007-11-08 17:57:54,871 [127.0.1.1-upul] [main] INFO ServerManager Starting transport https on port 4433 2007-11-08 17:57:54,875 [127.0.1.1-upul] [main] INFO HttpCoreNIOListener HTTP Listener starting on port : 8280 2007-11-08 17:57:54,875 [127.0.1.1-upul] [main] INFO ServerManager Starting transport http on port 8280 2007-11-08 17:57:54,894 [127.0.1.1-upul] [main] INFO ServerManager Starting transport vfs 2007-11-08 17:57:54,894 [127.0.1.1-upul] [main] INFO ServerManager Starting transport admin/https 2007-11-08 17:57:54,894 [127.0.1.1-upul] [main] INFO ServerManager Ready for processing 2007-11-08 17:57:55,933 [127.0.1.1-upul] [main] INFO TomcatServer Tomcat Server Started at https://192.168.13.1:9444/esb 2007-11-08 17:57:55,934 [127.0.1.1-upul] [main] INFO Main WSO2 ESB started in 10214 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/carbon. 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 environment. 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 requirements. 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 "Edit" link in the same row as the "main" sequence. 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 on the corresponding mediator icon and modifying the parameter values in the form which appears below. 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 "Sequences" link in the left menu to display all the available sequences.
Now click on the first two icons under the Actions heading of the "main" sequence. That is 'enable statistics' and 'enable tracing'.
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:~/wso2esb/samples/axis2Server/src/SimpleStockQuoteService$ ant Buildfile: build.xml clean: init: [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Server/repository/services compile-all: [javac] Compiling 9 source files to /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes build-service: [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 1 file to /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 1 file to /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 9 files to /home/upul/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [jar] Building jar: /home/upul/wso2esb/samples/axis2Server/repository/services/SimpleStockQuoteService.aar BUILD SUCCESSFUL Total time: 1 second
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:~/wso2esb/samples/axis2Server$ ./axis2server.sh Using Bouncy castle JAR for Java 1.5 Using JAVA_HOME: /usr/java Using AXIS2 Repository : /home/upul/wso2esb/samples/axis2Server/repository Using AXIS2 Configuration : /home/upul/wso2esb/samples/axis2Server/repository/conf/axis2.xml 2007-11-08 18:00:54,283 [-] [main] INFO SimpleHTTPServer [SimpleAxisServer] Starting [SimpleAxisServer] Using the Axis2 Repository : /home/upul/wso2esb/samples/axis2Server/repository [SimpleAxisServer] Using the Axis2 Configuration File : /home/upul/wso2esb/samples/axis2Server/repository/conf/axis2.xml 2007-11-08 18:00:55,494 [-] [main] INFO HttpCoreNIOSender HTTPS Sender starting 2007-11-08 18:00:55,495 [-] [main] INFO HttpCoreNIOSender HTTP Sender starting 2007-11-08 18:00:55,798 [-] [main] INFO HttpCoreNIOListener HTTPS Listener starting on port : 9002 2007-11-08 18:00:55,804 [-] [main] INFO HttpCoreNIOListener HTTP Listener starting on port : 9000 2007-11-08 18:00:55,805 [-] [main] INFO 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/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dsymbol=IBM -Dmode=quote
You can see the following output with the quote price sent by the server.
user@host:~/wso2esb/samples/axis2Client$ ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dsymbol=IBM -Dmode=quote Buildfile: build.xml init: [mkdir] Created dir: /home/upul/wso2esb/samples/axis2Client/target/classes compile: [javac] Compiling 10 source files to /home/upul/wso2esb/samples/axis2Client/target/classes stockquote: [java] Standard :: Stock price = $82.19300717003419 BUILD SUCCESSFUL Total time: 4 seconds
This sends a request for a stock quote for the symbol IBM, sets the transport URL to the ESB (http://localhost:8280), and the WS-Addressing EPR set to the actual server (http://localhost:9000/services/SimpleStockQuoteService). The actual wire level HTTP message sent by the client is as follows, and is sent over port 8280 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/services/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 analyze 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 "Mediation Tracer" to view the trace messages emitted by the ESB. You will see trace messages as listed in the following image.
Now let's move on to the most interesting part, mediation statistics. Click on Mediation Statistics to view the overall runtime statistics graphically using 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 "Service > List" 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" on left panel. You will be directed to the add proxy service wizard 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 are going to specify a WSDL for this proxy service. It can be displayed using the ?wsdl operation with an actual service. Select 'Specify Source URL' in the 'Publishing WSDL' drop down list under 'General Settings'. 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 as the WSDL URL and click on 'Test URI' button to instantly validate the path.
Then click 'Next' at the bottom of the page to proceed to the next step of the proxy service creation wizard. As the next step of the wizard we will add a target endpoint to handle request messages and a target in sequence to handle request messages. To add a target endpoint, select the option 'Anonymous' under 'Endpoint Options' and click on the 'Add' button that appears. In the next sub menu select "Add Address Endpoint". A web form 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/services/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.
As for the in sequence we will leave it empty for this sample. So click on 'Next' to proceed to the next step of the wizard.
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. Select "Anonymous" in "Out Sequence Options" and click "Add". 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. Click "Save" to save the out sequence configuration. Finally on the wizard click "Finish" to save and quit the wizard.
Now on the services listing page you will be able to see the newly created proxy service. Click on the service name link to enter the service dashboard. On the service dashboard 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:8280/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 Mediation 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 #150 and above in the Samples guide, for in-depth 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).