7 Interoperating with Oracle AQ JMS

This chapter describes how Oracle WebLogic Server applications interoperate with Oracle Streams Advanced Queuing (AQ) through the JMS API using either WebLogic Server resources (Web Apps, EJBs, MDBs) or stand-alone clients.

See Oracle Streams Advanced Queuing User's Guide.

Overview

AQ JMS uses a database connection and stored JMS messages in a database accessible to an entire WebLogic Server cluster, enabling the use of database features and tooling for data manipulating and backup. Your WebLogic Server installation includes all the necessary classes, no additional files are required in the WebLogic Server classpath.to interoperate with Oracle AQ JMS.

WebLogic AQ JMS uses the WebLogic JMS Foreign Server framework to allow WebLogic Server applications and stand-alone clients to lookup AQ JMS connection factories and destinations using a standard the WebLogic JNDI context, and to allow applications and clients to load and invoke AQ JMS using standard Java EE APIs. The required references to the database, JDBC driver, and data source are configured as part of this framework.

For applications running within the WebLogic Server's JVM:

  • A configured WebLogic Data Source references a particular JDBC driver, pools JDBC connections, and provides connectivity to the Oracle database hosting AQ JMS.

  • A configured WebLogic Foreign Server references the data source.

  • 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.

  • In turn, WebLogic Server applications, such as MDBs, reference the local JNDI names.

Using AQ Destinations as Foreign Destinations

AQ foreign destinations must be local to the server running the application or MDBs sending/receiving messages. An application that is running on one WebLogic Server instance cannot look up and use an AQ JMS foreign server and data source that is registered on another WebLogic Server instance. WebLogic AQ JMS uses a data source/DB connection that does not support remote connectivity. An alternative is to use a messaging bridge between AQ destinations in one domain and applications/MDBs running in another domain. See WebLogic Messaging Bridge.

Driver Support

WebLogic AQ JMS requires a JDBC driver to communicate with the Oracle database. Only the Oracle JDBC 11g thin driver, included in your WebLogic Server installation, is supported for this release. Oracle OCI JDBC Driver and non-Oracle JDBC Drivers are not supported.

Transaction Support

Global XA (JTA) transactions and local JMS transacted session transactions are supported. Global transactions require use of XA based connection factories, while local transactions use non-XA based JMS connection factories.

  • If you select a non-XA JDBC driver, you can only use WebLogic AQ JMS in local transactions.

  • If you select an XA JDBC driver, you can use WebLogic AQ JMS in both local and global transactions.

  • This release does not support non-XA JDBC driver data sources with any of the global transaction options such as Logging Last Resource (LLR), One-Phase Commit (JTS), and Emulated Two-Phase Commit. If Supports Global Transactions is selected, WebLogic Server logs a warning message.

  • Global transactions are only supported with an XA JDBC driver One-Phase commit optimization. If you use the same XA capable data source for both AQ JMS and JDBC operations, the XA transactional behavior is equivalent to having two connections in a single data source that is treated as a single resource by the transaction manager. Therefore, if the AQ JMS and JDBC operations are invoked under the same JTA transaction, and no other resources are involved in the transaction, the transaction uses One-Phase commit optimization instead of Two-Phase commit; otherwise read-only optimization is used.

See "Understanding Transactions" in Programming JMS for Oracle WebLogic Server

Oracle RAC

WebLogic AQ JMS supports Oracle Real Application Clusters (Oracle RAC) with the use of WebLogic Multi Data Sources to provide failover in a Oracle RAC environment. See "Using WebLogic Server with Oracle RAC" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.

Note:

Oracle does not recommend configuring multi data sources for Load balancing with AQ JMS. AQ JMS and AQ usage scenarios have natural hot spots that can cause over synchronization when the load is spread among Oracle RAC instances. Under the right circumstances, it can cause significant performance degradation

MBean and Console Support

Except for purposes of interoperating with AQ JMS using a JMS Foreign Server, there are no AQ JMX specific MBeans and no support for configuring AQ JMS in the Administration Console. Use SQL scripts or other tools for AQ administration and monitoring, such as AQ queue table creation/removal, destination creation/removal, and statistics query.

