This tutorial gives an introduction to basic features and most common usage scenarios of the WSO2 ESB by walking you through two sample applications: one that performs message mediation by logging information about messages that have a specific header, and one that performs service mediation by performing logic on all messages that are destined for a specific endpoint.
Setting up the ESB
WSO2 ESB setup is relatively very easy. While a more detailed description of the installation steps are given in the Installation Guide, we have given below a summary to get you started fast.
- Ensure that the following are in your environment:
- JDK 1.6.* or higher is installed
- JAVA_HOME environment variable is set to <JDK_HOME>. For example,
JAVA_HOME=c:\Program Files\java\jdk1.6.0_27.
- Go to http://wso2.com/products/enterprise-service-bus/, click "Binary", and download the ESB distribution ZIP file.
- Extract the ZIP file. The path to this folder will be referred to as <PRODUCT_HOME> throughout the documentation.
- Open a command prompt (or a shell in Linux) and go to the <PRODUCT_HOME>\bin directory.
- Start the ESB server by executing wso2server.sh (or wso2server.bat in Windows).
The operation log keeps running until the server starts, which usually takes several seconds. Wait until the server has fully booted up and displays a message similar to "WSO2 Carbon started in n seconds."
Starting the Management Console
Now that the ESB is up and running, let's open its Management Console. WSO2 ESB starts with a default configuration, which is sufficient for the first sample scenario discussed here. The default configuration will be changed later when running the second sample scenario.
1. Set the log level of org.apache.synapse to DEBUG by editing the <PRODUCT_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.
2. To access the Management Console, open a web browser and enter this URL: https://localhost:9443/carbon.
3. On the ESB Sign-in screen, type admin for the username and admin for the password, and then click "Sign-in".
The Home page of the management console opens with various menu items listed on the left navigation panel. The ESB is now ready to execute the two sample mediation scenarios:
Message Mediation
In this sample, the ESB is 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. You can replace this simple functionality with any combination of advanced mediations such as transformation and content-based routing as well as bridging different communication protocols.
This sample will walk you through the following tasks:
Configure the Sample
1. In the ESB's Management Console, click "Monitor -> System Logs".
You will see the same set of log messages that appeared in the command line when the ESB started.
2. In the left panel, click "Main -> Sequences". On the "Defined Sequences" tab, two sequences named "fault" and "main" are currently available.
These two sequences are generated automatically by the ESB at start up and are sufficient for this sample application. You could use this tab to add additional sequences as needed for specific mediation requirements.
3. To analyze what happens to the messages inside the main sequence, click the "Edit" link for the "main" sequence. A set of mediators appears for the main sequence as shown below.
Notice that there are two mediators named "In" and "Out" at the top level. They handle request messages and response messages respectively. The Log Mediator and Filter Mediator are listed as children of the In mediator, so incoming messages will flow through these two mediators. The Log Mediator is configured to log all the details of the messages (full log level) and the Filter Mediator is configured only to pass along messages that contain "http://localhost:9000" in the WS-Addressing header. A Send Mediator is listed as the child of the Filter Mediator ensuring that filtered messages are sent to the specified WS-Addressing destination.
By default, the Out Mediator has only a Send Mediator defined, which sends response messages back to the client. You could change this default configuration by clicking the corresponding mediator icon and modifying the parameter values in the form that appears below.
Now that you have seen the basic message flow inside the ESB, let's enable statistics monitoring and tracing by making some simple modifications to the main sequence as described below.
4. In the left pane, click "Sequences" to display all the available sequences, and then click "Enable Statistics" and "Enable Tracing" for the "main" sequence.
You have finished configuring the sample scenario and are ready to test and monitor the mediation.
Start the Server
We use a standalone Apache Axis2 Web services engine as the server, which is bundled with the WSO2 ESB distribution by default.
1. To deploy a sample service to which the client can send requests, go to the <PRODUCT_HOME>/samples/axis2Server/src/SimpleStockQuoteService directory and 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 second
2. Navigate to the <PRODUCT_HOME>/samples/axis2Server directory and start the server using the following command. This will start Axis2 server on port 9000 (HTTP).
- Linux/Unix:
./axis2server.sh - Windows:
axis2server.bat
The following messages appear 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
Run the Client
The final step is running the client.
- Navigate to the <PRODUCT_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 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 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 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>0
Monitor the Mediation
You have now seen how message mediation is performed by the ESB. Let's take a look at the various visual monitoring tools on the Monitor tab you can use to analyze the behavior of the ESB during the mediation.
1. To see runtime statistics for the system in general, click "Monitor -> System Statistics".
2. To see the log messages produced by the ESB and the actions performed by the mediation process, click "System Logs".
3. To see the trace messages produced by the ESB, click "Mediation Tracer".
4. To see the overall runtime statistics of the message mediation, click "Mediation Statistics".
The graph in the top-left corner displays the mediated messages per server, whereas the graph below it displays the mediated messages per sequence. For more runtime statistics, click the "Server Statistics" panel to display a summary of the server statistics containing total messages, average response time, etc. In the same way, you can click the "Sequence Statistics" panel to see summarized statistics for sequences.
You have completed the first sample, which illustrated how to configure and monitor the mediation of messages. The second sample walks you through the mediation of services .
Service Mediation Using Proxy Services
The ESB sends messages to services at designated endpoints. A proxy service acts as a virtual front end to a service, allowing you to mediate messages destined for that service. This service mediation can include adding WS-Security, exposing the message on a different transport, transforming the message, and more. It can mediate the messages before they are delivered to the actual endpoint, and it can mediate the response messages before they reach the client.
When a client sends a request to a service at a specific endpoint, the ESB uses the proxy service for that service to perform the service mediation. The most common service mediation is to process the message and send it to the actual service, which is usually running on a different computer. However, it is not necessary to always send the message to the actual service. You can list any combination of tasks to be performed on the messages received by the proxy service and could terminate the flow or send a message back to the client without sending it to the actual service.
Let's explore a simple proxy service scenario that illustrates service mediation. This sample walks you through the following tasks:
Configure the Sample
1. If you have not already done so, set up the ESB and start the management console before proceeding.
2. Click "Main -> Proxy Service". There are several templates available for creating a proxy service.
3. Select the "Custom Proxy" template. The proxy service creation wizard appears.
4. For the proxy service name, enter "StockQuoteProxy".
5. In the "Publishing WSDL" drop-down list, select "Specify Source URL", enter the URL of the WSDL as file:repository/samples/resources/proxy/sample_proxy_1.wsdl, and then click "Test URI" to validate the path. In the future, you can determine the WSDL of a running service using the ?wsdl operation.
6. Select the transports needed to expose the proxy service in the "Transport Settings" panel at the bottom of the page. For this example, leave the defaults set to make this proxy service available on both HTTP and HTTPS.
Note that you can also add service parameters to the proxy service. When the ESB starts, it initiates all proxy services that may need to fetch WSDLs associated with proxy services. If the ESB cannot locate those WSDLs during startup, it ignores them and continues.
7. Click Next, and then add a target endpoint to handle request messages and a target 'in' sequence to handle request messages. To add a target endpoint, click "Define Inline" under "Define Endpoint" and click the "Create" button that appears.
8. In the list that opens, select "Address Endpoint". This will allow us to configure the endpoint by typing the URL of the service.
9. Type the EPR of the target endpoint in the Address field as "http://localhost:9000/services/SimpleStockQuoteService", leave the other fields unchanged, and click "Save" to add the endpoint to the proxy service.
10. You will be navigated back to the previous screen. Click "Next" leaving the 'In' Sequence empty.
11. Next, to add an 'out' sequence that will send the response messages back to the client, click "Define Inline" under "Define Out Sequence" and click the "Create" button that appears.
12. In the sequence editor, click the "Add Child" icon, and then click "Core -> Send" from the sub menus to create a send mediator with default configuration.
13. Click "Save", and then click "Finish" to save and quit the wizard.
14. The newly created proxy service appears in the "deployed services" list. Click its name to view its dashboard.
You have finished configuring the sample scenario and are ready to test and monitor the mediation.
Start the Server
You already built and deployed the SimpleStockQuote service, so simply start the server by switching to the <PRODUCT_HOME>/samples/axis2Server directory and running one of the following commands:
- Linux / Unix:
./axis2server.sh - Windows:
axis2server.bat
Run the Client
Now that the server is running, let's run the client and send a request to the service. Go to <PRODUCT_HOME>/samples/axis2Clients directory and type the following command:
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM
This command sends a stockquote request directly to the provided transport endpoint at: http://localhost:8280/services/StockQuoteProxy. The response from the server is displayed in the console as follows:
Standard :: Stock price = $165.32687331383468
Monitor the Mediation
As with the previous message mediation sample, you can monitor log messages, statistics, and trace messages for the proxy service mediation. Let's look only at the statistics for the proxy service.
- Click "Monitor -> Mediation Statistics".
- On the statistics page, click "Proxy Service Statistics" in the top right-hand box to view summarized statistics for the "StockQuoteProxy" service.
You have now learned how to mediate messages and services in the management console using basic examples. For a more advanced example, see sample #150 in the ESB Samples. As with the basic examples in this tutorial, you can build all samples using the ESB management console's graphical interface without having to study the configuration language in the samples and without editing any files at all.