6
Oracle Message Broker Extensions

This chapter covers features that are not part of the JMS specification. These features are Oracle Message Broker specific features or extensions to the JMS specification.

This chapter covers the following:

• Using XML Messages

• Collecting Runtime Metrics

• Creating Destinations

• Using Client-Side Callouts

• Universal Connections and Universal Sessions

• Receiving with a Message ID

• Using AQ Rules for Message Selection

• Obtaining the JDBC Connection in Local Mode

Using XML Messages

Oracle Message Broker supports methods that translate between JMS messages and XML with the source being either an XML document or a JMS message. Each message translation retains all information. The translation methods depend on the Document Type Definition (DTD) defined in jms.dtd. The DTD is defined in the directory $OMB_HOME/src on Unix systems or %OMB_HOME%\src on Windows NT.

The jms.dtd provides a complete mapping of JMS message components to XML, including: the message header, standard message properties, and all JMS message body types.

Sending and Receiving XML Messages

Oracle Message Broker supports the following behavior for an application that uses HTTP. The client receives XML data from an HTTP post command. The client then uses the Oracle Message Broker translation methods to convert the XML data to JMS messages. If the destination queue or topic were included in the XML data, the client enqueues or publishes the JMS message.

Assuming that HTTP is the transport by which the XML capable application interacts with JMS, the Oracle Message Broker supports the following actions:

• A JMS client could receive HTTP get commands that request a message from a queue or topic. The client would perform a non-blocking receive on the queue or topic, and then translate the JMS message to XML, and return the XML data using HTTP.

• The destination queue or topic name is included in the XML data. The client would then enqueue or publish the message.

The XML_to_JMS Method

The XML_to_JMS method in the package oracle.oas.mercury.MercuryXML returns a JMS message. Table 6-1 shows the XML_to_JMS parameters. Refer to the Javadoc supplied with the Oracle Message Broker for a complete description of the parameters (the Javadoc distributed with the Oracle Message Broker is in the directory $OMB_HOME/doc/javadoc or %OMB_HOME%\doc\javadoc on Windows NT).

Table 6-1  XML_to_JMS parameters

The JMS_to_XML Method

The JMS_to_XML method found in the oracle.oas.mercury.MercuryXML package returns an XML document from the supplied JMS message. Table 6-2 shows the JMS_to_XML parameters. Refer to the Javadoc supplied with the Oracle Message Broker for a complete description of the parameters (the Javadoc distributed with the Oracle Message Broker is in the directory $OMB_HOME/doc/javadoc or %OMB_HOME%\doc\javadoc on Windows NT).

Table 6-2  JMS_to_XML parameters

Collecting Runtime Metrics

Oracle Message Broker collects metrics so that you can monitor Oracle Message Broker performance and activity. You can save the Oracle Message Broker metrics using the MsgBroker -stats option. Table 6-3 shows the metrics available for queues and topics. Table 6-4 shows the metrics available for Oracle Message Broker instances (for each active msg_broker entry in the directory). Table 6-5 shows the metrics available for the Oracle Message Broker process.

Table 6-3  Oracle Message Broker Queue and Topic Metrics

Table 6-4  Oracle Message Broker Instance Metrics

Table 6-5  Oracle Message Broker Process Metrics

Using DMS

Use the MsgBroker command with the -stats option to save the collected Dynamic Monitoring Service metrics to the DMS log file. MsgBroker -stats saves the DMS log file to a file with the same name as the associated Oracle Message Broker log (omblog) file, prepended with "dms-". Refer to "Working with Log Files" for information on the omblog file name, and the directory where the DMS log file is written.

The -stats option includes a parameter that specifies whether information is appended to the DMS log file, or if an existing log file is replaced. The -stats option also specifies the format for the data in the DMS log file. Refer to Table 2-2 for detailed information on the available MsgBroker -stats options.

DMS Format Options - Standard and Pretty

When DMS metrics are saved using MsgBroker -stats, the display options are standard format and pretty format. The pretty format allows easy viewing and uses indenting to illustrate the DMS directory hierarchy. The standard format is easy to parse with scripts and prints the full DMS pathnames on every line. Both formats use XML-like tags to delimit the metrics and the timestamps.

Each DMS metric save starts with a DMSDUMP tag as shown below (there may be more than one DMSDUMP saved in a DMS log file):

<DMSDUMP version = 2.0>

The DMSDUMP tag is always followed by a timestamp, of the form:

<timestamp>timestamp formatted-timestamp</timestamp>

Where:

timestamp represents milliseconds since the epoch (Jan 1, 1970)

formatted-timestamp is formatted and readable version of the same timestamp.

The timestamp is included for quick ordering and sorting.

Dumps end with a closing DMSDUMP tag of the form:

</DMSDUMP>

DMS Pretty Format

The following lines contain describe the pretty format data:

 jspy_uptime.value: 0 secs
 testNoun
  testState.value: 55 msecs
  testEvent.count: 3 ops
  testPhase.time: 0 msecs
 JDMS
  JVM
   jvmTotalMem.max: 6144.0 kbytes

