Endpoint or Destination Fragment

Endpoints (destinations) are the configuration describing an external EPR that can be used to send messages from UltraESB. The endpoint configuration also defines the qualities and properties of an EPR. While this section concentrates on the configuration aspect of the endpoints, for advance endpoint configurations, it is good/recommended to cover the concepts from Understanding Endpoints or Destinations under the Architecture and Design of UltraESB.

Endpoint Configuration

There is a slight difference in defining a reusable endpoint on the configuration and defining an endpoint in-line in a proxy service, either as it’s in destination or out destination. The difference is mainly in the root element tag name. If you are defining a reusable endpoint the tag name to be used is "endpoint" while the same changes to "inDestination" if you in-line it as an in destination of a proxy service, or to "outDestination" if you in-line it as an out destination of a proxy service. Except for that the configuration should be identical whether you in-line it or defined as a reusable endpoint.

To add a reusable endpoint into the configuration open up the "ultra-unit.xml" file of the deployment unit that you want to add this endpoint, in your IDE and start to insert an XML element with the angular bracket ("<"), upon which the IDE will pop you up the following options.

endpoint add

Select the "u:endpoint" as shown above and hit enter to add an endpoint. The endpoint with a bare configuration will be added as follows;

Starting the reusable endpoint configuration

<u:endpoint id="">
  <u:address></u:address>
</u:endpoint>

Note the automatic addition of the mandatory "id" attribute, which is the identifier of the endpoint you can use as the value for either an inDestination attribute or outDestination attribute of the target element of a proxy service. Apart from that it automatically adds a child element with the element tag name "address", again qualified with the UltraESB namespace.

Identifier for a reusable endpoint must be given and lets use the "MyFirstEndpoint" identifier for that matter. The next thing is the selection of the endpoint type, which is specified as an attribute to the endpoint element. Having the idea of adding this attribute press space at the end of the id attribute declaration within the endpoint element, where you will be able to see the following options.

ep attributes

While we will discuss the "keepalive" and "timeout" attributes under the Advance Configurations of endpoints, our intention here is to define the endpoint type. Select the "type" attribute to define the endpoint type.

Giving an endpoint an identifier

<u:endpoint id="MyFirstEndpoint" type="">
  <u:address></u:address>
</u:endpoint>

Endpoint Types

There are 8 types of endpoints in UltraESB categorized according to the behaviour of the endpoint. To select the exact type you want you might want to go through the concepts behind each and every type of the endpoint described under the Architecture and Design.

