Monday, October 24, 2011

WSO2 Enterprise Service Bus (ESB) Endpoint Catalog


The endpoints catalog wlks you through the endpoints which are there inside the WSO2 ESB. This will cover the very basics of the endpoints and dive deeper in to the configurtion details and the technical implementation details as well

Contents

Endpoints - Introduction

An endpoint defines an external destination for an outgoing message through WSO2 ESB. An <endpoint> element defines an endpoint in the configuration. An endpoint may be specified as an address endpoint, WSDL based endpoint, a load balancing endpoint or a fail-over endpoint as follows:
    <endpoint [name="string"] [key="string"]>
        address-endpoint | default-endpoint | wsdl-endpoint | load-balanced-endpoint | fail-over-endpoint
    </endpoint>
All the types of endpoints can have a name attribute which specify the name of the endpoint and such named endpoints can be referred by other endpoints using a key attribute. For example if there is an endpoint named as "foo", the following endpoint can be used in any place, where "foo" has to be used.
    <endpoint key="foo"/>
This let the users to reuse the already defined endpoints in several places.
The endpoints also have a trace attribute which turns on detailed trace information for messages being sent to the endpoint. These are available in the trace.log configured via the log4j.properties file(which can be found within lib folder once you unzip wso2 ESB zip). Setting the trace log level to TRACE will dump detailed trace information including message payloads.
At any given time an endpoint can be one of the following four states.
[1] Active - Endpoint is active and running.
[2] TimeOut - The endpoint can be in TimeOut state if we get a timeout error when invoking the endpoint (because the endpoint is currently unavailable or due to a network failure) or if it returns a previously defined error code for timeout state, the endpoint said to be in TimeOut state. The possible error codes can be found in the SynapseConstant class (under the endpoint failure section). A timed out endpoint is a candidate for a suspenstion. The configuration related to marking an endpoint for suspension is given bymarkForSuspension.If the configuration does have a positive retrieve count (see the configuration section below) the endpoint will be retrieve again (the number of time to retrieve can be configured using the same configuration element) and if it fails in further attempts it will transfer into Suspended state.
[3] Suspended - When invoking the endpoint if a previously defined error code for Suspended state is returned or a if a TimeOut endpoint fails in further attempts the endpoint is said to be in Suspended state. The endpoint can goes into Active state once the suspend duration is over. The configuration section called suspendOnFailure.
[4] Switch Off - The endpoint is moved into maintains mode.
A state transfer between any state to Switch off state can be done only manually using JMX based API. And also an endpoint which is in SwitchOff state can only transfer intoActive state again using the JMX based API. See section on using JMX based API to learn how to do this.
The state transition between states can be shown as follows.
endpoint-state-image
Figure1: The state transition between states in an endpoint

Using jconsole to manage state transition between states

The jconsole tool is a JMX-compliant graphical tool for monitoring a Java virtual machine. If you have installed java you'll automatically get this tool. We'll add an endpoint (name 'ep1') and monitor the states transition between states in ep1
1. Add an address endpoint called 'ep1'. Refer endpoint userguide to see how this can be done.
2. Start jconsole by typing jconsole at your termnial, if you encounter any problem please consult your operatying system guide. You'll see the following console once you select Mbeans tab.
jconsole-mbean-tab
Figure2: Jconsole Mbeans tab
3.Go to org.apache.synpase menu from left hand and expand it. You'll see the following figure with the endpoint ep1 that we just added.
endpoint-mbean-show
Figure3: Endpoint Mbean is selected
4. Select the ep1 endpoint and you'll see the information related to this endpoint and please note that the state is given as active as the first entry and value is set to true. The endpoint is in active state.
endpoint-information-image
Figure4: The ep1 endpoint attributes. The endpoint is active.
5. Now go to the Operations tab and switch off the endpoint. You'll see a message saying the operation was successful.
endpoint-off-image
Figure5: Switching off the endpoint.
You'll also see a INFO level log message saying that the endpoint was switched off manually.
[2009-06-23 12:18:21,149] INFO - EndpointContext Manually switching off endpoint : ep1
6. Next again switch back to Attributes tab and see the state of the endpoint after refreshing it. You'll see endpoint is inactive and the endpoint is in switch off state. At this point if you try to use a client which use this endpoint you'll see it fails since the endpoint is down. You can use a similar approach activate the endpoint back.
endpoint-switched-off-image
Figure6: Endpoint is in Switch off state.

