7
Message Servers and Drivers

Oracle Message Broker includes drivers that access message storage and distribution facilities. Drivers allow client programs to produce and consume messages and allow the Oracle Message Broker to store messages. Oracle Message Broker supports several drivers, each having different characteristics, and depending on the driver, supporting JMS point-to-point or Publish/Subscribe messaging.

This chapter covers the following:

• Driver Configuration

• Driver Features Summary

• Oracle Advanced Queuing Driver

• Oracle AQ Lite Driver

• Oracle Volatile Driver

• IBM MQSeries Driver

• Oracle Multicast Driver

• TIB/Rendezvous Driver

Driver Configuration

Oracle Message Broker administration facilities store driver configuration information. For information on driver configuration using an LDAP Directory, see Chapter 4, "Administration". For information on driver configuration using lightweight configuration, without the LDAP Directory, see Chapter 13, "Lightweight Configuration".

Driver Features Summary

This section summarizes the features of the Oracle Message Broker Drivers in Table 7-1. Where references to the JMS specification are included, they are in the form [JMS X.X], where chapter and section number. For additional driver specific limitations and general Oracle Message Broker limitations, refer to the Oracle Message Broker Release Notes.

Table 7-1  JMS Features Supported by Oracle Message Broker Drivers

Driver	Persistent Delivery	Non persistent delivery	JMS Publish Subscribe	JMS Point to Point	Queue Browsers	Transacted Sessions	Durable Subscriber
Oracle AQ	3	No	3	3	3	3	3
AQ Lite	3	No	No	3	No	3	No
Volatile	No	3	3	3	3	3	3 (Note 1)
Multicast	No	3	3	No	No	No	3 (Note 1)
MQSeries	3	3	No	3	3	3	No
TIBCO	No	3	3	No	No	No	3 (Note 1)

Note 1: Durable Subscribers for the Volatile Driver, Mutlicast Driver, and the TIBCO Driver are only as durable as the process in which the Oracle Message Broker runs.

The JMS specification describes the features shown in the headings of Table 7-1 in the following sections: Persistent Delivery - [JMS 4.7], Non-Persistent Delivery [JMS 4.7], Publish/Subscribe [JMS 6], Point-to-Point [JMS 5], Queue Browsers [JMS 5.1], Transacted Sessions [JMS 4.4.7], Durable Subscriber [JMS 6.3].

Refer to the Java Message Service specification available from Javasoft at the following site for more information on JMS:

http://www.javasoft.com/products/jms

Oracle Advanced Queuing Driver

The Oracle Advanced Queuing Driver (Oracle AQ Driver) supports persistent delivery of JMS messages using the Oracle 8i Database Server Advanced Queueing (AQ) messaging infrastructure (see the Oracle 8i Application Developers Guide for more information on AQ).

See the section, "Driver Features Summary" for a list of the features and limitations of the Oracle AQ Driver.

In addition, the features shown in Table 7-1, the AQ Driver supports Oracle specific extensions that expose functionality unique to Oracle AQ. These extensions include:

• AQ Rules based message selection

• AQ Driver specific runtime metrics

The AQ Driver maps JMS topics to AQ multi-consumer queues and JMS queues to AQ single-consumer queues. Thus, the AQ Driver supports both JMS topics and JMS queues using Oracle AQ queues. The format of the AQ message stored in Oracle AQ is configurable using the Oracle Message Broker administrative facilities. The AQ Driver converts JMS messages to and from AQ messages during enqueues and dequeues respectively.

This section covers the following Oracle Message Broker AQ Driver topics:

• AQ Driver Connection Types

• AQ Messages

• JDBC Mode

• OCI Mode

• AQ Message Persistence

• AQ Tuning and Configuration

• AQ Failure Recovery

AQ Driver Connection Types

The AQ Driver uses one of two connection types to access Oracle AQ: JDBC connections or OCI connections. To support these connection types, the AQ Driver operates in one of two modes: JDBC Mode, or OCI Mode. The Oracle Message Broker administration facilities determine the AQ Driver Mode.

To specify OCI Mode for the OCI connections, or JDBC Mode for the JDBC connections, use the use_jdbc attribute for directory based administration, (see Table 4-9). Using Lightweight configuration, the property oracle.oas.mercury.driver.aq.useJdbc determines the AQ Driver Mode (see Table 13-5 for information on this property).

The benefits of using JDBC connections include:

• This configuration provides a rich set of data types (ADTs) for storing JMS messages. Using these ADTs, programmers can access the messages in AQ using the Oracle Message Broker with the AQ Driver or with other applications, such as PL/SQL.

• Portability - this configuration can use pure Java. Pure Java may be a better fit for most Oracle Message Broker applications, which are usually written in Java.

• Interoperability - the Oracle Message Broker is easier to use for application integration. Oracle Message Broker clients can share AQ queues with native Oracle applications.

• Message management - the message warehousing functionality of Oracle AQ is exposed to Oracle Message Broker clients. JMS messages stored in AQ can be can be queried using SQL.

• With an understanding of the native storage mechanism, PL/SQL applications can enqueue messages into a queue from which Oracle Message Broker JMS clients dequeue messages. PL/SQL applications can also dequeue messages that are enqueued by an Oracle Message Broker JMS client.

• Enables AQ rules - the AQ rules engine is available directly, since all the data in the JMS message that is stored in AQ is queriable.

• Easier debugging - when problems arise, the JDBC configuration is easier to debug, as compared with the OCI configuration which is implemented in C.

• A JDBC connection used to access Oracle AQ can be shared with the client if the Oracle Message Broker is running in Local Mode. This enables the client to access the Oracle Database Server in the same transaction as the Oracle Message Broker's Oracle AQ access.

The benefits of using OCI connections include:

• For some applications, the OCI configuration may provide a performance advantage for large messages. The actual performance characteristics for any given application depend on the size of the messages being sent, the number of messages sent, the tuning and configuration parameter settings, and many other factors.

