A
Oracle AQ Driver ADTs

This appendix describes the Oracle8 abstract data types (ADTs) that the AQ Driver uses to store Oracle Message Broker messages in AQ.

The AQ Driver uses these ADTs is work with messages using the JDBC Mode. For details on configuring Oracle Message Broker for using JDBC Mode, see, and for information on specifying ADT types for topics and queues, refer to "AQ Messages". In this appendix, we refer to this feature of the AQ Driver as, JMS ADTs. The JMS ADTs define the data structures in Oracle8i, Oracle AQ Database Tables, that store Oracle Message Broker JMS messages. Using JMS ADTs, all of the data types available for a JMS message have corresponding types in the Oracle8 type system.

The JMS ADTs are defined as part of a PL/SQL package that is added to the Oracle8i Database Server during the Oracle Message Broker installation. The package includes PL/SQL procedures that support access to the ADTs using JDBC.

This appendix covers the following:

• JMS ADT Types

• PL/SQL Package Interface

This appendix assumes that you have knowledge of the following:

• The JMS specification

• Oracle AQ administration

• Oracle AQ operational access

• The Oracle8i type system

• Oracle8 AQ Reference Guide

• Oracle8 SQL Reference Guide

The AQ Driver connects to AQ Queues that have the following characteristics:

1. An AQ queue is stored in a queue table.

2. A queue table is created with a type. That type can be raw or a type defined using the Oracle8i type system.

3. The Oracle8i type system supports basic types, structures, arrays, and nested tables.

4. The JMS ADTs define one type for each JMS message type. A queue that uses a type can only store one message type: map, stream, bytes, object or text.

5. JMS ADTs define a type in which 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.

JMS ADT Types

The AQ Driver's JMS ADTs define abstract data types that store JMS messages in AQ tables. Five of the JMS ADTs store a particular JMS message type: map, stream, bytes, object, text. Another JMS ADT can store any of the JMS message types.

The AQ Driver maps data from the Oracle Message Broker JMS messages, to and from messages in AQ tables. These messages include components that are stored using SQL types. Table A-1 describes the mapping from JMS message Java types to SQL table types.

In the mapping shown in Table A-1, when a Java type is always mapped to the same SQL type, the name of the SQL type is specified. Using the JMS ADT, a SQL number type holds either a Java int, byte, short, boolean, or float. A type code determines the actual Java type stored in a SQL number type. The "Type Code" column lists the values for each Java type.

Table A-1  Mappings of Java Types to SQL Types in the AQ Driver

Java type	SQL type	Type Code	Notes
boolean	number	ombaq_boolean	Used in ombaq_property, ombaq_map_element, ombaq_stream_element
byte	number	ombaq_byte	Used in ombaq_property, ombaq_map_element, ombaq_stream_element
short	number	ombaq_short	Used in ombaq_property, ombaq_map_element, ombaq_stream_element
boolean	number	ombaq_boolean	Used in ombaq_property, ombaq_map_element, ombaq_stream_element
int	number or integer	ombaq_integer	Stored as number when used in ombaq_property, ombaq_map_element, ombaq_stream_element, otherwise stored as int.
long	number	ombaq_long	Used in ombaq_property, ombaq_map_element, ombaq_stream_element.
float	number	ombaq_float	Number can store range but may lose precision
double	varchar	ombaq_double	Number cannot store valid range for double. Store value as a string.
String	varchar	ombaq_string
char	varchar	ombaq_char	Used in ombaq_map_element, ombaq_stream_element.
byte[]	varchar	ombaq_bytearray	Stored as a hexadecimal encoded string. Two characters are used to encode each byte. The two characters used are the hexadecimal equivalent of the two nibbles of each byte.

Type ombaq_property

The JMS ADT type ombaq_property stores a message property. An array of instances of ombaq_property stores all of the message properties set for a message. Table A-2 describes the fields in ombaq_property.

Table A-2  Type ombaq_property Fields

Field	Type	Description
name	varchar2(100)	The name of the property. The JMS specification mandates what names are valid and invalid. This includes the syntax and prefixes that cannot be used.
str_value	varchar2(1000)	When ombaq_type is ombaq_string str_value stores the value of the string. When ombaq_type is ombaq_double str_value is the value of the double stored as a string per the Java Language Specification.
num_value	number	When ombaq_type is one of ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, or ombaq_float, num_value stores the value of the data.
ombaq_type	integer	One of: ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, ombaq_float, ombaq_double, ombaq_string. This determines whether str_value or num_value is used to store the value of the property.

