Using subtopics -- Flex 2.01

The subtopic feature lets you divide the messages that a Producer component sends to a destination into specific categories at the destination. You can configure a Consumer component that subscribes to the destination to receive only messages sent to a specific subtopic or set of subtopics. You use wildcard characters (*) to send or receive messages from more than one subtopic.

You cannot use subtopics with a JMS destination. However, you can use message headers and Consumer selector expressions to achieve similar functionality when using JMS. For more information, see Filtering messages with a message selector.

In the subtopic property of a Producer component, you specify the subtopic(s) that the component sends messages to. In the subtopic property of a Consumer component, you specify the subtopic(s) to which the Consumer is subscribed.

To send a message from a Producer component to a destination and a subtopic, you set the destination and subtopic properties, and then call the send() method, as the following example shows:

<?xml version="1.0"?> 
<!-- fds\messaging\Subtopic1.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 acknowledgeHandler(event:MessageAckEvent):void {
                // Handle message acknowledgement event.
            }           
            private function faultHandler(event:MessageFaultEvent):void {
            // Handle fault event.
            }
            private function useSubtopic():void {
                var message:AsyncMessage = new AsyncMessage();
                producer.subtopic = "chat.fds.newton";
                // Generate message.
                producer.send(message);
            }
        ]]>
    </mx:Script>
    <mx:Producer id="producer"
        destination="ChatTopicJMS"
        acknowledge="acknowledgeHandler(event)"
        fault="faultHandler(event)"/>
</mx:Application>

To subscribe to a destination and a subtopic with a Consumer component, you set the destination and subtopic properties and then call the subscribe() method, as the following example shows. This example uses a wildcard character (*) to receive all messages sent to all subtopics under the chat.fds subtopic.

<?xml version="1.0"?> 
<!-- fds\messaging\Subtopic2.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.
            }
            private function useSubtopic():void {
                consumer.destination = "ChatTopic";
                consumer.subtopic = "chat.fds.*";
                consumer.subscribe();
            }
        ]]>
    </mx:Script>
    <mx:Consumer id="consumer" destination="ChatTopicJMS"
         message="messageHandler(event)"
         fault="faultHandler(event)"/>
</mx:Application>

To allow subtopics for a destination, you must set the allow-subtopics element to true in the destination definition in the services-config.xml file or a file that it includes by reference, such as the messaging-config.xml file. The subtopic-separator element is optional; the default value is "." (period).

<destination id="ChatTopic">
    <properties>
        <network>
            <session-timeout>0</session-timeout>
        </network>
        <server>
            <max-cache-size>1000</max-cache-size>
            <message-time-to-live>0</message-time-to-live>
            <durable>false</durable>
            <allow-subtopics>true</allow-subtopics>
            <subtopic-separator>.</subtopic-separator>
        </server>
    </properties>
    <channels>
        <channel ref="my-rtmp"/>
    </channels>
</destination>

The following example is a runnable application that uses subtopics. In this case, the Producer and Consumer components are declared in MXML tags. The Consumer component uses a wildcard character (*) to receive all messages under the chat.fds subtopic.

<?xml version="1.0"?> 
<!-- fds\messaging\Subtopic3.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 sendMessage():void {
                myCon.subscribe();
                var message:AsyncMessage = new AsyncMessage();
                message.body = userName.text;       
                myPub.send(message);
            }   
            private function messageHandler(event: MessageEvent):void {
                ta.text += event.message.body + "\n";
            }
        ]]>
    </mx:Script>

    <mx:Producer id="myPub" destination="mike" subtopic = "chat.fds.blue"/> 
    <mx:Consumer id="myCon" destination="mike" subtopic="chat.fds.*"
        message="messageHandler(event);"/>


    <mx:TextInput id="userName" width="20%"/>
    <mx:TextInput id="msg" width="20%"/>
    <mx:Button label="Send" click="sendMessage();"/>
    <mx:TextArea id="ta"/>
</mx:Application>