• The OCI based AQ Driver uses a maximum timeout of 5 seconds for any blocking call, (other than create subscriber and destroy subscriber which can block due to deadlocks in the Database Server). The OCI based driver can be used with a Database Server in MTS mode, and it does not unnecessarily lock resources on the shared servers.

  Note: An Oracle Message Broker process can start the Oracle AQ Driver using only one AQ Driver Mode, either the OCI Mode or the JDBC Mode. For an active Oracle Message Broker to change the mode of its AQ Driver, the Oracle Message Broker must be shutdown and then restarted using the new mode.

AQ Messages

The AQ Driver supports several underlying AQ queue table types for storing JMS messages to destinations. The types of underlying AQ queue tables are referred to as Abstract Data Types (ADTs). A destination's configuration determines the ADT that the AQ Driver uses to store a message.

The administrator sets the configuration and assigns an ADT for a destination when the destination, queue or topic, is created. The AQ Driver sends JMS messages to a destination using the specified ADT. If the underlying AQ queue table does not support the ADT that the AQ Driver is sending, the Oracle Message Broker throws an exception.

The message types that the AQ Driver supports depends on the mode the AQ Driver is using. This section describes the message types for both AQ Driver modes.

• JDBC Mode Message Types

• OCI Mode Message Types

JDBC Mode Message Types

Table 7-2 shows the ADTs supported in JDBC mode. Oracle Message Broker supports different AQ queue table ADTs for each JMS message type, plus a generic AQ queue table ADT that supports all JMS messages. A queue created with any of the ADTs other than the generic type can only store one type of JMS message, either: map, stream, bytes, object, or text.

Developers use one of the AQ Driver's JDBC JMS ADTs when they want to do one or more of the following:

• Share queues between the Oracle Message Broker and PL/SQL applications and other Oracle8i applications.

• Use the AQ rules engine (see the Oracle 8i Application Developers Guide for more information).

• Use Oracle AQ message warehousing features (see the Oracle 8i Application Developers Guide for more information).

To access and use the underlying AQ messages using PL/SQL, or other Oracle tools, you need to understand how JMS messages are mapped into AQ queues. Refer to Appendix A, "Oracle AQ Driver ADTs" to for a complete description of the mapping between JMS messages and AQ queue tables.

Table 7-2  JDBC AQ Driver Queue Message Options

Queue Configuration	Description	Oracle8i ADT Used for Queue Table
bytes	The underlying AQ Queue only supports JMS bytes messages.	OMBAQ_BYTES_MSG
map	The underlying AQ Queue only supports JMS map messages.	OMBAQ_MAP_MSG
object	The underlying AQ Queue only supports JMS object messages.	OMBAQ_OBJECT_MSG
stream	The underlying AQ Queue only supports JMS stream messages.	OMBAQ_STREAM_MSG
text	The underlying AQ Queue only supports JMS text messages.	OMBAQ_TEXT_MSG
all	The underlying AQ Queue supports all JMS message types. With this type of AQ Queue, the message is serialized and stored as a stream of bytes. A queue that uses this type can store all message types, but is not queriable.	OMBAQ_SERIAL_MSG

Note: the queue configuration specified in the Queue Configuration column is specified using the queue or topic attribute aq_adt. See Table 4-17 and Table 4-18 for the list of valid values for the aq_adt attribute.

OCI Mode Message Types

Table 7-3 lists the types supported for the AQ Driver in OCI mode.To access and use the underlying AQ messages using PL/SQL, or other Oracle tools, you need to understand how JMS messages are mapped into AQ queues. Refer to Appendix A, "Oracle AQ Driver ADTs" to for a complete description of the mapping between JMS messages and AQ queue tables.

Note: The AQ Driver in OCI mode does not support access to AQ queues created with any of the AQ Driver's JDBC queue configurations.

Table 7-3  OCI AQ Driver Queue Message Options

Queue Configuration	Description	Oracle8i ADT Used for Queue Table
raw	The Oracle Message Broker administrator should select raw (non-queriable) mode when there is no need to query the contents of stored messages using SQL. The JMS message is serialized and stored as a raw payload in an AQ message. Non-queriable mode supports all the JMS message types. For non-queriable messages, the maximum message size is restricted only by the Oracle AQ payload size.	RAW
queriable	Administrators should select queriable mode to support queriable JMS messages (using SQL). The contents of the JMS message are mapped onto an AQ Driver defined abstract datatype (ADT). Using this type, the JMS properties are not saved.	OMBAQ_MESSAGE_T

Note: the queue configuration specified in the Queue Configuration column is specified using the queue or topic attribute aq_adt. See Table 4-17 and Table 4-18 for the list of valid values for the aq_adt attribute.

AQ Message Priority

When sending messages using the AQ Driver, the JMSPriority field is mapped to an associated AQ message priority (for message types where the JMS properties are retained). Native AQ priorities have a PL/SQL type BINARY_INTEGER, and the priority can be negative. Using the native AQ message system, a priority with a smaller value indicates a higher priority. However, with JMS messages, the valid values for the JMSPriority header fields are one of: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9. The values 0 - 4 are normal priority messages, and the values 5 - 9 are expedited priority messages (refer to [JMS 3.4.10] for more information).

The Oracle Message Broker converts the priority values as follows, when it is sending/publishing a message using the AQ Driver:

Priority stored in AQ = ( 10 - JMS_priority )

The Oracle Message Broker converts the priority value as follows, when it is receiving a message using the AQ Driver:

JMS_priority = ( 10 - AQ_priority )

Thus after a send and receive, the original JMS priority is returned.

JDBC Mode

The AQ Driver in the JDBC mode creates one JDBC connection per JMS session to provide operational access to AQ queues. The Oracle Message Broker also creates the administrative JDBC connections when the Oracle Message Broker is initialized.

