Runtime Connection Allocation for Adapter Services

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

At runtime, all connection activities for adapter services are performed inside a transaction context that holds references to connections used when the context is open. This is true regardless of whether the referenced connections are transacted or not. 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 may be created using the pub.art.transaction:startTransaction and closed using pub.art.transaction:commitTransaction or pub.art.transaction:rollbackTransaction. For more information about using these services, see webMethods Integration Server Built-In Services Reference for your release.

When Integration Servers' 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 first determines whether a connection from the required connection pool and the partition are in the context; if so, Integration Server uses the connection from the transaction context for use by the adapter service instead of requesting another from the connection pool.

When a connection is requested from a particular connection pool, the request may identify a partition in the form of an adapter-generated ConnectionRequestInfo object. A connection pool partition is a logical division within a given connection pool where connection objects in different partitions are used at different times in an adapter-defined way.

If the pool has no available connection in the specified partition, and the pool is not full, then the pool requests a new connection from the associated connection factory, including any provided ConnectionRequestInfo object.

Each connection node must 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.

The connection node used for a particular invocation is determined as follows:

1. The adapter may specify a connection name by overriding the default implementation of the WmAdapterService.getConnectionSpec method to return a WmConnectionSpec object containing the connection name. For more information on using WmConnectionSpec objects, see Implementing WmConnectionSpec.

2. If the connection is not specified using WmAdapterService.getConnectionSpec method, the connection name may be specified on the pipeline in the $connectionName field. Integration Server checks for a value in $connectionName, if the field is part of the service's input signature. For more information about exposing $connectionName field in the service signature, see the Javadoc for WmDescriptor.showConnectionName method.

3. If a connection node name has still not been specified, the service's default connection is used. The default connection is the connection that is used when the adapter service is created, unless it is changed using either the pub.art.service:setAdapterServiceNodeConnection or the wm.art.dev.service:updateAdapterServiceNode service.

To update a service node, in Designer you must either lock the node for editing or check out the node. When the Integration Servers' watt.server.ns.lockingMode property is set to system, you must obtain Write ACL access to the service node that you want to edit before updating the node. For information about obtaining Write ACL access, see the webMethods Service Development Help for your release.

While a connection node defines a general set of connections to a backend resource, it is sometime necessary to connect to the backend using the attributes that are specific to a particular operation or data set. For example, the backend may require that a connection be established with a specific set of user credentials in order to update a given record. If the number of unique attributes is small, it may be possible to define a connection pool with each set of attributes and select the appropriate pool at run time based on the service being called or the data being manipulated. When this is not practical, an adapter must implement connection pool partitioning.

A connection pool partition is a logical division within a given connection pool where connection objects in different partitions are used at different times in an adapter-defined way. Connections in different partitions have different permissions, and are often associated with different users. However, the use of partitions and how they are segregated is entirely determined by the adapter implementation. Connection objects are assigned to a particular partition at the time they are created and remain in the same partition for the life of the object.

When a connection pool is started, it is initialized with connections in the default (null) partition. Additional partitions are created and populated as the connections from those partitions are requested.

The diagram shows the interactions when a connection is obtained in a specified partition of the pool.

The process of requesting a connection from a particular partition begins in the WmAdapterService.getConnectionSpec method. Adapter developers must extend the WmConnectionSpec class to capture any context information necessary to determine the required partition. This may include information from the invocation pipeline, as well as information about the service being invoked, including the metadata parameter settings.

The WmConnectionSpec object returned by the service implementation is then passed to the getConnectionRequestInfo method of the connection factory associated with the selected connection node. The connection factory is then required to identify the connection pool partition based on the information in the WmConnectionSpec object.