This chapter describes how Oracle WebLogic Server 12.1.3 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 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.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 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.
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.
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.
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 Developing JMS Applications for Oracle WebLogic Server
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 Administering JDBC Data Sources for Oracle WebLogic Server.
Note:
Oracle does not recommend configuring multi data sources forLoad 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 degradationExcept 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. Use SQL scripts or other tools for AQ administration and monitoring, such as AQ queue table creation/removal, destination creation/removal, and statistics query.
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.
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 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
;
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.
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.
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.
The following sections provide information on how to configure WebLogic Server to interoperate with 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:
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 JDBC Data Sources" in Administering JDBC Data Sources for Oracle WebLogic Server.
"Create JDBC data sources" in Oracle WebLogic Server Administration Console Online Help.
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:
"Using Active GridLink Data Sources" in Administering JDBC Data Sources for Oracle WebLogic Server.
"Create JDBC GridLink data sources" in Oracle WebLogic Server Administration Console Online Help.
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:
"Overview of JMS Modules" in Administering JMS Resources for Oracle WebLogic Server.
"Create foreign servers in a system module" in Oracle WebLogic Server Administration Console Online Help.
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:
Configuring Foreign Server Resources to Access Third-Party JMS Providers
"Configure foreign servers" in Oracle WebLogic Server Administration Console Online Help.
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/credentials, is required. However, if you provide a database url, java.naming.security.principal
and java.naming.security.credentials
are required.
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 8-1 Remote JNDI names for AQ JMS Connection Factories
<AQ JMS Prefix Value> | JMS Interface |
---|---|
|
javax.jms.QueueConnectionFactory |
|
javax.jms.TopicConnectionFactory |
|
javax.jms.ConnectionFactory |
|
javax.jms.XAQueueConnectionFactory |
|
javax.jms.XATopicConnectionFactory |
|
javax.jms.XAConnectionFactory |
For example, consider two connection factories configured for an AQ JMS Foreign Server:
Table 8-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:
"Create foreign connection factories" in Oracle WebLogic Server Administration Console Online Help.
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 8-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 8, "Create a JMS Queue or Topic." For example, consider the two destinations configured for an AQ JMS Foreign Server in the following table:
Table 8-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:
"Create foreign destinations" in Oracle WebLogic Server Administration Console Online Help.
The following section provides additional configuration that may be required when interoperating AQ JMS on a Oracle 12c Database:
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 following WebLogic Server properties to minimize the number of JMS sessions used and to control the MDB polling interval:
-Dweblogic.mdb.message.MinimizeAQSessions=true
-Dweblogic.ejb.container.MDBDestinationPollIntervalMillis=6000
The following sections provide information on advanced WebLogic AQ JMS topics:
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.
SeeDeveloping 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 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.
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.
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:
"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
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.
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 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.
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>');
The following sections provide information on advanced interoperability topics when WebLogic Server applications interoperate with AQ JMS.
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:
Access to JNDI Advertised Destinations and Connection Factories
Controlling Access to Destinations that are Looked Up using the JMS API
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.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.
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.
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.
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 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 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.
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.
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:
Create the bridge instance on the server where AQ destinations configured as foreign destinations.
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.
Deploy a resource adapter.
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.
Target the messaging bridge.
The WebLogic Server 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 Online Help
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
, wlclient.jar
, or wlfullclient.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.
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.
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.
The following section provides links to related documentation:
"FAQs: Integrating Remote JMS Providers" in Developing JMS Applications for Oracle WebLogic Server