Each line represents either a DMS Noun or Metric. Refer to Example 6-1 for more sample pretty format output.

Noun Format

Nouns are single strings on their own. Nouns never contain control characters or whitespace.

Metric Format

Metrics have the form:

metricname: value [units]

metricname fields never contain control characters or whitespace.

value field contains the metric's value. If the metric is a String metric, then this field may contain whitespace. Otherwise it is an integer or floating point number with no whitespace.

units field is optional.

The pretty format indenting indicates containment, so in this case testState.value is a child of testNoun, and its siblings include testEvent.count and testPhase.time.

DMS Standard Format

The following lines contain sample standard format data:

/jspy_uptime.value: 0
/testNoun/testState.value: 55
/testNoun/testEvent.count: 3
/testNoun/testPhase.time: 0
/JDMS/JVM/jvmTotalMem.max: 6144.0
/JDMS/JVM/jvmTotalMem.min: 6144.0

Each line represents a metric. Units are not included. Names for Nouns and Metrics have no control characters or whitespace. Refer to Example 6-2 for more sample pretty format output.

Noun Format

With standard format, noun names must be deduced from the metric names. Containment is indicated with the path separator `/' characters.

DMS-defined metrics

In addition to the Oracle Message Broker metrics, a DMS dump may contain any of the following pre-defined metrics:

/jspy_uptime.value: -- number of seconds since the process started
/JDMS/JVM/jvmTotalMem.max -- maximum observed JVM heap size 
/JDMS/JVM/jvmTotalMem.min -- minimum observed JVM heap size
/JDMS/JVM/jvmTotalMem.value -- current JVM heap size
/JDMS/JVM/jvmFreeMem.max -- maximum observed amount of free JVM heap space
/JDMS/JVM/jvmFreeMem.min -- minimum observed amount of free JVM heap space
/JDMS/JVM/jvmFreeMem.value -- current amount of free JVM heap space
/JDMS/Measurement/nodes.max -- maximum number of metrics+nouns allocated by DMS
/JDMS/Measurement/nodes.value -- # nouns + # metrics allocated by DMS
/JDMS/Measurement/lastID.value -- last noun/metric identifier allocated
/JDMS/Measurement/nounCreate.count -- number of DMS nouns created
/JDMS/Measurement/nounDestroy.count -- number of DMS nouns destroyed
/JDMS/Measurement/sensorCreate.count -- number of DMS sensors created
/JDMS/Measurement/sensorDestroy.count -- number of DMS sensors destroyed
/JDMS/Measurement/sampleVal.count -- # metric values served by DMS so far
/JDMS/Log/archiveCount.count -- number of rollovers for the DMS log
/JDMS/Log/bytesWritten.value -- bytes written by DMS logging
/JDMS/Log/init.count -- number of times that DMS log was initialized
/JDMS/Log/attribute_changed.count -- count of changes to DMS logging attributes


Example 6-1  Sample Dump Using Pretty Format
<DMSDUMP version = 2.0>
<timestamp>958084102187 (Thu May 11 15:28:22 PDT 2000)</timestamp>
 
 jspy_uptime.value: 0 secs
 testNoun
  testState.value: 55 msecs
  testEvent.count: 3 ops

testPhase.time: 0 msecs

 JDMS
  JVM
   jvmTotalMem.max: 6144.0 kbytes
   jvmTotalMem.min: 6144.0 kbytes
   jvmTotalMem.value: 6144 kbytes
   jvmFreeMem.max: 5665.0 kbytes
   jvmFreeMem.min: 5306.0 kbytes
   jvmFreeMem.value: 5306 kbytes
  Measurement
   nodes.max: 28.0 
   nodes.value: 28 
   lastID.value: 27 
   nounCreate.count: 2 ops
   nounDestroy.count: 0 ops
   sensorCreate.count: 8 ops
   sensorDestroy.count: 0 ops
   sampleVal.count: 150 ops
  Log
   archiveCount.count: 0 ops
   bytesWritten.value: 0 bytes
   init.count: 1 ops
   attribute_changed.count: 0 ops
</DMSDUMP>


Example 6-2  Sample DMS Output Using Standard Format
<DMSDUMP version = 2.0>
<timestamp>958084102111 (Thu May 11 15:28:22 PDT 2000)</timestamp>
/jspy_uptime.value: 0
/testNoun/testState.value: 55
/testNoun/testEvent.count: 3
/testNoun/testPhase.time: 0
/JDMS/JVM/jvmTotalMem.max: 6144.0
/JDMS/JVM/jvmTotalMem.min: 6144.0
/JDMS/JVM/jvmTotalMem.value: 6144
/JDMS/JVM/jvmFreeMem.max: 5665.0
/JDMS/JVM/jvmFreeMem.min: 5366.0
/JDMS/JVM/jvmFreeMem.value: 5366
/JDMS/Measurement/nodes.max: 28.0
/JDMS/Measurement/nodes.value: 28
/JDMS/Measurement/lastID.value: 27
/JDMS/Measurement/nounCreate.count: 2
/JDMS/Measurement/nounDestroy.count: 0
/JDMS/Measurement/sensorCreate.count: 8
/JDMS/Measurement/sensorDestroy.count: 0
/JDMS/Measurement/sampleVal.count: 106
/JDMS/Log/archiveCount.count: 0
/JDMS/Log/bytesWritten.value: 0
/JDMS/Log/init.count: 1
/JDMS/Log/attribute_changed.count: 0
</DMSDUMP>

AQ Driver Runtime Metrics

The AQ Driver optionally exports Oracle AQ specific statistics using DMS. Since DMS monitoring can consume processor and other resources, by default the AQ specific metric collection is disabled.

Table 6-6 shows the available AQ Driver runtime metrics.

Table 6-6  AQ Driver Runtime Metrics

The AQ Driver runtime metrics are collected for JMS queues and topics (multi-consumer AQ queues and single-consumer AQ queues). AQ implements a multi-consumer queue with:

• A base table with one row per message.

• A subscriber table with one row per subscriber.

• An index table with one row per pair (message_id, subscriber_id)

The per-subscriber metric ready_count is computed by querying the index table. The per-topic metrics (ready_count, expired_count, deferred_count) are computed by querying the basetable. If the ready_count for a topic is 0, then the ready_count for all subscribers to that topic will be 0. If the ready_count for a topic is 10, the ready_count for any subscriber to that topic will be less than or equal to 10 (the ready_count for all subscriber can be 10).

It is possible for schemas to show no queues or topics when there are queues/topics in that schema. This occurs when the username/password used to establish the JDBC connection by the AQ driver does not have access to execute queries on the tables created by AQ within that schema.

AQ Driver Runtime Metric Administration

Table 6-7 shows the Java properties that control AQ Driver runtime metric collection. The Oracle Message Broker does not support LDAP Directory based administration for AQ Driver runtime metrics.

Table 6-7  AQ Driver Runtime Metric Properties

Creating Destinations

Oracle Message Broker clients can use several methods to create destinations that are not JMS administered objects. A client uses these destinations to send or to publish messages without referencing the Oracle Message Broker administrative directory. Refer to the JMS specification, section 4.4.4, for a brief description of domain-specific destinations.

The methods Oracle Message Broker provides to create and use destinations are:

TopicSession.createTopic

to create a topic

Defining Destination Strings

The createQueue and createTopic methods each take a String argument that defines a destination. To describe a destination, use the following syntax for the destination string:

tag=value[,tag=value]*

The order of tags is not significant, nor is the case. The destination string syntax does not allow whitespace, embedded commas, or embedded "=" signs.

The createQueue and createTopic methods each require two tags: name and driver. The name and driver tag are defined as follows:

name	The destination name
driver	The driver name. The driver name must be one of the following: aq, aqlite, vol, mq, zyg, or rv.

In addition, when the driver is mq, the following tags are also required:

queue	The MQ specific queue name
manager	The name of the queue manager

For example, the following code creates an MQ Series queue using createQueue:

QueueSession qs = ...;
Queue q = qs.createQueue("driver=mq,name=q1,manager=mgr1,queue=mqq");

The following code creates a Volatile queue using createQueue:

QueueSession qs = ...;
Queue q = qs.createQueue("driver=vol,name=volq1");

Using Client-Side Callouts

Oracle Message Broker provides a facility for creating and using client-side callouts. Client-side callouts define message transformations or other user defined processing that is applied when messages are produced or consumed. Callout methods can be written in Java or C/C++.

A Callout method defines the transformations or processing that a message consumer performs before receiving messages. Likewise, message producers can also use callout methods to perform transformations or processing before sending messages. Since callout methods execute on the client-side, the Oracle Message Broker knows nothing of the transformations or of the callout methods.

This section covers the following:

• Defining Callout Methods

• Using Callouts in a Message Producer

• Using Callouts in a Message Consumer

• Using Properties to Indicate Callouts

• Sample Client Side Callout Programs

Defining Callout Methods

Oracle Message Broker supports both Java and C/C++ callout methods. Use the interfaces shown in this section to define callout methods. Example 6-3 shows a sample Java stub for a callout method.

Defining Java Callouts

To define a callout method in Java, implement the following Oracle Message Broker client-side interface (defined in oracle.oas.mercury.jmsClient.callout):

interface Callout
{
     public Message invoke(Message message) throws JMSException;
}


Example 6-3  Java Callout Sample Stub
 
import oracle.oas.mercury.jmsClient.callout.Callout;
class mapName implements Callout
{
public Message invoke(Message message)
{
/* Include invoke method code for MapName message transformation. */
return message;
}

To supply parameters to a callout method, a message producer sets the JMSType message header field to indicate the message type. A message producer can set this value to indicate the message type and the callout method can use this field as a flag for callout transformation processing.

C/C++ Callouts

To define a callout method in C/C++, implement the following Oracle Message Broker JNI. Use this JNI to create a dynamic library for each callout and include the following in the callout source:

#include <jni.h>
#ifdef __cplusplus
extern "C" {
#endif
JNIEXPORT void JNICALL Java_oracle_oas_mercury_jmsClient_callout_CMaps_invoke 
(JNIEnv jenv*, jobject javathis, jobject message);
#ifdef __cplusplus
}
#endif

This is the signature for the native method. Implement the callout transformation with this signature and then create a dynamic library. The name of the dynamic library is the same as the name of the callout.

To supply parameters to a callout method, a message producer sets the JMSType message header field to indicate the message type. A message producer can set this value to indicate the message type and the callout method can use this field as a flag for callout transformation processing.

For additional information on callouts, refer to the README file in the sample directory $OMB_HOME/samples/client/java/callout.

Using Callouts in a Message Producer

To register a callout in a message producer, either a QueueSender or a TopicPublisher, use the following method:

void MercuryProducer.setCallout(String calloutName) throws CalloutException

For example:

((MercuryProducer)sender).setCallout(pcallout);

To unregister a callout, use the following method:

MercuryProducer.setCallout(null);

To find the name of any registered callouts, use the following method:

String MercuryProducer.getCallout()

This returns a registered callout or null if a callout is not registered.

A client can use the following method to handle exceptions and return the original message:

Message MercuryProducer.getMsg()

This returns the original message, as it was before the callout transformation was attempted. The getMsg method returns a null value if no message was supplied to the callout routine.

The setCallout method specifies a transformation method, or a handler method that hands off messages to the appropriate transformation method.

When setCallout is invoked with a name, for example calloutName, the callout manager checks to see if a Java class, calloutName, can be found. If the name is available, the class is dynamically loaded. If the class is not available, the callout manager attempts to load a dynamic library with the name calloutName. If this fails the callout manager throws a CalloutException and the callout is set to null. Subsequent messages do not use any callouts until setCallout successfully completes.

After a queue sender calls send or a topic publisher calls publish, the Oracle Message Broker JMS client-side code sends messages to the CalloutManager, which invokes the transformation methods registered with setCallout(..), and returns the transformed message, which is then passed on to the Oracle Message Broker. If the callout fails, the callout manager throws a callout exception that contains the original message.

For additional information on callouts and samples showing callouts, refer to the README file in the sample directory $OMB_HOME/samples/client/java/callout.

Using Callouts in a Message Consumer

To register a callout in a message consumer, either a QueueReceiver or a TopicSubscriber, use the following method:

void setCallout(String calloutName) throws CalloutException

To unregister a callout, use the following method:

MercuryConsumer.setCallout(null);

To find the name of any registered callouts, use the following method:

String MercuryConsumer.getCallout()

This returns a registered callout or null if no callout is registered.

Handle exceptions using the following method:

Message CalloutException.getMsg()

This returns the original message, as it was before the callout transformation was attempted. The getMsg method returns a null value if no message was supplied to the callout routine.

The setCallout methods specifies a transformation method, or a handler method that hands off messages to the appropriate transformation method.

When setCallout is invoked with a name, for example calloutName, the callout manager checks to see if a Java class, calloutName, can be found. If the name is available, the class is dynamically loaded. If the class is not available, the callout manager attempts to load a dynamic library with the name calloutName. If this fails the callout manager throws a CalloutException and the callout is set to null. Subsequent messages do not use any callouts until setCallout successfully completes.

After a queue receiver calls receive or a topic subscriber calls receive, the Oracle Message Broker JMS client-side code sends messages to the callout manager, which invokes the transformation method registered with setCallout(..), and returns the transformed message, which is then passed on to the Oracle Message Broker. If the callout fails, the callout manager throws a callout exception that contains the original message.

For additional information on callouts, refer to the README file in the sample directory $OMB_HOME/samples/client/java/callout.

Using Properties to Indicate Callouts

When the message consumer or producer does not indicate a callout method by explicitly using setCallout, the application can use a Java property to specify a default callout method for either a producer or a consumer.

A message consumer can indicate a routine to be called upon receipt of messages by setting oracle.oas.mercury.callout.consumer. A message producer can indicate a method to be called when sending or publishing messages with the property oracle.oas.mercury.callout.producer.

For example the following property sets a callout method that specifies that the client TestClient should use the consumer callout method named myMap for callout transformations:

java -Doracle.oas.mercury.callout.consumer=myMap TestClient

Each message is sent to the user-indicated callout. By default, if the message consumer or producer does not explicitly specify a callout transformation, the Java property oracle.oas.mercury.callout.producer is checked. If this property is set, and the callout exists, that callout is used. Otherwise, no callout transformation is attempted.

To supply parameters to a callout method, a message producer sets the JMSType message header field to indicate the message type. A message producer can set this value to indicate the message type and the callout method can use this field as a flag for callout transformation processing.

For additional information on callouts, refer to the README file in the sample directory $OMB_HOME/samples/client/java/callout.

Sample Client Side Callout Programs

For additional information on callouts and examples showing callouts, refer to the README file in the sample directory $OMB_HOME/samples/client/java/callout.

Universal Connections and Universal Sessions

The Oracle Message Broker supports a JMS connection and session extension called Universal Connections and Universal Sessions. This extension allows a JMS connection to support both topic and queue connections with a single, Universal Connection. Likewise, a JMS session can support both topic and queue sessions with a single Universal Session.

This extension is implemented as follows, for connections and sessions:

• Instances of javax.jms.TopicConnection and javax.jms.QueueConnection returned from calls to Oracle Message Broker's ConnectionFactories implement the interface oracle.oas.mercury.MercuryConnection.

• The interface oracle.oas.mercury.MercuryConnection implements both TopicConnection and QueueConnection. Thus, you can cast a newly created connection, either topic or queue, to MercuryConnection.

• Instances of oracle.oas.mercury.MercuryConnection can create both TopicSessions and QueueSessions.

• Instances of javax.jms.QueueSession and javax.jms.TopicSession returned from calls to the Oracle Message Broker's version of TopicConnection, QueueConnection, or MercuryConnection can be cast to the type oracle.oas.mercury.MercurySession. MercurySession implements both TopicSession and QueueSession.

With this feature, you only need to create one connection, either a topic connection or a queue connection. The result can be cast to type MercuryConnection. The MercuryConnection implements both javax.jms.TopicConnection and javax.jms.QueueConnection and can be used wherever a javax.jms.*Connection is expected.

Likewise, you only need to create one session, either a topic session or a queue session. The result can be cast to type MercurySession. MercurySession implements both javax.jms.TopicSession and javax.jms.QueueSession and can be used wherever a javax.jms.*Session is expected.

Thus, using Universal Connections and Universal Sessions, access to a queue and a topic can be performed in the same transaction.

Receiving with a Message ID

The Oracle Message Broker provides a JMS extension to receive messages by specifying a message ID. This is facilitated by using the receive method for a message consumer. The receive returns a Message. Refer to the Oracle Message Broker Javadoc for the package oracle.oas.mercury.MercuryConsumer for a full description of receive (the Javadoc is available in the directory $OMB_HOME/doc/javadoc, or %OMB_HOME%\doc\javadoc on Windows NT).

Using AQ Rules for Message Selection

The Oracle Message Broker supports two types of message selectors when messages are stored using the AQ Driver, including:

• Standard Oracle Message Broker messages selectors (refer to "Using Message Selectors" for more information).

• AQ Rules based messages selectors. AQ Rules based message selectors are passed to Oracle AQ when an Oracle Message Broker JMS durable subscription is created for a topic using the AQ Driver (an Oracle AQ multi-consumer queue). AQ Rules based message selectors use Oracle AQ features to select specific messages that are stored in an AQ multi-consumer queue (JMS topic).

  Note: The Oracle Message Broker only supports AQ Rules based messages selectors for messages stored using the AQ Driver.

The benefits of using AQ Rules include:

• Scalability - AQ Rules provide better performance when there are many subscribers for a single topic.

• Lower storage requirements - Using AQ Rules, the rules are evaluated on enqueue. This allows Oracle AQ to avoid storing a message when the message does not satisfy any of the specified selectors. The Oracle Message Broker evaluates standard message selectors on dequeue, so with standard message selectors, all messages are stored in the underlying message store.

• Durability - With AQ Rules based message selectors, the message selector is as durable as the subscription. The Oracle Message Broker records both the AQ Rule based message selector and the durable subscription in the underlying Oracle 8i database tables representing the queue.

• Better selectors - AQ Rules accepts a more general syntax for message selectors. AQ Rules can also access a message body, while standard Oracle Message Broker message selectors cannot use the message body.

• AQ rules can call stored procedures supplied by Oracle or created by an Oracle 8i Database Server user.

Creating AQ Rules Based Message Selectors

Oracle Message Broker standard message selectors are specified according to the syntax in the JMS specification (refer to "Using Message Selectors" for more information). The AQ Rules engine accepts a more general message selectors syntax. Application developers create AQ Rules during the development of Oracle Message Broker applications.

To create AQ Rules based message selectors, application developers must understand the following:

• Oracle8 ADTs used to store Oracle Message Broker messages (see Appendix A, "Oracle AQ Driver ADTs").

• PL/SQL (see the Oracle 8i Database Server documentation).

• PL/SQL helper functions (see "PL/SQL Functions Supporting AQ Rules"). The Oracle Message Broker support for AQ Rules requires developers to access property values explicitly using function calls rather than implicitly as described in the JMS specification. The helper functions assist developers in accessing property values.

• Oracle AQ Rules. See the Oracle 8i Documentation Library for complete information on Oracle AQ and AQ Rules.

Message Selector Format

When Oracle Message Broker applications use AQ Rules based message selectors, the message selector must be a string. The string must be constructed so that it would be valid as the WHERE clause of a SQL statement. The message selector string is also restricted; it can only access columns in the underlying AQ queue table representing the JMS topic that the AQ Rule is to be applied to.

To determine the available columns that AQ Rules can be applied to, execute the following SQLPLUS command:

sqlplus> DESCRIBE queue_table

Where queue_table is the name of the queue table in which the JMS messages are stored (a queue table holds an AQ queue that stores a JMS topic in the Oracle 8i Database). When the AQ queue table is created, the Oracle Message Broker administrator specifies the Oracle8 ADT for the queue_table's user_data column. The types for all other queue_table columns are fixed for each queue table. Table 7-2 and Table 7-3 show the available types for the Oracle Message Broker AQ based queue table user_data column.

Table 6-8 describes how the ADT specified for the underlying AQ queue table affects the parts of JMS messages that can be selected using an AQ Rules based message selector. Each entry in Table 6-8 lists the type of the AQ Driver and the parts of the JMS message that can be accessed using a message selector for the specified ADT. All queues that Oracle Message Broker accesses use one of the eight data types for the user_data column shown in Table 6-8.

Keep the following in mind for the Exposes field in Table 6-8.

• Exposes nothing means the message is stored as a stream of bytes serialized in Java. The message is stored in the Database Server as a blob and should not be accessed using PL/SQL or AQ Rules based message selectors.

• Exposes message body and properties means the type used to create the queue table is an Oracle8 JMS ADT (see Appendix A, "Oracle AQ Driver ADTs"). Message properties and the message body can be accessed using PL/SQL or AQ Rules based message selectors.

  .

  Table 6-8  JDBC AQ Driver Queue Message Options

  Oracle8i ADT Used for Queue Table	Driver	Message Types Allowed	Exposes
  OMBAQ_BYTES_MSG	JDBC AQ	bytes	Exposes message body and properties
  OMBAQ_MAP_MSG	JDBC AQ	map	Exposes message body and properties
  OMBAQ_OBJECT_MSG	JDBC AQ	object	Exposes message body and properties
  OMBAQ_STREAM_MSG	JDBC AQ	stream	Exposes message body and properties
  OMBAQ_TEXT_MSG	JDBC AQ	text	Exposes message body and properties
  OMBAQ_SERIAL_MSG	JDBC AQ	All JMS Message Types	Exposes nothing
  RAW	OCI AQ	Non-queriable	Exposes nothing
  OMBAQ_MESSAGE_T	OCI AQ	Queriable	Exposes the message body. Does not expose the message properties.

PL/SQL Functions Supporting AQ Rules

This section provides tables showing the PL/SQL helper functions that the Oracle Message Broker provides for developers to use AQ Rules as message selectors. The helper functions are part of the aq.ombaq PL/SQL package that is included with the Oracle Message Broker installation. Each entry in Table 6-9, Table 6-10, Table 6-11, Table 6-12, and Table 6-13 shows a helper function, with its description, and an example showing how to use the function. The tables listing helper functions are specific to each message type ADT, as specified in Table 6-8.

An AQ Rule rule is specified as a boolean expression (one that evaluates to true or false) using syntax similar to the WHERE clause of a SQL query. This boolean expression can include conditions on:

1. The fixed columns from queue table. This allows an AQ Rule to access the fixed columns from a queue table as part of the AQ Rule, regardless of the type of the user_data column. For example, the following example uses the priority and corrid columns from a queue table:

   tab.priority > 2 AND tab.corrid = `PAYMENT'
   
   

