Skip navigation links

Oracle® Streams Advanced Queuing Java API Reference
11g Release 2 (11.2)

E10768-01


oracle.jms
Class AQjmsSession

java.lang.Object
  extended by oracle.jms.AQjmsObject
      extended by oracle.jms.AQjmsSession

All Implemented Interfaces:
java.lang.Runnable, QueueSession, Session, TopicSession
Direct Known Subclasses:
AQjmsXASession

public class AQjmsSession
extends oracle.jms.AQjmsObject
implements QueueSession, TopicSession

This is an Oracle class which implements javax.jms.Session, javax.jms.QueueSession and javax.jms.TopicSession.


Field Summary

 

Fields inherited from interface javax.jms.Session
AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

 

Fields inherited from interface javax.jms.Session
AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED

 

Method Summary
 void alterAQAgent(java.lang.String agentName, boolean enableHTTP, boolean enableSMTP, java.lang.String certLocation)
          Alter an AQ agent.
 void bindAgent(oracle.jms.AQjmsAgent agent, java.lang.String certificate)
          Add an agent into LDAP server (bind)
 void close()
          Closes the session.
 void commit()
          Commits all messages done in this transaction and releases any locks currently held.
 AdtMessage createAdtMessage()
          Creates an AdtMessage.
 AQjmsAdtMessage createAdtMessage(oracle.sql.CustomDatum payload)
          Creates an initialized AdtMessage.
 void createAQAgent(java.lang.String agentName)
          Create an AQ agent.
 void createAQAgent(java.lang.String agentName, boolean enableHTTP, boolean enableSMTP, java.lang.String certLocation)
          Create an AQ agent.
 QueueBrowser createBrowser(Queue queue)
          Creates a QueueBrowser to peek at the messages in the specified queue.
 QueueBrowser createBrowser(Queue queue, java.lang.Object payloadFactory)
          Creates a QueueBrowser to peek at the messages in the specified queue containing ADT messages.
 QueueBrowser createBrowser(Queue queue, java.lang.String messageSelector)
          Creates a QueueBrowser to peek at the messages in the specified queue.
 QueueBrowser createBrowser(Queue queue, java.lang.String messageSelector, boolean locked)
          Creates a QueueBrowser to peek at the messages in the specified queue.
 QueueBrowser createBrowser(Queue queue, java.lang.String messageSelector, java.lang.Object payloadFactory)
          Creates a QueueBrowser to peek at the messages on the specified queue containing ADT messages.
 QueueBrowser createBrowser(Queue queue, java.lang.String messageSelector, java.lang.Object payloadFactory, boolean locked)
          Creates a QueueBrowser to peek at the messages on the specified queue containing ADT messages.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName)
          Creates a TopicBrowser to peek at the messages on the specified topic.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, boolean locked)
          Creates a TopicBrowser to peek at the messages on the specified topic.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.Object payloadFactory)
          Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.Object payloadFactory, boolean locked)
          Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.String messageSelector)
          Creates a TopicBrowser to peek at the messages on the specified topic.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.String messageSelector, boolean locked)
          Creates a TopicBrowser to peek at the messages on the specified topic.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.String messageSelector, java.lang.Object payloadFactory)
          Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages.
 TopicBrowser createBrowser(Topic topic, java.lang.String consumerName, java.lang.String messageSelector, java.lang.Object payloadFactory, boolean locked)
          Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages.
 BytesMessage createBytesMessage()
          Creates a BytesMessage object.
 MessageConsumer createConsumer(Destination destination)
          Creates a MessageConsumer for the specified destination.
 MessageConsumer createConsumer(Destination destination, java.lang.String messageSelector)
          Creates a MessageConsumer for the specified destination, using a message selector.
 MessageConsumer createConsumer(Destination destination, java.lang.String messageSelector, boolean NoLocal)
          Creates MessageConsumer for the specified destination, using a message selector.
 MessageConsumer createConsumer(Destination destination, java.lang.String messageSelector, java.lang.Object payloadFactory, java.lang.String transformation, boolean noLocal)
          A generic routine to create a MessageConsumer used to receive messages from the specified destination.
 TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String subscriberName)
          Creates a durable subscriber to the specified topic.
 TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String subscriberName, java.lang.Object payloadFactory)
          Creates a durable subscriber to the specified topic.
 TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String subscriberName, java.lang.String messageSelector, boolean noLocal)
          Creates a durable subscriber to the specified topic.
 TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String subscriberName, java.lang.String messageSelector, boolean noLocal, java.lang.Object payloadFactory)
          Creates a durable subscriber to the specified topic.
 TopicSubscriber createDurableSubscriber(Topic topic, java.lang.String subscriberName, java.lang.String messageSelector, boolean noLocal, java.lang.Object payloadFactory, java.lang.String transformation)
          Create a durable Subscriber to the specified topic.
 MapMessage createMapMessage()
          Creates a MapMessage.
 Message createMessage()
          Creates a Message object.
 ObjectMessage createObjectMessage()
          Creates an ObjectMessage.
 ObjectMessage createObjectMessage(java.io.Serializable object)
          Creates an initialized ObjectMessage.
 AdtMessage createORAMessage()
          Creates an AdtMessage.
 AQjmsAdtMessage createORAMessage(oracle.sql.ORAData payload)
          Creates an initialized AdtMessage.
 MessageProducer createProducer(Destination destination)
          Creates a MessageProducer to send messages to the specified destination.
 TopicPublisher createPublisher(Topic topic)
          Create a Publisher for the specified topic.
 Queue createQueue(oracle.AQ.AQQueueTable queueTable, java.lang.String queueName, AQjmsDestinationProperty destinationProperty)
          Create a queue.
 Queue createQueue(oracle.AQ.AQQueueTable queueTable, java.lang.String queueName, AQjmsDestinationProperty destinationProperty, boolean autonomous)
           
 Queue createQueue(java.lang.String queueName)
          Creates a queue identity given a Queue name.
 oracle.AQ.AQQueueTable createQueueTable(java.lang.String owner, java.lang.String name, oracle.AQ.AQQueueTableProperty property)
          Create a Queue Table.
 oracle.AQ.AQQueueTable createQueueTable(java.lang.String owner, java.lang.String name, oracle.AQ.AQQueueTableProperty property, boolean autonomous)
           
 QueueReceiver createReceiver(Queue queue)
          Creates a QueueReceiver to receive messages from a queue containing JMS payloads.
 QueueReceiver createReceiver(Queue queue, java.lang.Object payloadFactory)
          Creates a QueueReceiver to receive messages from a queue containing ADT messages.
 QueueReceiver createReceiver(Queue queue, java.lang.String messageSelector)
          Creates a QueueReceiver to receive messages from a queue containing JMS payloads.
 QueueReceiver createReceiver(Queue queue, java.lang.String messageSelector, java.lang.Object payloadFactory)
          Creates a QueueReceiver to receive messages from a queue containing ADT messages.
 void createRemoteSubscriber(Topic topic, oracle.jms.AQjmsAgent remoteSubscriber, java.lang.String messageSelector)
          Creates a remote topic subscriber.
 void createRemoteSubscriber(Topic topic, oracle.jms.AQjmsAgent remoteSubscriber, java.lang.String messageSelector, java.lang.Object payloadFactory)
          Creates a remote topic subscriber.
 void createRemoteSubscriber(Topic topic, oracle.jms.AQjmsAgent remoteSubscriber, java.lang.String messageSelector, java.lang.Object payloadFactory, java.lang.String transformation)
          Creates a remote topic subscriber.
 void createRemoteSubscriber(Topic topic, oracle.jms.AQjmsAgent remoteSubscriber, java.lang.String messageSelector, java.lang.Object payloadFactory, java.lang.String transformation, boolean queueToQueue)
          Create a remote subscriber for a topic.
 QueueSender createSender(Queue queue)
          Creates a QueueSender to send messages to a queue.
 StreamMessage createStreamMessage()
          Creates a StreamMessage.
 TopicSubscriber createSubscriber(Topic topic)
          Creates a nondurable subscriber to the specified topic.
 TopicSubscriber createSubscriber(Topic topic, java.lang.String messageSelector, boolean noLocal)
          Creates a nondurable subscriber to the specified topic, using a message selector or specifying whether messages published by its own connection should be delivered to it.
 TemporaryQueue createTemporaryQueue()
          Creates a TemporaryQueue object.
 TemporaryTopic createTemporaryTopic()
          Create a temporary topic.
 TextMessage createTextMessage()
          Creates a TextMessage.
 TextMessage createTextMessage(java.lang.String text)
          Creates an initialized TextMessage.
 TextMessage createTextMessage(java.lang.StringBuffer stringBuffer)
          Creates an initialized TextMessage.
 Topic createTopic(oracle.AQ.AQQueueTable queueTable, java.lang.String topicName, AQjmsDestinationProperty destinationProperty)
          Create a topic
 Topic createTopic(oracle.AQ.AQQueueTable queueTable, java.lang.String topicName, AQjmsDestinationProperty destinationProperty, boolean autonomous)
           
 Topic createTopic(java.lang.String topicName)
          Creates a topic identity given a Topic name.
 AQjmsTopicReceiver createTopicReceiver(Topic topic, java.lang.String receiverName, java.lang.String messageSelector)
          Creates a TopicReceiver to receive messages from the specified topic.
 AQjmsTopicReceiver createTopicReceiver(Topic topic, java.lang.String receiverName, java.lang.String messageSelector, java.lang.Object payloadFactory)
          Creates a TopicReceiver to receive messages from the specified topic.
 void disableDBAccess(java.lang.String agentName, java.lang.String dbUserName)
          Disable Agent Database Access This method revokes the privileges of the specified database user.
 void dropAQAgent(java.lang.String agentName)
          Drop AQ agent.
 void enableDBAccess(java.lang.String agentName, java.lang.String dbUserName)
          Enable Agent Database Access This method enables the given agent name to have the privileges of the specified database user.
 int getAckMode()
          Returns the acknowledgement mode with which this session was created.
 int getAcknowledgeMode()
          Returns the acknowledgement mode of the session.
 java.sql.Connection getDBConnection()
          Return the JDBC connection used to connect to the database.
 AQjmsConnection getJmsConnection()
          This method returns the JMS connection in which this session was created.
 MessageListener getMessageListener()
          Returns this session's distinguished message listener.
 Queue getQueue(java.lang.String owner, java.lang.String name)
          Get an existing queue.
 oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner, java.lang.String name)
          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 priveleges on queues/topics in the queue table.
 Topic getTopic(java.lang.String owner, java.lang.String name)
          Get an existing topic.
 boolean getTransacted()
          Checks if this session is in transacted mode.
 java.util.Map getTypeMap()
          Get the JDBC type map
 void grantSystemPrivilege(java.lang.String privilege, java.lang.String grantee, boolean adminOption)
          Grants AQ system privileges to users/roles.
 void recover()
          Rolls back the current transaction in the Session.CLIENT_ACKNOWLEDGE mode if this session is a non-transacted session.
 void restartConsumers()
          Restarts receive on all consumers in cons_list Called when a commit or rollback is detected
 void revokeSystemPrivilege(java.lang.String privilege, java.lang.String grantee)
          Revokes AQ system privilege from user/roles.
 void rollback()
          Rolls back any messages done in this transaction and releases any locks currently held.
 void run()
          Optional operation, intended to be used only by Application Servers, not by ordinary JMS clients.
 void setMessageListener(MessageListener listener)
          Sets this session's distinguished message listener.
 void unbindAgent(oracle.jms.AQjmsAgent agent)
          remove an agent from LDAP server (unbind)
 void unsubscribe(java.lang.String subscriberName)
          Unsubscribe a durable subscription that has been created by a client.
 void unsubscribe(Topic topic, oracle.jms.AQjmsAgent remoteSubscriber)
          Unsubscribe a remote durable subscription that has been created by a client on the specified topic
 void unsubscribe(Topic topic, java.lang.String subscriberName)
          Unsubscribe a durable subscription that has been created by a client on the specified topic

 

