TechNote (Archived)

Flex Data Services 2: How to use subtopics in messaging applications

This TechNote describes how to use subtopics with producers and consumers in Flex Data Services 2 messaging applications, and provides a sample to demonstrate the configuration steps as well as a simple working code example.

The subtopic feature lets you divide the messages that a Producer component sends to a destination into specific categories or subtopics. 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. When using JMS, you can instead use message headers and Consumer selector expressions to achieve similar functionality. Flex 2 supports the subtopic feature with an ActionScript Adapter destination. Below is an example of how to configure your destination for subtopics and how to write code to produce/consume the subtopic using the ActionScript Adapter.

Configuration

You must specify the following property in the destination section to allow subtopics to be used for a message service destination:

 <destination id="ChatTopic"><properties><server><allow-subtopics>true</allow-subtopics> ...

In the destination definition below, we didn't set any adapter reference because we are using the default adapter, which is ActionScript adapter.

Here is the destination definition we will use for the provided sample. Add the following destination to your messaging-config.xml configuration file:

 <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>

Sample Code

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.

You can see the sample program implementing these steps here (save the example as msgSubtopics.mxml).

There are a couple of issues requiring additional attention:

The Producer and Consumer component tag has subtopic property, used as follows:
<mx:Producer id="myPub2" destination="ChatTopic" subtopic = "chat.fds.red"/> <mx:Consumer id="myCon" destination="ChatTopic" subtopic="chat.fds.blue"

The subtopic, however, does not get set properly this way, so you will need to set them in the ActionScript as shown in the code above.
When setting the subtopic value, for example, subtopic = "chat.fds.red", you can use a simple string, or a hierarchical separator delimited structure. The separator can be defined in the destination by<subtopic-separator>.</subtopic-separator>

The default is . (dot).

Running the sample:

Make sure you add the destination definition mentioned in the Configuration section above into messaging-config.xml.
Request msgSubtopics.mxml from a browser.

Note: If you want to run this from Flex Builder 2, make sure your project is configured to use "Flex Data Services," otherwise the application will run but the message will not be consumed.
Type in something like "Hello" in "subtopic blue" TextInput, and click the "send blue" button. The message is displayed in the TextArea as "from blue: Hello".
Type in something like "Hello again" in "subtopic red" TextInput, and click the "send red" button. The message is not displayed in the TextArea because it is not subscribed.
You can change the consumer's subtopic to red in the code, and should see only the subtopic red displayed in the TextArea.