You might find it helpful to set up your AQ JMS queues and topics in your Oracle Database before you configure WebLogic Server to integrate with AQ JMS.

For more detailed information on using and configuring AQ, see Introduction to Oracle Database Advanced Queuing in Oracle Streams Advanced Queuing User's Guide.

The following sections describe one configuration method:

• Create Users and Grant Permissions
  
• Create AQ Queue Tables
  
• Create a JMS Queue or Topic
  
• Start the JMS Queue or Topic
  

The following sections provide information about how to configure WebLogic Server to interoperate with AQ JMS:

• Configure a WebLogic Data Source for AQ JMS
  
• Configure a JMS System Module
  
• Configure a JMS Foreign Server
  
• Configure JMS Foreign Server Connection Factories
  
• Configure AQ JMS Foreign Server Destinations
  

Message Driven Beans (MDBs) interoperate with AQ JMS by using a configured foreign server. See Overview.

The following are the considerations for MDBs when interoperating with AQ JMS:

• Set the following WebLogic Server properties to minimize the number of JMS sessions used and to control the MDB polling interval:

• —Dweblogic.mdb.message.MinimizeAQSessions=true

  This property reduces the number of AQ JMS sessions in the MDB layer and there by reduce the number of JDBC connections held by the MDB. Also, the value true for this property will be effective only when weblogic.ejb.container.MDBDestinationPollIntervalMillis is set to a value more than 5000 milliseconds.

  -Dweblogic.ejb.container.MDBDestinationPollIntervalMillis=6000

• The message driven parameters initial-context-factory and provider-url are not supported as these parameters are supplied as part of the JMS Foreign Server configuration

• The destination type for the MDB destination in the ejb-jar.xml file should be configured to either: javax.jms.Queue or javax.jms.Topic

• Additional MDB configuration is required to enable container managed transactions, durable topic subscriptions, and other MDB features.

See Understanding Message-driven Beans in Developing Message-Driven Beans for Oracle WebLogic Server.

Use a shared subscription to implement a one-copy-per-application messaging strategy when a clustered MDB listens to an AQ topic.

The subscribers that share a subscription need to:

• Be on different VMs.

• Use the same data source (or a data source that uses the same database user-name and password).

• Use the same subscription name.

The database username acts as the client ID for the subscription. When the client ID is the same for a same-named subscription, the subscription in AQ is shared. For more information about shared subscriptions, see Advanced Messaging Features for High Availability in Developing JMS Applications for Oracle WebLogic Server.

AQ JMS extension APIs are supported by AQ JMS-specific classes. You can invoke the AQ JMS extensions, after casting the standard JMS objects (such as connection factories and destinations) to proprietary AQ JMS classes. For example:

. . .
import oracle.jms.AQjmsFactory;
. . .
ConnectionFactory myCF = (ConnectionFactory) jndiCtx.lookup("aqjms/testCF");
AQjmsFactory myCF = (AQjmsFactory) myCF;
myCF.someProprietaryAQJMSmethod(..);
. . .

When you use resource references for an AQ JMS connection factory, WebLogic Server wraps the underlying AQ JMS connection factory with a wrapper object. This wrapper object implements the JMS standard API, but it cannot cast it to an AQ JMS class that provides AQ JMS extension APIs. For example:

. . .
// Implements wrapping and cannot cast to AQ JMS
<resource-ref>
    <res-ref-name>aqjms/testCF</res-ref-name>
    <res-type>javax.jms. ConnectionFactory</res-type>
    <res-auth>Application</res-auth>
  </resource-ref>
. . .

To avoid the wrapping, users can specify the java.lang.Object as the resource type of the resource reference instead of javax.jms.XXXConnectionFactory in the deployment descriptor. This limitation is specific to AQ JMS, as resource references support only extensions that are exposed using Jakarta interfaces. For example:

. . .
// Use for AQ JMS extensions
<resource-ref>
    <res-ref-name>aqjms/testCF</res-ref-name>
    <res-type>java.lang.Object</res-type>
    <res-auth>Application</res-auth>
  </resource-ref>
. . .

AQ JMS does not define Jakarta interfaces for its extensions. With AQ JMS, avoiding wrapping does not disable automatic JTA transaction enlistment, nor does it prevent pooling, because AQ JMS obtains these capabilities implicitly through its embedded use of WebLogic data sources.

• Using AdtMessage
  

