Java Message Service (JMS) is a Java API that lets applications create, send, receive, and read messages. Flex applications can then exchange messages with Java client applications.

In a standard configuration of the Messaging Service, a destination references the ActionScriptAdapter. The ActionScriptAdapter lets you use messaging with Flex clients as the sole producers and consumers of the messages.

You use the JMSAdapter to connect LiveCycle Data Services ES to JMS topics or queues. The JMSAdapter supports topic-based and queue-based messaging. The JMSAdapter class lets Flex applications participate in existing messaging-oriented middleware (MOM) systems. Therefore, a Java application can publish messages to and respond to messages from Flex applications.

To connect LiveCycle Data Services ES to a JMS server, you create a destination that references the JMSAdapter. The following image shows LiveCycle Data Services ES using the JMSAdapter:

The Flex client sends and receives messages through a destination that references the JMSAdapter. The JMSAdapter then connects to the destination on the JMS server. Since the destination is accessible by a Java client, the Java client can exchange messages with the Flex client.

Writing client-side code to use JMS

The Flex client uses the Consumer and Producer components to send and receive messages through the JMSAdapter, just as it would for an application using the ActionScriptAdapter. For example, if the name of a destination that references the JMSAdapter is messaging_JMS_Topic, you reference it from a Producer component as the following example shows:

<mx:Producer id="producer"
    destination="messaging_JMS_Topic"
    acknowledge="acknowledgeHandler(event);"
    fault="faultHandler(event);"/>

JMS topics and queues

The JMSAdapter supports both JMS topics and JMS queues. The JMSAdapter supports the use of message headers and selectors for JMS topics, but hierarchical topics and subtopics are not supported.

Topics support dynamic client subscribe and unsubscribe, and therefore do not require the same level of administration as JMS queues. When using JMS queues, define a unique queue for each client.

If two Flex clients listen to the same JMS queue, and the JMS server sends a message to the queue, only one of the clients receives the message at a given time. This operation is expected because JMS queues are meant to be consumed by one consumer.

JMS queues are point-to-point, unlike topics which are one-to-many. However, due to the administrative overhead of JMS queues, the JMSAdapter is not the best choice for point-to-point messages between clients. A better choice for point-to-point messaging is to use the ActionScriptAdapter in conjunction with message filtering on the client side. For more information, see Message filtering.

Setting up your system to use the JMSAdapter

You can use any JMS server with LiveCycle Data Services ES that implements the JMS specification. To use the JMSAdapter to connect to a JMS server, you perform several types of configurations, including the following:

1. Configure your web application so that it has access to the JMS server. For example, if you are using Tomcat, you might have to add the following Resource definitions to the application to add support for Apache ActiveMQ, which supports JMS version 1.1:

   <Context docBase="${catalina.home}/../../apps/team" privileged="true"
       antiResourceLocking="false" antiJARLocking="false" reloadable="true">
       <!-- Resourced needed for JMS -->
       <Resource name="jms/flex/TopicConnectionFactory"
           type="org.apache.activemq.ActiveMQConnectionFactory"
           description="JMS Connection Factory"
           factory="org.apache.activemq.jndi.JNDIReferenceFactory"
           brokerURL="vm://localhost"
           brokerName="LocalActiveMQBroker"/>
       <Resource name="jms/topic/flex/simpletopic"
           type="org.apache.activemq.command.ActiveMQTopic"
           description="my Topic"
           factory="org.apache.activemq.jndi.JNDIReferenceFactory"
           physicalName="FlexTopic"/>
       <Resource name="jms/flex/QueueConnectionFactory"
           type="org.apache.activemq.ActiveMQConnectionFactory"
           description="JMS Connection Factory"
           factory="org.apache.activemq.jndi.JNDIReferenceFactory"
           brokerURL="vm://localhost"
           brokerName="LocalActiveMQBroker"/>
        <Resource name="jms/queue/flex/simplequeue"
           type="org.apache.activemq.command.ActiveMQQueue"
           description="my Queue"
           factory="org.apache.activemq.jndi.JNDIReferenceFactory"
           physicalName="FlexQueue"/>
       <Valve className="flex.messaging.security.TomcatValve"/>
   </Context> 
   
   

   The JMS server is often embedded in your J2EE server, but you can interact with a JMS server on a remote computer accessed by using JNDI. For more information, see Using a remote JMS provider.

2. Create a JMSAdapter definition in the messaging-config.xml file:

   <adapters>
       <adapter-definition id="jms"         
           class="flex.messaging.services.messaging.adapters.JMSAdapter"/>
   </adapters>
   
   

   For more information on configuring the JMSAdapter, see Configure the JMSAdapter.

3. Create a destination that references the adapter in the messaging-config.xml file:

   <destination id="messaging_AMF_Poll_JMS_Topic" channels="my-amf-poll">
       <adapter ref="jms"/>
       <properties>
           <jms>
               <connection-factory>
                   java:comp/env/jms/flex/TopicConnectionFactory
               </connection-factory>
               <destination-type>Topic</destination-type>
               <destination-jndi-name>
                   java:comp/env/jms/topic/flex/simpletopic
               </destination-jndi-name>
               <message-type>javax.jms.TextMessage</message-type>
           </jms>
       </properties>
       <channels>
           <channel ref="samples-rtmp"/>
           <channel ref="samples-amf-polling"/>
       </channels>
   </destination>
   
   

   This destination references the first Apache ActiveMQ Resource, which supports topic-based messaging.

   Note: Since the channel only defines how the Flex client communicates with the server, you do not have to perform any special channel configuration to use the JMSAdapter.

   For more information, see Configuring a destination to use the JMSAdapter.

4. Compile your Flex application against the services-config.xml file, which includes the messaging-config.xml file by reference.