Methods inherited from class oracle.jms.AQjmsObject
checkClosed, children, finalize, getID, getParent, isOpen, localClose, preClose

 

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Method Detail

createBytesMessage

public BytesMessage createBytesMessage()
                                throws JMSException
Creates a BytesMessage object. A BytesMessage object is used to send a message containing a stream of uninterpreted bytes.
Specified by:
createBytesMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createMapMessage

public MapMessage createMapMessage()
                            throws JMSException
Creates a MapMessage. A MapMessage is used to send a set of name-value pairs where names are Strings and values are instances of Java primitive types.
Specified by:
createMapMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createMessage

public Message createMessage()
                      throws JMSException
Creates a Message object. The Message interface is the root interface of all JMS messages. A Message object holds all the standard message header information. It can be sent when a message containing only header information is sufficient.
Specified by:
createMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createObjectMessage

public ObjectMessage createObjectMessage()
                                  throws JMSException
Creates an ObjectMessage. An ObjectMessage is used to send a message that contains a serializable Java object.
Specified by:
createObjectMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createObjectMessage

public ObjectMessage createObjectMessage(java.io.Serializable object)
                                  throws JMSException
Creates an initialized ObjectMessage. An ObjectMessage is used to send a message that contains a serializable Java object.
Specified by:
createObjectMessage in interface Session
Parameters:
object - the object to use to initialize this message
Throws:
JMSException - if the message is not created due to some error.

