Running the WSO2 Enterprise Service Bus (ESB) Samples
While the Samples Setup Guide
document above gives you a generic description on how to set up and and run
the WSO2 ESB samples, this document takes each sample, one by one and
discusses the objective of the sample, its prerequisites, and its expected
behavior when the sample is built.
Note: The ESB configurations listed below, with each
sample, is the raw source XML serialization of the sample configuration. This
may be viewed graphically through the WSO2 ESB administration console after
logging into the console.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<!-- log all attributes of messages passing through -->
<log level="full"/>
<!-- Send the messageto implicit destination -->
<send/>
</definitions>
Objective: Introduction to ESB. Shows how a message could be made
to pass through ESB and logged before it is delivered to its
ultimate receiver.
The Stock quote client can operate in the following modes for this
example.
Smart Client mode
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
Using ESB as a HTTP Proxy
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dprxurl=http://localhost:8280/
Gateway Mode / Dumb Client
See sample # 1
Prerequisites: Start the Synapse configuration numbered 0: e.g. wso2-esb -sample
0
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
deployed
Execute the Smart Client
By tracing the execution of ESB with the log output level set to DEBUG,
you will see the client request arriving at ESB with a WS-Addressing 'To' set
to EPR http://localhost:9000/soap/SimpleStockQuoteService. The ESB engine
logs the message at the "full" log level (i.e. all the message headers and
the body) then sends the message to its implicit 'To' address which is
http://localhost:9000/soap/SimpleStockQuoteService. You will see a message in
the Axis2 server console confirming that the message got routed to the sample
server and the sample service hosted at the sample server generating a stock
quote for the requested symbol.
Sat Nov 18 21:01:23 IST 2006 SimpleStockQuoteService :: Generating quote for : IBM
The response message generated by the service is again received by ESB,
and flows through the same mediation rules, which logs the response message
and then sends it back. This time to the client. On the client console you
should see an output similar to the following based on the message received
by the client.
Standard :: Stock price = $95.26454380258552
Execute the Proxy Client
You will see the exact same behaviour as per the previous example when you
run this scenario. However this time the difference is at the client, as it
sends the message to the WS-Addressing 'To' address
http://localhost:9000/soap/SimpleStockQuoteService, but the transport
specifies ESB as the http proxy.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<!-- filtering of messages with XPath and regex matches -->
<filter source="get-property('To')" regex=".*/StockQuote.*">
<send>
<endpoint>
<address uri="http://localhost:9000/soap/SimpleStockQuoteService"/>
</endpoint>
</send>
<drop/>
</filter>
<send/>
</definitions>
Objective: Introduction to simple content based routing. Shows how
a message could be made to pass through ESB using the Dumb Client mode, where
ESB acts as a gateway to accept all messages and then perform mediation and
routing based on message properties or content.
Prerequisites:
Start the Synapse configuration numbered 1: i.e. wso2-esb -sample 1
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
deployed
Execute the Dumb Client as:
ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuote
This time you will see ESB receiving a message for which ESB was set as
the ultimate receiver of the message. Based on the 'To' EPR of
http://localhost:8280/soap/StockQuote, ESB performs a match to the path
'/StockQuote' and as the request matches the XPath expression of the filter
mediator, the filter mediator's child mediators execute. This sends the
message to a different endpoint as specified by the endpoint definition. The
'drop' mediator terminates further processing of the current message in a
configuration. During response processing, the filter condition fails, and
thus the implicit 'send' mediator forwards the response back to the client.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples/xsd">
<case regex="IBM">
<!-- the property mediator sets a local property on the *current* message -->
<property name="symbol" value="Great stock - IBM"/>
</case>
<case regex="MSFT">
<property name="symbol" value="Are you sure? - MSFT"/>
</case>
<default>
<!-- it is possible to assign the result of an XPath expression as well -->
<property name="symbol"
expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"
xmlns:m0="http://services.samples/xsd"/>
</default>
</switch>
<log level="custom">
<!-- the get-property() XPath extension function allows the lookup of local message properties
as well as properties from the Axis2 or Transport contexts (i.e. transport headers) -->
<property name="symbol" expression="get-property('symbol')"/>
<!-- the get-property() function supports the implicit message headers To/From/Action/FaultTo/ReplyTo -->
<property name="epr" expression="get-property('To')"/>
</log>
<!-- Send the messages where they are destined to (i.e. the 'To' EPR of the message) -->
<send/>
</definitions>
Objective: Introduce switch-case mediator and writing and reading
of local properties set on a message instance
Prerequisites:
Start the Synapse configuration numbered 2: i.e. wso2-esb -sample 2
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done.
Execute the 'ant stockquote ..' request again in the smart client mode,
specifying 'IBM', 'MSFT' and 'SUN' as the stock symbols. When the symbol IBM
is requested, viewing the mediation logs you will see that the case
statements' first case for 'IBM' is executed and a local property named
'symbol' was set to 'Great stock - IBM'. Subsequently this local property
value is looked up by the log mediator and logged using the 'get-property()'
XPath extension function.
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
-Dtrpurl=http://localhost:8280/ -Dsymbol=IBM
INFO LogMediator - symbol = Great stock - IBM, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
-Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
INFO LogMediator - symbol = Are you sure? - MSFT, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService
<definitions xmlns="http://ws.apache.org/ns/synapse">
<!-- define a string resource entry to the local registry -->
<localEntry key="version">0.1</localEntry>
<!-- define a reuseable endpoint definition -->
<endpoint name="simple">
<address uri="http://localhost:9000/soap/SimpleStockQuoteService"/>
</endpoint>
<!-- define a reusable sequence -->
<sequence name="stockquote">
<!-- log the message using the custom log level. illustrates custom properties for log -->
<log level="custom">
<property name="Text" value="Sending quote request"/>
<property name="version" expression="get-property('version')"/>
<property name="direction" expression="get-property('direction')"/>
</log>
<!-- send message to real endpoint referenced by key "simple" endpoint definition -->
<send>
<endpoint key="simple"/>
</send>
</sequence>
<sequence name="main">
<in>
<property name="direction" value="incoming"/>
<sequence key="stockquote"/>
</in>
<out>
<send/>
</out>
</sequence>
</definitions>
Objective: Illustrates local registry entry definitions, reusable
endpoints and sequences
Prerequisites:
Start the Synapse configuration numbered 3: i.e. wso2-esb -sample 3
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This example uses a sequence named as "main" that specifies the main
mediation rules to be executed. This is equivalent to directly specifying the
mediators of the main sequence within the <definitions> tags. This is
the recommended and also a better approach for non-trivial configurations.
Execute the 'ant stockquote ..' request again, and following through the
mediation logs you will now notice that the sequence named "main" is
executed. Then for the incoming message flow the <in> mediator
executes, and it calls the sequence named "stockquote".
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
As the "stockquote" sequence executes, the log mediator dumps a simple
text/string property, result of an XPath evaluation, that picks up the key
named "version", and a second result of an XPath evaluation that picks up a
local message property set previously by the <property> mediator. The
get-property() XPath extension function is able to read message properties
local to the current message, local or remote registry entries, Axis2 message
context properties as well as transport headers. The local entry definition
for "version" defines a simple text/string registry entry for that which is
visible to all messages that pass through ESB.
[HttpServerWorker-1] INFO LogMediator - Text = Sending quote request, version = 0.1, direction = incoming
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] DEBUG AddressEndpoint - Sending To: http://localhost:9000/soap/SimpleStockQuoteService
Objective: Introduction to error handling with the 'fault'
sequence
Prerequisites:
Start the Synapse configuration numbered 4: i.e. wso2-esb -sample 4
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
When the IBM stock quote is requested, the configuration routes it to the
defined inline endpoint, which routes the message to the
SimpleStockQuoteService on the local Axis2 instance. Hence a valid response
message is shown at the client.
If you lookup a stock quote for 'MSFT', ESB is instructed to route the
message to the endpoint defined as the 'bogus' endpoint, which does not
exist. ESB executes the specified error handler sequence closest to the point
where the error was encountered. In this case, the currently executing
sequence is 'main' and it does not specify an 'onError' attribute. Whenever
ESB cannot find an error handler, it looks for a sequence named 'fault'. Thus
the 'fault' sequence can be seen executing, and writing the generic error
message to the logs.
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : bogus
[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <fault> :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured, message = Reference to non-existent endpoint for key : bogus
When the 'SUN' quote is requested, a custom sequence 'sunSequence' is
invoked, and it specifies 'sunErrorHandler' as its error handler. Hence when
the send fails, you could see the proper error handler invocation and the
custom error message printed as follows.
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunSequence> :: mediate()
[HttpServerWorker-1] DEBUG SequenceMediator - Setting the onError handler for the sequence
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : sunPort
[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunErrorHandler> :: mediate()
[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured for stock SUN, message = Reference to non-existent endpoint for key : sunPort
Objective: Makefault mediator and sending back error responses
Prerequisites:
Start the Synapse configuration numbered 5: i.e. wso2-esb -sample 5
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
When the MSFT stock quote is requested, an unknown host exception would be
generated. A connection refused exception would be generated for the SUN
stock request. This error message is captured and returned to the original
client as a SOAP fault in this example.
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT
Objective: Introduction to header, in (out) mediators
Prerequisites:
Start the Synapse configuration numbered 6: i.e. wso2-esb -sample 6
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
In this example we use the stockquote client in the dumb client mode,
setting the 'To' EPR of the message to ESB. Then the 'in' mediator processes
the incoming messages, and manipulates the 'To' header to refer to the stock
quote service on the sample Axis2 server. Thus it is now possible to request
for a stock quote as follows.
Objective: Introduction to local (static) registry entries and the
validate mediator
Prerequisites:
Start the Synapse configuration numbered 7: i.e. wso2-esb -sample 7
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This example shows how a static XML fragment could be made available to
the ESB local registry. Resources defined in the local registry are static
(i.e. never changes over the lifetime of the configuration) and may be
specified as a source URL, inline text or inline xml. In this example the
schema is made available under the key 'validate_schema'.
The validate mediator by default operates on the first child element of
the SOAP body. You may specify an XPath expression using the 'source'
attribute to override this behaviour. The validate mediator now uses the
'validate_schema' resource to validate the incoming message, and if the
message validatation fails it invokes the 'on-fail' sequence of mediators.
If you send a stockquote request using 'ant stockquote ...' you will get a
fault back with the message 'Invalid custom quote request' as the schema
validation failed. This is because the schema used in the example expects a
slightly different message than what is created by the stock quote client.
(i.e. expects a 'stocksymbol' element instead of 'symbol' to specify the stock
symbol)
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
<definitions xmlns="http://ws.apache.org/ns/synapse">
<!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
<registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
<!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
<parameter name="root">file:./repository/conf/sample/resources/</parameter>
<!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
<parameter name="cachableDuration">15000</parameter>
</registry>
<!-- define the request processing XSLT resource as a static URL source -->
<localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/>
<in>
<!-- transform the custom quote request into a standard quote requst expected by the service -->
<xslt key="xslt-key-req"/>
</in>
<out>
<!-- transform the standard response back into the custom format the client expects -->
<!-- the key is looked up in the remote registry and loaded as a 'dynamic' registry resource -->
<xslt key="transform/transform_back.xslt"/>
</out>
<send/>
</definitions>
Objective: Introduction to static and dynamic registry resources
and the XSLT mediator
Prerequisites:
Start the Synapse configuration numbered 8: i.e. wso2-esb -sample 8
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This example uses the XSLT mediator to perform transformations, and the
xslt transformations are specified as registry resources. The first resource
'xslt-key-req' is specified as a 'local' registry entry. Local entries do not
place the resource on the registry, but simply make it available to the local
configuration. If a local entry is defined with a key that already exists in
the remote registry, the local entry will get higher preference and override
the remote resource.
In this example you will notice the new 'registry' definition. ESB comes
with a simple URL based registry implementation SimpleURLRegistry. During
initialization of the registry, the SimpleURLRegistry expects to find a
property named 'root', which specifies a prefix for the registry keys used
later. When the SimpleURLRegistry is used, this root is prefixed to the entry
keys to form the complete URL for the resource being looked up. The registry
caches a resource once requested, and caches it internally for a specified
duration. Once this period expires, it will reload the meta information about
the resource and reload its cached copy if necessary, the next time the
resource is requested.
Hence the second XSLT resource key 'transform/transform_back.xslt'
concatenated with the 'root' of the SimpleURLRegistry
'file:repository/conf/sample/resources/' forms the complete URL of the
resource as
'file:repository/conf/sample/resources/transform/transform_back.xslt' and
caches its value for a period of 15000 ms.
Execute the custom quote client as 'ant stockquote -Dmode=customquote ...'
and analyze the the ESB debug log output
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote
The incoming message is now transformed into a standard stock quote
request as expected by the SimpleStockQuoteService deployed on the local
Axis2 instance, by the XSLT mediator. The XSLT mediator uses Xalan-J to
perform the transformations. It is possible to configure the underlying
transformation engine using properties where necessary. The response from the
SimpleStockQuoteService is converted back into the custom format as expected
by the client during the out message processing.
During the response processing you could see the SimpleURLRegistry
fetching the resource as shown by the log message below
[HttpClientWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt
If you run the client again immediately (i.e within 15 seconds of the
first request) you will not see the resource being reloaded by the registry
as the cached value would be still valid.
However if you leave the system idle for 15 seconds or more and then retry
the same request, you will now notice that the registry noticed the cached
resource has expired and will check the meta information about the resource
to check if the resource itself has changed and will require a fresh fetch
from the source URL. If the meta data / version number indicates that a
reload of the cached resource is not necessary (i.e. unless the resource
itself actually changed) the updated meta information is used and the cache
lease extended as appropriate.
[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
[HttpClientWorker-1] DEBUG AbstractRegistry - Expired version number is same as current version in registry
[HttpClientWorker-1] DEBUG AbstractRegistry - Renew cache lease for another 15s
Now edit the
repository/conf/sample/resources/transform/transform_back.xslt file and add a
blank line at the end. Now when you run the client again, and if the cache is
expired, the resource would be re-fetched from its URL by the registry and
this can be seen by the following debug log messages
[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
[HttpClientWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt
Thus the SimpleURLRegistry allows resource to be cached, and updates
detected so that the changes could be reloaded without restarting the ESB
instance.
Objective: Introduction to dynamic sequences with a
Registry
Prerequisites:
Start the Synapse configuration numbered 9: i.e. wso2-esb -sample 9
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This example introduces the dynamic behaviour of ESB through the use of a
Registry. ESB supports dynamic definitions for sequences and endpoints, and
as seen before, for resources. In this example we define a Synapse
configuration which references a sequence definition specified as a registry
key. The registry key resolves to the actual content of the sequence which
would be loaded dynamically by ESB at runtime, and cached appropriately as
per its definition in the registry. Once the cache expires, ESB would recheck
the meta information for the definition and re-load the sequence definition
if necessary and re-cache it again.
Once ESB is started, execute the stock quote client as 'ant stockquote..'.
You will notice that that ESB fetches the definition of the sequence from the
registry and executes its rules as follows:
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
[HttpServerWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
...
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
...
[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 1 ***
Now if you execute the client immediately (i.e. within 15 seconds of the
last execution) you will notice that the sequence was not reloaded. If you
edit the sequence definition in
repository/conf/sample/resources/sequence/dynamic_seq_1.xml (i.e. edit the
log message to read as "*** Test Message 2 ***") and execute the client
again, you will notice that the new message is not yet visible (i.e. if you
execute this within 15 seconds of loading the resource for the first time)
However, after 15 seconds elapsed since the original caching of the sequence,
you will notice that the new sequence is loaded and executed by ESB from the
following log messages.
[HttpServerWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
...
[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
...
[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 2 ***
The cache timeout could be tuned appropriately by configuring the URL
registry to suite the environment and the needs.
Objective: Introduction to dynamic endpoints with the
Registry
Prerequisites:
Start the Synapse configuration numbered 10: i.e. wso2-esb -sample 10
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
Start a second Axis2 server on http port 9001 and https port 9003 as follows:
./axis2server.sh -http 9001 -https 9003
This example introduces dynamic endpoints, where the definition of an
endpoint is stored in the Registry. To follow this example execute the stock
quote client as 'ant stockquote..' and see that the message is routed to the
SimpleStockQuoteService on the default Axis2 instance on http port 9000.
Repeat the above example immediately again, and notice that the endpoint is
cached and reused by ESB - similarly to example # 8.
ant stockquote -Dtrpurl=http://localhost:8280/
Now edit the repository/conf/sample/resources/endpoint/dynamic_endpt_1.xml
definition and update the address to
"http://localhost:9001/soap/SimpleStockQuoteService". After the cached
expires, the Registry loads the new definition of the endpoint, and then the
messages can be seen being routed to the second sample Axis2 server on http
port 9001.
Prerequisites:
Start the Synapse configuration numbered 11: i.e. wso2-esb -sample 11
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This example shows a full registry based ESB configuration. Thus it is
possible to start a remote configuration from multiple instances of ESB in a
clustered environment easily. The Synapse configuration held on a node
hosting ESB simply points to the registry and looks up the actual
configuration by requesting the key 'synapse.xml'.
(Note: Full registry based configuration is not dynamic atleast for the
moment. i.e. it is not reloading itself)
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/
[HttpServerWorker-1] INFO LogMediator - message = This is a dynamic Synapse configuration
The actual synapse.xml loaded is:
<!-- a registry based Synapse configuration -->
<definitions xmlns="http://ws.apache.org/ns/synapse">
<log level="custom">
<property name="message" value="This is a dynamic Synapse configuration $$$"/>
</log>
<send/>
</definitions>
Objective: Demonstrate one way messaging / fireAndForget through
ESB
Prerequisites:
Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps
above)
Start the Synapse configuration numbered 1: i.e. wso2-esb -sample 1
This example invokes the one-way 'placeOrder' operation on the
SimpleStockQuoteService using the custom client which uses the Axis2
ServiceClient.fireAndForget() API. To test this, use 'ant
-Dmode=placeorder...' and you will notice the one way message flowing through
ESB into the sample Axis2 server instance, which reports the acceptance of
the order as follows:
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=placeorder
SimpleStockQuoteService :: Accepted order for : 7482 stocks of IBM at $ 169.27205579038733
If you send your client request through TCPmon, you will notice that the
SimpleStockQuoteService replies to ESB with a HTTP 202 reply, and that ESB
in-turn replies to the client with a HTTP 202 acknowledgement
Objective: Demonstrate dual channel messaging
through synapse
Prerequisites:
Start the Axis2 server
and deploy the SimpleStockQuoteService (Refer steps above)
Start
the Synapse configuration numbered 0: i.e. synapse -sample 0
This example invokes the same 'getQuote' operation on the
SimpleStockQuoteService using the custom client which uses the Axis2
ServiceClient API with useSeparateListener set to true so that the response is
coming through a different channel than the one which is used to send the request
to a callback defined in the client.
To test this, use 'ant
-Dmode=dualquote...' and you will notice the dual channel invocation
through Synapse into the sample Axis2 server instance, which reports the response
back to the client over a different channel:
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=dualquote
Response received to the callback
Standard dual channel :: Stock price = $57.16686934968289
If you send your client request through TCPmon, you will notice that
Synapse replies to the client with a HTTP 202 acknowledgment when you send the request and
the communication between synapse and the server happens on a single channel and then you
get the response back from synapse to the clients callback in a different channel (which
cannot be observed through TCPmon)
Also you could see the wsa:Reply-To header being something like
http://localhost:8200/axis2/soap/anonService2 which implies that the reply
is being on a different channel listening on the port 8200. Please note that it is
required to engage addressing when using the dual channel invocation because it
requires the wsa:Reply-To header.
Objective: MTOM and SwA optimizations and request/response
correlation
Prerequisites:
Start the Synapse configuration numbered 51: i.e. wso2-esb -sample 51
Start the Axis2 server and deploy the MTOMSwASampleService if not already
done
Execute the 'ant optimizeclient' specifying MTOM optimization as follows:
ant optimizeclient -Dopt_mode=mtom
The configuration now sets a local message context property, and forwards
the message to 'http://localhost:9000/soap/MTOMSwASampleService' optimizing
binary content as MTOM. By sending this message through TCPMon you would be
able to see the actual message sent over the http transport if required. Thus
during response processing, by checking the local message property ESB could
identify the past information about the current message context, and uses
this knowledge to transform the response back to the client in the same
format as the original request.
When the client executes successfully, it will upload a file containing
the ASF logo and receive its response back again and save it into a temporary
file.
[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as MTOM
[java] Saved response to file : ./../../work/temp/sampleClient/mtom-49258.gif
Next try SwA as:
ant optimizeclient -Dopt_mode=swa
[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as SwA
[java] Saved response to file : ./../../work/temp/sampleClient/swa-47549.gif
By using TCPMon and sending the message through it, one can inspect that
the requests and responses sent are indeed MTOM optimized or sent as http
attachments as follows:
<definitions xmlns="http://ws.apache.org/ns/synapse">
<sequence name="main" onError="errorHandler">
<in>
<send>
<endpoint>
<loadbalance>
<endpoint>
<address uri="http://localhost:9001/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9002/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9003/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
</loadbalance>
</endpoint>
</send><drop/>
</in>
<out>
<!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
<send/>
</out>
</sequence>
<sequence name="errorHandler">
<makefault>
<code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
</makefault>
<header name="To" action="remove"/>
<property name="RESPONSE" value="true"/>
<send/>
</sequence>
</definitions>
Objective: Demonstrate the simple load balancing among a set of
endpoints
Prerequisites:
Start ESB with sample configuration 52. (i.e. wso2-esb -sample 52)
Deploy the LoadbalanceFailoverService by switching to <ESB installation
directory>/samples/axis2Server/src/LoadbalanceFailoverService directory
and running ant.
Start three instances of sample Axis2 server on HTTP ports 9001, 9002 and
9003 and give some unique names to each server.
Example commands to run sample Axis2 servers from the <ESB installation
directory>/samples/axis2Server directory in Linux are listed below:
Now we are done with setting up the environment for load balance sample.
Start the load balance and failover client using the following command:
ant loadbalancefailover -Di=100
This client sends 100 requests to the LoadbalanceFailoverService through
ESB. ESB will distribute the load among the three endpoints mentioned in the
configuration in round-robin manner. LoadbalanceFailoverService appends the
name of the server to the response, so that client can determine which server
has processed the message. If you examine the console output of the client,
you can see that requests are processed by three servers as follows:
[java] Request: 1 ==> Response from server: MyServer1
[java] Request: 2 ==> Response from server: MyServer2
[java] Request: 3 ==> Response from server: MyServer3
[java] Request: 4 ==> Response from server: MyServer1
[java] Request: 5 ==> Response from server: MyServer2
[java] Request: 6 ==> Response from server: MyServer3
[java] Request: 7 ==> Response from server: MyServer1
...
Now run the client without the -Di=100 parameter to send infinite
requests. While running the client shutdown the server named MyServer1. You
can observe that requests are only distributed among MyServer2 and MyServer3
after shutting down MyServer1. Console output before and after shutting down
MyServer1 is listed below (MyServer1 was shutdown after request 63):
...
[java] Request: 61 ==> Response from server: MyServer1
[java] Request: 62 ==> Response from server: MyServer2
[java] Request: 63 ==> Response from server: MyServer3
[java] Request: 64 ==> Response from server: MyServer2
[java] Request: 65 ==> Response from server: MyServer3
[java] Request: 66 ==> Response from server: MyServer2
[java] Request: 67 ==> Response from server: MyServer3
...
Now restart MyServer1. You can observe that requests will be again sent to
all three servers roughly after 60 seconds. This is because we have specified
<suspendDurationOnFailure> as 60 seconds in the configuration.
Therefore, load balance endpoint will suspend any failed child endpoint only
for 60 seconds after detecting the failure.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<sequence name="main" onError="errorHandler">
<in>
<send>
<endpoint>
<failover>
<endpoint>
<address uri="http://localhost:9001/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9002/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9003/soap/LBService1">
<enableAddressing/>
<suspendDurationOnFailure>60</suspendDurationOnFailure>
</address>
</endpoint>
</failover>
</endpoint>
</send><drop/>
</in>
<out>
<!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
<send/>
</out>
</sequence>
<sequence name="errorHandler">
<makefault>
<code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
</makefault>
<header name="To" action="remove"/>
<property name="RESPONSE" value="true"/>
<send/>
</sequence>
</definitions>
Objective: Demonstrate the failover sending
Prerequisites:
Start ESB with sample configuration 53 (i.e. wso2-esb -sample 53)
Deploy the LoadbalanceFailoverService and start three instances of sample
Axis2 server as mentioned in sample 52.
Above configuration sends messages with the failover behavior. Initially
the server at port 9001 is treated as primary and other two are treated as
back ups. Messages are always directed only to the primary server. If the
primary server has failed, next listed server is selected as the primary.
Thus, messages are sent successfully as long as there is at least one active
server. To test this, run the loadbalancefailover client to send infinite
requests as follows:
ant loadbalancefailover
You can see that all requests are processed by MyServer1. Now shutdown
MyServer1 and inspect the console output of the client. You will observe that
all subsequent requests are processed by MyServer2.
The console output with MyServer1 shutdown after request 127 is listed
below:
...
[java] Request: 125 ==> Response from server: MyServer1
[java] Request: 126 ==> Response from server: MyServer1
[java] Request: 127 ==> Response from server: MyServer1
[java] Request: 128 ==> Response from server: MyServer2
[java] Request: 129 ==> Response from server: MyServer2
[java] Request: 130 ==> Response from server: MyServer2
...
You can keep on shutting down servers like this. Client will get a
response till you shutdown all listed servers. Once all servers are shutdown,
the error sequence is activated and a fault message is sent to the client as
follows.
[java] COULDN'T SEND THE MESSAGE TO THE SERVER.
Once a server is detected as failed, it will be added to the active
servers list again after 60 seconds (specified in
<suspendDurationOnFailure> in the configuration). Therefore, if you
have restarted any of the stopped servers and have shutdown all other
servers, messages will be directed to the newly started server.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<sequence name="main" onError="errorHandler">
<in>
<send>
<endpoint>
<!-- specify the session as the simple client session provided by Synapse for
testing purpose -->
<session type="simpleClientSession"/>
<loadbalance>
<endpoint>
<address uri="http://localhost:9001/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9002/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9003/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
</loadbalance>
</endpoint>
</send><drop/>
</in>
<out>
<!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
<send/>
</out>
</sequence>
<sequence name="errorHandler">
<makefault>
<code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
</makefault>
<header name="To" action="remove"/>
<property name="RESPONSE" value="true"/>
<send/>
</sequence>
</definitions>
Objective: Demonstrate the load balancing with session affinity
using client initiated sessions
Prerequisites:
Start ESB with sample configuration 54 (i.e. wso2-esb -sample 54).
Deploy the LoadbalanceFailoverService and start three instances of the
sample Axis2 server as in sample 52.
Above configuration is same as the load balancing configuration in sample
52, except that the session type is specified as "simpleClientSession". This
is a client initiated session, which means that the client generates the
session identifier and sends it to with each request. In this sample session
type, client adds a SOAP header named ClientID containing the identifier of
the client. ESB binds this ID with a server on the first request and sends
all seccessive requests containing that ID to the same server. Now switch to
samples/axis2Client directory and run the client using the following command
to check this in action.
ant loadbalancefailover -Dmode=session
In the session mode, client continuously sends requests with three diferent
client (session) IDs. One ID is selected among these three IDs for each
request randomly. Then client prints the session ID with the responded server
for each request. Client output for the first 10 requests are shown below.
You can see that session number 0 is always directed to the server named
MyServer1. That means session number 0 is bound to MyServer1. Similarly
session 1 and 2 are bound to MyServer3 and MyServer2 respectively.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<sequence name="main" onError="errorHandler">
<in>
<send>
<endpoint>
<!-- specify the session as the simple client session provided by Synapse for
testing purpose -->
<session type="simpleClientSession"/>
<loadbalance>
<endpoint>
<failover>
<endpoint>
<address uri="http://localhost:9001/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9002/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
</failover>
</endpoint>
<endpoint>
<failover>
<endpoint>
<address uri="http://localhost:9003/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
<endpoint>
<address uri="http://localhost:9004/soap/LBService1">
<enableAddressing/>
</address>
</endpoint>
</failover>
</endpoint>
</loadbalance>
</endpoint>
</send><drop/>
</in>
<out>
<!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
<send/>
</out>
</sequence>
<sequence name="errorHandler">
<makefault>
<code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
<reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
</makefault>
<header name="To" action="remove"/>
<property name="RESPONSE" value="true"/>
<send/>
</sequence>
</definitions>
Objective: Demonstrate the session affinity based load balancing
with failover capability
Prerequisites:
Start ESB with sample configuration 55 (i.e. wso2-esb -sample 55).
Deploy the LoadbalanceFailoverService and start four sample Axis2 servers
on http ports 9001, 9002, 9003 and 9004 respectively (make sure to specify
unconflicting https ports).
This configuration also uses "simpleClientSession" to bind sessions as in
the previous sample. But failover endpoints are specified as the child
endpoints of the load balance endpoint. Therefore sessions are bound to the
failover endpoints. Session information has to be replicated among the
servers listed under each failover endpoint using some clustering mechanism.
Therefore, if one endpoint bound to a session failed, successive requests for
that session will be directed to the next endpoint in that failover group.
Run the client using the following command to observe this behaviour.
Note that session 0 is always directed to MyServer1 and session 1 is
directed to MyServer3. No requests are directed to MyServer2 and MyServer4 as
they are kept as backups by failover endpoints. Now shutdown the server named
MyServer1 while running the sample. You will observe that all successive
requests for session 0 is now directed to MyServer2, which is the backup
server for MyServer1's group. This is shown below, where MyServer1 was
shutdown after the request 534.
<definitions xmlns="http://ws.apache.org/ns/synapse">
<sequence name="main">
<in>
<send>
<!-- get epr from the given wsdl -->
<endpoint>
<wsdl uri="file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl" service="SimpleStockQuoteService" port="SimpleStockQuoteServiceSOAP11port_http"/>
</endpoint>
</send>
</in>
<out>
<send/>
</out>
</sequence>
</definitions>
Objective: Demonstrate the use of WSDL endpoints
Prerequisites:
Start the Synapse configuration numbered 56 (i.e. wso2-esb -sample 56).
Deploy the SimpleStockQuoteService and start the sample Axis2 server.
This sample uses a WSDL endpoint inside the send mediator. WSDL endpoints
can extract endpoint's address from the given WSDL. As WSDL documents can
have many services and many ports inside each service, the service and port
of the required endpoint has to be specified. As with address endpoints, QoS
parameters for the endpoint can be specified inline in the configuration. An
excerpt taken from the sample_proxy_1.wsdl containing the specified service
and port is listed below.
Specified service and port refers to the endpoint address
"http://localhost:9000/soap/SimpleStockQuoteService" according to the above
WSDL. Now run the client using the following command.
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
Client will print the quote price for IBM received from the server running
on port 9000. Observe the Axis2 console and the ESB console to verify this
behavior.
Objective: Connecting to endpoints with WS-Security for outgoing
messages
Prerequisites:
You may also need to download and install the unlimited strength policy
files for your JDK before using Apache Rampart (e.g. see
http://java.sun.com/javase/downloads/index_jdk5.jsp)
Start the Synapse configuration numbered 100: i.e. wso2-esb -sample 100
Start the Axis2 server and deploy the SecureStockQuoteService if not already
done
Use the stock quote client to send a request without WS-Security. ESB is
configured to enable WS-Security as per the policy specified by
'policy_3.xml' for the outgoing messages to the SecureStockQuoteService
endpoint hosted on the Axis2 instance. The debug log messages on ESB shows
the encrypted message flowing to the service and the encrypted response being
received by ESB. The wsse:Security header is then removed from the decrypted
message and the response is delivered back to the client, as expected. You
may execute the client as follows:
ant stockquote -Dtrpurl=http://localhost:8280/
The message sent by ESB to the secure service can be seen as follows, when
TCPMon is used.
Objective: Demonstrate the message exchange between ESB and the
server using WS-ReliableMessaging (WS-RM)
Prerequisites:
Deploy the ReliableStockQuoteService in the sample Axis2 server by
switching to the samples/axis2Server/src/ReliableStockQuoteService directory
and running ant.
Start the sample Axis2 server on port 9000.
Start ESB with the sample configuration 101 (i.e. wso2-esb -sample 101).
In the above configuration, WS-RM is engaged to the endpoint using the
<enableRM/> tag. It is possible to engage WS-RM to both Address and
WSDL endpoints using this tag. In addition to the RM enabled endpoint,
RMSequence mediator is specified before the send mediator. This mediator is
used to specify the set of messages to be sent using a single RM sequence. In
this sample it is specified as single message per sequence. It also specifies
the version of the WS-RM to be used. Refer to the ESB configuration language
documentation for more information about the RMSequence mediator. RM related
SOAP headers are removed form the message in the out mediator as WS-RM
message exchange happens only between the ESB and the server. Now run the
sample client using the following command.
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280
You can observe the client output displaying the quote price for IBM as
follows:
[java] Standard :: Stock price = $189.2521262517493
There is no difference to be observed between the normal message exchange
and WS-RM enabled message exchange as far as client and server outputs are
considered. But if you look at the wire level messages, you would observe
additional WS-RM messages and WS-RM elements. ESB, the initiator of the RM
sequence, first try to create a sequence by sending a message with
CreateSequence element.
ESB keeps on sending above message till the server responds with a valid
response message with 200 OK HTTP header. If the server is not ready with a
response, it will respond with 202 Accepted HTTP header for all requests.
Once the server is ready with a response it will send the response message
with sequence ID as follows.
Note that although each of above messages are separate SOAP messages, in
most cases they will be exchanged in a single socket connection as HTTP
Keep-Alive header is used.
Prerequisites:
Start the Synapse configuration numbered 150: i.e. wso2-esb -sample 150
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
Once ESB starts, you could go to
http://localhost:8280/soap/StockQuoteProxy?wsdl and view the WSDL generated
for the proxy service defined in the configuration. This WSDL is based on the
source WSDL supplied in the proxy service definition, and is updated to
reflect the proxy service EPR.
Execute the stock quote client by requesting for a stock quote on the
proxy service as follows:
ant stockquote -Daddurl=http://localhost:8280/soap/StockQuoteProxy
An 'inSequence' or 'endpoint' or both of these would decide how the
message would be handled after the proxy service receives the message. In the
above example, the request received is forwarded to the sample service hosted
on Axis2. The 'outSequence' defines how the response is handled before it is
sent back to the client. By default, a proxy service is exposed over all
transports configured for ESB, unless these are specifically mentioned
through the 'transports' attribute.
Objective: Using custom sequences and endpoints for message
mediation with proxy services
Prerequisites:
Start the Synapse configuration numbered 151: i.e. wso2-esb -sample 151
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
This configuration creates two proxy services.. The first proxy service
'StockQuoteProxy1' uses the sequence named 'proxy_1' to process incoming
messages and the sequence named "out" to process outgoing responses. The
second proxy service 'StockQuoteProxy2' is set to directly forward messages
that are received to the endpoint named 'proxy_2_endpoint' without any
mediation.
You could send a stock quote request to each of these proxy services and
receive the reply generated by the actual service hosted on the Axis2
instance.
ant stockquote -Daddurl=http://localhost:8280/soap/StockQuoteProxy1
ant stockquote -Daddurl=http://localhost:8280/soap/StockQuoteProxy2
Objective: Switching transports and message format from SOAP to REST/POX
Prerequisites:
Start the Synapse configuration numbered 152: i.e. wso2-esb -sample 152
Start the Axis2 server and deploy the SimpleStockQuoteService if not
already done
This configuration demonstrates how a proxy service could be exposed on a
subset of available transports, and how it could switch from one transport to
another. This example exposes the created proxy service only on https, and
thus if the user tries to access it over http, would result in a fault.
ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuoteProxy
...
[java] org.apache.axis2.AxisFault: The service cannot be found for the endpoint reference (EPR) /soap/StockQuoteProxy
Accessing this over https (ant stockquote
-Dtrpurl=https://localhost:8243/soap/StockQuoteProxy) causes the proxy
service to access the SimpleStockQuoteService on the sample Axis2 server
using REST/POX. This could be seen if the message exchange was captured using
TCPMon as follows. The REST/POX response is now transformed back into a SOAP
message and returned to the client.
Objective: Routing the messages arrived to a proxy service without
processing the MustUnderstand headers (Security header)
Prerequisites:
You may also need to download and install the unlimited strength policy files
for your JDK before using Apache Rampart (e.g. see
http://java.sun.com/javase/downloads/index_jdk5.jsp)
Start the Synapse configuration numbered 153: i.e. wso2-esb -sample 153
Start the Axis2 server and deploy the SecureStockQuoteService if not already
done
The proxy service will receive secure messages with security headers which
are MustUnderstand. But hence element 'engageSec' is not present in the proxy
configuration ESB will not engage that Apache Rampart on this proxy service.
It is expected that an MustUnderstand failure exception on the AxisEngine
would occur before the message arrives ESB. But ESB handles this message and
gets it in by setting all the headers which are MustUnderstand and not
processed to processed state. This will enable ESB to route the messages
without reading the Security headers (just routing the messages from client
to service, both of which are secure). To execute the client, send a stock
quote request to the proxy service, and sign and encrypt the request by
specifying the client side security policy as follows:
ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuoteProxy -Dpolicy=./../../repository/conf/sample/resources/policy/client_policy_3.xml
By following through the debug logs or TCPMon output, you could see that
the request received by the proxy service was signed and encrypted. Also,
looking up the WSDL of the proxy service by requesting the URL
http://localhost:8280/soap/StockQuoteProxy?wsdl reveals the security policy
attachments are not there and security is not engaged. When sending the
message to the backend service, you could verify that the security headers
were there as in the original message to ESB from client, and that the
response received does use WS-Security, and forwarded back to the client
without any modification. You should note that this wont be a security hole
because the message inside ESB is signed and encrypted and can only be
forwarded to a secure service to be useful.
Sample setup is same as LoadBalance endpoints (#53 to #54).
Start the Synapse configuration numbered 154: i.e. synapse -sample 154
Start the Axis2 server and deploy the SecureStockQuoteService if not already
done
Runs the client with
ant loadbalancefailover -Dmode=session -Dtrpurl=http://localhost:8280/soap/LBProxy
Objective: Demonstrate the dual channel invocation with Synapse proxy services
Prerequisites:
Start the Synapse
configuration numbered 150: i.e. synapse -sample 155
Start the
Axis2 server and deploy the SimpleStockQuoteService if not already done
This sample will show the action of the dual channel invocation within client and Synapse
as well as within synapse and the actual server. Note that if you want to enable dual
channel invocation you need to set the separateListener attribute to true of the
enableAddressing element of the endpoint.
Execute the stock quote client by requesting for a stock quote on a dual channel from the
proxy service as follows:
ant stockquote -Daddurl=http://localhost:8280/soap/StockQuoteProxy -Dmode=dualquote
In the above example, the request received is forwarded to the sample service
hosted on Axis2 and the endpoint specifies to enable addressing and do the invocation
over a dual channel. If you observe this message flow by using a TCPmon, you could see that
on the channel you send the request to synapse the response has been written as an
HTTP 202 Accepted, where as the real response from synapse will come over a different channel
which cannot be obsesrved unless you use tcpdump to dump all the TCP level messages.
At the same time you can observe the behaviour of the invocation between synapse and
the actual Axis2 service, where you can see a 202 Accepted message being delivered to synapse
as the response to the request. The actual response will be delivered to synapse over a
different channel.
Objective: Using WS-Security signing and encryption with proxy
services through WS-Policy
Prerequisites:
You may also need to download and install the unlimited strength policy files
for your JDK before using Apache Rampart (e.g. see
http://java.sun.com/javase/downloads/index_jdk5.jsp)
Start the Synapse configuration numbered 200: i.e. wso2-esb -sample 200
Start the Axis2 server and deploy the SimpleStockQuoteService if not already
done
The proxy service expects to receive a signed and encrypted message as
specified by the security policy. Please see Apache Rampart and Axis2
documentation on the format of the policy file. The element 'engageSec'
specifies that Apache Rampart should be engaged on this proxy service. Hence
if Rampart rejects any request messages that does not conform to the
specified policy, those messages will never reach the 'inSequence' to be
processed. Since the proxy service is forwarding the received request to the
simple stock quote service that does not use WS-Security, we are instructing
ESB to remove the wsse:Security header from the outgoing message. To execute
the client, send a stock quote request to the proxy service, and sign and
encrypt the request by specifying the client side security policy as follows:
ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuoteProxy -Dpolicy=./../../repository/conf/sample/resources/policy/client_policy_3.xml
By following through the debug logs or TCPMon output, you could see that
the request received by the proxy service was signed and encrypted. Also,
looking up the WSDL of the proxy service by requesting the
URLhttp://localhost:8280/soap/StockQuoteProxy?wsdl reveals the security
policy attachment to the supplied base WSDL. When sending the message to the
backend service, you could verify that the security headers were removed, and
that the response received does not use WS-Security, but that the response
being forwarded back to the client is signed and encrypted as expected by the
client.
Objective: Demonstrate the reliable message exchange between the
client and ESB using WS-ReliableMessaging (WS-RM)
Prerequisites:
Deploy the SimpleStockQuoteService in the sample Axis2 server and start it
on port 9000.
Start ESB with the sample configuration number 201 (i.e. wso2-esb -sample
201).
In the above configuration, a proxy service is created with WS-RM enabled
using the <enableRM/> tag. Therefore, this proxy service is capable of
communicating with a WS-RM client. It also removes the WS-RM headers in the
In Sequence before the message is sent to the back end server. This is
required as the reliable messaging is applicable only between the client and
ESB. Now start the client with WS-RM as follows:
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8280/soap/StockQuoteProxy -Dwsrm=true
In this case, client sends WS-RM enabled request to ESB where ESB sends
normal request to the server. This can be observed by examining the wire
level messages between the client and ESB. These messages would be similar to
the wire level messages shown in sample 101. Each message would perform a
similar function to the messages discussed in sample 53.
Objective: Introduction to switching transports with proxy
services
Prerequisites:
Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps
above)
Download, install and start a JMS server, and configure ESB to listen on JMS
(refer notes below)
Start the Synapse configuration numbered 250: i.e. wso2-esb -sample 250
For this example we would use ActiveMQ as the JMS provider. Once ActiveMQ is
installed and started you should get a message as follows:
INFO BrokerService - ActiveMQ JMS Message Broker (localhost) started
You will now need to configure the Axis2 instance used by ESB (not the
sample Axis2 server) to enable JMS support using the above provider. Refer to
the Axis2 documentation on setting up JMS for more details
(http://ws.apache.org/axis2/1_1/jms-transport.html). You will also need to
copy the ActiveMQ client jar files activeio-core-3.0-beta1.jar,
activemq-core-4.0-RC2.jar and geronimo-j2ee-management_1.0_spec-1.0.jar into
the lib directory to allow ESB to connect to the JMS provider.
For a default ActiveMQ v4.0 installation, you may uncomment the Axis2
transport listener configuration found at repository/conf/axis2.xml as
Once you start the Synapse configuration and request for the WSDL of the
proxy service (http://localhost:8280/soap/StockQuoteProxy?wsdl) you will
notice that its exposed only on the JMS transport. This is because the
configuration specified this requirement in the proxy service definition.
Now lets send a stock quote request on JMS, using the dumb stock quote
client as follows:
ant jmsclient -Djms_type=pox -Djms_dest=dynamicQueues/StockQuoteProxy -Djms_payload=MSFT
On the ESB debug log you will notice that the JMS listener received the
request message as:
[JMSWorker-1] DEBUG ProxyServiceMessageReceiver -Proxy Service StockQuoteProxy received a new message...
Now if you examine the console running the sample Axis2 server, you will
see a message indicating that the server has accepted an order as follows:
Accepted order for : 16517 stocks of MSFT at $ 169.14622538721846
In this sample, client sends the request message to the proxy service
e