Type ombaq_properties

The JMS ADT type ombaq_properties is a varray of type ombaq_property. The maximum size of the varray is 1000.

The JMS specification requires that each name used for a property is unique within a message. This is not enforced by the JMS ADT. A PL/SQL client can enqueue a message with 10 properties, such that each property has the same name. If an Oracle Message Broker client dequeues the message, Oracle Message Broker coerces the duplicate property names by appending a string to the end of the duplicate property names.

Type ombaq_header

The JMS ADT type ombaq_header contains fields that are common to all JMS messages. Table A-3 describes the fields in ombaq_header.

Table A-3  Type ombaq_header Fields

Field	Type	Description
aq_reply_to_is_topic	varchar2(1000)	This field indicates that the destination named in omb_replyto is either a topic or a queue.
omb_replyto	varchar2(1000)	The name of the destination to which a reply should be sent. This field contains the value that had been specified using a call to setJMSReplyTo when an Oracle Message Broker client enqueues a message. This field determines the value returned from a call to getJMSReplyTo when an Oracle Message Broker client dequeues a message. The type used in the call to setJMSReplyTo/getJMSReplyTo is a destination rather than a string. The value of omb_replyto must be a valid name for a destination and will be used to create an object of type javax.jms.Destination. If LDAP is used to store configuration information for the Oracle Message Broker, the Oracle Message Broker will treat this string as a DN and the DN must be within the same subtree a the msg_broker directory entry.
type	varchar2(100)	This field contains the value that had been specified using a call to setJMSType when an Oracle Message Broker client enqueues a message. This field determines the value returned from a call to getJMSType when an Oracle Message Broker client dequeues a message.
properties	ombaq_properties	The varray that contains the message properties.

Type ombaq_text_msg

The JMS ADT type ombaq_text_msg contains the fields needed to store a JMS text message. Table A-4 describes the fields in an ombaq_text_msg.

Table A-4  Type ombaq_text_msg Fields

Field	Type	Description
header	ombaq_header	The header for the message
null_flag	integer	An integer that should be 0 or 1. This determines whether the value of text_vc should be treated as null or the empty string when accessed via JDBC since JDBC converts the empty string to the null string on enqueues.
text_vc	varchar2(4000)	The text body is stored inline if possible.
text_lob	clob	The text body is stored in a CLOB if it is too large.

When the Oracle Message Broker runtime dequeues a text message using the AQ Driver, it sets the value of the message body as shown in Table A-5.

Table A-5  AQ Driver Dequeue from an ombaq_text_msg

null_flag	text_vc	text_lob	Value of Message Body
0	null	null	null
0	null	non-null	text_lob
0	non-null	null	text_vc
0	non-null	non-null	text_lob
<> 0	null	null	null
<> 0	null	non-null	null
<> 0	non-null	null	null
<> 0	non-null	non-null	null

When the Oracle Message Broker runtime enqueues a text message, it does the following:

• If the message body is null, null_flag is set to 0, text_vc is set to null and text_lob is set to null

• If the message body can be stored in text_vc, null_flag is set to 0, text_vc is set to the value of the message body, and text_lob is set to null.

• If the message body cannot be stored in text_vc, null_flag is set to 0, text_vc is set to null, and text_lob is set to the value of the message body.

Type ombaq_bytes_msg

The JMS ADT type ombaq_bytes_msg contains the fields needed to store a JMS bytes message. Table A-6 describes the fields in an ombaq_bytes_msg.

Table A-6  Type ombaq_bytes_msg Fields

Field	Type	Description
header	ombaq_header	The header for the message
bytes_raw	raw(2000)	The bytes body is stored inline if possible
bytes_lob	blob	The bytes body is stored as a blob if it is too large

When the Oracle Message Broker runtime dequeues a bytes message, it sets the value of the message body as shown in Table A-7.

Table A-7  AQ Driver Dequeue from an ombaq_bytes_msg

bytes_vc	bytes_lob	Value of message body
null	null	null
null	non-null	bytes_lob
non-null	null	bytes_vc
non-null	non-null	bytes_lob

When the Oracle Message Broker runtime enqueues a bytes message, it does the following:

• If the message body is null, bytes_vc is set to null and bytes_lob is set to null.

