Programming WebLogic Resource Adapters
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, as described in Transactional Inflow.
Figure 7-1, Messaging and Transactional Inflow Architecture, on page 7-2 contains the following components:
ActivationSpec) that corresponds to each specific message listener type, MLT-j. For information about requirements for an
ActivationSpecclass, see Chapter 12, "Message Inflow" in the J2CA 1.5 Specification.
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).
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, Connector Architecture Overview, on page 2-5.
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.
Workinstance) looks up the correct message endpoint to which it will send the message.
ResourceAdapterbean, without involving other components.
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.
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.
Prior to EJB 2.1, a message-driven bean (MDB) supported only Java Message Service (JMS) messaging. That is, an MDB had to implement the
javax.jms.MessageListener interface, 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 to accommodate the delivery of messages from inbound resource adapters. The main ingredients for message delivery to an MDB by way of a resource adapter are:
ActivationSpecobject implemented by the resource adapter
For more information about message-driven Beans, see Message-Driven EJBs in Programming WebLogic Enterprise JavaBeans.
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.
ResourceAdapterbean is bound into JNDI using the name specified.
endpointActivation(MessageEndpointFactory, ActivationSpec)method on the resource adapter.
ActivationSpec(containing configuration information) and a factory for the creation of message endpoint instances.
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.
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 12, "Message Inflow" in the J2CA 1.5 Specification.
As described in section 22.214.171.124 of the J2CA 1.5 Specification, 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:
default-propertieselement. See default-properties.
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-interface element (a subelement of the
admin-object-group element) serves as a required unique element (a key) to each
admin-object-group. There must be a one-to-one relationship between the
admin-object-interface element in
weblogic-ra.xml and the
admin-object-interface element in
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.
This section discusses how transactions flow into WebLogic Server from an EIS and a resource adapter. A transaction inflow contract allows the resource adapter to handle transaction completion and crash recovery calls initiated by an EIS. It also ensures that ACID properties of the imported transaction are preserved. For more information on transaction inflow, see Chapter 14, "Transaction Inflow" of the J2CA 1.5 Specification.
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 Programming WebLogic JTA. As part of the J2EE 1.5 Connector Architecture, the ability for a resource adapter to participate in such a transaction is now exposed through a J2EE standard API.
The following illustrates how a resource adapter would participate in a external transaction. For more information, see section 14.4, "Transaction Inflow Model" of the J2CA 1.5 Specification.
javax.resource.spi.work.ExecutionContext), setting the
Xidit created and also setting a transaction timeout value.
Workobject to process the incoming message and deliver it to a message endpoint.
Workobject and the
ExecutionContextto 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.
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 an