Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.5.0)
Part Number E13981-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

Understanding Message Services

A message service provider is responsible for providing a destination to which clients can send messages and from which message-driven beans can receive messages for processing.

OC4J supports a variety of message service providers for both XA-enabled two-phase commit (2PC) and non-XA enabled transactions.

You can access a message service provider directly or by way of a J2EE Connector Architecture (J2CA) resource adapter such as Oracle JMS Connector. For more information about the Oracle JMS Connector, see "Oracle JMS Connector: J2EE Connector Architecture (J2CA)-Based Provider".

Note:

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

For more information, see the following:

What Message Service Providers Can you use With Your MDB?

Using OC4J, you can use an MDB with any of the following Oracle Enterprise Messaging Service (OEMS) providers:

Note:

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

Oracle JMS Connector: J2EE Connector Architecture (J2CA)-Based Provider

The Oracle JMS Connector is a J2CA 1.5-compliant resource adapter that allows OC4J-managed applications to have a unified mechanism to access any JMS provider that implements JMS 1.1 or 1.02b. Using the Oracle JMS Connector, you can integrate OC4J with various Oracle and non-Oracle JMS providers, as Figure 2-1 shows.

From the perspective of OC4J, J2CA is only used as a means of accessing a message service provider for use with message-driven beans.

Oracle JMS Connector supports both XA factories for two-phase commit (2PC) transactions and non-XA factories for transactions that do not require 2PC.

Figure 2-1 Demonstration of an MDB Interacting with a J2CA JMS Destination

Description of Figure 2-1 follows
Description of "Figure 2-1 Demonstration of an MDB Interacting with a J2CA JMS Destination"

Table 2-7 summarizes the JMS message service providers that the Oracle JMS Connector supports.

Table 2-7 Oracle JMS Connector Support for JMS Message Service Providers

JMS Provider Version

OEMS JMS: In-Memory or File-Based Provider

all

OEMS JMS Database: Advanced Queueing (AQ)-Based Provider

all

IBM WebSphere MQ-based JMS

Server Version 5.3 and 6.0

TIBCO Enterprise for JMS

3.1.0

SonicMQ

6.0

Note:

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

For more information, see the following:

Note:

For a code example of configuring a J2CA message service provider resource adapter and MDB application, see http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-gjra-with-oracleasjms/doc/how-to-gjra-with-oracleasjms.html.

OEMS JMS: In-Memory or File-Based Provider

OEMS JMS is a native Java JMS provider implementation that provides in-memory or file-based persistence and is tightly integrated with OC4J. It is the default JMS provider included with OC4J. Figure 2-2 shows how a client sends an asynchronous request directly to the OEMS JMS queue or topic that is located internally within OC4J. The MDB receives the message directly from OEMS JMS.

Figure 2-2 Demonstration of an MDB Interacting with an OEMS JMS Destination

Description of Figure 2-2 follows
Description of "Figure 2-2 Demonstration of an MDB Interacting with an OEMS JMS Destination"

You can access OEMS JMS directly or by way of the Oracle JMS Connector (see "Oracle JMS Connector: J2EE Connector Architecture (J2CA)-Based Provider").

Note:

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

OEMS JMS supports both XA factories for two-phase commit (2PC) transactions and non-XA factories for transactions that do not require 2PC. For more information on 2PC support, see "How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?". For more information on how to configure OEMS JMS to support XA factories, see "Configuring jms.xml".

For more information, see the following:

OEMS JMS Database: Advanced Queueing (AQ)-Based Provider

OEMS JMS Database is the JMS interface to the Oracle Database Streams Advanced Queueing (AQ) feature. Oracle AQ is the Oracle database-integrated message queuing feature built on the Oracle Streams information integration infrastructure that you install and configure within an Oracle database (see Figure 2-3).

Figure 2-3 Demonstration of an MDB Interacting with an OEMS JMS Database Destination

Description of Figure 2-3 follows
Description of "Figure 2-3 Demonstration of an MDB Interacting with an OEMS JMS Database Destination"

An MDB uses OEMS JMS Database as follows:

  1. The MDB opens a JMS connection to the database using a data source with a username and password. The data source represents the Oracle JMS provider and uses a JDBC driver to facilitate the JMS connection.

  2. The MDB opens a JMS session over the JMS connection.

  3. Any message for the MDB is routed to the onMessage method of the MDB.

At any time, the client can send a message to the Oracle JMS topic or queue on which MDBs are listening. The Oracle JMS topic or queue is located in the database.

Before using Oracle JMS, you must create the appropriate queue or table in the database.

