About channels and endpoints

Channels are client-side objects that encapsulate the connection behavior between Flex components and the LiveCycle Data Services server or the Edge Server. Channels communicate with corresponding endpoints on the LiveCycle Data Services server. You configure the properties of a channel and its corresponding endpoint in the services-config.xml file.

For more information on the Edge Server, see Edge Server.

How channels are assigned to a Flex component

Flex components use channel sets, which contain one or more channels, to contact the server. You can automatically or manually create and assign a channel set to a Flex component. The channel allows the component to contact the endpoint, which forwards the request to the destination.

If you compile an MXML file using the MXML compiler option -services pointing to the services-config.xml file, the component (RemoteObject, HTTPService, and so on) is automatically assigned a channel set that contains one or more appropriately configured channel instances. The configuration is based on the channel definition assigned to a destination in a configuration file. Alternatively, if you do not compile your application with the -services option or want to override the compiled-in behavior, you can create a channel set in MXML or ActionScript, populate it with one or more channels, and then assign the channel set to the Flex component.

Application-level default channels are especially important when you want to use dynamically created destinations and you do not want to create and assign channel sets to your Flex components that use the dynamic destination. In that case, application-level default channels are used. For more information, see Assigning channels and endpoints to a destination.

When you compile a Flex client application with the MXML compiler-services option, it contains all of the information from the configuration files that is needed for the client to connect to the server.

Configuring channels and endpoints

You can configure channels in channel definitions in the services-config.xml file or on the Flex client.

Configuring channels on the server

The channel definition in the following services-config.xml file snippet creates an AMFChannel that communicates with an AMFEndpoint on the server:

<channels> 
... 
<channel-definition id="samples-amf" 
        type="mx.messaging.channels.AMFChannel"> 
        <endpoint url="http://servername:8400/myapp/messagebroker/amf" port="8700" 
            type="flex.messaging.endpoints.AMFEndpoint"/> 
</channel-definition> 
</channels>
The channel-definition element specifies the following information:
  • id and channel class type of the client-side channel that the Flex client uses to contact the server

  • remote attribute that specifies that the endpoint as remote. In that case, the endpoint is not started on this server and it is assumed that the client will connect to a remote endpoint on another server. This is useful when the client is compiled against this configuration but some of the endpoints are on a remote server.

  • endpoint element that contains the URL and endpoint class type of the server-side endpoint

  • properties element that contains channel and endpoint properties

  • server element, which when using an NIO-based channel and endpoint optionally refers to a shared NIO server configuration

The endpoint URL is the specific network location that the endpoint is exposed at. The channel uses this value to connect to the endpoint and interact with it. The URL must be unique across all endpoints exposed by the server. The url attribute can point to the MessageBrokerServlet or an NIO server if you are using an NIO-based endpoint.

Configuring channels on the client

To create channels at runtime in Flex code, you create your own channel set in MXML or ActionScript, add channels to it, and then assign the channel set to a component. This process is common in the following situations:

  • You do not compile your MXML file using the -services MXML compiler option. This is useful when you do not want to hard code endpoint URLs into your compiled SWF files on the client. It is also useful when you want to use a remote server when developing an application in Flash Builder.

  • You want to use a dynamically created destination (the destination is not in the services-config.xml file) with the run-time configuration feature. For more information, see Run-time configuration.

  • You want to control in your client code the order of channels that a Flex component uses to connect to the server.

When you create and assign a channel set on the client, the client requires the correct channel type and endpoint URL to contact the server. The client does not specify the endpoint class that handles that request, but there must be a channel definition in the services-config.xml file that specifies the endpoint class to use with the specified endpoint URL.

The following example shows a RemoteObject component that defines a channel set and channel inline in MXML:

... 
<RemoteObject id="ro" destination="Dest"> 
    <mx:channelSet> 
        <mx:ChannelSet> 
            <mx:channels> 
                <mx:AMFChannel id="myAmf" 
                    uri="http://myserver:2000/myapp/messagebroker/amf"/> 
            </mx:channels> 
        </mx:ChannelSet> 
    </mx:channelSet> 
