23 Configuring Message Services

This chapter describes how to configure Java Message Service (JMS) and non-JMS message service providers, including:

Configuring an OracleAS JMS Message Service Provider
Configuring an OJMS Message Service Provider
Configuring a Message Service Provider Using J2CA

For more information, see:

"What Message Providers Can I use with My MDB?"
"Implementing an EJB 3.0 MDB"
"Implementing an EJB 2.1 MDB"
"Java Message Service" in the Oracle Containers for J2EE Services Guide

Configuring an OracleAS JMS Message Service Provider

To configure the OracleAS JMS message service provider, you must:

Choose appropriate JNDI names for your destination and connection factory (see "OracleAS JMS Destination and Connection Factory Names").
Configure the <OC4J_HOME>/j2ee/home/config/jms.xml file (see "Configuring jms.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)").
Associate the OracleAS JMS message service provider with the message-driven beans that will use it.

For more information, see:
- "Configuring an EJB 3.0 MDB to Use a Non-J2CA Message Service Provider"
- "Configuring an EJB 2.1 MDB to Use a Non-J2CA Message Service Provider"

For more information about OracleAS JMS, see "Oracle Application Server JMS (OracleAS JMS) Provider: File-Based".

OracleAS JMS Destination and Connection Factory Names

The actual JNDI names for the JMS destination and connection factory are the ones you specify in the jms.xml file (see "Configuring jms.xml").

Table 23-1 lists the form of these names.

Table 23-1 OracleAS JMS Destination and Connection Factory Names

Type	Form
Queue	`jms/Queue/<QName>`
Queue Connection Factory	`jms/Queue/<QCFName>`
Topic	j`ms/Topic/<TName>`
Topic Connection Factory	`jms/Topic/<TCFName>`

Configuring jms.xml

You configure OracleAS JMS options in the <OC4J_HOME>/j2ee/home/config/jms.xml file. In 10.1.3, the jms.xml is defined by the XML schema document (XSD) located at http://www.oracle.com/technology/oracleas/schema/jms-server-10_1.xsd.

Some of the options you can configure in the jms.xml file include:

JMS Destination objects used by the MDB.
Topic or queue in the jms.xml file to which the client sends all messages that are destined for the MDB.
The name, location, and connection factory for either Destination type must be specified.
If your MDB accesses a database for inquiries and so on, then you can configure the Data Source used. For information on data source configuration, see the Data Source chapter in the Oracle Containers for J2EE Services Guide.
Path to a file in which OracleAS JMS events and errors are written.

Example 23-1 shows the jms.xml file configuration for an EJB 2.1 MDB that specifies a queue (named jms/Queue/rpTestQueue) that is used by the message-driven bean rpTestMdb (see Example 17-1). The queue connection factory is defined as jms/Queue/myQCF. In addition, a topic is defined named jms/Topic/rpTestTopic, with a connection factory of jms/Topic/myTCF.

Example 23-1 jms.xml For an EJB 2.1 MDB using OracleAS JMS

<jms>
    <jms-server port="9128">
        <queue location="jms/Queue/rpTestQueue"></queue>
        <queue-connection-factory location="jms/Queue/myQCF"></queue-connection-factory>
        <topic location="jms/Topic/rpTestTopic"></topic>
        <topic-connection-factory location="jms/Topic/myTCF"></topic-connection-factory>
        <log>
             <!-- path to the log-file where JMS-events and errors are written -->
             <file path="../log/jms.log" />
        </log>
    </jms-server>
</jms>

Configuring an OJMS Message Service Provider

To configure the OJMS message service provider, you must:

Install and configure the OJMS provider (see "Installing and Configuring the OJMS Provider").
Choose appropriate JNDI names for your destination and connection factory (see "OracleAS JMS 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 OJMS provider within the <resource-provider> element (see "Configuring application.xml or orion-application.xml").
Associate the OJMS message service provider with the message-driven beans that will use it.

For more information, see:
- "Configuring an EJB 3.0 MDB to Use a Non-J2CA Message Service Provider"
- "Configuring an EJB 2.1 MDB to Use a Non-J2CA Message Service Provider"

For more information, see "Oracle JMS (OJMS) Provider: Advanced Queueing (AQ)-Based".

OJMS Destination and Connection Factory Names

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

Table 23-2 OJMS 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 OJMS 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 OJMS 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 OJMS Provider").
<TCFName>: the name of the topic connection factory. You may specify any arbitrary name.

Installing and Configuring the OJMS 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 at http://www.oracle.com/technology/tech/java/oc4j/demos.

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 OJMS 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 two-phase commit or system administration privileges, based on what the user needs. See the JTA chapter in the Oracle Containers for J2EE Services Guide for the two-phase commit privileges.
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 OJMS, 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 OJMS 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-2 shows a typical managed data source, which by default, supports global (two-phase commit) transactions.

Example 23-2 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 OJMS 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 OJMS.

class attribute—The OJMS 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 OJMS provider. This JNDI name is specified in the managed-data-source element jndi-name attribute in Example 23-2. 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>

Configuring a Message Service Provider Using J2CA

To configure the J2CA message service provider, you must:

Install and configure the J2CA adapter (see "Installing and Configuring a J2CA Adapter").
Choose appropriate JNDI names for your connection factory (see "J2CA Message Service Provider Connection Factory Names").
Configure the appropriate deployment XML files (see "Configuring OC4J Deployment XML Files").
Associate the J2CA message service provider with the message-driven beans that will use it.

For more information, see:
- "Configuring an EJB 3.0 MDB to Use a J2CA Message Service Provider"
- "Configuring an EJB 2.1 MDB to Use a J2CA Message Service Provider"

For more information, see "J2EE Connector Architecture (J2CA) Adapter Message Provider".

Note:

For a complete code example of configuring a J2CA message service provider resource adapter and MDB application, see

http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/how-to-gjra-with-oracleasjms/doc/how-to-gjra-with-oracleasjms.html

J2CA Message Service Provider Connection Factory Names

The actual JNDI names for the destination and connection factory depend on your J2CA installation as defined in your oc4j-connectors.xml file (see "Configuring OC4J Deployment XML Files").

Typically, it will be composed of java:<Prefix>/<FactoryName> where <Prefix> is an optional JNDI location like comp/env/eis and <FactoryName> is the name of the javax.cci.ConnectionFactory for your adapter.

Installing and Configuring a J2CA Adapter

OC4J includes the Oracle JMS Connector: a generic JMS J2CA resource adapter that integrates OC4J with OracleAS JMS and OJMS message service providers, as well as non-Oracle JMS providers such as WebSphereMQ, Tibco, and SonicMQ.

For more information, see "Overview: Administering Resource Adapters" in the Oracle Containers for J2EE Resource Adapter Administrator's Guide.

Configuring OC4J Deployment XML Files

To configure a J2CA message service provider, you must configure the following deployment XML files:

ra.xml
oc4j-ra.xml
oc4j-connectors.xml

For more information, see:

"Binding and Configuring a Connection Factory: Basic Settings" in the Oracle Containers for J2EE Resource Adapter Administrator's Guide
"OC4J Resource Adapter Configuration Files" in the Oracle Containers for J2EE Resource Adapter Administrator's Guide