Commodity Quote Sample Guide

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:

Services offered by CommodityQuote to Client
- List stock symbols
- Get stock quote (name, symbol, price, high, low) and portfolio
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:
- Run WSO2 WSAS. See Installation Guide
for
installation details.
- Switch to the CommodityQuote directory, e.g.
cd WSO2WSAS_HOME\samples\CommodityQuote
- From there simply type
ant
You should see messages like this:
Buildfile: build.xml
clean:
init:
[mkdir] Created dir: C:\wso2wsas-2.2.1\samples\CommodityQuote\temp
[mkdir] Created dir:
C:\wso2wsas-2.2.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-2.2.1\repository\services
BUILD SUCCESSFUL
Total time: 11 seconds
The build automatically copies the .aar file containing the service into
the repository.- 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
(See Administrator?s
Guide
on how to sign into the Management Console and to navigate
through it.)- 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.
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:
- -e : is the Endpoint Reference (EPR) of the CommodityQuote service.
This can be obtained from the Management Console: The relevant service
EPR can be found at Services > CommondityQuote (under services column)
> End Points. For this sample the default URL is
?http://127.0.0.1:9762/services/CommodityQuote? in the case of
the standalone distribution, and
?http://127.0.0.1:9762/wso2wsas/services/CommodityQuote? in the
case of the embeddable version. In addition to this the ssl connection
(https://127.0.0.1:9443/services/CommodityQuote or
https://127.0.0.1:9443/wso2wsas/services/CommodityQuote)will be needed for
security scenarios, which will be discussed later in this document. The
default EPRs for http and https will be available in
WSO2WSAS_HOME/samples/CommodityQuote/conf/default_epr.properties file.
In addition to that mail transport can also be used. In mail transport
there should be two mail addresses to identify the client and server.
Those are the EPRs needed to communicate. A mail server should be used in
this case and two accounts should be created (A mail server like JAMES
can be used for this purpose). One should correspond to WSO2 WSAS and the
other one should correspond to the client. In addition to that Client's
axis2.xml and server's axis2.xml should be configured to do SMTP and pop
according to the mail server used. Here the EPR should be given as
"mail:<mail id corresponds to the
server>@localhost/services/CommodityQuote". More details will be discussed
later in this document.
- -qos : This will represent rm, secure or securerm options, which will
eventually engage respective modules to the CommodityQuote service. These
modules can be easily engaged from WSO2 WSAS console. More details will
be discussed below. To run the sample with these QoS, you must engage the
respective modules for the CommodityQuote service on the WSO2 WSAS server.
- rm - Sandesha2: Sandesha2 configuration will be available from RM
domain policies. We would only demonstrate the sample with the
default policy available from Sandesha2.
- secure - Rampart/Rahas: WSO2 WSAS distribution compliant with fifteen
security scenarios.
- Username Token authentication over HTTPS
- Sign only - X509 Authentication
- Sign and encrypt - X509 Authentication
- Sign only - Anonymous clients
- Encrypt only - Anonymous clients
- Sign and Encrypt - Anonymous clients
- Encrypt only - Username Token Authentication
- Sign and Encrypt - Username Token Authentication
- SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
- SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
- SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
- SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
- SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
- SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
- SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
Note: Some of the scenarios listed above need
provision for unlimited security jurisdiction. This will basically be
couple of Jar files, which will be available at Java
Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy
Files.
Download jce_policy-x_y_z.zip (relevant to your JDK
version) and extract the jar files local_policy.jar and
US_export_policy.jar to $JAVA_HOME/jre/lib/security.
- securerm - Both Sandesha2 and Rampart. securerm option will
demonstrate all the security scenarios with reliable messaging.
Let?s illustrate the above options with following samples:
Sample 1: Without any module engaged.
From CommodityQuote directory type:
$ ./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/services/CommodityQuote
Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:
Sample 2: With -qos secure : Rampart/Rahas
From CommodityQuote directory type:
$ ./run-client.sh -qos secure
STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================
Enter security scenario [1 - 15]...
{select a value between 1 to 15}
- Username Token authentication
- 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/
- Server side: Go to Keystores and upload the
service.jks. Keystore password will be "testing" and private key
store password will be "testing". Then go to Services >
CommodityQuote > Security Configuration and select "Sign only",
after which select "Continue". Select Trusted Certificate Stores as
service.jks and select private keystore as service.jks in the next
page.
- Client side:
STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================
Enter security scenario number [1 - 15]...
2
Client will be tuned to work on security scenario : 2
In this demonstration, client will use client.jks and server should use
service.jks.
Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference : http://127.0.0.1:9762/services/CommodityQuote
Quality of Service : secure
Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:1
...Getting Quote...
Please enter the symbol:xe
Results
-------
Name :xe
Symbol :Xenon
High value :0.0
Low value :0.0
Price :24.0
Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:
- Sign and encrypt - X509 Authentication
Configuration same as in scenario 2, except using this security
scenario.
- Sign only - Anonymous clients
Configuration as in scenario 2, except using this security
scenario. But in the client side, client's keys are not used and only
the service's public key is used
- Encrypt only - Anonymous clients
Configuration as in scenario 2, except using this security
scenario. But in the client side, client's keys are not used and only
the service's public key is used
- Sign and Encrypt - Anonymous clients
Configuration as in scenario 2, except using this security
scenario. But in the client side, client's keys are not used and only
the service's public key is used
- Requests as well as responses are encrypted 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/
- Server side: Logging to management console. Go to
Security > Users > User Management. The add a user "client"
with password "testing". Go to Keystores and upload the
service.jks. Keystore password will be "testing" and private key
store password will be "testing". Then go to Services >
CommodityQuote > Security Configuration and select "Encrypt only -
Username Token Authentication",after which select "Continue". Select
Trusted Certificate Stores as service.jks and select private keystore
as service.jks and also select user client and apply it.
- Client side:
STARTING COMMODITY QUOTE SAMPLE CLIENT
=============================
Enter security scenario number [1 - 15]...
7
Selected security scenario : 7
In this demonstration, client will use client.jks and server should use
service.jks.
Please enter your username :
client
Please enter your password :
testing
Sample will be invoked using following parameters ..
CommodityQuoteService Endpoint reference : http://127.0.0.1:9762/services/CommodityQuote
Quality of Service : secure
Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:1
...Getting Quote...
Please enter the symbol:xe
Results
-------
Name :xe
Symbol :Xenon
High value :0.0
Low value :0.0
Price :24.0
Please select your operation...
---------------------------------
(1) getQuote
(2) getSymbols
(3) Exit
:
- Sign and Encrypt - Username Token Authentication
Configuration as in scenario 7, except using this security
scenario
- SecureConversation - Sign only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
Configuration as in scenario 2, except using this security
scenario
- SecureConversation - Encrypt only - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
Configuration same as in scenario 2, except using this security
scenario.
- SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , X509 Authentication
Configuration same as in scenario 2, except using this security
scenario.
- SecureConversation - Sign Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
Configuration same as in scenario 2, except using this security
scenario.
- SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Anonymous clients
Configuration same as in scenario 2, except using this security
scenario.
- SecureConversation - Encrypt Only - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
Configuration same as in scenario 7, except using this security
scenario.
- SecureConversation - Sign and Encrypt - Service as STS - Bootstrap policy - Sign and Encrypt , Username Token Authentication
Configuration same as in scenario 7, except using this security
scenario.
sample 3: -qos rm : When Sandesha2 module has been engaged.
From CommodityQuote directory type:
$ ./run-client.sh -qos rm -e http://127.0.0.1:9762/services/CommodityQuote
or
$ ./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/services/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:
$ ./run-client.sh -qos securerm
sample 5: Invoking Commodity quote sample using mail transport
with/without RM/Sec
- Unzip the wso2wsas-2.2.1.zip. I
assumed the unzipped location as WSO2WSAS_HOME.
- Go to WSO2WSAS_HOME/samples/CommodityQuote folder. Run "ant" this will
copy the generated CommodityQuote.aar to
WSO2WSAS_HOME/repository/services.
- 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.
- 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}
- Start the server WSO2WSAS_HOME/bin/run.sh
- Go to client repository and do the following ./run-client.sh -e
mail:red@localhost/services/CommodityQuote.
- To run the sample with RM enabled, first engaged Sandesha2-<version> 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-<version>
mar. Go to client repo and use the following command, ./run-client.sh -e
mail:red@localhost/services/CommodityQuote -qos rm
- 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
- Set the 'Sandesha2StorageManager' property of the axis2.xml of the
server side to 'persistent'.
- Start the WSO2 Web Services Application Server.
- Engage the Sandesha2 module to Commodity Quote service.
- Run the client with QOS 'rm' and issue a command (e.g. getSymbols).
- Before this command gets completed (before response is received)
shutdown the server.
- Then start the server again.
- The client should now show the response.
APPENDIX