Message selectors and subtopics

The Message Service provides functionality for Producer components to add information to message headers and to add subtopic information. Consumer components can then specify filtering criteria based on this information so that only messages that meet the filtering criteria are received by the consumer.

The Consumer component sends the filtering criteria to the server when the Consumer calls the subscribe() method. Therefore, while the Consumer component defines the filtering criteria, the actual filtering is done on the server before a message is sent to the consumer.

Note: Filter messages based on message headers or subtopics. However, do not filter messages using both techniques at the same time.

Using selectors

A Producer component can include extra information in a message in the form of message headers. A Consumer component then uses the selector property to filter messages based on message header values.

Use the AsyncMessage.headers property of the message to specify the message headers. The headers are contained in an associative Array where the key is the header name and the value is either a String or a number.

Note: Do not start message header names with the text "JMS" or "DS". These prefixes are reserved.

The following code adds a message header called prop1 and sets its value:

<?xml version="1.0"?> 
<!-- ds\messaging\SendMessageHeader.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 { 
                var message:AsyncMessage = new AsyncMessage(); 
                message.headers = new Array(); 
                message.headers["prop1"] = 5; 
                message.body = input.text; 
                producer.send(message); 
            } 
        ]]> 
    </mx:Script> 
 
    <mx:Producer id="producer" 
        destination="chat"/> 
 
    <mx:TextInput id="userName"/> 
    <mx:TextInput id="input"/> 
    <mx:Button label="Send" 
        click="sendMessage();"/> 
</mx:Application>

To filter messages based on message headers, use the Consumer.selector property to specify a message selector. 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.

The following code sets the Consumer.selector property so that the Consumer only receives messages where the value of prop1 in the message header is greater than 4:

<?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"; 
            } 
 
        ]]> 
    </mx:Script> 
 
    <mx:Consumer id="consumer" 
        destination="chat" 
        selector="prop1 > 4" 
        message="messageHandler(event);"/>        
    <mx:TextArea id="ta" width="100%" height="100%"/> 
</mx:Application>
Note: For advanced messaging scenarios, you can use the mx.messaging.MultiTopicConsumer and mx.messaging.MultiTopicProducer classes.

If you run the previous two applications at the same time, the Consumer receives messages from the Producer because the Producer sets the value of prop1 to 5.

Using subtopics

A Producer can send a message to a specific category or categories, called subtopics, within a destination. You then configure a Consumer component to receive only messages assigned to a specific subtopic or subtopics.

Note: 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 Using selectors.

In a Producer component, use the subtopic property to assign a subtopic to messages. Define a subtopic as a dot (.) delimited String, in the form:

mainToken[.secondaryToken][.additionalToken][...]

For example, you can define a subtopic in the form "chat", "chat.fds", or "chat.fds.newton". The dot (.) delimiter is the default; use the <subtopic-separator> property in the configuration file to set a different delimiter. For more information, see Setting server properties in the destination.

In the Consumer component, use the subtopic property to define the subtopic that a message must be sent to for it to be received. You can specify a literal String value for the subtopic property. Use the wildcard character (*) in the Consumer.subtopic property to receive messages from more than one subtopic.

The Message Service supports single-token wildcard characters (*) in the subtopic String. If the wildcard character is the last character in the String, it matches any tokens in that position or in any subsequent position. For example, the Consumer component specifies the subtopic as "foo.*". It matches the subtopics "foo.bar" and "foo.baz", and also "foo.bar.aaa" and "foo.bar.bbb.ccc".

If the wildcard character is in any position other than the last position, it only matches a token at that position. For example, a wildcard character in the second position matches any tokens in the second position of a subtopic value, but it does not apply to multiple tokens. Therefore, if the Consumer component specifies the subtopic as "foo.*.baz", it matches the subtopics "foo.bar.baz" and "foo.aaa.baz", but not "foo.bar.cookie".

You can use the optional disallow-wildcard-subtopics element in the server section of a messaging destination to specify whether wildcard characters (*) to receive messages from more than one subtopic are disallowed. The default value is false.

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

<?xml version="1.0"?> 
<!-- ds\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 useSubtopic():void { 
                var message:AsyncMessage = new AsyncMessage(); 
                producer.subtopic = "chat.fds.newton"; 
                message.body = "A subtopic message"; 
                producer.send(message); 
            } 
        ]]> 
    </mx:Script> 
 
    <mx:Producer id="producer" 
        destination="chat"/> 
    
    <mx:Button label="Send Data" 
        click="useSubtopic();"/> 
</mx:Application>

To subscribe to a destination and a subtopic with a Consumer component, 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"?> 
<!-- ds\messaging\Subtopic2.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.*; 
            
            private function messageHandler(event:MessageEvent):void { 
                // Handle message event. 
                ta.text += event.message.body + "\n"; 
            } 
 
            private function logon():void { 
                consumer.subtopic = "chat.fds.*"; 
                consumer.subscribe(); 
            } 
        ]]> 
    </mx:Script> 
    
    <mx:Consumer id="consumer" 
        destination="chat" 
        message="messageHandler(event);"/> 
    <mx:TextArea id="ta" width="100%" height="100%"/> 
</mx:Application>

To allow subtopics for a destination, set the allow-subtopics element to true in the destination definition in the messaging-config.xml file. The subtopic-separator element is optional and lets you change the separator character; the default value is "." (period).

<destination id="chat"> 
    <properties> 
        <network> 
            <subscription-timeout-minutes>0</subscription-timeout-minutes> 
        </network> 
        <server> 
            <message-time-to-live>0</message-time-to-live> 
            <allow-subtopics>true</allow-subtopics> 
            <subtopic-separator>.</subtopic-separator> 
        </server> 
    </properties> 
    <channels> 
        <channel ref="my-rtmp"/> 
    </channels> 
</destination>

If you run the previous two applications at the same time, the Consumer receives messages from the Producer.

For more information on configuration, see Configuring the Message Service.