5
Oracle Message Broker Features

This chapter covers JMS programming features and provides information on programming using the Oracle Message Broker's implementation of JMS. Chapter 6, "Oracle Message Broker Extensions" covers additional Oracle specific features of the Oracle Message Broker.

This chapter covers the following:

Working With JMS Messages

This sections covers information on JMS messages. The Oracle Message Broker supports all JMS message types. Each JMS message consists of the following parts:

Header - header fields contain values used by clients and by the Oracle Message Broker to identify and route messages.
Properties - properties fields add a built-in facility for adding optional header information. Properties are a variable-length list of name/value pairs.
Body - JMS defines several types of message body. The Oracle Message Broker supports all JMS body types. The body contains the actual message data, the format of which depends on the type of the JMS message: TextMessage, BytesMessage, MapMessage, ObjectMessage, or StreamMessage.

Message Properties

JMS supports message properties that provide a built-in facility for adding optional header fields to a message. Properties allow Oracle Message Broker to support message selectors that select specific messages to distribute to a destination (see "Using Message Selectors", for more information). The JMS specification includes three types of properties:

Application-specific properties
JMS standard properties
Provider specific properties

Using the JMS_Oracle_Delay Message Property

The Oracle Message Broker defines the JMS_Oracle_Delay provider specific property. The JMS_Oracle_Delay is an integer whose value represents the number of milliseconds to delay before the message is available for delivery. Using Remote Mode, the JMS_Oracle_Delay property is an offset from the current time on the system on which the remote mode Oracle Message Broker runs. Client programs can set this property based on the current time to assure that messages are only sent during specific periods, for example, at night.

JMS_Oracle_Delay is only supported for the Volatile Driver and the AQ Driver.

For example to set the delivery delay property to 60 seconds:

// Delay delivery for 60 seconds
javax.jms.Message msg = ...;
msg.setIntProperty("JMS_Oracle_Delay", 60000);

And the following code sets the delivery delay to 10 seconds:

// Delay delivery for 10 seconds
javax.jms.Message msg = ...;
msg.setObjectProperty("JMS_Oracle_Delay", new Integer(10000));

Using Message Selectors

Message selectors allow the Oracle Message Broker to filter the messages that are sent to consumers based on a message selection criteria. This allows the Oracle Message Broker to handle filtering so that the client application does not need to receive messages that it is not interested in. Message selectors simplify a JMS client application and eliminate the overhead associated with sending messages to a client that it does not need.

A JMS client specifies message selection criteria when it creates a message consumer (either a QueueReceiver, QueueBrowser, or TopicSubscriber). JMS message selectors always reference either a header field or a message property. JMS message selectors do not apply to the message body. Table 5-1 lists the parts of the message header that can be specified in a message selector.

Note:
The AQ Driver supports JMS message selectors and AQ Rules based selectors. Refer to "Using AQ Rules for Message Selection" for information on AQ Rules.

Table 5-1 Message Selector Identifier References

Reference	Description
JMSPriority	The corresponding message header field
JMSDeliveryMode	The corresponding message header field
JMSMessageID	The corresponding message header field
JMS_Oracle_Delay	See "Using the JMS_Oracle_Delay Message Property" for details
JMSTimeStamp	The corresponding message header field
JMSCorrelationID	The corresponding message header field
A name that does not begin with JMS	An application specific property name

Message Selector Format

A message selector is a Java String whose syntax is based on the SQL92 conditional expression syntax. Section 3.8.1.1 of the JMS Specification defines the message selector syntax. In addition, Section 3.10 of the Java Language Specification defines the syntax for floating-point and integer literals that are valid in message selectors.

Keep the following points in mind when creating a message selector:

Integer literals of type long must have a suffix of 'l' or 'L'.
Floating point literals of type float must have a suffix of 'f' or 'F'.
Floating point literals of type double can have a suffix of 'd' or 'D'.
The exponent indicator can be 'e' or 'E'.

Example 5-1 shows code for a sample message selector for both point-to-point and publish/subscribe messaging.

Example 5-1 Sample Message Selector

String selector;
QueueReceiver receiver;
TopicSubscriber subscriber;

selector = new String("JMSType = 'car' ");
receiver = session.createReceiver(queue, selector);
subscriber = session.createSubscriber(topic, selector);

QueueReceivers and Message Selectors (Limitation)

