You can create Consumer components in MXML or ActionScript. To subscribe to a destination, you call the Consumer.subscribe() method.

You can also specify message and fault event handlers for a Consumer component. A Consumer component broadcasts a message event when a message is sent to a destination and the message has been routed to a consumer subscribed to that destination. A fault event is broadcast when the channel to which the Consumer component is subscribed cannot establish a connection to the destination, or the subscription request is denied.

For reference information about the Consumer class, see the Adobe LiveCycle ES ActionScript Reference.

Creating a Consumer component in MXML

You use the <mx:Consumer> tag to create a Consumer component in MXML. The tag must contain an id value. It typically specifies a destination that is defined in the server-side services-config.xml file.

The following code shows an <mx:Consumer> tag that specifies a destination and acknowledge and fault event handlers:

<?xml version="1.0"?>
<!-- ds\messaging\CreateConsumerMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="logon();">
    
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;
            
            // Subscribe to destination.
            private function logon():void {
                consumer.subscribe();
            }

            // Write received message to TextArea control.
            private function messageHandler(event:MessageEvent):void {
                // Handle message event.
                ta.text += event.message.body + "\n";
            }

            private function faultHandler(event:MessageFaultEvent):void {
                // Handle message fault event.
            }
        ]]>
    </mx:Script>
    
    <mx:Consumer id="consumer"
        destination="chat"
        message="messageHandler(event);"
        fault="faultHandler(event);"/>
    <mx:TextArea id="ta" width="100%" height="100%"/>
</mx:Application>

You can unsubscribe a Consumer component from a destination by calling the component's unsubscribe() method.

Creating a Consumer component in ActionScript

You can create a Consumer component in ActionScript. The following code shows a Consumer component created in a method in an <mx:Script> tag:

<?xml version="1.0"?>  
<!-- ds\messaging\CreateConsumerAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="logon();">
        
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;

            // Create a variable of type Consumer.
            private var consumer:Consumer;
            
            // Create the Consumer.
            private function logon():void {
                consumer = new Consumer();
                consumer.destination = "chat";
                consumer.addEventListener
                    (MessageEvent.MESSAGE, messageHandler);
                consumer.addEventListener
                    (MessageFaultEvent.FAULT, faultHandler);
                consumer.subscribe();
            }

            // Write received message to TextArea control.
            private function messageHandler(event:MessageEvent):void {
                // Handle message event.
                ta.text += event.message.body + "\n";
            }

            private function faultHandler(event:MessageFaultEvent):void{
                // Handle message fault event.
            }           
        ]]>
    </mx:Script>    

    <mx:TextArea id="ta" width="100%" height="100%"/>
</mx:Application>

Sending and receiving an object in a message

You can send and receive objects as part of a message. The following example sends and receives a message that contains an object:

<?xml version="1.0"?> 
<!-- ds\messaging\SendObjectMessage.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="logon();">

    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;
                        
            // Subscribe to destination.
            private function logon():void {
                consumer.subscribe();
            }

            // Create message from TextInput controls.
            private function sendMessage():void {
                var message:AsyncMessage = new AsyncMessage();
                message.body = new Object();
                message.body.uName = userName.text;
                message.body.uInput = input.text;
                message.body.theCollection = ['b','a',3,new Date()];
                producer.send(message);
            }

            // Write received message to TextArea control.
            private function messageHandler(event:MessageEvent):void {
                // Handle message event.
                ta.text = String(event.message.body.uName) + " ," + 
                    String(event.message.body.uInput);
            }
        ]]>
    </mx:Script>

    <mx:Producer id="producer"
        destination="chat"/>
    <mx:Consumer id="consumer"
        destination="chat"
        message="messageHandler(event);"/>

    <!-- User input controls. -->
    <mx:TextInput id="userName"/>
    <mx:TextInput id="input"/>
    <mx:Button label="Send" 
        click="sendMessage();"/>
        
    <!-- Display received message. -->
    <mx:TextArea id="ta"/>
</mx:Application>

Handling a network disconnection

Use the Consumer.subscribed and Consumer.connected properties to monitor the status of the Consumer component. The connected property is set to true when the Flex client is connected to the server. The subscribed property is set to true when the Flex client is subscribed to a destination.

Two properties control the action of the Consumer component when the destination becomes unavailable, or the subscription to the destination fails:

• resubscribeAttempts

  Specifies the number of times the component attempts to resubscribe to the server before dispatching a fault event. The component makes the specified number of attempts over each available channel. You can set the Channel.failoverURIs property to the URI of a computer to attempt to resubscribe to if the connection is lost. You typically use this property when operating in a clustered environment. For more information, see Clustering.

  A value of -1 specifies to continue indefinitely, and a value of 0 disables attempts.

• resubscribeInterval

  Specifies the interval, in milliseconds, between attempts to resubscribe. Setting the value to 0 disables resubscription attempts.

Calling the receive method

Typically, you use a real-time polling or streaming channel with the Consumer component. In both cases, the Consumer receives messages from the server without having to initiate a request. For more information, see Channels.

You can use a non-real-time channel, such as an AMFChannel with polling-enabled set to false, with a Consumer component. In that case, call the Consumer.receive() method directly to initiate a request to the server to receive any queued messages. Before you call the receive() method, call the subscribe() method to subscribe to the destination. A fault event is broadcast if a failure occurs when the Consumer.receive() method is called.