3 Java Message Service (JMS)

Default Destination Objects

OracleAS JMS creates two default Destination objects, as follows:

• The default queue is defined as jms/demoQueue.

• The default topic is defined as jms/demoTopic.

You can use these Destination objects in your code without adding them to the jms.xml configuration file.

The default connection factories that are automatically associated with these objects are as follows:

• jms/QueueConnectionFactory

• jms/TopicConnectionFactory

Default Connection Factories

OracleAS JMS creates six default connection factories for the XA/non-XA and various JMS domains. You can use these connection factories in your code without adding them to the jms.xml configuration file, rather than defining new connection factories. The only reason to define a new connection factory in the jms.xml file is if you need to specify nondefault values for one or more of the optional attributes of connection-factory elements.

The default connection factories are as follows:

• jms/ConnectionFactory

• jms/QueueConnectionFactory

• jms/TopicConnectionFactory

• jms/XAConnectionFactory

• jms/XAQueueConnectionFactory

• jms/XATopicConnectionFactory

Thus, if you used only the default connection factories, then you could define only the topic and queues necessary in the jms.xml file. The following example defines the jms/demoQueue and the jms/demoTopic. Both of these objects use their respective default connection factories.

<?xml version="1.0" ?>
<!DOCTYPE jms-server PUBLIC "OracleAS JMS server" "http://xmlns.oracle.com/ias/dtds
/jms-server.dtd">

<jms-server port="9127">
   <queue location="jms/demoQueue"> </queue>
   <topic location="jms/demoTopic"> </topic>
    <!-- path to the log-file where JMS-events/errors are stored -->
    <log>
        <file path="../log/jms.log" />
    </log>
</jms-server>

OracleAS JMS internally creates the default connection factory objects and binds them to the default names within the OC4J server where the JMS connection is created.

However, you can also redefine the default connection factories to have specific attributes by configuring them in the jms.xml file.

Overview

If persistence is enabled, then OC4J automatically performs the following:

• If a persistence file does not exist, OC4J automatically creates the file and initializes it with the appropriate data.

• If the persistence file exists and is empty, then OC4J initializes it with the appropriate data.

Even if persistence is enabled, only certain messages are persisted to a file. For a message to be persisted, all of the following must be true:

• The Destination object is defined to be persistent within the persistence-file attribute in the jms.xml file.

• The message has a persistent delivery mode, which is the default. Messages sent to persistent destinations that are defined with a non-persistent delivery mode (defined as DeliveryMode.NON_PERSISTENT) are not persistent.

The complete semantics of which messages are persisted are documented within the JMS specification.

Enabling Persistence

To enable file-based persistence for Destination objects, specify the persistent-file attribute in the jms.xml file. For JMS objects within standalone OC4J, this is all you have to do to enable persistence. The following XML configuration demonstrates how the persistence-file attribute defines the name of the file as pers. See "OracleAS JMS Configuration File Elements for jms.xml" for information on the path and naming conventions for the persistence-file attribute.

<queue name="foo" location="jms/persist" persistence-file="pers">
</queue>

The path for the persistence-file attribute is either an absolute path of the file or a path relative to the persistence directory defined in application.xml.

The JMS server will not create any directories for persistence files. So when a persistence file is defined in jms.xml it must either be in an existing absolute directory, for example:

persistence-file="/this/dir/exists/PersistenceFile"

or simply be a filename for example:

persistence-file="PersistenceFile"

In the latter case, by default the persistence file will be created in $J2EE_HOME/persistence (for a standalone instance) or $J2EE_HOME/persistence/<island_name> (for an iAS environment).

Oracle Application Server may have multiple OC4J instances writing to the same file directory, even with the same persistence filename. Setting this attribute enables file-based persistence, but also creates the possibility that your persistence files can be overwritten by another OC4J instance.

Recovery

The file-based persistence of OC4J JMS provides recoverable and persistent storage of messages. Each OC4J JMS Destination, which can be either a queue or topic, can be associated with a relative or absolute path name that points to a file that stores the messages sent to the Destination object. The file can reside anywhere in the file system (and not necessarily inside a J2EE_HOME directory). Multiple persistence files can be placed in the same directory; persistence files can be placed on a remote network file system or can be part of a local file system.

The following sections discuss the various aspects of persistence recovery for OracleAS JMS:

• Scope of Recoverability

• Persistence File Management

• Reporting Errors to the JMS Client

• OracleAS JMS Recovery Steps

Message Expiration

By default, if a message sent to a persistent Destination expires, then OC4J JMS moves the message to the exception queue. The JMSXState of the expiring message is set to the value 3 (for EXPIRED), but the message headers, properties, and body are not otherwise modified. The message is wrapped in an ObjectMessage (with appropriate property name and value copies performed as described elsewhere in this chapter), and the wrapping message is sent to the exception queue.

To affect the behavior of what goes into the exception queue, use the oc4j.jms.saveAllExpired property (described in Table 3-6).

The wrapping ObjectMessage has the same DeliveryMode as the original message.

By default, messages expiring on nonpersistent or temporary Destination objects are not moved to the exception queue. The messages sent to these Destination objects are not worth persisting and neither should their expired versions be.

You can specify that all expired messages be sent to the OC4J JMS exception queue, regardless of whether they are sent to persistent, nonpersistent, or temporary Destination objects, by setting the oc4j.jms.saveAllExpired administration property (described in Table 3-6) to true when starting the OC4J server. In this case, all expired messages are moved to the exception queue.

Examples

This section contains code samples that show connection factory configuration fragments.

The following code sample configures a connection factory of jms/Cf, a queue connection factory of jms/Qcf, and an XA topic connection factory of jmx/xaTcf.

<connection-factory location="jms/Cf">
</connection-factory>

<queue-connection-factory location="jms/Qcf">
</queue-connection-factory>

<xa-topic-connection-factory location="jms/xaTcf"
    username="foo" password="bar" clientID="baz">
</xa-topic-connection-factory>

If you want to add a topic connection factory, you must use a unique name. For example, you could not use the same name as the connection factory (above) of jms/Cf. Thus, the following would be invalid.

<!-- Invalid: cannot reuse "location"  -->
<topic-connection-factory location="jms/Cf">
</topic-connection-factory>

The following code sample shows queue and topic configuration fragments. This segment creates a queue foo and a topic bar.

<queue name="foo" location="jms/foo">
</queue>

<topic name="bar" location="jms/bar">
</topic>

Certain locations are reserved and cannot be redefined within the jms.xml configuration file. The following code sample shows that you cannot use the jms/Oc4jJmsExceptionQueue when defining a queue location, because it is a reserved location.

<!-- Invalid: cannot use a reserved "location" -->
<queue name="fubar" location="jms/Oc4jJmsExceptionQueue">
</queue>

When defining a persistence file for queues and topics, you can define the location and the filename. In addition, you can specify multiple persistence files, as long as the persistence filename is the same. Thus, the persistence file is written out to two locations for the same queue.

<queue name="foo" location="jms/persist" persistence-file="pers">
</queue>

<!-- OK: multiple persistence file specification ok if consistent -->
<queue name="foo" location="jms/file" persistence-file="pers">
</queue>

<!-- Invalid: multiple persistence file specifications should be consistent -->
<queue name="foo" location="jms/file1" persistence-file="notpers">
</queue>

Alternatively, you cannot have two objects writing out to the same persistence file. Each queue or topic must have its own persistence filename, even if the locations are different.

<topic name="demoTopic" location="jms/dada" persistence-file="/tmp/abcd">
</topic>

<!-- Invalid: cannot reuse persistence-file for multiple destinations -->
<topic name="demoTopic1" location="jms/dada1" persistence-file="/tmp/abcd">
</topic>

Install and Configure the JMS Provider

You or your DBA must install OJMS according to theOracle9i Application Developer's Guide—Advanced Queuing for Release 2 (9.2) and generic database manuals. After you have installed and configured this JMS provider, you must apply additional configuration. This includes the following:

1. You or your DBA must create an RDBMS user through which the JMS client connects to the database. Grant this user appropriate access privileges to perform OJMS operations. See "Create User and Assign Privileges".

2. You or your DBA must create the tables and queues to support the JMS Destination objects. See "Create JMS Destination Objects".

   
   

   Note: The following sections use SQL for creating queues, topics, their tables, and assigning privileges within the JMS demo on the OC4J sample code page on the OTN Web site at http://www.oracle.com/technology/tech/java/oc4j/demos/index.html

   
   

Create User and Assign Privileges

