# Messaging System

## Contents
Overview Configuring a JMS Service Configuring a JMS Session Configuring a JMS Consumer Configuring the JMS Wizard

## Overview
A messaging system is a loosely coupled, peer-to-peer facility where clients can send messages to, and receive messages from any other client. In a messaging system, a client sends a message to a messaging agent. The recipient of the message can then connect to the same agent and read the message. However, the sender and recipient of the message do not need to be available at the same time to communicate (for example, unlike HTTP). The sender and recipient need only know the name and address of the messaging agent to talk to. The Java Messaging System (JMS) is an implementation of such a messaging system. It provides an API for creating, sending, receiving, and reading messages. Java-based applications can use it to connect to other messaging system implementations. A JMS provider can deliver messages synchronously or asynchronously, which means that the client can fire and forget messages or wait for a response before resuming processing. Furthermore, the JMS API ensures different levels of reliability in terms of message delivery. For example, it can ensure that the message is delivered once and only once, or at least once. The Enterprise Gateway uses the JMS API to connect to other messaging systems that expose a JMS interface, including Oracle WebLogic Server, IBM MQSeries, JBoss Messaging, TIBCO EMS, IBM WebSphere Server, and Progress SonicMQ. As a consumer of a JMS queue or topic, the Enterprise Gateway can read XML messages and pass them into a policy for validation. These messages can then be routed on over HTTP or dropped on to another JMS queue or topic. Important Note: You must add the JMS provider's JAR files to the Enterprise Gateway classpath for this feature to function correctly. Copy the provider JAR files to the `INSTALL_DIR/ext/lib` folder, where `INSTALL_DIR` points to the root of your Enterprise Gateway installation.
## Configuring a JMS Service
You can configure a global JMS service on the External Connections tab in Policy Studio by right-clicking the JMS Services node, and selecting Add a JMS Service. The details entered in the JMS Service dialog are used by the Enterprise Gateway to drop messages on to a JMS queue or topic. The Messaging System Connection filter uses JMS Services configured here to do this. Alternatively, you can configure a JMS service at the Process level and configure the Enterprise Gateway to consume a JMS queue or topic. Right-click the Process on the Services tab in Policy Studio, and select JMS Wizard. Configure the following fields on the JMS Service dialog: Name: Enter a descriptive name for the JMS Provider in the Name field. Provider URL: Enter the URL of the JMS provider (for example, `jnp://localhost:1099`). Initial Context Factory: The Enterprise Gateway uses a connection factory to create a connection with a JMS provider. A connection factory encapsulates a set of connection configuration parameters that have been defined by the administrator. For example, the initial context factory class for the JBoss application server is `org.jnp.interfaces.NamingContextFactory`. Connection Factory: Enter the name of the connection factory to use when connecting to the JMS provider. The name of the connection factory is vendor-specific. For example, the connection factory used for the JBoss application server is `org.jnp.interfaces:javax.jnp`. Username: If a user name is required to connect to this JMS provider, enter it in this field. Password: Enter the password for this user. Custom Message Properties: You can add JNDI context settings by clicking the Add button, and adding name and value properties in the fields. When the JMS Service has been configured, you can configure the Enterprise Gateway to drop messages on to a queue or topic exposed by this service by selecting it from the JMS Service field on the Messaging System Connection filter dialog when configuring a policy. For more details, see the Messaging System Filter topic. You can also configure JMS sessions for the newly added JMS Service at the Process level. For more details, see the next section.
## Configuring a JMS Session
JMS services have JMS sessions, which can be shared by multiple JMS consumers, or used by a single JMS consumer only. To configure a JMS session, right-click the Process on the Services tab in the Policy Studio, and select Messaging System -> Add JMS Session. Alternatively, you can configure a JMS session using the JMS Wizard. Configure the following fields on the JMS Session screen: Service Select a pre-configured JMS Service from the drop-down list. For more details, see Configuring a JMS Service. Allow Duplicates Typically, a JMS session operates in auto mode, meaning that messages received by the session are automatically acknowledged to guarantee once-only message delivery. By selecting the Allow Duplicates checkbox, you are configuring the JMS session to operate in duplicates okay mode. This means that messages are acknowledged lazily by the JMS session with the result that duplicate messages are possible. If messages are not automatically acknowledged, the client has no way of telling whether the JMS consumer received the message, and so may re-send the message. Running in this mode reduces the overhead associated with the guarantee of once-only message delivery offered by auto mode. Listener Count Specify the number of listeners permitted for this JMS session. Defaults to 1.
## Configuring a JMS Consumer
You can configure multiple JMS consumers under a single JMS session, which share that session. Alternatively, you can configure a single JMS consumer per JMS session. Consumers sharing a JMS session access that session serially. Each consumer blocks until a response (if any) is received. Consumers with their own session do not encounter this problem, which may improve performance. You can configure JMS consumers using the JMS Wizard, or by right-clicking an existing JMS session, and selecting Add JMS Consumer. Configure the following fields on the JMS consumer screen: Source: Enter the name of the queue or topic from which you want to consume JMS messages. Selector: The entered expression specifies the messages that the consumer is interested in receiving. Using a selector, the task of filtering the messages is performed by the JMS provider instead of by the consumer. The selector is a string that specifies an expression whose syntax is based on the SQL-92 conditional expression syntax. The Process only receives messages whose headers and properties match the selector. Extraction Method: Specify how to extract the data from the JMS message from the drop-down list: Create a `content.body` attribute based on the SOAP over JMS draft specification (the default) Insert the JMS message directly into the attribute named below Populate the attribute below with the value inferred from message type to Java Attribute Name: The name of the message attribute that holds the data extracted from the JMS message. Defaults to the `jms.message` message attribute. Policy: Select the checkbox for the appropriate policy to run on the JMS message after it has been consumed by the Enterprise Gateway.
## Configuring the JMS Wizard
You can use the JMS Wizard to configure a Process to consume JMS messages from a JMS queue or topic. When a message has been consumed by the Enterprise Gateway, it can be dispatched to a specified policy where the full compliment of message filters can run on the message. The message can then be routed onwards over HTTP or dropped back on to a JMS queue or topic. To launch the JMS Wizard, right-click the Process on the Services tab in the Policy Studio, and select Messaging System -> JMS Wizard. The wizard includes the following configuration screens: JMS Service Provider The first screen in the wizard enables you to configure connection details to the JMS provider that produces the JMS messages that are consumed by the Enterprise Gateway. For details on configuring the fields on this screen, see the Configuring a JMS Service section. JMS Session Configuration The second screen in the wizard enables you to configure the Allow Duplicates option for the JMS session that is established with the JMS provider. For details on configuring this option, see the Configuring a JMS Session section. JMS Consumer Configuration The third screen in the wizard enables you to configure JMS consumer settings. For details on configuring the fields on this screen, see the Configuring a JMS Consumer section.