Queue receivers that use message selectors can be inefficient. When a queue receiver is created with a message selector, any message that does not satisfy the selector cannot be delivered to that receiver and the message remains on the queue. This implies that the Oracle Message Broker performs a non-destructive read to examine the messages and then uses the message ID to dequeue messages when a message is found that satisfies the message selector.

To satisfy these requirements for a QueueReceiver, the Oracle Message Broker reads messages twice for QueueReceivers using message selectors. The first read is a non-destructive read and the second read is the dequeue by message ID.

Another inefficiency for QueueReceivers using message selectors is due to the separation between the Oracle Message Broker and the persistent message store. There is not an efficient technique to determine when messages have been added to a queue.

Because the Oracle Message Broker cannot always detect state changes in the message store, it must execute non-blocking reads when it attempts to retrieve new messages. Therefore, if there are 10 messages on a queue, and there is an outstanding request for a message by a receiver with a message selector, The Oracle Message Broker must poll the queue.

Therefore, when there is a QueueReceiver and a selector, polling is required.

Using a QueueBrowser

The Oracle Message Broker supports JMS QueueBrowsers. A QueueBrowser enables a client to look at messages on a queue without removing the messages. How the QueueBrowser functions depends upon the driver:

Volatile Driver

Messages that may be fetched are those ready for delivery when the browser is created and any messages sent and committed after the browser is created.

AQ Driver (OCI Mode)

Messages that may be fetched are messages ready for delivery when the browser is created. Messages that are ready for delivery or those in state 0 (see the Oracle 8i Database Server documentation for more information).

AQ Driver (JDBC Mode)

Messages may be fetched are those available using browsing as implemented by Oracle AQ.

AQ Lite Driver

Messages that may be fetched are messages ready for delivery when the browser is created. Messages that are ready for delivery when the browser is created.

MQ Driver

Uses native MQ browse functions.

Using Durable Subscribers

JMS publish/subscribe messaging defines methods for both non-durable and durable subscriptions. Non-durable subscriptions only last while the subscriber is active, and the client using the subscriber only sees the messages that are published while the subscriber is active. The Oracle Message Broker supports durable subscribers that retain the messages that are published to a topic until the durable subscriber, identified by a unique ID, receives the messages or until the messages expire (refer to Chapter 7, "Message Servers and Drivers" and the Oracle Message Broker Release Notes for limitations and for information on driver specific features related to durable subscribers).

The Oracle Message Broker manages durable subscribers by adding entries to the LDAP Directory for each durable subscriber. As JMS clients create durable subscribers, durable subscriber directory entries are added, and as clients delete durable subscribers directory entries are removed. There are several cases where the Oracle Message Broker handles special conditions for durable subscribers. The following is a list of some of these conditions:

If a JMS client creates a durable subscriber and the following are both true then the Oracle Message Broker throws an exception:
- The durable subscriber exists
- The durable subscriber is in-use. A durable subscriber is in-use when there is an active subscriber
If a JMS client creates a durable subscriber and the following are all true, then the current subscription is deleted and a new subscription is created. Any messages that were in the topic for the durable subscriber are lost when the subscription is deleted.
- The durable subscriber exists
- The durable subscriber is not in use
- A different filter has been specified for the durable subscriber
If a durable subscriber is created and the Oracle Message Broker cannot modify the LDAP Directory with the durable subscriber information, the Oracle Message Broker throws an exception.
All the directory attributes for a durable subscriber entry are read-only-after-create. This means that you can only view the durable subscriber attributes. If you need to modify a durable subscriber entry, delete the entry and then recreate it.

Using the PL/SQL Operational Interface

The PL/SQL package, ombaqpublic, implements the Oracle Message Broker's publicly supported PL/SQL operational interface to AQ queues and topics (multi-consumer AQ queues). This package allows PL/SQL applications running inside the Database Server to enqueue and dequeue messages directly from AQ queues and topics. The AQ Queues must have been created using the Oracle Message Broker administrative utilities, and they must use one of the following supported types:

OMBAQ_TEXT_MSG
OMBAQ_BYTES_MSG
MESSAGE_T

Oracle Message Broker can dequeue messages enqueued using the ombaqpublic PL/SQL interface, and convert them into a JMSTextMessage or a JMSBytesMessage format. The messages can then pass to JMS clients or be propagated between Oracle Message Brokers without any loss of information. In addition PL/SQL applications are able to browse or dequeue messages enqueued by the Oracle Message Broker into AQ queues using the ombaqpublic package (as long as the AQ Queues are in one of the supported types shown above).

