Overview

What Is webMethods Adapter Runtime?

webMethods Adapter Runtime provides a common framework for webMethods adapters version 6 and later to use IBM webMethods Integration Server’s functionality, making Integration Server the run-time environment for the adapters. webMethods Adapter Runtime functionality is delivered as the WmART package, which is automatically installed with Integration Server. The WmART package provides logging, transaction management and error handling for adapter connections, services, notifications, and listeners.

The following diagram shows at a high level how an adapter uses WmART to interact with the back end.

Package Management

Each webMethods adapter is provided as a separate package that has a dependency on the WmART package. When you create connections, adapter services, listeners, and notifications for an adapter, you must define them in user-defined packages rather than in the adapter package. The user-defined packages, in turn, have a dependency on the adapter package.

You manage the WmART package, the adapter package and user-defined packages as you would manage any package on Integration Server.

When Integration Server starts, it automatically loads or reloads the WmART package first, the adapter package next, and the user-defined packages last.The WmART package is automatically installed when you install Integration Server. You should not need to manually reload the WmART package.

The following diagram shows the various package dependencies.

User-Defined Package Dependency Requirements and Guidelines

This section contains a list of dependency requirements and guidelines for user-defined packages. For instructions for setting package dependencies, see IBM webMethods Service Development Help.

When working with user-defined packages, keep in mind the following:

When you create user-defined packages, use the package management functionality provided in IBM webMethods Designer and set the user-defined packages to have a dependency on the adapter package. That way, when the adapter package loads or reloads, the user-defined packages load automatically.
Keep connections for different adapters in separate packages so that you do not create interdependencies between adapters. If a package contains connections for two different adapters, and you reload one of the adapter packages, the connections for both adapters will reload automatically.
If the connections and adapter services of an adapter are defined in different packages:
- A package that contains the connections must have a dependency on the adapter package.
- Packages that contain adapter services must have a dependency on their associated connection package.
Integration Server will not allow you to enable a package if it has a dependency on another package that is disabled. Before you can enable your package, you must enable all packages on which your package depends.
Integration Server will allow you to disable a package even if another package that is enabled has a dependency on it. Therefore, you must manually disable any user-defined packages that have a dependency on the adapter package before you disable the adapter package.
You can give connections, adapter services, and notifications the same name provided that they are in different folders and packages.

Adapter Connections

You create one or more adapter connections at design time to use in integrations. The number of connections you create depends on your integration needs. When an adapter connection is created, the WmART package creates a connection object. An adapter connection enables Integration Server to connect to the back end at run time. You must configure an adapter connection before you can create adapter services or notifications.

Connection State for Adapters

The following table lists the different connection state for adapters:

State	Description
Enabled	Connectivity is established with the backend and the connection is active.
Disabled	Connection is in inactive state.
Suspended	Enabled Connection has failed to establish connectivity with the backend.
Pending enabled	Intermediate state before enabling the connection.

By default, all the connections are in disabled state.

Connection Pools

Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. By default, connection pooling is enabled for all adapter connections.

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 Minimum Pool Size parameter of the connection. 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 parameter, 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. For information about configuring connections, see the installation and user’s guide for the individual adapter.

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

Additionally, the pub.art.service:setAdapterServiceNodeConnection and pub.art.notification:setPollingNotificationNodeConnection services allow you to change the connection associated with an adapter service or polling notification respectively at design time.

Run-Time Connection Allocation for Adapter Services

When an adapter service is invoked, either directly or from a flow service, webMethods Adapter Runtime provides a connection object to the adapter service. This section describes how connections are retrieved and managed and how to dynamically control the type of connection used for each service invocation.

At run time, all connection activity for adapter services is performed inside a transaction context that holds references to connections used while the context is open. This is true regardless of whether the referenced connections are transacted. There is an implicit transaction context that begins at the invocation of a top-level flow service (such as an HTTP invocation of an Integration Server service) and continues until that top-level service exits. Additional contexts can be created using the pub.art.transaction:startTransaction service and ended using pub.art.transaction:commitTransaction or pub.art.transaction:rollbackTransaction. For more information about using these services, see Built-In Services Reference.