createAdtMessage

public AdtMessage createAdtMessage()
                            throws JMSException
Creates an AdtMessage. An AdtMessage is used to send a message that contains a Java object that maps to an Oracle SQL ADT and implements the Oracle CustomDatum interface.
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createAdtMessage

public AQjmsAdtMessage createAdtMessage(oracle.sql.CustomDatum payload)
                                 throws JMSException
Creates an initialized AdtMessage. An AQjmsAdtMessage is used to send a message that contains a Java object that maps to an Oracle SQL ADT and implements the Oracle CustomDatum interface.

Important: CustomDatum support (and hence this method) will be deprecated in a future release.

Parameters:
payload - the object to use to initialize this message
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.
See Also:
createORAMessage(ORAData)

createORAMessage

public AdtMessage createORAMessage()
                            throws JMSException
Creates an AdtMessage. An AdtMessage is used to send a message that contains a Java object that maps to an Oracle SQL ADT and implements the ORAData interface.
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createORAMessage

public AQjmsAdtMessage createORAMessage(oracle.sql.ORAData payload)
                                 throws JMSException
Creates an initialized AdtMessage. An AQjmsAdtMessage is used to send a message that contains a Java object that maps to an Oracle SQL ADT and implements the ORAData interface.
Parameters:
payload - the object to use to initialize this message
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createStreamMessage

public StreamMessage createStreamMessage()
                                  throws JMSException
Creates a StreamMessage. A StreamMessage is used to send a stream of Java primitives.
Specified by:
createStreamMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createTextMessage

public TextMessage createTextMessage()
                              throws JMSException
Creates a TextMessage. A TextMessage is used to send a message containing a text payload.
Specified by:
createTextMessage in interface Session
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createTextMessage

public TextMessage createTextMessage(java.lang.StringBuffer stringBuffer)
                              throws JMSException
Creates an initialized TextMessage. A TextMessage is used to send a message containing a text payload.
Parameters:
stringBuffer - the string buffer used to initialize this message
Returns:
the message
Throws:
JMSException - if the message is not created due to some error.

createTextMessage

public TextMessage createTextMessage(java.lang.String text)
                              throws JMSException
Creates an initialized TextMessage. A TextMessage is used to send a message containing a text payload.
Specified by:
createTextMessage in interface Session
Parameters:
text - the text payload used to initialize this message
Throws:
JMSException - if the message is not created due to some error.

getTransacted

public boolean getTransacted()
                      throws JMSException
Checks if this session is in transacted mode.
Specified by:
getTransacted in interface Session
Returns:
true iff in transacted mode
Throws:
JMSException - if this session is closed.

getAckMode

public int getAckMode()
               throws JMSException
Returns the acknowledgement mode with which this session was created.

Important: This method will be deprecated in a future release.Use getAcknowledgeMode() instead.

Returns:
acknowlegement mode as an int
Throws:
JMSException - if this session is closed.
See Also:
getAcknowledgeMode()

commit

public void commit()
            throws JMSException
Commits all messages done in this transaction and releases any locks currently held.
Specified by:
commit in interface Session
Throws:
JMSException - if the transaction is not committed due to some error.

rollback

public void rollback()
              throws JMSException
Rolls back any messages done in this transaction and releases any locks currently held.
Specified by:
rollback in interface Session
Throws:
JMSException - if the transaction is not rolled back due to some error.

close

public void close()
           throws JMSException
Description copied from interface: Session
Closes the session.

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

There is no need to close the producers and consumers of a closed session.

This call will block until a receive call or message listener in progress has completed. A blocked message consumer receive call returns null when this session is closed.

Closing a transacted session must roll back the transaction in progress.

This method is the only Session method that can be called concurrently.

Invoking any other Session method on a closed session must throw a JMSException.IllegalStateException. Closing a closed session must not throw an exception.

Specified by:
close in interface Session
Overrides:
close in class oracle.jms.AQjmsObject
Throws:
JMSException - if the session is not closed due to some error.

recover

public void recover()
             throws JMSException
Rolls back the current transaction in the Session.CLIENT_ACKNOWLEDGE mode if this session is a non-transacted session. Otherwise, this call could come from a message listener's onMessage() method, in which case the transaction should be rolled back for all acknowledgement modes (since the listener did not successfully process the message). In all other cases the call is ignored
Specified by:
recover in interface Session
Throws:
JMSException - if the JMS provider fails to stop and restart message delivery due to some internal error.
IllegalStateException - if the method is called by a transacted session.
See Also:
Session.recover()

getMessageListener

public MessageListener getMessageListener()
                                   throws JMSException
Returns this session's distinguished message listener.
Specified by:
getMessageListener in interface Session
Returns:
the message listener associated with this session
Throws:
JMSException - if the message listener is not retrieved due to some error.
See Also:
Session.setMessageListener(javax.jms.MessageListener), ServerSessionPool, ServerSession

setMessageListener

public void setMessageListener(MessageListener listener)
                        throws JMSException
Sets this session's distinguished message listener. When it is set, no other form of message receipt in the session can be used; however, all forms of sending messages are still supported.
Specified by:
setMessageListener in interface Session
Parameters:
listener - the message listener to associate with this session
Throws:
JMSException - if the message listener is not set due to some error.
See Also:
Session.getMessageListener(), ServerSessionPool, ServerSession

createQueue

public Queue createQueue(java.lang.String queueName)
                  throws JMSException
Description copied from interface: QueueSession
Creates a queue identity 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 and is not to be initiated by the JMS API. The one exception is the creation of temporary queues, which is accomplished with the createTemporaryQueue method.

Specified by:
createQueue in interface QueueSession
Specified by:
createQueue in interface Session
Parameters:
queueName - name of queue, format is schema.queueName (where the schema. is optional)
Returns:
the queue
Throws:
JMSException - if the queue is not created due to some error.

createReceiver

public QueueReceiver createReceiver(Queue queue)
                             throws JMSException
Creates a QueueReceiver to receive messages from a queue containing JMS payloads.

This method is used to create receivers for queues that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

For Sys.AnyData queues, the typemap must be populated with ORADataFactory objects for any user-defined SQL types.

Specified by:
createReceiver in interface QueueSession
Parameters:
queue - the queue to access
Returns:
the queue receiver
Throws:
JMSException - if a receiver is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createReceiver

public QueueReceiver createReceiver(Queue queue,
                                    java.lang.Object payloadFactory)
                             throws JMSException
Creates a QueueReceiver to receive messages from a queue containing ADT messages.

This method is used to create receivers for queues that contain Oracle ADT payloads.

Parameters:
queue - the queue to access
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
Returns:
the queue receiver
Throws:
JMSException - if a receiver is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createReceiver

