Sending a Simple Message Through the ESB

To begin, let’s try a simple scenario using the sample back-end service SimpleStockQuoteService, which is provided with WSO2 ESB. This service takes an incoming stock symbol and provides the current price for that stock. We will configure the ESB to act as a proxy for client requests to the service, instead of sending messages from the client directly to the back-end service, thereby decoupling the client and the back-end service.

This scenario includes the following sections:

Installing the products

The following products will be used to implement and run this scenario:

• WSO2 Enterprise Service Bus, which includes the Axis2 server that is used to host the sample back-end service

• WSO2 Developer Studio for creating and deploying artifacts

• Apache Ant, which is used to build and deploy the sample service the Axis2 server

• SoapUI, which is used as the client to send requests to WSO2 ESB

The following instructions provide the basic installation instructions for these products.

Before you begin

1. Ensure you have met all the Installation Prerequisites.

2. Ensure that the following are in your environment:
   
   • Java Runtime Environment/JDK 1.7.0_45 or later is installed. WSO2 ESB can also work with Java 1.6.24 or later, but Developer Studio requires version 1.7.0_45 or later.
   • JAVA_HOME environment variable is set to <JDK_HOME>. For example, JAVA_HOME=c:\Program Files\java\jdk1.7.0_45. For instructions on setting JAVA_HOME, go to Installing the Product and click the link to instructions for your operating system.

To install the ESB

1. Go to http://wso2.com/products/enterprise-service-bus/, click Binary, and download the ESB distribution ZIP file.
2. Extract the ZIP file.
   The path to this folder will be referred to as <ESB_HOME> throughout the documentation.

For more detailed installation instructions, see the Installing the Product.

To install Developer Studio

1. Download and extract the Eclipse + Developer Studio 32-bit or 64-bit complete installation distribution file.
2. Start Eclipse by double-clicking the Eclipse icon in <DevStudio_Home>.

For more detailed installation instructions, see the Developer Studio Installation Guide.

To install Ant

1. Download Ant from the Ant Website and extract the archive on your computer.
2. Set the ANT_HOME environment variable and add the Ant bin directory to your path.

For more detailed installation instructions, see the Ant documentation.

To install SoapUI

1. Download SoapUI and launch the installer.
2. Follow the instructions in the installer to complete the installation.

Building and deploying SimpleStockQuoteService

SimpleStockQuoteService is a sample service provided with WSO2 ESB. In these steps, you will build and deploy the service in the Axis2 server that is also provided with WSO2 ESB.

1. In the command line window, navigate to the <ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService folder, which is where the sample service is located, and then run ant to build and deploy the service in the Axis2 server. The command line will then display the following, indicating that the build was successful:
   

2. Using the command line, go to <ESB_HOME>/samples/axis2Server and execute one of the following commands to start the Axis2 server, which will provide access to the back-end service:

   • On Windows: axis2server.bat

   • On Linux/Solaris: ./axis2server.sh
     For more information, see Starting the Axis2 server.

3. Go to http://localhost:9000/services/ in your Web browser. You will see the sample service (SimpleStockQuoteService) you deployed in the first step is now available.
   

You have just built a back-end service (SimpleStockQuoteService) and deployed it on the Axis2 server, so it is now ready to receive and process requests (that is, take an incoming stock symbol and provide a quote in response). The next step is to configure the ESB to take those incoming requests from client applications, perform any necessary logic on them, and then send them to SimpleStockQuoteService. This process of handling requests is called mediation.

Creating the message mediation artifacts

Requests going through the ESB are called messages, and message mediation is a fundamental part of any ESB. In this section, we will configure message mediation for requests to the SimpleStockQuoteService that come through the ESB. We will use WSO2 Developer Studio to create the message mediation artifacts and then deploy them to WSO2 ESB.

Creating the deployable artifacts project

The best practice in WSO2 Developer Studio is to create all deployable artifacts within a Maven Multi Module project. This approach allows you to build the deployable artifacts using Maven. More details are available at Using Maven with Developer Studio.

1. In Eclipse, open the Developer Studio dashboard by clicking the Developer Studio menu and choosing Open Dashboard. For more information on ways you can access the Developer Studio features, see Accessing Developer Studio.
   

2. Click Maven Multi Module Project in the right-hand column of the dashboard. (You might have to maximize the Developer Studio dashboard to see all its options.)

3. Fill in the details as follows:

   • Group Id: SampleAppId
   • Artifact Id: SampleApp
   • Version 1.0.0
   • Location: Use Default Location
   
