Configuring an OEMS JMS Database Message Service Provider

To configure the OEMS JMS Database message service provider (see "OEMS JMS Database: Advanced Queueing (AQ)-Based Provider"), you must do the following:

Install and configure the OEMS JMS Database provider (see "Installing and Configuring the OEMS JMS Database Provider").

You can grant privileges that either disable XA-compliant resources, when two-phase commit (2PC) transactions are not needed, or enable XA-compliant resources, when 2PC transactions are needed. For more information on 2PC, see "How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?".
Choose appropriate JNDI names for your destination and connection factory (see "OEMS JMS Database Destination and Connection Factory Names").
Configure the data-sources.xml file to identify your database (see "Configuring data-sources.xml").
Optionally, map the actual JNDI names to logical names (see "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)").
Configure the application.xml (or orion-application.xml) file to identify the JNDI name of the data source that is to be used as the OEMS JMS Database provider within the <resource-provider> element (see "Configuring application.xml or orion-application.xml").
Configure your message-driven beans to access your OEMS JMS Database message service provider.

For more information, see the following:
Note:
Oracle recommends that you access a message service provider using a J2CA resource adapter such as the Oracle JMS Connector. For more information, see "Restrictions When Accessing a Message Service Provider Without a J2CA Resource Adapter".

OEMS JMS Database Destination and Connection Factory Names

The actual JNDI names for the JMS destination and connection factory depend on your OEMS JMS Database installation as shown in Table 23-2.

Table 23-2 OEMS JMS Database Destination and Connection Factory Names

Type	Form
Queue	`java:comp/resource/<ProviderName>/Queues/<QName>`
Queue Connection Factory	`java:comp/resource/<ProviderName>/QueueConnectionFactories/<QCFName>`
Topic	`java:comp/resource/<ProviderName>/Topics/<TName>`
Topic Connection Factory	`java:comp/resource/<ProivderName>/TopicConnectionFactories/<TCFName>`

The values for the variables in Table 23-2 are defined as follows:

<ProviderName>: the JNDI name of the data source that is providing OEMS JMS Database service (see "Configuring application.xml or orion-application.xml")
<QName>: the name of the queue you created in the database (see step 3 b in "Installing and Configuring the OEMS JMS Database Provider").
<QCFName>: the name of the queue connection factory. You may specify any arbitrary name.
<TName>: the name of the topic you created in the database (see step 3 b in "Installing and Configuring the OEMS JMS Database Provider").
<TCFName>: the name of the topic connection factory. You may specify any arbitrary name.

Installing and Configuring the OEMS JMS Database Provider

Note:

The following sections use SQL for creating queues, topics, their tables, and assigning privileges that is provided within the MDB demo on the OC4J sample code page .

You or your DBA must install Oracle AQ according to the Oracle Streams Advanced Queuing User's Guide and Reference. and generic database manuals.
You or your DBA should create an RDBMS user through which the MDB connects to the database and grant this user appropriate access privileges to perform OEMS JMS Database operations.

The privileges that you need depend on what functionality you are requesting. Refer to the Oracle Streams Advanced Queuing User's Guide and Reference. for more information on privileges necessary for each type of function.

The following example creates jmsuser, which must be created within its own schema, with privileges required for Oracle AQ operations. You must be a SYS DBA to execute these statements.
```
DROP USER jmsuser CASCADE ;

GRANT connect, resource,AQ_ADMINISTRATOR_ROLE TO jmsuser IDENTIFIED BY jmsuser ;
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;

connect jmsuser/jmsuser;
```
You may need to grant other privileges, such as XA-compliant, two-phase commit (2PC) privileges or system administration privileges, based on what the user needs.

For more information on 2PC, see the following:
- "How do You Participate in a Global or Two-Phase Commit (2PC) Transaction?"
- Oracle Containers for J2EE Services Guide JTA chapter
You or your DBA should create the tables and queues to support the JMS Destination objects.

Refer to the Oracle Streams Advanced Queuing User's Guide and Reference. for more information on the DBMS_AQADM packages and Oracle AQ messages types.
1. Create the tables that handle the JMS Destination (queue or topic).
  
  In OEMS JMS Database, both topics and queues use a queue table. The rpTestMdb JMS example creates a single table: rpTestQTab for a queue.
  
  To create the queue table, execute the following SQL:
