About the Adapter
Overview of the Adapter
The IBM webMethods Adapter for JMS is an add-on to the IBM webMethods Integration Server that enables you to exchange messages with JMS providers through the use of the JMS APIs. The adapter provides seamless and real-time communication with JMS providers. Using the Adapter for JMS, webMethods clients can create and run services that can exchange messages from queues and topics on the JMS provider.
For a list of the JMS providers that the Adapter for JMS supports, see IBM webMethods Adapters System Requirements.
Architecture and Components
The Adapter for JMS enables you to configure the following components:
- Adapter Connections: Enable the webMethods product suite to connect to JMS providers at run time.
- Adapter Services: Perform operations on JMS providers using the built-in services provided with the Adapter for JMS.
- MessageListener Notifications: Provide Asynchronous notification of messages in queues and topics.
The following diagram illustrates how the Adapter for JMS interfaces with a JMS provider using JMS APIs. Following the diagram are descriptions of the different architectural pieces involved in the integration process.
For a more detailed description of the run time data flow for the different types of Adapter for JMS services, see Adapter Services.
- IBM webMethods Integration Server. The Adapter for JMS is installed and runs on the Integration Server.
- WmART Package. The WmART package provides a common framework for webMethods product suite 6.x and later adapters to utilize the Integration Server functionality, making the Integration Server the run-time environment for the Adapter for JMS. The WmART package is installed with the Integration Server.
- Adapter for JMS. The Adapter for JMS is delivered
as a single package called WmJMSAdapter.
The Adapter for JMS provides Integration Server Administrator and Designer user interfaces that enable you to configure and manage adapter connections, adapter services, and adapter notifications.
- Adapter Connection Templates. Adapter connections enable the
Adapter for JMS to connect
to JMS providers. You must configure an adapter connection before you can configure adapter services
or adapter notifications. The Adapter for JMS connections use JNDI to look up the JMS connection factories.
You configure adapter connections using the Integration Server Administrator. For a detailed description of adapter connections, see Adapter Connections.
- Adapter Service Templates. Adapter services enable the Adapter for JMS to produce and
consume messages from JMS destinations (queues and topics). The Adapter for JMS provides
adapter service templates that enable you to configure adapter services. The Adapter for JMS services use
JNDI to look up the JMS destinations.
You configure adapter services in Designer using the Adapter for JMS adapter services templates. For a detailed description of adapter services, see Adapter Services.
- Adapter Notification Template. Adapter notifications enable the
Adapter for JMS to listen
to and retrieve messages from JMS destinations (queues and topics). The Adapter for JMS provides an
adapter notification template that enables you to configure adapter notifications. The Adapter for JMS notifications
use JNDI to look up the JMS destinations.
You configure adapter notifications in Designer using the Adapter for JMS adapter notification templates. For a detailed description of adapter notifications, see Adapter Notifications.
- JMS APIs. The Adapter for JMS uses JMS APIs
to interface with JMS providers.
For more information about the JMS API libraries that the adapter requires, see Installing, Upgrading, and Uninstalling the Adapter.
- JMS Provider. Adapter for JMS services and
notifications are associated with specific JMS destinations (queues or topics) in the JMS provider.
The Adapter for JMS can retrieve configured ConnectionFactory and Destination class objects from a JNDI-supported naming service. The Adapter for JMS does not dictate how a JMS provider should publish connection factory and message destination entities. However, it supports only those JMS providers that publish these objects in a JNDI-supported naming service. To configure objects of these classes and to register them in a JNDI naming service, you must use the administrative tools provided by your JMS provider.
The ConnectionFactory class exposes methods that enable a JMS application to establish connections to the underlying messaging system.
Destination class objects identify:
- Topics: An application may publish to, or subscribe to, a topic.
- Queues: An application may send messages to, or receive messages from, a queue.
For a complete list of JMS providers that the Adapter for JMS supports, see Installing, Upgrading, and Uninstalling the Adapter.
Package Management
The Adapter for JMS is provided as a package called WmJMSAdapter. You manage the adapter package the same way you manage any package on the Integration Server. There are several considerations regarding how you set up and manage your packages on the Integration Server, such as those described in the following list.
- Create user-defined packages for your connections and adapter services. For details, see Adapter for JMS Package Management.
- Understand how package dependencies work so you make the best decisions regarding how you manage your connections and adapter services. For details, see Package Dependency Requirements and Guidelines.
- Control which groups have access to which adapter services. For details, see Group Access Control.
- Understand how clustering, an advanced feature of the IBM webMethods Integration Server, works to effectively manage your adapter services. For details, see Adapter for JMS in a Clustered Environment.
- Enable and disable packages. For details, see Enabling Packages and Disabling Packages.
Adapter Connections
The Adapter for JMS uses adapter connections to define how its adapter services and adapter notifications connect to JMS providers. Each Adapter for JMS connection contains a set of connection parameters, including the logon parameters that the adapter requires to connect to the JMS provider. You must configure an adapter connection before you can configure an adapter service.
You configure connections using the Integration Server Administrator. For instructions for configuring and managing Adapter for JMS connections, see Adapter Connections.
The Adapter for JMS has two types of connections:
-
Adapter for JMS QueueConnection:
Select this connection type to connect to a queue.
-
Adapter for JMS TopicConnection:
Select this connection type to connect to a topic.
Transaction Management of Adapter for JMS Connections
Adapter for JMS connections support the following transaction types:
| Transaction Type | Description |
|---|---|
| XA_TRANSACTION | This transaction type allows the connection to support two-phase
transactions executed across multiple resources. In one transaction boundary, all of the
operations on multiple connections will be committed or rolled back together. A transaction
boundary means the scope of the transaction, from the beginning to the end of a transaction.
It can be in one adapter service, one flow service, one Java service, or several steps in a
flow service. The following JMS providers do not support the XA_TRANSACTION transaction type:
Note: All of the connections involved in a two-phase transaction must support the
XA_TRANSACTION transaction type.
Note: You cannot use connections that use the XA_TRANSACTION transaction type with
notifications.
|
| NO_TRANSACTION | When receiving messages, the connection automatically acknowledges the
received message. (Sessions are created with the CLIENT_ACKNOWLEDGE acknowledge mode.) When
sending messages, the message is automatically delivered. For instructions on managing transactions manually, see Built-In Transaction Management Services. |
| LOCAL_TRANSACTION | The connection does not automatically commit transactions. You can manually define the transactions, or the Integration Server transaction manager will manage it for you. For instructions on managing transactions manually, see Built-In Transaction Management Services. |
When you define a connection, the transaction type that you choose determines the type of transaction management that the connection's operations use implicitly. Implicit transactions, which include the transactions types in the preceding table, are managed by the Integration Server transaction manager.
You can also explicitly manage transactions using built-in services. For information about explicitly managing transactions, see Built-In Transaction Management Services.
Connection Pooling
Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. All adapter services use connection pooling.
A connection pool is a collection of connections with the same set of attributes. Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections instead of opening new connections.
Run-Time Behavior of Connection Pools
When you enable a connection, Integration Server initializes the connection pool, creating the number of connection instances you specified in the connection's Minimum Pool Size field. Whenever an adapter service needs a connection, Integration Server provides a connection from the pool. If no connections are available in the pool, and the maximum pool size has not been reached, the server creates one or more new connections (according to the number specified in Pool Increment Size) and adds them to the connection pool. If the pool is full (as specified in Maximum Pool Size), the requesting service will wait for Integration Server to obtain a connection, up to the length of time specified in the Block Timeout field, until a connection becomes available. Periodically, Integration Server inspects the pool and removes inactive connections that have exceeded the expiration period that you specified in Expire Timeout.
If the connection pool initialization fails because of a network connection failure or some other type of exception, you can enable the system to retry the initialization any number of times, at specified intervals. For information about configuring connections, see Adapter Connections.
Built-In Services For Connections
Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.
Another built-in service, pub.art.service:setAdapterServiceNodeConnection, enables you to change the connection associated with an adapter service. For information, see Changing the Connection for an Adapter Service or Notification at Design Time.
For details about the WmART services, see the IBM webMethods Integration Server Built-In Services Reference for your release.
Adapter Services
Adapter services enable the Adapter for JMS to initiate operations that interact with JMS providers. You configure adapter services using adapter service templates, which are provided with the Adapter for JMS. Each template represents a specific operation. For example, the MessageProducer template enables you to send (publish) messages to a JMS queue or topic.
Adapter service templates contain all of the code that is necessary to perform an operation on a JMS provider, but without the data specifications. You provide these specifications when you configure an adapter service. Configuring a new service from an adapter service template is straightforward. Using Designer, you assign a default adapter connection to the service, select the adapter service template, and supply the service's data specifications.
After you configure a service, you can incorporate it into a flow or Java service to interact with a JMS provider. For example, you can create a MessageConsumer flow service that retrieves JMS messages from a specific queue, call a MessageToDocument service to convert the JMS message to an Integration Server document, and then call another service that routes the JMS message data to a different backend resource.
The Adapter for JMS provides the following adapter service templates:
| Adapter Service Template | Description |
|---|---|
| MessageProducer | Sends (publishes) JMS messages to a queue or topic. |
| MessageConsumer | Receives (subscribes to) JMS messages from a queue or topic. |
| MessageRequestor | Sends JMS messages to a queue or topic and then waits for a reply JMS message. |
| DocumentToTextMessage | Converts an Integration Server document to a JMS text message. |
| TextMessageToDocument | Converts a JMS text message to an Integration Server document. |
| DocumentToObjectMessage | Converts an Integration Server document to a JMS object message. |
| ObjectMessageToDocument | Converts a JMS object message to an Integration Server document. |
| DocumentToMapMessage | Converts an Integration Server document to a JMS map message. |
| MapMessageToDocument | Converts a JMS map message to an Integration Server document. |
| DocumentToBytesMessage | Converts an Integration Server document to a JMS bytes message. |
| BytesMessageToDocument | Converts a JMS bytes message to an Integration Server document. |
| DocumentToStreamMessage | Converts an Integration Server document to a JMS stream message. |
| StreamMessageToDocument | Converts a JMS stream message to an Integration Server document. |
Using MessageProducer, MessageConsumer, and MessageRequestor
About this task
The following steps lists the tasks required to use the MessageProducer, MessageConsumer, and MessageRequestor adapter services:
Procedure
- Configure an adapter connection using Integration Server Administrator. For more information, see Adapter Connections.
- Select the appropriate adapter service template and configure the adapter service using Designer. For more information, see Adapter Services.
- If you plan to use an Integration Server flow or Java service to invoke the adapter service, design the flow or Java service to use this adapter service using Designer. For more information, see the IBM webMethods Service Development Help for your release.
- Manage the adapter service using Designer and Integration Server Administrator. For more information, see Package Management.
Changing the Connection for an Adapter Service or Notification at Design Time
Integration Server provides built-in services that you can use at design time to change the connection associated with an adapter service or notification. These built-in services are named pub.art.service:setAdapterServiceNodeConnection and pub.art.notification:setPollingNotificationNodeConnection. Using these services, you can change the specific connection associated with an adapter service or an adapter notification at design time so that you do not need to create and maintain multiple adapter services or notifications.
For details about these services, see the IBM webMethods Integration Server Built-In Services Reference for your release.
Other built-in services enable you to control connections; for more information, see Built-In Services For Connections.
Changing the Connection for an Adapter Service at Run Time
Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar backend resources.
For more information about overriding a service's default connection at run time, see Dynamically Changing a Service's Connection at Run Time.
Adapter Service Run-Time Processing
The following diagram illustrates how the Adapter for JMS processes MessageConsumer, MessageProducer, and MessageRequestor services at run time.
| Step | Description |
|---|---|
| 1 | An Integration Server client, typically using a flow or Java service, invokes a Adapter for JMS
service on IBM webMethods Integration Server to perform an operation on a JMS provider. You configured the adapter service earlier using Designer. |
| 2 | The adapter service gets a connection from the service's connection pool.
Adapter connections contain connection information for the JMS provider. |
| 3 | The adapter service uses the JMS APIs to operate on the JMS destination.
You created and enabled the adapter connection earlier using Integration Server Administrator. |
| 4 | The adapter service retrieves a JMS message from the JMS destination or
places a JMS message on the JMS destination as follows, depending on the type of service:
|
Adapter Notifications
The Adapter for JMS provides a notification called MessageListener, which monitors a specified JMS destination (queue or topic) and notifies the adapter when a message arrives at that destination.
You can configure the notification to either publish the notification's associated publishable document or you can configure the notification to invoke a flow or Java service using the data from the notification.
If the notification publishes the document, you can use an Integration Server trigger to monitor for a given publishable document associated with a notification. When Integration Server receives this publishable document, it invokes a flow or Java service that is registered with the trigger. The flow or Java service then reacts to the data changes contained in the notification's publishable document. For more details about Integration Server publishable documents, see the Publish-Subscribe Developer’s Guide for your release.
For instructions for configuring MessageListener notifications, see Configuring MessageListener Notifications.
Considerations When Using MessageListener Notifications
- If you are using the MessageListener notification on an Integration Server that does not have a Broker configured (and does not have a service associated with the notification), the notification publishes the document in local mode.
- When an Integration Server hosts a MessageListener notification that is configured to publish a document, only the Integration Server that hosts the notification should subscribe to the notification's publishable document type. This is because a different Integration Server will not be able to understand the document's serialized message unless that Integration Server also has an Adapter for JMS installed.
- When you configure a MessageListener notification, the adapter creates a publishable document type to use with the notification. When you associate a MessageListener notification with a service (rather than publish the document), the service must use the same input signature as the notification's publishable document type would use.
Exactly Once Notifications
Adapter notifications can use the Exactly Once notification feature. This feature ensures that notification data will not be duplicated even if a failure occurs during processing. This is achieved by assigning unique IDs for each publishable document. After a processing failure, Integration Server checks for duplicate records in storage and ignores any duplicate IDs.
MessageListener Notification Run-Time Processing
The following diagram and steps illustrate what happens at run time when MessageListener notifications are invoked. Integration Server continues to invoke the notification periodically, as defined when you configured the schedule parameters for the MessageListener notification.
| Step | Description |
|---|---|
| 1 | JMS messages are placed on a JMS destination (queue or topic). |
| 2 | The notification gets a connection from the notification's connection pool. |
| 3 | The notification uses the JMS APIs to monitor the JMS destination. |
| 4 | The notification retrieves the JMS messages from the queue or topic. |
| 5 | The notification does one of the following actions, depending on how you
configured the notification:
For more details about Integration Server publishable documents, see the Publish-Subscribe Developer’s Guide for your release. |
Using MessageListener Notifications
About this task
The following steps lists the tasks required to use these types of notification:
Procedure
- Create an adapter connection using Integration Server Administrator. See Configuring Adapter for JMS Connections for details.
- Configure the notification using Designer. See Configuring MessageListener Notifications for instructions for configuring notifications.
- If you plan to use an Integration Server flow or Java service, design it to react to the data changes contained in the notification's publishable document. Create the Integration Server trigger to use the notification's publishable document using Designer. For details, see the IBM webMethods Service Development Help for your release.
- Schedule and enable the adapter notification using Integration Server Administrator. See Managing MessageListener Notifications for instructions.
- Manage the notification using Designer and Integration Server Administrator. See Package Management and Adapter Notifications for details.
Using Version Control Systems to Manage Adapter Elements
The adapter supports the Version Control System (VCS) Integration feature provided by Designer. When you enable the feature in Integration Server, you can check adapter packages or elements into and out of your version control system from Designer. For more information about the VCS Integration feature, see the Configuring the VCS Integration Feature.
Beginning with Integration Server 8.2 SP3, the adapter supports the local service development feature in Designer. This feature extends the functionality of the VCS Integration feature to check package elements and their supporting files into and out of a VCS directly from Designer. For more information about local service development and how it compares to the VCS Integration feature, see the IBM webMethods Service Development Help.
Optimize Infrastructure Data Collector Support for Adapter for JMS
Optimize Infrastructure Data Collector monitors the system and operational data associated with webMethods run-time components such as Integration Servers, Broker Servers, Brokers, and adapters, and reports the status of these components on Optimize for Infrastructure or other external tools. When you start monitoring an Integration Server, Infrastructure Data Collector automatically starts monitoring all ART-based adapters that are installed on Integration Server.
For information about monitored key performance indicators (KPIs) collected for the monitored adapter components, see Administering IBM webMethods Optimize for your release.
Viewing the Adapter's Update Level
You can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the adapter's About page in Integration Server Administrator.
Controlling Pagination
About this task
You can control the number of items that are displayed on the adapter Connections screen, Listeners screen, and Listener Notifications screen. By default, 10 items are displayed per page. Click Next and Previous to move through the pages, or click a page number to go directly to a page.
To change the number of items displayed per page, set the watt.art.page.size property and specify a different number of items.
To set the number of items per page