</RemoteObject> 
...

The following example shows ActionScript code that is equivalent to the MXML code in the previous example:

... 
    private function run():void { 
            ro = new RemoteObject(); 
            var cs:ChannelSet = new ChannelSet();  
            cs.addChannel(new AMFChannel("myAmf",  
                "http://myserver:2000/eqa/messagebroker/amf")); 
            ro.destination = "Dest";  
            ro.channelSet = cs; 
    } 
...
Important: When you create a channel on the client, you still must include a channel definition that specifies an endpoint class in the services-config.xml file. Otherwise, the message broker cannot pass a Flex client request to an endpoint.

To further externalize configuration, you can pass the endpoint URL value to the client at runtime. One way to do this is by reading a configuration file with an HTTPService component at application startup. The configuration file includes the information to programmatically create a channel set at runtime. You can use E4X syntax to get information from the configuration file.

The following MXML application shows this configuration file technique:

<?xml version="1.0" encoding="utf-8"?> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    applicationComplete="configSrv.send()"> 
    <mx:Script> 
    <![CDATA[ 
    import mx.controls.Alert; 
    import mx.messaging.channels.AMFChannel; 
    import mx.messaging.ChannelSet; 
    import mx.rpc.events.ResultEvent; 
    private var channelSet:ChannelSet; 
    private function configResultHandler(event:ResultEvent):void 
    { 
        var xml:XML = event.result as XML; 
        var amfEndpoint:String = "" + xml..channel.(@id=="amf").@endpoint; 
        if (amfEndpoint == "") 
        { 
            Alert.show("amf channel not configured", "Error"); 
        } 
        else 
        { 
            channelSet = new ChannelSet(); 
            var channel:AMFChannel = new AMFChannel("my-amf", amfEndpoint); 
            channelSet.addChannel(channel); 
            ro.channelSet = channelSet; 
            ro.getProducts(); 
        } 
    } 
    ]]> 
    </mx:Script> 
    <mx:HTTPService id="configSrv" url="config.xml" resultFormat="e4x" result="configResultHandler(event)"/> 
    <mx:RemoteObject id="ro" destination="product"/> 
    <mx:DataGrid dataProvider="{ro.getProducts.lastResult}" width="100%" height="100%"/> 
</mx:Application>

The MXML application reads the following configuration file:

<?xml version="1.0" encoding="utf-8"?> 
<config> 
    <channels> 
        <channel id="amf" endpoint="http://localhost:8400/lcds-samples/messagebroker/amf"/> 
    </channels> 
</config>

Configuring a Flash Builder project with client-configured channels

When you create a new LiveCycle Data Services or BlazeDS project in Flash Builder, you typically select J2EE as the Application Server Type and then check Use Remote Object Access Service. This adds an MXML compiler argument that points to the services-config.xml file. If you check the Flex Compiler properties of your Flash Builder project, you see something like this:
-services "c:\lcds\tomcat\webapps\samples\WEB-INF\flex\services-config.xml"

When you compile the application, the required values of the services-config.xml are included in the SWF file. The services-config.xml file is read at compile time and not at runtime as you might assume. You can use tokens such as {server.name}, {server.port}, and {context.root} in the services-config.xml file. The {context.root} token is substituted at compile time. The {server.name} and {server.port} are replaced at runtime with the server name and port number of the server the SWF is loaded from; you can’t use these tokens for AIR applications.

When you configure channels on the client, you can avoid dependency on the services-config.xml file. You can create a new Flex project with no Application Server Type settings because the channels are configured at runtime in the SWF file. For existing LiveCycle Data Services or BlazeDS projects, you can remove the services-config.xml compiler argument.

Assigning channels and endpoints to a destination