Create an RDBMS user through which the JMS client connects to the database. Grant access privileges to this user to perform OJMS operations. The privileges that you need depend on what functionality you are requesting. Refer to the Oracle9i Application Developer's Guide—Advanced Queuing for Release 2 (9.2) 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 OJMS 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 Chapter 7, "Java Transaction API", for information on two-phase commit privileges.

Create JMS Destination Objects

Each JMS provider requires its own method for creating the JMS Destination object. Refer to the Oracle9i Application Developer's Guide—Advanced Queuing for Release 2 (9.2) for more information on the DBMS_AQADM packages and OJMS messages types. For our example, OJMS requires the following methods:

http://www.oracle.com/technology/tech/java/oc4j/demos/index.html

1. Create the tables that handle the JMS Destination (queue or topic).

   In OJMS, both topics and queues use a queue table. The JMS example creates a single table, demoTestQTab, for a queue.

   To create the queue table, execute the following SQL:

   DBMS_AQADM.CREATE_QUEUE_TABLE(
           Queue_table            => 'demoTestQTab',
           Queue_payload_type     => 'SYS.AQ$_JMS_MESSAGE',
           sort_list => 'PRIORITY,ENQ_TIME',
           multiple_consumers  => false,
           compatible             => '8.1.5');
   
   

   The multiple_consumers parameter specifies whether there are multiple consumers. 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 JMS example requires a single queue—demoQueue.

   The following command creates a queue called demoQueue within the queue table demoTestQTab. After creation, the queue is started.

   DBMS_AQADM.CREATE_QUEUE(
         Queue_name          => 'demoQueue',
         Queue_table         => 'demoTestQTab');
   
   DBMS_AQADM.START_QUEUE(
         queue_name         => 'demoQueue');
   
   

   If you want to add a topic, then the following example shows how you can create a topic called demoTopic within the topic table demoTestTTab. 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            => 'demoTestTTab',
           Queue_payload_type     => 'SYS.AQ$_JMS_MESSAGE',
           multiple_consumers  => true,
           compatible             => '8.1.5');
   DBMS_AQADM.CREATE_QUEUE( 'demoTopic', 'demoTestTTab');
   DBMS_AQADM.ADD_SUBSCRIBER('demoTopic',                          sys.aq$_agent('MDSUB', null, null));
   DBMS_AQADM.ADD_SUBSCRIBER('demoTopic',                          sys.aq$_agent('MDSUB2', null, null));
   DBMS_AQADM.START_QUEUE('demoTopic');
   

   
   

   Note: The names defined here must be the same names used to define the queue or topic in the deployment descriptors of the application.

   
   

Define the OJMS Resource Provider

You can define the OJMS resource provider either through the Oracle Enterprise Manager 10g or by hand-editing the XML files, as described in the following sections:

• Configure the OJMS Provider Through the Oracle Enterprise Manager 10g

• Configure the OJMS Provider in the OC4J XML Files

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

<data-source
  class="com.evermind.sql.DriverManagerDataSource"
  name="OracleDS"
  location="jdbc/emulatedOracleCoreDS"
  xa-location="jdbc/xa/emulatedOracleXADS"
  ejb-location="jdbc/emulatedDS"
  connection-driver="oracle.jdbc.driver.OracleDriver"
  username="jmsuser"
  password="jmsuser"
  url="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com"
/>

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

<resource-provider class="oracle.jms.OjmsContext" name="ojmsdemo"> 
  <description> OJMS/AQ </description> 
  <property name="url" value="jdbc:oracle:thin:@//localhost:5521/oracle.regress.rdbms.dev.us.oracle.com">
  </property> 
  <property name="username" value="user"></property> 
  <property name="password" value="passwd"></property>

Access the OJMS Resources

The steps for accessing OJMS resources are the same as for OracleAS JMS resources, as listed in "Steps for Sending a Message". The only difference is the name of the resource provided in the JNDI lookup.

