BlazeDS Developer Guide

Message filtering

The Messaging 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 message 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.

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 Messaging Service supports single-token wildcards 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".

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";
                // Generate message.
                producer.send(message);
            }
        ]]>
    </mx:Script>
 
    <mx:Producer id="producer"
        destination="chat"/>
</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="ChatTopic">
    <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-streaming-amf"/>
    </channels>
</destination>

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


 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/blazeds/1/blazeds_devguide/messaging_6.html