```
DBMS_AQADM.CREATE_QUEUE_TABLE(
        Queue_table            => 'rpTestQTab',
        Queue_payload_type     => 'SYS.AQ$_JMS_MESSAGE',
        sort_list => 'PRIORITY,ENQ_TIME',
        multiple_consumers  => false,
        compatible             => '8.1.5');
```
  The multiple_consumers parameter denotes whether there are multiple consumers or not; thus, is always false for a queue and true for a topic.
2. Create the JMS Destination. If you are creating a topic, you must add each subscriber for the topic. The rpTestMdb JMS example requires a single queue–rpTestQueue.
  
  The following creates a queue called rpTestQueue within the queue table rpTestQTab. After creation, the queue is started:
```
DBMS_AQADM.CREATE_QUEUE(
      Queue_name          => 'rpTestQueue',
      Queue_table         => 'rpTestQTab');

DBMS_AQADM.START_QUEUE(
      queue_name         => 'rpTestQueue');
```
  If you wanted to add a topic, then the following example shows how you can create a topic called rpTestTopic within the topic table rpTestTTab. After creation, two durable subscribers are added to the topic. Finally, the topic is started and a user is granted a privilege to it.
  
  Note:
  Oracle AQ uses the DBMS_AQADM.CREATE_QUEUE method to create both queues and topics.
```
DBMS_AQADM.CREATE_QUEUE_TABLE(
        Queue_table            => 'rpTestTTab',
        Queue_payload_type     => 'SYS.AQ$_JMS_MESSAGE',
        multiple_consumers  => true,
        compatible             => '8.1.5');
DBMS_AQADM.CREATE_QUEUE( 'rpTestTopic', 'rpTestTTab');
DBMS_AQADM.ADD_SUBSCRIBER('rpTestTopic',                          sys.aq$_agent('MDSUB', null, null));
DBMS_AQADM.ADD_SUBSCRIBER('rpTestTopic',                          sys.aq$_agent('MDSUB2', null, null));
DBMS_AQADM.START_QUEUE('rpTestTopic');
```
  Note:
  The names defined here must be the same names used to define the queue or topic in the orion-ejb-jar.xml file.

Configuring data-sources.xml

Configure a data source for the database where the OEMS JMS Database provider is installed. The JMS topics and queues use database tables and queues to facilitate messaging. The type of data source you use depends on the functionality you want.

Example 23-3 shows a typical managed data source, which by default, supports global (two-phase commit) transactions.

Example 23-3 Emulated Data Source With Thin JDBC Driver

<connection-pool name="ScottConnectionPool">
    <connection-factory
        factory-class="oracle.jdbc.pool.OracleDataSource"
        user="scott"
        password="tiger"
        url="jdbc:oracle:thin:@//localhost:1521/ORCL" >
    </connection-factory>
</connection-pool>
 
<managed-data-source
    name="OracleDS"
    jndi-name="jdbc/OracleDS"
    connection-pool-name="ScottConnectionPool"
/>

For more information, see "Understanding EJB Data Source Services".

Configuring application.xml or orion-application.xml

Identify the JNDI name of the data source that is to be used as the OEMS JMS Database provider within the <resource-provider> element.

If this is to be the JMS provider for all applications (global), configure the global application.xml file.
If this is to be the JMS provider for a single application (local), configure the orion-application.xml file of the application.

The following code sample shows how to configure the JMS provider using XML syntax for OEMS JMS Database:

class attribute–The OEMS JMS Database provider is implemented by the oracle.jms.OjmsContext class, which is configured in the class attribute.
property attribute–Identify the data source that is to be used as this JMS provider in the property element. The topic or queue connects to this data source to access the tables and queues that facilitate the messaging.

The following example demonstrates that the data source identified by "jdbc/OracleDS" is to be used as the OEMS JMS Database provider. This JNDI name is specified in the managed-data-source element jndi-name attribute in Example 23-3. If this example used a non-emulated data source, then the name would be the same as in the location element.

<resource-provider
    class="oracle.jms.OjmsContext"
    name="myProvider">
    <description>OJMS/AQ</description>
    <property name="datasource" value="jdbc/OracleDS"></property>
</resource-provider>