When webMethods Adapter Runtime retrieves a connection from a connection pool for use by an adapter service, a reference to that connection is placed in the transaction context, and the connection is not returned to the pool until the transaction context is closed. If another adapter service call is made within the transaction context, Integration Server will first determine whether a connection from the required connection pool and partition is in the context; if so, Integration Server will use the connection from the transaction context to the adapter service instead of requesting another from the connection pool.

Dynamically Selecting a Connection Node

Each connection node should be used to access a single physical resource. In some integration environments, similar functionality is available on multiple physical resources. In these cases, a single adapter service node may be used to access those resources by dynamically specifying which connection node to use for a particular service invocation.

You can run a service using a connection other than the default connection that was associated with the service when the service node was created. To override the default, you must code your flow to pass a value through the pipeline into a service's $connectionName field.

Alternatively, you can use the configured connection for an adapter service, but at run time override the user credentials defined in the connection. To override the user credentials, you must code your flow service to pass values through the pipeline into the adapter service's user name and password fields.

Adapter Services

An adapter service defines an operation that the adapter will perform on an adapter resource. Adapter services operate like Integration Server flow services or Java services. You call adapter services within flow or Java services, and you can audit them from the Integration Server's audit system.

Adapter services have input and output signatures. An input signature describes the data that the service expects to find in the flow service pipeline at run time. An output signature describes the data that the service expects to add to the pipeline when it has successfully executed. You can view an adapter service node's signature on the Input/Output tab of the Adapter Service Editor in IBM webMethods Designer.

Adapter services are based on templates provided with each adapter. Each template represents a specific technique for doing work on a resource, such as using the a template to retrieve specified information from a database.

An adapter service template contains all the code necessary for interacting with the resource but without the data specifications. You provide these specifications when you create a new adapter service in Designer. Before configuring an adapter service, you must assign it a connection that you created earlier.

Adapter Polling Notifications

A polling notification is a facility that enables an adapter to initiate activity on Integration Server, based on events that occur in the adapter resource. A polling notification monitors an adapter resource for changes (such as an insert, update, or delete operation) so that the appropriate flow or Java services can react to the data, such as sending an invoice or publishing an invoice to Integration Server.

You create a polling notification node using Designer. You assign to the notification an adapter connection node that you created earlier.

Polling notifications cannot be directly invoked from a flow service (or from Designer). Instead, the server invokes a polling notification automatically, based on a fixed time interval. When a polling notification determines that a specified event has occurred in the adapter resource, it produces a document describing the event. These documents are automatically published to Integration Server (or IBM webMethods Broker) as they are generated by the notification. The processing of the published document is based on triggers that are configured to invoke flow services when the given document type is published. For more information on Integration Server publishable documents, see Publish-Subscribe Developer’s Guide.

Adapter Listeners and Listener Notifications

Listeners and listener notifications work together to create a much more powerful model for detecting and processing events in the adapter resource than is possible with polling notifications.

With a listener notification, the responsibility for monitoring the adapter resource and processing any events is divided between a listener and its notification(s). A listener object is instantiated and is given a connection when you enable the associated node. The listener object remains active with the same connection to monitor the resource activity until it is disabled (either explicitly or by disabling the containing package, the adapter, the connection, or Integration Server). When the listener detects a publishable event in the resource, it passes an object back to the server. The server will interrogate a configured list of listener notifications associated with the listener node until it finds a listener notification node that can process the event. The listener notification processes the event either asynchronously or synchronously.

Synchronous and Asynchronous Listener Notifications

When you create an asynchronous listener notification, the adapter creates a publishable document type. At run time, when the listener detects an event in the back end, it invokes the asynchronous notification. The asynchronous notification then publishes a document, which has the structure defined by the publishable document type, in either of the following ways:

