Programming Considerations

The following sections provide information on advanced WebLogic AQ JMS topics:

■ Section 8.3.1, "Message Driven Beans"

■ Section 8.3.2, "Scalability for Clustered WebLogic MDBs Listening on AQ Topics" ■ Section 8.3.3, "AQ JMS Extensions"

■ Section 8.3.4, "Resource References"

■ Section 8.3.5, "JDBC Connection Utilization" ■ Section 8.3.6, "Oracle RAC Support"

■ Section 8.3.7, "Debugging"

■ Section 8.3.8, "Performance Considerations"

Table 8–4 Example AQ JMS Foreign Server Destinations

Local JNDI Name Remote JNDI Name

jms/myQueue Queues/userQueue

Programming Considerations

8.3.1 Message Driven Beans

MDBs interoperate with AQ JMS by using a configured foreign server. See

Section 8.2.2.3, "Configure a JMS Foreign Server." 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.

SeeDeveloping Message-Driven Beans for Oracle WebLogic Server.

8.3.2 Scalability for Clustered WebLogic MDBs Listening on AQ Topics

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 same data source (or a data source that uses the same database username and

password).

■ Use 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 on shared subscriptions, see "Advanced Messaging Features for High Availability" in Developing JMS Applications for Oracle WebLogic Server.

8.3.3 AQ JMS Extensions

AQ JMS extension API's 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 a 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 which provides AQ JMS extension APIs. For example:

. . .

// Implements wrapping and can’t 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

Programming Considerations

deployment descriptor. This limitation is specific to AQ JMS, as resource references only support extensions that are exposed using Java 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 Java interfaces for its extensions. With AQ JMS, avoiding wrapping does not disable automatic JTA transaction enlistment, nor does it prevent pooling, as AQ JMS obtains these capabilities implicitly through its embedded use of WebLogic data sources.

8.3.3.1 Using AdtMessage

An AdtMessage is a special type of AQ JMS extension that supports Oracle Abstract Data Types (ADTs). ADTs consists of a data structure and subprograms that manipulate data in an Oracle database.

See:

■ "Using Oracle Java Message Service (OJMS) to Access Oracle Streams Advanced

Queuing" and "Object Type Support" in Oracle Streams Advanced Queuing User's Guide

■ "Data Abstraction" in Oracle Database PL/SQL Language Reference

8.3.4 Resource References

If you choose to use the resource references and the resource type is

javax.jms.XXXConnectionFactory, WebLogic wraps the AQ JMS objects passed to a user application. If you also use the AQ JMS extension APIs, they must be unwrapped as described in Section 8.3.3, "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.

8.3.5 JDBC Connection Utilization

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.

Advanced Topics

8.3.6 Oracle RAC Support

The following section provides information on 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.

8.3.7 Debugging

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.

8.3.8 Performance Considerations

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>');