public QueueReceiver createReceiver(Queue queue,
                                    java.lang.String messageSelector)
                             throws JMSException
Creates a QueueReceiver to receive messages from a queue containing JMS payloads.

This method is used to create receivers for queues that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

For Sys.AnyData queues, the typemap must be populated with ORADataFactory objects for any user-defined SQL types.

Specified by:
createReceiver in interface QueueSession
Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
When used with an 8.2 or later database, standard JMS selector syntax is fully supported.
When used with a pre-8.2 database, the message selector is limited to one of the following:
  • JMSMessageID to retrieve messages that have the specified message ID. All message IDs must be prefixed with "ID:". For example, JMSMessageID = 'ID:2345234523452345'.
  • JMSCorrelationID to retrieve messages that have a certain correlationID. For example, JMSCorrelationID = 'RUSH'.
Returns:
the queue receiver
Throws:
JMSException - if a receiver is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.
InvalidSelectorException - if the message selector is invalid.

createReceiver

public QueueReceiver createReceiver(Queue queue,
                                    java.lang.String messageSelector,
                                    java.lang.Object payloadFactory)
                             throws JMSException
Creates a QueueReceiver to receive messages from a queue containing ADT messages.

This method is used to create receivers for queues that contain Oracle ADT payloads.

Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
Returns:
the queue receiver
Throws:
JMSException - if a receiver is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.
InvalidSelectorException - if the message selector is invalid.

createSender

public QueueSender createSender(Queue queue)
                         throws JMSException
Creates a QueueSender to send messages to a queue.
Specified by:
createSender in interface QueueSession
Parameters:
queue - the queue to access, or null to create an unidentifed producer
Returns:
the queue sender
Throws:
JMSException - if a sender is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createBrowser

public QueueBrowser createBrowser(Queue queue)
                           throws JMSException
Creates a QueueBrowser to peek at the messages in the specified queue.

This method is used to create browsers for queues that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

Specified by:
createBrowser in interface QueueSession
Specified by:
createBrowser in interface Session
Parameters:
queue - the queue to access
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createBrowser

public QueueBrowser createBrowser(Queue queue,
                                  java.lang.Object payloadFactory)
                           throws JMSException
Creates a QueueBrowser to peek at the messages in the specified queue containing ADT messages.

This method is used to create receivers for queues that contain Oracle ADT payloads.

Parameters:
queue - the queue to access
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT.

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createBrowser

public QueueBrowser createBrowser(Queue queue,
                                  java.lang.String messageSelector)
                           throws JMSException
Creates a QueueBrowser to peek at the messages in the specified queue.

This method is used to create browsers for queues that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

For Sys.AnyData queues, the typemap must be populated with ORADataFactory objects for any user-defined SQL types.

Specified by:
createBrowser in interface QueueSession
Specified by:
createBrowser in interface Session
Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.
InvalidSelectorException - if the message selector is invalid.

createBrowser

public QueueBrowser createBrowser(Queue queue,
                                  java.lang.String messageSelector,
                                  boolean locked)
                           throws JMSException
Creates a QueueBrowser to peek at the messages in the specified queue.

This method is used to create browsers for queues that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

For Sys.AnyData queues, the typemap must be populated with ORADataFactory objects for any user-defined SQL types.

Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.
InvalidSelectorException - if the message selector is invalid.

createBrowser

public QueueBrowser createBrowser(Queue queue,
                                  java.lang.String messageSelector,
                                  java.lang.Object payloadFactory)
                           throws JMSException
Creates 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.

Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createBrowser

public QueueBrowser createBrowser(Queue queue,
                                  java.lang.String messageSelector,
                                  java.lang.Object payloadFactory,
                                  boolean locked)
                           throws JMSException
Creates 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.

Parameters:
queue - the queue to access
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory 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)

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Queue is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic. Subscribers are durable.

This method is used to create browsers for topics that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  boolean locked)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic. Subscribers are durable.

This method is used to create browsers for topics that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.Object payloadFactory)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages. Subscribers are durable.

This method is used to create receivers for topics that contain Oracle ADT payloads.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.Object payloadFactory,
                                  boolean locked)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages. Subscribers are durable.

This method is used to create receivers for topics that contain Oracle ADT payloads.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.String messageSelector)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic. Subscribers are durable.

This method is used to create browsers for topics that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
messageSelector - only messages with properties matching the message selector expression are delivered
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.
InvalidSelectorException - if the message selector is invalid.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.String messageSelector,
                                  boolean locked)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic. Subscribers are durable.

This method is used to create browsers for topics that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer
messageSelector - only messages with properties matching the message selector expression are delivered
locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.
InvalidSelectorException - if the message selector is invalid.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.String messageSelector,
                                  java.lang.Object payloadFactory)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages. Subscriber names are durable.

This method is used to create browsers for topics that contain Oracle ADT payloads.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer to use
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createBrowser

public TopicBrowser createBrowser(Topic topic,
                                  java.lang.String consumerName,
                                  java.lang.String messageSelector,
                                  java.lang.Object payloadFactory,
                                  boolean locked)
                           throws JMSException
Creates a TopicBrowser to peek at the messages on the specified topic containing ADT messages. Subscriber names are durable.

This method is used to create browsers for topics that contain Oracle ADT payloads.

Parameters:
topic - the topic to access
consumerName - the name of the durable subscriber/consumer to use
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

locked - if true then messages are locked as they are browsed (similar to a SELECT for UPDATE)
Returns:
the browser
Throws:
JMSException - if a browser is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createTemporaryQueue

public TemporaryQueue createTemporaryQueue()
                                    throws JMSException
Description copied from interface: QueueSession
Creates a TemporaryQueue object. Its lifetime will be that of the QueueConnection unless it is deleted earlier.
Specified by:
createTemporaryQueue in interface QueueSession
Specified by:
createTemporaryQueue in interface Session
Returns:
a temporary queue identity
Throws:
JMSException - if the session fails to create a temporary queue due to some internal error.

createTopic

public Topic createTopic(java.lang.String topicName)
                  throws JMSException
Description copied from interface: Session
Creates a topic identity given a Topic name.

This facility is provided for the rare cases where clients need to dynamically manipulate topic identity. This 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 topics is an administrative task and is not to be initiated by the JMS API. The one exception is the creation of temporary topics, which is accomplished with the createTemporaryTopic method.

Specified by:
createTopic in interface Session
Specified by:
createTopic in interface TopicSession
Parameters:
topicName - the name of this Topic
Returns:
a Topic with the given name
Throws:
JMSException - if the session fails to create a topic due to some internal error.

createSubscriber

public TopicSubscriber createSubscriber(Topic topic)
                                 throws JMSException
Description copied from interface: TopicSession
Creates a nondurable subscriber to the specified topic.

A client uses a TopicSubscriber object to receive messages that have been published to a topic.

