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.
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 by markForSuspension.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 into Active 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>