Address Endpoint

Address endpoint is an endpoint defined by specifying the EPR (Endpoint Reference) and other attributes of the configuration.

Address endpoint configuration

<address uri="endpoint address" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
    [encoding="charset encoding"]
    [statistics="enable|disable"] [trace="enable|disable"]>

    <enableRM [policy="key"]/>?
    <enableSec [policy="key"]/>?
    <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?

    <timeout>
        <duration>timeout duration in milliseconds</duration>
        <action>discard|fault</action>
    </timeout>?

    <markForSuspension>
        [<errorCodes>xxx,yyy</errorCodes>]
        <retriesBeforeSuspension>m</retriesBeforeSuspension>
        <retryDelay>d</retryDelay>
    </markForSuspension>

    <suspendOnFailure>
        [<errorCodes>xxx,yyy</errorCodes>]
        <initialDuration>n</initialDuration>
        <progressionFactor>r</progressionFactor>
        <maximumDuration>l</maximumDuration>
    </suspendOnFailure>
</address>

Address endpoint attributes

uriEPR of the target endpoint. See the table below for a possible list of transports.
formatMessage format for the endpoint.
optimizeMethod to optimize the attachments.
encodingThe charset encoding to use for the endpoint.
statisticsThis enables statistics for the endpoint.
traceThis enables trace for the endpoint.

QoS for the endpoint

QoS (Quility of service) aspects such as WS-RM(WS-Reliable messaging), WS-Security and WS-Addressing may be enabled on messages send to an endpoint using enableRM, enableSec and enableAddressing elements. Optionally, the WS-RM and WS-Security policies could be specified using policy attribute.

QoS configuration

enableRM [policy="key"]This enables WS-Reliable messaging for the message which goes for the endpoint. The optional policy attribute specify the WS-RM policy.
enableSec [policy="key"]This enables WS-Security for the message which goes for the endpoint. The optional policy attribute specify the WS-Security policy.
enableAddressing [version="final | submission"] [seperateListener=" true | false"]This enables WS-Addressing for the message which goes for the endpoint. User can specify to have seperate listener with version final or submission. 

Endpoint timeout

Address(and also WSDL) endpoints can timeout if the response fails to arrive at Synapse by a predefined timeout duration specified in seconds. The timeout action specifies whether to discard reponse that arives later, or to trigger a fault. Synapse has a periodic timeout handler that triggers itself at each 15 seconds interval. Thus endpoint timeout will have a +/- erroce on trigger time. Though this can be minimized by setting a System property "synapse.timeout_handler_interval"(This property can be set in synapse.properties synpase property file which is located in conf directory inside repository once you unzipped WSO2 ESB ) to a millisecond duration below the desired endpoint timeout, care must be taken as a lesser value may have a higher overhead on the system.

timeout configuration

durationTimeout duration in millisecond. 
actionOnce a timeout occurs the action to perform, avilable options are discard (discard the response which arrives late) or fault (trigger a fault) .

Marking endpoint for suspension

As described before (see description on Timeout state above) this configuration element describes the configuration for a timeout endpoint.

markForSuspension configuration

errorCodesA comma separated error code list which can be returned by the endpoint. See SynpaseConstant class for a possible list of error codes. 
retriesBeforeSuspensionNumber of retries before go into suspended state.
retryDelayThe delay between each try.

Suspending endpoint on failure

Leaf endpoints(Address and WSDL) endpoint can be put into suspended state if it is detected as failed. An endpoint that fails may be suspended for a specified duration after such a failure, during which new messages will not be processed through the endpoint. The amount of time waiting before next attempt follows the following formula.
next suspension time period = Max (Initial Suspension duration * (progression factor try count), Maximum Duration)
All the variables in the above formula are configuration values used to calculate the try count. Try count means, how many tries occurred after the endpoint is SUSPENDED. As the try count increases, the next SUSPENSION time period will also increase. This increase is bound to a maximum duration.

