Working with Consumer components -- Flex 2.01

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

You can also specify message and fault event handlers for a Consumer component. A message event is broadcast when a message is received by the destination to which a Consumer component is subscribed. A fault event is broadcast when the channel to which the Consumer component is subscribed can't establish a connection to the destination, the subscription request is denied, or if a failure occurs when the Consumer component's receive() method is called. The receive() method retrieves any pending messages from the destination.

For reference information about the Consumer class, see Adobe Flex 2 Language Reference.

Subtopics

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 should also specify 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"?>
<!-- fds\messaging\CreateConsumerMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;
            private function messageHandler(event:MessageEvent):void {
                // Handle message event.
            }
            private function faultHandler(event:MessageFaultEvent):void {
            // Handle fault event.
            }
        ]]>
    </mx:Script>
    <mx:Consumer id="consumer"
        destination="ChatTopicJMS"
        message="messageHandler(event)"
        fault="faultHandler(event)"/>
</mx:Application>

Creating a Consumer component in ActionScript

You can create a Consumer component in an ActionScript method. The following code shows a Consumer component created in a method in an <mx:Script> tag. The import statements import the classes required to create a Consumer component, create AsyncMessage objects, add event listeners, and create message handlers.

<?xml version="1.0"?>  
<!-- fds\messaging\CreateConsumerAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;
            private var consumer:Consumer;
            private function acknowledgeHandler(event:MessageAckEvent):void{
                // Handle message event.
            }
            private function faultHandler(event:MessageFaultEvent):void{
            // Handle fault event.
            }           
            private function logon():void {
                consumer = new Consumer();
                consumer.destination = "ChatTopicJMS";
                consumer.addEventListener
                    (MessageAckEvent.ACKNOWLEDGE,  acknowledgeHandler);
                consumer.addEventListener
                    (MessageFaultEvent.FAULT, faultHandler);
            }
        ]]>
    </mx:Script>    
</mx:Application>

Subscribing to a destination

Whether you create a Consumer component in MXML or ActionScript, you still must call the component's subscribe() method to subscribe to a destination and receive messages from that destination.

A Consumer component can subscribe to destinations that use the Flex Message Service with no message adapters or to destinations that use message adapters. For example, the Java Message Service (JMS) adapter enables Consumer components to subscribe to JMS topics. On the client side, the API for non-adapter and adapter-enabled destinations is identical. The definition for a particular destination in the Flex services configuration file determines what happens when a Consumer component subscribes to the destination or a Producer component sends messages to the destination. For information about configuring destinations, see Configuring the Message Service.

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

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

Filtering messages with a message selector

You can use a Consumer component's selector property to filter the messages that the component should receive. A message selector is a String that contains a SQL conditional expression based on the SQL92 conditional expression syntax. The Consumer component receives only messages with headers that match the selector criteria. For information about creating message headers, see Adding extra information to a message.

The following code sets a Consumer component's selector property in an <mx:Consumer> tag:

<?xml version="1.0"?>
<!-- fds\messaging\CreateConsumerMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;
            private function messageHandler(event:MessageEvent):void {
                // Handle message event.
            }
            private function faultHandler(event:MessageFaultEvent):void {
            // Handle fault event.
            }
        ]]>
    </mx:Script>
    <mx:Consumer id="consumer"
        destination="ChatTopicJMS"
        selector="prop1 > 5" 
        message="messageHandler(event)"
        fault="faultHandler(event)"/>        
</mx:Application>

The following code sets a Consumer component's selector property in ActionScript:

<?xml version="1.0"?> 
<!-- fds\messaging\SelectorAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.events.*;
            private var consumer:Consumer;

            private function logon():void {
                consumer = new Consumer();
                consumer.destination = "ChatTopic";
                consumer.selector = "prop1 > 5";
                consumer.subscribe();
            }
        ]]>
    </mx:Script>    
</mx:Application>