Endpoints, Destinations and Addresses

An Endpoint describes an external destination for a message sent out from the ESB. Most commonly, a proxy service will perform some mediation on an incoming message (e.g. log, transform etc) and then send it out to an external service endpoint or destination. Note that both 'Endpoint' and 'Destination' refer to the same concept. Since the most common use case on an ESB always defines an Endpoint for an incoming message accepted by a proxy, we allow one to easily specify this via the 'inDestination' (instead of calling this the 'inEndpoint'). Similarly for an outgoing message through a proxy, we allow the user to define an 'outDestination' - which for HTTP/S style transports most often is the response channel back to the synchronous client which made the original request.

Address Types

An Endpoint/Destination defines one or more ’Address’es depending on the type of endpoint. An Address type could be one of the following:

  • URL - sends the message to the specified absolute URL

  • Prefix - sends the message to the absolute URL made up by adding the 'prefix' to the part already specified on the message

  • Default - sends the message to the destination already specified on the message

  • Response - sends the message as a response to the original client for HTTP/S style transports

URL based Addresses

URL based addresses are the most common type of addresses across many transports, and hence the default type if another type is not specified. Some examples follows.

<u:address>http://localhost:9000/service/EchoService</u:address>
<u:address>jms:/Q.jmsPending</u:address>
<u:address>file:///tmp/AS2/received</u:address>
<u:address>mailto:fwd@localhost</u:address>
Prefix based Addresses

Prefix based addresses are most common when the absolute destination for a message depends on some URL prefix + a trailing section of the incoming URL (or another custom assigned URL postfix). Refer to the 'rest-proxy' of the ESB sample #101 (line 42), where an incoming request to a URL '/service/rest-proxy/customer/details?name=john' for example, needs to be sent to 'http://localhost:9000/rest-services/customer/details?name=john' - where the highlighted prefix is static, and the postfix is dynamically looked up from the message. A prefix endpoint must declare its 'type' as follows:

<u:address type="prefix">http://localhost:9000/rest-services</u:address>
Default Address

Sometimes the destination address may not be static, or have a common prefix at all times. An example is if the destination address is picked up from a database, registry or even another service etc. In such cases, the destination address must be first set to the message via the Message.setDestinationURL() API call. Refer to the ESB sample #502 (line 126) for an example, where the destination Email address is being set during the mediation and then using a 'response' endpoint to send it.

<u:address type="default"/>
Response Address

The 'response' address is a special address for HTTP/S style interactions, where a message should be sent as a synchronous response to an incoming request message. Although the response may actually be sent asynchronously, to the HTTP/S style client making a request to the ESB, the response will appear as a synchronous response on the same TCP socket. An example definition follows:

<u:address type="response"/>

Endpoint Types

Endpoints will belong to one of the following types, as specified by the 'type' attribute.

Single Endpoints
ep single

A 'single' endpoint specifies exactly one single address. Hence this single address is never suspended from use - as it would be always better to try to use the only known address when no other choices exist. Any error while sending to the address is handed to the immediate error handler.

Round-Robin Endpoints without Fail-Over
ep rr wo fo

A Round-Robin endpoint without fail-over cycles through the available addresses for each new message. Whenever an error occurs the message is handed to the immediate error handler, without a fail-over to another address within the group.

Round-Robin Endpoints with Fail-Over
ep rr fo

A Round-Robin endpoint with fail-over cycles through the available addresses for each new message. Whenever an error occurs the message is retried by the next available address. If all addresses fail to deliver the message it is handed to the immediate error handler. See Fail-Over behavior.

Fail-Over only Endpoint
ep fo

A Fail-Over only endpoint will always try the first address to send a message - failing with the next address is attempted etc. Whenever an error occurs the message is handed over to the immediate error handler. This maybe used for Active-Passive service invocations, where the passive address will only be used if the active address fails. See Fail-Over behavior.

Weighted Endpoint without Fail-Over
ep weighted wo fo

A weighted endpoint without fail-over will use the available addresses at random, but ensuring the frequency of use of a particular address to be in relationship to its weight. Hence an address with a weight 2w is twice as likely to be used as an address with a weight of just w. Whenever an error occurs the message is handed over to the immediate error handler. If any of the addresses are suspended due to serious suspension errors or continued transient errors, the new weights are re-calculated from among the remaining addresses. See Fail-Over behavior.

Weighted Endpoint with Fail-Over
ep weighted fo

A weighted endpoint with fail-over will use the available addresses at random, but ensuring the frequency of use of a particular address to be in relationship to its weight. Hence an address with a weight 2w is twice as likely to be used as an address with a weight of just w. Whenever an error occurs the message is retried again with another address from the endpoint, and if all addresses are exhausted, it is handed over to the immediate error handler. If any of the addresses are suspended due to serious suspension errors or continued transient errors, the new weights are re-calculated from among the remaining addresses. See Fail-Over behavior.

Random Endpoint without Fail-Over
ep random wo fo

A random endpoint without fail-over will use the available addresses at random. Whenever an error occurs the message is handed over to the immediate error handler. See Fail-Over behavior.

Random Endpoint with Fail-Over
ep random fo