to IBM webMethods Broker when Integration Server is connected to Broker.
to IBM webMethods Universal Messaging when Integration Server is connected to Universal Messaging.
to IBM webMethods Digital Event Services using IS_DES_CONNECTION alias.
to a JMS queue or topic when Integration Server is connected to a JMS provider.
locally to Integration Server when Integration Server is not connected to Broker or to a JMS provider.

Adapter users can process the document's data any way they want to. For example, they can create an Integration Server trigger that receives the document and executes an Integration Server flow service or a Java service.

At run time, a synchronous listener notification invokes a specified Integration Server service, and potentially receives a reply from the service and delivers the results back to the adapter resource. The listener notification waits until the service has finished processing before it begins to process the next message from the adapter resource. A synchronous listener notification does not publish a document.

Synchronous listener notifications do not support session handling. When a synchronous listener notification calls a service that needs information contained in the session data, that service can fail. However, note that the same service may appear to work for an asynchronous listener notification. This is because asynchronous listener notifications themselves do not execute a service. Instead, an Integration Server trigger, which supports session handling, is used to receive the document and execute an Integration Server flow service or a Java service.

Single-Threaded and Multi-Threaded Listeners

Beginning with Integration Server 9.5, webMethods Adapter Runtime based adapters support single-threaded listeners and multi-threaded listeners, based on the number of threads that a listener uses to process messages coming from the back end. Multi-threaded listeners improve performance by streamlining message processing.

With a single-threaded listener, the adapter processes incoming events from the back end one after the other in the order in which they arrive. The thread executes the most suitable notification for each event.

With a multi-threaded listener, the adapter uses a new thread for each event coming from the back end and processes the messages concurrently, which boosts performance. Therefore, if you have a long-running flow service for processing a message, subsequent messages do not have to wait for the first message to be processed.

Multi-threaded listeners rely on the Integration Server thread pool to concurrently read and process messages. When you enable a multi-threaded listener, for each incoming event from the back end an idle thread from the thread pool is allocated to execute the listener notification. When the maximum number of threads is reached, as specified in the Thread Count parameter when configuring a listener, new events have to wait and are processed only when threads become available.

With a multi-threaded listener, if the thread executing the notification uses a connection providing transaction support, the thread is responsible for committing or rolling back the transaction. In this case, each thread uses a separate connection.

Event Publishing Support for Adapter Notifications

Note: Event Routing component is deprecated from version 10.3 onwards. Event publishing for adapter notifications will not be supported.

Transaction Support

Integration Server considers a transaction to be one or more interactions with one or more resources that are treated as a single logical unit of work. The interactions within a transaction are either all committed or all rolled back. For example, if a transaction includes multiple database inserts, and one or more inserts fail, all inserts are rolled back.

Integration Server supports the following kinds of transactions:

A local transaction, which is a transaction to a resource's local transaction mechanism
An XAResource transaction, which is a transaction to a resource's XAResource transaction mechanism

Integration Server can automatically manage both kinds of transactions, without requiring the adapter user to do anything. Integration Server uses the container-managed (implicit) transaction management approach as defined by the JCA standard and also performs some additional connection management. This is because adapter services use connections to create transactions. However, there are cases where the adapter user needs to explicitly control the transactional units of work.

To support transactions, Integration Server relies on a built-in transaction manager. The transaction manager is responsible for beginning and ending transactions, maintaining a transaction context, enlisting newly connected resources into existing transactions, and ensuring that local and XAResource transactions are not combined in illegal ways.

For more information about transactions, see Transaction Management.

Controlling Pagination

About this task

When using the adapter on Integration Server 8.2 and later, you can control the number of items that are displayed on the adapter Connections screen and 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. For example, to display 50 items per page, specify:

watt.art.page.size=50

For information about working with extended configuration settings, see IBM webMethods Integration Server Administrator’s Guide.