suspendOnFailure configuration

errorCodeA comma separated error code list which can be returned by the endpoint. See SynpaseConstant class for a possible list of error codes. 
initialDurationInitial duration(in milliseconds) to suspend the endpoint.
progressionFactorThe progression factor for the geometric series. See above for a more detailed description.
maximumDurationMaximum duration(in milliseconds) to suspend the endpoint. 

Following are the sample address URI definitions.

TransportSample Address
HTTPhttp://localhost:9000/services/SimpleStockQuoteService
JMSjms:/SimpleStockQuoteService?
transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&
java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&
java.naming.provider.url=tcp://localhost:61616&
transport.jms.DestinationType=topic
Mailmailto:guest@host
VFSvfs:file:///home/user/directory
vfs:file:///home/user/file
vfs:ftp://guest:guest@localhost/directory?vfs.passive=true
FIXfix://host:port?BeginString=FIX4.4&SenderCompID=WSO2&TargetCompID=APACHE

Default Endpoint

Default endpoint is an endpoint defined for adding QoS and other configurations to the endpoint which is resolved from the 'To' address of the message context. All the configurations such as message format for the endpoint, the method to optimize attachments, reliable messaging, security policies for the endpoint can be specified as in the Address Endpoint. This endpoint differs from the address endpoint only in the uri attribute which will not be present in this endpoint. Following section describes the configuration of a default endpoint.

Default endpoint configuration

<default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
     [encoding="charset encoding"]
     [statistics="enable|disable"] [trace="enable|disable"]>

    <enableRM [policy="key"]/>?
    <enableSec [policy="key"]/>?
    <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?

    <timeout>
        <duration>timeout duration in milliseconds</duration>
        <action>discard|fault</action>
    </timeout>?

    <markForSuspension>
        [<errorCodes>xxx,yyy</errorCodes>]
        <retriesBeforeSuspension>m</retriesBeforeSuspension>
        <retryDelay>d</retryDelay>
    </markForSuspension>

    <suspendOnFailure>
        [<errorCodes>xxx,yyy</errorCodes>]
        <initialDuration>n</initialDuration>
        <progressionFactor>r</progressionFactor>
        <maximumDuration>l</maximumDuration>
    </suspendOnFailure>
</default>

WSDL endpoint

WSDL endpoint is an endpoint definition based on a specified WSDL document. The WSDL document can be specified either as a URI or as an inlined definition within the configuration. The service and port name containing the target EPR has to be specified with the 'service' and 'port' (or 'endpoint') attributes respectively. enableRM, enableSec, enableAddressing, suspendDurationOnFailure and timeout elements are same as for an Address endpoint.

WSDL endpoint configuration

<wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname">
    <wsdl:definition>...</wsdl:definition>?
    <wsdl20:description>...</wsdl20:description>?
    <enableRM [policy="key"]/>?
    <enableSec [policy="key"]/>?
    <enableAddressing/>?

    <timeout>
        <duration>timeout duration in milliseconds</duration>
        <action>discard|fault</action>
    </timeout>?

    <markForSuspension>
        [<errorCodes>xxx,yyy</errorCodes>]
        <retriesBeforeSuspension>m</retriesBeforeSuspension>
        <retryDelay>d</retryDelay>
    </markForSuspension>

    <suspendOnFailure>
        [<errorCodes>xxx,yyy</errorCodes>]
        <initialDuration>n</initialDuration>
        <progressionFactor>r</progressionFactor>
        <maximumDuration>l</maximumDuration>
    </suspendOnFailure>
</wsdl>

Load balance Endpoint

