Lost in Time!!!: 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

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.

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.

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.

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.

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.

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.

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

uri	EPR of the target endpoint. See the table below for a possible list of transports.
format	Message format for the endpoint.
optimize	Method to optimize the attachments.
encoding	The charset encoding to use for the endpoint.
statistics	This enables statistics for the endpoint.
trace	This 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

duration	Timeout duration in millisecond.
action	Once 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

errorCodes	A comma separated error code list which can be returned by the endpoint. See SynpaseConstant class for a possible list of error codes.
retriesBeforeSuspension	Number of retries before go into suspended state.
retryDelay	The 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

errorCode	A comma separated error code list which can be returned by the endpoint. See SynpaseConstant class for a possible list of error codes.
initialDuration	Initial duration(in milliseconds) to suspend the endpoint.
progressionFactor	The progression factor for the geometric series. See above for a more detailed description.
maximumDuration	Maximum duration(in milliseconds) to suspend the endpoint.

Following are the sample address URI definitions.

Transport	Sample Address
HTTP	http://localhost:9000/services/SimpleStockQuoteService
JMS	jms:/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
Mail	mailto:guest@host
VFS	vfs:file:///home/user/directory vfs:file:///home/user/file vfs:ftp://guest:guest@localhost/directory?vfs.passive=true
FIX	fix://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 hostName, httpPort 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>

Lost in Time!!!

Monday, October 24, 2011

WSO2 Enterprise Service Bus (ESB) Endpoint Catalog

Contents