WebLogic resource adapters use inbound connections to handle message inflow as well as transactional inflow. These inbound connections require several key components, such as a communications channel and protocol to be used with the EIS, message types recognized by the resource adapter, a Work instance to process the incoming message and deliver it to a message endpoint, and much more.
Overview of Message and Transactional Inflow
Message inflow refers to inbound communication from an EIS to the application server, using a resource adapter. Inbound messages can be part of a transaction that is governed by a Transaction Manager that is external to WebLogic Server and the resource adapter.
The following diagram provides an overview of how messaging and transaction inflow occurs within a resource adapter and the role played by the Work Manager. For details about transactional inflow, see also Transactional Inflow.
Figure 8-1 Messaging and Transactional Inflow Architecture
Description of "Figure 8-1 Messaging and Transactional Inflow Architecture"
Figure 8-1 contains the following components:
A client application, which connects to an application running on WebLogic Server, but which also needs to connect to an EIS
An external system (in this case, an EIS or Enterprise Information System)
An application component (an EJB) that the client application uses to submit outbound requests to the EIS through the resource adapter
A message endpoint application (a message-driven bean and possibly other Java EE components) used for the receipt of inbound messages from the EIS through the resource adapter
The WebLogic Server Work Manager and an associated thread (or threads) to which the resource adapter submits Work instances to process inbound messages and possibly process other actions.
An external Transaction Manager, to which the WebLogic Server Transaction Manager is subordinate for transactional inflow of messages from the EIS
The WebLogic Server Connector container in which the resource adapter is deployed. The container manages the following:
A deployed resource adapter that provides bi-directional (inbound and outbound) communication to and from the EIS.
Multiple managed connections (MC1, ..., MCn), which are objects representing the outbound physical connections from the resource adapter to the EIS.
Connection handles (C-handle) returned to the application component from the connection factory of the resource adapter and used by the application component for communicating with the EIS.
One of perhaps many activation specifications. There is an activation specification (
ActivationSpec) that corresponds to each specific message listener type, MLT-j. For information about requirements for an
ActivationSpecclass, see Chapter 13, Message Inflow in JSR 322: Java EE Connector Architecture 1.6.
One of the connection pools maintained by the container for the management of managed connections for a given
ManagedConnectionFactory(in this case, MCF-2. A Connector container could include multiple connection pools, each corresponding to a different type of connections to a single EIS or even different EISes).
MessageEndpointFactorycreated by the EJB container and used by the resource adapter to create proxies to
MessageEndpointinstances (MDB instances from the MDB pool).
An external message source, which could be an EIS or Message Provider
Inbound Communication Scenario
This section describes a basic inbound communication scenario that may be described using the diagram, showing how inbound messages originate in an EIS, flow into the resource adapter, and are handled by a Message-driven Bean. For related information, see Figure 2-1.
A typical simplified inbound sequence involves the following steps:
The EIS sends a message to the resource adapter.
The resource adapter inspects the message and determines what type of message it is.
The resource adapter may create a
Workobject and submit it to the Work Manager. The Work Manager performs the succeeding work in a separate Thread, while the resource adapter can continue waiting for other incoming messages.
Based on the message type, the resource adapter (either directly or as part of a
Workinstance) looks up the correct message endpoint to which it will send the message.
Using the message endpoint factory corresponding to the type of message endpoint it needs, the resource adapter creates a message endpoint (which is a proxy to a message-driven bean instance from the MDB pool).
The resource adapter invokes the message listener method on the endpoint, passing it message content based on the message it received from the EIS.
The message is handled by the MDB in one of several possible ways:
the MDB may handle the message directly and possibly return a result to the EIS through the resource adapter
the MDB may distribute the message to some other application component
the MDB may place the message on a queue to be picked up by the client
the MDB may directly communicate with the client application.
How Message Inflow Works
To manage message inflow, a resource adapter that supports inbound communication from an EIS to the application server typically includes a proprietary communications channel and protocol, a set of recognized message types, and a dispatching mechanism.
A proprietary communications channel and protocol is required for connecting to and communicating with an EIS. The communications channel and protocol are not visible to the application server in which the resource adapter is deployed. See Proprietary Communications Channel and Protocol.
One or more message types that are recognized by the resource adapter must be established.
A dispatching mechanism is required for dispatching a message of a given type to another component in the application server.
Handling Inbound Messages
A resource adapter may handle an inbound message in a variety of ways. For example, it may:
Handle the message locally, that is, within the
ResourceAdapterbean, without involving other components.
Pass the message off to another application component. For example, it may look up an EJB and invoke a method on it.
Send the message to a message endpoint. Typically, a message endpoint is a message-driven bean (MDB). For more information, see Message Inflow to Message Endpoints (Message-Driven Beans).
Inbound messages may return a result to the EIS that is sending the message. A message requiring an immediate response is referred to as synchronous (the sending system waits for a response). This is also referred to as request-response messaging. A message that does not expect a response as part of the same exchange with the resource adapter is referred to as asynchronous or event notification-based communication. A resource adapter can support asynchronous or synchronous communications for all three destinations listed above.
Depending upon the transactional capabilities of the resource adapter and the EIS, inbound messages can be either part of a transaction (XA) or not (non-transactional). If the messages are XA, the controlling transaction may be coordinated by an external Transaction Manager (transaction inflow) or by the application server's Transaction Manager. See Transactional Inflow.
In most cases, inbound messages in a resource adapter are dispatched through a
Work instance in a separate thread. The resource adapter wraps the work to be done in a
Work instance and submits it to the application server's Work Manager for execution and management. A resource adapter can submit a Work instance using the
scheduleWork() methods depending upon the scheduling requirements of the work.
Proprietary Communications Channel and Protocol
The resource adapter can expose connection configuration information to the deployer by various means; for example, as properties on the
ResourceAdapter bean or properties on the
ActivationSpec object. An alternative is to use the same communication channel for inbound as well as outbound traffic. Thus you can also set configuration information on the outbound connection pool.
Message Inflow to Message Endpoints (Message-Driven Beans)
javax.jms.MessageListenerinterface, including the
onMessage(javax.jms.Message)message listener method. MDBs were bound to JMS components and the JMS subsystem delivered the messages to MDBs by invoking the
onMessage()method on an instance of the MDB. With EJB 2.1, the JMS-only MDB restriction has been lifted.
The main ingredients for message delivery to an MDB by way of a resource adapter are:
An inbound message of a certain type (determined by the resource adapter/EIS contract)
ActivationSpecobject implemented by the resource adapter
A mapping between message types and message listener interfaces
An MDB that implements a given message listener interface
A deployment-time binding between an MDB and a resource adapter
For more information about message-driven Beans, see Message-Driven EJBs in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Deployment-Time Binding Between an MDB and a Resource Adapter
A resource adapter can be deployed independently (as a standalone RAR) or as part of an enterprise application (EAR). An MDB can also be deployed independently (as a standalone JAR) or as part of an enterprise application (EAR). In either case, an MDB whose messages are derived from a resource adapter must be bound to the resource adapter. The following sections describe binding the MDB and resource adapter and subsequent messaging operations.
Binding an MDB and a Resource Adapter
To bind an MDB and a resource adapter, you must:
- Set the
jndi-nameelement in the
weblogic-ra.xmldeployment descriptor for the resource adapter. See Example A- in weblogic-ra.xml Schema.
- Set the
adapter-jndi-nameelement in the
weblogic-ejb-jar.xmldeployment descriptor to match the value set in the corresponding
jndi-nameelement in the resource adapter.
- Assume that the resource adapter is deployed prior to the MDB. (The MDB could be deployed before the resource adapter is deployed; in that case, the deployed MDB polls until the resource adapter is deployed.) When the resource adapter is deployed, the
ResourceAdapterbean is bound into JNDI using the name specified.
- The MDB is deployed, and the MDB container invokes an application server-specific API that looks up the resource adapter by its JNDI name and invokes the specification-mandated
endpointActivation(MessageEndpointFactory, ActivationSpec)method on the resource adapter.
- The MDB container provides the resource adapter with a configured
ActivationSpec(containing configuration information) and a factory for the creation of message endpoint instances.
- The resource adapter saves this information for later use in message delivery. The resource adapter thereby knows what message listener interface the MDB implements. This information is important for determining what kind of messages to deliver to the MDB.
Dispatching a Message
When a message arrives from the EIS to the resource adapter, the resource adapter determines where to dispatch it. The following is a possible sequence of events:
- A message arrives from the EIS to the resource adapter.
- The resource adapter examines the message and determines its type by looking it up in an internal table. The resource adapter determines the message type corresponds to a particular pair (
- The resource adapter determines the message should be dispatched to an MDB.
- Using the
MessageEndpointFactoryfor that type of message endpoint (one to be dispatched to an MDB), the resource adapter creates an MDB instance by invoking
createEndpoint()on the factory.
- The resource adapter then invokes the message listener method on the MDB instance, passing any required information (such as the body of the incoming message) to the MDB.
- If the message listener does not return a value, the message dispatching process is complete.
- If the message listener returns a value, the resource adapter determines how to handle that value. This may or may not result in further communication with the EIS, depending upon the contract with the EIS.
A resource adapter is configured with a mapping of message types and activation specifications. The activation specification is a JavaBean that implements
javax.resource.spi.ActivationSpec. The resource adapter has an
ActivationSpec class for each supported message type. The mapping of message types and activation specifications is configured in the
ra.xml deployment descriptor, as described in Configuring Inbound Connections, For more information about
ActivationSpecs, see Chapter 13, Message Inflow, in JSR 322: Java EE Connector Architecture 1.6.
As described in section 22.214.171.124 of JSR 322: Java EE Connector Architecture 1.6, a resource adapter may provide the Java class name and the interface type of an optional set of JavaBean classes representing administered objects that are specific to a messaging style or message provider. You configure administered objects in the
admin-objects elements of the
weblogic-ra.xml deployment descriptor files. As with outbound connections and other WebLogic resource adapter configuration elements, you can define administered objects at three configuration scope levels:
Group - Specify parameters that apply to all administered objects belonging to a particular administered object group specified in the
ra.xmldeployment descriptor using the
admin-object-groupelement. The properties specified in a group override any parameters specified at the global level. See admin-object-group.
admin-object-interfaceelement (a subelement of the
admin-object-groupelement) serves as a required unique element (a key) to each
admin-object-group. There must be a one-to-one relationship between the
Instance - Under each admin object group, you can specify administered object instances using the
admin-object-instanceelement of the
weblogic-ra.xmldeployment descriptor. These correspond to the individual administered objects for the resource adapter. You can use the
admin-object-propertiessubelement to specify properties at the instance level too; properties specified at the instance level override those provided at the group and global levels. See admin-object-instance.
When an EIS passes a message through a resource adapter to the application server, it may pass a transactional context under which messages are delivered or work is performed. The inbound transaction will be controlled by a transaction manager external to the resource adapter and application server. See Message Inflow to Message Endpoints (Message-Driven Beans).
A resource adapter may act as a bridge between the EIS and the application server for transactional control. That is, the resource adapter receives messages that it interprets as XA callbacks for participating in a transaction with a external Transaction Manager.
WebLogic Server can function as an XA resource to a external Transaction Manager through its interposed Transaction Manager. The WebLogic Server Transaction Manager maps external transaction IDs to WebLogic Server-specific transaction IDs for such transactions.
The WebLogic Server Transaction Manager is subordinate to the external Transaction Manager, which means that the external Transaction Manager ultimately determines whether the transaction succeeds or is rolled back. See Participating in Transactions Managed by a Third-Party Transaction Manager in Developing JTA Applications for Oracle WebLogic Server. As part of the Java EE Connector Architecture 1.6, the ability for a resource adapter to participate in such a transaction is now exposed through a Java EE standard API.
The following process explains how a resource adapter would participate in a external transaction. For more information, see section 15.4, Transaction Inflow Model, in JSR 322: Java EE Connector Architecture 1.6.
The resource adapter receives an inbound message with the transaction context that arrived along with the incoming message.
The resource adapter represents the transaction context using the
The resource adapter creates a new
Workinstance to process the incoming message and deliver it to a message endpoint, and also creates an instance of an
javax.resource.spi.work.ExecutionContext), setting the
Xidit created and also setting a transaction timeout value. Version 1.6 of the Connector Architecture defines a standard class,
TransactionContext, which resource adapters may use instead of the
ExecutionContextfor propagating the transaction context from the EIS to the application server.
The resource adapter submits the
Workobject and the
ExecutionContext) to the Work Manager for processing. At this point, the Work Manager performs the necessary work to enlist the transaction and start it with the WebLogic Server Transaction Manager.
To use a
Create and return a
TransactionContextinstance in the
If the resource adapter uses a
TransactionContext, the adapter must not use an
Subsequent XA calls from the external Transaction Manager are sent through the resource adapter and communicated to the WebLogic Server Transaction Manager. In this way, the resource adapter acts as a bridge for the XA calls between the external Transaction Manager and the WebLogic Server Transaction Manager, which is acting as a resource manager.
Using the Transactional Inflow Model for Locally Managed Transactions
When the resource adapter receives requests from application components running in the same server instance as the resource adapter that need to be delivered to an MDB as part of the same transaction as the resource adapter request, the transaction ID must be obtained from the transaction on the current thread and placed in a
In this case, WebLogic Server does not use the Interposed Transaction Manager but simply passes the transaction on to the Work Thread used for message delivery to the MDB.
Configuring and Managing Long-Running Work
HintsContext.LONGRUNNING_HINT, which if set to
truein a resource adapter
Workclass, causes a
Workinstance to be established as a long-running work item that WebLogic Server schedules in a separate daemon thread, not in a
LONGRUNNING_HINTperforms the same function as the WebLogic Server extension annotation
WebLogic Server extends Connector Architecture 1.6 by providing the ConnectorWorkManagerRuntimeMBean, which contains attributes for configuring and monitoring long-running
Work instances. These attributes, described in the following sections, are also exposed in the WebLogic Server Administration Console.
For more information about the
@LongRunning extension annotation, see
LongRunning in Java API Reference for Oracle WebLogic Server.
Setting the Maximum Number of Concurrent Long-Running Work Instances
Oracle recommends that you minimize the number of long-running
Work instances executing concurrently because each long running work runs in its own daemon thread. Having too many concurrent long-running Work instances can exhaust the thread resources in WebLogic Server and cause a negative impact on server performance and stability. WebLogic Server may introduce restrictions on maximum concurrent long running works allowed in a future release.
You can use the WebLogic Server Administration Console to set the maximum allowed number of concurrent
Work instance requests as follows:
- Select the resource adapter in the Summary of Deployments > Control page.
- Select Configuration > Workload.
- Enter a new value in Maximum Number of Concurrent Long Running Requests, if desired, and click Save.
If you save a new value, the Save Deployment Plan Assistant is displayed, which prompts you to select or enter the path of a deployment plan file. For more information about working with deployment plans, see Understanding WebLogic Server Deployment in Deploying Applications to Oracle WebLogic Server.
Note the following:
You can also view the maximum number of concurrent
Workinstance requests allowed from the Resource Adapter: Monitoring: Workload page in the WebLogic Server Administration Console, as described in Monitoring Long-Running Work.
As an alternative to using the WebLogic Server Administration Console, you can use the
max-concurrent-long-running-requestselement in the
weblogic-ra.xmlfile to set the maximum allowed number of concurrent
Workinstance requests. For information, see connector-work-manager.
Monitoring Long-Running Work
The ConnectorWorkManagerRuntimeMBean exposes long-running run-time information about the resource adapter's specific Work Manager in the following MBean attributes:
ConnectorWorkManagerRuntimeMBean.ActiveLongRunningRequests— Returns the number of current active long-running
ConnectorWorkManagerRuntimeMBean.CompletedLongRunningRequests— Returns the number of completed long-running
ConnectorWorkManagerRuntimeMBean.MaxConcurrentLongRunningRequests— Returns the maximum number of concurrent
Workinstance requests allowed.
To view information about the currently active or completed long-running
Work instance requests using the WebLogic Server Administration Console:
- Select the resource adapter in the Summary of Deployments > Control page.
- Select Monitoring > Workload.
The following information about long-running
Workinstance requests is available from the Long Running Work Managers table:
The column labeled . . . . . . identifies the following
The number of currently active long-running
The number of completed long-running
Max Concurrent Requests Allowed
The maximum number of concurrent
Workinstance requests allowed.