A Load balanced endpoint distributes the messages (load) arriving at it among a set of listed endpoints or static members by evaluating the load balancing policy and any other relevant parameters. The policy attribute of the load balance element specifies the load balance policy (algorithm) to be used for selecting the target endpoint or static member. Currently only the roundRobin policy is supported. The failover attribute determines if the next endpoint or static member should be selected once the currently selected endpoint or static member has failed, and defaults to true. The set of endpoints or static members amongst which the load has to be distributed can be listed under the 'loadBalance' element. These endpoints can belong to any endpoint type mentioned in this document. For example, failover endpoints can be listed inside the load balance endpoint to load balance between failover groups etc. The loadbalance element cannot have both endpoint & member child elements in the same configuration. In the case of the member child element, the hostNamehttpPort and/or httpsPort attributes could be specified.
The optional 'session' element makes the endpoint a session affinity based load balancing endpoint. If it is specified, sessions are bound to endpoints in the first message and all successive messages for those sessions are directed to their associated endpoints. Currently there are two types of sessions supported in SAL endpoints. Namely HTTP transport based session which identifies the sessions based on http cookies and the client session which identifies the session by looking at a SOAP header sent by the client with the QName '{http://ws.apache.org/ns/synapse}ClientID'. The 'failover' attribute mentioned above is not applicable for session affinity based endpoints and it is always considered as set to false. If it is required to have failover behavior in session affinity based load balance endpoints, list failover endpoints as the target endpoints.

Load balance endpoint configuration

<session type="http|simpleClientSession"/>?
<loadBalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"]
        [failover="true|false"]>
    <endpoint .../>+
    <member hostName="host" [httpPort="port"] [httpsPort="port2"]>+
</loadBalance>

Failover Endpoint

Failover endpoints send messages to the listed endpoints with the following failover behavior. At the start, the first listed endpoint is selected as the primary and all other endpoints are treated as backups. Incoming messages are always sent only to the primary endpoint. If the primary endpoint fails, next active endpoint is selected as the primary and failed endpoint is marked as inactive. Thus it sends messages successfully as long as there is at least one active endpoint among the listed endpoints.

Failover endpoint configuration

<failover>
    <endpoint .../>+
</failover>

Dynamic Load balance Endpoint

A Dynamic Load balanced endpoint distributes the messages (load) arriving at it among a application members by evaluating the load balancing policy and any other relevant parameters. These application members will be discovered using the membershipHandler class. Generally, this class will use a group communication mechanism to discover the application members. The class attribute of the membershipHandler element should be an implementation of org.apache.synapse.core.LoadBalanceMembershipHandler. membershipHandler specific properties can be specified using the property elements. The policy attribute of the dynamicLoadbalance element specifies the load balance policy (algorithm) to be used for selecting the next member to which the message has to be forwaded to. Currently only the roundRobin policy is supported. The failover attribute determines if the next member should be selected once the currently selected member has failed, and defaults to true.

Dynamic Load balance endpoint configuration

  <dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]>
    <membershipHandler class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler">
      <property name="name" value="value"/>
    </membershipHandler>
  </dynamicLoadBalance>

Tuesday, October 18, 2011

WSO2 Carbon Studio: How to specify the namespace to a synapse artifact (endpoint/sequence/proxy/local entry)


Synapse changed it default namespace from "http://ws.apache.org/ns/synapse" to "http://synapse.apache.org/ns/2010/04/configuration" with its version 2.0 release. So when you are going to create a synapse artifact you need to decide which namespace you are going to use and how to specify it. This short KB tell you how to get it done in easy steps.
Date: Thu, 21st Oct, 2010
Level: Introductory
Reads: 1036 Comments: 0 | Login or register to post comments
Saminda Wijeratne
Senior Software Engineer
WSO2 Inc
samindaw's picture

Applies To

Projects: ESB, Carbon Studio
Note: The Synapse artifact which I have referred here can be a synapse configuration file, an endpoint, a sequence, a proxy server or a local entry
  

Solution

Determining which namespace to use is easy if you know which carbon server version you are going to deploy the synapse artifacts.
  • If you are going to deploy the synapse artifacts in to a carbon server version 3.0.1 or before (also ESB server version 3.0.1 or before), then you need to use the old synapse namespace version which is "http://ws.apache.org/ns/synapse". 
  • From carbon version 3.1 onwards (i.e. ESB server version 4.0 onwards) you are required to use the namespace "http://synapse.apache.org/ns/2010/04/configuration" in all your synapse configurations. 