• If the message body can be stored in bytes_vc, bytes_vc is set to the value of the message body, and bytes_lob is set to null.

• If the message body cannot be stored in bytes_vc, bytes_vc is set to null, and bytes_lob is set to the value of the message body.

Type ombaq_object_msg Fields

The JMS ADT type ombaq_object_msg contains the fields needed to store a JMS object message. Table A-8 describes the fields in an ombaq_object_msg.

Table A-8  Type ombaq_object_msg Fields

Field	Type	Description
header	ombaq_header	The header for the message
object_raw	raw(2000)	The object body is stored inline if possible
object_lob	blob	The object body is stored as a blob if it is too large

When the Oracle Message Broker runtime dequeues an object message, it sets the value of the message body as shown in Table A-9.

Table A-9  AQ Driver Dequeue for an ombaq_object_msg

object_vc	object_lob	Value of Message Body
null	null	null
null	non-null	object_lob
non-null	null	object_vc
non-null	non-null	object_lob

When the Oracle Message Broker runtime enqueues an object message, it does the following:

• If the message body is null, object_vc is set to null and object_lob is set to null.

• If the message body can be stored in object_vc, object_vc is set to the value of the message body, and object_lob is set to null.

• If the message body cannot be stored in object_vc, object_vc is set to null, and object_lob is set to the value of the message body.

Type ombaq_stream_element Fields

The JMS ADT type ombaq_stream_element stores one element that has been set as part of a stream message body. An array of instances of ombaq_stream_element is used to store the entire stream message body. Table A-10 describes the fields in an ombaq_stream_element.

Table A-10  Type ombaq_stream_element Fields

Field	Type	Description
str_value	varchar2(2000)	When ombaq_type is ombaq_string str_value stores the value of the string. When ombaq_type is ombaq_double str_value is the value of the double stored as a string per the Java Language Specification. When ombaq_type is ombaq_char, str_value stores the character. When ombaq_type is ombaq_bytearray, str_value stores the byte array as a hexadecimal encoded string.
num_value	number	When ombaq_type is one of ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, or ombaq_float, num_value stores the value of the data.
ombaq_type	integer	One of: ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, ombaq_float, ombaq_double, ombaq_string, ombaq_char, ombaq_bytearray. This determines whether str_value or num_value is used to store the value of the property.

Type ombaq_stream_elements

The JMS ADT type ombaq_stream_elements is a varray of type ombaq_stream_element. The maximum size of the varray is 5000.

Type ombaq_stream_msg

The JMS ADT type ombaq_stream_msg contains the fields needed to store a JMS stream message. Table A-11 describes the fields in an ombaq_stream_msg.

Table A-11  Type ombaq_stream_msg Fields

Field	Type	Description
header	ombaq_header	The header for the message
elements	ombaq_stream_elements	The stream message body

Type ombaq_map_element

The JMS ADT type ombaq_map_element is used to store one element that has been set as part of a stream message body. An array of instances of ombaq_map_element is used to store the entire stream message body. Table A-12 describes the fields in an ombaq_map_element.

Table A-12  Type ombaq_map_element Fields

Field	Type	Description
name	varchar2(100)	The name of the map element. The JMS specification requires that all map elements for a particular map message have a unique name.
str_value	varchar2(2000)	When ombaq_type is ombaq_string str_value stores the value of the string. When ombaq_type is ombaq_double str_value is the value of the double stored as a string per the Java Language Specification. When ombaq_type is ombaq_char, str_value stores the character. When ombaq_type is ombaq_bytearray, str_value stores the byte array as a hexadecimal encoded string.
num_value	number	When ombaq_type is one of ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, or ombaq_float, num_value stores the value of the data.
ombaq_type	integer	One of: ombaq_boolean, ombaq_byte, ombaq_short, ombaq_integer, ombaq_long, ombaq_float, ombaq_double, ombaq_string, ombaq_char, ombaq_bytearray. This determines whether str_value or num_value is used to store the value of the property.

Type ombaq_map_elements

The JMS ADT ombaq_map_elements is a varray of type ombaq_map_element. The maximum size of the varray is 5000.

The JMS specification requires that each name used for a map element is unique within a message. The JMS ADT does not enforce this restriction. A PL/SQL client can enqueue a map message with 10 map elements such that each map element has the same name. If an Oracle Message Broker client dequeues the message, Oracle Message Broker will coerce the duplicate map element names by appending a string to the end of the duplicate map element names.