Regular TopicSubscriber objects are not durable. They receive only messages that are published while they are active.

In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection. The default value for this attribute is false.

Specified by:
createSubscriber in interface TopicSession
Parameters:
topic - the Topic to subscribe to
Throws:
JMSException - if the session fails to create a subscriber due to some internal error.
InvalidDestinationException - if an invalid topic is specified.

createSubscriber

public TopicSubscriber createSubscriber(Topic topic,
                                        java.lang.String messageSelector,
                                        boolean noLocal)
                                 throws JMSException
Description copied from interface: TopicSession
Creates a nondurable subscriber to the specified topic, using a message selector or specifying whether messages published by its own connection should be delivered to it.

A client uses a TopicSubscriber object to receive messages that have been published to a topic.

Regular TopicSubscriber objects are not durable. They receive only messages that are published while they are active.

Messages filtered out by a subscriber's message selector will never be delivered to the subscriber. From the subscriber's perspective, they do not exist.

In some cases, a connection may both publish and subscribe to a topic. The subscriber NoLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection. The default value for this attribute is false.

Specified by:
createSubscriber in interface TopicSession
Parameters:
topic - the Topic to subscribe to
messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
noLocal - if set, inhibits the delivery of messages published by its own connection
Throws:
JMSException - if the session fails to create a subscriber due to some internal error.
InvalidDestinationException - if an invalid topic is specified.
InvalidSelectorException - if the message selector is invalid.

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               java.lang.String subscriberName)
                                        throws JMSException
Creates a durable subscriber to the specified topic.

This method is used to create browsers for topics that contain JMS payloads (payloads of type aq$_jms_*). A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and message selector.

Specified by:
createDurableSubscriber in interface Session
Specified by:
createDurableSubscriber in interface TopicSession
Parameters:
topic - the topic to subscribe to
subscriberName - the name used to identify this subscription
Throws:
JMSException - if a subscriber is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               java.lang.String subscriberName,
                                               java.lang.Object payloadFactory)
                                        throws JMSException
Creates a durable subscriber to the specified topic.

This method is used to create subscribers 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
subscriberName - the name used to identify this subscription
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT

Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.

Throws:
JMSException - if a subscriber is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               java.lang.String subscriberName,
                                               java.lang.String messageSelector,
                                               boolean noLocal)
                                        throws JMSException
Creates a durable subscriber to the specified topic.

This method is used to create subscribers for topics that contain standard JMS payloads (payloads of type aq$_jms_*).

Specified by:
createDurableSubscriber in interface Session
Specified by:
createDurableSubscriber in interface TopicSession
Parameters:
topic - the non-temporary Topic to subscribe to
subscriberName - the name used to identify this subscription
messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
noLocal - if set, inhibits the delivery of messages published by its own connection
Returns:
TopicSubscriber newly created durable subscriber for this topic
Throws:
JMSException - if the session fails to create a subscriber due to some internal error.
InvalidDestinationException - if an invalid topic is specified.
InvalidSelectorException - if the message selector is invalid.
See Also:
Session.createDurableSubscriber(Topic,String,String,boolean)

createDurableSubscriber

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               java.lang.String subscriberName,
                                               java.lang.String messageSelector,
                                               boolean noLocal,
                                               java.lang.Object payloadFactory)
                                        throws JMSException
Creates a durable subscriber to the specified topic.

This method is used to create browsers 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. ADT messages do not contain any user defined properties. However, the selector can be used to select messages based on priority or correlation id or attribute values of the message payload 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).

Parameters:
topic - the topic to subscribe to
subscriberName - 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 selector syntax is similar to the AQ rules syntax:
  • Selection based on priority or correlation is specified as in the following example:
    priority < 3 AND corr_id = 'Fiction'
  • Selection based on message payload is specified as in the following example:
    tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000
    Note that the attribute name must be prefixed with tab.user_data.
noLocal - if set, inhibits the delivery of messages published by its own connection
payloadFactory - CustomDatumFactory/ORADataFactory 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

public TopicSubscriber createDurableSubscriber(Topic topic,
                                               java.lang.String subscriberName,
                                               java.lang.String messageSelector,
                                               boolean noLocal,
                                               java.lang.Object payloadFactory,
                                               java.lang.String transformation)
                                        throws JMSException
Create a durable Subscriber to the specified topic.

This method is used to create browsers only 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. ADT messages do not contain any user defined properties. However, the selector can be used to select messages based on priority or correlation id or attribute values of the message payload 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).

Parameters:
topic - the topic to subscribe to
subscriberName - 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 selector syntax is similar to the AQ rules syntax:
  • Selection based on priority or correlation is specified as in the following example:
    priority < 3 AND corr_id = 'Fiction'
  • Selection based on message payload is specified as in the following example:
    tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000
    Note that the attribute name must be prefixed with tab.user_data.
noLocal - if set, inhibits the delivery of messages published by its own connection
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
transformation - transformation for this subscriber
Throws:
JMSException - if a session fails to create a subscriber due to some JMS error.
InvalidDestinationException - if invalid Topic specified.

createRemoteSubscriber

public void createRemoteSubscriber(Topic topic,
                                   oracle.jms.AQjmsAgent remoteSubscriber,
                                   java.lang.String messageSelector)
                            throws JMSException
Creates a remote topic subscriber. This method is used to create remote subscribers for queues that contain JMS payloads (payloads of type aq$_jms_*).

AQ allows topics to have remote subscribers, i.e. subscribers at other topics in the same or different database. In order to use remote subscribers you must set up propagation from the local topic to the remote subscriber/topic using one of the createRemoteSubscriber methods and schedule propagation using the AQjmsDestination.schedulePropagation(javax.jms.Session, java.lang.String, java.util.Date, java.lang.Double, java.lang.String, java.lang.Double) method. 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

Parameters:
topic - the local topic to propagate
remoteSubscriber - the remote subscriber/topic
The following attributes of remoteSubscriber define the remote subscriber/topic:
  • name - subscription name of the subscriber of the remote topic to which messages published to the local topic should be propagated, or null if messages published to the local topic should be propagated to all subscribers of the remote topic
  • address - address of the remote topic. The syntax is schema.topicName@dblink (where the schema. and @dblink portions are optional).
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.
Throws:
JMSException - if the remote subscriber is not created due to some error.

createRemoteSubscriber

public void createRemoteSubscriber(Topic topic,
                                   oracle.jms.AQjmsAgent remoteSubscriber,
                                   java.lang.String messageSelector,
                                   java.lang.Object payloadFactory)
                            throws JMSException
Creates a remote topic subscriber. This method is used to create remote subscribers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