4. Click Finish.

Developer Studio creates a Maven Multi Module project named SampleApp and displays it in the Project Explorer on the left. (Restore the Developer Studio dashboard window to its original size to see the Project Explorer.) Inside this project, we will create the mediation artifacts we want to build and deploy to the ESB using Maven.

Creating the mediation artifacts for WSO2 ESB

You create several mediation artifacts that configure WSO2 ESB to process requests, such as the proxy service (the configuration inside the ESB that receives and processes the requests), endpoints (the destination of the message, in this case the address of the back-end service where the ESB will send requests), and sequences (a list of mediators that take action on the request, such as transforming its format and then sending it to a back-end service). You create these artifacts in WSO2 Developer Studio within an ESB Config project. The following steps describe how to create the ESB Config project and the artifacts that are required for this scenario inside the Maven Multi Module Project you just created.

1. Right-click the SampleApp project in the project explorer and navigate to New -> ESB Config Project.

2. Ensure New ESB Config Project is selected and click Next.

3. Fill in the following details to create an ESB Config Project called SampleServices:

   • Project Name: SampleServices
   • Location: Use Default Location
   
4. Click Finish.

You have now created an ESB Config project called SampleServices within the SampleApp Maven Multi Module project, as shown in the Project Explorer when you expand SampleApp:

Next, inside the SampleServices ESB Config project, we will create an endpoint that will allow the ESB to connect to the back-end service SimpleStockQuoteService.

Connecting to SimpleStockQuoteService

To connect to SimpleStockQuoteService, which is hosted in the Axis2 server, we must expose a URL that can be used to connect to the service. To do this, we create an endpoint for SimpleStockQuoteService.

An endpoint defines an external destination for the outgoing message from the ESB. Typically an endpoint is based on a service address or a WSDL. WSO2 ESB also supports failover and load-balance endpoints that are defined over a group of endpoints. In this example, we want to create an endpoint that connects to SimpleStockQuoteService, which is available at http://localhost:9000/services/SimpleStockQuoteService.

1. Right-click SampleServices in the Project Explorer and navigate to New -> Endpoint.

2. Ensure Create a New Endpoint is selected and click Next.

3. Fill in the following details:

   • Endpoint Name: SimpleStockQuoteEP
   • Endpoint Type: Address Endpoint (indicating that we are specifying a service address)
   • Address: http://localhost:9000/services/SimpleStockQuoteService
   • Static Endpoint: Select this option because we are going to use this endpoint in this ESB project only and will not re-use it in other projects. If you need to create a reusable endpoint, you create it as a Dynamic Endpoint and save the endpoint in either the Configuration or Governance Registry. For more information, see the documentation on registries.
   • Save endpoint in: SampleServices (the ESB Config project we created in the last section)
     
4. Click Finish. The SimpleStockQuoteEP endpoint you created is saved in the endpoints folder within the ESB Config Project you created.

Now that you have created the endpoint for the back-end service, it’s time to create the proxy service that will receive requests from client applications, mediate them and send them to the endpoint, and return the results to the client.

Mediating requests to SimpleStockQuoteService

A proxy service is used by the WSO2 ESB mediation engine to mediate incoming requests, forward them to a specified endpoint, mediate the responses from the endpoint, and send the responses back to the client that originally requested them. Below is an illustration of the how a proxy service handles requests. The “In” sequence handles incoming requests and sends them to the back-end service, and the “Out” sequence handles the responses from the back-end service and sends them back to the requesting client.

We will use WSO2 Developer Studio to create a proxy service called SimpleStockQuoteProxy that forwards requests to the SimpleStockQuoteService back-end service.

Creating the proxy service

1. In the Project Explorer, right-click SampleServices and navigate to New -> Proxy Service.

2. Ensure Create A New Proxy Service is selected and click Next.

3. Fill in the following details:

   • Proxy Service Name: SimpleStockQuoteProxy

     The proxy service name you provide here will become part of the name of the generated proxy service URL, which is the URL used by the client when sending requests to SimpleStockQuoteService. For example, setting the name to SimpleStockQuoteProxy will generate the following URL for the proxy service: http://<host>:<port>/services/SimpleStockQuoteProxy

   • Proxy Service Type: Pass Through Proxy (provides a template for passing a message through to the back-end service)
   • Save proxy service in: SampleServices (the ESB Config project we created previously)
   • Advanced Configuration: Click Predefined Endpoint, and then select SimpleStockQuoteEP (the endpoint we created previously) from the list
     