2. The JMS message body, as stored in the queue table. The helper functions can assist in providing access to the JMS message body, as stored in the queue table with Oracle Message Broker ADTs, for particular message types, as shown in Table 6-8.

3. The JMS message properties, as stored in the queue table. The helper functions can assist in providing access to the JMS message properties, as stored in the queue table with Oracle Message Broker ADTs, for particular message types, as shown in Table 6-8.

4. The message body and the message properties can also be explicitly accessed from the user_data column. For example, the following example accesses properties from the user_data column:

   tab.user_data.ombaq_property.name = `X.X'
   
   

Using Helper Functions

When using the PL/SQL helper functions, the function name must be fully specified. For example, aq.ombaq.str_text is fully specified. However, the function, str_text is not fully specified.

The helper functions can only be used with queue table user_data columns of the following types:

• OMBAQ_MAP_MSG

• OMBAQ_STREAM_MSG

• OMBAQ_TEXT_MSG

• OMBAQ_BYTE_MSG

• OMBAQ_OBJECT_MSG

Some functions return an integer when they should return a boolean. Functions that return a boolean cannot be used with AQ Rules for an AQ subscriber. To overcome this limitation, these functions return 0 to indicate false and 1 to indicate true.

Number Property Helper Functions

The num_prop functions search the varray in which properties are stored and return the property that matches the specified name if the property value is stored as a SQL Number.

The num_prop functions return null if there is no property element with a matching name or if there is an element that matches, but the value is stored as a SQL varchar2. Properties in a JMS message with the following types are stored as a SQL Number:

• boolean

• byte

• short

• integer

• long

• float - float values may lose precision when converted from a Java float to a SQL Number and then back to a Java float.

String Property Helper Functions

The str_prop functions search the varray in which properties are stored and return the property that matches the specified name if the property is stored as a SQL varchar2.

The str_prop functions return null if there is no property element with a matching name or if there is an element that matches, but the value is stored as a SQL number. Properties in a JMS message with the following types are stored as a SQL varchar2:

• double - doubles are stored as a string since SQL Number cannot store the valid range of a Java double.

• string

Type of Property Helper Functions

The type_prop functions search the varray in which properties are stored and return a SQL integer that is the value of the ombaq_type field for the ombaq_property varray element. The value of the ombaq_type field determines whether str_prop or num_prop should be used to access the value of the property. The values for the types are defined in the package aq.ombaq. The type_prop functions return:

• The value of the ombaq _type field if there is a property element that matches and the property element is valid. The symbolic values for the types are defined in the aq.ombaq PL/SQL package installed with Oracle Message Broker.

• Null otherwise

In Property Test Helper Functions

The in_prop functions search the varray in which the properties are stored and return a SQL integer. The returned value is:

• 1 if there is a name that matches and the property element is valid.

• 0 otherwise.

Functions for aq.ombaq_bytes_msg Messages

Table 6-9 shows the AQ Rules message selector helper functions for messages stored in queue tables of type OMBAQ_BYTES_MSG ADT.

Table 6-9  OMBAQ_BYTES_MSG Helper Functions

function num_prop(msg in ombaq_bytes_msg, name in varchar2) return number;

aq.ombaq.num_prop(tab.user_data, `shortProperty') = 13

