The servlet-based endpoints are part of both BlazeDS and LiveCycle Data Services ES.
Simple channels and endpoints
The AMFEndpoint and HTTPEndpoint are simple servlet-based endpoints. You generally use channels with these endpoints without client polling for RPC service components, which require simple call and response communication with a destination. When working with the Messaging Service, you can use these channels with client polling to constantly poll the destination on the server for new messages, or with long polling to provide near real-time messaging when using a streaming channel is not an option in your network environment.
Property | Description |
---|
polling-enabled | Optional channel property. Default value is false. |
polling-interval-millis | Optional channel property. Default value is 3000. This parameter specifies the number of milliseconds the client waits before polling the server again. When polling-interval-millis is 0, the client polls as soon as it receives a response from the server with no delay. |
wait-interval-millis | Optional endpoint property. Default value is 0. This parameter specifies the number of milliseconds the server poll response thread waits for new messages to arrive when the server has no messages for the client at the time of poll request handling. For this setting to take effect, you must use a nonzero value for the max-waiting-poll-requests property. A value of 0 means that server does not wait for new messages for the client and returns an empty acknowledgment as usual. A value of-1 means that server waits indefinitely until new messages arrive for the client before responding to the client poll request. The recommended value is 60000 milliseconds (one minute). |
client-wait-interval-millis | Optional channel property. Default value is 0. Specifies the number of milliseconds the client will wait after it receives a poll response from the server that involved a server wait. A value of 0 means the client uses its configured polling-interval-millis value to determine the wait until its next poll. Otherwise, this value overrides the default polling interval of the client. Setting this value to 1 allows clients that poll the server with wait to poll immediately upon receiving a poll response, providing a real-time message stream from the server to the client. Any clients that poll the server and are not serviced with a server wait use the polling-interval-millis value. |
max-waiting-poll-requests | Optional endpoint property. Default value is 0. Specifies the maximum number of server poll response threads that can be in wait state. When this limit is reached, the subsequent poll requests are treated as having zero wait-interval-millis. |
piggybacking-enabled | Optional endpoint property. Default value is false. Enable to support piggybacking of queued messaging and data management subscription data along with responses to any messages the client sends to the server over this channel. |
login-after-disconnect | Optional channel property. Default value is false. Setting to true causes clients to automatically attempt to reauthenticate themselves with the server when they send a message that fails because credentials have been reset due to server session timeout. The failed messages are resent after reauthentication, making the session timeout transparent to the client with respect to authentication. |
flex-client-outbound-queue-processor | Optional channel property. Use to manage messaging quality of service for subscribers. Every client that subscribes to the server over this channel is assigned a unique instance of the specified outbound queue processor implementation that manages the flow of messages to the client. This can include message conflation, filtering, scheduled delivery and load shedding. You can define configuration properties, and if so, they are used to configure each new queue processor instance that is created. The following example shows how to provide a configuration property: <flex-client-outbound-queue-processor class="my.company.QoSQueueProcessor"> <properties> <custom-property>5000</custom-property> </properties> </flex-client-outbound-queue-processor> |
serialization | Optional serialization properties on endpoint. For more information, see Configuring AMF serialization on a channel. |
connect-timeout-seconds | Optional channel property. Use to limit the client channel's connect attempt to the specified time interval. |
invalidate-session-on-disconnect | Optional endpoint property. Disabled by default. If enabled, when a disconnect message is received from a client channel, the corresponding server session is invalidated. If the client is closed without first disconnecting its channel, no disconnect message is sent, and the server session is invalidated when its idle timeout elapses. |
add-no-cache-headers | Optional endpoint property. Default value is true. HTTPS requests on some browsers do not work when pragma no-cache headers are set. By default, the server adds headers, including pragma no-cache headers to HTTP responses to stop caching by the browsers. |
Non-polling AMF and HTTP channels
The simplest types of channels are AMF and HTTP channels in non-polling mode, which operate in a single request-reply pattern. The following example shows AMF and HTTP channel definitions configured for no polling:
<!-- Simple AMF -->
<channel-definition id="samples-amf"
type="mx.messaging.channels.AMFChannel">
<endpoint url="http://{server.name}:8400/myapp/messagebroker/amf"
type="flex.messaging.endpoints.AmfEndpoint"/>
</channel-definition>
<!-- Simple secure AMF -->
<channel-definition id="my-secure-amf"
class="mx.messaging.channels.SecureAMFChannel">
<endpoint url="https://{server.name}:9100/dev/messagebroker/
amfsecure" class="flex.messaging.endpoints.SecureAMFEndpoint"/>
</channel-definition>
<!-- Simple HTTP -->
<channel-definition id="my-http"
class="mx.messaging.channels.HTTPChannel">
<endpoint url="http://{server.name}:8400/dev/messagebroker/http"
class="flex.messaging.endpoints.HTTPEndpoint"/>
</channel-definition>
<!-- Simple secure HTTP -->
<channel-definition id="my-secure-http" class="mx.messaging.channels.SecureHTTPChannel">
<endpoint url=
"https://{server.name}:9100/dev/messagebroker/
httpsecure"
class="flex.messaging.endpoints.SecureHTTPEndpoint"/>
</channel-definition>
Polling AMF and HTTP channels
You can use an AMF or HTTP channel in polling mode to repeatedly poll the endpoint to create client-pull message consumers. The interval at which the polling occurs is configurable on the channel. You can also manually poll by calling the poll() method of a channel for which polling is enabled; for example, you want set the polling interval to a high number so that the channel does not automatically poll, and call the poll() method to poll manually based on an event, such as a button click.
When you use a polling AMF or HTTP channel, you set the polling property to true in the channel definition. You can also configure the polling interval in the channel definition.
Note: You can also use AMF and HTTP channels in long polling mode to get pushed messages to the client when the other more efficient and real-time mechanisms are not suitable. For information about long polling, see
Long polling AMF and HTTP channels.
The following example shows AMF and HTTP channel definitions configured for polling:
<!-- AMF with polling -->
<channel-definition id="samples-polling-amf"
type="mx.messaging.channels.AMFChannel">
<endpoint url="http://{server.name}:8700/dev/messagebroker/amfpolling"
type="flex.messaging.endpoints.AMFEndpoint"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-seconds>8</polling-interval-seconds>
</properties>
</channel-definition>
<!-- HTTP with polling -->
<channel-definition id="samples-polling-http"
type="mx.messaging.channels.HTTPChannel">
<endpoint url="http://{server.name}:8700/dev/messagebroker/httppolling"
type="flex.messaging.endpoints.HTTPEndpoint"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-seconds>8</polling-interval-seconds>
</properties>
</channel-definition>
Note: You can also use secure AMF or HTTP channels in polling mode.
Long polling AMF and HTTP channels
In the default configuration for a polling AMF or HTTP channel, the endpoint does not wait for messages on the server. When the poll request is received, it checks whether any messages are queued for the polling client and if so, those messages are delivered in the response to the HTTP request. You configure long polling in the same way as polling, but you also must set the wait-interval-millis, max-waiting-poll-requests, and client-wait-interval-millis properties.
To achieve long polling, you set the following properties in the properties section of a channel definition in the services-config.xml file:
- polling-enabled
- polling-interval-millis
- wait-interval-millis
- max-waiting-poll-requests.
- client-wait-interval-millis
Using different settings for these properties results in different behavior. For example, setting the wait-interval-millis property to 0 (zero) and setting thepolling-interval-millis property to a nonzero positive value results in normal polling. Setting the wait-interval-millis property to a high value reduces the number of poll messages that the server must process, but the number of request handling threads on the server limits the total number of parked poll requests.
The following example shows AMF and HTTP channel definitions configured for long polling:
<!-- Long polling AMF -->
<channel-definition id="my-amf-longpoll" class="mx.messaging.channels.AMFChannel">
<endpoint
url="http://servername:8700/contextroot/messagebroker/myamflongpoll"
class="flex.messaging.endpoints.AMFEndpoint"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-seconds>0</polling-interval-seconds>
<wait-interval-millis>60000</wait-interval-millis>
<client-wait-interval-millis>3000</client-wait-interval-millis>
<max-waiting-poll-requests>100</max-waiting-poll-requests>
</properties>
</channel-definition>
<!-- Long polling HTTP -->
<channel-definition id="my-http-longpoll" class="mx.messaging.channels.HTTPChannel">
<endpoint
url="http://servername:8700/contextroot/messagebroker/myhttplongpoll"
class="flex.messaging.endpoints.HTTPEndpoint"/>
<properties>
<polling-enabled>true</polling-enabled>
<polling-interval-seconds>0</polling-interval-seconds>
<wait-interval-millis>60000</wait-interval-millis>
<client-wait-interval-millis>3000</client-wait-interval-millis>
<max-waiting-poll-requests>100</max-waiting-poll-requests>
</properties>
</channel-definition>
Note: You can also use secure AMF or HTTP channels in polling mode.
The caveat for using the wait-interval-millis BlazeDS is the utilization of available application server threads. Because this channel ties up one application server request handling thread for each parked poll request, this mechanism can have an impact on server resources and performance. Modern JVMs can typically support about 200 threads comfortably if given enough heap space. Check the maximum thread stack size (often 1 or 2 megabytes per thread) and make sure that you have enough memory and heap space for the number of application server threads you configure.
To ensure that Flex clients using channels with wait-interval-millis do not lock up your application server, BlazeDS requires that you set the max-waiting-poll-requests property, which specifies the maximum number of waiting connections that BlazeDS should manage. This number must be set to a number smaller than the number of HTTP request threads your application server is configured to use. For example, you configure the application server to have at most 200 threads and allow at most 170 waiting poll requests. This setting would ensure that you have at least 30 application server threads to use for handling other HTTP requests. Your free application server threads should be large enough to maximize parallel opportunities for computation. Applications that are I/O heavy can require a large number of threads to ensure all I/O channels are utilized completely. Multiple threads are useful for the following operations:
- Simultaneously writing responses to clients behind slow network connections
- Executing database queries or updates
- Performing computation on behalf of user requests
Another consideration for using wait-interval-millis is that BlazeDS must avoid monopolizing the available connections that the browser allocates for communicating with a server. The HTTP 1.1 specification recommends that browsers allocate at most two connections to the same server when the server supports HTTP 1.1. To avoid using more that one connection from a single browser, BlazeDS allows only one waiting thread for a given application server session at a time. If more than one Flash Player instance within the same browser process attempts to interact with the server using long polling, the server forces them to poll on the default interval with no server wait to avoid busy polling.
Streaming AMF and HTTP channels
The streaming AMF and HTTP channels are HTTP-based streaming channels that the BlazeDS server can use to push updates to clients using a technique called HTTP streaming. These channels give you the option of using standard HTTP for real-time messaging. This capability is supported for HTTP 1.1, but is not available for HTTP 1.0. There are also a number of proxy servers still in use that are not compliant with HTTP 1.1. When using a streaming channel, make sure that the channel hasconnect-timeout-seconds defined and the channel set has a channel to fall back to, such as an AMF polling channel.
Using streaming AMF or HTTP channels/endpoints is like setting a long polling interval on a standard AMF or HTTP channel/endpoint, but the connection is never closed even after the server pushes the data to the client. By keeping a dedicated connection for server updates open, network latency is greatly reduced because the client and the server do not continuously open and close the connection. Unlike polling channels, because streaming channels keep a constant connection open, they can be adversely affected by HTTP connectors, proxies, reverse proxies or other network components that can buffer the response stream.
The following table describes the channel and endpoint configuration properties in the services-config.xml file that are specific to streaming AMF and HTTP channels/endpoints. The table includes the default property values as well as considerations for specific environments and applications.
Property | Description |
---|
connect-timeout-seconds | Using a streaming connection that passes through an HTTP 1.1 proxy server that incorrectly buffers the response sent back to the client hangs the connection. For this reason, you must set the connect-timeout-seconds property to a relatively short timeout period and specify a fallback channel such as an AMF polling channel. |
idle-timeout-minutes | Optional channel property. Default value is 0. Specifies the number of minutes that a streaming channel is allowed to remain idle before it is closed. Setting the idle-timeout-minutes property to 0 disables the timeout completely, but it is a potential security concern. |
max-streaming-clients | Optional endpoint property. Default value is 10. Limits the number of Flex clients that can open a streaming connection to the endpoint. To determine an appropriate value, consider the number of threads available on your application server because each streaming connection open between a FlexClient and the streaming endpoints uses a thread on the server. Use a value that is lower than the maximum number of threads available on the application server. This value is for the number of Flex client application instances, which can each contain one or more MessageAgents (Producer or Consumer components). |
server-to-client-heartbeat-millis | Optional endpoint property. Default value is 5000. Number of milliseconds that the server waits before writing a single byte to the streaming connection to make sure that the client is still available. This is important to determine when a client is no longer available so that its resources associated with the streaming connection can be cleaned up. Note that this functionality keeps the session alive. A non-positive value disables this functionality. |
user-agent-settings | Optional endpoint property. Default values are as shown in the following example: <user-agent-settings> <user-agent match-on="MSIE" kickstart-bytes= "2048" max-streaming-connections-per-session="1"/> <user-agent match-on="Firefox" kickstart-bytes="0" max-streaming-connections-per-session="1"/> </user-agent-settings>User agents are used to customize the streaming endpoint for specific web browsers for the following reasons: - A certain number of bytes must be written before the endpoint can reliably use a streaming connection as specified by the kickstart-bytes attribute.
- There is a browser-specific limit to the number of connections allowed per session. In Firefox, the limit is eight connections per session. In Internet Explorer, the limit is two connections allowed per session. Therefore, BlazeDS must limit the number of streaming connections per session on the server to stay below this limit.
By default, BlazeDS uses 1 as the value for max-streaming-connections-per-session. You can change the values for Internet Explorer and Firefox, and you can add other browser-specific limits by specifying a new user-agent element with a match-on value for a specific browser user agent. |
The following example shows streaming AMF and HTTP channel definitions:
<!-- AMF with streaming -->
<channel-definition id="my-amf-stream"
class="mx.messaging.channels.StreamingAMFChannel">
<endpoint url="http://servername:2080/myapp/messagebroker/streamingamf"
class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
</channel-definition>
<!-- Secure AMF with streaming -->
<channel-definition id="my-secure-amf-stream"
class="mx.messaging.channels.SecureStreamingAMFChannel">
<endpoint url="http://servername:2080/myapp/messagebroker/securestreamingamf"
class="flex.messaging.endpoints.SecureStreamingAMFEndpoint"/>
</channel-definition>
<!-- HTTP with streaming -->
<channel-definition id="my-http-stream"
class="mx.messaging.channels.StreamingHTTPChannel">
<endpoint url="http://servername:2080/myapp/messagebroker/streaminghttp"
class="flex.messaging.endpoints.StreamingHTTPEndpoint"/>
</channel-definition>
<!-- Secure HTTP with streaming -->
<channel-definition id="my-secure-http-stream"
class="mx.messaging.channels.SecureStreamingHTTPChannel">
<endpoint url="http://servername:2080/myapp/messagebroker/securestreaminghttp"
class="flex.messaging.endpoints.SecureStreamingHTTPEndpoint"/>
</channel-definition>