AQ allows topics to have remote subscribers, i.e. subscribers at other topics in the same or different database. In order to use remote subscribers you must set up propagation from the local topic to the remote subscriber/topic using one of the createRemoteSubscriber methods and schedule propagation using the AQjmsDestination.schedulePropagation(javax.jms.Session, java.lang.String, java.util.Date, java.lang.Double, java.lang.String, java.lang.Double) method. 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

Parameters:
topic - the local topic to propagate
remoteSubscriber - the remote subscriber/topic
The following attributes of remoteSubscriber define the remote subscriber/topic:
  • name - subscription name of the subscriber of the remote topic to which messages published to the local topic should be propagated, or null if messages published to the local topic should be propagated to all subscribers of the remote topic
  • address - address of the remote topic. The syntax is schema.topicName@dblink (where the schema. and @dblink portions are optional).
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.
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
Throws:
JMSException - if the remote subscriber is not created due to some error.

createRemoteSubscriber

public void createRemoteSubscriber(Topic topic,
                                   oracle.jms.AQjmsAgent remoteSubscriber,
                                   java.lang.String messageSelector,
                                   java.lang.Object payloadFactory,
                                   java.lang.String transformation)
                            throws JMSException
Creates a remote topic subscriber. This method is used to create remote subscribers for queues that contain Oracle ADT payloads (instead of the standard JMS defined payloads)

AQ allows topics to have remote subscribers, i.e. subscribers at other topics in the same or different database. In order to use remote subscribers you must set up propagation from the local topic to the remote subscriber/topic using one of the createRemoteSubscriber methods and schedule propagation using the AQjmsDestination.schedulePropagation(javax.jms.Session, java.lang.String, java.util.Date, java.lang.Double, java.lang.String, java.lang.Double) method. 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

Parameters:
topic - the local topic to propagate
remoteSubscriber - the remote subscriber/topic
The following attributes of remoteSubscriber define the remote subscriber/topic:
  • name - subscription name of the subscriber of the remote topic to which messages published to the local topic should be propagated, or null if messages published to the local topic should be propagated to all subscribers of the remote topic
  • address - address of the remote topic. The syntax is schema.topicName@dblink (where the schema. and @dblink portions are optional).
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
transformation - transformation to be applied
Throws:
JMSException - if the remote subscriber is not created due to some error.

createRemoteSubscriber

public void createRemoteSubscriber(Topic topic,
                                   oracle.jms.AQjmsAgent remoteSubscriber,
                                   java.lang.String messageSelector,
                                   java.lang.Object payloadFactory,
                                   java.lang.String transformation,
                                   boolean queueToQueue)
                            throws JMSException
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
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

Parameters:
topic - the local topic to propagate
remoteSubscriber - the remote subscriber/topic
The following attributes of remoteSubscriber define the remote subscriber/topic:
  • name - subscription name of the subscriber of the remote topic to which messages published to the local topic should be propagated, or null if messages published to the local topic should be propagated to all subscribers of the remote topic
  • address - address of the remote topic. The syntax is schema.topicName@dblink (where the schema. and @dblink portions are optional).
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
transformation - transformation to be applied
queueToQueue - If true, propagation is from queue to queue
Throws:
JMSException - if the remote subscriber is not created due to some

createTopicReceiver

public AQjmsTopicReceiver createTopicReceiver(Topic topic,
                                              java.lang.String receiverName,
                                              java.lang.String messageSelector)
                                       throws JMSException
Creates a TopicReceiver to receive messages from the specified topic. This method is used to create topic receivers for topics that contain JMS payloads (payloads of type aq$_jms_*) or payloads of type Sys.AnyData

AQ allows messages to be sent to all subscribers of a topic or to specified recipients. The specified recipients may or may not be subscribers of the topic. If a specified recipient is not a subscriber of the topic, then one of the createTopicReceiver methods must be used to create a TopicReceiver which can receive the recipient's messages. TopicReceivers only receive messages that are enqueued using a recipient list where recipient receiverName is included in the list.

Parameters:
topic - the topic from which messages are to be received
receiverName - the name of the recipient
messageSelector - only messages with properties matching the message selector expression are delivered
See createReceiver for messageSelector limitations.
Throws:
JMSException - if a topic receiver is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.
InvalidSelectorException - if the message selector is invalid.
See Also:
createReceiver(Queue,String)

createTopicReceiver

public AQjmsTopicReceiver createTopicReceiver(Topic topic,
                                              java.lang.String receiverName,
                                              java.lang.String messageSelector,
                                              java.lang.Object payloadFactory)
                                       throws JMSException
Creates a TopicReceiver to receive messages from the specified topic. This method is used to create topic receivers for topics that contain Oracle ADT payloads.

AQ allows messages to be sent to all subscribers of a topic or to specified recipients. The specified recipients may or may not be subscribers of the topic. If a specified recipient is not a subscriber of the topic, then one of the createTopicReceiver methods must be used to create a TopicReceiver which can receive the recipient's messages. TopicReceivers only receive messages that are enqueued using a recipient list where recipient receiverName is included in the list.

Parameters:
topic - the topic from which messages are to be received
receiverName - the name of the recipient
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
Throws:
JMSException - if a topic receiver is not created due to some error.
InvalidDestinationException - if an invalid Topic is specified.
InvalidSelectorException - if the message selector is invalid.

createPublisher

public TopicPublisher createPublisher(Topic topic)
                               throws JMSException
Create a Publisher for the specified topic. A client uses a TopicPublisher for publishing messages on a topic.
Specified by:
createPublisher in interface TopicSession
Parameters:
topic - the topic to publish to, or null if this is an unidentifed producer.
Throws:
JMSException - if a session fails to create a publisher due to some JMS error.
InvalidDestinationException - if invalid Topic specified.

createTemporaryTopic

public TemporaryTopic createTemporaryTopic()
                                    throws JMSException
Create a temporary topic. It's lifetime will be that of the TopicConnection unless deleted earlier.
Specified by:
createTemporaryTopic in interface Session
Specified by:
createTemporaryTopic in interface TopicSession
Returns:
a temporary topic identity
Throws:
JMSException

unsubscribe

public void unsubscribe(java.lang.String subscriberName)
                 throws JMSException
Unsubscribe a durable subscription that has been created by a client. This method works only if the subscriber name is a key in the in-memory subscriber-topic map, else the InvalidDestinationException is thrown and clients must use AQjmsSession.unsubscribe(Topic, subscriberName) instead
Specified by:
unsubscribe in interface Session
Specified by:
unsubscribe in interface TopicSession
Parameters:
subscriberName - the name used to identify this subscription
Throws:
JMSException - NOT_SUPPORTED

unsubscribe

public void unsubscribe(Topic topic,
                        java.lang.String subscriberName)
                 throws JMSException