function str_prop(msg in ombaq_bytes_msg, name in varchar2) return varchar2;

aq.ombaq.str_prop(tab.user_data, `stringProperty') = `foo'

function in_prop(msg in ombaq_bytes_msg, name in varchar2) return integer;

aq.ombaq.in_prop(tab.user_data, `doNotSelectProperty') == 0

function type_prop(msg in ombaq_bytes_msg, name in varchar2) return integer;

aq.ombaq.type_prop(tab.user_data, `booleanProperty') = 1

Functions for aq.ombaq_map_msg Messages

Table 6-10 shows the AQ Rules message selector helper functions for messages stored in queue tables with the OMBAQ_MAP_MSG ADT type.

The functions num_map, str_map, in_map, and type_map are similar to the functions num_prop, str_prop, in_prop, and type_prop. The difference is the set of values that are searched. Functions of the form *_map search the varray that contains the map elements from a map message (the body of a map message). Functions of the form *_prop search the varray that contains the message properties.

Table 6-10  OMBAQ_MAP_MSG Helper Functions

function num_map(msg in ombaq_map_msg, name in varchar2) return number;

aq.ombaq.num_map(tab.user_data, `mapElemName') = 13

function str_map(msg in ombaq_map_msg, name in varchar2) return varchar2;

aq.ombaq.str_map(tab.user_data, `stringMapElem') = `foo'

function in_map(msg in ombaq_map_msg, name in varchar2) return integer;

aq.ombaq.in_map(tab.user_data, `doNotSelectElem') == 0

function type_map(msg in ombaq_map_msg, name in varchar2) return integer;

aq.ombaq.type_map(tab.user_data, `booleanMapElem') = 1

function num_prop(msg in ombaq_map_msg, name in varchar2) return number;

aq.ombaq.num_prop(tab.user_data, `shortProperty') = 13

function str_prop(msg in ombaq_map_msg, name in varchar2) return varchar2;

aq.ombaq.str_prop(tab.user_data, `stringProperty') = `foo'

function in_prop(msg in ombaq_map_msg, name in varchar2) return integer;

aq.ombaq.in_prop(tab.user_data, `doNotSelectProperty') == 0

function type_prop(msg in ombaq_map_msg, name in varchar2) return integer;

aq.ombaq.type_prop(tab.user_data, `booleanProperty') = 1

Functions for aq.ombaq_object_msg Messages

Table 6-11 shows the AQ Rules message selector helper functions for messages stored in queue tables with the OMBAQ_OBJECT_MSG ADT type.

Table 6-11  OMBAQ_OBJECT_MSG Helper Functions

function num_prop(msg in ombaq_object_msg, name in varchar2) return number;

aq.ombaq.num_prop(tab.user_data, `shortProperty') = 13

function str_prop(msg in ombaq_object_msg, name in varchar2) return varchar2;

aq.ombaq.str_prop(tab.user_data, `stringProperty') = `foo'

function in_prop(msg in ombaq_object_msg, name in varchar2) return integer;

aq.ombaq.in_prop(tab.user_data, `doNotSelectProperty') == 0

function type_prop(msg in ombaq_object_msg, name in varchar2) return integer;

aq.ombaq.type_prop(tab.user_data, `booleanProperty') = 1

Functions for aq.ombaq_stream_msg Messages

Table 6-12 shows the AQ Rules message selector helper functions for messages stored in queue tables with the OMBAQ_STREAM_MSG ADT type.

The functions num_stream, str_stream, and type_stream are similar to the functions num_prop, str_prop, and type_prop. The difference is the set of values that are searched and the argument use to specify how elements are matched. Functions of the form *_stream search the varray that contains the stream elements from a stream message (the body of a map message). Functions of the form *_prop search the varray that contains the message properties. Also, the *_stream function accept an integer that represents the index within a stream rather than a name. Since stream elements do not contain a name field, the only way to specify a stream element is to specify its position within the stream varray. The first element in a varray is at index 1, not at index 0.

Table 6-12  OMBAQ_STREAM_MSG Helper Functions

function num_stream(msg in ombaq_stream_msg, stream_index in integer) return 
number;

aq.ombaq.num_stream(tab.user_data,1) = -1

function str_stream(msg in ombaq_stream_msg, stream_index in integer) return 
varchar2;

aq.ombaq.str_stream(tab.user_data, 1) = `foo'

function type_stream(msg in ombaq_stream_msg, stream_index in integer) return 
varchar2;

aq.ombaq.type_stream(tab.user_data, 2) = 6

function num_prop(msg in ombaq_stream_msg, name in varchar2) return number;

aq.ombaq.num_prop(tab.user_data, `shortProperty') = 13

function str_prop(msg in ombaq_stream_msg, name in varchar2) return varchar2;

aq.ombaq.str_prop(tab.user_data, `stringProperty') = `foo'

function in_prop(msg in ombaq_stream_msg, name in varchar2) return integer;

aq.ombaq.in_prop(tab.user_data, `doNotSelectProperty') == 0

function type_prop(msg in ombaq_stream_msg, name in varchar2) return integer;

aq.ombaq.type_prop(tab.user_data, `booleanProperty') = 1

Functions for aq.ombaq_text_msg Messages

Table 6-13 shows the AQ Rules message selector helper functions for messages stored in queue tables of type OMBAQ_TEXT_MSG.

Table 6-13  OMBAQ_TEXT_MSG Helper Functions

function str_text(msg in ombaq_text_msg) return varchar2;

aq.ombaq.str_text(tab.user_data) = `textbody'

function size_text(msg in ombaq_text_msg) return integer;

aq.ombaq.size_text(tab.user_data) > 100

function num_prop(msg in ombaq_text_msg, name in varchar2) return number;

aq.ombaq.num_prop(tab.user_data, `shortProperty') = 13

function str_prop(msg in ombaq_text_msg, name in varchar2) return varchar2;

aq.ombaq.str_prop(tab.user_data, `stringProperty') = `foo'

function in_prop(msg in ombaq_text_msg, name in varchar2) return integer;

aq.ombaq.in_prop(tab.user_data, `doNotSelectProperty') == 0

function type_prop(msg in ombaq_text_msg, name in varchar2) return integer;

aq.ombaq.type_prop(tab.user_data, `booleanProperty') = 1

Selectors for aq.ombaq_serial_msg

The following selectors can be used when the type of the user_data column of the queue table is aq.ombaq_serial_msg. There are no helper functions available for this message type. AQ Rules can use fixed columns from the queue table. For example,

tab.priority > 2 and tab.corrid = `PAYMENT'

Selectors for raw

The following selectors can be used when the type of the user_data column of the queue table is aq.ombaq_serial_msg. There are no helper functions available for this message type. AQ Rules can use fixed columns from the queue table. For example,

tab.priority > 2 and tab.corrid = `PAYMENT'

Selectors for aq.message_t

The following selectors can be used when the type of the `user_data' column of the queue table is aq.ombaq_serial_msg. There are no helper functions available for this message type. AQ Rules can use fixed columns from the queue table. For example,

tab.priority > 2 and tab.corrid = `PAYMENT'

Obtaining the JDBC Connection in Local Mode

Using the AQ Driver, in JDBC Mode, Oracle Message Broker clients can access the JDBC connection associated with a transacted session, and perform JDBC operations within the transaction. Only when running in local mode, the method, oracle.oas.mercury.MercurySession.getJdbcConnection() allows you to obtain the JDBC connection.

Since all Oracle Message Broker JMS sessions that the Oracle Message Broker creates are instances of MercurySession, any connection that uses the AQ Driver in JDBC mode, with the following requirements, use the method getJdbcConnection():

• The configuration must be set up so that the session uses the JDBC AQ Driver

• The Oracle Message Broker must be running in local mode

• The session must be transacted

If a message listener has been registered for the session, the JDBC connection can only be used when a registered message listener is active for the session. A message listener is active when the `onMessage' method is executing or on the call stack for a method that is executing.

Sample Code Using a JDBC Connection

The following example uses the getJdbcConnection method in a JMS client.

Example 6-4 Sample JDBC Connection Using getJdbcConnection()

private static void addMessage(MercurySession qs,
        QueueSender snd, int i)
        throws Exception
    {
        TextMessage msg = qs.createTextMessage();
        msg.setText("this is message: " + msg.getJMSMessageID());
                                          snd.send(msg);
        Connection        conn = null;
        PreparedStatement stmt = null;
        try
        {
            conn = qs.getJdbcConnection();
            String cmd = "insert into jdbc_tmp_tbl VALUES (?)";
            stmt = conn.prepareStatement(cmd);

            System.out.println("adding messageID: " +
msg.getJMSMessageID());
            stmt.setString(1, msg.getJMSMessageID());

            stmt.executeUpdate();
        }
        catch (Exception e)
        {
            if (stmt != null) { stmt.close(); }
            throw e;
        }

        if ((i % 2) == 0)
        {
            System.out.println("commit session");
            qs.commit();
        }
        else
        {
            System.out.println("rollback session");
            qs.rollback();
        }
    }