Note:

MDBs only work with certain versions of the Oracle database. See the certification matrix in the JMS chapter of the Oracle Containers for J2EE Services Guide for more information.

You can access OEMS JMS Database directly or by way of the Oracle JMS Connector (see "Oracle JMS Connector: J2EE Connector Architecture (J2CA)-Based Provider").

Note:

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

OEMS JMS Database supports both XA factories for two-phase commit (2PC) transactions and non-XA factories for transactions that do not require 2PC. For more information on 2PC support, see "How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?". For more information on how to configure OEMS JMS to support XA factories, see step 2 in "Installing and Configuring the OEMS JMS Database Provider".

For more information, see the following:

Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter

Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS connector (see "Oracle JMS Connector: J2EE Connector Architecture (J2CA)-Based Provider").

If you choose not to use a J2CA resource adapter, consider the following restrictions:

  • If your MDB uses container-managed transactions and the transaction attribute is set to Required or RequiresNew, you must use the Oracle JMS Connector.

  • To be enlisted in a global, two-phase commit (2PC) transaction, both the JMS producer and consumer must come from a J2CA-based XA connection factory.

    If a JMS producer or consumer is not derived from a J2CA-based XA connection factory, it will not enlist in a global transaction (if present): in this case, JMS will behave as though it is outside the global transaction, even if you create the (non-J2CA) JMS session with a transaction parameter set to true, for example:

    QueueConnection.createQueueSession(true,1)

    In this case, you must invoke the Session methods commit or rollback independent of any global transaction.

    Note:

    In 10.1.3.1 release, by default, OC4J auto-enlists MDB connections only if the MDB uses J2CA and an XA factory. For more information, see "MDB Auto-Enlisting in Two-Phase Commit (2PC) XA Transactions".

  • If you are in a global transaction and you attempt to produce or consume a JMS message from a producer or consumer that is not from a J2CA-based XA connection factory, you will get a run-time JMS exception.

  • Container-Managed Transactions (CMT's) and Bean-Managed Transactions (BMT's) with the OEMS JMS provider (see OEMS JMS: In-Memory or File-Based Provider) are only supported through the use of a J2CA resource adapter. These features will not be supported when using the oc4j.jms.pseudoTransactionEnlistment backward compatibility flag (see "MDB Auto-Enlisting in Two-Phase Commit (2PC) XA Transactions").

Message Service Configuration Options: Annotations or XML? Attributes or Activation Configuration Properties?

As Figure 2-4 shows, there are two ways to configure message service provider options:

In general, Oracle recommends that you use activation configuration properties instead of attributes, whether you choose annotations or XML.

Figure 2-4 Message Service Configuration Options

Description of Figure 2-4 follows
Description of "Figure 2-4 Message Service Configuration Options"

Message Service Configuration Using Annotations

Using annotations, you can configure message service options using the @MessageDrivenDeployment or @MessageDriven annotation: @MessageDrivenDeployment configuration overrides that in @MessageDriven.

If you use @MessageDrivenDeployment, you can configure message service options using nested @ActivationConfigProperty annotations or using @MessageDrivenDeployment attributes: @ActivationConfigProperty configuration overrides @MessageDrivenDeployment attributes.

If you use @MessageDriven, you can configure message service options using nested @ActivationConfigProperty annotations only.

If you configure using @MessageDrivenDeployment attributes, your application can only access a message service provider without a J2CA resource adapter. If later you decide to access your message service provider using a J2CA resource adapter, your application will fail to deploy. If you configure using nested @ActivationConfigProperty annotations, your application can access a message service provider with or without a J2CA resource adapter. Oracle recommends that if you configure using annotations, you should use the @ActivationConfigProperty approach.

Example 2-6 shows both a @MessageDrivenDeployment and @MessageDriven annotation using @ActivationConfigProperty annotations for message service configuration. Note that the DestinationName activation configuration property in the @MessageDrivenDeployment annotation overrides that in the @MessageDriven annotation.

Example 2-6 @MessageDriven and @MessageDrivenDeployment Annotation for a J2CA Message Service Provider

import javax.ejb.MessageDriven;
import oracle.j2ee.ejb.MessageDrivenDeployment;
import javax.ejb.ActivationConfigProperty;
import javax.jms.Message;
import javax.jms.MessageListener;

@MessageDriven(
    activationConfig = {
        @ActivationConfigProperty(
            propertyName="DestinationName", propertyValue="OracleASjms/MyQueue"
        )
    }
)