Unsubscribe a durable subscription that has been created by a client on the specified topic
Parameters:
topic - the topic subscribed to
subscriberName - the name used to identify this subscription.
Throws:
JMSException - if JMS fails to unsubscribe to durable subscription due to some JMS error.
InvalidDestinationException - if invalid Topic specified.

unsubscribe

public void unsubscribe(Topic topic,
                        oracle.jms.AQjmsAgent remoteSubscriber)
                 throws JMSException
Unsubscribe a remote durable subscription that has been created by a client on the specified topic
Parameters:
topic - the topic subscribed to
remoteSubscriber - AQjmsAgent that refers to the remote subcriber. the address field of the AQjmsAgent cannot be null
Throws:
JMSException - if JMS fails to unsubscribe to durable subscription due to some JMS error.
InvalidDestinationException - if invalid Topic specified.

run

public void run()
Description copied from interface: Session
Optional operation, intended to be used only by Application Servers, not by ordinary JMS clients.
Specified by:
run in interface java.lang.Runnable
Specified by:
run in interface Session
See Also:
ServerSession

getDBConnection

public java.sql.Connection getDBConnection()
                                    throws JMSException
Return the JDBC connection used to connect to the database. This method get the underlying JDBC connection. This connection can be used to perform other SQL operations as part of the same JMS transaction
Throws:
JMSException - if JMS fails to get the JDBC connection

getTypeMap

public java.util.Map getTypeMap()
                         throws JMSException
Get the JDBC type map
Returns:
java.util.Map TypeMap (jdk 1.1)
Throws:
JMSException - if type map not found or if the connection is closed

getJmsConnection

public AQjmsConnection getJmsConnection()
                                 throws JMSException
This method returns the JMS connection in which this session was created.
Throws:
JMSException - if JMS fails to get the connection

createQueueTable

public oracle.AQ.AQQueueTable createQueueTable(java.lang.String owner,
                                               java.lang.String name,
                                               oracle.AQ.AQQueueTableProperty property)
                                        throws JMSException
Create a Queue Table. A QueueTable holds both queues or topics
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:
AQQueueTableProperty, AQQueueTableProperty.setMultiConsumer(boolean)

createQueueTable

public oracle.AQ.AQQueueTable createQueueTable(java.lang.String owner,
                                               java.lang.String name,
                                               oracle.AQ.AQQueueTableProperty property,
                                               boolean autonomous)
                                        throws JMSException
Throws:
JMSException

getQueueTable

public oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner,
                                            java.lang.String name)
                                     throws JMSException
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 priveleges 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

createQueue

public Queue createQueue(oracle.AQ.AQQueueTable queueTable,
                         java.lang.String queueName,
                         AQjmsDestinationProperty destinationProperty)
                  throws JMSException
Create a queue.
Parameters:
queueTable - Queue-Table in which the queue is to be created. The queue-table must not be multiconsumer enabled
queueName - name of the queue to be created
destinationProperty - Queue properties.
Throws:
JMSException - if the queue could not be created
See Also:
AQjmsDestinationProperty

createQueue

public Queue createQueue(oracle.AQ.AQQueueTable queueTable,
                         java.lang.String queueName,
                         AQjmsDestinationProperty destinationProperty,
                         boolean autonomous)
                  throws JMSException
Throws:
JMSException

createTopic

public Topic createTopic(oracle.AQ.AQQueueTable queueTable,
                         java.lang.String topicName,
                         AQjmsDestinationProperty destinationProperty)
                  throws JMSException
Create a topic
Parameters:
queueTable - Queue-Table in which the topic is to be created. The queue-table must be multiconsumer enabled
topicName - name of the topic to be created
destinationProperty - Topic properties.
Throws:
JMSException - if the topic could not be created
See Also:
AQjmsDestinationProperty

createTopic

public Topic createTopic(oracle.AQ.AQQueueTable queueTable,
                         java.lang.String topicName,
                         AQjmsDestinationProperty destinationProperty,
                         boolean autonomous)
                  throws JMSException
Throws:
JMSException

getQueue

public Queue getQueue(java.lang.String owner,
                      java.lang.String name)
               throws JMSException
Get an existing queue. The Queue is returned only if the user has created the queue or as enqueue/dequeue privileges on the specified queue
Parameters:
owner - queue owner (schema)
name - queue name
Throws:
JMSException - if the queue could not be returned due to some error

getTopic

public Topic getTopic(java.lang.String owner,
                      java.lang.String name)
               throws JMSException
Get an existing topic. The Topic is returned only if the user has created the topic or as enqueue/dequeue privileges on the specified topic
Parameters:
owner - topic owner (schema)
name - topic name
Throws:
JMSException - if the topic could not be returned due to some error

grantSystemPrivilege

public void grantSystemPrivilege(java.lang.String privilege,
                                 java.lang.String grantee,
                                 boolean adminOption)
                          throws JMSException
Grants AQ system privileges to users/roles. Initially only SYS and SYSTEM can use this procedure successfully.
Parameters:
privilege - options are:
  • "ENQUEUE_ANY" - users with this privilege are allowed to enqueue messages to any queue/topic in the database
  • "DEQUEUE_ANY" - users with this privilege are allowed to dequeue messages from any queue/topic in the database
  • "MANAGE_ANY" - users with this privilege are allowed to access and make admin calls on any queue/topic in the database
grantee - specifies the grantee. The grantee can be a user, role or the "PUBLIC" role.
adminOption - if this is set to true, the grantee is allowed to use this procedure to grant the system privilege to other users or roles
Throws:
JMSException - if the system privilege could not be granted.

revokeSystemPrivilege

public void revokeSystemPrivilege(java.lang.String privilege,
                                  java.lang.String grantee)
                           throws JMSException
Revokes AQ system privilege from user/roles.
Parameters:
privilege - options are "ENQUEUE_ANY", "DEQUEUE_ANY" and "MANAGE_ANY"
grantee - specifies the grantee. The grantee can be a user, role or the "PUBLIC" role.
Throws:
JMSException - if the system privilege could not be revoked.

createAQAgent

public void createAQAgent(java.lang.String agentName)
                   throws JMSException
Create an AQ agent. This agent can be used to access secure queues. In addition, the agent can be allowed access via protocols - HTTP/SMTP.
Parameters:
agentName - name of the AQ agent
Throws:
JMSException - is the agent could not be created. Check linked SQL exception for details

createAQAgent

public void createAQAgent(java.lang.String agentName,
                          boolean enableHTTP,
                          boolean enableSMTP,
                          java.lang.String certLocation)
                   throws JMSException
Create an AQ agent. This agent can be used to access secure queues. In addition, the agent can be allowed access via protocols - HTTP/SMTP.
Parameters:
agentName - name of the AQ agent
enableHTTP - allow this agent to access AQ via HTTP
enableSMTP - allow this agent to access AQ via SMTP
certLocation - certificate location - used authentication when accessing queues via SMTP. Not required for other protocols
Throws:
JMSException - is the agent could not be created. Check linked SQL exception for details

