| Oracle® Streams Advanced Queuing User's Guide and Reference Release 10.1 Part Number B10785-01 |
|
|
View PDF |
| Oracle® Streams Advanced Queuing User's Guide and Reference Release 10.1 Part Number B10785-01 |
|
|
View PDF |
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
Setting Default TimeToLive for All Messages Sent by a MessageProducer
Setting Default Priority for All Messages Sent by a MessageProducer
This section discusses Oracle Streams AQ shared interfaces for JMS operations.
This section contains these topics:
Starts a JMS connection for receiving messages.
public void start()
throws JMSException
The start method is used to start (or restart) the connection's delivery of incoming messages.
Gets the JMS connection from a session.
public oracle.jms.AQjmsConnection getJmsConnection()
throws JMSException
Commits all operations in a session.
public void commit()
throws JMSException
This method commits all JMS and SQL operations performed in this session.
Rolls back all operations in a session.
public void rollback()
throws JMSException
This method terminates all JMS and SQL operations performed in this session.
Gets the underlying JDBC connection from a JMS session.
public java.sql.Connection getDBConnection()
throws JMSException
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.
java.sql.Connection db_conn; QueueSession jms_sess; db_conn = ((AQjmsSession)jms_sess).getDBConnection();
Gets the underlying OracleOCIConnectionPool from a JMS connection.
public oracle.jdbc.pool.OracleOCIConnectionPool getOCIConnectionPool()
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.
oracle.jdbc.pool.OracleOCIConnectionPool cpool; QueueConnection jms_conn; cpool = ((AQjmsConnection)jms_conn).getOCIConnectionPool();
Creates a bytes message.
public javax.jms.BytesMessage createBytesMessage()
throws JMSException
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.
Creates a map message.
public javax.jms.MapMessage createMapMessage()
throws JMSException
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.
Creates a stream message.
public javax.jms.StreamMessage createStreamMessage()
throws JMSException
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.
Creates an object message.
public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
throws JMSException
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.
Creates a text message.
public javax.jms.TextMessage createTextMessage()
throws JMSException
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.
Creates a JMS message.
public javax.jms.Message createMessage()
throws JMSException
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.
Creates an ADT message.
public oracle.jms.AdtMessage createAdtMessage()
throws JMSException
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.
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:
JMSXAppID (String)
JMSXGroupID (string)
JMSXGroupSeq (int)
JMS_OracleExcpQ (String) - exception queue
JMS_OracleDelay (int) - message delay (seconds)
The following properties can be set on AdtMessage
JMS_OracleExcpQ (String) - exception queue - specified as "schema.queue_name"
JMS_OracleDelay (int) - message delay (seconds)
This section contains these topics:
Specifies message property as Boolean.
public void setBooleanProperty(java.lang.String name,
boolean value)
throws JMSException
Name of the Boolean property.
Boolean property value to set in the message.
Specifies message property as String.
public void setStringProperty(java.lang.String name,
java.lang.String value)
throws JMSException
Name of the string property.
String property value to set in the message.
Specifies message property as Int.
public void setIntProperty(java.lang.String name,
int value)
throws JMSException
Name of the integer property.
Integer property value to set in the message.
Specifies message property as Double.
public void setDoubleProperty(java.lang.String name,
double value)
throws JMSException
Name of the double property.
Double property value to set in the message.
Specifies message property as Float.
public void setFloatProperty(java.lang.String name,
float value)
throws JMSException
Name of the float property.
Float property value to set in the message.
Specifies message property as Byte.
public void setByteProperty(java.lang.String name,
byte value)
throws JMSException
Name of the byte property.
Byte property value to set in the message.
Specifies message property as Long.
public void setLongProperty(java.lang.String name,
long value)
throws JMSException
Name of the long property.
Long property value to set in the message.
Specifies message property as Short.
public void setShortProperty(java.lang.String name,
short value)
throws JMSException
Name of the short property.
Short property value to set in the message.
Specifies message property as Object.
public void setObjectProperty(java.lang.String name,
java.lang.Object value)
throws JMSException
Name of the Java object property.
Java object property value to set in the message.
Only objectified primitive values are supported: Boolean, Byte, Short, Integer, Long, Float, Double and String.
Sets default TimeToLive for all messages sent by a message producer.
public void setTimeToLive(long timeToLive)
throws JMSException
Message time to live in milliseconds. Zero (the default) is unlimited.
TimetoLive is specified in milliseconds. It is calculated after the message is in ready state (i.e after message delay has taken effect).
/* Set default timeToLive value to 100000 milliseconds for all messages sent by the QueueSender*/ QueueSender sender; sender.setTimeToLive(100000);
Sets default Priority for all messages sent by a MessageProducer.
public void setPriority(int priority)
throws JMSException
Message priority for this MessageProducer. The default is 4.
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.
/* Set default priority value to 2 for all messages sent by the QueueSender*/ QueueSender sender; sender.setPriority(2);
/* Set default priority value to 2 for all messages sent by the TopicPublisher*/ TopicPublisher publisher; publisher.setPriority(1);
Creates an AQjmsAgent.
public void createAQAgent(java.lang.String agent_name,
boolean enable_http,
throws JMSException
Name of the AQ agent.
If set to true, then this agent is allowed to access AQ through HTTP.
You can receive a message synchronously two ways:
Receives a message using a message consumer by specifying timeout.
public javax.jms.Message receive(long timeout)
throws JMSException
Timeout value (in milliseconds).
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);
Specifies the navigation mode for receiving messages.
public void setNavigationMode(int mode)
throws JMSException
New value of the navigation mode.
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();
You can receive a message asynchronously two ways:
Specifies a message listener at the message consumer.
public void setMessageListener(javax.jms.MessageListener myListener)
throws JMSException
Set the consumer's message listener.
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"); }
}
}
This section contains these topics:
Gets the correlation ID of a message.
public java.lang.String getJMSCorrelationID()
throws JMSException
This section contains these topics:
Gets the message property as Boolean.
public boolean getBooleanProperty(java.lang.String name)
throws JMSException
Name of the Boolean property.
Gets the message property as String.
public java.lang.String getStringProperty(java.lang.String name)
throws JMSException
Name of the string property.
Gets the message property as Int.
public int getIntProperty(java.lang.String name)
throws JMSException
Name of the integer property.
Gets the message property as Double.
public double getDoubleProperty(java.lang.String name)
throws JMSException
Name of the double property.
Gets the message property as Float.
public float getFloatProperty(java.lang.String name)
throws JMSException
Name of the float property.
Gets the message property as Byte.
public byte getByteProperty(java.lang.String name)
throws JMSException
Name of the byte property.
Gets the message property as Long.
public long getLongProperty(java.lang.String name)
throws JMSException
Name of the long property.
Gets the message property as Short.
public short getShortProperty(java.lang.String name)
throws JMSException
Name of the short property.
Gets the message property as Object.
public java.lang.Object getObjectProperty(java.lang.String name)
throws JMSException
Name of the Java object property.
TextMessage message;
message.getObjectProperty("empid", new Integer(1000);
This section contains these topics:
Closes a MessageProducer.
public void close()
throws JMSException
Closes a message consumer.
public void close()
throws JMSException
Stops a JMS connection.
public void stop()
throws JMSException
This method is used to temporarily stop a connection's delivery of incoming messages.
Closes a JMS connection.
public void close()
throws JMSException
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.
This section contains these topics:
Gets the error code for the JMS exception.
public java.lang.String getErrorCode()
Gets the error number for the JMS exception.
|
Note: This method will be deprecated in a future release. UsegetErrorCode() instead. |
public int getErrorNumber()
Gets the exception linked to the JMS exception.
public java.lang.String getLinkString()
This method is used to get the exception linked to this JMS exception. In general, this contains the SQL exception raised by the database.
Prints the stack trace for the JMS exception.
public void printStackTrace(java.io.PrintStream s)
Specifies an exception listener for the connection.
public void setExceptionListener(javax.jms.ExceptionListener listener)
throws JMSException
Exception listener.
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.
//register an exception listener
Connection jms_connection;
jms_connection.setExceptionListener(
new ExceptionListener() {
public void onException (JMSException jmsException) {
System.out.println("JMS-EXCEPTION: " + jmsException.toString());
}
};
);
Gets the exception listener for the connection.
public javax.jms.ExceptionListener getExceptionListener()
throws JMSException
//Get the exception listener Connection jms_connection; ExceptionListener el = jms_connection.getExceptionListener();
|
 Copyright © 1996, 2003 Oracle Corporation All Rights Reserved. |
|