The Quick Start guide gives an introduction to basic features and most common usage scenarios of the WSO2 ESB by walking you through two sample applications.
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.
1.Ensure that the following are installed in your environment.
- JDK 1.6.* or higher installed.
- JAVA_HOME environment variable is set to <JDK_HOME>. For example,
JAVA_HOME=c:\Program Files\java\jdk1.6.0_27.
2. Download the ESB distribution from http://dist.wso2.org/products/enterprise-service-bus/4.5.1/wso2esb-4.5.1.zip.
3. Extract the zip file to a folder which will be referred to as the <PRODUCT_HOME> throughout the rest of this guide.
4. Open a command prompt (or a shell in Linux) and go to <PRODUCT_HOME>\bin directory.
5. Start the ESB server by executing wso2server.sh (or wso2server.bat in Windows).
6. 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 <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.
2. To access the Management Console, open a web browser and type the URL: https://localhost:9443/carbon.
3. You should see the ESB log-in screen. Type user/password as admin/admin and click "Login" button.
4. The Home page of the management console will open with various menu items listed on the left navigation panel.
The ESB now ready to execute the two sample mediation scenarios as follows:
Message Mediation
In this sample, the 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. This simple functionality can be replaced by any combination of advanced mediations such as transformation, and content-based routing as well as bridging between different communication protocols.
1. In the ESB's Management Console, click "Monitor -> System Logs".
2. You will see the same set of log messages which appeared in the command line when ESB started.
3. Click "Monitor > System Statistics" to view runtime statistics of the system. Note that currently there are no runtime statistics as no message mediation has happened.
4. Click on the "Sequences" link on the left panel. In 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. Any number of additional sequences can also be added using this page to suit specific mediation requirements. For this sample, the pre-defined sequences are sufficient.
5. To analyze what happens to the messages inside the main sequence, click on the "Edit" link of the "main" sequence. You will see a set of mediators listed for the main sequence as shown below.
Note two mediators named "In" and "Out" at the top level. They 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. The Log Mediator is configured to log all the details of the messages (i.e. full log level) and the Filter Mediator is configured only to pass through messages containing "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. This is the configuration of the request messages. Also note that there is only a Send Mediator defined in the Out Mediator by default, which sends response messages back to the client. This default configuration can be changed by clicking on the corresponding mediator icon and modifying the parameter values in the form which appears below.
This is the basic message flow inside the ESB. To enable statistics monitoring and tracing, simple modifications have to be done to the main sequence as described below.
6. Click on the "Sequences" link in the left menu to display all the available sequences. Then, click "Enable Statistics" and "Enable Tracing" links of the "main" sequence.
Configuration of the second sample scenario is complete. You are now ready to test and monitor the mediation.
Starting the Sample Apache Axis2 Server
We use a standalone Apache Axis2 Web services engine as the server, which is bundled with the WSO2 ESB distribution by default.
7. To deploy a sample service to which the client can send requests, go to <PRODUCT_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 second
8. Navigate to <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
Running the Client
9. The final step is running the client. Navigate to <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
Monitoring the Mediation
Demonstrated above is how message mediation is performed using the WSO2 ESB. The ESB also provides various visual monitoring tools to analyze the behavior of the ESB during the mediation.
10. Click on "Monitor -> System Logs" to see the log messages produced by the ESB, displaying the actions performed in the mediation process.
11. Click on "Monitor -> Mediation Tracer" to view the trace messages emitted by the ESB, as shown in the following example.
12. Next, click "Monitor -> Mediation Statistics" to view the overall runtime statistics of the message mediation just performed, as shown in the example below.
The graph on the top-left corner displays the mediated messages per server. The one below displays the mediated messages per sequence.
For more runtime statistics, click on the "Server Statistics" panel and a summary of the server statistics containing total messages, average response time, etc. will appear. In the same way, summarized statistics for sequences can be viewed by clicking on "Sequence Statistics" panel.
Service Mediation using Proxy Services
A proxy acts as a service hosted in the WSO2 ESB. It 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. It 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 any way you like. The most common method is 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 for better understanding.
Configuring WSO2 ESB for the Sample Scenario
Start the ESB as explained in section 'Starting the Management Console' and follow the steps below.
1. Click "Services -> Add -> Proxy Service". A list of standard proxy service templates will appear to select from.
2. Select the "Custom Proxy" template. The proxy service creation wizard will appear as shown below.
3. Provide the proxy service name as "StockQuoteProxy" and a WSDL, which can be displayed using the ?wsdl operation with an actual service. In the 'Publishing WSDL' drop down list under 'General Settings,' select 'Specify Source URL' option and enter the URL of the WSDL as file:repository/samples/resources/proxy/sample_proxy_1.wsdl. Then, click on "Test URI" button to instantly validate the path.
4. Select the transports needed to expose the proxy service in the "Transport Settings" panel at the bottom of the page and click "Next."
By default, the proxy service will be available in both HTTP and HTTPS transports. Also, service parameters can be added to the proxy service. During the ESB start-up, it initiates all proxy services that may need to fetch WSDLs associated with proxy services. If ESB cannot locate those WSDLs during stat-up, it ignores them and continues.
5. Next, 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 the "Create" button that appears.
6. In the list that opens, select "Address Endpoint".
7. A web form appears to configure the new endpoint. Type the EPR of the target endpoint in the Address field as "http://localhost:9000/services/SimpleStockQuoteService" and leave the other fields unchanged. Click "Save" to add the endpoint to the proxy service.
8. You will be navigated back to the previous screen. Click "Next" leaving the 'In' Sequence empty.
9. Next, add an 'out' sequence to the proxy service in order to send the response messages back to the client. Select "Define Inline" option under "Define Out Sequence" and click the "Create" button that appears.
10. A sequence editor appears. 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."
11. Finally, back on the wizard, click "Finish" to save and quit the wizard.
12. The newly-created proxy service will appear in the "deployed services" list. Click on its name to access its dashboard.
Configuration of the second sample scenario is complete. You are now ready to test and monitor the mediation.
Starting the Sample Apache Axis2 Server
13. As the "SimpleStockQuote" service is already built and deployed in the previous section, simply start the server by switching to <PRODUCT_HOME>/samples/axis2Server directory and running the following command.
- Linux / Unix: ./axis2server.sh
- Windows: axis2server.bat
Running the Client
14. Go to <PRODUCT_HOME>/samples/axis2Clients directory and type the following command:
ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM
It sends a stockquote request directly to the provided transport endpoint at: http://localhost:8280/services/StockQuoteProxy. The response from the server will be displayed on the console as follows:
Standard :: Stock price = $165.32687331383468
Monitoring the Mediation
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 that are different from the previous sample.
15. Click "Monitor -> Mediation Statistics". The statistics page appears. For more information about proxy service statistics, click on "Proxy Service Statistics" in the top, right-hand box, which opens the summarized statistics for the "StockQuoteProxy" service.
This guide illustrates the visual construction of a proxy service and a simple use case. Refer from samples #150 in the ESB Samples for an in-depth coverage of more advanced use cases. All samples can be built by using the ESB management console's graphical interface without having to study the configuration language in the samples or without editing any file at all.