The Oracle Message Broker PL/SQL package, ombaqpublic, is modeled after the AQ PL/SQL operational interface. The package allows setting of AQ message properties, including priority, delay, and expiration. The package also supports Oracle AQ enqueue options including: visibility and relative messageid. And the package supports the Oracle AQ dequeue options including dequeue mode and navigation using the types and constants defined by the Oracle AQ PL/SQL interfaces. Oracle Message Broker PL/SQL package, ombaqpublic, allows for JMS specific message properties to be set, for which there are no corresponding analogues in AQ. These properties include the SQL equivalents of JMSProperties, JMSType and JMSReplyTo.

The package provides four enqueue and four dequeue subroutines. Table 5-2 shows the Oracle Message Broker PL/SQL package subroutines.

Exceptions, are thrown when the package is improperly used and should be handled by the PL/SQL application developer.

The source for the PL/SQL routines is available in the following files:

$OMB_HOME/admin/plsql/ombaqpublic.sql
$OMB_HOME/admin/plsql/ombaqpublicb.sql

or, on Windows NT systems:

%OMB_HOME%\admin\plsql\ombaqpublic.sql
%OMB_HOME%\admin\plsql\ombaqpublicb.sql

Table 5-2 PL/SQL Client Interface Subroutines

PL/SQL Subroutine	Description
`dequeue_blob()`	Is used to dequeue messages from AQ queues in the form of BLOB messages.
`dequeue_clob()`	Is used to dequeue `CLOB` messages from AQ queues of type `OMBAQ_TEXT_MSG` and `MESSAGE_T`.
`dequeue_raw()`	Is used to dequeue messages from AQ queues in the form of `RAW` messages from queues of type `OMBAQ_BYTES_MSG`.
`dequeue_varchar()`	Is used to dequeue VARCHAR messages from AQ queues of type `OMBAQ_TEXT_MSG` and `MESSAGE_T`.
`enqueue_blob()`	Is used to enqueue `BLOB` messages into AQ queues of type `OMBAQ_BYTES_MSG`.
`enqueue_clob()`	Is used to enqueue `CLOB` messages into AQ queues of type `OMBAQ_TEXT_MSG` and `MESSAGE_T`.
`enqueue_raw()`	Is used to enqueue `RAW` messages into AQ queues of type `OMBAQ_BYTES_MSG`.
`enqueue_varchar()`	Is used to enqueue `VARCHAR` messages into AQ queues of type `OMBAQ_TEXT_MSG` and `MESSAGE_T`.

Running in Local Mode

The Oracle Message Broker provides two modes of operation, Remote Mode and Local Mode (Remote Mode is also called Non-Local Mode). When configured in Local Mode, one active Oracle Message Broker is created in each client JVM (that is, in each program that uses the JMS API). Local Mode provides a decentralized architecture, supporting a more efficient and more robust system with no single point of failure.

Local Mode Oracle Message Brokers are especially useful for applications using the Oracle Multicast Driver or the TIBCO Driver with multicast communication. In a typical Local Mode configuration, multiple Oracle Message Brokers, that is multiple clients, use a single directory instance. Running in Local Mode allows the Oracle Message Broker to operate very efficiently, without utilizing significant system resources.

In Local Mode, as in Remote Mode, the Oracle Message Broker provides two choices storing administrative objects:

Using an LDAP Directory (see Chapter 4 for information on LDAP Directory configuration)
Using Lightweight Configuration (see Chapter 13 for information on lightweight configuration)

This chapter describes how to use Oracle Message Broker Local Mode with an LDAP Directory, and how to use Oracle Message Broker Local Mode without an LDAP Directory.

Using Local Mode with an LDAP Directory

Operation in Local Mode is the only situation where multiple, active Oracle Message Brokers can share an Oracle Message Broker Instance in the LDAP Directory. Since Oracle Message Brokers working together using the Oracle Multicast Driver or the TIBCO Driver must define the same topics, Local Mode allows LDAP Directory administration to be significantly simplified. Using the LDAP Directory, only one Oracle Message Broker Instance needs to be maintained, since the multiple active Oracle Message Brokers share a single Oracle Message Broker Instance. Alternatively, using lightweight configuration, only one configuration file needs to be maintained.

A Local Mode Oracle Message Broker process is created when the local attribute in the Oracle Message Broker Instance's msg_broker entry is true, and an Oracle Message Broker client creates a connection (you do not use the MsgBroker command for Local Mode).

Note:
A remote client cannot use a Local Mode Oracle Message Broker.