Settings in the LiveCycle Data Services configuration files determine the channels and endpoints from which a destination can accept messages, invocations, or data, except when you use the run-time configuration feature. The channels and endpoints are determined in one of the following ways:

  • If most of the destinations across all services use the same channels, you can define application-level default channels in the services-config.xml file, as the following example shows.

    Note: Using application-level default channels is a best practice whenever possible.
    <services-config ...> 
    ... 
        <default-channels> 
            <channel ref="my-http"/> 
            <channel ref="my-amf"/> 
        </default-channels> 
    ...

    In this case, all destinations that do not define channels use a default channel. You can override the default channel setting by specifying a channel at the destination level or service level.

  • If most of the destinations in a service use the same channels, you can define service-level default channels, as the following example shows:

    <service ...> 
    ... 
        <default-channels> 
            <channel ref="my-http"/> 
            <channel ref="my-amf"/> 
        </default-channels> 
    ...

    In this case, all destinations in the service that do not explicitly specify their own channels use the default channel.

  • The destination definition can reference a channel inline, as the following example shows:

    <destination id="sampleVerbose"> 
        <channels> 
            <channel ref="my-secure-amf"/> 
        </channels> 
    ... 
    </destination>

Fallback and failover behavior

The primary reason that channels are contained in a channel set is to provide a fallback mechanism from one channel to the next listed in the channel set, and so on, in case the first choice is unable to establish a connection to the server. For example, you could define a channel set that falls back from a StreamingAMFChannel to an AMFChannel with polling enabled to work around network components such as web server connectors, HTTP proxies, or reverse proxies that could buffer chunked responses incorrectly. You can also use this functionality to provide different protocol options so that a client can first try to connect using RTMP and if that fails, can fall back to HTTP.

The connection process involves searching for the first channel and trying to connect to it. In addition to the fallback behavior that the channel set provides, the channel defines a failoverURIs property. This property lets you configure a channel in ActionScript that causes failover across this array of endpoint URLs when it tries to connect to its destination. If the channel defines failover URIs, each is attempted before the channel gives up and the channel set searches for the next available channel. If no channel in the set can connect, any pending unsent messages generate faults on the client.

If the channel was successfully connected before experiencing a fault or disconnection, it attempts a pinned reconnection to the same endpoint URL once. If this immediate reconnection attempt fails, the channel falls back to its previous failover strategy and attempts to fail over to other server nodes in the cluster or fall back to alternate channel protocols.

Choosing an endpoint

The two types of endpoints in LiveCycle Data Services are servlet-based endpoints and NIO-based endpoints that use Java New I/O APIs.

Note: NIO-based endpoints are not available in BlazeDS.

The J2EE servlet container manages networking, IO, and HTTP session maintenance for the servlet-based endpoints. NIO-based endpoints are outside the servlet container and run inside an NIO-based socket server. NIO-based endpoints can offer significant scalability gains. Because they are NIO-based, they are not limited to one thread per connection. Far fewer threads can efficiently handle high numbers of connections and IO operations. If the web application is not servicing general servlet requests, you can configure the servlet container to bind non-standard HTTP and HTTPS ports. Ports 80 and 443 are then free for your NIO-based endpoints to use.

You can also deploy an Edge Server in your DMZ to forward client requests to a LiveCycle Data Services server in the application tier. In this configuration, clients communicate with the Edge Server in the DMZ, and not directly with the LiveCycle Data Services server inside the internal firewall. This configuration gives you more options for the endpoints you can use and the ports those endpoints can listen over. For more information about the Edge Server, see Edge Server.

The servlet-based endpoints are part of both BlazeDS and LiveCycle Data Services. Reasons to use servlet-based endpoints when you have LiveCycle Data Services are that you must include third-party servlet filter processing of requests and responses or you must access data structures in the application server HttpSession.

The NIO-based endpoints include RTMP endpoints as well as NIO-based AMF and HTTP endpoints that use the same client-side channels as their servlet-based counterparts.