Migrating from OC4J

For information on how to migrate your AQ JMS applications from Oracle OC4J to Oracle WebLogic Server, see "Upgrading OEMS JMS Database Persistence" in Oracle Fusion Middleware Upgrade Guide for Java EE.

Configuring WebLogic Server to Interoperate with AQ JMS

The following sections provide information on one method of configuring AQ JMS queues and topics in an Oracle database and configuring a JMS foreign server in WebLogic Server so applications can lookup AQ JMS connection factories and destinations in the WebLogic JNDI context.

After you have prepared your AQ JMS queues and topics, you can perform the remaining configuration tasks using either the WebLogic Console or the WLST command line interface.

Configure Oracle AQ in the Database

Before you can start configuring your WebLogic Server resources, you need ensure that there are AQ JMS queues and topics in your Oracle database. The following sections describe one configuration method:

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

Create Users and Grant Permissions

Create users in the database and grant them AQ JMS permissions. Use a database user with administrator privileges to perform the following task:

  • Using the Oracle SQL*Plus environment, log in with an administrator login.

    connect / as sysdba;

  • Create the JMS user schema. For the following example, the user name is jmsuser and the password is jmsuserpwd.

    Grant connect, resource TO jmsuser IDENTIFIED BY jmsuserpwd;

  • Grant the AQ user role to jmsuser.

    Grant aq_user_role TO jmsuser;

  • Grant execute privileges to AQ packages.

    Grant execute ON sys.dbms_aqadm TO jmsuser;

    Grant execute ON sys.dbms_aq TO jmsuser;

    Grant execute ON sys.dbms_aqin TO jmsuser;

    Grant execute ON sys.dbms_aqjms TO jmsuser;

Create AQ Queue Tables

Each JMS queue or topic for AQ JMS is backed by an AQ queue table. Each queue table serves as a repository for JMS messages. A JMS queue or topic (see Create AQ Queue Tables) is a logical reference to the underlying AQ queue table.

AQ queue tables are created within individual JMS user schemas and can be defined using Oracle SQL*PLUS. For example:

connect jmsuser / jmsuserpwd;

Configuring an AQ queue table requires a minimum of three parameters: the name of the queue table, the payload type, and a flag for whether the AQ queue table accepts multiple consumers. For example:

dbms_aqadm.create_queue_table(
     queue_table=>"myQueueTable",
     queue_payload_type=>'sys.aq$_jms_text_message',
     multiple_consumers=>false
);

where:

  • queue_table: The queue table name. Mixed case is supported if the database is 10.0 but the name must be enclosed in double quotes. Queue table names must not be longer than 24 characters.

  • queue_payload_type: The message type. Use sys.aq$_jms_message to support all JMS message interface types.

  • multiple_consumers: Set false for queues; set true for topics.

For more information on creating queue tables, see "CREATE_QUEUE_TABLE Procedure" in Oracle Database PL/SQL Packages and Types Reference.

Create a JMS Queue or Topic

AQ JMS queues are the JMS administrative resource for both queues and topics. Once the AQ queue table is created, you can create a AQ JMS queue within individual JMS user schemas using Oracle SQL*PLUS. For example:

connect jmsuser/jmsuserpwd;

The PL/SQL procedure for creating a queue or topic has the following form:

dbms_aqadm.create_queue(
     queue_name=>'userQueue',
     queue_table=>'myQueueTable'
);

where:

  • queue_name is the user defined name for the JMS queue.

  • queue_table must point to an existing AQ queue table.

For more information on creating queue tables, see "CREATE_QUEUE Procedure" in Oracle Database PL/SQL Packages and Types Reference.

Start the JMS Queue or Topic

Before first use, a AQ JMS queue must be started. Using the JMS user schema, execute the following PL/SQL procedure where queue_name represents the AQ JMS queue name.

