Typically, you configure the Messaging Service, including the JMSAdapter, in the messaging-config.xml file.

Configure the JMSAdapter

You configure the JMSAdapter individually for the destinations that use it, as the following example shows:

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

Configuring a destination to use the JMSAdapter

You perform most of the configuration of the JMSAdapter in the destination definition. Configure the adapter with the proper JNDI information and JMS ConnectionFactory information to look up the connection factory in JNDI.

The following example shows a destination that uses the JMSAdapter:

<destination id="chat-topic-jms">
    <properties>
    ...
        <jms>
            <destination-type>Topic</destination-type>
            <message-type>javax.jms.TextMessage</message-type>
            <connection-factory>jms/flex/TopicConnectionFactory</connection-factory>
            <destination-jndi-name>jms/topic/flex/simpletopic</destination-jndi-name>
            <delivery-mode>NON_PERSISTENT</delivery-mode>
            <message-priority>DEFAULT_PRIORITY</message-priority>
            <preserve-jms-headers>"true"</preserve-jms-headers>
            <acknowledge-mode>AUTO_ACKNOWLEDGE</acknowledge-mode>
            <connection-credentials username="sampleuser" password="samplepassword"/>
            <max-producers>1</max-producers>
        </jms>
    </properties>
    ...
    <adapter ref="jms"/>
</destination>

The JMSAdapter accepts the following configuration properties. For more specific information about JMS, see the Java Message Service specification or your application server documentation.

Configuring a server for the JMSAdapter

When a destination specifies a <destination-type> of topic for the JMSAdapter, you can set the durable property in the server definition. When true, the durable property specifies that messages are saved in a durable message store to ensure that they survive connection outages and reach destination subscribers. The default value is false.

The following example sets the durable property to true:

<server>
    <durable>true</durable>
</server>

Using a remote JMS provider

In many cases, the JMS server is embedded in your J2EE server. However, you can also interact with a JMS server on a remote computer accessed by using JNDI.

You can use JMS on a remote JNDI server by configuring the optional initial-context-environment element in the jms section of a message destination that uses the JMSAdapter. The initial-context-environment element takes property subelements, which in turn take name and value subelements. To establish the desired JNDI environment, specify the javax.naming.Context constant names and corresponding values in the name and value elements, or specify String literal names and corresponding values.

The bold-faced code in the following example is an initial-context-environment configuration:

<destination id="chat-topic-jms">
    <properties>
        ...
        <jms>
            <destination-type>Topic</destination-type>
            <message-type>javax.jms.TextMessage</message-type>
            <connection-factory>jms/flex/TopicConnectionFactory</connection-factory>
            <destination-jndi-name>jms/topic/flex/simpletopic</destination-jndi-name>
            <delivery-mode>NON_PERSISTENT</delivery-mode>
            <message-priority>DEFAULT_PRIORITY</message-priority>
            <acknowledge-mode>AUTO_ACKNOWLEDGE</acknowledge-mode>

            <!-- (Optional) JNDI environment. Use when using JMS on a remote JNDI server. -->
            <initial-context-environment>
                <property>
                    <name>Context.SECURITY_PRINCIPAL</name>
                    <value>anonymous</value>
                </property>
                <property>
                    <name>Context.SECURITY_CREDENTIALS</name>
                    <value>anonymous</value>
                </property>
                <property>
                    <name>Context.PROVIDER_URL</name>
                    <value>http://{server.name}:1856</value>
                </property>
                <property>
                    <name>Context.INITIAL_CONTEXT_FACTORY</name>
                    <value>fiorano.jms.runtime.naming.FioranoInitialContextFactory</value>
                </property>
            </initial-context-environment>
        </jms>
    </properties>
    ...
    <adapter ref="jms"/>
</destination>

Flex treats name element values that begin with the text "Context." as constants defined by javax.naming.Context and verifies that the Context class defines the constants that you specify. Some JMS providers also allow custom properties to be set in the initial context. You can specify these properties by using the string literal name and corresponding value that the provider requires. For example, the FioranoMQ JMS provider configures failover to back up servers with the following property:

<property>
     <name>BackupConnectURLs</name>
     <value>http://backup-server:1856;http://backup-server-2:1856</value>
</property>

If you do not specify the initial-context-environment properties in the jms section of a destination definition, the default JNDI environment is used. The default JNDI environment is configured in a jndiprovider.properties application resource file and or a jndi.properties file.

Naming conventions across JNDI providers for topic connection factories and destinations can vary. Depending on your JNDI environment, the connection-factory and destination-jndi-name elements must correctly reference the target named instances in the directory. Include the client library JAR files for your JMS provider in the WEB-INF/lib directory of your web application, or in another location from which the class loader loads them. Even when using an external JMS provider, LiveCycle Data Services ES uses the connection-factory and destination-jndi-name configuration properties to look up the necessary connection factory and destination instances.

J2EE restrictions on JMS

Section 6.6 of the J2EE 1.4 specification limits some of the JMS APIs that can be used in a J2EE environment. The following table lists the restricted APIs that are relevant to the JMSAdapter and the implications of the restrictions.

The JMSAdapter handles these restrictions by doing the following:

• Providing an explicit choice between synchronous and asynchronous message delivery.
• When asynchronous message delivery is specified and setMessageListener is restricted, a clear error message is sent to ask the user to switch to synchronous message delivery.
• When asynchronous message delivery is specified and setExceptionListener is restricted, a clear error message is sent to ask the user to switch to synchronous message delivery.
• Providing fine-grained tuning for synchronous message delivery so asynchronous message delivery is not needed.
• Providing clear error messages when durable subscribers cannot be used due to setClientID being restricted and asking the user to switch durable setting to false.