The following situations prevent the NIO socket server used with NIO-based endpoints from creating a real-time connection between client and server in a typical deployment of a rich Internet application:

  • The only client access to the Internet is through a proxy server.

  • The application server on which LiveCycle Data Services is installed can only be accessed from behind the web tier in the IT infrastructure.

    Servlet-based streaming endpoints and long polling are good alternatives when NIO-based streaming is not an option. In the worst case, the client falls back to simple polling. The main disadvantages of polling are increased overhead on client and server machines, and increased network latency.

Servlet-based channel and endpoint combinations

LiveCycle Data Services provides the following servlet-based channel and endpoint combinations. A secure version of each of these channels/endpoints transports data over a secure HTTPS connection. The names of the secure channels and endpoints all start with the text "Secure"; for example, SecureAMFChannel and SecureAMFEndpoint.

Servlet-based channel/endpoint classes

Description

AMFChannel/AMFEndpoint

A simple channel/endpoint that transports data over HTTP in the binary AMF format in an asynchronous call and response model. Use for RPC requests/responses with RPC-style Flex components such as RemoteObject, HTTPService, and WebService. You can also configure a channel that uses this endpoint to repeatedly poll the endpoint for new messages. You can combine polling with a long wait interval for long polling, which handles near real-time communication.

For more information, see Simple channels and endpoints.

HTTPChannel/HTTPEndpoint

Provides the same behavior as the AMF channel/endpoint, but transports data in the AMFX format, which is the text-based XML representation of AMF. Transport with this endpoint is not as fast as with the AMFEndpoint because of the overhead of text-based XML. Use when binary AMF is not an option in your environment.

For more information, see Simple channels and endpoints.

StreamingAMFChannel/StreamingAMFEndpoint

Streams data in real time over the HTTP protocol in the binary AMF format. Use for real-time data services, such as the Data Management Service and the Message Service where streaming data is critical to performance.

For more information, see Streaming AMF and HTTP channels.

StreamingHTTPChannel/StreamingHTTPEndpoint

Provides the same behavior model as the streaming AMF channel/endpoint, but transports data in the AMFX format, which is the text-based XML representation of AMF. Transport with this endpoint is not as fast as with the StreamingAMFEndpoint because of the overhead of text-based XML. Use when binary AMF is not an option in your environment.

For more information, see Streaming AMF and HTTP channels.

NIO-based channel and endpoint combinations

The NIO-based endpoints include RTMP endpoints as well as NIO-based AMF and HTTP endpoints that use the same client-side channels as their servlet-based counterparts.

Note: NIO-based endpoints are not available in BlazeDS.

LiveCycle Data Services provides the following NIO-based channels/endpoints. A secure version of the RTMP channel/endpoint transports data over an RTMPS connection. A secure version of each of the HTTP and AMF channels/endpoints transports data over an HTTPS connection. The names of the secure channels and endpoints all start with the text "Secure"; for example, SecureAMFChannel and SecureNIOAMFEndpoint.

NIO-based channel/endpoint classes

Description

RTMPChannel/RTMPEndpoint

Streams data in real time over the TCP-based RTMP protocol in the binary AMF format. Use for real-time data services, such as the Data Management Service and the Message Service where streaming data is critical to performance.

The RTMP channel/endpoint uses an NIO server to support scaling up to thousands of connections. It uses a single duplex socket connection to the server and gives the server the best notification of Flash Player being shut down. If the direct connect attempt fails, Flash Player attempts a CONNECT tunnel through an HTTP proxy if the browser defines one (resulting in a direct, tunneled duplex socket connection to the server). In the worst case, Flash Player falls back to adaptive polling of HTTP requests that tunnel RTMP data back and forth between client and server, or it fails to connect entirely.

When you define an RTMP endpoint with a URI that starts with rtmp: and specifies no port, the endpoint automatically binds ports 1935 and 80 when the server starts.

When you define an RTMP endpoint with a URI that starts with rtmpt: and specifies no port, the endpoint will automatically bind port 80 when the server starts.

When you define a secure RTMP endpoint that specifies no port, the endpoint automatically binds port 443 when the server starts.

