This chapter describes the Oracle Java Messaging Service (OJMS) interfaces and classes that are contained in package oracle.jms. The Oracle JMS interfaces extend the standard JMS interfaces to support the Oracle9i Advanced Queing (AQ) administrative operations and other AQ features that are not included in the public standard contained in the javax.jms package.

Package oracle.jms Description

The Oracle package oracle.jms provides a set of interfaces and associated semantics based on the Java Messaging Service (JMS) standard. These interfaces define how a JMS client accesses the facilities of an enterprise messaging product like Oracle9i Advanced Queuing. Advanced Queuing (AQ) is the unique database-integrated message queuing feature of the Oracle9i database. Oracle supports the standard JMS interfaces and has extensions to support the AQ administrative operations and other AQ features that are not included in the public standard.

Accessing Standard JMS and Oracle JMS Packages

Oracle JMS uses JDBC to connect to the database. Therefore, its applications can run as follows:

Outside the database using the "OCI9" or "thin" JDBC driver.

Inside Oracle8i or Oracle 9i JServer using the Oracle Server driver.

The standard JMS interfaces are contained in the javax.jms package (refer to Sun J2EE documentation for details). The Oracle JMS interfaces extend javax.jms and are contained in the oracle.jms package.

Using the OCI9 or Thin JDBC Driver

To use JMS interfaces with clients running outside the database, you must include the appropriate JDBC driver, JNDI jar files, and the following AQ jar files in your CLASSPATH. (The CLASSPATH is the operating system environmental variable that the JVM uses to find the classes it needs to run applications.)

Using Oracle Server Driver in JServer

If your application is running inside the JServer, you should be able to access the Oracle JMS classes that have been automatically loaded when the JServer was installed. If these classes are not available, you may have to load jmscommon.jar followed by aqapi.jar using the loadjava utility.

Privileges Required

Users must have EXECUTE privilege on DBMS_AQIN and DBMS_AQJMS packages in order to use the Oracle JMS interfaces. Users can also acquire these rights through the AQ_USER_ROLE or the AQ_ADMINSTRATOR_ROLE.

Users will also need the appropriate system and Queue or Topic privileges to send or receive messages.

This interface extends the TopicReceiver interface that defines AQ extensions for remote subscribers and explicitly specified recipients (in point-to-mulitpoint communication). A TopicReceiver is used to receive messages from a Topic.

Table 4-3 Exceptions for oracle.jms

This exception extends IllegalStateException. It is thrown when when an OJMS method is invoked at an illegal or inappropriate time, or when OJMS is not in an appropriate state for the requested operation.

Overrides

Parameters

Returns

Throws

JMSException - if JMS fails to get Property due to some internal JMS error.

MessageFormatException - if this type conversion is invalid.

getObjectProperty(String)

public java.lang.Object getObjectProperty(java.lang.String name)

Return the Java object property value with the given name.

Note that this method can be used to return in objectified format, an object that had been stored as a property in the Message with the equivalent setObject method call, or it's equivalent primitive set method.

Returns

Throws

JMSException - if JMS fails to read message due to some internal JMS error.

readInt()

public int readInt()

Read a signed 32-bit integer from the stream message.

Specified By

javax.jms.BytesMessage.readInt() in interface javax.jms.BytesMessage

Returns

the next four bytes from the stream message, interpreted as an int.

Throws

MessageNotReadableException - if message in write-only mode.

MessageEOFException - if end of message stream

JMSException - if JMS fails to read message due to some internal JMS error.

readLong()

public long readLong()

Read a signed 64-bit integer from the stream message.

Specified By

javax.jms.BytesMessage.readLong() in interface javax.jms.BytesMessage

Returns

the next eight bytes from the stream message, interpreted as a long.

Throws

MessageNotReadableException - if message in write-only mode.

MessageEOFException - if end of message stream

JMSException - if JMS fails to read message due to some internal JMS error.

readShort()

public short readShort()

Put the message in read-only mode, and reposition the stream of bytes to the beginning. ThrowsMessageNotWriteableException - if message in write-only mode. JMSException - if JMS fails to read message due to some internal JMS error.

Methods

close()

public void close()

Since a provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Specified By

javax.jms.Connection.close() in interface javax.jms.Connection

Specified By

javax.jms.Connection.close() in interface javax.jms.Connection

Throws

JMSException - if JMS implementation fails to close the connection due to internal error. For example, a failure to release resources or to close socket connection can lead to throwing of this exception.

Specified By

Parameters

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives. This parameter will be ignored if the session is transacted.

Returns

a newly created topic session.

Throws

JMSException - if JMS Connection fails to create a session due to some internal error or lack of support for specific transaction and acknowledgement mode.

getClientID()

public java.lang.String getClientID()

Get the client identifier for this connection.

Specified By

javax.jms.Connection.getClientID() in interface javax.jms.Connection

Returns

the unique client identifier.

Throws

