1. Administering JMS Resources for Oracle WebLogic Server
  2. Interoperating with Oracle AQ JMS

7 Interoperating with Oracle AQ JMS

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.

This chapter includes the following sections:

See Introduction to Oracle Database Advanced Queuing in Oracle Streams Advanced Queuing User's Guide.

Note:

AQ-JMS integration is not supported in a mixed or dynamic cluster. No exception is thrown when this is attempted.

Overview

AQ JMS uses a database connection and stores JMS messages in a database accessible to an entire WebLogic Server cluster. This connection enables the use of database features and tooling for data manipulation and backup. Your WebLogic Server installation includes all the necessary classes, and 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 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 or 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 or DB connection that does not support remote connectivity. An alternative is to use a messaging bridge between AQ destinations in one domain and applications or MDBs running in another domain. See WebLogic Messaging Bridge.

Driver Support

WebLogic AQ JMS requires the Oracle thin driver to communicate with the Oracle database. Oracle OCI JDBC Driver and non-Oracle JDBC Drivers are not supported. See Supported Configurations in What's New in Oracle WebLogic Server.

Transaction Support

WebLogic AQ JMS supports both Global XA (JTA) transactions and local JMS transacted session transactions.Global transactions require use of XA based connection factories, while local transactions may use non-XA based JMS connection factories:

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

  • If you select an XA JDBC driver, then 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, then WebLogic Server logs a warning message.

  • Global transactions are supported only 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, then 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 called 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 Developing JMS Applications for Oracle WebLogic Server

Oracle Real Application Clusters

WebLogic AQ JMS supports Oracle Real Application Clusters (Oracle RAC) with the use of WebLogic Multi Data Sources to provide failover in an Oracle RAC environment.See Using WebLogic Server with Oracle RAC in Administering 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

Use SQL scripts or other tools for AQ administration and monitoring, such as AQ queue table creation/removal, destination creation/removal, and statistics queries.

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 WebLogic Server Administration Console.

Configuring WebLogic Server to Interoperate with AQ JMS

You can configure AQ JMS queues and topics in an Oracle Database and configure a JMS foreign server in WebLogic Server so that applications can lookup AQ JMS connection factories and destinations in the WebLogic JNDI context. The following sections describe the preferred method for configuring WebLogic Server to interoperate with AQ JMS:

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

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. The following sections describe one configuration method:

For more detailed information on using and configuring AQ, see Introduction to Oracle Database Advanced Queuing in 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 in Oracle Database 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. After the AQ queue table is created, you can create an 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 about 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, an 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 about starting queues, see START_QUEUE Procedure in Oracle Database PL/SQL Packages and Types Reference.

Configure WebLogic Server for AQ JMS

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

Configure a WebLogic Data Source for AQ JMS

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. You can use a generic or Active GridLink (AGL) data source:

Configuring a Generic Data Source for AQ JMS

When configuring your data source:

  • Select the appropriate 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 an AGL Data Source for AQ JMS

When configuring your data source:

  • Select the Oracle Thin XA Driver for Connections.

  • Configure the database user name and password in the data source connection pool configuration.

See:

Configuring a Generic Data Source for AQ JMS

When configuring your data source:

  • Select the appropriate 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 an AGL Data Source for AQ JMS

When configuring your data source:

  • Select the Oracle Thin XA Driver for Connections.

  • Configure the database user name and password in the data source connection pool configuration.

See:

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, such as security principal or credentials, is required. However, if you provide a database url, then java.naming.security.principal and java.naming.security.credentials are required.

See Configure a WebLogic Data Source for AQ JMS.

Configure JMS Foreign Server Connection Factories

After 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 those in Table 7-1.

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 that 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 that implements the JMS javax.jms.XATopicConnectionFactory 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, then the remote JNDI name must be Queues/<queue name>.

    • If the destination is a topic, then 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 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:

Additional Configuration for Interoperation with Oracle 12c Database

The following section provides additional configuration that may be required when interoperating AQ JMS on a Oracle 12c Database:

  • The AQ asynchronous notification feature is enabled by default with sharded queues in Oracle 12c database.

    When using the AQ sharded queues, an asynchronous receive from a Message Listener or from a Message Driven Bean (MDB) may create more JDBC connections internally based on the load. If the number of JDBC connections is restricted in the system, the client application should disable the asynchronous notification by setting the value of the system property oracle.jms.useJmsNotification to false.

    For transactional MDBs or when -Dweblogic.mdb.message.MinimizeAQSessions is set to true, the MDB container will internally use synchronous receivers, not an asynchronous consumer.

  • To use the notification service (-Doracle.jms.useJmsNotification=true), set the database service name in place of SID for the JDBC URL. For example:

    jdbc:oracle:thin:@//DB_HOST:DB_PORT/Database ServiceName

  • Specify a local listener by setting the init parameter in the init.ora file and restart the database. For example:

    LOCAL_LISTENER="(ADDRESS=(PROTOCOL=tcp)(host=DB_HOST)(port=DB_PORT)).

  • Set the WebLogic Server properties to minimize the number of JMS sessions used and to control the MDB polling interval: See Settings for Message Driven Beans to Interoperate with AQ JMS

Note:

As of WebLogic Server 12.2.1.2, the WebLogic Server Java system properties weblogic.mdb.message.MimizeAQSessions and weblogic.ejb.container.MDBDestinationPollIntervalMillis are obsolete. Use the corresponding activation-config-property instead. The two activation-config-property overrides the respective Java system properties.

Programming Considerations

Learn about some of the programming considerations for managing WebLogic AQ JMS.

The following sections include information about advanced WebLogic AQ JMS topics:

Settings for Message Driven Beans to Interoperate with AQ JMS

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.

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

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 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, because 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 Abstract Data Types (ADTs). ADTs consists of a data structure and subprograms that manipulate data in an Oracle Database.

Note:

This is not supported with Message-Driven Beans (MDBs).

See:

Resource References

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.

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

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

Learn about advanced interoperability information when WebLogic Server applications interoperate with AQ JMS.

This section includes the following topics:

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 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 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 to be able to successfully look-up 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 Developing JMS Applications 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 is 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 user-name 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 user-name and password, then the database connection is created using the user-name 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 user-name 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 user-name and password. For server-side JMS AQ applications, the method assumes the user-name is for a WebLogic user and authenticates it with the WebLogic server. This behavior deviates from other kinds of JMS AQ clients, where the user-name 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 Administering 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 called the application, or, in the case of MDBs, this credential can be configured 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 typically recommended. This creates a new credential that overrides the application's current credentials. In other words, the user-name 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 the 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 Administering the WebLogic Messaging Bridge for Oracle WebLogic Server.

Create a Messaging Bridge Instance

The following are the major steps in creating a messaging bridge between AQ destinations are configured as foreign destinations in one domain and applications or 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 for AQ JMS and Configure JMS Foreign Server Connection Factories.

  5. Target the messaging bridge.

The WebLogic Server Administration Console helps you in create 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 Online 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: $MW_HOME/oracle_common/modules/oracle.jdbc_12.1.0/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.

Note:

Only use WebLogic Server 12c jar files on the client-side classpath. Using 11g or mixing 12c and 11g jar files is not supported.

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

  • The value of 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 that 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 are 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.