This article is applicable to LiveCycle DS, LiveCycle DS Express, and BlazeDS.

Message Service is one of the key features in LiveCycle DS and BlazeDS. It enables Flex clients to communicate in your enterprise infrastructure with zero-coding on the server side.

Based on the publisher-subscriber model, the Message Service acts as a message router for both Flex and JMS-enabled clients. This article shows you how to leverage the Message Service in your Flex applications.

The conceptual diagram below demonstrates the message flow. It also covers some basic lingoes you need to know,

data services message flow

The Message Producer and Message Consumer could be either Flex apps or JMS enabled Java clients. The Service Destination is the message routing service residing on the server. Channel is the communication protocol between server and client. There are a variety of protocols you could use based on your infrastructure and project requirements.

Configuring the Server Side

The message service configuration file, messaging-config.xml, resides under the WEB-INF/flex directory.

Within the configuration file, Adapter node determines what type of clients could participate in the service.

  • The ActionScript Adapter supports messaging between Flex/Flash clients only. It is the default adapter setting.
  • The JMS Adapter accepts messaging from both Flex and JMS-enabled clients.
  • Custom messaging adapter could be created by extending the MessagingAdapter class on the server.

To create a messaging service, you need to add a destination node in messaging-config.xml,

<destination id="myNewDestination">
        <channels>
                <channel ref="my-polling-amf" />
        </channels>
</destination>

The messaging clients will publish and subscribe to the destination by referring to its id attribute.

The messaging service is free to use a variety of channel protocols defined in services-config.xml. The most commons ones are,

  • my-rtmp for server-pushed messaging. It’s a lot more responsive compare to polling, but it does not work if the client is behind a web proxy. Note that RTMP is not supported in BlazeDS.
  • my-polling-amf for client-pulled messaging. It’s not the most efficient, but it doesn’t have the client side proxy limitation.
  • It’s also possible to create a secure polling-amf channel in services-config.xml

You can fine tune your message destination with a rich set of property settings,

<destination id="myNewDestination">
        <properties>
                <network>
                        <session-timeout>0</session-timeout>
                </network>
                <server>
                        <max-cache-size>1000</max-cache-size>
                        <durable>false</durable>
                </server>
        </properties>
        <channels>
                <channel ref="my-polling-amf" />
        </channels>
</destination>

Coding on the Client Side

To start using the messaging service, the basic rules are,

  • Messages flow from producers to consumers, via a message destination
  • Each message destination could have multiple producers and consumers
  • Each Flex client could instantiate multiple producers and consumers

To create a message producer, just specify the destination id,

<mx:Producer id="producer" destination="myNewDestination" />

To publish a message,

private function pub():void
{
        var message:AsyncMessage = new AsyncMessage();
        message.headers.myCustomHeader = "hello header";
        message.body = "hello flex message service!";
        producer.send(message);
}

To create a message consumer, supply the destination id along with a message handler,

<mx:Consumer id="consumer" destination="myNewDestination" message="onMsg(event)" />

To handle an incoming message,

private function onMsg(event:MessageEvent):void
{
        trace(event.message.body);
}

Finally, bind the consumer to the destination,

private function init():void
{
        consumer.subscribe();
}

Note: you could put complex data types into the message body, such as collection data types, as long as the consumer could parse it properly.

See attached for the sample code used in this article.

Flex Message Service Sample Code