4. Click Finish. Once the proxy service is created, the design view of the SimpleStockQuoteProxy.xml file appears so that you can start configuring the proxy service.
   

The top part of the canvas is the In sequence, which controls how incoming messages are mediated. Notice that a Send mediator is already in place to handle sending requests to the endpoint we selected (SimpleStockQuoteEP) when we created the proxy service.

The middle part of the canvas is the Out sequence, which controls how responses are handled. In this case, a Send mediator is already in place to send responses back to the requesting client.

The bottom part of the canvas is the Fault sequence, which allows you to configure how to handle messages when an error occurs (for more information, see Error Handling).

Configuring the WSDL

To be able to test the proxy service, we must publish the request format of the proxy service. In this scenario, we are simply passing the message through to a back-end service, so we can use the WSDL of the back-end service (SimpleStockQuoteService) as the publishing WSDL of the proxy service.

1. In the Design view, click the SimpleStockQuoteProxy icon on the left side of the canvas. The properties for the proxy service appear on the Properties tab at the bottom of the window. (If they do not appear, you can right-click the proxy icon and click Show Properties View.)

2. On the Properties tab, scroll down to the WSDL property and provide the WSDL configuration as follows:
   • WSDL Type: Click in the Value field, click the down arrow, and then select SOURCE_URL from the list
   • URL: http://localhost:9000/services/SimpleStockQuoteService?wsdl

We are now ready to add mediators to the In sequence to handle requests from the client.

Configuring the In sequence

You can use the Log mediator to log a message when the request is received by the In sequence of the proxy service. In this scenario, we will configure the Log mediator to extract the company stock symbol from the incoming requests and use this value to display the message “Welcome <company stock symbol>”.

1. From the Mediators palette, click and drag a Log mediator to the In sequence (the top of the canvas) just before the first Send mediator.
   
2. With the Log mediator selected, access the Properties tab and fill in the following details:
   
   • Log Category: INFO
     This log contains an informational message, so we select ‘INFO’
   • Log Level: Custom
     Only specified properties will be logged by this mediator, so we select ‘CUSTOM’.
   • Log Separator: (blank)
     Because there is only one property that is being logged, we do not require a separator, so this field can be left blank.
   • Properties: We will add the property in the next step, so skip this for now.
   • Description: Request Log
     The Description field provides the name that appears for the Log mediator icon in the design view.