• The OJMS syntax for the connection factory is "java:comp/resource" + JMS provider name + "TopicConnectionFactories" or "QueueConnectionFactories" + a user defined name. The user-defined name can be anything and does not match any other configuration. The xxxConnectionFactories details what type of factory is being defined. For this example, the JMS provider name is defined in the <resource-provider> element as ojmsdemo.

  • For a queue connection factory: Because the JMS provider name is ojmsdemo and you decide to use a name of myQCF, the connection factory name is: java:comp/resource/ojmsdemo/ QueueConnectionFactories/myQCF

  • For a topic connection factory: Because the JMS provider name is ojmsdemo and you decide to use a name of myTCF, the connection factory name is: java:comp/resource/ojmsdemo/ TopicConnectionFactories/myTCF

  The user defined names, as shown above by myQCF and myTCF, are not used for anything else in your logic. So, any name can be chosen.

• The OJMS syntax for any Destination is "java:comp/resource" + JMS provider name + "Topics" or "Queues" + Destination name. The Topic or Queue details what type of Destination is being defined. The Destination name is the actual queue or topic name defined in the database.

  For this example, the JMS provider name is defined in the <resource-provider> element as ojmsdemo. In the database, the queue name is demoQueue.

  • For a queue: If the JMS provider name is ojmsdemo and the queue name is demoQueue, then the JNDI name for the topic is: java:comp/resource/ojmsdemo/Queues/demoQueue

  • For a topic: If the JMS provider name is ojmsdemo and the topic name is demoTopic, then the JNDI name for the topic is: java:comp/resource/ojmsdemo/Topics/demoTopic

Example 3-4 demonstrates the steps for sending a JMS message; Example 3-5 demonstrates the steps for receiving a JMS message. For the complete example, download the JMS example used in this chapter from the OC4J sample code page on the OTN Web site at

http://www.oracle.com/technology/tech/java/oc4j/demos/index.html

public static void dosend(int nmsgs)
{
   // 1a. Retrieve the queue connection factory
    QueueConnectionFactory qcf = (QueueConnectionFactory) 
    ctx.lookup(       "java:comp/resource/ojmsdemo/QueueConnectionFactories/myQCF");
   // 1b. Retrieve the queue
    Queue q = (Queue) 
       ctx.lookup("java:comp/resource/ojmsdemo/Queues/demoQueue");
         
   // 2. Create the JMS connection
    QueueConnection qc  = qcf.createQueueConnection();
   // 3. Start the queue connection.
    qc.start();
   // 4. Create the JMS session over the JMS connection
    QueueSession    qs  = qc.createQueueSession(false,
                                        Session.AUTO_ACKNOWLEDGE);
    // Create a sender on the JMS session to send messages.
    QueueSender     snd = qs.createSender(q);

    // Send out messages...  
    for (int i = 0; i < nmsgs; ++i)
    {
     //Create the message using the createMessage method 
    // of the JMS session
     Message msg = qs.createMessage();
     // Send the message out over the sender (snd) using the send method
     snd.send(msg);
     System.out.println("msg:" + " id=" + msg.getJMSMessageID());
    }

   // Close the sender, the JMS session and the JMS connection.
    snd.close();
    qs.close();
    qc.close();
}

public static void dorcv(int nmsgs)
{
   Context ctx = new InitialContext();
   
   // 1a. Retrieve the queue connection factory
    QueueConnectionFactory qcf = (QueueConnectionFactory) ctx.lookup(
          "java:comp/resource/ojmsdemo/QueueConnectionFactories/myQCF");
   // 1b. Retrieve the queue
    Queue q = (Queue) 
      ctx.lookup("java:comp/resource/ojmsdemo/Queues/demoQueue");
         
   // 2. Create the JMS connection
    QueueConnection qc  = qcf.createQueueConnection();
   // 3. Start the queue connection.
    qc.start();
   // 4. Create the JMS session over the JMS connection
    QueueSession    qs  = qc.createQueueSession(false,
                                        Session.AUTO_ACKNOWLEDGE);
   // Create a receiver, as we are receiving off of the queue.
    QueueReceiver   rcv = qs.createReceiver(q);

   // Receive the messages
    int count = 0;
    while (true)
    {
      Message msg = rcv.receiveNoWait();
      System.out.println("msg:" + " id=" + msg.getJMSMessageID());
      ++count;
    }

    if (nmsgs != count)
    {
        System.out.println("expected: " + nmsgs + " found: " + count);
    }

   // Close the receiver, the JMS session and the JMS connection.
    rcv.close();
    qs.close();
    qc.close();
}

Error When Copying aqapi.jar

A common error seen when using OJMS with the Oracle Application Server is:

PLS-00306 "wrong number or types of arguments"

If you receive this message, then the aqapi.jar file being used in Oracle Application Server is not compatible with the version of the Oracle database being used for AQ. A common mistake is to copy the aqapi.jar file from the Oracle database installation into the Oracle Application Server installation, or from the Oracle Application Server installation into the Oracle database installation, under the false assumption that they are interchangeable. The confusion is because the Oracle Application Server and the Oracle database both ship the OJMS client JAR file. Do not copy this file. Use the matrix in Table 3-7 to find the correct version of the database and Oracle Application Server, then use the aqapi.jar file that comes with the Oracle Application Server.

In an Oracle Application Server installation, the OJMS client JAR file can be found at ORACLE_HOME/rdbms/jlib/aqapi.jar and should be included in the CLASSPATH.

OJMS Certification Matrix

Table 3-7 summarizes which version of the Oracle database to use with the Oracle Application Server when the OJMS client is running in OC4J. An X indicates that the Oracle database version and the Oracle Application Server version that intersect at that cell are certified to work together. If the intersection has no X, then the corresponding version of the Oracle database and Oracle Application Server should not be used together.

Configuring WebSphere MQ

To configure WebSphere MQ, perform the following steps:

1. Install and configure WebSphere MQ on your system, then verify the installation by running any examples or tools supplied by the vendor. (See the documentation supplied with your software for instructions.)

2. Configure the resource provider. You can use either of two methods to configure the resource provider: Use Oracle Enterprise Manager 10g (as shown in "Define the OJMS Resource Provider"), or use the <resource-provider> element in orion-application.xml. Use either method to add WebSphere MQ as a custom resource provider. The following example demonstrates using the <resource-provider> element to configure WebSphere MQ. You can use the same information to configure using Oracle Enterprise Manager 10g.

   <resource-provider
       class="com.evermind.server.deployment.ContextScanningResourceProvider"
       name="MQSeries">
     <description> MQSeries resource provider </description>
     <property
         name="java.naming.factory.initial"
         value="com.sun.jndi.fscontext.RefFSContextFactory">
     </property>
     <property
         name="java.naming.provider.url"
         value="file:/var/mqm/JNDI-Directory">
     </property>
   </resource-provider>
   
   

3. Add the following WebSphere MQ JMS client JAR files to J2EE_HOME/lib:

   com.ibm.mq.jar
   com.ibm.mqbind.jar
   com.ibm.mqjms.jar
   mqji.properties
   
   

4. Add the file system JNDI JAR files fscontext.jar and providerutil.jar to J2EE_HOME/lib.

Configuring SonicMQ

To configure SonicMQ, perform the following steps:

1. Install and configure SonicMQ on your system, then verify the installation by running any examples or tools supplied by the vendor. (See the documentation supplied with your software for instructions.)

2. Configure the resource provider. You can use either of two methods to configure the resource provider: Use Oracle Enterprise Manager 10g (as shown in "Define the OJMS Resource Provider"), or use the <resource-provider> element in orion-application.xml. Use either method to add SonicMQ as a custom resource provider. The following example demonstrates using the <resource-provider> element to configure SonicMQ. You can use the same information to configure using Oracle Enterprise Manager 10g.

   <resource-provider
     class="com.evermind.server.deloyment.ContextScanningResourceProvider"
     name="SonicJMS">
      <description>
         SonicJMS resource provider.
      </description>
      <property name="java.naming.factory.initial"
            value="com.sun.jndi.fscontext.RefFSContextFactory">
      <property name="java.naming.provider.url"
            value="file:/private/jndi-directory/">
   </resource-provider>
   
   

3. Add the following SonicMQ JMS client JAR files to J2EE_HOME/lib:

   Sonic_client.jar
   Sonic_XA.jar
   

Configuring SwiftMQ

To configure SwiftMQ, perform the following steps:

1. Install and configure SwiftMQ on your system, then verify the installation by running any examples or tools supplied by the vendor. (See the documentation provided with your software for instructions.)

