Author: ruwan Date: Tue Jul 7 02:26:25 2009 New Revision: 40926 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=40926
Log: Fixing the endpoints guide Modified: trunk/esb/java/docs/xdoc/endpoint_guide.xml Modified: trunk/esb/java/docs/xdoc/endpoint_guide.xml URL: http://wso2.org/svn/browse/wso2/trunk/esb/java/docs/xdoc/endpoint_guide.xml?rev=40926&r1=40925&r2=40926&view=diff ============================================================================== --- trunk/esb/java/docs/xdoc/endpoint_guide.xml (original) +++ trunk/esb/java/docs/xdoc/endpoint_guide.xml Tue Jul 7 02:26:25 2009 @@ -17,12 +17,13 @@ ~ under the License. ~ --> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" - "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";> -<html xmlns="http://www.w3.org/1999/xhtml";> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> <head> - <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> - <title>WSO2 ESB - Endpoint Guide </title> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/> + <title>WSO2 ESB - Endpoint Catalog </title> <link href="css/esb-docs.css" rel="stylesheet" /> <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all" /> @@ -30,8 +31,60 @@ <body xml:lang="en"> -<h2>Endpoint Guide</h2> -<h3>Endpoints</h3> +<h1>WSO2 Enterprise Service Bus (ESB) Endpoint Catalog</h1> +<p>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</p> + + <h2>Contents</h2> + <ul> + <li><a href="#Intro">Endpoints - Introduction</a> + <ul> + <li><a href="#Jconsole">Using jconsole to manage state transition between states</a></li> + </ul> + </li> + <li><a href="#AddressEp">Address Endpoint</a> + <ul> + <li><a href="#AddressEpConfig">Address endpoint configuration</a></li> + <li><a href="#AddressEpAttr">Address endpoint attributes</a></li> + <li><a href="#QoSEp">QoS for the endpoint</a></li> + <li><a href="#QoSConfig">QoS configuration</a></li> + <li><a href="#EpTimeout">Endpoint timeout</a></li> + <li><a href="#TimeoutConfig">timeout configuration</a></li> + <li><a href="#MarkSuspension">Marking endpoint for suspension</a></li> + <li><a href="#SuspensionConfig">markForSuspension configuration</a></li> + <li><a href="#SuspendingEp">Suspending endpoint on failure</a></li> + <li><a href="#SuspendOnFailureConfig">suspendOnFailure configuration</a></li> + <li><a href="#SampleAddressURI">Following are the sample address URI definitions</a></li> + </ul> + </li> + <li><a href="#DefaultEp">Default Endpoint</a> + <ul> + <li><a href="#DefaultEpConfig">Default endpoint configuration</a></li> + </ul> + </li> + <li><a href="#WsdlEp">WSDL endpoint</a> + <ul> + <li><a href="#WsdlEpConfig">WSDL endpoint configuration</a></li> + </ul> + </li> + <li><a href="#LbEp">Load balance Endpoint</a> + <ul> + <li><a href="#LbEpConfig">Load balance endpoint configuration</a></li> + </ul> + </li> + <li><a href="#FoEp">Failover Endpoint</a> + <ul> + <li><a href="#FoEpConfig">Failover endpoint configuration</a></li> + </ul> + </li> + <li><a href="#DlbEp">Dynamic Load balance Endpoint</a> + <ul> + <li><a href="#DlbEpConfig">Dynamic Load balance endpoint configuration</a></li> + </ul> + </li> + </ul> +<h2 id="Intro">Endpoints - Introduction</h2> <p>An endpoint defines an external destination for an outgoing message through WSO2 ESB. An <endpoint> element defines an endpoint in the @@ -51,7 +104,7 @@ </p> <pre xml:space="preserve"> - <endpoint key="foo"/> + <endpoint key="foo"/> </pre> <p>This let the users to reuse the already defined endpoints in several places.</p> <p>The endpoints also have a trace attribute which turns on detailed trace information for messages being sent to the @@ -66,7 +119,7 @@ <p><b>[2] TimeOut </b>- 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 <a title="SynapseConstant class" target="_blank" + TimeOut state. The possible error codes can be found in the <a title="SynapseConstant class" href="https://svn.apache.org/repos/asf/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/SynapseConstants.java"; id="or6m">SynapseConstant class</a> (under the endpoint failure section). The configuration section for this state called <b><i>markForSuspension</i></b>.If a previously defined error code is and if it does have a positive @@ -92,9 +145,9 @@ <div id="endpoint-state" style="text-align: left;"><img style="width: 648px; height: 267.568px;" alt="endpoint-state-image" src="images/endpoint-state.png"/></div> -<p>Figure1: The state transition between states in an endpoint</p> +<p>Figure1: The state transition between states in an endpoint</p> -<h4>Using jconsole to manage state transition between states</h4> +<h3 id="Jconsole">Using jconsole to manage state transition between states</h3> <p>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 @@ -133,23 +186,23 @@ <p>You'll also see a INFO level log message saying that the endpoint was switched off manually.</p> -<p><font style="font-family: Courier New;" size="3">[2009-06-23 12:18:21,149] INFO - EndpointContext Manually switching off endpoint : ep1</font></p> +<p><span style="font-family: serif;">[2009-06-23 12:18:21,149] INFO - EndpointContext Manually switching off endpoint : ep1</span></p> <p>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. </p> - + <div id="y.8h" style="text-align: left;"><img style="width: 648px; height: 336.767px;" alt="endpoint-switched-off-image" src="images/endpoint-turn-off.png"/></div> <p>Figure6: Endpoint is in Switch off state.</p> -<h3>Address Endpoint</h3> +<h2 id="AddressEp">Address Endpoint</h2> <p>Address endpoint is an endpoint defined by specifying the EPR (Endpoint Reference) and other attributes of the configuration.</p> -<h4>Address endpoint configuration</h4> +<h3 id="AddressEpConfig">Address endpoint configuration</h3> <pre xml:space="preserve"> <address uri="<i>endpoint address</i>" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] @@ -170,7 +223,7 @@ <retriesBeforeSuspension>m</retriesBeforeSuspension> <retryDelay>d</retryDelay> </markForSuspension> - + <suspendOnFailure> [<errorCodes>xxx,yyy</errorCodes>] <initialDuration>n</initialDuration> @@ -180,39 +233,39 @@ </address> </pre> -<h5>Address endpoint attributes</h5> -<div><table class="" id="grrh" border="1" cellpadding="3" cellspacing="0" +<h3 id="AddressEpAttr">Address endpoint attributes</h3> +<div><table id="grrh" border="1" cellpadding="3" cellspacing="0" width="1488"><tbody> - <tr><td width="50%">uri<br/></td><td width="50%">EPR of the target endpoint. + <tr><td>uri<br/></td><td>EPR of the target endpoint. See the table below for a possible list of transports.<br/></td></tr> - <tr><td width="50%">format<br/></td><td width="50%">Message format for the endpoint.<br/></td></tr> - <tr><td width="50%">optimize<br/></td><td width="50%">Method to optimize the attachments.<br/></td></tr> - <tr><td width="50%">encoding<br/></td><td width="50%">The charset encoding to use for the endpoint.<br/></td></tr> - <tr><td width="50%">statistics<br/></td><td width="50%">This enables statistics for the endpoint.<br/></td></tr> - <tr><td width="50%">trace<br/></td><td width="50%">This enables trace for the endpoint.<br/></td></tr> + <tr><td>format<br/></td><td>Message format for the endpoint.<br/></td></tr> + <tr><td>optimize<br/></td><td>Method to optimize the attachments.<br/></td></tr> + <tr><td>encoding<br/></td><td>The charset encoding to use for the endpoint.<br/></td></tr> + <tr><td>statistics<br/></td><td>This enables statistics for the endpoint.<br/></td></tr> + <tr><td>trace<br/></td><td>This enables trace for the endpoint.<br/></td></tr> </tbody></table></div> -<h5>QoS for the endpoint</h5> +<h3 id="QoSEp">QoS for the endpoint</h3> <p>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 <b>enableRM, enableSec</b> and <b>enableAddressing</b> elements. Optionally, the WS-RM and WS-Security policies could be specified using <i><b>policy</b></i> attribute. </p> -<h5>QoS configuration</h5> +<h3 id="QoSConfig">QoS configuration</h3> -<div><table class="" id="v1c." border="1" cellpadding="3" cellspacing="0" width="1490"> +<div><table id="v1c." border="1" cellpadding="3" cellspacing="0" width="1490"> <tbody> - <tr><td width="50%">enableRM [policy="<i>key</i>"]<br/></td><td width="50%">This enables WS-Reliable messaging + <tr><td>enableRM [policy="<i>key</i>"]<br/></td><td>This enables WS-Reliable messaging for the message which goes for the endpoint. The optional <i>policy</i> attribute specify the WS-RM policy.<br/></td></tr> - <tr><td width="50%">enableSec [policy="<i>key</i>"]<br/></td><td width="50%">This enables WS-Security for + <tr><td>enableSec [policy="<i>key</i>"]<br/></td><td>This enables WS-Security for the message which goes for the endpoint. The optional <i>policy</i> attribute specify the WS-Security policy.<br/></td></tr> - <tr><td width="50%">enableAddressing [version="final | submission"] [seperateListener=" true | false"]<br/> - </td><td width="50%">This enables WS-Addressing for the message which goes for the endpoint. User can specify + <tr><td>enableAddressing [version="final | submission"] [seperateListener=" true | false"]<br/> + </td><td>This enables WS-Addressing for the message which goes for the endpoint. User can specify to have seperate listener with version final or submission. <br/></td></tr> </tbody></table></div> -<h5>Endpoint timeout</h5> +<h3 id="EpTimeout">Endpoint timeout</h3> <p>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 @@ -222,34 +275,34 @@ to a millisecond duration below the desired endpoint timeout, <b>care must be taken as a lesser value may have a higher overhead on the system.</b></p> -<h5>timeout configuration</h5> -<div><table class="" id="cs2_" border="1" cellpadding="3" cellspacing="0" width="1493"> +<h3 id="TimeoutConfig">timeout configuration</h3> +<div><table id="cs2_" border="1" cellpadding="3" cellspacing="0" width="1493"> <tbody> - <tr><td width="50%">duration<br/></td><td width="50%">Timeout duration in second. <br/></td></tr> - <tr><td width="50%">action<br/></td><td width="50%">Once a timeout occurs the action to perform, avilable + <tr><td>duration<br/></td><td>Timeout duration in second. <br/></td></tr> + <tr><td>action<br/></td><td>Once a timeout occurs the action to perform, avilable options are <i>discard</i> (discard the response which arrives late) or <i>fault</i> (trigger a fault) .<br/></td></tr> </tbody></table></div> -<h5>Marking endpoint for suspension</h5> +<h3 id="MarkSuspension">Marking endpoint for suspension</h3> <p>As described before (see description on Timeout state above) this configuration element describes the configuration for a timeout endpoint. </p> -<h5>markForSuspension configuration</h5> -<div><table class="" id="aliw" border="1" cellpadding="3" cellspacing="0" width="1496"> - <tbody><tr><td width="50%">errorCodes<br/></td><td width="50%">A comma separated error code list which can be - returned by the endpoint. See <a title="SynpaseConstant" target="_blank" +<h3 id="SuspensionConfig">markForSuspension configuration</h3> +<div><table id="aliw" border="1" cellpadding="3" cellspacing="0" width="1496"> + <tbody><tr><td>errorCodes<br/></td><td>A comma separated error code list which can be + returned by the endpoint. See <a title="SynpaseConstant" href="https://svn.apache.org/repos/asf/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/SynapseConstants.java"; >SynpaseConstant</a> class for a possible list of error codes. <br/></td></tr> <tr><td>retriesBeforeSuspension</td><td>Number of retries before go into suspended state.<br/></td></tr> - <tr><td>retryDelay</td><td><font size="3">The delay between each try.<br/></font></td></tr> + <tr><td>retryDelay</td><td>The delay between each try.</td></tr> </tbody></table></div> -<h5>Suspending endpoint on failure</h5> +<h3 id="SuspendingEp">Suspending endpoint on failure</h3> <p>Address (and also 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 a - <a title="geometric series" target="_blank" href="http://en.wikipedia.org/wiki/Geometric_series"; id="r-md">geometric series.</a> + <a title="geometric series" href="http://en.wikipedia.org/wiki/Geometric_series"; id="r-md">geometric series.</a> <br/> Ex: Suppose T<sub>1</sub>, T<sub>2</sub>, T<sub>3</sub>....T<sub>n</sub> are suspended duration before next attempt. The T<sub>1</sub>, T<sub>2</sub>, T<sub>3</sub>...T<sub>n</sub> can be defined as follows:<br/> @@ -266,84 +319,84 @@ <br/> </p> -<h5>suspendOnFailure configuration</h5> +<h3 id="SuspendOnFailureConfig">suspendOnFailure configuration</h3> <div> -<table class="" id="ieu9" border="1" cellpadding="3" cellspacing="0" width="1499"> +<table id="ieu9" border="1" cellpadding="3" cellspacing="0" width="1499"> <tbody> <tr> -<td width="50%">errorCode<br/> +<td>errorCode<br/> </td> -<td width="50%">A comma separated error code list which can be returned by the endpoint. See <a title="SynpaseConstant" target="_blank" +<td>A comma separated error code list which can be returned by the endpoint. See <a title="SynpaseConstant" href="https://svn.apache.org/repos/asf/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/SynapseConstants.java"; >SynpaseConstant</a> class for a possible list of error codes. <br/> </td> </tr> <tr> -<td width="50%"> +<td> initialDuration </td> -<td width="50%">Initial duration to suspend the endpoint.<br/> +<td>Initial duration to suspend the endpoint.<br/> </td> </tr> <tr> -<td width="50%"> +<td> progressionFactor </td> -<td width="50%">The progression factor for the geometric series. See above for a more detailed description.<br/> +<td>The progression factor for the geometric series. See above for a more detailed description.<br/> </td> </tr> <tr> -<td width="50%"> +<td> maximumDuration </td> -<td width="50%">Maximum duration to suspend the endpoint. <br/> +<td>Maximum duration to suspend the endpoint. <br/> </td> </tr> </tbody> </table> </div> -<h5>Following are the sample address URI definitions. </h5> +<h3 id="SampleAddressURI">Following are the sample address URI definitions.</h3> <div> -<table class="" id="aq95" border="1" cellpadding="3" cellspacing="0" width="1495"> +<table id="aq95" border="1" cellpadding="3" cellspacing="0" width="1495"> <tbody> <tr> -<td width="50%">Transport<br/> +<td>Transport<br/> </td> -<td width="50%">Sample Address<br/> +<td>Sample Address<br/> </td> </tr> <tr> -<td width="50%">HTTP<br/> +<td>HTTP<br/> </td> -<td width="50%">http://localhost:9000/services/SimpleStockQuoteService</td> +<td>http://localhost:9000/services/SimpleStockQuoteService</td> </tr> <tr> -<td width="50%">JMS<br/> +<td>JMS<br/> </td> -<td width="50%">jms:/SimpleStockQuoteService?<br/> +<td>jms:/SimpleStockQuoteService?<br/> transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&<br/> java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&<br/> java.naming.provider.url=tcp://localhost:61616&<br/> transport.jms.DestinationType=topic</td> </tr> <tr> -<td width="50%">Mail<br/> +<td>Mail<br/> </td> -<td width="50%">mailto:gu...@host</td> +<td>mailto:gu...@host</td> </tr> <tr> -<td width="50%">VFS<br/> +<td>VFS<br/> </td> -<td width="50%">vfs:file:///home/user/directory<br/> +<td>vfs:file:///home/user/directory<br/> vfs:file:///home/user/file<br/> vfs:ftp://guest:gu...@localhost/directory?vfs.passive=true </td> </tr> <tr> -<td width="50%">FIX<br/> +<td>FIX<br/> </td> -<td width="50%">fix://host:port?BeginString=FIX4.4&SenderCompID=WSO2&TargetCompID=APACHE<br/> +<td>fix://host:port?BeginString=FIX4.4&SenderCompID=WSO2&TargetCompID=APACHE<br/> <br/> </td> </tr> @@ -351,7 +404,7 @@ </table> </div> -<h3>Default Endpoint</h3> +<h2 id="DefaultEp">Default Endpoint</h2> <p>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 @@ -359,7 +412,7 @@ 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.</p> -<h4>Default endpoint configuration</h4> +<h3 id="DefaultEpConfig">Default endpoint configuration</h3> <pre xml:space="preserve"> <default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] [encoding="<i>charset encoding</i>"] @@ -389,14 +442,14 @@ </default> </pre> -<h3>WSDL endpoint</h3> +<h2 id="WsdlEp">WSDL endpoint</h2> <p>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.</p> -<h4>WSDL endpoint configuration</h4> +<h3 id="WsdlEpConfig">WSDL endpoint configuration</h3> <pre xml:space="preserve"> <wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname"> <wsdl:definition>...</wsdl:definition>? @@ -425,7 +478,7 @@ </wsdl> </pre> -<h3>Load balance Endpoint</h3> +<h2 id="LbEp">Load balance Endpoint</h2> <p>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 @@ -454,7 +507,7 @@ affinity based load balance endpoints, list failover endpoints as the target endpoints. </p> -<h4>Load balance endpoint configuration</h4> +<h3 id="LbEpConfig">Load balance endpoint configuration</h3> <pre xml:space="preserve"> <session type="http|simpleClientSession"/>? <loadBalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"] @@ -465,7 +518,7 @@ </pre> -<h3>Failover Endpoint</h3> +<h2 id="FoEp">Failover Endpoint</h2> <p>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, @@ -473,14 +526,14 @@ Thus it sends messages successfully as long as there is at least one active endpoint among the listed endpoints.</p> -<h4>Failover endpoint configuration</h4> +<h3 id="FoEpConfig">Failover endpoint configuration</h3> <pre xml:space="preserve"> <failover> <endpoint .../>+ </failover> </pre> -<h3>Dynamic Load balance Endpoint</h3> +<h2 id="DlbEp">Dynamic Load balance Endpoint</h2> <p>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 @@ -490,17 +543,14 @@ 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.</p> -<h4>Dynamic Load balance endpoint configuration</h4> +<h3 id="DlbEpConfig">Dynamic Load balance endpoint configuration</h3> <pre xml:space="preserve"> -<dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]> - <membershipHandler - class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler"> - <property name="name" value="value"/> + <dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]> + <membershipHandler class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler"> + <property name="name" value="value"/> </membershipHandler> -</dynamicLoadBalance> + </dynamicLoadBalance> </pre> - - </body> </html> \ No newline at end of file _______________________________________________ Esb-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/esb-java-dev