Type ombaq_map_msg

The JMS ADT type ombaq_map_msg contains the fields needed to store a JMS map message. Table A-13 describes the fields in an ombaq_map_msg.

Table A-13  Type ombaq_map_msg Fields

Field	Type	Description
header	ombaq_header	The header for the message
elements	ombaq_map_elements	The map message body

Type ombaq_serial_msg

The JMS ADT type ombaq_serial_msg contains the fields needed to store any JMS message. This type is meant to store a stream of bytes that represents a JMS message. The stream of bytes is created by the Oracle Message Broker runtime. This type is not meant to support access by PL/SQL clients. Table A-14 describes the fields in an ombaq_serial_msg.

Table A-14  Type ombaq_serial_msg Fields

Field	Type	Description
serial_raw	raw(2000)	Stores the stream of bytes if possible
serial_lob	blob	Stores the stream of bytes if serial_vc is too small

When the Oracle Message Broker runtime dequeues an serial message, it sets the value of the message body as shown in Table A-15.

Table A-15  AQ Dequeue for an ombaq_serial_msg

serial_vc	serial_lob	Value of Message
null	null	throw exception
null	non-null	serial_lob
non-null	null	serial_vc

When the Oracle Message Broker runtime enqueues a message to a queue of type ombaq_serial_msg, it does the following:

• If the stream of bytes can be stored in serial_vc, serial_vc is set to the value of the stream of bytes, and serial_lob is set to null.

• If the stream of bytes cannot be stored in serial_vc, serial_vc is set to null, and serial_lob is set to the value of the stream of bytes.

PL/SQL Package Interface

The JMS ADTs are defined in PL/SQL packages included with the Oracle Message Broker. The JMS ADTs are installed during the AQ Driver specific installation tasks. Refer to the Oracle Message Broker Installation Guide for information on AQ Driver specific installation tasks.

This section covers the following:

• PL/SQL Package Limitations

• Coercion and Invalid Data

• Sample Usage from PL/SQL

PL/SQL Package Limitations

AQ queues that are created using the JMS ADTs can be accessed with the Oracle Message Broker AQ Driver, or with any of the following clients:

• PL/SQL

• Oracle OCI

• JDBC

• Clients that uses Oracle precompilers

The JMS specification includes constraints on a JMS message that must be satisfied to produce a valid JMS message. The PL/SQL JMS ADT definitions do not automatically imply that types created using the JMS ADT are valid JMS messages. For example, a valid instance of a ombaq_text_message is not guaranteed to be a valid instance of javax.jms.TextMessage. This limitation creates the following problems:

1. The Oracle Message Broker must be able to handle messages that have been dequeued from an AQ queue, that are valid instances of one of the JMS ADTs, but that are not valid JMS messages (according to the JMS specification).

   The Oracle Message Broker solves this problem using coercion. See "Coercion and Invalid Data" for more information on how the Oracle Message Broker handles coercion.

2. The Oracle Message Broker should make it easy for non-Oracle Message Broker clients to enqueue messages with the guarantee that the message satisfies the JMS specification.

   The Oracle Message Broker solves this problem using the PL/SQL Operational Interface Package (this package only supports text and bytes messages, and does not support other message types). See "Using the PL/SQL Operational Interface" for information on the facilities available in this package.

Coercion and Invalid Data

The Oracle Message Broker must be prepared to dequeue messages from AQ queues, when the message was created using JMS ADTs that do not satisfy the JMS specification. This is true even if PL/SQL helper packages attempt to verify the enqueued messages.

Table A-16 describes some of the ways in which an AQ JMS ADT message may not satisfy the JMS specification.

Table A-16  Problems and Solutions for Invalid JMS Messages

Problem	Where this Problem may occur
num_value null when it must be non-null	ombaq_property, ombaq_stream_element, ombaq_map_element
str_value null when it must be non-null	ombaq_property, ombaq_stream_element, ombaq_map_element
num_value exceeds range implied by ombaq_type	ombaq_property, ombaq_stream_element, ombaq_map_element
invalid value for ombaq_type	ombaq_property, ombaq_stream_element, ombaq_map_element
invalid byte array value in str_value	ombaq_stream_element, ombaq_map_element
duplicate values for name in ombaq_property	ombaq_properties
invalid value for name	ombaq_property
null value for name	ombaq_property