2. Configure the resource provider. You can use either of two methods to configure the resource provider: Use Oracle Enterprise Manager 10g (as shown in "Define the OJMS Resource Provider"), or use the <resource-provider> element in orion-application.xml. Use either method to add SwiftMQ as a custom resource provider. The following example demonstrates using the <resource-provider> element to configure SwiftMQ. You can use the same information to configure using Oracle Enterprise Manager 10g.

   <resource-provider
     class="com.evermind.server.deloyment.ContextScanningResourceProvider"
     name="SwiftMQ">
      <description>
         SwiftMQ resource provider.
      </description>
      <property name="java.naming.factory.initial"
         value="com.swiftmq.jndi.InitialContextFactoryImpl">
      <property name="java.naming.provider.url"
         value="smqp://localhost:4001">
   </resource-provider>
   
   

3. Add the following SwiftMQ JMS client JAR files to J2EE_HOME/lib:

   swiftmq.jar
   

Terminology

The terms introduced here are explained in the Oracle Application Server High Availability Guide and the Oracle Process Manager and Notification Server Administrator's Guide.

• OHS—Oracle HTTP Server

• OracleAS Cluster—A grouping of similarly configured Oracle Application Server instances

• Oracle Application Server Instance—Represents an installation of Oracle Application Server (that is, an ORACLE_HOME)

• OC4J Instance—Within an Oracle Application Server instance there can be multiple OC4J instances, and each OC4J instance has 1 to n identically-configured JVMs.

• Factory—Denotes a JMS connection factory

• Destination —Denotes a JMS destination

OracleAS JMS Server Distributed Destinations

In this configuration, OHS services HTTP requests and load balances them across the two Oracle Application Server instances in an Oracle Application Server cluster. This can scale to more than two Oracle Application Server instances. This type of deployment has several advantages:

• High throughput is achieved because applications and the JMS server are both running inside the same JVM and no interprocess communication is necessary.

• Load balancing promotes high throughput as well as high availability.

• There is no single point of failure. As long as one OC4J process is available, then requests can be processed.

• Oracle Application Server instances can be clustered without impacting JMS operations.

• Destination objects can be persistent or in-memory.

Figure 3-2 OracleAS JMS Server Distributed Destinations

Description of the illustration O_1087.gif

Within each Oracle Application Server instance, two OC4J instances have been defined. Each of these OC4J instances is running a separate application. In other words, OC4J instance #1 (Home1) is running Application #1 while OC4J instance #2 (Home2) is running Application #2. Remember, each OC4J instance can be configured to run multiple JVMs, allowing the application to scale across these multiple JVMs.

Within an Oracle Application Server cluster, the configuration information for each Oracle Application Server instance is identical (except for the instance-specific information such as host name, port numbers, and so on). This means that Application #1 deployed to OC4J instance #1 in Oracle Application Server instance #1 is also deployed on OC4J instance #1 in Oracle Application Server instance #2. This type of architecture allows for load balancing of messages across multiple Oracle Application Server instances—as well as high availability of the JMS application, especially if Oracle Application Server instance #2 is deployed to another node to ensure against hardware failure.

The sender and receiver of each application must be deployed together on an OC4J instance. In other words, a message enqueued to the JMS Server in one OC4J process can be dequeued only from that OC4J process.

All factories and destinations are defined on all OC4J processes. Each OC4J process has a separate copy of each of the destinations. The copies of destinations are not replicated or synchronized. So, in the diagram, Application #1 is writing to a destination called myQueue1. This destination physically exists in two locations (Oracle Application Server instance #1 and #2) and is managed by the respective JMS servers in each OC4J instance.

Note that this type of JMS deployment is suited only for specific types of JMS applications. Assuming that message order is not a concern, messages are enqueued onto distributed queues of the same name. Given the semantics of JMS point-to-point messaging, messages must not be duplicated across multiple queues. In the preceding case, messages are sent to whatever queue the load balancing algorithm determines, and the MDBs dequeue them as they arrive.

Cold Failover Cluster

This configuration is a two-node cluster. Only one node is active at any time. The second node is made active if the first node fails. For Cold Failover documentation, see the Oracle Application Server 10g High Availability Guide.

Configure

Configure both nodes identically as described in the following example. Modify the jms.xml file for both OC4J instances. Set the host parameter in the jms-server to be:

<jms-server host=vmt.us.oracle.com port="9127">
….
….
</jms-server>
 

When using file-based message persistence for a queue, the file must be located on a shared disk that is accessible by both nodes. The shared disk must fail over with the virtual IP when failing over from one node to the other. Configure the persistence-file as follows:

<queue name="Demo Queue" location="jms/demoQueue" persistence-file="/path/to/shared_file_system/demoQueueFile">
        <description>A dummy queue</description>
</queue> 
 

Update, Stop, and Start

On each node, use the following commands to update configuration, stop, and start:

$ORACLE_HOME/dcm/bin/dcmctl updateConfig -ct  oc4j
$ORACLE_HOME/opmn/bin/opmnctl stopall
$ORACLE_HOME/opmn/bin/opmnctl startall
 

OracleAS Dedicated JMS Server

In this configuration, a single OC4J instance is configured as the dedicated JMS server within an Oracle Application Server clustered environment. This OC4J instance handles all messages, thus message ordering is always maintained. All JMS applications use this dedicated server to host their connection factories and destinations, and to service their enqueue and dequeue requests.

Only one OC4J JVM is acting as the dedicated JMS provider for all JMS applications within the cluster. This is achieved by limiting the JMS port range in the opmn.xml file to only one port for the dedicated OC4J instance.

Although this diagram shows the active JMS server in the OC4J Home instance, Oracle recommends that the JMS provider be hosted in its own OC4J instance. For example, although Home is the default OC4J instance running after an Oracle Application Server install, you should create a second OC4J instance with the Oracle Enterprise Manager 10g. In the opmn.xml file example following, we have created an OC4J instance called JMSserver.

Figure 3-3 OracleAS Dedicated JMS Server

Description of the illustration O_1088.gif

After creating an OC4J instance called JMSserver, we must make the following two changes to the opmn.xml file for this Oracle Application Server instance:

1. Make sure that only one JVM is started for this OC4J instance (JMSserver).

2. Specify only one value for the JMS port range for this instance.

The single JVM in the OC4J instance ensures that other JVMs will not attempt to use the same set of persistent files.

The single port value ensures that OPMN always assigns this value to the dedicated JMS server. This port value is used to define the connection factory in the jms.xml file that other OC4J instances will use to connect to the dedicated JMS server.

For more information on OPMN and dynamic port assignments, see the Oracle Process Manager and Notification Server Administrator's Guide.

Modifying the OPMN Configuration

The following XML from the opmn.xml file shows what changes must be made and how to find where to make these changes.

• Assuming an OC4J instance has been created through Oracle Enterprise Manager 10g called JMSserver, then the line denoted by (1) demonstrates where to locate the start of the JMSserver definition.

• The line denoted by (2) is the JMS port range that OPMN uses when assigning JMS ports to OC4J JVMs. For the desired dedicated OC4J instance that acts as your JMS provider, narrow this range down to one value. In this example, the original range was from 3701-3800. In our connection factory definitions, we know the port to use by configuring this value as 3701-3701.

• The line denoted by (3) defines the number of JVMs that will be in the JMSserver default island. By default, this value is set to 1. This value must always be 1.

<ias-component id="OC4J">
  (1) <process-type id="JMSserver" module-id="OC4J" status="enabled"> 
     <module-data>
       <category id="start-parameters">
         <data id="java-options" value="-server 
           -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy 
           -Djava.awt.headless=true
         "/>
       </category>
       <category id="stop-parameters">
         <data id="java-options" 
           value="-Djava.security.policy=
             $ORACLE_HOME/j2ee/home/config/java2.policy 
           -Djava.awt.headless=true"/>
       </category>
    </module-data>
    <start timeout="600" retry="2"/>
    <stop timeout="120"/>
    <restart timeout="720" retry="2"/>
    <port id="ajp" range="3000-3100"/>
    <port id="rmi" range="3201-3300"/>
    (2) <port id="jms" range="3701-3701"/> 
    (3) <process-set id="default_island" numprocs="1"/> 
  </process-type>
</ias-component>

Configuring OracleAS JMS

As already described in this scenario, one of the OC4J instances is dedicated as the JMS server. Other OC4J instances and standalone JMS clients running outside OC4J must be set up to forward JMS requests to the dedicated JMS server. All connection factories and destinations are defined in the JMS server instance's jms.xml file. This jms.xml file should then be copied to all the other OC4J instances that will be communicating with the JMS server.

The connection factories configured in the jms.xml file on the dedicated JMS server should specify, explicitly, the host name and the port number of the server. These values, in particular the port number, should also use the single port number defined by OPMN for the dedicated server as discussed above. The same connection factory configuration should also be used in all other OC4J instances so that they all point to the dedicated JMS server for their operations.

