About channels and endpoints

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.

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

<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>

... 
<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> 
...

... 
    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; 
    } 
...

<?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>

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

-services "c:\lcds\tomcat\webapps\samples\WEB-INF\flex\services-config.xml"

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>

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.

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

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.

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).