This guide demonstrates two sample applications covering the basic and the most common usage scenarios of WSO2 ESB, namely Message Mediation and Service Mediation (using Proxy Services). You will be guided through a series of steps to create, execute, and analyze these mediation configurations using the ESB Management Console.
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. Let's start with the basics.
Our first task is to download WSO2 ESB. Open a Web browser and access 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 as a ZIP archive.
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 current working 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 backend 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 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 message on the console to indicate that the ESB started successfully.
[2011-05-23 13:57:03,248] INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 20 sec
Configuring the ESB to Perform Message Mediation
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 https://localhost:9443/carbon. You will be directed to the login screen of the Management Console shown below.
The Management Console ships with a default username and password combination: "admin", "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 Monitor > System Logs in the left-hand side navigation pane 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 Monitor > System Statistics 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. In the Defined Sequences tab 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 of 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" and "Out" 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. 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, namely 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.
Starting the Sample Apache Axis2 Server
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/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp
[mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
[mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/repository/services
compile-all:
[javac] Compiling 9 source files to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/classes
build-service:
[mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
[mkdir] Created dir: /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
[copy] Copying 1 file to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
[copy] Copying 1 file to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF
[copy] Copying 9 files to /home/user/wso2esb/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote
[jar] Building jar: /home/user/wso2esb/samples/axis2Server/repository/services/SimpleStockQuoteService.aar
BUILD SUCCESSFUL
Total time: 1 secondNow 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 JAVA_HOME: /usr/java Using AXIS2 Repository : /home/user/wso2esb/samples/axis2Server/repository Using AXIS2 Configuration : /home/user/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/user/wso2esb/samples/axis2Server/repository [SimpleAxisServer] Using the Axis2 Configuration File : /home/user/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/user/wso2esb/samples/axis2Client/target/classes
compile:
[javac] Compiling 10 source files to /home/user/wso2esb/samples/axis2Client/target/classes
stockquote:
[java] Standard :: Stock price = $82.19300717003419
BUILD SUCCESSFUL
Total time: 4 secondsThis 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">
<m0:request>
<m0:symbol>IBM</m0:symbol>
</m0:request>
</m0:getQuote>
</soapenv:Body>
</soapenv:Envelope>0We 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 Monitor > 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 Monitor > Mediation Tracer to view the trace messages emitted by the ESB. You will see trace messages as shown in the following image.
Now let's move on to viewing mediation statistics. Click Monitor > Mediation Statistics to view the overall runtime statistics graphically. You will see the updated statistics reflecting the message mediation we have just performed.
Top left box displays the mediated messages per server. Bottom right box displays the mediated messages per sequence.
Now let's go deeper into the statistics console and get more information about the runtime statistics. First click on the Server Statistics 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 Sequence Statistics 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 Web Services > 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 Web Services > Add > Proxy Service on left panel. You will be shown a list of standard proxy service templates to choose from.
Select the Custom Proxy template from the list and you will be directed to the proxy service creation 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/samples/resources/proxy/sample_proxy_1.wsdl as the WSDL URL and click on 'Test URI' button to instantly validate the path.
Next, select the transports that you need to expose the proxy service. By default proxy service will available in both HTTP and HTTPS transports. Also you can add service parameters to proxy service. During ESB startup process, it will start all proxy services and that may need to fetch WSDLs associated with proxy services. If ESB cannot locate those WSDLs during statup, it will ignore such services and continue with the startup process.
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 'Define Inline' under 'Define Endpoint' and click on Create button that appears. In the next sub menu select 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 is shown above. 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 'Define Inline' under 'Define Out Sequence' and click Create. You will be presented with a sequence editor. Click on the 'Add Child' 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.
Starting the Sample Apache Axis2 Server
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/services/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 Monitor > Mediation Statistics. You will be directed to the overall statistics page.
To get more information about proxy service statistics, click on Proxy Service Statistics 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).