Now that you know which namespace to use lets see how you can specify it.
When you create a new synapse configuration through Carbon Studio ESB tools there is a namespace applied to them by default. You can specify this default namespace through the Carbon Studio preferences.
  1. From the main menu select
    • Window -> Preferences
  2. In left handside tree, you will find the preference page "ESB" under the category "Carbon Studio"
  3. Select the "ESB" preference page 
  4. At the right hand side the preference page will show settings related to ESB.
  5. Change the setting "Default namepsace" by selecting the namespace you want from the drop down list (which contains the namespaces available)
  6. Click "Apply"
  7. Click "OK"
  8. Now when you create new synapse artifacts the namespace specified in them by default will be the namespace you've just selected.
Once you have created a synapse artifact inside Carbon Studio or have imported to Carbon Studio, if you need to change the namespace, you will have to use the source view.
  1. Double click to open the synapse artifact file
    • Note that you may use either the ESB editor or the standard XML editor in Eclipse for this
  2. Select the "Source" tab in the multi-page editor which just opened
  3. On the document element (the root element) of the synapse artifact there will be an attribute called "xmlns" and it is this attribute which corresponds to the namespace of the main synapse artifact
  4. Specify the required namespace as the value of the "xmlns" attribute
  5. Note that there could be other namespaces defined in the root element with different namespace prefixes. Their namespaces should not be altered unless the context requires you to do so 
  
Author : Saminda Wijeratne, Product Manager WSO2 Tools, WSO2 Inc, samindaw@wso2.co

WSO2 ESB by Example - File Processing


This article is the first article of a series of articles demonstrating the capabilities of WSO2's ESB with full end-to-end scenarios. It gives a full ESB configuration as well as end-to-end clients and consumer configurations so that users can try out the scenario while understanding the underlying concepts
Date: Wed, 16th Feb, 2011
Level: Advanced
Reads: 2836 Comments: 5 | Login or register to post comments
Supun Kamburugamuva
Technical Lead
WSO2 Inc
supun's picture

Applies To

WSO2 ESB3.0.0 and above

Contents

Introduction

It is often a requirement to pick up a file from a directory and process it within the ESB. In this article we will be discussing a scenario where we pick up a file in a directory, insert the records in the file into a database, send an email saying we have moved the file and finally send the contents of the file to another directory.

This article is aimed at users who have a good knowledge of WSO2 ESB basics. So if you are new to the WSO2 ESB, Configuration Language and Samples of the WSO2 ESB documentation will help you to get familiarized with the basic concepts.
The complete sample is included in the article as an attachment ESB-Sample-01.zip. Inside the .zip, there is a sample-01.pdf document which describes how to set up the sample.
In this article, we will go through the complete configuration step-by-step. First, let's go through the basic configuration of the ESB, which must be done prior to starting the ESB.

Base Configuration

For this scenario, we need to enable e-mail transport and files transport. Also we need to copy a database driver and configure a message formatter. The two transports and message formatter are configured in axis2.xml.

axis2.xml

This very important configuration file is in /repository/conf directory. It is used to configure some of the core functionalities of the ESB. For example, transports, message formatters and builders and execution phases are configured in this configuration file.

VFS Transport

This is the file transport of the ESB. This transport can be used to pick up a file from a file/ftp location and inject the contents into the ESB. Also this transport can be used to create a file in a local directory/ftp location using the message in the ESB.
To enable the transport, un-comment the VFS transport receiver and sender.

Receiver

<transportreceiver name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportListener"/>

Sender

<transportSender name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportSender"/>

Mail Transport

This transport can be used to send and receive e-mail messages.
To enable the transport, un-comment the mailto transport sender. Then configure the mail transport sender to use a mailbox for sending the messages. In this sample, we are not retrieving mails from a mailbox. So there is no need to enable the mail transport receiver.

Sender

<transportSender name="mailto" class="org.apache.axis2.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">synapse.demo.0@gmail.com</parameter>
</transportSender>

