Oracle® Fusion Middleware
Part 8. API Gateway Instances

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

You can configure a global JMS service under the External Connections node 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 API 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 API Gateway to consume a JMS queue or topic. Right-click the Process under the Listeners node in the 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 API 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 API 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.

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 under the Listeners node in the Policy Studio tree, 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 the section called “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. If the volume of messages arriving at the queue is more than a single thread can process, you can increase the number of threads listening on the queue by increasing the listener count.

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:

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 appropriate policy to run on the JMS message after it has been consumed by the API Gateway.

Send Response to Configured Destination:

Specifies whether the API Gateway sends a reply to the response queue named in the incoming message (in the ReplyTo header). This option is selected by default. Deselecting this option means that the API Gateway never sends a reply to the response queue named in the ReplyTo header.

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 API 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 under the Listeners node in the Policy Studio tree, 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 API Gateway. For details on configuring the fields on this screen, see the section called “Configuring a JMS Service”.

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 section called “Configuring a JMS Session”.

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 section called “Configuring a JMS Consumer”.