@MessageDrivenDeployment(
    activationConfig = {
        @ActivationConfigProperty(
            propertyName="DestinationName", propertyValue="OracleASjms/DeployedQueue"
        ),
        @ActivationConfigProperty(
            propertyName="ResourceAdapter", propertyValue="OracleASjms"
        )
    }
)

public class JCAQueueMDB implements MessageListener 
{
    public void onMessage(Message msg) {
        ...
    }
}

Message Service Configuration Using XML

Using XML, you can configure message service options using the orion-ejb-jar.xml file <message-driven-deployment> element or the ejb-jar.xml file <message-driven> element: orion-ejb-jar.xml configuration overrides that in ejb-jar.xml.

If you use the orion-ejb-jar.xml file <message-driven-deployment> element, you can configure message service options using nested <config-property> elements or using <message-driven-deployment> attributes: <config-property> configuration overrides <message-driven-deployment> attributes.

If you use the ejb-jar.xml file <message-driven> element, you can configure message service options using nested <activation-config-property> elements only.

If you configure using orion-ejb-jar.xml file <message-driven-deployment> element attributes, your application can only access a message service provider without a J2CA resource adapter. If later you decide to access your message service provider using a J2CA resource adapter, your application will fail to deploy. If you configure using nested <config-property> elements, your application can access a message service provider with or without a J2CA resource adapter. Oracle recommends that if you configure using XML, you should use the <config-property> approach.

Example 2-8 shows how to use <config-property> elements in the orion-ejb-jar.xml file <message-driven-deployment> element and Example 2-7 shows how to use <activation-config-property> elements in the ejb-jar.xml file <message-driven> element. Note that the DestinationName activation configuration property in the <message-driven-deployment> element overrides that in the <message-driven> element. Also note that in the ejb-jar.xml file <message-driven> element, <activation-config-property> elements are contained in an <activation-config> element.

Example 2-7 ejb-jar.xml <activation-config-property>

<message-driven>
    <ejb-name>JCA_QueueMDB</ejb-name>
    <ejb-class>test.JCA_MDB</ejb-class>
    <messaging-type>javax.jms.MessageListener</messaging-type>
    <transaction-type>Container</transaction-type>
    ...
    <activation-config>
        <activation-config-property>
            <activation-config-property-name>
                DestinationName
            </activation-config-property-name>
            <activation-config-property-value>
                OracleASJMSSubcontext
            </activation-config-property-value>
        </activation-config-property>
    </activation-config>
    ...
</message-driven>

Example 2-8 orion-ejb-jar.xml <config-property>

<message-driven-deployment
    name="JCA_QueueMDB"
    resource-adapter="OracleASjms">
    ...
    <config-property>
        <config-property-name>
            DestinationName
        </config-property-name>
        <config-property-value>
            OracleASJMSRASubcontext
        </config-property-value>
    </config-property>
    ...
</message-driven-deployment>

Configuring Message Services for Two-Phase Commit (2PC) Transactions

OC4J supports 2PC transactions with XA-enabled resources (see "How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?").

Note:

In 10.1.3.1 release, by default, OC4J auto-enlists MDB connections only if the MDB uses J2CA and an XA factory. For more information, see "MDB Auto-Enlisting in Two-Phase Commit (2PC) XA Transactions".

For more information on configuring JMS message service providers to be XA-compliant, see the following:

MDB Auto-Enlisting in Two-Phase Commit (2PC) XA Transactions

In 10.1.2 and 10.1.3.0 releases of OC4J, both normal non-XA JMS connections as well as XA JMS connections were automatically enlisted into an OC4J global transaction by the native OEMS JMS provider. In 10.1.3.1 release, neither XA nor normal JMS connections are enlisted into an OC4J global transaction. If you use the provided JMS APIs, you should explicitly enlist an XA connection into an OC4J global transaction using the javax.jms.XA* implementation of OEMS JMS. You should also explicitly commit or rollback the local transaction of a given JMS session created from a non-XA JMS connection.

For backward-compatibility reasons, it is still possible (but discouraged) to use the auto-enlisting feature in 10.1.3.1 release. Disabled by default, you can enable auto-enlisting by setting global OC4J system property oc4j.jms.pseudoTransactionEnlistment to true.

A J2CA MDB configured to use an XA connection factory (thereby creating an XA session) will auto-enlist as expected. Sessions created from non-XA factories will not enlist. The oc4j.jms.pseudoTransactionEnlistment property is only required to force enlistment of non-XA sessions. This is mostly a concern to legacy applications that do not use J2CA.

For more information, see "Java Message Service (JMS)" in the Oracle Containers for J2EE Services Guide.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us