Message Builders/Formatters

When a message comes thorough the wire, it first goes through a message builder and message builder is responsible for converting the message into a SOAP message. Message formatters determine the outgoing wire message format of a SOAP message inside the ESB.
For this scenario, the user has to add the following message formatter to axis2.xml. Message formatters are configured in axis2.xml under the section:
<messageFormatters></messageFormatters>
We need to add the org.apache.axis2.transport.http.ApplicationXMLFormatter under the content type “text/html”.
<messageFormatter contentType="text/html" class="org.apache.axis2.transport.http.ApplicationXMLFormatter"/>

Database Drivers

This example uses mySQL as the database. So the driver should be copied into the /repository/components/lib directory. The driver can be found in the ESB-Sample-01.zip's lib folder.

Smooks Libraries

This example uses a CSV smooks library. The library must be copied in to the /repository/components/lib directory. The library is milyn-smooks-csv-1.2.4.jar and can be found in the ESB-Sample-01.zip's lib folder.
These configuration changes make system-wide changes to the ESB and the ESB has to be restarted for these changes to take effect. Now, we must configure the ESB to listen to the file system and process the file.

Mediation Configuration

Proxy Service

In this sample, we are listening to a file system directory using the VFS transport listener. When a file is placed on this directory, we need to get it to a ESB proxy service and process it from there. VFS is a transport configurable at the level of Proxy Services enabling different proxy services to listen to different file directories and different file types. These transport specific configurations are done as parameters of the proxy service.
Our proxy name is FileProxy and it is exposed through the VFS transport.
     
<proxy name="FileProxy" transports="vfs" startOnLoad="true" trace="disable">
    <target>
        <inSequence>
            <log level="full"/>
            <clone>
                <target sequence="fileWriteSequence"/>
                <target sequence="sendMailSequence"/>
                <target sequence="databaseSequence"/>
            </clone>
        </inSequence>
    </target>
    <parameter name="transport.vfs.ActionAfterProcess">MOVE</parameter>
    <parameter name="transport.PollInterval">15</parameter>
    <parameter name="transport.vfs.MoveAfterProcess">file:///Users/supun/quick-starts/original</parameter>
    <parameter name="transport.vfs.FileURI">file:///Users/supun/quick-starts/in</parameter>
    <parameter name="transport.vfs.MoveAfterFailure">file:///Users/supun/quick-starts/failure</parameter>
    <parameter name="transport.vfs.FileNamePattern">.*.txt</parameter>
    <parameter name="transport.vfs.ContentType">text/plain</parameter>
    <parameter name="transport.vfs.ActionAfterFailure">MOVE</parameter>
</proxy>
To expose the proxy service using a particular transport, the "transports" attribute of the proxy service should have the name of the transport and, in this case, it is VFS.
There are several parameters in the FileProxy for configuring the VFS transport. Some of the important parameters are:
  • transport.vfs.FileURI - The directory where proxy is listening 
  • transport.vfs.FileNamePattern - The pattern of the file name as a regular expression
  • transport.vfs.ContentType - When the file is processed it is processed as content from the given content type
Now when a .txt file is placed in the transport.vfs.FileURI, the file is injected into the ESB as a message. Now this message goes to the inSequence of the FileProxy and it creates three clones from the message and executes three sequences. These three sequences are:
  • fileWriteSequence
  • sendMailSequence
  • databaseSequence
Now, let's look at what these three sequences do.

fileWriteSequence

In this sequence, we send the content of the message to a file in the local file system.
    <sequence name="fileWriteSequence">
        <log level="custom">
            <property name="sequence" value="fileWriteSequence"/>
        </log>
        <property name="transport.vfs.ReplyFileName" 
               expression="fn:concat(fn:substring-after(get-property('MessageID'), 'urn:uuid:'), '.txt')" scope="transport"/>
        <property name="OUT_ONLY" value="true"/>
        <send>
            <endpoint name="FileEpr">
                <address uri="vfs:file:///Users/supun/quick-starts/out"/>
            </endpoint>
        </send>
    </sequence>
  1. First we use the log mediator to log the sequence name
  2. Then we set a property called transport.vfs.ReplyFileName at transport scope. This will set the name of the output file. To calculate the name we use XPath. From the XPath we get the Message ID and use that to create a unique file name
  3. Because this is an "out only" operation, we set the OUT_ONLY property to true. Otherwise, the ESB will expect a response for the send
  4. Then, finally, we use the send mediator with an endpoint to write the content of the message into a file. The address of the endpoint is vfs:file:///Users/supun/quick-starts/out. This endpoint address specifies the directory to which the message should be sent