A defined (hardcoded) port value in the channel/endpoint URI overrides these defaults, and a bind-port configuration setting overrides these as well. When using a defined port in the URI or bind-port the endpoint binds just that single port at startup.

For more information, see Configuring channels with NIO-based endpoints.

AMFChannel/NIOAMFEndpoint

NIO-based version of the AMF channel/endpoint. Uses an NIO server and a minimal HTTP stack to support scaling up to thousands of connections.

StreamingAMFChannel/ NIOStreamingAMFEndpoint

NIO-based version of streaming AMF channel/ endpoint. Uses an NIO server and a minimal HTTP stack to support scaling up to thousands of connections.

HTTPChannel/NIOHTTPEndpoint

NIO-based version of HTTP channel/endpoint. Uses an NIO server and a minimal HTTP stack to support scaling up to thousands of connections.

StreamingHTTPChannel/StreamingNIOHTTPEndpoint

NIO-based version of streaming HTTP channel/endpoint. Uses an NIO server and a minimal HTTP stack to support scaling up to thousands of connections.

Choosing a channel

Depending on your application requirements, you can use simple AMF or HTTP channels without polling or with piggybacking, polling, or long polling. You can also use streaming RTMP, AMF, or HTTP channels. The difference between AMF and HTTP channels is that AMF channels transport data in the binary AMF format and HTTP channels transport data in AMFX, the text-based XML representation of AMF. Because AMF channels provide better performance, use an HTTP channel instead of an AMF channel only when you have auditing or compliance requirements that preclude the use of binary data over your network or when you want the contents of messages to be easily readable over the network (on the wire).

Non-polling AMF and HTTP channels

You can use AMF and HTTP channels without polling for remote procedure call (RPC) services, such as remoting service calls, proxied HTTP service calls and web service requests, or Data Management Service requests without automatic synchronization. These scenarios do not require the client to poll for messages or the server to push messages to the client.

Piggybacking on AMF and HTTP channels

The piggybacking feature enables the transport of queued messages along with responses to any messages the client sends to the server over the channel. By default, piggybacking is disabled. You can set it to true in the piggybacking-enabled property of a channel definition in the services-config.xml file or in the piggybackingEnabled property of a Channel instance when you create a channel in ActionScript.

Piggybacking provides lightweight pseudo polling, where rather than the client channel polling the server on a fixed or adaptive interval, when the client sends a non-command message to the server (using a Producer, RemoteObject, or DataService object), the server sends any pending data for client messaging or data management subscriptions along with the response to the client message.

Piggybacking can also be used on a channel that has polling enabled but on a wide interval like 5 seconds or 10 seconds or more, in which case the application appears more responsive if the client is sending messages to the server. In this mode, the client sends a poll request along with any messages it sends to the server between its regularly scheduled poll requests. The channel piggybacks a poll request along with the message being sent, and the server piggybacks any pending messages for the client along with the acknowledge response to the client message.

Polling AMF and HTTP channels

AMF and HTTP channels support simple polling mechanisms that clients can use to request messages from the server at set intervals. A polling AMF or HTTP channel is useful when other options such as long polling or streaming channels are not acceptable and also as a fallback channel when a first choice, such as a streaming channel, is unavailable at run time.

Long polling AMF and HTTP channels

You can 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. This mechanism uses the normal application server HTTP request processing logic and works with typical J2EE deployment architectures.

You can establish long polling for any channel that uses a non-streaming AMF or HTTP endpoint by setting the polling-enabled, polling-interval-millis, wait-interval-millis, and client-wait-interval-millis properties in a channel definition; for more information, see Simple channels and endpoints.

Streaming channels

For streaming, you can use RTMP channels, or streaming AMF or HTTP channels. Streaming channels must be paired with corresponding streaming endpoints that are NIO-based or servlet-based. Streaming AMF and HTTP channels work with servlet-based streaming AMF or HTTP endpoints or NIO-based streaming AMF or HTTP endpoints. RTMP channels work with NIO-based RTMP endpoints.

For more information about endpoints, see Choosing an endpoint.