JMSException - if JMS implementation fails to return the client ID for this Connection due to some internal error.

getCurrentJmsSession()

public javax.jms.Session getCurrentJmsSession()

gets the current session

Returns

Session The current JMS session

getMetaData()

public javax.jms.ConnectionMetaData getMetaData()

Get the meta data for this connection.

Specified By

javax.jms.Connection.getMetaData() in interface javax.jms.Connection

Returns

the connection meta data.

Throws

JMSException - general exception if JMS implementation fails to get the Connection meta-data for this Connection.

See Also

javax.jms.ConnectionMetaData

setClientID(String)

public void setClientID(java.lang.String clientID)

Set the client identifier for this connection.

The preferred way to assign a Client's client identifier is for it to be configured in a client-specific ConnectionFactory and transparently assigned to the Connection it creates. Alternatively, a client can set a Connections's client identifier using a provider-specific value.

The purpose of client identifier is to associate a session and its objects with a state maintained on behalf of the client by a provider. The only such state identified by JMS is that required to support durable subscriptions

start()

Start (or restart) a Connection's delivery of incoming messages. Restart begins with the oldest unacknowledged message. Starting a started session is ignored.

Specified By

javax.jms.Connection.start() in interface javax.jms.Connection

Throws

JMSException - if JMS implementation fails to start the message delivery due to some internal error.

See Also

javax.jms.Connection.stop()

stop()

public void stop()

Used to temporarily stop a Connection's delivery of incoming messages. It can be restarted using its start method. When stopped, delivery to all the Connection's message consumers is inhibited: synchronous receive's block and messages are not delivered to message listeners.

After stop is called there may still be some messages delivered.

Stopping a Session has no affect on its ability to send messages. Stopping a stopped session is ignored.

Specified By

javax.jms.Connection.stop() in interface javax.jms.Connection

Throws

JMSException - if JMS implementation fails to stop the message delivery due to some internal error.

See Also

javax.jms.Connection.start()

setExceptionListener(ExceptionListener)

If a JMS provider detects a serious problem with a connection it will inform the connection's ExceptionListener if one has been registered. It does this by calling the listener's onException() method passing it a JMSException describing the problem.

This allows a client to be asynchronously notified of a problem. Some connections only consume messages so they would have no other way to learn their connection has failed.

Specified By

Returns

Throws

JMSException - general exception if JMS implementation fails to get the Exception listener for this Connection.

setPingPeriod(long)

public void setPingPeriod(long period)

Set the sleep period (in milliseconds) between each 'ping' of the exception listener for this connection.

If a exception listener is registered, the connection 'pings' the server periodically to ensure that the server is alive. These 'pings' can result in performance degradation. A trade-off has to be made in selecting a good 'ping' period value. The greater the value the larger the time period an asynchronous client may have to wait before it is aware of a fatal exception. The smaller the value, more the overhead of the 'pings'. If an exception listener is not registered for this connection, then 'ping' period is of no relevance. The default value of the ping period is 2 minutes.

Parameters

period - the sleep period between each 'ping' in milliseconds.

getPingPeriod()

public long getPingPeriod()

Get the sleep period (in milliseconds) between each 'ping' of the exception listener for this connection.

This method Returnsthe value set by a previous call to setPingPeriod() or the default value (2 minutes) if setPingPeriod is not calle.

STATE_WAITING

TRANSACTIONAL

WAIT_FOREVER

WAIT_NONE

Constructors

AQjmsConstants()

public AQjmsConstants()

Methods

isJ2eeCompliant()

Returnstrue if the JMS client is run in the J2EE/JMS 1.3 compliance mode and false otherwise.

The client can define the j2EE compliance mode used by OJMS by setting the java property "oracle.jms.j2eeCompliant" to either true or false at run time. When running with the j2eeCompliant flag set to false, OJMS clients will support older (non j2ee compliant) OJMS behavior for priority, expiration and non durable subscriber semantics. This allows older clients to run without code modifications.

Methods

close()

public void close()

Since a provider may allocate some resources on behalf of a MessageConsumer outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Specified By

Parameters

Returns

the next message produced for this message consumer, or null if one is not available.

Throws

JMSException - if JMS fails to receive the next message due to some error.

receiveNoData()

public synchronized void receiveNoData()

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database. It can be used as an optimization by jms clients who have already read the message, for example using a queue browser.

Specified By

receiveNoData() in interface AQjmsQueueReceiver

Throws

JMSException - if the message could not be received due to an error

receiveNoData(long)

public synchronized void receiveNoData(long timeout)

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database. It can be used as an optimization by jms clients who have already read the message, for example using a queue browser. This call will block until a message arrives or the timeout expires

maximum retries for dequeue with REMOVE mode; specifying NULL will use the default. The default applies to single consumer queues and 8.1. compatible multiconsumer queues. Max_retries is not supported for 8.0 compatible multiconsumer queues.