sendMailSequence

In this sequence, we send a mail.
<sequence name="sendMailSequence">
    <log level="custom">
        <property name="sequence" value="sendMailSequence"/>
    </log>
    <property name="messageType" value="text/html" scope="axis2"/>
    <property name="ContentType" value="text/html" scope="axis2"/>
    <property name="Subject" value="File Received" scope="transport"/>
    <property name="OUT_ONLY" value="true"/>
    <send>
        <endpoint name="FileEpr">
            <address uri="mailto:supun@wso2.com"/>
        </endpoint>
    </send>
</sequence>
  1. Log the message using the log mediator
  2. Set the messageType property to text/html to format the message correctly. This property is used by the ESB to select the correct message formatter for outgoing messages
  3. Set the property Subject at transport scope to set the subject of the e-mail
  4. Set the OUT_ONLY property to make the invocation one-way
  5. Send the e-mail using the given address
<send>
    <endpoint name="FileEpr">
        <address uri="mailto:supun@wso2.com"/>
    </endpoint>
</send>

databaseSequence

<sequence name="databaseSequence" xmlns="http://ws.apache.org/ns/synapse">
    <log level="full">
        <property name="sequence" value="before-smooks"/>
    </log>
    <smooks config-key="smooks"/>
    <log level="full">
        <property name="sequence" value="after-smooks"/>
    </log>
    <iterate xmlns:ns2="http://org.apache.synapse/xsd" 
                xmlns:sec="http://secservice.samples.esb.wso2.org" expression="//csv-set/csv-record">
        <target>
            <sequence>
                <log level="full">
                    <property name="State" value="Iteration"/>
                </log>
                <dbreport>
                    <connection>
                        <pool>
                            <password>wso2carbon</password>
                            <user>wso2carbon</user>
                            <url>jdbc:mysql://localhost:3306/DEMO</url>
                            <driver>com.mysql.jdbc.Driver</driver>
                        </pool>
                    </connection>
                    <statement>
                        <sql>insert into INFO values (?, ?)</sql>
                        <parameter expression="//csv-record/name/text()" type="VARCHAR"/>
                        <parameter expression="//csv-record/value/text()" type="VARCHAR"/>
                    </statement>
                </dbreport>
            </sequence>
        </target>
    </iterate>
</sequence>
The message goes to the ESB looking like the following:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <text xmlns="http://ws.apache.org/commons/ns/payload">name_1,value_1
name_2,value_2
        </text>
     </soapenv:Body>
</soapenv:Envelope>
  • Logs the sequence name and full message before applying the smooks Apply and smooks transformation for the message
  • The Smooks transformation will create a XML structure from the incoming text message
<smooks config-key="smooks"/>
Here smooks mediator expects a smooks configuration. The smooks configuration is stored in the file system and referred using a local entry.
<localEntry key="smooks" src="file:resources/smooks-config.xml"/>
Here is the smooks configuration. It executes the the smooks CSV Parser and creates a XML from the input text message.
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd">
        <resource-config selector="org.xml.sax.driver">
                <resource>org.milyn.csv.CSVParser</resource>
                <param name="fields" type="string-list">name,value</param>
        </resource-config>
</smooks-resource-list>
After the smooks transformation the message is as follows:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <csv-set>
            <csv-record>
                <name>name_1</name>
                <value>value_1</value>
            </csv-record>
            <csv-record>
                <name>name_2</name>
                <value>value_2</value>
            </csv-record>
         </csv-set>
    </soapenv:Body>