If you use the resource references and the resource type is javax.jms.XXXConnectionFactory, then the WebLogic wraps the AQ JMS objects passed to a user application. If you also use the AQ JMS extension APIs, then they must be unwrapped as described in AQ JMS Extensions.

WebLogic resource reference wrappers do not automatically pool AQ JMS connections. Instead, AQ JMS server-side integration depends on data source connection pooling to mitigate the overhead of opening and closing JMS connections and sessions. WebLogic resource references disable pooling because the AQ JMS provider JMS connection factory is always pre-configured with a client identifier, which in turn, causes WebLogic resource references to disable its pooling feature.

An AQ JMS session holds a JDBC connection until the JMS session is closed, regardless of whether the connection uses a data source or a JDBC URL. Oracle recommends that you close an AQ JMS session if the session becomes idle for an extended period of time. Closing the JMS session releases the JDBC connection back to the WebLogic data source pool or releases the database and network resources for a JDBC URL.

The following section provides information about limitations in Oracle RAC environments:

• Oracle RAC environments require the configuration of WebLogic Multi data sources to provide AQ JMS Oracle RAC failover. See Using WebLogic Server with Oracle RAC in Administering JDBC Data Sources for Oracle WebLogic Server.

• Oracle RAC failover is not supported when using a WebLogic AQ JMS stand alone client for this release.

To use AQ JMS tracing and debugging, set the following system property: oracle.jms.traceLevel.

The value of this property is an integer ranging from 1 to 6 where a setting of 6 provides the finest level of detail. The trace output is directed to the standard output of the running JVM.

In releases prior to Oracle RDBMS 11.2.0.2, statistics on the queue table are locked by default which causes a full table scan for each dequeue operation. To work around this issue, unlock the queue tables and collect the statistics. For example:

exec DBMS_STATS.UNLOCK_TABLE_STATS ('<schema>','<queue table>');

exec DBMS_STATS.gather_table_stats('<schema>','<queue table>');

exec DBMS_STATS.LOCK_TABLE_STATS ('<schema>','<queue table>');

Stand alone clients and server-side applications have different security semantics and configuration. If security is a concern, read this section carefully and also reference the WebLogic lock-down document for general information about how to secure a WebLogic Server or Cluster (see Lock Down WebLogic Server in Securing a Production Environment for Oracle WebLogic Server). The following sections outlines security considerations for this release:

• Configuring AQ Destination Security
  
• Access to JNDI Advertised Destinations and Connection Factories
  
• Controlling Access to Destinations that are Looked Up using the JMS API
  

A WebLogic Messaging Bridge communicates with the configured source and target bridge destinations. For each mapping of a source destination to a target destination, you must configure a messaging bridge instance. Each messaging bridge instance defines the source and target destination for the mapping, a message filtering selector, a QOS, transaction semantics, and various reconnection parameters.

If you have AQ foreign destinations that are not local to the server running the application or MDBs sending and receiving messages, you must configure a messaging bridge instance on the server that is local to the AQ foreign destinations. A local database connection is used in the process of sending and receiving messages from AQ destinations.

For more information on the WebLogic Messaging Bridge, see Understanding the Messaging Bridge in Administering the WebLogic Messaging Bridge for Oracle WebLogic Server.

• Create a Messaging Bridge Instance
  

You can create WebLogic AQ JMS standalone clients that can look up AQ JMS connection factories and destinations defined by a JMS foreign server using a JDBC URL. The client must have the following jars on the client-side classpath: $MW_HOME/oracle_common/modules/oracle.jdbc/aqapi.jar, $MW_HOME/oracle_common/modules/features/com.oracle.db.jdbc7-no-dms.jar, and one of the following WebLogic client jars: wlthint3client.jar or weblogic.jar.

For applications running outside the WebLogic Server's JVM:

• A configured WebLogic JMS foreign server references the database's URL, as well as other JDBC driver configurations. See Configure a Foreign Server using a Database's JDBC URL.

• Local JNDI names are defined for AQ JMS connection factories and destinations as part of the WebLogic JMS Foreign Server configuration. These JNDI names are configured to map to existing AQ connection factories and destinations.

• Standalone clients reference local JNDI names. Unlike applications that run on WebLogic Server, standalone clients need to ensure that the driver and AQ client are on the classpath.

• Configure a Foreign Server using the Database's JDBC URL
  
• Limitations when using Standalone WebLogic AQ JMS Clients