Register a Queue or Topic Connection Factory in the LDAP server associated with the Oracle database. The user can log on to the Oracle9i database first and then have the database update the LDAP entry. The user that logs on to the database must have the AQ_ADMINISTRATOR_ROLE to perform this operation.

Parameters

connection - a valid database connection

conn_name - the name of the Connection Factory to be registered

hostname - host name of the machine which hosts the database that the connection factory represents

oracle_sid - the oracle SID of the database that the connection factory represents

portno - the port number of the database

driver - the type of jdbc driver ("thin" or "oci8") to be used to connect to the database (JMS provider)

Register a Queue or Topic Connection Factory in the LDAP server associated with the Oracle database. The user can log on to the Oracle9i database first and then have the database update the LDAP entry. The user that logs on to the database must have the AQ_ADMINISTRATOR_ROLE to perform this operation.

Parameters

connection - a valid database connection

conn_name - the name of the Connection Factory to be registered

jdbc_url - the JDBC URL to connect to the database that this factory represents

getJMSDeliveryMode()

Specified By

Returns

The delivery mode of this message, which is either DeliverMode.PERSISTENT or DeliveryMode.NON_PERSISTENT.

Throws

JMSException - if JMS fails to get JMS DeliveryMode due to some internal JMS error.

getJMSDestination()

public javax.jms.Destination getJMSDestination()

Get the destination for this message. The destination field contains the destination to which the message is being sent. When a message is sent this value is ignored. After completion of the send method it holds the destination specified by the send. When a message is received, its destination value must be equivalent to the value assigned when it was sent.

Specified By

javax.jms.Message.getJMSDestination() in interface javax.jms.Message

Returns

the destination of this message.

Throws

JMSException - if JMS fails to get JMS Destination due to some internal JMS error.

getJMSExpiration()

public long getJMSExpiration()

Get the message's expiration value. When a message is sent, expiration is left unassigned. After completion of the send method, it holds the expiration time of the message. This is the sum of the time-to-live value specified by the client and the GMT at the time of the send. If the time-to-live is specified as zero, expiration is set to zero which indicates the message does not expire. When a message's expiration time is reached, the message is moved to the exception queue corresponding to the destination queue/topic

Specified By

javax.jms.Message.getJMSExpiration() in interface javax.jms.Message

Returns

the time the message expires. It is the sum of the time-to-live value specified by the client, and the GMT at the time of the send.

Throws

JMSException - if JMS fails to get JMS message expiration due to some internal JMS error.

See Also

javax.jms.Message#setJMSExpiration()

getJMSMessageID()

public java.lang.String getJMSMessageID()