Using Local Mode, the client uses the same JVM as the Oracle Message Broker instance. That is, the client and the broker are not only on the same system, but are also in the same process. Using Local Mode, the Oracle Message Broker instance is limited to local operation for the local client.

When a client looks up a connection factory associated with a local Oracle Message Broker, it creates an active OMB Instance in the client's JVM. Because a connection factory establishes a connection with an active Oracle Message Broker, a client program may use Local Mode and Remote Mode Oracle Message Brokers at the same time by creating multiple connection factories. Note that only one local OMB Instance is allowed per JVM process.

When starting a client that uses a local Oracle Message Broker, start the Java interpreter with the following flags:

-mxmemm (for Java 1.1.x)
-Xmxmemm (for Java 1.2)

Java JVM maximum heap size.

-msmemm (for Java 1.1.x)
-Xmsmemm (for Java 1.2)

Java JVM startup heap size.

-Doracle.oas.mercury.maxheap=mem

(Optional) - this is used to inform the Oracle Message Broker of the maximum JVM heap size.

Where mem is the memory, in megabytes, that you want to allocate to the Oracle Message Broker process. The mem value should be at least 8, specifying 8 megabytes per instance. If max_memory is set in the msg_broker entry, the mem value, as shown above, must be greater than or equal to the value of max_memory.

Table 2-3 shows the environment variables that Oracle Message Broker Local Mode programs need to start. The environment variables shown are defined in the Oracle Message Broker startup files. See "Working with the Administration Utilities" for more information on the startup environment.

Authentication in Local Mode

The authentication information and mode used by a JMS client to look up the connection factory will be the same information that the local OMB Instance uses when it is started. Thus, the authentication, user and password, are the same for the client and the Oracle Message Broker when running in Local Mode.

Stopping Oracle Message Broker in Local Mode (using an LDAP Directory)

A client program running the Oracle Message Broker should stop the Oracle Message Broker when it is finished. For information on stopping the Oracle Message Broker, see "Shutting Down".

Using Local Mode with Lightweight Configuration

Using Local Mode, the client uses the same JVM as the Oracle Message Broker instance. That is, the client and the broker are not only on the same system, but are also in the same process.

Local Mode Limitations

In Local Mode, the following limitations apply:

Propagation is disabled - see Chapter 8, "Oracle Message Broker Propagation" for details on using propagation in Remote Mode.
DMS is disabled - see "Collecting Runtime Metrics" for information on displaying runtime metrics in Remote Mode.
The MsgBroker command is not used.
The messages in the Volatile Driver can only be accessed from a single Oracle Message Broker Instance. If the Oracle Message Broker Instance is running in local mode, then all clients must access it from within the same process. Due to this restriction, Oracle Message Broker Remote Mode is recommended when using destinations with the Volatile Driver.

Sample Local and Remote Mode Client Programs

To illustrate a client program that uses a local Oracle Message Broker, we present a sample stock quote system. This system is composed of a stock quote database, one or several publishers, and any number of subscribers that represent the clients requesting quotes.

In this application, the publishers retrieve quotes from the databases and publish them to topics. The application supports any number of subscribers. Each subscriber subscribes to topics according to its interest, and receives quotes asynchronously. Topics can be mapped to individual stock quotes (for example, ORCL, for Oracle Corp. quotes), or to sets of similar stock quotes (for example, the high-tech market).

Stock Quotes Using a Remote Oracle Message Broker

When using a Remote Mode Oracle Message Broker to implement the stock quote application, all publishers and subscribers use a centralized Oracle Message Broker to forward stock quotes from the publishers to all of the subscribers (see Figure 5-1). Although this architecture is straightforward to deploy and maintain, it suffers from some limitations when applied to the stock quote application: it does not scale well to hundreds of subscribers since quotes are typically sent to all subscribers using a sequence of point-to-point messages, and a failure of the centralized Oracle Message Broker completely stops the service for all subscribers.

Figure 5-1 Remote Mode Oracle Message Broker Quote System

Stock Quotes Using Local Mode Oracle Message Brokers

When using a local Oracle Message Broker with either the TIBCO Driver or the Oracle Multicast Driver to implement the stock quote application, all publishers and subscribers use their own local copy of the Oracle Message Broker. All local Oracle Message Brokers use the same OMB instance in the directory, and thus define the same topics. Quotes sent by publishers are directly multicast to all subscribers without the intervention of a central Oracle Message Broker.