3. We will now add the property that will extract the stock symbol from the request and print a welcome message in the log. Click the Value field of the Properties property, and then click the browse (...) icon that appears.
4. In the Log Mediator Configuration dialog, click New, and then add a property called "message" as follows:
   
   • Name: message
   • Type: EXPRESSION
     We select EXPRESSION because the required properties for the log message must be extracted from the request, which we can do using an XPath expression.
   • Value/Expression: Click the browse (...) icon in the Value/Expression field and enter the following:
     • Property expression: fn:concat('Welcome ', //m0:getQuote/m0:request/m1:symbol)
       This is an XPath expression that is used to extract the symbol from the request message and will then concatenate the two strings to display the log message “Welcome <company stock symbol>”.
     • Namespaces: Add the following two namespaces that are used in the above expression by entering the following prefix/URI pairs and clicking Add after each pair:
       • Prefix: m0 URI: http://services.samples
       • Prefix: m1 URI: http://services.samples/xsd
         
         
5. Click OK. The log mediator configuration should now look like this:
   

6. Click OK again to save the Log mediator configuration.

The In Sequence is now complete. Next, we need to ensure that we send the response from the SimpleStockQuoteService endpoint back to the client.

Configuring the Out sequence

To send the response back to the client, we use a Send mediator with no output endpoint defined, which defaults to sending the response back to the requesting client. Because the Send mediator was already added for us in the Out sequence when we created the proxy service, we do not have to do any further configuration right now. In a later lesson, we will add a mediator that changes the response before sending it back to the client.

This completes the steps for creating the artifacts required for proxying a request through WSO2 ESB to the SimpleStockQuoteService back-end service. We will now package these artifacts and deploy them to WSO2 ESB.

Deploying the artifacts to WSO2 ESB

To deploy the artifacts to WSO2 ESB, we must first package the SampleServices ESB Config project into a Composite Application project. A Composite Application (C-App) is a collection of artifacts that allows you to easily port your Web services solution from one environment to another. After using Developer Studio to develop your artifacts and C-Apps, you can then deploy the C-Apps as Carbon Application Archive (CAR) files to WSO2 ESB or any Carbon server that has C-App deployment capabilities.

To create the Composite Application project

1. In the Project Explorer, right-click SampleApp (the top-level Maven Multi Module Project, not the SampleService ESB Config project below it) and click New -> Project.

2. Select Composite Application Project and click Next.
   

3. Fill in the details as follows:

   • Project Name: SampleCApp
   • Dependencies: Click the check box next to SampleServices to include the ESB Config project and its dependencies
   • Location: Use default location
   • Working Sets: Leave blank
     
4. Click Finish.

The SampleCApp Composite Application project is generated and appears under SampleApp in the Project Explorer. Next, we will add the WSO2 ESB instance as a server in Developer Studio so that we can access it from within Developer Studio.

To add WSO2 ESB as a server in Developer Studio

1. Make sure the Axis2 server is still running so that the back-end service and its WSDL are available, and then go to Developer Studio Dashboard and click Server under Add Server.
   
2. In the Define a New Server dialog box, expand the WSO2 folder, and select the version of Carbon on which your version of WSO2 ESB is based. In this scenario, we are using WSO2 ESB 4.9.0, which is based on Carbon 4.4.0, so select WSO2 Carbon 4.4 based server.
   
3. Click Next, provide the path to your ESB home (the directory where you installed WSO2 ESB) in the CARBON_HOME field, and then click Next again.
   
4. Review the default port details for WSO2 ESB. Typically, you can leave these unchanged, but if you are already running another server on these ports, specify unused ports here. (See Default Ports of WSO2 Products for more information.) Click Next.
   
5. To deploy the SampleCApp Composite Application project to the WSO2 ESB server we just added, select SampleCApp from the list, click Add to move it into the Configured list, and then click Finish.
   
   The WSO2 ESB server is now added to Developer Studio.
6. On the Servers tab, you can see that the server is currently stopped. Click the "start the server" icon on the Servers tab's toolbar. If prompted to save changes to any of the artifact files you created earlier, click Yes.
   
   As the server starts, the Console tab will appear. You should see messages indicating that SimpleStockQuoteProxy and SampleCApp_1.0.0 were successfully deployed.
7. In your Web browser, navigate to the WSO2 ESB management console using the following URL: https://localhost:9443/carbon/. (If you changed the ports in Step 4 above, replace "9443" with the correct HTTPS port.)
8. Log into the management console using the following credentials:
   • Username: admin
   • Password: admin
9. In the left navigation pane, click List under Services. Here you can see that the proxy service we created earlier, SimpleStockQuoteProxy, is available in the ESB and is ready to receive requests and send them to the back-end service. Here you can also view the WSDL for any existing service, which you will need when creating the SoapUI project in the next section to send the request to the service.

Sending requests to SimpleStockQuoteProxy

Let's send a request to our proxy service, SimpleStockQuoteProxy, which is now deployed in WSO2 ESB. We will create a new SOAP project in SoapUI to send the requests.

1. Launch SoapUI and then click File -> New SOAP Project.
   

2. Enter the following details to create the project:

   • Project Name: SimpleStockQuoteProxy

   • Initial WADL/WSDL: http://localhost:8280/services/SimpleStockQuoteProxy?wsdl
Note: This is the URL of the proxy service WSDL, which includes the ESB's host (localhost) and HTTP port (8280), followed by services, and then the proxy service name followed by ?wsdl

   • Create Requests: Select the check box for this option. Leave the remaining options blank.
     
3. Click OK. The project is created, and details for the project appear in the SoapUI project explorer on the left.
4. In the SimpleStockQuoteProxy project, expand SimpleStockQuoteProxySoap11Binding, expand getQuote, and then double-click Request 1.
   
5. In the Request pane on the left, change the "?" in "<xsd:symbol>?</xsd:symbol>" to "WSO2" so that the line now looks like this:
   <xsd:symbol>WSO2</xsd:symbol>
6. Click the "Submit request to specified endpoint URL" icon (the green arrow) in the upper left corner of the Request 1 window.
   
   The request is sent, and the response is received and appears similar to below.
   

7. Now, check the Console in Eclipse, and you will see the following message:
INFO - LogMediator message = Welcome WSO2
   This is the message printed by the Log mediator when the message from the client is received in the In sequence of the proxy service.

You have now created and deployed a proxy service in WSO2 ESB that receives requests, logs a message using the Log mediator, sends the request to a back-end service using the Send mediator, and returns a response to the requesting client. Next, we will look at a more complex scenario that uses more advanced mediators.

You are now ready for Routing Requests Based on Message Content.