A random endpoint with fail-over will use the available addresses at random. Whenever an error occurs the message is retried again with another address from the endpoint, and if all addresses are exhausted, it is handed over to the immediate error handler. See Fail-Over behavior.

Endpoint Error Handling

endpoint failover

Irrespective of the fail-over behavior, an endpoint will mark failures encountered by addresses as temporary failures or suspension failures depending on the error code raised. By default, the temporary error indication codes are:

  • 101508 - Sender connect timeout (TCP level connection establishment failure within specified (default 10) number of seconds

  • 101504 - Sender connection timeout (expiration of the specified, or default connection timeout from the ESB side sender waiting for a response from the remote party)

  • 101512 - Sender connect timeout (submitting the request to a remote party)

  • 101500 - Sender IO error during sending

  • 101501 - Sender IO error during receiving

  • 101506 - Sender detection of a HTTP/S protocol violation during send

  • 101505 - Sender detection of a connection close by remote party during receive

  • 101513 - Sender detection of a connection close by remote party during send

  • 101510 - Rejection by response validator as a temporary error

  • 101006 - Listener detection that a response cannot be submitted (e.g. Connection already closed)

  • 101000 - Listener side IO error during send

  • 101001 - Listener side IO error in receiving a message from a client

  • 101003 - Listener connection timeout (expiration of the specified, or default connection timeout from the ESB side listener)

  • 101005 - Listener detection of a connection close by remote party

The default suspension error codes are:

  • 101503 - Connect failed (connection refused by remote party over the specified port)

  • 101511 - Rejection by response validator as a suspension error

On a suspension error, the address is immediately placed into 'Suspended' mode, and will not be considered as a candidate for future messages until its suspension rules indicate that it could be retried.

address state chart

An address transitions from the Ready state to the 'Temporary Failure' state on encountering a temporary error indication code, and to the 'Suspended' state on encountering a suspension error code. From the time it enters the 'Temporary Failure' state, the specified 'gracePeriod' counter will begin. An address in the 'Temporary Failure' state will be used for subsequent messages, and any subsequent temporary failures will keep it in the same state, while a successful send move it back to the 'Ready' state. If an address surpasses the 'gracePeriod' in the temporary failure state, it will be moved to the 'Suspended' state.

When an address is suspended, a suspend duration is computed, until which time the address will be ignored from use. The suspension duration is calculated as a Geometric series as follows. A 'progressionFactor' of 2 would yield an exponential series. The first time an address is suspended, the 'initialDuration' will be used, while on subsequent suspensions, the value will be limited upto the 'maximumDuration'

  • Current Duration = Last Duration == null ? Initial Duration : max( (Last Duration * Progression Factor), Maximum Duration)

After expiry of the suspend duration, an address becomes ready for a retry. If the retry is successful, the address moves to the 'Ready' state, and if not, the next suspension duration is calculated as per the parameters, and the address is re-suspended.

Fail-Over behavior

When an address fails to deliver a message, an error is raised internally with an error code indicating the problem. The default behavior is to only retry messages where it is guaranteed that a call to the next address would be safe. For example, if the first address returns a connect timeout (i.e. a TCP connection could not be established within a specified delay - error code 101508) or a connection refused (i.e. the endpoint explicitly refusing a connection - error code 101503) it will always be safe to retry as the message has clearly not been accepted by any of the backend service addresses. Other error codes such as a connection timeout, connection close, IO error or protocol violation etc is considered unsafe for retry by default.

An endpoint fail-over takes place only if the error code raised is configured as a 'safeToRetryErrorCode' of the endpoint. The default safe codes are the following, however the configuration could define a special value 'all' to indicate that any error code maybe considered as safe for a retry (e.g. for idempotent service calls)

  • 101508 - Sender connect timeout (TCP level connection establishment failure within specified (default 10) number of seconds

  • 101503 - Connect failed (connection refused by remote party over the specified port)

  • 101510 - Rejection by response validator as a temporary error

Advanced Endpoint Configurations

Endpoints allow custom properties to be configured at the endpoint level. Some of these properties may be only valid for some types of messages. For example, HTTP authentication properties, email properties (e.g. subject) etc maybe specified at an endpoint level.

Response Validation

Response validation allows a successfully received message be validated to check if it indicates a successful response, a temporary error or a suspension error. An example is a Hessian fault which is transported as a HTTP 200 level (i.e. successful) response. In addition, sometimes application servers (e.g. Tomcat) may return an HTML error page saying a service is not available etc which is hidden at the transport layer. The sample response validator SOAPResponseValidator is able to indicate certain HTTP error codes for retry, and fail on encountering some static text as the SOAP fault. See ESB sample #601 for an example.

<u:property name="ultra.endpoint.response_validator_bean" value="soapValidator"/>
Switch HTTP Location headers of responses

Usually when proxying REST calls, the responses from a backend service may include HTTP 'Location' headers which may point the end client back to it, instead of the Proxy service fronting it. The location headers maybe switched to the proxy service prefix using this property. See ESB example # 101 for an example

<u:property name="ultra.endpoint.switch_location_headers_to" value="http://localhost:8280/service/rest-proxy"/>
In this topic
In this topic
Contact Us