Commodity Quote Sample Guide for WSO2 Web Services Application Server (WSO2 WSAS) for Java, v1.1

Figure:1

INTRODUCTION

We will use this sample to demonstrate the capabilities of WSO2 Web Services Application Server, highlighting the ease of integration of quality of service modules. In the context of this scenario, the use of security and reliable messaging is emphasized on.

The Commodity Quote sample demonstrates the interactions between a simple Web service client & and a CommodityQuote service. This service provides information of chemical agents in d-block of the periodic table.

The following section describes the service in detail.

SCENARIO

In this sample, the client queries the CommodityQuote service for the available chemical elements (symbols). Using one of these symbols, the client gets stock quotes from the CommodityQuote service.

In summary the services are as follows:

Figure:2

Services offered by CommodityQuote to Client

Note: attributes of Stock Quote -name, symbol, selling price, high price, low price

HOW TO BUILD AND RUN THE SAMPLE

Commodity quote sample is in WSO2WSAS_HOME/samples/CommodityQuote. This sample emulates a simple "stock trader", where you can get the stock symbols and the stock quote for a particular stock symbol. In this case the stocks are elements in the periodic table, and stock symbols are the corresponding chemical element symbol.

To build the samples you need the Apache Ant build tool.

Now follow the simple instructions:

  1. Run WSO2 WSAS. See Installation Guide for installation details.
  2. Switch to the CommodityQuote directory, e.g.
  3.   cd WSO2WSAS_HOME\samples\CommodityQuote
  4. From there simply type
  5.   ant

    You should see messages like this:

    Buildfile: build.xml
    clean:
    init:
    
    [mkdir] Created dir: C:\wso2wsas-1.1\samples\CommodityQuote\temp
    [mkdir] Created dir:
    C:\wso2wsas-1.1\samples\CommodityQuote\temp\classes
    
    [some lines deleted here]
    
    build-all:
    [echo] Copying the created aar files in to the repository
    [copy] Copying 1 file to C:\wso2wsas-1.1\repository\services
    
    BUILD SUCCESSFUL
    Total time: 11 seconds

    The build automatically copies the .aar file containing the service into the repository.

  6. If you select the Services page in the Management Console, you should see the CommodityQuote service deployed. If you don't see it, the page will be refreshed once the deployment engine of Axis2 picks up the newly added .aar
  7. (See Administrator’s Guide on how to sign into the Management Console and to navigate through it.)

  8. If you are still in the CommodityQuote directory, you will find the run-client.bat and run-client.sh files. To see the CommodityQuote in action you can use the following syntax on the command prompt.
  9. On MS Windows:

    run-client.bat [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL]

    On Unix/Linux:

    run-client.sh [ -qos (rm|secure|securerm)] [ -e CommodityQuoteServiceURL]

    Terms used:

Let’s illustrate the above options with following samples:

Sample 1: Without any module engaged.

From CommodityQuote directory type:

   $ sh run-client.sh

You should see:

STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference   : http://127.0.0.1:9762/soap/CommodityQuote


Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:

Sample 2: With -qos secure : Rampart/Rahas

From CommodityQuote directory type:

   $ sh run-client.sh -qos secure

STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Enter security scenario [1 - 10]...
{select a value between 1 to 10}
  1. Username Token authentication
  2. Requests as well as responses are signed for this scenario to work. Commodity quote service needs to import a certificate. Let this certificate be service.jks. In addition to this, client needs to import the private key of the service.jks. Let's say this is client.jks. For this demonstration, service.jks and client.jks will be shipped with the sample and it's located at WSO2WSAS_HOME/samples/CommodityQuote/keys/
  3. Sign and encrypt using Basic256 algorithm suite
    Configuration same as in 2., except using this security scenario.
  4. Encrypt and sign using Basic256 algorithm suite
    Configuration as in 2., except using this security scenario.
  5. Sign and encrypt using Basic256 algorithm suite and derived keys
    Configuration as in 2., except using this security scenario.
  6. Sign and encrypt using TripleDesRsa15 algorithm suite
    Configuration as in 2., except using this security scenario.
  7. Sign and encrypt using TripleDesRsa15 algorithm suite and derived keys
    Configuration as in 2., except using this security scenario.
  8. Sign and encrypt using TripleDesRsa15 algorithm suite, derived keys and encrypt primary signature
    Configuration as in 2., except using this security scenario
  9. SecureConversation - Sign and encrypt - Service as STS - Bootstrap policy - UsernameToken with Timestamp over HTTPS
    Select "client" as the user.
  10. SecureConversation - Sign and encrypt with signature encrypted - Service as STS - Bootstrap policy - Derived Key encr/sig based on an phemeral key
    Select "client" as the user.

sample 3: -qos rm : When Sandesha2 module has been engaged.

From CommodityQuote directory type:

   $ sh run-client.sh -qos rm -e http://127.0.0.1:9762/soap/CommodityQuote
        or
        $ sh run-client.sh -qos rm
   
STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================

Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference   : http://127.0.0.1:9762/soap/CommodityQuote
Quality of Service                : rm


Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:
   

sample 4: -qos securerm : When Rampart/Rahas and Sandesha have been engaged.

Scenarios 1 & 9 with Secure-RM are not supported since HTTPS is required on the client side receiver. This is a limitation of the client.

From CommodityQuote directory type:

   $ sh run-client.sh -qos securerm

sample 5: Invoking Commodity quote sample using mail transport with/without RM/Sec

  1. Unzip the wso2wsas-standalone-edition-java-1.1.zip. I assumed the unzipped location as WSO2WSAS_HOME.
  2. Go to WSO2WSAS_HOME/samples/CommodityQuote folder. Run "ant" this will copy the generated CommodityQuote.aar to WSO2WSAS_HOME/repository/services.
  3. In mail transport there should be two mail addresses to identify the client and server. Thus, these are the EPR's need to communicate. For this example I've create two email addressed "red" and "blue", where "red" corresponds to WSO2WSAS server and "blue" corresponds to the client. I've used JAMES Mail server to create the two accounts.
  4. Client's axis2.xml and server's axis2.xml has been configured to do SMTP and POP from JAMES. {See, axis2.xml in WSO2WSAS_HOME/conf/ to server config and WSO2WSAS_HOME/samples/CommodidtyQuote/conf for client config}
  5. Start the server WSO2WSAS_HOME/bin/run.sh
  6. Go to client repository and do the following sh run-client.sh -e mail:red@localhost/soap/CommodityQuote.
  7. To run the sample with RM enabled, first engaged Sandesha2-1.1 to CommodityQuote service. Go to admin page using https://host:9443/, Username and password will be "admin". Go to Services/CommodityQuote/Manage Module Engagement and engage Sandesha2-1.1 mar. Go to client repo and use the following command, sh run-client.sh -e mail:red@localhost/soap/CommodityQuote -qos rm
  8. POP interval for the client and server has been given as 3000 ms. If user wants to change this value, in the respective axis2.xml, find following, <transportReceiver name="mail" class="org.apache.axis2.transport.mail.SimpleMailListener"> ... <parameter name="transport.listener.interval" locked="false">3000</parameter> ... </transportReceiver> and change the interval as you pleased.

As you will be able to see, with the rm option, the time to receive the response for the very first request will be comparatively larger. This is due to the control messages that are sent initially, in order to establish the reliable messaging channel.

Try playing around with the above options and see how it works for yourself!

Running the Sample with persistent RM

APPENDIX