Oracle Message Broker Adminstration Guide Release 2.0.1.0 Part Number A65435-01 |
|
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:
This sections covers information on JMS messages. The Oracle Message Broker supports all JMS message types. Each JMS message consists of the following parts:
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:
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));
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. |
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 |
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:
Example 5-1 shows code for a sample message selector for both point-to-point and publish/subscribe messaging.
String selector; QueueReceiver receiver; TopicSubscriber subscriber; selector = new String("JMSType = 'car' "); receiver = session.createReceiver(queue, selector); subscriber = session.createSubscriber(topic, selector);
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.
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:
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:
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:
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
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:
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.
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).
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:
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.
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.
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, 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.
In Local Mode, the following limitations apply:
MsgBroker
command is not used.
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).
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.
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.
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:
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. |
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.
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:
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.
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|