The general solution to these problems is coercion. That is, the Oracle Message Broker AQ Driver corrects the errors in an obvious manner and attempts to avoid losing data. The intent is to make the errors obvious to Oracle Message Broker developers so that they will notice what went wrong with the content of a message and will know how to correct the problem based on the coercion that the Oracle Message Broker performs.

num_value null when it must be non-null

This occurs when ombaq_type indicates that num_value will be used to store the value of the property, map element or stream element and num_value is null. When this occurs the property, map element, or stream element is coerced to a string with a value of 'NO_VALUE_type' where type is determined by the value of ombaq_type and is one of 'BOOLEAN', 'BYTE', 'SHORT', 'INT', 'LONG', 'FLOAT', 'CHAR'. The value of the property or map element name is not changed.

str_value null when it must be non-null

This occurs when ombaq_type indicates that str_value will be used to store the value of the property, map element or stream element and num_value is null. When this occurs the property, map element or stream element is coerced to a string with a value of 'NO_VALUE_type' where type is determined by the value of ombaq_type and is one of 'BYTE_ARRAY', 'DOUBLE', 'STRING'. The value of the property or map element name is not changed.

num_value exceeds range implied by ombaq_type

This occurs when ombaq_type indicates that num_value will be used to store the value of the property, map element or stream element and the value of num_value exceeds the range supported by the Java primitive type. This can occur when ombaq_type is one of 'OMBAQ_BOOLEAN', 'OMBAQ_BYTE', 'OMBAQ_SHORT',and 'OMBAQ_CHAR'. When this occurs, the property, map element or stream element is coerced to a string with a value of 'INVALID_VALUE_type_value'. type is replaced with one of 'BOOLEAN', 'BYTE', 'SHORT' or 'CHAR'. value is replaced with the original value that exceeded the range.

invalid value for ombaq_type

This occurs when ombaq_type is null or has a value other than the valid subset from the set {'OMBAQ_BOOLEAN', 'OMBAQ_BYTE', 'OMBAQ_SHORT', 'OMBAQ_INT', 'OMBAQ_LONG', 'OMBAQ_FLOAT', 'OMBAQ_DOUBLE', 'OMBAQ_STRING', 'OMBAQ_BYTE_ARRAY', 'OMBAQ_CHAR'}. When this occurs the property, map element or stream element is coerced to a string with the value 'INVALID_TYPE'.

invalid byte array value in str_value

This occurs when ombaq_type is 'OMBAQ_BYTE_ARRAY' and str_value does not contain a byte array encoded as a string. The byte array encoded as a string must be a size that is a multiple of 2 and every character in the string must be one of '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', or 'f'. When this occurs, the property, map element or stream element is coerced to a string with a value of 'INVALID_VALUE_BYTE_ARRAY_value'. The value is replaced with the value of str_value.

duplicate values for name in ombaq_property, name in ombaq_map_element

This occurs when the ombaq_properties varray contains ombaq_property instances that use the same value for the name field. This also occurs when the ombaq_map_elements varray contains ombaq_map_element instances that use the same value for the name field. When this occurs the duplicate names are made unique by replacing the duplicate names with 'DUPLICATE_NAME_integer_original_name'. integer is replaced with a small integer. The original_name is replaced with the value of name.

invalid value for name

This occurs when the name field in ombaq_property is invalid per the JMS specification. When this occurs the value of the name field is replaced with 'INVALID_NAME_integer'. integer is replaced with a small integer.

null value for name

This occurs when the name field in ombaq_property or ombaq_map_element is null. When this occurs the value of the name field is replaced with 'NULL_NAME_integer'. integer is replaced with a small integer.

Sample Usage from PL/SQL

Assuming a queue table had been created with the type ombaq_text_msg, a PL/SQL client can enqueue a message to this queue that uses this queue table as:

DECLARE
    enq_opt        dbms_aq.enqueue_options_t;
    props        dbms_aq.message_properties_t;
    msg         aq.ombaq_text_msg;
    header             aq.ombaq_header;
    msgid        raw(16);

BEGIN
    header := aq.ombaq_header(NULL, NULL, 'example', NULL);
    msg := aq.ombaq_text_msg(header, 0, 'example text body', NULL);
    dbms_aq.enqueue(    queue_name    => 'TextQueue',
            enqueue_options    => enq_opt,
            message_properties => props,
            payload         => msg,
            msgid        => msgid);
               COMMIT;
END;