The Quick Start guide 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
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
- 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 Go to http://dist.wso2.orgcom/products/enterprise-service-bus/4.5.1/wso2esb-4.5.1.zip, click "Binary", and download the ESB distribution ZIP file.
3. Extract the zip ZIP file. The path to a this folder which will be referred to as the <PRODUCT_HOME> throughout the rest of this guidedocumentation.
4. Open a command prompt (or a shell in Linux) and go to the <PRODUCT_HOME>\bin directory.
...
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
| Anchor | ||||
|---|---|---|---|---|
|
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>/libthe <PRODUCT_HOME>/repository/conf/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 enter this URL: https://localhost:9443/carbon.
3. You should see On the ESB logSign-in screen. Type user/password as admin/admin and click "Login" button.
4. , type admin for the username and admin for the password, and then click "Sign-in".
The Home page of the management console will open opens with various menu items listed on the left navigation panel. The ESB is now ready to execute the two sample mediation scenarios as follows:
Message Mediation
| Anchor | ||||
|---|---|---|---|---|
|
In this sample, the ESB will be 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. This You can replace this simple functionality can be replaced by with 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
This sample will walk you through the following tasks:
Configure the Sample
| Anchor | ||||
|---|---|---|---|---|
|
1. In the ESB's Management Console, click "Monitor -> System Logs".
2. You will see the same set of log messages which that appeared in the command line when the 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 "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. Any number of additional sequences can also be added using this page to suit You could use this tab to add additional sequences as needed for specific mediation requirements. For this sample, the pre-defined sequences are sufficient.5. To .
3. To analyze what happens to the messages inside the main sequence, click on the "Edit" link of for the "main" sequence. You will see a A set of mediators listed appears for the main sequence as shown below.
Note Notice that there are 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 The Log Mediator and Filter Mediator are listed as children . Therefore, 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 (i.e. full log level) and the Filter Mediator is configured only to pass through along messages containing 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. This is the configuration of the request messages. Also note that there is
By default, the Out Mediator has only a Send Mediator defined in the Out Mediator by default, which sends response messages back to the client. This You could change this default configuration can be changed by clicking on the corresponding mediator icon and modifying the parameter values in the form which that appears below.
This is Now that you have seen the basic message flow inside the ESB. To , let's enable statistics monitoring and tracing , by making some simple modifications have to be done to the main sequence as described below.
64. Click on the In the left pane, click "Sequences" link in the left menu to display all the available sequences. Then, and then click "Enable Statistics" and "Enable Tracing" links of for the "main" sequence.
Configuration of the second You have finished configuring the sample scenario is complete. You and are now ready to test and monitor the mediation.
...
Start the
...
Server
| Anchor | ||||
|---|---|---|---|---|
|
We use a standalone Apache Axis2 Web services engine as the server, which is bundled with the WSO2 ESB distribution by default.
71. To deploy a sample service to which the client can send requests, go to the <PRODUCT_HOME>/samples/axis2Server/src/SimpleStockQuoteService directory . Run and run "ant" to build and deploy this service to the sample Axis2 server.
| Code Block |
|---|
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 |
82. 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.
| Code Block |
|---|
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
...
| Anchor | ||||
|---|---|---|---|---|
|
The final step is running the client.
- Navigate to the <PRODUCT_HOME>/samples/axis2Client directory and type the following command
...
- :
| Code Block |
|---|
ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dsymbol=IBM -Dmode=quote |
...
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.
| Code Block |
|---|
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
...
| Anchor | ||||
|---|---|---|---|---|
|
You have now seen how message mediation is performed using by the WSO2 ESB. The ESB also provides 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.
10. Click on 1. To see runtime statistics for the system in general, click "Monitor -> System Logs" to Statistics".
2. To see the log messages produced by the ESB , displaying and the actions performed in by the mediation process, click "System Logs".
11. Click on "Monitor -> Mediation Tracer" to view 3. To see the trace messages emitted produced by the ESB, as shown in the following exampleclick "Mediation Tracer".
12. Next, click "Monitor -> Mediation Statistics" to view 4. To see the overall runtime statistics of the message mediation just performed, as shown in the example below, click "Mediation Statistics".
The graph on in the top-left corner displays the mediated messages per server. The one below , whereas the graph below it displays the mediated messages per sequence. For more runtime statistics, click on the "Server Statistics" panel and to display 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 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
| Anchor | ||||
|---|---|---|---|---|
|
The ESB sends messages to services at designated endpoints. A proxy service acts as a service hosted in the WSO2 ESB. It typically fronts an existing service endpoint. A proxy service can be created and exposed 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, schema, WSDL, or QoS (such as WS-Security, WS-Reliable Messaging) aspect than the real service. It transforming the message, and more. It can mediate the messages before being they are delivered to the actual endpoint, and it can mediate the responses response messages 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 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, probably which is usually running on a different computer. ButHowever, it is not necessary to always send the message to the actual service. You may can list any combination of tasks to be performed on the messages received for by the proxy service , and could terminate the flow or send some a message back to the client even without sending it to an the actual service.
Let's explore a simple proxy services scenario for better understanding.
...
Start the ESB as explained in section 'Starting the Management Console' and follow the steps below.
1. Click "Services -> Add service scenario that illustrates service mediation. This sample walks you through the following tasks:
Configure the Sample
| Anchor | ||||
|---|---|---|---|---|
|
1. If you have not already done so, set up the ESB and start the management console before proceeding.
2. Click "Main -> Proxy Service". A list of standard proxy service templates will appear to select fromThere are several templates available for creating a proxy service.
23. Select the "Custom Proxy" template. The proxy service creation wizard will appear as shown belowappears.
34. Provide For the proxy service name as , enter "StockQuoteProxy" and a WSDL, which can be displayed using the ?wsdl operation with an actual service.
5. 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, and then click on "Test URI" button to instantly validate the path. In the future, you can determine the WSDL of a running service using the ?wsdl operation.
46. 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 . For this example, leave the defaults set to make this proxy service available on both HTTP and HTTPS transports. Also, service parameters can be added .
Note that you can also add service parameters to the proxy service. During When the ESB start-upstarts, it initiates all proxy services that may need to fetch WSDLs associated with proxy services. If the ESB cannot locate those WSDLs during stat-upstartup, it ignores them and continues.
57. 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, select the option click "Define Inline" under "Define Endpoint" and click the "Create" button that appears.
68. In the list that opens, select "Address Endpoint".
7. A web form appears to configure the new 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" and , leave the other fields unchanged. Click , and click "Save" to add the endpoint to the proxy service.
810. You will be navigated back to the previous screen. Click "Next" leaving the 'In' Sequence empty.
911. Next, to add an 'out' sequence to the proxy service in order to that will send the response messages back to the client. Select , click "Define Inline" option under "Define Out Sequence" and click the "Create" button that appears.
1012. A In the sequence editor appears. Click on , click the "Add Child" icon, and select then click "Core " and then "-> Send" , from the sub menu. A menus to create a send mediator with default configuration will be added.
13. Click "Save."
11. Finally, back on the wizard, , and then click "Finish" to save and quit the wizard.
1214. The newly - created proxy service will appear appears in the "deployed services" list. Click on its name to access view its dashboard.
Configuration of the second You have finished configuring the sample scenario is complete. You and are now ready to test and monitor the mediation.
...
Start the
...
Server
| Anchor | ||||
|---|---|---|---|---|
|
You already built and deployed in the previous sectionSimpleStockQuote service, so simply start the server by switching to the <PRODUCT_HOME>/samples/axis2Server directory and running one of the following command.commands:
- Linux / Unix:
./axis2server.sh - Windows:
axis2server.bat
...
Run the Client
...
| Anchor | ||||
|---|---|---|---|---|
|
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:
| Code Block |
|---|
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:
| Code Block |
|---|
Standard :: Stock price = $165.32687331383468 |
...
Monitor the Mediation
| Anchor | ||||
|---|---|---|---|---|
|
As with the previous message mediation sample, you will be able to can monitor log messages, statistics, and trace messages , and statistics for the proxy services based service mediation. We will Let's look only at the statistics that are different from the previous samplefor the proxy service.15.
- 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.
This guide illustrates the visual construction of a proxy service and a simple use case. Refer from samples 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 for an in-depth coverage of more advanced use cases. All samples can be built by . 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 or and without editing any file files at all.
| Excerpt | ||
|---|---|---|
| ||
The WSO2 ESB Quick Start guide. |