connect jmsuser / jmsuserpwd
dbms_aqadm.start_queue(queue_name=>'userQueue'

For more information on starting queues, see "START_QUEUE Procedure" in Oracle Database PL/SQL Packages and Types Reference.

Configure WebLogic Server

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

Configure a WebLogic Data Source

WebLogic Server applications (such as MDBs, EJBs, and Web apps) that use AQ JMS configure a data source for the Oracle database that provides the AQ JMS service. In most situations, this data source is dedicated to AQ JMS usage because it uses the JMS user and password to connect to the schema in the database. It does support multiple queues and topics if they are created in the schema used in the database connection. When configuring your data source:

  • Select the Oracle Thin Driver.

  • Select the driver type based on the type of transactions required for AQ JMS:

    • Select a non-XA based JDBC driver for use with AQ JMS in local transactions.

    • Select a XA based JDBC driver for use with AQ JMS in either in global transactions or in local transactions.

  • When configuring a data source for non-XA drivers, do not select the Supports Global Transactions option. This release does not support non-XA JDBC driver data sources with any of the global transaction options such as LLR, JTS, and Emulate Two-Phase Commit. If the global transaction option is selected, the server instance logs a warning message. Global transactions are supported with XA-based JDBC drivers.

  • Configure the database user name and password in the data source connection pool configuration. Identity-based connection pools are not supported.

See "Configuring JDBC Data Sources" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.

Configure a JMS System Module

Configure a dedicated JMS system module to host a JMS foreign server for AQ resources. Target the module at the WebLogic Server instances or the cluster that needs to host the foreign JNDI names. See:

Configure a JMS Foreign Server

In your JMS Foreign Server configuration:

  • Specify oracle.jms.AQjmsInitialContextFactory as the JNDI Initial Context Factory.

  • Configure the JDBC data sources needed for your application environment.

See:

Reference a Data Source

Specify the datasource JNDI property which is the JNDI location of a locally bound WLS data source.

For Example:

<foreign-server>
<initial-context-factory>oracle.jms.AQjmsInitialContextFactory</initial-context-factory>
<jndi-property>
<key>datasource</key>
<value>jdbc/aqjmsds</value>
</jndi-property>
</foreign-server>

The value of the datasource JNDI property is the name of the data source configured to access the AQ JMS Oracle database. No other configuration information is required.

See Configure a WebLogic Data Source.

Configure JMS Foreign Server Connection Factories

Once you have created a JMS Foreign Server, you can create JNDI mappings for the AQ JMS connection factories in the WebLogic Server JNDI tree. Unlike destinations, AQ JMS does not require connection factories to be redefined in the Oracle database. Instead, a predefined JNDI name is specified when identifying the remote JNDI name for a connection factory. The remote JNDI name for the AQ JMS connection factory is one of the following:

Table 7-1 Remote JNDI names for AQ JMS Connection Factories

<AQ JMS Prefix Value> JMS Interface

QueueConnectionFactory

javax.jms.QueueConnectionFactory

TopicConnectionFactory

javax.jms.TopicConnectionFactory

ConnectionFactory

javax.jms.ConnectionFactory

XAQueueConnectionFactory

javax.jms.XAQueueConnectionFactory

XATopicConnectionFactory

javax.jms.XATopicConnectionFactory

XAConnectionFactory

javax.jms.XAConnectionFactory


For example, consider two connection factories configured for an AQ JMS Foreign Server:

Table 7-2 AQ JMS Foreign Server Example Connection Factories

Local JNDI Name RemoteJNDI Name

jms/aq/myCF

ConnectionFactory

aqjms/orderXaTopicFactory

XATopicConnectionFactory


When a WebLogic application looks up a JMS factory at jms/aq/myCF, the application gets the AQ JMS object which implements the JMS javax.jms.ConnectionFactory interface. When a WebLogic application looks up a JMS factory at aq/orderXaTopicFactory, the application gets the AQ JMS object which implements the JMS javax.jms.XAToicConnectionFactory interface.

To configure a AQ JMS foreign server connection factory, you need to:

  • Specify Local and Remote JNDI names

    • The local JNDI name is the name that WebLogic uses to bind the connection factory into the WebLogic JNDI tree. The local JNDI name must be unique so that it doesn't conflict with an other JNDI name advertised on the local WebLogic Server.

    • The Remote JNDI name is the name that WebLogic passes to AQ JMS to lookup AQ JMS connection factories.

    When configuring AQ JMS for use in global transactions, use an XA based connection factory; otherwise configure a non-XA based connection factory.

  • No other configuration parameters are required.

See:

Configure AQ JMS Foreign Server Destinations

When configuring an AQ JMS foreign destination, you need to configure the following:

  • Local JNDI name—the name that WLS uses to bind the destination into the WebLogic JNDI tree. The local JNDI name must be unique so that it doesn't conflict with any other JNDI names advertised on the local WebLogic Server instance.

  • Remote JNDI name—the name that WLS passes to AQ JMS to do a lookup. AQ JMS requires the Remote JNDI name to be in the following syntax:

    • If the destination is a queue, the remote JNDI name must be Queues/<queue name>.

    • If the destination is a topic, the remote JNDI name must be Topics/<topic name>

Similar to connection factories, AQ JMS destinations require a remote JNDI name with a prefix to identify the JMS object type. There are two values for destinations:

Table 7-3 AQ JMS Prefix Value of the JMS Interface

AQ JMS Prefix Value JMS Interface

Queues

Javax.jms.Queue

Topics

javax.jms.Topic


Unlike AQ JMS connection factory JNDI names, the value for the destination name represents the AQ JMS destination defined in the database. See Chapter 7, "Create a JMS Queue or Topic." For example, consider the two destinations configured for an AQ JMS Foreign Server in the following table:

Table 7-4 Example AQ JMS Foreign Server Destinations

Local JNDI Name Remote JNDI Name

jms/myQueue

Queues/userQueue

AqTopic

Topics/myTopic


A WebLogic application looking up the location jms/myQueue references the AQ JMS queue defined by userQueue. Looking up the location AqTopic references the AQ JMS topic defined by myTopic.

See:

Programming Considerations

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

Message Driven Beans

MDBs interoperate with AQ JMS by using a configured foreign server. See 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.

SeeProgramming Message-Driven Beans for Oracle WebLogic Server.

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 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.

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.

Note:

Not supported with Message-Driven Beans (MDBs).

See:

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 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.

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.

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 Configuring and Managing 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.

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.

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

Advanced Topics

The following sections provide information on advanced interoperability topics when WebLogic Server applications interoperate with AQ JMS.

Security Considerations

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 on how to secure a WebLogic Server or Cluster (see Securing a Production Environment for Oracle WebLogic Server). The following section outlines security considerations for this release:

Configuring AQ Destination Security

ENQUEUE and/or DEQUEUE permission must be configured for the database user in AQ to allow destination lookups as well as to allow enqueues and dequeues.

The following usernames must be given enqueue and/or dequeue permission:

  • For stand-alone clients:

    • The configured JMS Foreign Server username, as specified using the java.naming.security.principal property.

    • For Java code that passes a username using the JMS ConnectionFactory API createConnection() method, this username requires permission.

  • For server-side applications:

    • The Database User Name is configured on the WebLogic Data Source.

    • Do not give permission for a username specified for JDBC Data Source clients that pass a username using the JMS ConnectionFactory API createConnection() method: this username is a WebLogic username, not a database username.

To understand which JDBC connection credentials and permissions that are used for AQ lookups, enqueues, and dequeues, see "Queue Security and Access Control" in Oracle Streams Advanced Queuing User's Guide.

Note:

A permission failure while looking up a destination will manifest as a "name not found" exception thrown back to application caller, not a security exception.

Access to JNDI Advertised Destinations and Connection Factories

As described earlier, local JNDI names for connection factories and destinations must be configured as part of the JMS Foreign Server configuration task. You can optionally configure security policies on these JNDI names, so access checks occur during JNDI lookup based on the current WebLogic credentials. The current WebLogic credentials depend on the client type.

Once an application's WebLogic JNDI lookup security policy credential check passes for a destination, a JMS Foreign Server destination automatically looks up the destination resources in Oracle AQ using a JDBC connection.

For stand-alone clients, the credential used for the second part of a destination lookup process are based on the username and password that is configured on the JMS Foreign Server.

For server-side application JDBC Data Source clients, the credential used for this second destination lookup is based on the database username and password configured as part of the data source. Note that the credential used to gain access to this data source is the current WebLogic credential. It is possible to configure a WebLogic security policies on the data source. The WebLogic data source Identity Based Connection Pooling feature is not supported for this purpose.

As previously mentioned, the database credential must have AQ JMS enqueue or dequeue permission on a destination in order to be able to successfully lookup the destination. See Configuring AQ Destination Security.

Controlling Access to Destinations that are Looked Up using the JMS API

The JMS QueueSession and TopicSession APIs provide an alternative to JNDI for looking up destinations, named createQueue() and createTopic() respectively. See "How to Lookup a Destination" in Programming JMS for Oracle WebLogic Server.

The createQueue() and createTopic() calls use the database credential associated with the JMS connection. The following sections describe how to set this credential.

Additional Security Configuration for Stand-alone Clients

The following section provides security configuration information for stand-alone clients:

  • Network communication from a client into WebLogic occurs when establishing a JNDI initial context and when performing any subsequent JNDI lookups. To ensure secure communication and avoid plain text on the wire, use an SSL capable protocol (such as t3s or https). The credentials used for WebLogic login, as well as the JMS Foreign Server credentials that are configured for database login, are passed plain-text on the wire unless SSL is configured.

  • Network communication is direct from the client to the database when communicating with AQ. This communication is controlled by the JDBC URL configuration, and is in plain text unless the JDBC URL is configured to use SSL. Stand-alone clients communicate directly with the database over a database connection when using the AQ JMS APIs, their JMS requests do not route through a WebLogic server.

  • WebLogic Server username and password: The network login from a client into WebLogic is performed as part of establishing the JNDI initial context. The username and password properties that are optionally supplied when creating the context become the WebLogic identity (the property names are Context.SECURITY_PRINCIPAL = "java.naming.security.principal" and Context.SECURITY_CREDENTIALS = "java.naming.security.credentials" respectively). This becomes the credential that is checked for subsequent JNDI lookups. The credential is also implicitly associated with current thread, and so becomes the credential used for subsequent WebLogic operations on the same thread, but this is not the credential used for AQ JMS operations.

  • The javax.jms.ConnectionFactory createConnection() method has an optional username and password. For stand-alone clients, these override the context credentials that were configured as part of the JMS Foreign Server configuration. AQ JMS creates a database connection with the specified user identity. If createConnection() is called without a username and password, then the database connection is created using the username and password that was configured as part of the JMS Foreign Server configuration.

  • Do not include a username/password directly in the JDBC URL. Instead use the JMS Foreign Server username and password.

  • Do not configure a username and password on the JMS Foreign Server connection factory. The resulting behavior is unsupported.

Additional Security Configurations for Server-side Applications

The following section provides security configuration information for server-side applications.

  • Do not configure a java.naming.security.principal or a credential on the JMS Foreign Server unless the same JMS Foreign Server is also being used to support stand-alone clients.

  • Do not configure a username and password on the JMS Foreign Server connection factory. The resulting behavior is unsupported.

  • Network communication from the server to the database (server-side applications) is controlled by data source configuration, and is in plain text unless the data source is configured to use SSL.

  • The javax.jms.ConnectionFactory createConnection() method has an optional username and password. For server-side JMS AQ applications, the method assumes the username is for a WebLogic user and authenticates it with the WebLogic server. This behavior deviates from other kinds of JMS AQ clients, where the username is instead treated as a database user. When configured with a WebLogic data source, AQ JMS delegates the authentication to the WebLogic data source and AQ JMS inherits the WebLogic user semantics.

  • When an AQ JMS foreign server is configured with a WebLogic data source, the data source is exposed to general-purpose JDBC usage. Oracle recommends that you secure the data source as described in "Using Roles and Policies to Secure JDBC Data Sources" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.

  • WebLogic Server username and password: WebLogic credentials are checked when accessing secured names in JNDI, and accessing secured data sources. Server side applications automatically assume the same WebLogic credentials as the caller that invoked the application, or, in the case of MDBs, this credential is configurable as part of the MDB configuration.

  • The WebLogic data source Identity Based Connection Pooling feature is not supported.

  • JNDI context credentials: Specifying credentials as part of setting up a JNDI context within a server-side application is usually not necessary, and is not normally recommended. This creates a new credential that overrides the application's current credentials. In other words, the username and password properties that are optionally supplied when creating the context become the WebLogic identity and replace any current identity (the property names are Context.SECURITY_PRINCIPAL = "java.naming.security.principal" and Context.SECURITY_CREDENTIALS = "java.naming.security.credentials" respectively). The optional new credential is implicitly associated with current thread, and so becomes the credential used for subsequent WebLogic operations on the same thread, such as JNDI lookups. The new credential is not the credential used for AQ JMS operations.

WebLogic Messaging Bridge

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 Configuring and Managing the Messaging Bridge for Oracle WebLogic Server.

Create a Messaging Bridge Instance

The section provides the major steps in creating a messaging bridge between AQ destinations configured as foreign destinations in one domain and applications/MDBs running in another domain:

  1. Create the bridge instance on the server where AQ destinations configured as foreign destinations.

  2. Create source and target bridge destinations.

    Select Other JMS in the default Messaging Provider drop down when a Foreign AQ JMS destination is specified for a source or target destination.

  3. Deploy a resource adapter.

  4. Create a messaging bridge instance.

    The Messaging Bridge Exactly-Once quality of service requires a data source configured with the XA based JDBC driver and must use an AQ JMS connection factory that implements an XA JMS connection factory interface. See Configure a WebLogic Data Source and Configure JMS Foreign Server Connection Factories.

  5. Target the messaging bridge.

The Administration Console assists you in creating a messaging bridge by deploying an appropriate resource adapter and setting the values of some attributes. Consider changing messaging bridge settings to better suit your environment. See "Create Messaging Bridge Instances" in Oracle WebLogic Server Administration Console Help

Stand-alone WebLogic AQ JMS Clients

You can create WebLogic AQ JMS stand-alone clients that can lookup 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: aqapi.jar, ojdbc6.jar, orai18n.jar and one of the following WebLogic client jars: wlthint3client.jar, wlclient.jar, or wlfullclient.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.

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

Configure a Foreign Server using a Database's JDBC URL

Specify the db_url, java.naming.security.principal JNDI properties and a password in jndi-properties-credentials.

For Example:

<foreign-server>

<initial-context-factory>oracle.jms.AQjmsInitialContextFactory</initial-context-factory>

<jndi-properties-credential-encrypted>{3DES}g8yFFu1AhP8=</jndi-properties-credential-encrypted>

<jndi-property>
<key>java.naming.security.principal</key>
<value>j2ee</value>
</jndi-property>

<jndi-property>
<key>db_url</key>
<value>jdbc:oracle:thin:@{hostname}:{port}:{sid}</value>
</jndi-property>

</foreign-server>

where:

  • The value of the db_url JNDI property is the JDBC URL used to connect to the AQ JMS Oracle database.

  • The value of the java.naming.security.principal is the database user name AQ JMS uses to connect to the database.

  • jndi-properties-credentials contains the database password.

No other configuration properties are required.

Limitations when using Stand-alone WebLogic AQ JMS Clients

The following section provides limitations to consider when creating and using stand-alone WebLogic JMS clients. This release does not support:

  • Use of a WebLogic AQ JMS stand-alone client to automatically participate in global transactions managed by WLS.

  • Connection pooling for WebLogic AQ JMS stand-alone clients.

  • Looking up JMS objects defined by an AQ JMS foreign server using a data source.