Endpoints¶
Introduction¶
A message exit point or an endpoint defines an external destination for a message. Typically, this is the address of a proxy service that acts as the front end to the actual service. You can configure the endpoint artifacts with any attributes or semantics needed for communicating with that service. An endpoint could represent a URL, a mailbox, a JMS queue, a TCP socket, etc. along with the settings needed for the connection.
For example, the endpoint for the simple stock quote sample is http://localhost:9000/services/SimpleStockQuoteService.
Endpoints are independant of transports, which allows you to use the same endpoint with multiple transports. When you configure a message mediation sequence or a proxy service to handle the incoming message, you can specify which transport to use and the endpoint to which the message is sent.
Classification of Endpoints¶
Named Endpoints¶
A named endpoint can be any one of the listed endpoints. You can reuse these endpoints by referencing them in another endpoint by name using the key attribute. For example, if you have an address endpoint named foo, you can reference the foo endpoint in an indirect using the key attribute: <endpoint key="foo">
Indirect Endpoints¶
Indirect endpoints are endpoint configurations that refer named endpoints using a key. The key attribute calls the named endpoint at runtime and delegates the message sending to the called endpoint.
<endpoint name="address">
<address uri="http://localhost:9000/services/SimpleStockQuoteService" format="soap11"/>
</endpoint><endpoint key="address">Indirect endpoints are useful when the actual endpoints are stored in the registry.
Resolving Endpoints¶
The resolving endpoint refers to an actual endpoint using a dynamic key (which is an XPath expression). The XPath expression dynamically calls another endpoint at runtime. The XPath is evaluated against the current message and the key-expression is calculated at runtime. The resolving endpoint then fetches the actual endpoint using the calculated key and delegates the message sending to the actual endpoint. Shown below is an example of a resolving endpoint.
<send>
<endpoint key-expression="get-property('Mail')"/>
</send>List of Endpoints¶
You can configure the following endpoint types.
| Endpoint | Description |
|---|---|
| Address Endpoint | Specifies the address URL or EPR (Endpoint Reference) and other attributes of the configuration. |
| Default Endpoint | Defined for adding QoS and other configurations to the endpoint that is resolved by the To address of the message context. All the configurations such as the message format for the endpoint, the method to optimize attachments, and security policies for the endpoint can be specified as in the Address Endpoint. This endpoint differs from the address endpoint because the URI property is not present in the default endpoint. |
| HTTP Endpoint |
Allows you to define REST endpoints using URI templates similar to the REST API. The URI templates allow a RESTful URI to contain variables that can be populated during mediation runtime using property values with the uri.var. prefix. An HTTP endpoint can also define the particular HTTP method to use in the RESTful invocation.
|
| Failover Endpoint | If an error occurs in an endpoint during message transmission, the message will be lost. The failed message will not be retried again. With some applications, these message losses are acceptable. However, if even rare message failures are not acceptable, use the Failover endpoint. A Failover Group is a list of leaf endpoints grouped together for the purpose of passing an incoming message from one to another when a failover occurs. The first endpoint in the failover group is considered the primary endpoint. An incoming message is first directed to the primary endpoint, and all other endpoints in the group serve as backups. If the primary endpoint fails, the next active endpoint is selected as the primary endpoint, and the failed endpoint is marked as inactive. Thus, failover group ensures that a message is delivered as long as there is at least one active endpoint among the listed endpoints. The Micro Integrator switches back to the primary endpoint as soon as it becomes available. This behaviour is known as dynamic failover. Note: An endpoint failure occurs when an endpoint is unable to invoke a service. An endpoint, which responds with an error is not considered a failed endpoint. |
| Dynamic Load-Balance Endpoint | This endpoint distributes its messages (load) among application members by evaluating the load-balancing policy and any other relevant parameters. These application members will be discovered using the membershipHandler class, which generally uses 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. You can specify membershipHandler properties using the property elements. The policy attribute of the dynamicLoadbalance element specifies the load-balancing policy (algorithm) to be used for selecting the next member that will receive the message. Note: 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. |
| Template Endpoint | Template endpoints are created based on predefined Endpoint Templates. Parameters of the endpoint template used as the target are copied to the endpoint configuration. However, you can make modifications by removing some of the copied parameters and/or adding new parameters. |
| WSDL Endpoint |
This definition is based on a specified WSDL document. The WSDL document can be specified in 2 ways:
|
| Recepient List Endpoint | This endpoint contains multiple child endpoints or member elements. It routes cloned copies of messages to each child recipient. This will assume that all immediate child endpoints are identical in state (state is replicated) or state is not maintained at those endpoints. |
Properties¶
See the topics given below for the list of properties that can be configured for an Endpoint artifact.
Basic Properties¶
Listed below are the basic properties that used to define an endpoint aritfact.
| Property | Description |
|---|---|
| Name | The name of the endpoint property. |
| Format |
The message format for the endpoint. The available values are as follows.
|
| Trace Enabled | This enables tracing for the endpoint. You can use trace logs to debug mediation errors. |
| Statistics Enabled | This enables statistics for the endpoint. |
| Build Message | This property only applies to the Failover Endpoint and LoadBalance Endpoint. |
| Algorithm |
The algorithm on which the load balancing is based. Round Robin is the default algorithm. You can also load a custom algorithm. Instructions for creating a custom algorithm are included in this article.
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. Note: Currently only the Round Robin policy is supported.
|
| Failover | The property determines whether the next endpoint or static member should be selected once the currently selected endpoint or static member has failed and defaults to true. The failover property 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. |
| Endpoints |
Click Endpoints to start adding the failover/loadbalancing endpoints. In the dialog that opens, you can specify the following values:
|
Given below are the basic properties for the Template Endpoint:
| Property | Description |
|---|---|
| Available Templates | Select one of the available templates. |
| Target Template | The endpoint template which should be used to define the endpoint. This is specified by selecting one of the existing templates from the Available Templates list. The parameters to be included in the endpoint you are defining will be copied from the target template. The values for these parameters can be entered in the Template Endpoint Parameters section shown below. Click Delete Parameter to remove a parameter fetched from the target template. |
| Parameters |
The parameters of the endpoint. For example, you can add name to add the parameter name, and uri to add the address etc.
|
Session Management Properties¶
The following properties only apply to the LoadBalance endpoint:
| Property | Description |
|---|---|
| Session Management |
A session management method from the load balancing group. This 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.
The possible values are as follows.
QName "[http://ws.apache.org/ns/synapse]ClientID".
|
| Session Timeout | The number of milliseconds after which the session would time out. |
Miscellaneous Properties¶
| Property | Description |
|---|---|
| URI |
EPR of the target endpoint. Following are the sample address URI definitions.
VAR is the url you need to set as an environment property. This is useful when you need to deploy the endpoint in a container.
|
| Optimize |
Optimization for the message, which transfers binary data. The available values are as follows.
|
| Description | |
| uri-template |
The URI template that constructs the RESTful endpoint URL at runtime. Insert uri.var. before each variable.
Notes:
|
| HTTP Method |
The HTTP method to use during the invocation of the endpoint. Supported methods are as follows.
|
| WSDL URI | The URI of the WSDL. |
| Service |
The service selected from the available services for the WSDL.
The service and port name containing the target EPR has to be specified with the service and port (or endpoint) properties respectively.
|
| Port | The port selected for the service specified in the Service parameter. In a WSDL, an endpoint is bound to each port inside each service. |
| Add Properties |
Click Add Property to open the Properties tab and add the required properties.
|
Quality of Service Properties¶
QoS (Quality of Service) aspects such as WS-Security and WS-Addressing may be enabled on messages sent to an endpoint using enableSec and enableAddressing elements. Optionally, the WS-Security policies could be specified using the policy attribute.
| Property | Description |
|---|---|
| enableSec [policy="key"] | This enables WS-Security for the message which is sent to the endpoint. The optional policy attribute specifies the WS-Security policy. |
| enableAddressing [version="final | submission"] [seperateListener=" true | false"] | This enables WS-Addressing for the message that is sent to the endpoint. User can have a separate listener with version final or submission. |
Endpoint Error Handling Properties¶
Errors that can occur at endpoints can be specifically configured using the endpoint error handling properties.
The last step of message mediation is to send the message to a service provider through a listening service endpoint. During this process, transport errors can occur. For example, the connection might time out, or it might be closed by the actual service. Therefore, endpoint error handling is a key part of any successful Micro Integrator deployment.
Messages can fail or be lost due to various reasons in a real TCP network. When an endpoint error occurs, if the Micro Integrator is not configured to accept the error, it will mark the endpoint as failed, which leads to a message failure. By default, the endpoint is marked as failed for quite a long time, which can result in severe message loss.
To avoid message loss, you configure error handling at the endpoint level. You should also run a few long-running load tests to discover errors and fine-tune the endpoint configurations for errors that can occur intermittently due to various reasons.
At any given time, the state of the endpoint can be one of the following. During an endpoint error, the endpoint will transition between these states and, if required, will initiate a fault sequence.
| State | Description |
|---|---|
| Active | Endpoint is running and handling requests. When the Micro Integrator starts, endpoints are in "Active" state until the user sets it to OFF state, or until an error occurs. In the endpoint error handling configuration, error codes are allocated to a particular endpoint state. Therefore, when the error occurs, the endpoint will either remain in Active state or change to Timeout or Suspended depending on the error code. The endpoint first checks whether the error is a Timeout error, and if not, it checks whether it is a suspended error. If the error is not defined for either "Timeout" or "Suspended," the error will be ignored and the endpoint will remain active. |
| Timeout | Endpoint encountered an error but can still send and receive messages. If it continues to encounter errors, it will be suspended. When an endpoint is in the Timeout state, it will continue to attempt to receive messages until one message succeeds or the maximum retry setting has been reached. If the maximum is reached at which point, the endpoint is marked as Suspended. If one message succeeds, the endpoint is marked as Active. For example, let's assume the number of retries is set to 3. When an error occurs and the endpoint is set to the "Timeout" state, the Micro Integrator can try to send up to three more messages to the endpoint. If the next three messages sent to this endpoint result in an error, the endpoint is put in the Suspended state. If one of the messages succeeds before the retry maximum is met, the endpoint will be marked as Active. |
| Suspended |
Endpoint encountered errors and cannot send or receive messages. Incoming messages to a suspended endpoint result in a fault.
When an endpoint is put into this state, the Micro Integrator waits until after an initial duration has elapsed (default is 30 seconds) before attempting to send messages to this endpoint again. If the message succeeds, the endpoint is marked as Active. If the next message fails, the endpoint is marked as Suspended or Timeout depending on the error, and the Micro Integrator waits before retrying messages using the following formula: Min(current suspension duration * progressionFactor, maximumDuration).
You configure the initial suspension duration, progression factor, and maximum duration as part of the suspendOnFailure settings. On each retry, the suspension duration increases, up to the maximum duration.
|
| OFF | Endpoint is not active. To put an endpoint into the OFF state, or to move it from OFF to Active, you must use JMX. |
The following is the configuration for the address endpoint. Since we all are only interested in error configurations, the same applies for WSDL endpoints as well. The error handling configuration are as follows:
- timeout
- markForSuspension
- suspendOnFailure
<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>
<responseAction>discard|fault|never</responseAction>
</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>Timeout Properties¶
The timeout element contains the following parameters that are used to consider an endpoint as "timeout" by not being responsive for a specified time duration.
|
Property |
Description |
|---|---|
|
Timeout Duration |
Connection timeout interval. If the remote endpoint does not respond in this time, it will be marked as "Timeout." This can be defined as a static value or as a dynamic value. Miliseconds or an XPATH expression. Default value is 60000 milliseconds. |
|
Timeout Action (responseAction) |
When a response comes to a timed out request, this property specifies whether to discard it or invoke the fault handler. If you select "never", the endpoint remains in the "Active" state. This parameter is used to specify the action to perform once an endpoint has timed out. The available options are as follows:
synapse.timeout_handler_interval property in the MI_Home/conf/deployment.toml file. This would minimise the number of late responses from the backend.
|
MarkForSuspension Properties¶
The markForSuspension element contains the following parameters that are used to mark an endpoint as "suspended" after the time out duration is reached.
|
Property |
Description |
|---|---|
|
Retry Error codes (errorCodes) |
A (comma-separated) list of error codes. If these error codes are received from the endpoint, the request will be subjected to a timeout.
The defined error codes moves the endpoint into the "Timeout" state, thereby marking it for suspension. After the number of defined retriesBeforeSuspension exceeds, the endpoint will be suspended.
Default: 101504, 101505.
See the SynpaseConstant class for a list of available error codes.
|
|
Retry Count (retriesBeforeSuspension) |
The number of times the endpoint should be allowed to retry sending the response before it is marked for suspension. In the "Timeout" state, this number of requests minus one can be tried and failed before the endpoint is marked as "Suspended". This setting is per endpoint (not per message), so several messages can be tried in parallel and failed and the remaining retries for that endpoint will be reduced. Default: 0.
Note: If you do not specify these error codes, or if you do not specify any error codes under suspendOnFailure, by default, the "HTTP Connection Closed" (i.e., 101504) and "HTTP Connection Timeout" (i.e., 101505) errors act as "Timeout" errors, and all other errors will move the endpoint into the "Suspended" state after retrying.
|
|
Retry Delay (retryDelay) |
The time to wait between the last retry attempt and the next retry. Default: 0. |
SuspendOnFailure Properties¶
Leaf endpoints (Address and WSDL) can be suspended if they are detected as failed endpoints. When an endpoint is in suspended state for a specified time duration following a failure, it cannot process any new messages. The following formula determines the wait time before the next attempt.
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 is the number of tries carried out after the endpoint is suspended. The increase in the try count causes an increase in the next suspension time period. This time period is bound to a maximum duration.
|
Property |
Description |
|---|---|
|
Suspend Error Codes (errorCodes) |
Comma separated list of error codes.
This parameter allows you to select one or more error codes from the list of values. If any of the selected errors are received from the endpoint, the endpoint will be suspended. All the errors except the errors specified in markForSuspension.
Only these defined error codes will directly send the endpoint into the "Suspended" state. Any other error code, which is not specified under MarkForSuspension, will keep the endpoint in the "Active" state without suspending.
If you do not specify these error codes, by default, all the errors except the errors specified in markForSuspension will suspend the endpoint.
|
|
Suspend Initial Duration (initialDuration) |
The time duration (in miliseconds) for which the endpoint will be suspended, when one or more suspend error codes are received from it for the first time. After an endpoint gets "Suspended", it will wait for this amount of time before trying to send the messages coming to it. All the messages coming during this time period will result in fault sequence activation. Default: 30000. |
|
Suspend Maximum Duration |
The maximum time duration (in miliseconds) for which the endpoint is suspended when the suspend error codes are received. |
|
Suspend Progression Factor (progressionFactor) |
The progression factor for the geometric series. See the above formula for a more detailed description. The duration to suspend can vary from the first time suspension to the subsequent time. The factor value decides the suspend duration variance between subsequent suspensions.
The endpoint will try to send the messages after the initialDuration. If it still fails, the next duration is calculated as:Min(current suspension duration * progressionFactor, maximumDuration).
Default: 1.
|
Sample Configuration:¶
<endpoint name="Sample_First" statistics="enable" >
<address uri="http://localhost:8280/myendpoint" statistics="enable" trace="disable">
<timeout>
<duration>60000</duration>
</timeout>
<markForSuspension>
<errorCodes>101504, 101505</errorCodes>
<retriesBeforeSuspension>3</retriesBeforeSuspension>
<retryDelay>1</retryDelay>
</markForSuspension>
<suspendOnFailure>
<errorCodes>101500, 101501, 101506, 101507, 101508</errorCodes>
<initialDuration>1000</initialDuration>
<progressionFactor>2</progressionFactor>
<maximumDuration>60000</maximumDuration>
</suspendOnFailure>
</address>
</endpoint>In this example, 101504 and 101505 errors move the endpoint into the "Timeout" state. At that point, three requests can fail for one of these errors before the endpoint is moved into the "Suspended" state. Additionally, 101500, 101501, 101506, 101507, and 101508 errors will move the endpoint directly into the "Suspended" state. If a 101503 error occurs, the endpoint will remain in the "Active" state as you have not specified it under suspendOnFailure. The default setting to suspend the endpoint for all error codes, except the ones specified under markForSuspension, will apply only if you do not specify error codes under suspendOnFailure.
When the endpoint is first suspended, the retry happens after one second. Because the progression factor is 2, the next suspension duration before retry is two seconds, then four seconds, then eight, and so on until it gets to sixty seconds, which is the maximum duration we have configured. At this point, all subsequent suspension periods will be sixty seconds until the endpoint succeeds and is back in the Active state, at which point the initial duration will be used on subsequent suspensions.
WS Addressing Properties¶
|
Property |
Description |
|---|---|
|
WS-Addressing |
Adds WS-Addressing headers to the endpoint. |
|
Separate Listener |
The listener to the response will be a separate transport stream from the caller. |
|
WS-Security |
Adds WS-Security features as described in a policy key (referring to a registry location). |
| Non Retry Error Codes |
When a child endpoint of a failover endpoint or load-balance endpoint fails for one of the error codes specified here, the child endpoint will be marked for suspension and the request will not be sent to the next endpoint in the group. |
| Retry Error Codes | When adding a child endpoint to a failover endpoint or load-balance endpoint, you can specify the error codes that trigger this node to be retried instead of suspended when that error is encountered. This is useful when you know that certain errors are transient and that the node will become available again shortly. Note that if you specify an error code as a Retry code on one node in the group but specify that same code as a Non Retry error code on another node in the group, it will be treated as a Non Retry error code for all nodes in the group. |