The AQ Driver uses the service name stored using the administrative facilities for connecting using JDBC connections. The JDBC driver supports local and host naming, so the service name must be a host name or a local name (for more information, see the Oracle SQL*Net/DCE Administrator's Guide).

The AQ Driver creates a pool of JDBC connections to support administrative access (create/destroy subscriptions, create/destroy AQ queues).

The number of JDBC connections used for administrative purposes by the AQ Driver can be specified as a parameter using the Oracle Message Broker administrative facilities (maxSharedSessions). These administrative JDBC connections are used to create durable subscriptions, destroy durable subscriptions, create AQ queues, and destroy AQ queues.

The AQ Driver in JDBC mode supports both transacted and non-transacted JMS sessions.

Obtaining the JDBC Connection in Local Mode

Using the AQ Driver in JDBC Mode, with the Oracle Message Broker running in Local Mode, the JMS Client can obtain a JDBC connection associated with a transaction. For information on obtaining the JDBC connection, see "Obtaining the JDBC Connection in Local Mode".

OCI Mode

The AQ Driver in the OCI mode uses OCI connections to provide operational access to AQ queues. One Database Server connection is created per JMS session. Using the OCI mode, the AQ Driver and the Oracle Message Broker AQ administrative tools use JDBC connections for administrative access to AQ queues. Oracle Message Broker creates the OCI and JDBC connections when the Oracle Message Broker is initialized.

The AQ Driver uses the service name stored in the directory to establish OCI and JDBC connections. The JDBC driver supports local and host naming, so the service name must be a host name or a local name (for more information, see the Oracle SQL*Net/DCE Administrator's Guide).

The AQ Driver supports both transacted and non-transacted JMS sessions. For non-transacted JMS sessions, operations are done in the context of local transactions. If the Oracle Message Broker is running in Local Mode, and it is killed using Control-C, or it dies for any reason, transactions are rolled back by the Database Server as soon as the Database Server notices that the client connections have failed.

The AQ Driver supports JMS queue browsers. A query is executed when the queue browser is created which returns the message IDs of available messages. Messages enqueued after the browser has been created will be returned if retention is enabled for the AQ queue. There is a limit on the number of messages that can be returned by the browser (for information on AQ limitations, refer to the Oracle Message Broker Release Notes).

AQ Message Persistence

The AQ Driver supports only JMS persistent delivery mode. When the Oracle Message Broker sends a message using the AQ Driver, it sets the header value for JMSDeliveryMode to the value PERSISTENT.

Availability (JDBC Mode Only)

When running in JDBC mode, the AQ Driver can recover from Database Server failures. If the Database Server fails, and is then restarted after the Oracle Message Broker has been started:

• New JMS sessions can be created.

• Existing JMS sessions receive a rollback exception but can be used.

• Administrative access is possible using Oracle Message Broker administrative facilities after the DBMS has been restarted.

AQ User Identities

The Oracle AQ Driver supports multiple Database Server schemas. Oracle Message Broker allows schemas other than the default, the `aq' schema to be used to access the underlying AQ queues. When additional schemas are not needed, the AQ Driver supports the `aq' user and schema as the default for accessing the Database Server.

The AQ Driver uses two identities for its connections to the Database Server:

1. The admin identity - performs administrative actions with the AQ Driver.

   Administrative actions include:

   • Create or destroy subscribers

   • Create or destroy queues and queue tables

   • Query the number of available messages in a single-consumer queue

   • Query the number of available messages for a subscriber to a multi-consumer queue.

   • Query the names of subscribers at broker startup to a multi-consumer queue.

   • Query the status of a queue at broker startup.

2. The user identity - performs operational actions with the AQ Driver.

   Operational actions include:

   • Enqueue or dequeue messages from an underlying AQ queue.

Admin Identities

When Oracle Message Broker is configured using the LDAP Directory, the administrative identity is set using the following AQ Server entry attributes:

aq_username
aq_password

When Oracle Message Broker is configured using Lightweight Configuration, the administrative identity is set with the following properties:

oracle.oas.mercury.driver.aq.adminUser 
oracle.oas.mercury.driver.aq.adminPassword

User Identities

Oracle Message Broker clients can specify both a user identity and a password, or neither, when creating JMS connections with javax.jms.createTopicConnection or javax.jms.createQueueConnection.

When the user identity and the password are not supplied, the credentials used to create a Database Server connection to DBMS are those set as follows:

• When Oracle Message Broker is configured using the LDAP Directory, the user identity for operational access is set using the AQ Server entry attributes:

  aq_username
  aq_password
  
  

• When Oracle Message Broker is configured using Lightweight Configuration, the user identity is set with the properties:

  oracle.oas.mercury.driver.aq.adminUser 
  oracle.oas.mercury.driver.aq.adminPassword
  
  

When the user identity and the password are supplied as arguments in the either the method javax.jms.createTopicConnection, or javax.jms.createQueueConnection, the credentials used to create a Database Server connection to the underlying DBMS are:

• When Oracle Message Broker is configured using the LDAP Directory, the password is used, as supplied in the argument. The user identity is set using the name component of the supplied username argument. The supplied username argument is a full DN for an LDAP Directory user.

  For example, if the username is supplied as an argument in the createTopicConnection or createQueueConnection method, and the LDAP Directory is used for configuration, then the AQ driver uses the component, "william" as the username:

  cn=william,cn=users,,cn=omb,cn=products,cn=oraclecontext,<initial-context>
  
  

• When Oracle Message Broker is configured using Lightweight Configuration, the username and password are used as exactly as supplied in the arguments to javax.jms.createTopicConnection, or javax.jms.createQueueConnection.

Using Different AQ Identities for AQ Administration

To perform administrative access on queues in a schema "foo" when the Oracle Message Broker aq_server username is not equal to "foo" (assume it is "bar" and the queue to be accessed is foo.q1):

1. Grant the role ombadmin to the user bar.

2. Grant select privileges on the queue table in which the queue foo.q1 has been created to the user bar.

3. Grant update privileges on the queue table in which the queue foo.q1 has been created to the user bar.

4. If foo.q1 is a multi-consumer queue, grant select on table_name.aq$_q1_s and table_name.aq$_q1_i to the user bar.

   Where table_name is the name of the queue table in which the queue foo exists.

Using Different AQ Identities for AQ Operational Access

To perform operational access on queues in schema "foo" when the Database Server connection is authenticated with a name other than "foo" (assume it is bar and the queue to be accessed is foo.q1):

1. Grant the role ombuser to the user bar.

2. Grant enqueue and dequeue privileges to bar on the queue foo.q1 using a call to dbms_aqadm.grant_queue_privelege.

3. Specify bar as the username and the correct password in the call to javax.jms.createTopicConnection or javax.jms.createQueueConnection.

4. Grant select privileges on the queue table in which the queuefoo.q1 has been created to the user bar.

5. Grant update privileges on the queue table in which the queue foo.q1 has been created to the user bar.

AQ Tuning and Configuration

An administrator should tune the Database Server if an Oracle Message Broker is performing a large number of administrative operations. However, metrics are not provided to measure the waiting time for AQ related administrative operations. An Oracle Message Broker that performs a large number of administrative operations is likely to generate a large number of DBMS deadlocks since creating and destroying subscriptions requires exclusive locks to resources for which operational access, enqueues and dequeues, requires shared locks. It is safer to perform administrative actions offline, when there is no operational access to the queues.

AQ Queue Configuration

Oracle Message Broker administrative utilities create AQ queues and AQ queue tables. These AQ queues and AQ queue tables have an administrative interface that is available using PL/SQL with the package dbms_aqadm. This PL/SQL package can be used to alter the message retention set for a queue, and to alter other AQ specific table and queue parameters. By default, the use the Oracle Message Broker sets the following values when it creates AQ queues:

max_retries = 2147483647 (java.lang.Integer.MAX_VALUE) 
retry_delay = 0 
retention_time = 0

To alter any of these values, use the procedure dbms_aqadm.alter_queue.

AQ Failure Recovery

JMS applications that use the AQ Driver should be able to recover from a Database Server restart without restarting the Oracle Message Broker. The application does need to create new JMS sessions after the Database Server restart.

When the Database Server fails, it may need to be restarted. Consult the Oracle8i Documentation to determine when the Database Server must be restarted.

When an Oracle Message Broker client encounters an unexpected Oracle error, the client may need create a new JMS session, which will create a new Database Server connection. The Oracle Message Broker does not have to be restarted when unexpected Database Server errors occur.

AQ Driver Restrictions

1. The AQ Driver throws an exception when a message is enqueued to a multi-consumer queue and there are no consumers registered for that queue. This means, the Oracle Message Broker throws an exception when messages are published to a topic that uses an AQ queue and no subscriptions have been created for that topic.

2. The AQ Driver only supports PERSISTENT JMS delivery mode [JMS 4.7].

3. The AQ Driver, in OCI Mode, only supports JMS text messages when the aq_adt attribute for the queue or topic is set to the value queriable.

4. JMSProperties are not supported when the aq_adt attribute is set to queriable.

5. AQ Driver Transaction Limitation:

   Using a transacted JMS session, if dequeues are performed on a given topic using a given subscriber and an unsubscribe operation is then attempted before the session is committed, or rolled back, then the unsubscribe blocks until the dequeues are committed or rolled back.

   It is recommended that the dequeues that are performed using a given subscriber be committed, or rolled back, before unsubscribing that subscriber.

   Unsubscribe or subscribe should not be attempted when there are uncommitted sends or receives to the topic.

6. The AQ Driver only supports correlation IDs with less than 129 characters. When you call javax.jms.Message.setJMSCorrelation() with a value containing more than 128 characters for the correlation ID, the AQ Driver throws an exception.

7. The AQ Driver allows durable subscribers to topics. The AQ Driver does not support non-durable subscribers for topics.

8. If the AQ time manager process is never started, or if it dies, the following may occur.

   Dequeued messages will not be removed from the topic AQ table, even though the messages have been delivered. This could eventually cause the database to run out of tablespace.

   Start the AQ time manager by adding aq_tm_processes=1 to the Database Server initialization file. If the AQ time manager is running, the following command should return a line showing an active process:

   % ps -ef | grep ora_q
   
   

9. If an Oracle Message Broker running on a system uses the Oracle8i Database Server on another system to support Oracle AQ, the NLS_LANG environment variable should have the same value on both systems, or if the values are different, they should be compatible values.

   If the NLS_LANG environment variable is set on one system, and not set on another system, receives from topic subscribers from multi-consumer AQ queues may fail when there are messages available.

10. The JDBC based AQ Driver does not work when the AQ Driver attribute thin_jdbc is set to true. Do not set thin_jdbc to true when the attribute use_jdbc is also true.

Oracle AQ Lite Driver

The Oracle Message Broker Advanced Queueing (AQ) Lite Driver provides support for storing persistent messages to AQ Lite. AQ Lite is Oracle's Advanced Queuing product based on Oracle 8i Lite Release 4.0. The AQ Lite driver should not be confused with the Oracle Message Broker AQ Driver. These two drivers support substantially different Oracle AQ implementations (see "Oracle Advanced Queuing Driver" for information on the AQ Driver.)

Note: The Oracle Message Broker AQ Lite Driver is only supported on Windows NT and requires JDK 1.2.x.The Oracle AQ Lite Driver and the AQ Driver, either JDBC or OCI, are mutually exclusive. Only one of these drivers can be active in a given OMB Instance at a given time.

The AQ Lite Driver supports installations that do not demand the performance or scalabiity of the Oracle Message Broker's full AQ driver. The AQ Lite Driver is easier to maintain and consumes fewer system resources than the full AQ Driver. The AQ Lite Driver supports JMS in a smaller configuration, intended for small scale, or individual use.

Note: The AQ Driver provides better overall performance, higher concurrency, and offers richer functionality than the AQ Lite Driver. The AQ Lite Driver implements a subset of the AQ Driver's functionality. Refer to "Oracle Advanced Queuing Driver" for a description of the AQ Driver.

The AQ Lite Driver runs against one and only one instance of an Oracle Lite database and there can be only one AQ Lite Driver per OMB Instance.

Note: An Oracle Message Broker using the AQ Lite Driver must be co-located with the Oracle8i Lite database instance assigned to the AQ Lite Driver.

Connection Management

AQ Lite provides administrative and operational access to its AQ queues using connections known as Java Access Class (JAC) connections. The AQ Lite Driver uses JAC connections to communicate with AQ Lite queues as well as the Oracle Lite database. JAC connections created on a system can only connect to Oracle Lite database instances on the same system. Therefore, an OMB instance using the AQ Lite Driver must be co-located with the Oracle Lite database instance assigned to the AQ Lite Driver.

Using the AQ Lite Driver JAC connections are not pooled. A JAC connection is created each time a JMS session is created, and the connection is associated with the JMS Session for the life of the session. A JAC connection is closed when its corresponding JMS Session is terminated.

Transacted JMS Sessions

The AQ Lite Driver supports both transacted and non-transacted JMS sessions. The AQ Lite Driver implicitly commits at the end of each operation on an AQ Lite queue for JAC connections with non transacted JMS Sessions.

AQ Lite Message Persistence

The AQ Lite Driver supports only JMS persistent delivery mode. When the Oracle Message Broker sends a message using the AQ Driver, it sets the header value for JMSDeliveryMode to the value PERSISTENT.

AQ Lite Message Mapping

AQ Lite only supports message payloads of the type RAW. Thus, the AQ Lite Driver serializes all JMS messages and stores them as a RAW message payload. The JMS Message ID, Correlation ID, Expiration, and Priority header fields have similar analogues in the AQ Lite message header. The AQ Lite Driver maps these JMS header fields to the AQ Lite message header when it stores a message, and maps the JMS message. Similarly, when the AQ Lite Driver maps messages from AQ Lite to JMS, it copies these AQ Lite message header fields to the corresponding JMS message header fields.

AQ Lite Driver Propagation

The AQ Lite Driver supports message propagation using the Oracle Message Broker propagation facilities (see Chapter 8, "Oracle Message Broker Propagation" for more information).

Oracle Volatile Driver

The Oracle Message Broker Volatile Driver supports lightweight and quick delivery of JMS messages using in-memory communication facilities. The Volatile Driver is useful when high throughput of messages is required. For example, an application using current stock price information, where speed is required and persistence is not required. The Volatile Driver is also useful for communicating in any application where the messaging system does not require that messages be logged to stable storage.

Note: The Volatile Driver only supports NON-PERSISTENT JMS delivery mode [JMS 4.7].

The Volatile Driver stores messages using the same process and the same memory as the active JVM running the Oracle Message Broker.Messages sent using the Volatile Driver are only as persistent as the process in which the Oracle Message Broker runs.

Note: There is a restriction for the Oracle Message Broker when it is running in Local Mode. When sending messages using the Volatile Driver, both the message producer using a volatile destination and the message consumer for the destination must reside in the same JVM. Due to this restriction, Remote Mode is recommended for the Volatile Driver.

IBM MQSeries Driver

The IBM MQSeries Driver is based on IBM MQSeries V5.1. The MQSeries Driver supports the features, and has the limitations as described in the section, "Driver Features Summary".

In addition, the features shown in Table 7-1, the MQSeries Driver supports the following:

• All JMS message types in JMS mode and only the JMS TextMessage and JMS BytesMessage types in Native mode.

• Native mode support for interoperability with MQSeries applications

• Maximum MQSeries message size of 4 MB. The actual size of a JMS Message body that can be sent using the MQSeries Driver depends on which Driver mode is used (native or JMS). For either mode, the maximum size is smaller than 4 MB, although it is not possible to specify the exact maximum message size, due to differences in the size of the header information that is sent, and due to other overhead associated with sending messages.

MQSeries Message Mapping

Clients using the MQSeries Driver need to distinguish between messages passing between JMS clients and native MQSeries applications. This distinction is required due to limitations in MQSeries, and the fact that JMS requires that JMS messages be delivered to JMS clients without changes. Also, an existing native MQSeries application that uses its own message formats needs to be able to exchange messages with a JMS based application; this implies that a JMS implementation must be able to pass native message formats. Due to this distinction, an Oracle Message Broker administrator needs to configure queues that use the MQSeries Driver to indicate whether the queue is used with a native MQSeries application.

In this section, the terms, native message and native queue are used for messages exchanged through a queue configured for native MQSeries applications, and the terms, JMS message and JMS queue refer to messages exchanged through a queue configured for JMS clients.

Native Queues

For native queues, only the JMS TextMessage and JMS BytesMessage body types are supported.

Sending a JMS TextMessage to a native queue translates the message into an MQSeries message with the format MQFMT_STRING; the message buffer contains the characters of the Java String in the character set currently in use by the MQSeries queue manager.

The JMS BytesMessage body type can interoperate with a native MQSeries application that has defined its own message formats. MQSeries data conversion exits must be supplied for these message formats on the queue manager accessed by Oracle Message Broker (for more information on data conversion exits, see the MQSeries Application Programming Guide).

Table 7-4 shows the native message mapping.

Table 7-4  Native Queues Message Header Mapping

JMS Header	MQSeries Mapping
JMSMessageID	MQSeries messageID field
JMSCorrelationID	MQSeries correlationID field
JMSDeliveryMode	MQSeries persistence field
JMSExpiration	MQSeries expiry field
JMSPriority	MQSeries priority field
JMSType	For JMS BytesMessage body type, the JMSType header field is mapped to the MQSeries format field. MQSeries format field set to MQFMT_STRING for JMS TextMessage messages.
JMSReplyTo	For native messages, the JMSReplyTo field must refer to another MQSeries queue. If the destination specified in the JMSReplyTo field is configured for this broker: the provider_queue_name for that destination is used to set the MQSeries replyToQueueName field the replyToQueueManagerName is not set and will be set by the MQSeries queue manager. If the JMSReplyTo destination is not configured for this broker: both the replyToQueueName and the replyToQueueManagerName fields are set from the destination destinations not configured for the broker are created either via createQueue() or upon receipt of a native message which has the replyToQueueName and replyToQueueManagerName fields set ReplyTo queues that are not defined locally require the use of the DefXmitQName feature of MQSeries.

JMS Queues

For JMS queues, messages are serialized and sent as raw bytes and then deserialized upon receipt.

The MQSeries Driver maps a JMS message header to fields in the MQSeries message descriptor. Table 7-5 shows the mapping between JMS header fields and MQSeries header fields.

Table 7-5  JMS to MQSeries Message Header Mapping

JMS Header	MQSeries Mapping
JMSMessageID	MQSeries messageID field
JMSCorrelationID	not mapped
JMSDeliveryMode	MQSeries persistence field
JMSExpiration	MQSeries expiry field
JMSPriority	MQSeries priority field
JMSType	MQSeries format field set to MQFMT_NONE
JMSReplyTo	not mapped

Connections to MQSeries Queue Managers

Each JMS session has its own connection to a MQSeries queue manager. The connection is established when the session is created and closed when the session is closed.

Transaction Support

JMS transacted sessions are supported using the native MQSeries transaction support.

Multiple Queue Manager Support

Currently, the MQSeries Driver supports connections to only one MQSeries queue manager.

MQSeries Driver Configuration

Configuring the Oracle Message Broker with the MQSeries Driver involves performing both MQSeries queue administration using the native MQSeries administrative tools and Oracle Message Broker administration using the Oracle Message Broker administrative tools.

Note: Setup and configuration of MQSeries queues is solely the MQSeries administrator's task. Oracle Message Broker does not provide utilities for MQSeries administration.

Administrators use the MQSeries administrative tools to perform all MQSeries administrative tasks, such as creating queues in an MQSeries queue manager. For details on using the MQSeries administration tools, refer to:

http://www.software.ibm.com/ts/mqseries/library/manuals/

The administrator also has to use the Oracle Message Broker administrative tools to configure the Oracle Message Broker to use MQSeries. See "Oracle Message Broker Configuration" for more information.

Message Persistence

The MQSeries Driver supports both the JMS non persistent delivery mode and persistent delivery mode. When the Oracle Message Broker sends a message using the MQSeries Driver, the default value for the JMSDeliveryMode header is set to PERSISTENT.

MQSeries Driver Limitations

1. The MQSeries driver supports only the JMS point-to-point (PTP) model.

2. The Oracle Message Broker MQSeries Driver only supports connections to one MQSeries Queue Manager.

3. The Oracle Message Broker must be executing on the same system as the MQSeries queue manager.

4. The maximum MQSeries message size is 4 MB. For JMS mode, this implies that the entire JMS message in its serialized form must be less than 4 MB. In native mode, it is just the message body that is limited to 4 MB.

5. Use the native MQSeries administrative tools for all MQSeries administration. Use the Oracle Message Broker administrative utilities to define queues in the directory that are accessed using the MQSeries Driver.

6. The MQSeries Driver does not support the programmatic creation and deletion of queues.

Oracle Multicast Driver

The Oracle Message Broker Multicast Driver supports lightweight and quick delivery of JMS messages using multicast communication facilities. The Multicast Driver is based on the Oracle Application Server Multicast Communication libraries.

The Oracle Application Server Multicast communication protocol gathers processes into logical groups, and issues messages to these groups using an efficient, reliable communication protocol. The Oracle Multicast Protocol uses hardware multicast facilities and is scalable to any number of recipients within a Local Area Network (LAN). The Multicast Driver supports delivery of JMS messages using the Oracle Multicast Protocol.

You can set up a JMS Publish/Subscribe domain using Oracle Message Broker by distributing providers across participating sites within the domain. In this set up, an individual provider does not represent a performance bottleneck or a single point of failure for the domain. On a domain using the Oracle Message Broker and the Multicast Driver, when an individual provider is unavailable, all the remaining providers are able to publish, and subscribe to topics.

Understanding Multicast Driver Operation

Before using Oracle Message Broker with the Oracle Multicast Driver, it is important to understand the driver's functional behavior. Improper usage can result in unexpected system behavior and poor performance.

Oracle Message Broker's multicast facilities define the notion of group. A group is a virtual entity that gathers processes together. A group is defined by an IP multicast address and a port number, and contains:

• All Oracle Message Broker instances in a LAN that use the Oracle Multicast Driver with the same IP multicast address and port number.

• All the instances of the mcastsrv program in a LAN that also use the same IP multicast address and port number. Refer to "Starting and Stopping the Multicast Bootstrap Server" for more information on mcastsrv.

The group membership is defined as the set of processes that are part of the group. The group membership changes dynamically, with processes being started, terminated, or failing. There are two important rules:

• At least one instance of the mcastsrv program must be running prior to starting any Oracle Message Broker instance that uses the Multicast Driver.

• At any point in time, when the group membership changes, the new membership of the group must contain a majority of processes of the previous membership.

The second rule means that only a strict minority of processes can be terminated or fail at the same time. At the same time means before a new membership is recorded, which is typically in the order of 1 second for a failure. This implies that, when there are only two processes in the group, a mcastsrv program and a single Oracle Message Broker, the failure of one of these prevents the other from functioning properly. To protect against this situation, you should start more than one instance of the mcastsrv program.

Distributed Topics

The Multicast Driver maps JMS topics to Oracle Multicast communication groups. These groups support distributed topics and permit simultaneous message communication to many destinations; the JMS client publishing a message does not know the identity, location, or number of these destinations. When the Oracle Message Broker sends messages using the Multicast Driver, communication of the messages occurs without relying on a single, centralized component.

The Multicast Driver manages the distribution of information across remote Oracle Message Brokers. The Multicast Driver does not store messages in a centralized location, each message is distributed to subscribers as it is published. Multiple instances of the Oracle Message Broker using the Multicast Driver are distributed on all participating sites. The multiple instances of the Multicast Driver communicate to manage the production and consumption of messages in an efficient, and reliable manner.

Messages

The Multicast Driver transmits JMS messages and does not interpret them. When a JMS client consumes a message using the Multicast Driver, the message is expected to have been produced by another JMS client using the Multicast Driver.

Message Persistence

The Multicast Driver only supports the non persistent delivery mode. When the Oracle Message Broker sends a message using the Multicast Driver, the JMSDeliveryMode header field is expected to have the value NON_PERSISTENT.

Multicast Server Configuration

This section covers information an administrator needs to know to configure the Oracle Message Broker's Multicast Driver environment.

Setting Multicast Server Options

To use the Multicast Driver, an administrator needs to configure the IP multicast address and port number pair. Set these values using the Oracle Message Broker administrative tools. If multiple Oracle Message Brokers using the Multicast Driver are set up as a single domain, they need to use the same IP multicast address and port number pair. When an Oracle Message Broker starts, it prints the IP multicast address and port number in the Oracle Message Broker log file.

Warning: Results are unpredictable if an application other than another Oracle Message Broker uses the same IP multicast address and port number pair.

Starting and Stopping the Multicast Bootstrap Server

To initialize a domain with the Oracle Message Broker using the Multicast Driver, an Oracle Multicast bootstrap server, the mcastsrv program, needs to be running. The bootstrap server is only required while there are fewer than two Oracle Message Brokers using the Multicast Driver. After two Oracle Message Brokers are running, the bootstrap server can fail without affecting the ability of additional brokers to start up, or the distribution of messages in the domain. This section shows the command to start the bootstrap server.

A network of Oracle Message Brokers using the Multicast Driver requires one instance of a bootstrap server for initialization. The bootstrap server needs to use the same IP multicast address and port number pair as the group of Oracle Message Brokers using the Multicast Driver.

Start the Oracle Multicast bootstrap server using the command:

% mcastsrv ip-address port-number [network]

Where ip-address and port-number specify the address and port used for multicast communication. The network parameter can be used to specify a IP address if the system has more than one network card (more than one IP address).

When the bootstrap server starts, it prints its IP multicast address and port number to the console.

The mcastsrv program shuts down automatically once all the Oracle Message Broker instances that use the Oracle Multicast Driver with the same IP address and port number as the mcastsrv program, have been stopped.

MultiCast Driver Performance

The Oracle Multicast Driver implements only minimal flow control; it is the application's responsibility to avoid saturating the network with messages. If an application sends messages as fast as possible, the Oracle Message Broker may fail because it runs out of memory (the Oracle Message Broker keeps a copy of the messages it sends until it is sure that they have been received by all consumers).

When an application tries to send too many messages using the Oracle Multicast Driver, the underlying communication mechanism may be unable to free its buffers.

A throughput of up to 300 messages per second is a possible maximum, depending on the characteristics of the network and depending on the systems running the Oracle Multicast Drivers. This throughout is calculated as the sum of the individual throughputs of all publishers using a single OMB instance. However, there is no specific maximum, the throughput limit depends both on the speed of the consumers and the load on the network.

MultiCast Driver Limitations

1. The Multicast Driver supports only the JMS publish/subscribe model.

2. The Multicast Driver only supports NON-PERSISTENT JMS delivery mode [JMS 4.7].

3. The Multicast Driver does not support transacted sessions [JMS 4.4.7].

4. The maximum length for a topic name is 120 characters. Using the Oracle Message Broker administrative utilities, limit topic names to less than 120 characters.

5. If a JMS Client performs a very large number of publishes with no delay between each publish, or is running on a highly loaded system, errors may result. The workaround for this is to delay between each publish. As an indication of this problem, the following JMSException is written to the omblog file: driver state is invalid.

6. Using the Multicast Driver on a highly loaded system, it is possible that the driver will be deactivated. In this case, any subsequent invocation of the Multicast Driver driver generates an invalid driver exception. All other drivers in the Oracle Message Broker process are fully functional. In this case, to use the Multicast Driver again, the Oracle Message Broker must be restarted. When running in local mode, the JMS client that instantiated the Oracle Message Broker needs to be restarted.

TIB/Rendezvous Driver

The TIB®/Rendezvous(tm) (TIBCO) Driver is based on TIB/Rendezvous Release 5.x or TIB/Rendezvous Pro Release 5.x (when using the JDK 1.2 version of Oracle Message Broker, TIB/Rendezvous Pro Release 5.x is required). The TIBCO Driver provides lightweight and quick delivery of transient messages based on multicast communication facilities.

TIB/Rendezvous is a Message Oriented Middleware (MOM) product based on the Publish/Subscribe model. Applications on heterogeneous platforms communicate by exchanging data on specific subjects. An application can listen to one or more subjects using TIBCO's subject-based addressing technology. TIB/Rendezvous provides lightweight reliable broadcast communication facilities that scale across multiple LANs. The TIBCO Driver allows the Oracle Message Broker to distribute JMS messages using TIB/Rendezvous.

An administrator can set up a JMS Publish/Subscribe domain using the Oracle Message Broker (provider) and the TIBCO Driver by distributing providers across participating sites within the domain. In this set up, an individual provider does not represent a performance bottleneck or a single point of failure for the domain. On a domain using the Oracle Message Broker and the TIBCO Driver, when an individual provider is unavailable, all the remaining providers are able to publish, and subscribe to topics.

Distributed Topics

The TIBCO Driver maps JMS topics to TIB/Rendezvous subjects. TIB/Rendezvous subjects support distributed topics and permit simultaneous communication of messages to several destinations; the JMS client publishing a message does not know the identity, location, or number of these destinations. Communication occurs without relying on a single, centralized component.

Messages

By default, the TIBCO Driver transmits JMS messages and does not interpret them. Messages received by a JMS client using the TIBCO Driver are expected to be produced by another JMS client using the TIBCO Driver. Optionally, the TIBCO Driver supports message mapping for converting JMS format messages to native TIB/Rendezvous format (refer to "TIB/Rendezvous Message Mapping").

Message Persistence

The TIBCO Driver only supports the JMS non persistent delivery mode. When the Oracle Message Broker sends a message using the TIBCO Driver, the JMSDeliveryMode header field is expected to have the value NON_PERSISTENT.

TIB/Rendezvous Message Mapping

The Oracle Message Broker Administrator supports a configuration where the TIBCO Driver converts JMS messages to native TIB/Rendezvous format. When the TIBCO Driver sends messages in native format, it maps JMS messages to structured self-describing TIB/Rendezvous messages. The TIBCO Driver performs this conversion for all JMS message types, including: TextMessage, BytesMessage, MapMessage, StreamMessage, and ObjectMessage. The native mapping option affects only topic publishers; topic subscribers can read both standard JMS and TIBCO Driver generated messages.

TIB/Rendezvous messages have a self-describing format composed of name/value pairs. A value is a basic type or another message. All the basic types valid in JMS messages have a corresponding type in the generated TIB/Rendezvous message, except the Java char type that is converted into a string containing a single character. Since native TIB/Rendezvous applications do not use this type, this limitation applies only when using the TIBCO Driver with the native mapping enabled to communicate messages between two JMS applications.

With the native mapping option enabled, the TIBCO Driver translates JMS header fields into a name/value pair with the name mapped to the header field name. Table 7-6 shows the native mapping for the JMS message header.

Table 7-6  TIBCO Driver Native Header Mapping

JMS Message Header	TIB/Rendezvous Native Message
JMSDestination: Destination	("JMSDestination", String)
JMSDeliveryMode: int	("JMSDeliveryMode", int)
JMSExpiration: long	("JMSException", long)
JMSPriority: int	("JMSPriority", int)
JMSMessageID: String	("JMSMessageID", String)
JMSTimestamp: long	("JMSTimestamp", long)
JMSCorrelationID: String	("JMSCorrelationID", String)
JMSReplyTo: Destination	("JMSReplyTo", String)
JMSType: String	("JMSType", String)
JMSRedelivered: boolean	("JMSRedelivered", boolean)

The TIBCO Driver translates JMS properties into an equivalent TIB/Rendezvous name/value pair stored in a nested message named Properties. Table 7-7 shows the native mapping for JMS properties.

Table 7-7  TIBCO Driver Native Properties Mapping

JMS Message Properties	TIB/Rendezvous Native Message
	("Properties", RvMsg)
("Name1", type1)	("Name1", type1)
("Name2", type2)	("Name2", type2)
("Namen", typen)	("Namen", typen)

The body of a JMS message is stored in a name/value pair named Body. The message has different values depending on the message type. A JMS message body is translated to include the message content, and an additional field, named BodyType that describes the type of the data in the body (Text, Bytes, Map, Stream, or Object). Table 7-8 shows the different mappings for the message body.

Table 7-8  JMS Message Body Translation for Native TIB/Rendezvous

JMS Message Type	Translation
TextMessage	String
BytesMessage	An opaque array of bytes
ObjectMessage	An opaque array of bytes
MapMessage	A nested TIB/Rendezvous message
StreamMessage	A nested TIB/Rendezvous message

Table 7-9 shows the translation values for a TextMessage. Table 7-10 shows the translation values for a BytesMessage. Table 7-11 shows the translation values for a MapMessage. Table 7-12 shows the translation values for a StreamMessage. Table 7-13 shows the translation values for the ObjectMessage type.

Table 7-9  TextMessage TIBCO Driver Native Body Mapping

JMS Message Body	TIB/Rendezvous Native Message
	("BodyType", "Text")
String	("Body", String)

Table 7-10  BytesMessage TIBCO Driver Native Body Mapping

JMS Message Body	TIB/Rendezvous Native Message
	("BodyType", "Bytes")
byte[]	("Body", RvOpaque)

Table 7-11  MapMessage TIBCO Driver Native Body Mapping

JMS Message Body	TIB/Rendezvous Native Message
	("BodyType", "Map")
	("Body", RvMsg)
("Name1", type1)	("Name1", type1)
("Name2", type2)	("Name2", type2)
("Namen", typen)	("Namen", typen)

Table 7-12  StreamMessage TIBCO Driver Native Body Mapping

JMS Message Body	TIB/Rendezvous Native Message
	("BodyType", "Stream")
	("Body", RvMsg)
type1	("1", type1)
type2	("2", type2)
typen	("n", typen)

Table 7-13  ObjectMessage TIBCO Driver Native Body Mapping

JMS Message Body	TIB/Rendezvous Native Message
	("BodyType","Object")
Object	("Body", RvOpaque)

Sessions

The number of TIB/Rendezvous sessions is limited by the maxPrivateConnections attribute of the ServerEntry. A TIB/Rendezvous session is created for each JMS session that has at least one producer or one consumer, and for each durable subscriber.

TIB/Rendezvous Installation and Administration

To use the Oracle Message Broker with the TIBCO Driver an administrator needs to install and configure TIB/Rendezvous Release 5.x or TIB/Rendezvous Pro Release 5.x. For information on TIB/Rendezvous installation and administration refer to the TIB/Rendezvous Administrator's Guide. For more information on TIB/Rendezvous see the following web site, http://www.rv.tibco.com/

Note: Setup and configuration of TIB/Rendezvous is solely the TIB/Rendezvous administrators task. Oracle Message Broker does not provide utilities for TIB/Rendezvous administration.

TIB/Rendezvous Driver Limitations

1. The TIB^®/Rendezvous^TM (TIBCO) Driver supports only the JMS publish/subscribe model.

2. The TIBCO Driver only supports NON-PERSISTENT JMS delivery mode [JMS 4.7].

3. The TIBCO Driver does not support transacted sessions [JMS 4.4.7].

4. The TIBCO Driver uses the max_private_sessions attribute to limit the number of sessions connected to the Rendezvous daemon. A session is created when a JMS session is created, and when a new durable subscriber is created. Therefore, creating a durable subscriber may cause an exception to be thrown because the Oracle Message Broker creates a Rendezvous session for the subscriber, even though it already maintains a valid JMS session. If an exception is thrown in this case, increase the value for the max_private_sessions attribute to increase the limit on the number of sessions connected to the Rendezvous daemon.

5. Using the JDK 1.2 version of Oracle Message Broker, TIB/Rendezvous Pro Release 5.x is required.