Coming back to configuration, you can select the value for the type attribute added previously to configure different endpoint types. The IDE will help us figure out the configuration for our type attribute value, if you press Ctrl+Space while the cursor is in between the (") double quote characters to define the attribute value.

ep types

Select the type that you desire and configure the rest according to the type you have selected as described below under relevant type configuration.

Single Endpoints

Single endpoint as it’s name depicts can have exactly one address as its address. Refer to single endpoint concepts for more information on it.

Configuration of the single endpoint requires the endpoint type attribute to be set to "single" and it should include an address of any valid address type as follows.

Single address endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="single">
  <u:address>http://localhost:9000/service/EchoService</u:address>
</u:endpoint>

Single endpoints are treated as the default endpoint type, so any endpoint without the type attribute is also treated as a single endpoint.

Default endpoint type
Single endpoint is the default endpoint type and hence the type declaration for single endpoints are optional.
Round-Robin Endpoints

Round-robin endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to the defined addresses in a round robin fashion balancing the load yet without doing fail-over. Refer to round-robin endpoint concepts for more information.

Configuration of the round-robin endpoint requires the endpoint type attribute to be set to "round-robin" and it should include a set of addresses of any valid address type as follows.

Round-Robin load balance endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="round-robin">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:address>http://localhost:9002/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Fail-over Endpoints

Fail-over endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to the first endpoint among the defined addresses, and if it fails tries the next defined address providing failover. Refer to failover endpoint concepts for more information.

Configuration of the fail-over endpoint requires the endpoint type attribute to be set to "fail-over" and it should include a set of addresses of any valid address type as follows.

Failover endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:address>http://localhost:9002/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Round-Robin with Fail-over Endpoints

Round-robin with fail-over endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to the defined addresses in a round-robin fashion while providing fail-over, capability, i.e. if an address fails endpoint tries the next available address to send the message. Refer to round-robin with fail-over endpoint concepts for more information.

Configuration of the round-robin with fail-over endpoint requires the endpoint type attribute to be set to "round-robin-with-fail-over" and it should include a set of addresses of any valid address type as follows.

Round-Robin load balance with failover endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="round-robin-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:address>http://localhost:9002/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Weighted Endpoints

Weighted endpoint should have more than one address with a weight associated with each and every address and there is no upper bound to the number of addresses. It deliver messages to the addresses defined considering the weight associated with those addresses balancing the load according to the assigned weight yet without doing fail-over. Refer to weighted endpoint concepts for more information.

Configuration of the weighted endpoint requires the endpoint type attribute to be set to "weighted" and it should include a set of addresses of any valid address type as follows.

Weighted load balance endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="weighted">
  <u:address weight="1">http://localhost:9000/service/EchoService</u:address>
  <u:address weight="1">http://localhost:9001/service/EchoService</u:address>
  <u:address weight="2">http://localhost:9002/service/EchoService</u:address>
  <u:address weight="4">http://localhost:9003/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service. Note the "weight" attribute and the integer value assigned as the weight in all addresses.

Weighted with Fail-over Endpoints

Weighted with fail-over endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to the defined addresses according to the weight assigned to each and every address while providing fail-over, capability, i.e. if an address fails endpoint tries the next available address to send the message. Refer to weighted with fail-over endpoint concepts for more information.

Configuration of the weighted with fail-over endpoint requires the endpoint type attribute to be set to "weighted-with-fail-over" and it should include a set of addresses of any valid address type as follows.

Weighted load balance with failover endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="weighted-with-fail-over">
  <u:address weight="1">http://localhost:9000/service/EchoService</u:address>
  <u:address weight="1">http://localhost:9001/service/EchoService</u:address>
  <u:address weight="2">http://localhost:9002/service/EchoService</u:address>
  <u:address weight="4">http://localhost:9003/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Random Endpoints

Random endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to to an address selected randomly among the defined addresses balancing the load according to probability of getting selected yet without doing fail-over. Refer to random endpoint concepts for more information.

Configuration of the random endpoint requires the endpoint type attribute to be set to "random" and it should include a set of addresses of any valid address type as follows.

Random load balance endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="random">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:address>http://localhost:9002/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Random with Fail-over Endpoints

Random with fail-over endpoint should have more than one address and there is no upper bound to the number of addresses. It deliver messages to an address selected randomly among the set of defined addresses while providing fail-over, capability, i.e. if a selected address fails endpoint tries the next selected address to send the message. Refer to random with fail-over endpoint concepts for more information.

Configuration of the random with fail-over endpoint requires the endpoint type attribute to be set to "random-with-fail-over" and it should include a set of addresses of any valid address type as follows.

Random load balance with failover endpoint configuration

<u:endpoint id="MyFirstEndpoint" type="random-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:address>http://localhost:9002/service/EchoService</u:address>
</u:endpoint>

In general all the addresses refer to the same replicated service.

Address Configuration

Addresses within an endpoint describes the actual destination or the EPR of an endpoint. Possible configurations for addresses are the address type configuration, address identifier and the weight, which only applies to weighted endpoint addresses.

All these are configured as attributes of the address element, while for some address types the address value is defined in the address element body as text. In order to see the options available for address configuration type space within the address element at the end of the address tag name.

address options

Address identifier is configured with the "id" attribute and the value of this attribute can be any string except for the illegal characters in XML. While the "weight" attribute only applies to weighted endpoint types, the type attribute is discussed as the next section in-detail.

Address Types

There are 4 types of addresses categorized according to the way they are configured. To configure the address type the attribute "type" needs to be added to the address element and the respective type value has to be specified as the attribute value.

To see the valid options for the address types, type Ctrl+Space within the double quotes ("), where you will be able to see the following pop-up value set.\

address types
URL Address

This type of addresses are the most common address type and hence is the default address type. To configure an URL address you just need to specify the complete URL of the service to which this endpoint address refers to, as follows. For more information refer to the URL address concepts.

URL (optional) type address configuration

<u:address type="url">http://localhost:9000/service/EchoService</u:address>

Since this type of addresses are the default type if no type is defined the address is considered as URL type.

Default address type
It is optional to specify the type attribute and the attribute for URL type addresses, and hence you can just neglect the type for any URL address
Prefix Address

This type of addresses are mostly used in load balancing and fail-over endpoints to change the prefix of the endpoint address while appending the rest of the URL to the specified new prefix. To configure an prefix address you need to specify the prefix of the address as follows. For more information refer to the prefix address concepts.

Prefix type address configuration

<u:address type="prefix">http://localhost:9000/service</u:address>
Default Address

This type of address is used to send the messages to the endpoint implicitly defined in the message itself, and hence no address value is given in configuring the endpoint. To configure a default type endpoint you just need to specify the endpoint type and the address extraction from the message will be done by the engine. For more information refer to the default endpoint concepts.

Default type address configuration

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

This type of addresses are used to send the messages back to the caller as a response, and hence no address value is given in configuring the endpoint. To configure a response type endpoint you just need to specify the endpoint type and the address caller selection from the message will be done by the engine. For more information refer to the response endpoint concepts.

Response type address configuration

<u:address type="response"/>
Echo Address

This types of addresses will inject the message to the next processing components without sending it to an actual endpoint. This will be useful when user want to inject message from in-sequence to out-sequence without sending it to an actual end point. To configure a echo type endpoint you just need to specify the endpoint type and the address caller selection from the message will be done by the engine.

Echo address type should not be used in out-sequence.

Echo type address configuration

<u:address type="echo"/>

Error Handing Configuration

Endpoint error handling configuration is a unified across all the endpoint types. Endpoint error handling is designed around the error codes that the engine reports on a failure of an address specified in the endpoint. By analyzing the error code received from the failure the endpoint takes the error handling decisions under 3 categories all configured as child elements of the endpoint element.

Safe to Retry Configuration

On a failure of an endpoint address, it could retry the same message to a different address on the same endpoint if the fail-over is turned on. But for certain failures you might not want to re-try the same message, as it could lead to duplication of messages to the back-end, while some errors are obvious that you can safely retry (for example a connect time out meaning that the ESB failed to establish the connection to the back end). In mission critical systems, it is wise to be able to configure the failure cases which are safe to retry.

All failures in UltraESB are associated with a unique error code and hence this decision to retry or not to retry, is being done by looking at the error code. While you can find the default behaviour and more information on this under fail-over concepts, you also can configure the error codes which are safe to retry, overriding the defaults.

For that matter the configuration would need to add an element with the tag name "safeToRetryErrorCodes" as follows;

Safe to retry configuration of endpoints

<u:endpoint id="MyFirstEndpoint" type="round-robin-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:safeToRetryErrorCodes>all</u:safeToRetryErrorCodes>
</u:endpoint>

While the above configuration specifies all error codes are safe to re-try, as opposed to the default behaviour, you can configure a sub set of error codes by listing the error codes as a comma separated value set.

Temporary Failure Configuration

Temporary failures are the failures that mark the address as temporarily failed and the endpoint is still available within the given grace period. These temporary failures are detected again based on the error codes and you can find the information on default temporary failure error codes and more information on temporary and suspension failure in the endpoint error handling concepts.

Configuring the temporary failures require an addition of "temporaryFailures" element into the endpoint element, and configuring the grace period and the error codes for marking the address as temporary failed with the child elements "gracePeriod" and "errorCodes" respectively.

Temporary failures configuration of endpoint

<u:endpoint id="MyFirstEndpoint" type="round-robin-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:safeToRetryErrorCodes>all</u:safeToRetryErrorCodes>
  <u:temporaryFailures>
    <u:gracePeriod>3000</u:gracePeriod>
    <u:errorCodes>101508,101506,101505,101504</u:errorCodes>
  </u:temporaryFailures>
</u:endpoint>

Here a subset of the default error codes are specified as the temporary failure error codes.

Suspend on Failure Configuration

Suspension failures are the failures that mark the address as suspended and the address wont be available for the duration in-effect. These suspension failures are also detected based on the error codes and you can find the information on default suspension failure error codes and more information on temporary and suspension failure in the endpoint error handling concepts.

Configuring the suspension on failure require an addition of "suspendOnFailure" element into the endpoint element, and configuring the initial duration, progression factor and the maximum duration with the error code under child elements with names "initialDuration","progressionFactor","maximumDuration" and "errorCodes" respectively.

Suspend on failure configuration of endpoint

<u:endpoint id="MyFirstEndpoint" type="round-robin-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:safeToRetryErrorCodes>all</u:safeToRetryErrorCodes>
  <u:temporaryFailures>
    <u:gracePeriod>3000</u:gracePeriod>
    <u:errorCodes>101508,101506,101505,101504</u:errorCodes>
  </u:temporaryFailures>
  <u:suspendOnFailure>
    <u:initialDuration>4000</u:initialDuration>
    <u:progressionFactor>1.0</u:progressionFactor>
    <u:maximumDuration>10000</u:maximumDuration>
    <u:errorCodes>101503,101511</u:errorCodes>
  </u:suspendOnFailure>
</u:endpoint>

The duration for which the endpoint is suspended is described with the initial duration (which is the duration for the first suspension), progression factor (which is the factor in which the duration gets increased on consecutive suspension failures after being ready for use) and maximum duration (which is the maximum duration for which the endpoint be suspended).

Advance Endpoint Options

Apart from that, there are few advance options which enables few advance configurations of endpoints and addresses.

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.

Keepalive
Timeout
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, as described in the concept of response validation. Configuring the response validator is being done as a property configuration for the endpoint. Further the response validator instance should be initialized with spring and that bean identifier is user to configure the response validator.

To configure the response validator, add a property with the key "ultra.endpoint.response_validator_bean" and the value being the spring bean identifier of the actual validator instance.

Response validaor configuration of endpoint

<u:endpoint id="MyFirstEndpoint" type="round-robin-with-fail-over">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:address>http://localhost:9001/service/EchoService</u:address>
  <u:property name="ultra.endpoint.response_validator_bean" value="soapValidator"/>
</u:endpoint>

<bean id="soapValidator" class="org.adroitlogic.ultraesb.core.endpoint.SOAPResponseValidator">
  <property name="failOnFaultText" value="Service not available"/>
</bean>
HTTP Location header switching of response

Some responses from the back-end services contain the HTTP Location header in which case the ESB might want to intercept the message and re-write the Location header value, as described in concept of HTTP Location switching. This again is configured as an endpoint property.

To configure the HTTP Location switching, add a property with the key "ultra.endpoint.switch_location_headers_to" with the value of the Location header that you want to switch to.

HTTP location header switching configuration of endpoint

<u:endpoint id="MyFirstEndpoint">
  <u:address>http://localhost:9000/service/EchoService</u:address>
  <u:property name="ultra.endpoint.switch_location_headers_to" value="http://localhost:8280/service/rest-proxy"/>
</u:endpoint>
Note
Completing the endpoint configuration, once again to emphasis on the in-lined endpoints in the proxy services, all the above configurations endpoint tag name has to be replaced with either "inDestination" or "outDestination" depending on the in-lined destination type.
In this topic
In this topic
Contact Us