</soapenv:Envelope>
  • Log the message after the smooks configuration
  • Then iterate through this XML structure. The iteration happens with the XPath expression //csv-set/csv-record. For each iteration, the message in the iteration target is as follows:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
     <soapenv:Body>
         <csv-record>
              <name>name_1</name>
              <value>value_1</value>
         </csv-record>
     </soapenv:Body>
</soapenv:Envelope>
  • Each iteration updates a database table
For each iteration, it executes a dbreport mediator that extracts values from the current iteration message and updates a database.
The dbreport mediator is configured to connect to a database using the given information in the configuration. The database connection information is given under the connection XML tag of the dbreport mediator.
The dbreport mediator is configured assuming a database with the name SAMPLE and a table INFO. The INFO table has two VARCHAR columns. The user has to create the database manually.
The dbreport mediator executes a SQL statement with parameters. The sample SQL statement accepts two parameters and these parameters are calculated using the XPath expressions given in the sample. The XPath expressions in the sample simply get the “name” and “value” XML element’s values from the message in each iteration.

Improvements

  • In this sample, error handling is minimal. In particular, the proxy service doesn’t have an error sequence for handling the errors. In a robust distribution, error handling is very important. 
  • Configuration artifacts should be stored in the registry. We can store the endpoints and smooks configuration file in the registry.

References

Author
Supun Kamburugamuva
Product Manager- Enterprise Service Bus, and Technical Lead; WSO2 Inc.
supun@wso2.com

AttachmentSize
ESB-Sample-01.zip866.7 KB
zoran.avalonsoft.com's picture

Using sqljdbc4 driver with this example

I'm getting the following error in the Windows 7 x64 environment:
ERROR - MediatorWorker Unexpected error executing task/async inject
java.lang.UnsupportedOperationException: Java Runtime Environment (JRE) version 1.6 is not supported by this driver. Use the sqljdbc4.jar class library, which provides support for JDBC 4.0.
Now, I have sqljdbc4.jar in the appropriate location, /repository/components/lib. The sequence specification looks like
com.microsoft.sqlserver.jdbc.SQLServerDriver
jdbc:sqlserver://xxx.xxx.xxx.xxx/DEVSQL;databaseName=ESB-TEST
dbTestUser
1234
The sqljdbc.jar is not present anywhere - except in a strange folder under C:\WSO2\wso2esb-3.0.1\repository\components\configuration\org.eclipse.osgi\bundles\327\1\.cp.
I am using Carbon Studio to get this sample put together, and that's the only thing I can think of specifying sqljdbc.jar.
What exactly is the issue ? How do I make the system use the sqljdbc4.jar ?
Best regards.
superwingkoo1986.163.com's picture

esb

hi, ahout this demo, I have a problem.
my computer os is win7.
the configuration of proxy service as follow:
MOVE
15
file:/C:/test/original
file:/C:/test/in
file:/C:/test/failure
.*.txt
text/plain
MOVE
like format "file:/C:/test/in" or "file://C:/test/in" throw exception, why?
The exception as follow:
TID: [] [WSO2 Stratos Enterprise Service Bus] [2011-09-09 09:08:51,015] ERROR {org.apache.axis2.description.ClientUtils} - The system cannot infer the transport information from the vfs:file:/C:/test/in URL. {org.apache.axis2.description.ClientUtils}
TID: [] [WSO2 Stratos Enterprise Service Bus] [2011-09-09 09:09:50,703] ERROR {org.apache.axis2.description.ClientUtils} - The system cannot infer the transport information from the vfs:file:/C:/test/in URL. {org.apache.axis2.description.ClientUtils}
please help me, thanks.
zoran.avalonsoft.com's picture

It was hiding in

It was hiding in /repository/components/dropin. Once I've deleted the obvious offender it started to work. Tho, now there's a connection issue with a named SQL instance and port selection.
sanket.karjagi.altisource.com's picture

Where can I find the samples zip for this example?

I dont find any attachments.
supun's picture

Not sure what happened but

Not sure what happened but the attachment went missing. I have re-attached it again. Sorry for the in-convenience.
Supun..