Get the message ID. The messageID header field contains a value that uniquely identifies each message sent by a provider. When the send method Returnsit contains a provider-assigned value. All JMSMessageID string values start with the prefix `ID:'

Specified By

javax.jms.Message.getJMSMessageID() in interface javax.jms.Message

Returns

the message ID as a string (prefixed with 'ID:')

Throws

JMSException - if JMS fails to get the message Id due to internal JMS error.

getJMSMessageIDAsBytes()

public byte[] getJMSMessageIDAsBytes()

Get the message ID.

Returns

the message ID as a byte array

Throws

JMSException - if JMS fails to get the message Id due to internal JMS error.

getJMSPriority()

public int getJMSPriority()

Get the message priority. JMS defines a ten level priority value with 0 as the lowest priority and 9 as the highest.

Specified By

javax.jms.Message.getJMSPriority() in interface javax.jms.Message

Returns

the default message priority

getJMSRedelivered()

public boolean getJMSRedelivered()

Get an indication of whether this message is being redelivered.

If a client receives a message with the redelivered indicator set, it is likely, but not guaranteed, that this message was delivered to the client earlier but the client did not commit the transaction

Specified By

javax.jms.Message.getJMSRedelivered() in interface javax.jms.Message

Returns

set to true if this message is being redelivered.

Throws

JMSException - if JMS fails to get JMS Redelivered flag due to some internal JMS error.

getJMSReplyTo()

public javax.jms.Destination getJMSReplyTo()

Get the replyTo field for this message

Specified By

javax.jms.Message.getJMSReplyTo() in interface javax.jms.Message

Returns

replyTo destination (the format is a AQjmsAgent)

getJMSTimestamp()

public long getJMSTimestamp()

Get the message timestamp. The JMSTimestamp header field contains the time a message was handed off to a provider to be sent. When a message is sent, JMSTimestamp is ignored. When the send is complete - this method will contain the time the message was enqueued.

Specified By

javax.jms.Message.getJMSTimestamp() in interface javax.jms.Message

Throws

JMSException - if JMS fails to get the Timestamp

getJMSType()

public java.lang.String getJMSType()

Get the message type.

Specified By

javax.jms.Message.getJMSType() in interface javax.jms.Message

Returns

the message type

Throws

JMSException - if JMS fails to get JMS message type due to some internal JMS error.

Specified By

Parameters

Returns

Throws

JMSException - if JMS fails to get Property

MessageFormatException - if this type conversion is invalid.

getObjectProperty(String)

public java.lang.Object getObjectProperty(java.lang.String name)

Return the Java object property value with the given name. Note that this method can be used to return in objectified format, an object that had been stored as a property in the Message with the equivalent setObject method call, or it's equivalent primitive set method.

Methods

close()

public void close()

Since a provider may allocate some resources on behalf of a MessageProducer outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Specified By

Parameters

Throws

JMSException - if JMS fails to set delivery mode due to some internal error.

setDisableMessageID(boolean)

public synchronized void setDisableMessageID(boolean value)

Set whether message IDs are disabled.

Since message ID's take some effort to create and increase a message's size, some JMS providers may be able to optimize message overhead if they are given a hint that message ID is not used by an application. JMS message Producers provide a hint to disable message ID. When a client sets a Producer to disable message ID they are saying that they do not depend on the value of message ID for the messages it produces. These messages must either have message ID set to null or, if the hint is ignored, messageID must be set to its normal unique value.

Methods

close()

public void close()

Since a provider may allocate some resources on behalf of a QueueBrowser outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Specified By

javax.jms.QueueBrowser.close() in interface javax.jms.QueueBrowser

getEnumeration()

public java.util.Enumeration getEnumeration()

Get an enumeration for browsing the current queue messages in the order they would be received.

createQueueConnection(Connection)

create a Queue Connection using the already open JDBC connection. This creation does NOT result in creation of another connection to the database. Instead JMS binds to the given connection to the database and provides an interface to the Queuing mechanism defined by JMS.

Parameters

jdbc_connection - a valid open connection to the database.

Returns

a Queue Connection

Throws

JMSException - if JMS fails to get a queue connection due to some JMS error

Returns

Throws

getTransformation()

Returns

the transformation

Throws

JMSException - if there was an error in getting the transformation

receiveNoData()

public void receiveNoData()

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser.

Throws

JMSException - if the message could not be received due to an error

receiveNoData(long)

public void receiveNoData(long timeout)

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser. This call will block until a message arrives or the timeout expires

Parameters

timeout - the timeout value in milliseconds

Throws

JMSException - if the message could not be received due to an error

setNavigationMode(int)

public void setNavigationMode(int mode)

set the navigation mode used for receiving messages

Parameters

mode - the new value of the navigation mode

Throws

JMSException - if there was an error in getting the navigation mode

setTransformation(String)

public void setTransformation(String transformation)

Set transformation for this receiver. This transformation will be applied before the message is returned to the user.

Parameters

transformation - transformation to be applied before returning the message

Throws

JMSException - if there was an error in setting the transformation

AQjmsQueueSender

Syntax

public interface AQjmsQueueSender extends javax.jms.QueueSender

All Superinterfaces

javax.jms.MessageProducer, javax.jms.QueueSender

All Known Implementing Classes

AQjmsProducer

Description

This interface extends QueueSender and defines AQ extensions to JMS. A client uses a QueueSender to send messages to a Queue

Get a handle to an existing queue-table If owner of queue-table is not the same as the user which opened the connection, the caller must have AQ enqueue/dequeue privileges on queues/topics in the queue table.

Methods

close()

public void close()

Close a JMS session Since a provider may allocate some resources on behalf of a Session outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough. This call may take a couple of minutes if there are receivers blocked on a receive call with infinite timeout

Specified By

javax.jms.Session.close() in interface javax.jms.Session

Specified By

javax.jms.Session.close() in interface javax.jms.Session

Throws

JMSException - if JMS implementation fails to close a Session due to some internal error.

commit()

public synchronized void commit()

Commit all messages done in this transaction and releases any locks currently held.

Specified By

javax.jms.Session.commit() in interface javax.jms.Session

Throws

JMSException - if JMS implementation fails to commit the transaction due to some internal error. The linked SQL exception has more info about the error

createAdtMessage()

public synchronized AdtMessage createAdtMessage()

Create an AdtMessage. An AdtMessage is used to send a message that containing an Java object that maps to a Oracle SQL ADT. This object must support the OracleCustomDatum interface.

Throws

createBrowser(Queue)

Create a QueueBrowser to peek at the messages on the specified queue. This method can be used to create browsers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

createBrowser(Queue, CustomDatumFactory)

Create a QueueBrowser to peek at the messages on the specified queue containing ADT messages. This method is used to create receivers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

queue - the queue to access

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

Throws

JMSException - if a session fails to create a browser due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

createBrowser(Queue, String)

Create a QueueBrowser to peek at the messages on the specified queue. This method can be used to create browsers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

createBrowser(Queue, String, boolean)

Create a QueueBrowser to peek at the messages on the specified queue. This method can be used to create browsers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

Parameters

queue - the queue to access

messageSelector - only messages with properties matching the message selector expression are delivered

The selector can be any expression that has a combination of one or more of the following:

JMSMessageID = 'ID:23452345' to retrieve messages that have a specified message ID

JMS Message header fields or properties:

JMSPriority < 3 AND JMSCorrelationID = 'Fiction'

User defined message properties:

color IN ('RED', BLUE', 'GREEN') AND price < 30000

All message IDs must be prefixed with "ID:"

locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)

Throws

JMSException - if a session fails to create a browser due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

InvalidSelectorException - if the message selector is invalid.

createBrowser(Queue, String, CustomDatumFactory)

Create a QueueBrowser to peek at the messages on the specified queue containing ADT messages. This method is used to create browsers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

queue - the queue to access

messageSelector - only messages with properties matching the message selector expression are delivered. For queues containing AdtMessages the selector for QueueBrowser can be a SQL expression on the message payload contents or messageID or priority or correlationID.

Selector on message id - to retrieve messages that have a specific messageID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'

Selector on priority or correlation is specified as follows

priority < 3 AND corrid = 'Fiction'

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

Throws

JMSException - if a session fails to create a browser due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

createBrowser(Queue, String, CustomDatumFactory, boolean)

Create a QueueBrowser to peek at the messages on the specified queue containing ADT messages. This method is used to create browsers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

queue - the queue to access

messageSelector - only messages with properties matching the message selector expression are delivered. For queues containing AdtMessages the selector for QueueBrowser can be a SQL expression on the message payload contents or messageID or priority or correlationID.

Selector on message id - to retrieve messages that have a specific messageID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'

Selector on priority or correlation is specified as follows

priority < 3 AND corrid = 'Fiction'

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)

Throws

JMSException - if a session fails to create a browser due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

createBytesMessage()

public synchronized javax.jms.BytesMessage createBytesMessage()

Create a BytesMessage. A BytesMessage is used to send a message containing a stream of uninterpreted bytes.

Specified By

javax.jms.Session.createBytesMessage() in interface javax.jms.Session

Throws

JMSException - if some error occurs during message creation

createDurableSubscriber(Topic, String)

Create a durable Subscriber to the specified topic. This method can be used to create subscribers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

createDurableSubscriber(Topic, String, CustomDatumFactory)

Create a durable Subscriber to the specified topic. This method is used to create browsers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads) A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

Parameters

topic - the topic to subscribe to

name - the name used to identify this subscription.

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

Throws

JMSException - if a session fails to create a subscriber due to some JMS error.

InvalidDestinationException - if invalid Topic specified.

createDurableSubscriber(Topic, String, String, boolean)

Create a durable Subscriber to the specified topic. This method can be used to create subscribers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

-- identifier [NOT] LIKE pattern-value [ESCAPE escape-character] pattern-value is a string literal where % refers to any sequence of characters and and _ refers to any single character. The optional escape-character is used to escape the special meaning of the '-' and '%' in pattern-value

-- identifier IS [NOT] NULL

noLocal - - must be set to false. nolocal=true not supported.

Throws

JMSException - if a session fails to create a subscriber due to some JMS error.

createDurableSubscriber(Topic, String, String, boolean, String)

Create a durable Subscriber to the specified topic and specify a transformation for the subscriber

This method can be used to create subscribers for topics that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

-- identifier [NOT] LIKE pattern-value [ESCAPE escape-character] pattern-value is a string literal where % refers to any sequence of characters and and _ refers to any single character. The optional escape-character is used to escape the special meaning of the '-' and '%' in pattern-value

-- identifier IS [NOT] NULL

noLocal - - must be set to false. nolocal=true not supported.

transformation - - transformation associated with this subscriber. This transformation is applied before messages are delivered to this subscriber

Throws

JMSException - if a session fails to create a subscriber due to some JMS error.

Create a durable Subscriber to the specified topic and specify a transformation for the subscriber.

This method is used to create subsccribers for topics that contain Oracle ADT payloads (instead of the standard JMS defined payloads) A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

Parameters

topic - the topic to subscribe to

name - the name used to identify this subscription.

messageSelector - only messages with attributes matching the message selector expression are delivered. This value may be null.

The syntax for the selector for queues containing ADT messages is different from the syntax for selectors on queues containing standard JMS payloads (text, stream, object, bytes, map) The selector is similar to the AQ rules syntax

Specified By

Parameters

topic - the topic to publish to, or null if this is an unidentified producer.

Throws

JMSException - if a session fails to create a publisher due to some JMS error.

InvalidDestinationException - if invalid Topic specified.

createQueue()

public synchronized javax.jms.Queue createQueue(String)

Create a queue given a Queue name. This facility is provided for the rare cases where clients need to dynamically manipulate queue identity. It allows the creation of a queue identity with a provider-specific name. Clients that depend on this ability are not portable. Note that this method is not for creating the physical

queue. The physical creation of queues is an administrative task.

The Queue name is of the form "[schema].name". If "schema" is not specified, current session "user", is utilised.

Parameters

owner - the queue table owner (schema)

name - queue table name

property - queue table properties. If the queuetable will be used to hold queues, then the queuetable must not be multiconsumer enabled (default). If the queue table will be used to hold topics the queuetable must be multiconsumer enabled

Throws

JMSException - if the QueueTable cannot be created

See Also

oracle.AQ.AQQueueTableProperty

createReceiver(Queue)

Create a QueueReceiver to receive messages from the specified queue. This method can be used to create receivers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

createReceiver(Queue, CustomDatumFactory)

Create a QueueReceiver to receive messages from the specified queue containing ADT messages. This method is used to create receivers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

queue - the queue to access

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

Throws

JMSException - if a session fails to create a receiver due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

createReceiver(Queue, String)

Create a QueueReceiver to receive messages from the specified queue. This method can be used to create receivers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

createReceiver(Queue, String, CustomDatumFactory)

Create a QueueReceiver to receive messages from the specified queue containing ADT messages. This method is used to create receivers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

queue - the queue to access

messageSelector - only messages with properties matching the message selector expression are delivered. For queues containing AdtMessages the selector for QueueReceiver can be a SQL expression on the message payload contents or messageID or priority or correlationID.

Selector on message id - to retrieve messages that have a specific messageID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'

Selector on priority or correlation is specified as follows

priority < 3 AND corrid = 'Fiction'

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

Throws

JMSException - if a session fails to create a receiver due to some JMS error.

InvalidDestinationException - if invalid Queue specified.

InvalidSelectorException - if the message selector is invalid.

createRemoteSubscriber(Topic, AQjmsAgent, String)

Create a remote subscriber for a topic. This method can be used to remote subscribers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE.

AQ allows topics to have remote subscribers, ie subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the two local and remote topic.

Parameters

topic - the topic to subscribe to

remote_subscriber - AQjmsAgent that refers to the remote subscriber

messageSelector - only messages with properties matching the message selector expression are delivered. This value may be null.

The selector syntax is the same as that for createDurableSubscriber Remote subscribers may be a specific consumer at the remote topic or all subscribers at the remote topic.

A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic - the syntax is (schema).(topic_name)[@dblink].

1. To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent. The remote topic must be specified in the address field of AQjmsAgent.

2. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null. The remote topic must be specified in the address field of AQjmsAgent.

createRemoteSubscriber(Topic, AQjmsAgent, String, String)

Create a remote subscriber for a topic and specify a transformation for the subscriber. This method can be used to remote subscribers for queues that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE.

AQ allows topics to have remote subscribers, ie subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the two local and remote topic.

Parameters

topic - the topic to subscribe to

remote_subscriber - AQjmsAgent that refers to the remote subscriber

messageSelector - only messages with properties matching the message selector expression are delivered. This value may be null.

The selector syntax is the same as that for createDurableSubscriber Remote subscribers may be a specific consumer at the remote topic or all subscribers at the remote topic.

tranformation - the transformation for this subscriber. This transformation will be applied before the message is delivered to this subscriber.

A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic - the syntax is (schema).(topic_name)[@dblink].

1. To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent. The remote topic must be specified in the address field of AQjmsAgent.

2. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null. The remote topic must be specified in the address field of AQjmsAgent.

createRemoteSubscriber(Topic, AQjmsAgent, String, CustomDatumFactory)

Create a remote subscriber for a topic. This method is used to create browsers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads).

AQ allows topics to have remote subscribers, ie subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the two local and remote topic.

Parameters

topic - the topic to subscribe to

remote_subscriber - AQjmsAgent that refers to the remote subscriber

messageSelector - only messages with properties matching the message selector expression are delivered. This value may be null. The selector syntax is the same as that for createDurableSubscriber for topics with ADT messages

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT.

Remote subscribers may be a specific consumer at the remote topic or all subscribers at the remote topic A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic - the syntax is (schema).(topic_name)[@dblink].

1. To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent. The remote topic must be specified in the address field of AQjmsAgent.

2. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null. The remote topic must be specified in the address field of AQjmsAgent

Create a remote subscriber for a topic and specify a transformation for this subscriber. This method is used to create browsers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads).

AQ allows topics to have remote subscribers, ie subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the two local and remote topic.

Parameters

topic - the topic to subscribe to

remote_subscriber - AQjmsAgent that refers to the remote subscriber

messageSelector - only messages with properties matching the message selector expression are delivered. This value may be null. The selector syntax is the same as that for createDurableSubscriber for topics with ADT messages

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT.

tranformation - the transformation for this subscriber. This transformation will be applied before the message is delivered to this subscriber.

Remote subscribers may be a specific consumer at the remote topic or all subscribers at the remote topic A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic - the syntax is (schema).(topic_name)[@dblink].

1. To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent. The remote topic must be specified in the address field of AQjmsAgent.

2. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null. The remote topic must be specified in the address field of AQjmsAgent

Specified By

Parameters

stringBuffer - the string buffer used to initialize this message.

Throws

JMSException - if some error occurs during message creation

createTopic()

public synchronized javax.jms.Topic createTopic(String)

Create a Topic given a Topic name. This facility is provided for the rare cases where clients need to dynamically manipulate topic identity. It allows the creation of a topic identity with a provider-specific name. Clients that depend on this ability are not portable. Note that this method is not for creating the physical topic. The physical creation of topic is an administrative task.

The Topic name is of the form "[schema].name." If "schema" is not specified, current session "user," is utilized.

createTopicReceiver(Topic, String, String)

Create a TopicReceiver to receive messages from the specified topic. AQ allows messages to be sent to all subscribers of a topic or to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, it will receive only those messages that are explicitly This method must be used order to create a TopicReceiver object for consumers that are not durable subscribers of the topic

This method can be used to create TopicReceivers for topics that contain payloads of type AQ$_JMS_TEXT_MESSAGE, AQ$_JMS_STREAM_MESSAGE, AQ$_JMS_BYTES_MESSAGE, AQ$_JMS_MAP_MESSAGE or AQ$_JMS_OBJECT_MESSAGE

Parameters

topic - the topic to access

receiver_name - the name of the recipient (or subscriber)

messageSelector - only messages with properties matching the message selector expression are delivered. The selector can be any expression that has a combination of one or more of the following:

JMSMessageID = 'ID:23452345' to retrieve messages that have a specified message ID

JMS Message header fields or properties:

JMSPriority < 3 AND JMSCorrelationID = 'Fiction'

User defined message properties:

color IN ('RED', BLUE', 'GREEN') AND price < 30000

All message IDs must be prefixed with "ID:"

Throws

JMSException - if a session fails to create a receiver due to some JMS error.

InvalidDestinationException - if invalid Topic specified.

InvalidSelectorException - if the message selector is invalid.

createTopicReceiver(Topic, String, String, CustomDatumFactory)

Create a TopicReceiver to receive messages from the specified topic containing ADT messages. AQ allows messages to be sent to all subscribers of a topic or to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, it will receive only those messages that are explicitly This method must be used order to create a TopicReceiver object for consumers that are not durable subscribers of the topic

This method is used to create TopicReceivers for topics that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

Parameters

topic - the topic to access

receiver_name - the name of the recipient (or subscriber)

messageSelector - only messages with properties matching the message selector expression are delivered. For queues containing AdtMessages the selector can be a SQL expression on the message payload contents or messageID or priority or correlationID.

Selector on message id - to retrieve messages that have a specific messageID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'

Selector on priority or correlation is specified as follows

priority < 3 AND corrid = 'Fiction'

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

payload_factory - CustomDatumFactory for the java class that maps to the Oracle ADT

getDBConnection()

public synchronized java.sql.Connection getDBConnection()

getJmsConnection()

public AQjmsConnection getJmsConnection()

getMessageListener()

public synchronized javax.jms.MessageListener getMessageListener()

Return the session's distinguished message listener.

Specified By

javax.jms.Session.getMessageListener() in interface javax.jms.Session

Returns

the message listener associated with this session.

Throws

JMSException - if JMS fails to get the message listener due to an internal error in JMS Provider.

Throws

getQueueTable(String, String)

Get a handle to an existing queue-table If owner of queue-table is not the same as the user which opened the connection, the caller must have AQ enqueue/dequeue privileges on queues/topics in the queue table. Otherwise the queue-table will not be returned

Parameters

owner - the owner (schema) of the queue-table

name - queue-table name

Throws

JMSException - if the queue table does not exist or if the user does not have privileges on any queue/topic in the queue-table

Methods

close()

public void close()

Close the topic browser. Since OJMS allocates resources on behalf of a TopicBrowser outside the JVM, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough

All errors during the operations will be silently ignored.

getTopic()

public Topic getTopic()

Get the topic associated with this topic browser

Returns

the topic associated with this topic browser

Throws

JMSException-if JMS fails to get the topic associated with this Browser due to some JMS error.

getEnumeration()

public Enumeration getEnumeration()

Get an enumeration for browsing the current topic messages in the order they would be received. If getEnumeration() is called twice on the same TopicBrowser, the same enumeration object is returned. Hence the nextElement() call on one enumeration object would modify the state second enumeration object too

Returns

an enumeration for browsing the messages

getMessageSelector()

public String getMessageSelector()

Get this topic browser's message selector expression.

Returns

this topic browser's message selector

Throws

JMSException-if JMS fails to get message selector due to some JMS error.

nextElement()

public Object nextElement()

Returnsthe next element of this enumeration. Attempt to use cached messages (if one is available from a previous call to hasMoreElements(). If the browser's selector used message ID, only one message can ever be returned during the browse

Returns

the next element of this enumerationn

Throws

NoSuchElementException-if no more elements exist

hasMoreElements()

public boolean hasMoreElements()

Check if this enumeration contains more elements.

Returns

true if more elements exist in the enumeration false otherwise.

purgeSeen()

public void purgeSeen()

Purge messages seen so far during browse. A message is considered seen if it was returned to the client via a call to nextElement() during the browse. Thus, it is possible for a client to create a topic browser, call purge immediately, and not change the state of the topic (since no messages were seen as specified by this method).

Purging a topic also does not affect the state of messages yet to be seen by the client during a browse.

Purging is supported only on topic browsers that were created in the LOCKED mode. Attempting to purge topics that were not created in the LOCKED mode will result in an exception.

The purge operation will take effect only if the session for this topic browser is commited. If the session is rolled back, the purge operation will be undone and the messages will become visible again.

The purge will be finalized only when the session for the topic browse is committed.

Throws

JMSException - if a JMS error occurred during the purge operation.

setTransformation(String transformation)

public void setTransformation(String transformation)

Set transformation for the browser. This transformation will becapplied before the message is returned to the user.

All Implemented Interfaces

java.io.Serializable

Description

This exception extends IlegalStateException. It is thrown when a method is invoked at an illegal or inappropriate time or if OJMS is not in an appropriate state for the requested operation. For example, this exception must be thrown if Session.commit is called on a non-transacted session.

createTopicConnection(Connection)

create a TopicConnection using the already open JDBC connection. This creation does NOT result in creation of another connection to the database. Instead JMS binds to the given connection to the database and provides an interface to the Pub/Sub mechanism defined by JMS.

Parameters

jdbc_connection - a valid open connection to the database.

Returns

a TopicConnection

Throws

JMSException - if JMS fails to get a topic connection due to some JMS error

publish(Topic, Message, AQjmsAgent[], int, int, long)

Publish a Message to a topic by specifying a list of recipients, delivery mode, priority and time to live

Parameters

topic - The topic to which to publish the message. This overrides the default topic of the Message Producer

message - The message to be published

recipient_list - The list of recipients to which the message is published. The recipients are of type AQjmsAgent.

deliveryMode - The delivery mode - persistent or non_persistent

priority - The priority of the message

timeToLive - the message time to live in milliseconds; zero is unlimited

Throws

JMSException - if JMS fails to publish the message due to some internal error.

setTransformation(String)

public void setTransformation(String transformation)

Set transformation for this sender. This transformation will be applied before the message is published to the topic

Parameters

transformation - transformation to be applied before publishing the message

Throws

JMSException - if there was an error in setting the transformation

AQjmsTopicReceiver

Syntax

public interface AQjmsTopicReceiver extends TopicReceiver

All Superinterfaces

javax.jms.MessageConsumer, TopicReceiver

All Known Implementing Classes

AQjmsConsumer

Description

This interface extends the TopicReceiver interface that defines AQ extensions for remote subscribers and explicitly specified recipients (in point-to-mulitpoint communication). A TopicReceiver is used to receive messages from a Topic.

Returns

Throws

getTransformation()

Returns

the transformation

Throws

JMSException - if there was an error in getting the transformation

receiveNoData()

public void receiveNoData()

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser.

Throws

JMSException - if the message could not be received due to an error

receiveNoData(long)

public void receiveNoData(long tomeOut)

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser. This call will block until a message arrives or the timeout expires

Parameters

timeout - the timeout value in milliseconds

Throws

JMSException - if the message could not be received due to an error

setTransformation(String)

public void setTransformation(String transformation)

Set transformation for this receiver. This transformation will be applied before the message is returned to the user.

Parameters

transformation - transformation to be applied before returning the message

Methods

getNavigationMode()

public int getNavigationMode()

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser. This call will block until a message arrives or the timeout expires

Parameters

timeout - the timeout value in milliseconds

Throws

JMSException - if the message could not be received due to an error

receiveNoData()

public void receiveNoData()

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser.

Throws

JMSException - if the message could not be received due to an error

receiveNoData(long)

public void receiveNoData(long tomeOut)

Consume the message without returning it to the user. This call will avoid the overhead of fetching the message from the database and hence can be used as an optimization by jms clients who have already got the message for example using a queue browser. This call will block until a message arrives or the timeout expires

Parameters

timeout - the timeout value in milliseconds

Throws

JMSException - if the message could not be received due to an error

setNavigationMode(int)

public void setNavigationMode(int mode)

set the navigation mode used for receiving messages

Parameters

mode - the new value of the navigation mode

Throws

JMSException - if there was an error in getting the navigation mode

TopicBrowser

Syntax

public interface TopicBrowser extends javax.jms.MessageConsumer

All Known Subinterfaces

AQjmsTopicBrowser

All Superinterfaces

javax.jms.MessageConsumer

Description

This interface extends MessageConsumer to allow remote subscribers to look at messages on a topic without removing them.