14
JMS Operational Interface: Basic Operations (Point-to-Point)

In this chapter we describe the operational interface to Oracle Advanced Queuing in terms of use cases. That is, we discuss each operation (such as "Creating a Queue Sender") as a use case by that name. The table listing all the use cases is provided at the head of the chapter (see "Use Case Model: Operational Interface -- Basic Operations" on page 14-2).

A summary figure, "Use Case Diagram: Operational Interface -- Basic Operations", locates all the use cases in a single drawing. If you are using the HTML version of this document, you can use this figure to navigate to the use case that interests you by clicking on the relevant use case title.

Each use case is laid out as follows:

• Use case figure. A figure that depicts the use case.
• Purpose. The purpose of this use case.
• Usage Notes. Guidelines to assist implementation.
• Syntax. The main syntax used to perform this activity.
• Examples. Examples in each programmatic environment that illustrate the use case.

Use Case Model: Operational Interface -- Basic Operations

Table 14-1 Use Case Model: Operational Interface -- Basic Operations

Use Case
Creating a Queue Connection with Username/Password
Creating a Queue Connection with an Open JDBC Connection
Creating a Queue Connection with Default Connection Factory Parameters
Creating a Queue Connection with an Open OracleOCIConnection Pool
Creating a Queue Session
Creating a Queue Sender
Sending a Message Using a Queue Sender with Default Send Options
Sending Messages Using a Queue Sender by Specifying Send Options
Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes or Map Messages
Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes, Map Messages, Locking Messages
Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages
Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages, Locking Messages While Browsing
Browsing Messages Using a Queue Browser
Creating a Queue Receiver for Queues of Standard JMS Type Messages
Creating a Queue Receiver for Queues of Oracle Object Type (ADT) Messages
Creating a Queue Connection with an Open OracleOCIConnection Pool

Creating a Queue Connection with Username/Password

Figure 14-1 Creating a Queue Connection with Username/Password

Text description of the illustration adque113.gif

Purpose

Create a queue connection with username/password.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueConnectionFactory.createQueueConnection

Example

QueueConnectionFactory qc_fact = 
AQjmsFactory.getQueueConnectionFactory("sun123", "oratest", 5521, "thin");
/* Create a queue connection using a username/password */
QueueConnection qc_conn = qc_fact.createQueueConnection("jmsuser", "jmsuser");

Creating a Queue Connection with an Open JDBC Connection

Figure 14-2 Creating a Queue Connection with an Open JDBC Connection

Text description of the illustration adque115.gif

Purpose

Create a queue connection with an open JDBC connection.

Usage Notes

This is a static method.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueConnectionFactory.createQueueConnection

Example 1

This method may be used if the user wants to use an existing JDBC connection (say from a connection pool) for JMS operations. In this case JMS will not open a new connection, but instead use the supplied JDBC connection to create the JMS QueueConnection object.

Connection db_conn;     /* previously opened JDBC connection */
 QueueConnection qc_conn = AQjmsQueueConnectionFactory.createQueueConnection(db_
conn);

Example 2

This method is the only way to create a JMS QueueConnection when using JMS from java stored procedures inside the database (JDBC Server driver)

OracleDriver ora = new OracleDriver();
QueueConnection qc_conn = 
AQjmsQueueConnectionFactory.createQueueConnection(ora.defaultConnection());

Creating a Queue Connection with Default Connection Factory Parameters

Figure 14-3 Creating a Connection with Default Connection Factory Parameters

Text description of the illustration adque114.gif

Purpose

Create a queue connection with default connection factory parameters.

Usage Notes

The QueueConnectionFactory properties must contain a default username and password: otherwise, this method will throw a JMSException.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueConnectionFactory.createQueueConnection

Creating a Queue Connection with an Open OracleOCIConnection Pool

Figure 14-4 Creating a Queue Connection with an Open OracleOCIConnectionPool

Text description of the illustration adque426.gif

Purpose

Create a queue connection with an open OracleOCIConnectionPool.

Usage notes

This is a static method.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueConnectionFactory.createQueueConnection

Example

This method may be used if the user wants to use an existing OracleOCIConnectionPool instance for JMS operations. In this case JMS will not open an new OracleOCIConnectionPool instance, but instead use the supplied OracleOCIConnectionPool instance to create the JMS QueueConnection object.

OracleOCIConnectionPool cpool; /* previously created OracleOCIConnectionPool */
QueueConnection qc_conn = 
AQjmsQueueConnectionFactory.createQueueConnection(cpool);

Creating a Queue Session

Figure 14-5 Creating a Queue Session

Text description of the illustration adque122.gif

Purpose

Create a queue session.

Usage Notes

Transacted and nontransacted sessions are supported.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsConnection.createQueueSession

Example

For a transacted session:

QueueConnection qc_conn;
QueueSession  q_sess = qc_conn.createQueueSession(true, 0);

Creating a Queue Sender

Figure 14-6 Creating a Queue Sender

Text description of the illustration adque149.gif

Purpose

Create a queue sender.

Usage Notes

If a sender is created without a default Queue, then the destination Queue will have to be specified on every send operation.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createSender

Sending a Message Using a Queue Sender with Default Send Options

Figure 14-7 Sending a Message Using a Queue Sender with Default Send Options

Text description of the illustration adque148.gif

Purpose

Send a message using a queue sender with default send options.

Usage Notes

If the QueueSender has been created with a default queue, then the queue parameter may not necessarily be supplied in the send call. If a queue is specified in the send operation, then this value will override the default queue of the QueueSender.

If the QueueSender has been created without a default queue, then the queue parameter must be specified in every send call.

This send operation uses default values for message priority (1) and timeToLive (infinite).

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueSender.send

Example

Example1

/* Create a sender to send messages to any queue */
QueueSession  jms_sess;
QueueSender  sender1;
TextMessage  message;
sender1 = jms_sess.createSender(null); 
sender1.send(queue, message);

Example2

/* Create a sender to send messages to a specific queue */
QueueSession jms_sess;
QueueSender sender2;
Queue   billed_orders_que;
TextMessage  message;
sender2 = jms_sess.createSender(billed_orders_que);
sender2.send(queue, message);

Sending Messages Using a Queue Sender by Specifying Send Options

Figure 14-8 Sending Messages Using a Queue Sender by Specifying Send Options

Text description of the illustration adque151.gif

Purpose

Send messages using a queue sender by specifying send options.

Usage Notes

If the QueueSender has been created with a default queue, then the queue parameter may not necessarily be supplied in the send call. If a queue is specified in the send operation, then this value will override the default queue of the QueueSender.

If the QueueSender has been created without a default queue, then the queue parameter must be specified in every send call.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueSender.send

Example

Example1

/* Create a sender to send messages to any queue */ 
/* Send a message to new_orders_que with priority 2 and timetoLive 100000 
   milliseconds */
QueueSession  jms_sess;
QueueSender  sender1;
TextMessage mesg;
Queue   new_orders_que
sender1 = jms_sess.createSender(null); 
sender1.send(new_orders_que, mesg, DeliveryMode.PERSISTENT, 2, 100000);

Example2

/* Create a sender to send messages to a specific  queue */ 
/* Send a message with priority 1 and timetoLive 400000 milliseconds */
QueueSession jms_sess;
QueueSender sender2;
Queue   billed_orders_que;
TextMessage mesg;
sender2 = jms_sess.createSender(billed_orders_que);
sender2.send(mesg, DeliveryMode.PERSISTENT, 1, 400000);

Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes or Map Messages

Figure 14-9 Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes or Map Messages

Text description of the illustration adque154.gif

Purpose

Create a queue browser for queues with text, stream, objects, bytes or map messages.

Usage Notes

To retrieve messages that match certain criteria, the selector for the QueueBrowser 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:"

Use methods in java.util.Enumeration to go through list of messages.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

Example1

/* Create a browser without a selector */
QueueSession    jms_session;
QueueBrowser    browser;
Queue           queue;

browser = jms_session.createBrowser(queue);

Example2

/* Create a browser for queues with a specified selector */
QueueSession    jms_session;
QueueBrowser    browser;
Queue           queue;

/* create a Browser to look at messages with correlationID = RUSH  */
browser = jms_session.createBrowser(queue, "JMSCorrelationID = 'RUSH'");

Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes, Map Messages, Locking Messages

Figure 14-10 Creating a Queue Browser for Queues with Text, Stream, Objects, Bytes or Map Messages, Locking Messages While Browsing

Text description of the illustration adque155.gif

Purpose

Create a queue browser for queues with text, stream, objects, bytes or map messages, locking messages while browsing.

Usage Notes

If locked parameter is specified as true, messages are locked as they are browsed. Hence these messages cannot be removed by other consumers until the browsing session ends the transaction

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

Example1

/* Create a browser without a selector */
QueueSession    jms_session;
QueueBrowser    browser;
Queue           queue;

browser = jms_session.createBrowser(queue, null, true);

Example2

/* Create a browser for queues with a specified selector */
QueueSession    jms_session;
QueueBrowser    browser;
Queue           queue;

/* create a Browser to look at messages with 
correlationID = RUSH in lock mode */

browser = jms_session.createBrowser(queue, "JMSCorrelationID = 'RUSH'", true);

Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages

Figure 14-11 Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages

Text description of the illustration adque157.gif

Purpose

Create a queue browser for queues of Oracle object type (ADT) messages.

Usage Notes

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
  

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

The CustomDatum factory for a particular java class that maps to the SQL ADT payload can be obtained using the getFactory static method.

Assume the Queue - test_queue has payload of type SCOTT.EMPLOYEE and the java class that is generated by Jpublisher for this ADT is called Employee. The Employee class implements the CustomDatum interface. The CustomDatumFactory for this class can be obtained by using the Employee.getFactory() method.

 /* Create a browser for a Queue with Adt messages of type EMPLOYEE*/
QueueSession jms_session
QueueBrowser browser;
Queue        test_queue;

browser = ((AQjmsSession)jms_session).createBrowser(test_queue,                  
                                     "corrid='EXPRESS'", Employee.getFactory());

Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages, Locking Messages While Browsing

Figure 14-12 Creating a Queue Browser for Queues of Oracle Object Type (ADT) Messages, Locking Messages While Browsing

Text description of the illustration adque251.gif

Purpose

Create a queue browser for queues of Oracle object type (ADT) messages, locking messages while browsing.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

  /* Create a browser for a Queue with Adt messages of type EMPLOYEE* in lock 
mode/
QueueSession jms_session
QueueBrowser browser;
Queue        test_queue;

browser = ((AQjmsSession)jms_session).createBrowser(test_queue, null, 
Employee.getFactory(), true);

Browsing Messages Using a Queue Browser

Figure 14-13 Browsing Messages Using a Queue Browser

Text description of the illustration adque159.gif

Purpose

Browse messages using a queue browser.

Usage Notes

Use methods in java.util.Enumeration to go through the list of messages.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueBrowser

Example

/* Create a browser for queues with a specified selector */
public void browse_rush_orders(QueueSession jms_session)
{
   QueueBrowser    browser;
   Queue           queue;
   ObjectMessage   obj_message
   BolOrder        new_order;
   Enumeration     messages;

   /* get a handle to the new_orders queue */
   queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");

   /* create a Browser to look at RUSH orders */
   browser = jms_session.createBrowser(queue, "JMSCorrelationID = 'RUSH'");

   /* Browse through the messages */
   for (messages = browser.elements() ; message.hasMoreElements() ;) 
   {
     obj_message = (ObjectMessage)message.nextElement();
   }
} 

Creating a Queue Receiver for Queues of Standard JMS Type Messages

Figure 14-14 Creating a Queue Receiver for Queues of Standard JMS Type Messages

Text description of the illustration adque161.gif

Purpose

Create a queue receiver for queues of standard JMS type messages.

Usage Notes

The selector for the QueueReceiver 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:"

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createReceiver

Example

Example1

/* Create a receiver without a selector */
QueueSession    jms_session
QueueReceiver   receiver;
Queue           queue;

receiver = jms_session.createReceiver(queue);

Example2

/* Create a receiver for queues with a specified selector */
QueueSession    jms_session;
QueueReceiver   receiver;
Queue           queue;

/* create a Receiver to receive messages with correlationID starting with EXP  
*/
browser = jms_session.createReceiver(queue, "JMSCorrelationID LIKE 'EXP%'");

Creating a Queue Receiver for Queues of Oracle Object Type (ADT) Messages

Figure 14-15 Creating a Queue Receiver for Queues of Oracle Object Type (ADT) Messages

Text description of the illustration adque162.gif

Purpose

Create a queue receiver for queues of Oracle object type (ADT) messages.

Usage Notes

The CustomDatum factory for a particular java class that maps to the SQL ADT payload can be obtained using the getFactory static method.

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
  

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createReceiver

Example

Assume the Queue - test_queue has payload of type SCOTT.EMPLOYEE and the java class that is generated by Jpublisher for this ADT is called Employee. The Employee class implements the CustomDatum interface. The CustomDatumFactory for this class can be obtained by using the Employee.getFactory() method.

/* Create a receiver for a Queue with Adt messages of type EMPLOYEE*/
QueueSession jms_session
QueueReceiver receiver;
Queue        test_queue;

browser = ((AQjmsSession)jms_session).createReceiver(test_queue, 
"JMSCorrelationID = 'MANAGER', Employee.getFactory());

Creating a Queue Connection with an Open OracleOCIConnection Pool

Figure 14-16 Creating a Queue Connection with an Open OracleOCIConnectionPool

Text description of the illustration adque426.gif

Purpose

Create a queue connection with an open OracleOCIConnectionPool.

Usage notes

This is a static method.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsQueueConnectionFactory.createQueueConnection

Example

This method may be used if the user wants to use an existing OracleOCIConnectionPool instance for JMS operations. In this case JMS will not open an new OracleOCIConnectionPool instance, but instead use the supplied OracleOCIConnectionPool instance to create the JMS QueueConnection object.

OracleOCIConnectionPool cpool; /* previously created OracleOCIConnectionPool */
QueueConnection qc_conn = 
AQjmsQueueConnectionFactory.createQueueConnection(cpool);
Connection db_conn;     /* previously opened JDBC connection */
 QueueConnection qc_conn = AQjmsQueueConnectionFactory.createQueueConnection(db_
conn);