Figure 5-2 shows the stock quotes application configured with the local attribute set to true. This local architecture is decentralized, does not present a single point of failure, and scales to any number of subscribers. The local architecture is inherently scalable, since it uses multicast-based communication: multicast communication allows a single message to be sent to many destinations as a single operation, without using a sequence of point-to-point messages.

Figure 5-2 Local Mode Oracle Message Broker Quote System

Running in Remote Mode

The Oracle Message Broker provides two modes of operation, Remote Mode and Local Mode (Remote Mode is also called Non-Local Mode). When configured in Local Mode, one active Oracle Message Broker is created in each client JVM (that is, in each program that uses the JMS API). When configured in Remote Mode, Oracle Message Brokers run as a process using their own JVM.

Running in Remote Mode provides the following features:

Connection pooling in the AQ driver provides a fixed number of OCI connections that can service a much larger number of application programs. Clients are guaranteed access to the connection pool, even when some clients perform blocking receives.
Remote Mode Oracle Message Brokers can be accessed by remote processes, and by local processes. A Remote Mode Oracle Message Broker must be used if multiple processes need to share messages using the Volatile Driver.
Clients may not have the privileges to connect directly to a database. In this case, the Oracle Message Broker may perform the database access.
Propagation can be enabled - see Chapter 8, "Oracle Message Broker Propagation" for details on using propagation.
Dynamic Monitoring System (DMS) can be enabled - see "Collecting Runtime Metrics" for information on displaying runtime metrics in Remote Mode.

Starting Oracle Message Broker in Remote Mode

Table 2-3 shows the environment variables that Oracle Message Broker requires to start in Remote Mode. The environment variables shown are defined in the Oracle Message Broker startup files. See "Working with the Administration Utilities" for more information on the startup environment.

A remote Oracle Message Broker writes its address, an IOR, to the directory when it starts. The address is used by clients to establish connections, by the propagation manager to transfer messages, and to shutdown the Oracle Message Broker. Refer to "Starting and Stopping the Oracle Message Broker" for information on the MsgBroker command.

Note:
If multiple remote Oracle Message Broker use the same OMB Instance, the results may be unpredictable, see the section "Starting Oracle Message Broker Clients in Remote Mode" for more information.

Starting Oracle Message Broker Clients in Remote Mode

Table 2-3 shows the environment variables that Oracle Message Broker clients need to set to contact the Oracle Message Broker. The environment variables shown are defined in the Oracle Message Broker startup files. See "Working with the Administration Utilities" for more information on the startup environment.

Remote Mode Limitations

When the Oracle Message Broker is starting in Remote Mode, it checks to see if there is another active Remote Mode Oracle Message Broker process using the same OMB Instance in the same LDAP Directory. If so, the new Oracle Message Broker prints an error message and shuts down. This procedure is intended to prevent two remote Oracle Message Brokers from using the same OMB Instance.

The Oracle Message Broker may fail to detect another active Oracle Message Broker process in two scenarios:

If both Oracle Message Broker processes are started at the same time (race condition).

If one Oracle Message Broker process is configured to use SSL over IIOP, while the other Oracle Message Broker does not use SSL over IIOP.

Note:
If two remote Oracle Message Broker use the same OMB Instance in the LDAP Directory, the second Oracle Message Broker overwrites the first address. This would likely cause problems for one or more clients, and result in unpredictable Oracle Message Broker behavior.

Oracle Message Broker Version Checking

When an Oracle Message Broker JMS client contacts an active Oracle Message Broker, the Oracle Message Broker checks that the client is using a compatible version of the Oracle Message Broker client libraries. If the client is not running with a compatible version, the Oracle Message Broker throws a version exception.

The Oracle Message Broker and the JMS client-side runtime throws an exception if either are started with an unsupported JVM version. Refer to the release notes for information on supported JVM versions.

When the system property oracle.oas.mercury.anyjvm is set, the Oracle Message Broker and the client-side runtime do not check the JVM version.

Volatile Driver	Messages that may be fetched are those ready for delivery when the browser is created and any messages sent and committed after the browser is created.
AQ Driver (OCI Mode)	Messages that may be fetched are messages ready for delivery when the browser is created. Messages that are ready for delivery or those in state 0 (see the Oracle 8i Database Server documentation for more information).
AQ Driver (JDBC Mode)	Messages may be fetched are those available using browsing as implemented by Oracle AQ.
AQ Lite Driver	Messages that may be fetched are messages ready for delivery when the browser is created. Messages that are ready for delivery when the browser is created.
MQ Driver	Uses native MQ browse functions.

5 Oracle Message Broker Features