The WSO2 ESB ships with a set of working examples that demonstrate some of the basic features and capabilities of itself. A set of sample clients and services are provided in addition to the sample configurations. Scripts are provided to execute the sample scenarios as explained below.
This document provides step-by-step instructions on how to install the pre-requisites, and set up the samples - generic instructions on how to start the sample server, deploy a service, and run the client.
You will need a Java development kit / JRE version 1.5.x or later and Apache Ant 1.7.0 or later, at a minimum, to try out the samples. Ant can be downloaded from http://ant.apache.org. The JMS examples can be executed against an ActiveMQ installation by default (or another JMS provider with configuration) and any HTTPS examples would require a JDK version 1.5 or later.
Once you setup ant go to the bin directory of the distribution and run the build.xml file which resides in that directory using ant. You could do this by typing 'ant' on a console in this directory.
Note*: The samples and the documentation assumes that you are running the ESB in DEBUG mode. You can switch from the default INFO log messages to DEBUG log messages by changing the line "log4j.category.org.apache.synapse=INFO" as "log4j.category.org.apache.synapse=DEBUG" in the webapps/ROOT/WEB-INF/classes/log4j.properties file.
|ant stockquote||./wso2esb-samples.sh -sn <n>||SimpleStockQuoteService|
The above table depicts the interactions between the clients, the ESB and services at a high level. The Clients are able to send SOAP/REST or POX messages over transports such as HTTP/HTTPS or JMS with WS-Addressing, WS-Security, or WS-Reliable messaging. They could send binary optimized content using MTOM or SwA or binary or plain text JMS messages. After mediation through the ESB, the requests are passed over to the sample services. The sample clients and services are explained below.
The sample clients can be executed from the samples/axis2Client directory through the provided Ant script. Simply executing 'ant' displays the available clients and some of the sample options used to configure them. The sample clients available are listed below:
This is a simple SOAP client that could send stock quote requests, and receive and display the last sale price for a stock symbol.
ant stockquote [-Dsymbol=IBM|MSFT|SUN|..] [-Dmode=quote | customquote | fullquote | placeorder | marketactivity] [-Daddurl=http://localhost:9000/services/SimpleStockQuoteService] [-Dtrpurl=http://localhost:8280/] [-Dprxurl=http://localhost:8280/] [-Dpolicy=../../repository/samples/resources/policy/policy_1.xml]
The client is able to operate in the following modes, and send the payloads listed below as SOAP messages:
<m:getQuote xmlns:m="http://services.samples/xsd"> <m:request> <m:symbol>IBM</m:symbol> </m:request> </m:getQuote>
<m0:checkPriceRequest xmlns:m0="http://services.samples/xsd"> <m0:Code>symbol</m0:Code> </m0:checkPriceRequest>
<m:getFullQuote xmlns:m="http://services.samples/xsd"> <m:request> <m:symbol>IBM</m:symbol> </m:request> </m:getFullQuote>
<m:placeOrder xmlns:m="http://services.samples/xsd"> <m:order> <m:price>3.141593E0</m:price> <m:quantity>4</m:quantity> <m:symbol>IBM</m:symbol> </m:order> </m:placeOrder>
<m:getMarketActivity xmlns:m="http://services.samples/xsd"> <m:request> <m:symbol>IBM</m:symbol> ... <m:symbol>MSFT</m:symbol> </m:request> </m:getMarketActivity>
Note : See samples/axis2Client/src/samples/common/StockQuoteHandler.java for sample responses expected by the clients.
The 'addurl' property sets the WS-Addressing EPR, and the 'trpurl' sets a transport URL for a message. Thus by specifying both properties, the client can operate in the 'smart client' mode, where the addressing EPR could specify the ultimate receiver, while the transport URL set to the ESB ensures that any necessary mediation takes place before the message is delivered to the ultimate reciver.
e.g: ant stockquote -Daddurl=<addressingEPR> -Dtrpurl=<esb>
By specifying only a transport URL, the client operates in the 'dumb client' mode, where it sends the message to the ESB and depends on the ESB rules for proper mediation and routing of the message to the ultimate destination.
e.g: ant stockquote -Dtrpurl=<esb>
In this mode, the client uses the 'prxurl' as an HTTP proxy to send the request. Thus by setting the 'prxurl' to the ESB, the client could ensure that the message would reach the ESB for mediation. The client could optionally set a WS-Addressing EPR if required.
e.g: ant stockquote -Dprxurl=<esb> [-Daddurl=<addressingEPR>]
By specifying a WS-Policy using the 'policy' property, QoS aspects such as WS-Security could be enforced on the request. The policy specifies details such as timestamps, signatures, and encryption. See Apache Axis2 and Apache Rampart documentation for more information.
The JMS client is able to send plain text, plain binary content, or POX content by directly publishing a JMS message to the specified destination. The JMS destination name should be specified with the 'jms_dest' property. The 'jms_type' property could specify 'text', 'binary' or 'pox' to specify the type of message payload.
The plain text payload for a 'text' message can be specified through the 'payload' property. For binary messages, the 'payload' property would contain the path to the binary file. For POX messages, the 'payload' property will hold a stock symbol name to be used within the POX request for stock order placement request.
ant jmsclient -Djms_type=text -Djms_dest=dynamicQueues/JMSTextProxy -Djms_payload="24.34 100 IBM" ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/JMSPoxProxy -Djms_payload=MSFT ant jmsclient -Djms_type=binary -Djms_dest=dynamicQueues/JMSFileUploadProxy -Djms_payload=./../../repository/samples/resources/mtom/asf-logo.gif
Note: The JMS client assumes the existence of a default ActiveMQ (5.2.0) installation on the local machine.
The MTOM / SwA client can send a binary image file as a MTOM or SwA optimized message, and receive the same file again through the response and save it as a temporary file. The 'opt_mode' can specify 'mtom' or 'swa' respectively for the above mentioned optimizations. Optionally, the path to a custom file can be specified through the 'opt_file' property, and the destination address can be changed through the 'opt_url' property if required.
e.g. ant optimizeclient -Dopt_mode=[mtom | swa]
The sample services ship with a pre-configured Axis2 server, and demonstrates in-only and in-out SOAP/REST or POX messaging over HTTP/HTTPS and JMS transports using WS-Addressing, WS-Security, and WS-Reliable Messaging. It also handles binary content using MTOM and SwA.
The sample services can be found in the samples/axis2Server/src directory and can be built and deployed using Ant from each service directory.
user@host:/tmp/wso2esb-2.0/samples/axis2Server/src/SimpleStockQuoteService$ ant Buildfile: build.xml ... build-service: .... [jar] Building jar: /tmp/wso2esb-2.0/samples/axis2Server/repository/services/SimpleStockQuoteService.aar BUILD SUCCESSFUL Total time: 3 seconds
To start the Axis2 server, go to the samples/axis2Server directory and execute the axis2server.sh or axis2server.bat script. This starts the Axis2 server with the HTTP transport listener on port 9000 and HTTPS on 9002 respectively. To enable JMS transport, you will need to set up and start a JMS provider. An ActiveMQ 5.2.0 JMS server on the local machine is supported by default, and can be easily enabled by uncommenting the JMS transport from the conf/axis2.xml
The Sample services are as follows:
This service has four operations, getQuote (in-out), getFullQuote(in-out), getMarketActivity(in-out) and placeOrder (in-only). The getQuote operation will generate a sample stock quote for a given symbol. The getFullQuote operation will generate a history of stock quotes for the symbol for a number of days, and the getMarketActivity operation returns stock quotes for a list of given symbols. The placeOrder operation will accept a one way message for an order.
This service is a clone of the SimpleStockQuoteService, but has WS-Security enabled and an attached security policy for signing and encrypting messages.
This service has three operations: uploadFileUsingMTOM(in-out), uploadFileUsingSwA(in-out) and oneWayUploadUsingMTOM(in-only), and also demonstrates the use of MTOM and SwA. The uploadFileUsingMTOM and uploadFileUsingSwA operations accept a binary image from the SOAP request as MTOM and SwA, and returns this image back again as the response, while the oneWayUploadUsingMTOM saves the request message to the disk.
To start the WSO2 ESB with the sample default configuration, execute the wso2server.bat or wso2server.sh script found in the /bin directory. This starts up an instance of the ESB using the Synapse and Axis2 configuration files located in the conf directory. The repository/samples directory contains the sample configurations available as synapse_sample_<n>.xml files. To start a specific sample configuration of the ESB, use the '-Desb.sample=<n>' switch as follows:synapse_sample_<n>.xml files. To start a specific sample configuration of the ESB, use the '-Desb.sample=<n>' switch as follows:
wso2esb-samples.bat -sn <n> ./wso2esb-samples.sh -sn <n>
The samples used in this guide assumes the existence of a local ActiveMQ (4.1.0 or higher) installation, which is properly installed and started.
To enable the JMS transport, you need to uncomment the JMS transport listener configuration. If you are using a JMS provider other than ActiveMQ, this configuration should be updated to reflect your environment. Once uncommented, the default configuration should be as follows. To enable JMS for the ESB, the conf/axis2.xml must be updated. To enable JMS support for the sample Axis2 server, the samples/axis2Server/repository/conf/axis2.xml file must be updated.
<!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)--> <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener"> <parameter name="myTopicConnectionFactory" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter> </parameter> <parameter name="myQueueConnectionFactory" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> </parameter> <parameter name="default" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> </parameter> </transportReceiver>
To enable the mail transport for samples, you need to uncomment the mail transport sender configuration in the conf/axis2.xml. Uncomment the MailTransportSender sample configuration and make sure it points to a valid SMTP configuration for any actual scenarios.
<transportSender name="mailto" class="org.apache.synapse.transport.mail.MailTransportSender"> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> <parameter name="mail.smtp.user">synapse.demo.0</parameter> <parameter name="mail.smtp.password">mailpassword</parameter> <parameter name="mail.smtp.from">email@example.com</parameter> </transportSender>
To enable the FIX transport for samples, you need to uncomment the FIX transport sender and FIX transport receiver configurations in the conf/axis2.xml. Simply locate and uncomment the FIXTransportSender and FIXTransportListener sample configurations. Alternatively if the FIX transport management bundle is in use you can enable the FIX transport listener and the sender from the WSO2 ESB management console. Login to the console and navigate to 'Transports' on management menu. Scroll down to locate the sections related to the FIX transport. Simply click on 'Enable' links to enable the FIX listener and the sender.
In order to configure WSO2 ESB to run the FIX samples given in this guide you will need to create some FIX configuration files as specified below.
The FileStorePath property in the following two files should point to two directories in your local file system. Once the samples are executed, Synapse will create FIX message stores in these two directories.
Put the following entries in a file called fix-synapse.cfg
[default] FileStorePath=examples/target/data/synapse-acceptor ConnectionType=acceptor StartTime=00:00:00 EndTime=00:00:00 HeartBtInt=30 ValidOrderTypes=1,2,F SenderCompID=SYNAPSE TargetCompID=BANZAI UseDataDictionary=Y DefaultMarketPrice=12.30 [session] BeginString=FIX.4.0 SocketAcceptPort=9876
Put the following entries in a file called synapse-sender.cfg
[default] FileStorePath=examples/target/data/synapse-initiator SocketConnectHost=localhost StartTime=00:00:00 EndTime=00:00:00 HeartBtInt=30 ReconnectInterval=5 SenderCompID=SYNAPSE TargetCompID=EXEC ConnectionType=initiator [session] BeginString=FIX.4.0 SocketConnectPort=19876
If you are using a binary distribution of Quickfix/J, the two samples and their configuration files are all packed to a single jar file called quickfixj-examples.jar. You will have to extract the jar file, modify the configuration files and pack them to a jar file again under the same name.
Locate and edit the FIX configuration file of Executor to be as follows. This file is usually named executor.cfg
[default] FileStorePath=examples/target/data/executor ConnectionType=acceptor StartTime=00:00:00 EndTime=00:00:00 HeartBtInt=30 ValidOrderTypes=1,2,F SenderCompID=EXEC TargetCompID=SYNAPSE UseDataDictionary=Y DefaultMarketPrice=12.30 [session] BeginString=FIX.4.0 SocketAcceptPort=19876
Locate and edit the FIX configuration file of Banzai to be as follows. This file is usually named banzai.cfg
[default] FileStorePath=examples/target/data/banzai ConnectionType=initiator SenderCompID=BANZAI TargetCompID=SYNAPSE SocketConnectHost=localhost StartTime=00:00:00 EndTime=00:00:00 HeartBtInt=30 ReconnectInterval=5 [session] BeginString=FIX.4.0 SocketConnectPort=9876
The FileStorePath property in the above two files should point to two directories in your local file system.
For more information regarding the FIX sample applications please refer the Example Applications section in the Quickfix/J documentation. For more information on configuring Quickfix/J applications refer the Configuring Quickfix/J section of the Quickfix/J documentation.
The Script Mediator is a Synapse extension, and thus all pre-requisites for all BSF supported scripting languages may not be bundled by default with the ESB distribution. Before you use some script mediators, you may need to manually add the required .jar files to the lib directory('lib/extensions'), and optionally perform other installation tasks as may be required by the individual scripting language. This is detailed in the following sections.
For Ruby support you need to download the 'jruby-complete.jar' from the Maven repository for JRuby, and copy it into the 'lib/extensions' folder of Synapse . The JRuby JAR can be downloaded from here.
You can download Apache Derby distribution from http://db.apache.org/derby/
CREATE table company(name varchar(10), id varchar(10), price double);
INSERT into company values ('IBM','c1',0.0); INSERT into company values ('SUN','c2',0.0); INSERT into company values ('MSFT','c3',0.0);
When using Derby, you need to add derby.jar, derbyclient.jar and derbynet.jar to the classpath. This can be done by putting the above three jars into the ESB lib/extensions directory. For testing these samples Derby10.3.2.1 binary distribution was used.
You can use any other database product instead of Derby. Then you have to change the database connection details accordingly. Also you have to copy the required database driver jars to the ESB classpath.
Definition of the reusable database connection pool or datasources can be done using datasources.properties file. It is possible to configure any number of datasources. Currently this only supports two types of datasources and those are based on Apache DBCP datasources. Those types are BasicDataSource and PerUserPoolDataSource (based on Apache DBCP). Following configuration includes both two definition. This configuration is related with sample 363.
Configuration is somewhat similar to the log4j appender configuration.
It requires two databases, follow the above specified (Setting up Derby Database server) steps to create the two databases 'jdbc:derby://localhost:1527/lookupdb', 'jdbc:derby://localhost:1527/reportdb' using the user name and password as 'esb'. Fill in the data for those two databases as per described in the above section
############################################################################### # DataSources Configuration ############################################################################### synapse.datasources=lookupds,reportds synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory synapse.datasources.providerPort=2199 # If following property is present , then assumes that there is an external JNDI provider and will not start a RMI registry #synapse.datasources.providerUrl=rmi://localhost:2199 synapse.datasources.lookupds.registry=Memory synapse.datasources.lookupds.type=BasicDataSource synapse.datasources.lookupds.driverClassName=org.apache.derby.jdbc.ClientDriver synapse.datasources.lookupds.url=jdbc:derby://localhost:1527/lookupdb;create=false # Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider synapse.datasources.lookupds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler synapse.datasources.lookupds.username=esb # Depending on the password provider used, you may have to use an encrypted password here! synapse.datasources.lookupds.password=esb synapse.datasources.lookupds.dsName=lookupdb synapse.datasources.lookupds.maxActive=100 synapse.datasources.lookupds.maxIdle=20 synapse.datasources.lookupds.maxWait=10000 synapse.datasources.reportds.registry=JNDI synapse.datasources.reportds.type=PerUserPoolDataSource synapse.datasources.reportds.cpdsadapter.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS synapse.datasources.reportds.cpdsadapter.className=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS synapse.datasources.reportds.cpdsadapter.name=cpds synapse.datasources.reportds.dsName=reportdb synapse.datasources.reportds.driverClassName=org.apache.derby.jdbc.ClientDriver synapse.datasources.reportds.url=jdbc:derby://localhost:1527/reportdb;create=false # Optionally you can specifiy a specific password provider implementation which overrides any globally configured provider synapse.datasources.reportds.secretProvider=org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler synapse.datasources.reportds.username=esb # Depending on the password provider used, you may have to use an encrypted password here! synapse.datasources.reportds.password=esb synapse.datasources.reportds.maxActive=100 synapse.datasources.reportds.maxIdle=20 synapse.datasources.reportds.maxWait=10000
To secure data sources password, it is need to use the mechanism for securing secret Information. Please refer securing secret Information guide. If that mechanism is used, then passwords that have been specified are considered as aliases and those are used for picking actual passwords. To get password securely, it is needed to set the password provider for each data source. The password provider should be an implementation of org.apache.synapse.commons.security.secret.SecretCallbackHandler. There are few options and for more information please refer securing secret Information guide.
For run this sample, you just need to uncomment secret-conf.properties, cipher-text.properties and datasources.properties. Those files are in conf directory.