Thus, if the dedicated JMS server runs on host1, port 3701, then all connection factories defined within the jms.xml file for each OC4J instance in the cluster should point to host1, port 3701—where this port is the single port available in the opmn.xml file used in the dedicated OC4J instance (in our example, JMSserver) used for the dedicated JMS server.

The destinations configured in the jms.xml file on the dedicated JMS server should also be configured on all other OC4J instances; the physical store for these destinations, however, is on the dedicated JMS server.

Queue Connection Factory Definition Example

The following is an example for defining a queue connection factory in the jms.xml file of the dedicated OracleAS JMS server.

<!-- Queue connection factory -->
<queue-connection-factory name="jms/MyQueueConnectionFactory"
          host="host1" port="3701"
          location="jms/MyQueueConnectionFactory"/>

Administrative changes (that is, add a new Destination object) should be made to the dedicated JMS server's jms.xml file. These changes should then be made in the jms.xml files of all other OC4J instances running JMS applications. Changes can be made either by hand or by copying the dedicated JMS server's jms.xml file to the other OC4J instances.

Deploying Applications

The user decides where the JMS applications will actually be deployed. Although the dedicated JMS server services JMS requests, it can also execute deployed JMS applications. JMS applications can also be deployed to other OC4J instances (that is, Home).

Remember, the jms.xml file from the dedicated JMS server must be propagated to all OC4J instances where JMS applications are to be deployed. JMS applications can also be deployed to standalone JMS clients running in separate JVMs.

High Availability

OPMN provides the failover mechanism to keep the dedicated JMS server up and running. If for some reason the JMS server fails, OPMN detects this and restarts the JVM. If a hardware failure occurs, then the only way to recover messages is to have the persisted destinations hosted on a network file system. An OC4J instance can then be brought up and configured to point to these persisted files.

See the Oracle Process Manager and Notification Server Administrator's Guidefor more information on how OPMN manages Oracle Application Server processes.

Using JMS with RAC Network Failover

A standalone OJMS client running against an RAC database must write code to obtain the connection again, by invoking the API com.evermind.sql.DbUtil.oracleFatalError(), to determine if the connection object is invalid. It must then reestablish the database connection if necessary. The oracleFatalError() method detects if the SQL error thrown by the database during network failover is a fatal error. This method takes in the SQL error and the database connection, and returns true if the error is a fatal error. If true, you may wish to aggressively roll back transactions and re-create the JMS state (such as connections, session, and messages that were lost).

The following example outlines the logic:

getMessage(QueueSesssion session)
{
    try
    {
        QueueReceiver rcvr;
         Message msgRec = null;
        QueueReceiver rcvr = session.createReceiver(rcvrQueue);
         msgRec = rcvr.receive();
    }
    catch(Exception e )
    {
        if (exc instanceof JMSException)
        {
           JMSException  jmsexc = (JMSException) exc;
           sql_ex = (SQLException)(jmsexc.getLinkedException());

           db_conn =
             (oracle.jms.AQjmsSession)session.getDBConnection();

           if ((DbUtil.oracleFatalError(sql_ex, db_conn))
           {
               // failover logic
            }
          }
     }
}

Using OJMS With Transparent Application Failover (TAF)

In most cases where TAF is configured, the application does not notice that failover to another database instance has occurred. So, you need not do anything to recover from failure.

However, in some cases, OC4J throws an ORA error when a failure occurs. OJMS passes these errors to the user as a JMSException with a linked SQL exception. In this case, do one or more of the following:

• As described in "Using JMS with RAC Network Failover", you can use the DbUtil.oracleFatalError method to determine if the error is a fatal error. If it is not a fatal error, then the client recovers by sleeping for a short time and then retrying the current operation.

• You can recover from failback and transient errors caused by incomplete failover by trying to use the JMS connection after a short time. Waiting allows the database failover to recover from the failure and reinstate itself.

• In the case of transaction exceptions (such as "Transaction must roll back" (ORA-25402) or "Transaction status unknown" (ORA-25405)) you must roll back the current operation and retry all operations past the last commit. The connection is not usable until the cause of the exception is dealt with. If this retry fails, then close and re create all connections and retry all noncommitted operations.