alterAQAgent

public void alterAQAgent(java.lang.String agentName,
                         boolean enableHTTP,
                         boolean enableSMTP,
                         java.lang.String certLocation)
                  throws JMSException
Alter an AQ agent. This agent must have previously been created using createAQAgent This agent can be used to access secure queues. In addition, the agent can be allowed access via protocols - HTTP/SMTP.
Parameters:
agentName - name of the AQ agent
enableHTTP - allow this agent to access AQ via HTTP
enableSMTP - allow this agent to access AQ via SMTP
certLocation - certificate location - used authentication when accessing queues via SMTP. Not required for other protocols
Throws:
JMSException - is the agent could not be altered. Check linked SQL exception for details

dropAQAgent

public void dropAQAgent(java.lang.String agentName)
                 throws JMSException
Drop AQ agent. This agent must have previously been created using createAQAgent
Parameters:
agentName - name of the AQ agent
Throws:
JMSException - is the agent could not be dropped. Check linked SQL exception for details

enableDBAccess

public void enableDBAccess(java.lang.String agentName,
                           java.lang.String dbUserName)
                    throws JMSException
Enable Agent Database Access This method enables the given agent name to have the privileges of the specified database user.
Parameters:
agentName - name of the AQ agent
dbUserName - name of the database user
Throws:
JMSException - is the agent/user mapping falied. Check linked SQL exception for details

disableDBAccess

public void disableDBAccess(java.lang.String agentName,
                            java.lang.String dbUserName)
                     throws JMSException
Disable Agent Database Access This method revokes the privileges of the specified database user. from the given agent.
Parameters:
agentName - name of the AQ agent
dbUserName - name of the database user
Throws:
JMSException - is the agent/user mapping falied. Check linked SQL exception for details

bindAgent

public void bindAgent(oracle.jms.AQjmsAgent agent,
                      java.lang.String certificate)
               throws JMSException
Add an agent into LDAP server (bind)
Parameters:
agent - the agent to be binded
certificate - the digital certificate of the agent
Throws:
JMSException - if the bind call failed

unbindAgent

public void unbindAgent(oracle.jms.AQjmsAgent agent)
                 throws JMSException
remove an agent from LDAP server (unbind)
Parameters:
agent - -- the agent to be unbinded
Throws:
JMSException - if the bind call failed

restartConsumers

public void restartConsumers()
Restarts receive on all consumers in cons_list Called when a commit or rollback is detected

getAcknowledgeMode

public int getAcknowledgeMode()
                       throws JMSException
Returns the acknowledgement mode of the session. The acknowledgement mode is set at the time that the session is created. If the session is transacted, the acknowledgement mode is ignored.
Specified by:
getAcknowledgeMode in interface Session
Returns:
If the session is not transacted, returns the current acknowledgement mode for the session. If the session is transacted, returns SESSION_TRANSACTED.
Throws:
JMSException - if the JMS provider fails to return the acknowledgment mode due to some internal error.
Since:
1.1
See Also:
AQjmsConnection.createSession(boolean, int)

createProducer

public MessageProducer createProducer(Destination destination)
                               throws JMSException
Creates a MessageProducer to send messages to the specified destination.

A client uses a MessageProducer object to send messages to a destination. Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageProducer object.

Specified by:
createProducer in interface Session
Parameters:
destination - the Destination to send to, or null if this is a producer which does not have a specified destination.
Throws:
JMSException - if the session fails to create a MessageProducer due to some internal error.
InvalidDestinationException - if an invalid destination is specified.
Since:
1.1

createConsumer

public MessageConsumer createConsumer(Destination destination)
                               throws JMSException
Description copied from interface: Session
Creates a MessageConsumer for the specified destination. Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.
Specified by:
createConsumer in interface Session
Parameters:
destination - the Destination to access.
Throws:
JMSException - if the session fails to create a consumer due to some internal error.
InvalidDestinationException - if an invalid destination is specified.

createConsumer

public MessageConsumer createConsumer(Destination destination,
                                      java.lang.String messageSelector)
                               throws JMSException
Description copied from interface: Session
Creates a MessageConsumer for the specified destination, using a message selector. Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.

A client uses a MessageConsumer object to receive messages that have been sent to a destination.

Specified by:
createConsumer in interface Session
Parameters:
destination - the Destination to access
messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
Throws:
JMSException - if the session fails to create a MessageConsumer due to some internal error.
InvalidDestinationException - if an invalid destination is specified.
InvalidSelectorException - if the message selector is invalid.

createConsumer

public MessageConsumer createConsumer(Destination destination,
                                      java.lang.String messageSelector,
                                      boolean NoLocal)
                               throws JMSException
Description copied from interface: Session
Creates MessageConsumer for the specified destination, using a message selector. This method can specify whether messages published by its own connection should be delivered to it, if the destination is a topic.

Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.

A client uses a MessageConsumer object to receive messages that have been published to a destination.

In some cases, a connection may both publish and subscribe to a topic. The consumer NoLocal attribute allows a consumer to inhibit the delivery of messages published by its own connection. The default value for this attribute is False. The noLocal value must be supported by destinations that are topics.

Specified by:
createConsumer in interface Session
Parameters:
destination - the Destination to access
messageSelector - only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
NoLocal - - if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for NoLocal is not specified if the destination is a queue.
Throws:
JMSException - if the session fails to create a MessageConsumer due to some internal error.
InvalidDestinationException - if an invalid destination is specified.
InvalidSelectorException - if the message selector is invalid.

createConsumer

public MessageConsumer createConsumer(Destination destination,
                                      java.lang.String messageSelector,
                                      java.lang.Object payloadFactory,
                                      java.lang.String transformation,
                                      boolean noLocal)
                               throws JMSException
A generic routine to create a MessageConsumer used to receive messages from the specified destination. This method is used to create consumers for destinations that contain standard JMS as well as Oracle ADT payloads.
Parameters:
destination - the destination to access
messageSelector - only messages with properties matching the message selector expression are delivered
payloadFactory - CustomDatumFactory/ORADataFactory for the java class that maps to the Oracle ADT
Important: CustomDatum support will be deprecated in a future release. Use ORAData instead.
transformation - transformation if any involved
noLocal - - if true, and the destination is a topic, inhibits the delivery of messages published by its own connection. The behavior for NoLocal is not specified if the destination is a queue.
Throws:
JMSException - if a session fails to create a consumer due to some JMS error.
InvalidDestinationException - if invalid Destination specified.
InvalidSelectorException - if the message selector is invalid.
Since:
1.1

Skip navigation links

Oracle® Streams Advanced Queuing Java API Reference
11g Release 2 (11.2)

E10768-01


Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved.