Skip Headers

Oracle® Streams Advanced Queuing User's Guide and Reference
Release 10.1

Part Number B10785-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

15 Oracle Streams AQ JMS Operational Interface: Shared Interfaces

This chapter describes the Java Message Service (JMS) operational interface (shared interfaces) to Oracle Streams Advanced Queuing (AQ).

This chapter contains these topics:

Oracle Streams AQ JMS Operational Interface: Shared Interfaces

This section discusses Oracle Streams AQ shared interfaces for JMS operations.

This section contains these topics:

AQjmsConnection.start


Purpose

Starts a JMS connection for receiving messages.


Syntax
public void start()
          throws JMSException

Usage Notes

The start method is used to start (or restart) the connection's delivery of incoming messages.

AQjmsSession.getJmsConnection


Purpose

Gets the JMS connection from a session.


Syntax
public oracle.jms.AQjmsConnection getJmsConnection()
                                            throws JMSException

AQjmsSession.commit


Purpose

Commits all operations in a session.


Syntax
public void commit()
           throws JMSException

Usage Notes

This method commits all JMS and SQL operations performed in this session.

AQjmsSession.rollback


Purpose

Rolls back all operations in a session.


Syntax
public void rollback()
              throws JMSException

Usage Notes

This method terminates all JMS and SQL operations performed in this session.

AQjmsSession.getDBConnection


Purpose

Gets the underlying JDBC connection from a JMS session.


Syntax
public java.sql.Connection getDBConnection()
                                    throws JMSException

Usage Notes

This method is used to obtain the underlying JDBC connection from a JMS session. The JDBC connection can be used to perform SQL operations as part of the same transaction that the JMS operations are accomplished.


Example
java.sql.Connection db_conn;
QueueSession     jms_sess;
db_conn = ((AQjmsSession)jms_sess).getDBConnection();

AQjmsConnection.getOCIConnectionPool


Purpose

Gets the underlying OracleOCIConnectionPool from a JMS connection.


Syntax
public oracle.jdbc.pool.OracleOCIConnectionPool getOCIConnectionPool()

Usage Notes

This method is used to obtain the underlying OracleOCIConnectionPool instance from a JMS connection. The settings of the OracleOCIConnectionPool instance can be tuned by the user depending on the connection usage, for example, the number of sessions the user wants to create using the given connection. The user should not, however, close the OracleOCIConnectionPool instance being used by the JMS connection.


Example
oracle.jdbc.pool.OracleOCIConnectionPool cpool;
QueueConnection jms_conn;
cpool = ((AQjmsConnection)jms_conn).getOCIConnectionPool();

AQjmsSession.createBytesMessage


Purpose

Creates a bytes message.


Syntax
public javax.jms.BytesMessage createBytesMessage()
                                          throws JMSException

Usage Notes

This method can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_BYTES_MESSAGE or AQ$_JMS_MESSAGE payload types.

AQjmsSession.createMapMessage


Purpose

Creates a map message.


Syntax
public javax.jms.MapMessage createMapMessage()
                                      throws JMSException

Usage Notes

This method can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_MAP_MESSAGE or AQ$_JMS_MESSAGE payload types.

AQjmsSession.createStreamMessage


Purpose

Creates a stream message.


Syntax
public javax.jms.StreamMessage createStreamMessage()
                                            throws JMSException

Usage Notes

This method can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_STREAM_MESSAGE or AQ$_JMS_MESSAGE payload types.

AQjmsSession.createObjectMessage


Purpose

Creates an object message.


Syntax
public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
                                            throws JMSException

Usage Notes

This method can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_OBJECT_MESSAGE or AQ$_JMS_MESSAGE payload types.

AQjmsSession.createTextMessage


Purpose

Creates a text message.


Syntax
public javax.jms.TextMessage createTextMessage()
                                        throws JMSException

Usage Notes

This method can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_TEXT_MESSAGE or AQ$_JMS_MESSAGE payload types.

AQjmsSession.createMessage


Purpose

Creates a JMS message.


Syntax
public javax.jms.Message createMessage()
                                throws JMSException

Usage Notes

Use this ADT to store any or all of the JMS message types: bytes messages (JMSBytes), map messages (JMSMap), stream messages (JMSStream), object messages (JMSObject), or text messages (JMSText).

You can use the AQ$_JMS_MESSAGE construct message to construct messages of different types. The message type must be one of the following:

  • DBMS_AQ.JMS_TEXT_MESSAGE

  • DBMS_AQ.JMS_OBJECT_MESSAGE

  • DBMS_AQ.JMS_MAP_MESSAGE

  • DBMS_AQ.JMS_BYTES_MESSAGE

  • DBMS_AQ.JMS_STREAM_MESSAGE

You can also use this ADT to create a header-only JMS message.

AQjmsSession.createAdtMessage


Purpose

Creates an ADT message.


Syntax
public oracle.jms.AdtMessage createAdtMessage()
                                       throws JMSException

Usage Notes

This method can be used only if the queue table that contains the queue/topic was created with an Oracle ADT payload_type (not one of the SYS.AQ$_JMS* types).

An ADT message must be populated with an object that implements the CustomDatum interface. This object must be the java mapping of the SQL ADT defined as the payload for the queue/topic. Java classes corresponding to SQL ADTs can be generated using the Jpublisher tool.

AQjmsMessage.setJMSCorrelationID


Purpose

Specifies message correlation ID.


Syntax
public void setJMSCorrelationID(java.lang.String correlationID)
                         throws JMSException

Specifying JMS Message Property

Property names starting with JMS are provider-specific. User-defined properties cannot start with JMS.

The following provider properties can be set by clients using Text, Stream, Object, Bytes or Map Message:

The following properties can be set on AdtMessage

This section contains these topics:

AQjmsMessage.setBooleanProperty


Purpose

Specifies message property as Boolean.


Syntax
public void setBooleanProperty(java.lang.String name,
                               boolean value)
                        throws JMSException

Parameters
name

Name of the Boolean property.

value

Boolean property value to set in the message.

AQjmsMessage.setStringProperty


Purpose

Specifies message property as String.


Syntax
public void setStringProperty(java.lang.String name,
                              java.lang.String value)
                       throws JMSException

Parameters
name

Name of the string property.

value

String property value to set in the message.

AQjmsMessage.setIntProperty


Purpose

Specifies message property as Int.


Syntax
public void setIntProperty(java.lang.String name,
                           int value)
                    throws JMSException

Parameters
name

Name of the integer property.

value

Integer property value to set in the message.

AQjmsMessage.setDoubleProperty


Purpose

Specifies message property as Double.


Syntax
public void setDoubleProperty(java.lang.String name,
                              double value)
                       throws JMSException

Parameters
name

Name of the double property.

value

Double property value to set in the message.

AQjmsMessage.setFloatProperty


Purpose

Specifies message property as Float.


Syntax
public void setFloatProperty(java.lang.String name,
                             float value)
                      throws JMSException

Parameters
name

Name of the float property.

value

Float property value to set in the message.

AQjmsMessage.setByteProperty


Purpose

Specifies message property as Byte.


Syntax
public void setByteProperty(java.lang.String name,
                            byte value)
                     throws JMSException

Parameters
name

Name of the byte property.

value

Byte property value to set in the message.

AQjmsMessage.setLongProperty


Purpose

Specifies message property as Long.


Syntax
public void setLongProperty(java.lang.String name,
                            long value)
                     throws JMSException

Parameters
name

Name of the long property.

value

Long property value to set in the message.

AQjmsMessage.setShortProperty


Purpose

Specifies message property as Short.


Syntax
public void setShortProperty(java.lang.String name,
                             short value)
                      throws JMSException

Parameters
name

Name of the short property.

value

Short property value to set in the message.

AQjmsMessage.setObjectProperty


Purpose

Specifies message property as Object.


Syntax
public void setObjectProperty(java.lang.String name,
                              java.lang.Object value)
                       throws JMSException

Parameters
name

Name of the Java object property.

value

Java object property value to set in the message.


Usage Notes

Only objectified primitive values are supported: Boolean, Byte, Short, Integer, Long, Float, Double and String.

Setting Default TimeToLive for All Messages Sent by a MessageProducer


Purpose

Sets default TimeToLive for all messages sent by a message producer.


Syntax
public void setTimeToLive(long timeToLive)
                   throws JMSException

Parameters
timeToLive

Message time to live in milliseconds. Zero (the default) is unlimited.


Usage Notes

TimetoLive is specified in milliseconds. It is calculated after the message is in ready state (i.e after message delay has taken effect).


Example
/* Set default timeToLive value to 100000 milliseconds for all messages sent by the QueueSender*/
QueueSender sender;
sender.setTimeToLive(100000);

Setting Default Priority for All Messages Sent by a MessageProducer


Purpose

Sets default Priority for all messages sent by a MessageProducer.


Syntax
public void setPriority(int priority)
                 throws JMSException

Parameters
priority

Message priority for this MessageProducer. The default is 4.


Usage Notes

Priority values can be any integer. A smaller number indicates higher priority. If a priority value is explicitly specified during the send operation, then it overrides the producer's default value set by this method.


Example 1
/* Set default priority value to 2 for all messages sent by the QueueSender*/
QueueSender sender;
sender.setPriority(2);

Example 2
/* Set default priority value to 2 for all messages sent by the TopicPublisher*/
TopicPublisher publisher;
publisher.setPriority(1);

Creating an AQjms Agent


Purpose

Creates an AQjmsAgent.


Syntax
public void createAQAgent(java.lang.String agent_name,
                          boolean enable_http,
                   throws JMSException

Parameters
agent_name

Name of the AQ agent.

enable_http

If set to true, then this agent is allowed to access AQ through HTTP.

Receiving a Message Synchronously

You can receive a message synchronously two ways:

Using a Message Consumer by Specifying Timeout


Purpose

Receives a message using a message consumer by specifying timeout.


Syntax
public javax.jms.Message receive(long timeout)
                          throws JMSException

Parameters
timeout

Timeout value (in milliseconds).


Examples
TopicConnectionFactory    tc_fact   = null;
TopicConnection           t_conn    = null;
TopicSession              t_sess    = null;
TopicSession              jms_sess;
Topic                     shipped_orders;
int                       myport = 5521;

/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory("MYHOSTNAME",
                                                  "MYSID", myport, "oci8");

t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);

shipped_orders = ((AQjmsSession )jms_sess).getTopic("WS",
"Shipped_Orders_Topic");

/* create a subscriber, specifying the correct CustomDatumFactory  and
selector */
subscriber1 = jms_sess.createDurableSubscriber(shipped_orders,
'WesternShipping', 
             " priority > 1 and tab.user_data.region like 'WESTERN %'",
              false,AQjmsAgent.getFactory());
/* receive, blocking for 30 seconds if there were no messages */
Message = subscriber.receive(30000);

Using a Message Consumer Without Waiting


Purpose

Receives a message using a message consumer without waiting.


Syntax
public javax.jms.Message receiveNoWait()
                                throws JMSException

Specifying the Navigation Mode for Receiving Messages


Purpose

Specifies the navigation mode for receiving messages.


Syntax
public void setNavigationMode(int mode)
                       throws JMSException

Parameters
mode

New value of the navigation mode.


Example
TopicConnectionFactory    tc_fact   = null;
TopicConnection           t_conn    = null;
TopicSession              t_sess    = null;
TopicSession              jms_sess;
Topic                     shipped_orders;
int                       myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
          "MYHOSTNAME",
          "MYSID", 
           myport, 
          "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
          "WS",
          "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory  and
selector */
subscriber1 = jms_sess.createDurableSubscriber(
           shipped_orders,
           WesternShipping',
          "priority > 1 and tab.user_data.region like 'WESTERN %'",
           false,
           AQjmsAgent.getFactory());
subscriber1.setNavigationMode(AQjmsConstants.NAVIGATION_FIRST_MESSAGE);
/* get message for the subscriber, returning immediately if there was no
message */
Message = subscriber.receive();

Receiving a Message Asynchronously

You can receive a message asynchronously two ways:

Specifying a Message Listener at the Message Consumer


Purpose

Specifies a message listener at the message consumer.


Syntax
public void setMessageListener(javax.jms.MessageListener myListener)
                        throws JMSException

Parameters
myListener

Set the consumer's message listener.


Example
TopicConnectionFactory    tc_fact   = null;
TopicConnection           t_conn    = null;
TopicSession              t_sess    = null;
TopicSession              jms_sess;
Topic                     shipped_orders;
int                       myport = 5521;
MessageListener           mLis = null;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
          "MYHOSTNAME",
          "MYSID", 
           myport, 
          "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
          "WS",
          "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory  and
selector */
subscriber1 = jms_sess.createDurableSubscriber(
           shipped_orders,
          'WesternShipping',
          "priority > 1 and tab.user_data.region like 'WESTERN %'",
           false,
           AQjmsAgent.getFactory());
mLis = new myListener(jms_sess, "foo");
/* get message for the subscriber, returning immediately if there was no
message */
subscriber.setMessageListener(mLis);
The definition of the myListener class
import oracle.AQ.*;
import oracle.jms.*;
import javax.jms.*;
import java.lang.*;
import java.util.*;
public class myListener implements MessageListener
{
   TopicSession   mySess;
   String         myName;
   /* constructor */
   myListener(TopicSession t_sess, String t_name)
   {
      mySess = t_sess;
      myName = t_name;
   }
   public onMessage(Message m)
   {
      System.out.println("Retrieved message with correlation: " ||
m.getJMSCorrelationID());
      try{
        /* commit the dequeue */
        mySession.commit();
      } catch (java.sql.SQLException e)
      {System.out.println("SQL Exception on commit"); }
   }
}

Specifying a Message Listener at the Session


Purpose

Specifies a message listener at the session.


Syntax
public void setMessageListener(javax.jms.MessageListener listener)
                        throws JMSException

Parameters
listener

Message listener to associate with this session.

Getting Message ID

This section contains these topics:

AQjmsMessage.getJMSCorrelationID


Purpose

Gets the correlation ID of a message.


Syntax
public java.lang.String getJMSCorrelationID()
          throws JMSException

AQjmsMessage.getJMSMessageID


Purpose

Gets the message ID of a message as bytes or a string.


Syntax
public byte[] getJMSCorrelationIDAsBytes()
          throws JMSException

Getting the JMS Message Properties

This section contains these topics:

AQjmsMessage.getBooleanProperty


Purpose

Gets the message property as Boolean.


Syntax
public boolean getBooleanProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the Boolean property.

AQjmsMessage.getStringProperty


Purpose

Gets the message property as String.


Syntax
public java.lang.String getStringProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the string property.

AQjmsMessage.getIntProperty


Purpose

Gets the message property as Int.


Syntax
public int getIntProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the integer property.

AQjmsMessage.getDoubleProperty


Purpose

Gets the message property as Double.


Syntax
public double getDoubleProperty(java.lang.String name)
                         throws JMSException

Parameters
name

Name of the double property.

AQjmsMessage.getFloatProperty


Purpose

Gets the message property as Float.


Syntax
public float getFloatProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the float property.

AQjmsMessage.getByteProperty


Purpose

Gets the message property as Byte.


Syntax
public byte getByteProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the byte property.

AQjmsMessage.getLongProperty


Purpose

Gets the message property as Long.


Syntax
public long getLongProperty(java.lang.String name)
          throws JMSException

Parameters
name

Name of the long property.

AQjmsMessage.getShortProperty


Purpose

Gets the message property as Short.


Syntax
public short getShortProperty(java.lang.String name)
                       throws JMSException

Parameters
name

Name of the short property.

AQjmsMessage.getObjectProperty


Purpose

Gets the message property as Object.


Syntax
public java.lang.Object getObjectProperty(java.lang.String name)
                                   throws JMSException

Parameters
name

Name of the Java object property.


Examples
TextMessage message;
message.getObjectProperty("empid", new Integer(1000);

Closing and Shutting Down

This section contains these topics:

AQjmsProducer.close


Purpose

Closes a MessageProducer.


Syntax
public void close()
           throws JMSException

AQjmsConsumer.close


Purpose

Closes a message consumer.


Syntax
public void close()
           throws JMSException

AQjmsConnection.stop


Purpose

Stops a JMS connection.


Syntax
public void stop()
          throws JMSException

Usage Notes

This method is used to temporarily stop a connection's delivery of incoming messages.

AQjmsSession.close


Purpose

Closes a JMS session.


Syntax
public void close()
           throws JMSException

AQjmsConnection.close


Purpose

Closes a JMS connection.


Syntax
public void close()
          throws JMSException

Usage Notes

This method closes the connection and releases all resources allocated on behalf of the connection. Because the JMS provider typically allocates significant resources outside the JVM on behalf of a Connection, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.

Troubleshooting

This section contains these topics:

AQjmsException.getErrorCode


Purpose

Gets the error code for the JMS exception.


Syntax
public java.lang.String getErrorCode()

AQjmsException.getErrorNumber


Purpose

Gets the error number for the JMS exception.


Note:

This method will be deprecated in a future release. Use getErrorCode() instead.


Syntax
public int getErrorNumber()

AQjmsException.getLinkString


Purpose

Gets the exception linked to the JMS exception.


Syntax
public java.lang.String getLinkString()

Usage Notes

This method is used to get the exception linked to this JMS exception. In general, this contains the SQL exception raised by the database.

AQjmsException.printStackTrace


Purpose

Prints the stack trace for the JMS exception.


Syntax
public void printStackTrace(java.io.PrintStream s)

AQjmsConnection.setExceptionListener


Purpose

Specifies an exception listener for the connection.


Syntax
public void setExceptionListener(javax.jms.ExceptionListener listener)
                          throws JMSException

Parameters
listener

Exception listener.


Usage Notes

If a serious problem is detected for the connection, then the connection's ExceptionListener, if one has been registered, is informed. This is accomplished by calling the listener's onException() method, passing it a JMSException describing the problem. This allows a JMS client to be asynchronously notified of a problem. Some connections only consume messages, so they have no other way to learn the connection has failed.


Example
//register an exception listener
Connection jms_connection;
jms_connection.setExceptionListener(
    new ExceptionListener() {
        public void onException (JMSException jmsException) {
            System.out.println("JMS-EXCEPTION: " + jmsException.toString());
        }
    };
  );

AQjmsConnection.getExceptionListener


Purpose

Gets the exception listener for the connection.


Syntax
public javax.jms.ExceptionListener getExceptionListener()
                                                 throws JMSException

Example
//Get the exception listener
Connection jms_connection;
ExceptionListener el = jms_connection.getExceptionListener();