| 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 Oracle Streams Advanced Queuing (AQ) Java Message Service (JMS) operational interface for basic point-to-point operations.
This chapter contains these topics:
A JMS Connection supports both point-to-point and publish/subscribe operations. The methods in this section are new and support JMS version 1.1 specifications.
This section contains these topics:
Creates a connection with username and password.
public javax.jms.Connection createConnection(
java.lang.String username,
java.lang.String password)
throws JMSException
Name of the user connecting to the database for queuing.
Password for creating the connection to the server.
This connection supports both point-to-point and publish/subscribe operations.
Creates a connection with default connection factory parameters.
public javax.jms.Connection createConnection()
throws JMSException
The ConnectionFactory properties must contain a default username and password; otherwise, this method throws a JMSException. This connection supports both point-to-point and publish/subscribe operations.
This section contains these topics:
Creating a Queue Connection with Default Connection Factory Parameters
Creating a Queue Connection with an Open OracleOCIConnection Pool
Creates a queue connection with username and password.
public javax.jms.QueueConnection createQueueConnection(
java.lang.String username,
java.lang.String password)
throws JMSException
Name of the user connecting to the database for queuing.
Password for creating the connection to the server.
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");
Creates a queue connection with an open JDBC connection.
public static javax.jms.QueueConnection createQueueConnection(java.sql.Connection jdbc_connection)
throws JMSException
Valid open connection to the database.
This is a static method.
This method can be used if the user wants to use an existing JDBC connection (say from a connection pool) for JMS operations. In this case JMS does 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);
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());
Creates a queue connection with default connection factory parameters.
public javax.jms.QueueConnection createQueueConnection()
throws JMSException
The QueueConnectionFactory properties must contain a default username and password: otherwise, this method throws a JMSException.
Creates a queue connection with an open OracleOCIConnectionPool.
public static javax.jms.QueueConnection createQueueConnection(
oracle.jdbc.pool.OracleOCIConnectionPool cpool)
throws JMSException
Valid open connection OCI connection pool to the database.
This is a static method.
This method can be used if the user wants to use an existing OracleOCIConnectionPool instance for JMS operations. In this case JMS does not open an new OracleOCIConnectionPool instance, but instead uses the supplied OracleOCIConnectionPool instance to create the JMS QueueConnection object.
OracleOCIConnectionPool cpool; /* previously created OracleOCIConnectionPool */ QueueConnection qc_conn = AQjmsQueueConnectionFactory.createQueueConnection(cpool);
Creates a Session, which supports both point-to-point and publish/subscribe operations.
public javax.jms.Session createSession(boolean transacted,
int ack_mode)
throws JMSException
If set to true, then the session is transactional.
Indicates whether the consumer or the client will acknowledge any messages it receives. It is ignored if the session is transactional. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.
This method is new and supports JMS version 1.1 specifications. Transactional and nontransactional sessions are supported.
Creates a QueueSession.
public javax.jms.QueueSession createQueueSession(boolean transacted,
int ack_mode)
throws JMSException
If set to true, then the session is transactional.
Indicates whether the consumer or the client will acknowledge any messages it receives. It is ignored if the session is transactional. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.
Transactional and nontransactional sessions are supported.
For a transactional session:
QueueConnection qc_conn; QueueSession q_sess = qc_conn.createQueueSession(true, 0);
Creates a QueueSender.
public javax.jms.QueueSender createSender(javax.jms.Queue queue)
throws JMSException
If a sender is created without a default queue, then the destination queue must be specified on every send operation.
This section contains these topics:
Sending Messages Using a QueueSender with Default Send Options
Sending Messages Using a QueueSender by Specifying Send Options
Sends a message using a QueueSender with default send options.
public void send(javax.jms.Queue queue,
javax.jms.Message message)
throws JMSException
Queue to send this message to.
Message to send.
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 overrides 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).
/* 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);
/* 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);
Sends messages using a QueueSender by specifying send options.
public void send(javax.jms.Queue queue,
javax.jms.Message message,
int deliveryMode,
int priority,
long timeToLive)
throws JMSException
Queue to send this message to.
Message to send.
Delivery mode to use.
Priority for this message.
Message lifetime (in milliseconds).
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 overrides 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.
/* 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);
/* 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);
You can create a QueueBrowser for:
Creates a QueueBrowser for queues with text, stream, objects, bytes or map messages.
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue,
java.lang.String messageSelector)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
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.
/* Create a browser without a selector */ QueueSession jms_session; QueueBrowser browser; Queue queue; browser = jms_session.createBrowser(queue);
/* 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'");
Creates a QueueBrowser for queues with text, stream, objects, bytes or map messages, locking messages while browsing.
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue,
java.lang.String messageSelector,
boolean locked)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE).
Locked messages cannot be removed by other consumers until the browsing session ends the transaction.
/* Create a browser without a selector */ QueueSession jms_session; QueueBrowser browser; Queue queue; browser = jms_session.createBrowser(queue, null, true);
/* 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);
Creates a QueueBrowser for queues of Oracle object type messages.
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue,
java.lang.String messageSelector,
java.lang.Object payload_factory)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
CustomDatumFactory or ORADataFactory for the java class that maps to the Oracle ADT.
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
For queues containing AdtMessages the selector for the 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
The CustomDatum factory for a particular java class that maps to the SQL object 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 Oracle object type 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());
Creates a QueueBrowser for queues of Oracle object type messages, locking messages while browsing.
public javax.jms.QueueBrowser createBrowser(javax.jms.Queue queue,
java.lang.String messageSelector,
java.lang.Object payload_factory,
boolean locked)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
CustomDatumFactory or ORADataFactory for the java class that maps to the Oracle ADT.
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE).
/* 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);
You can create a QueueReceiver for:
Creates a QueueReceiver for queues of standard JMS type messages.
public javax.jms.QueueReceiver createReceiver(javax.jms.Queue queue,
java.lang.String messageSelector)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
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. All message IDs must be prefixed with "ID:"
JMS message header fields or properties:
JMSPriority < 3 AND JMSCorrelationID = 'Fiction'
User-defined message properties:
color IN ('RED', BLUE', 'GREEN') AND price < 30000
/* Create a receiver without a selector */ QueueSession jms_session QueueReceiver receiver; Queue queue; receiver = jms_session.createReceiver(queue);
/* Create a receiver for queues with a specified selector */ QueueSession jms_session; QueueReceiver receiver; Queue queue; /* create Receiver to receive messages with correlationID starting with EXP */ browser = jms_session.createReceiver(queue, "JMSCorrelationID LIKE 'EXP%'");
Creates a QueueReceiver for queues of Oracle object type messages.
public javax.jms.QueueReceiver createReceiver(javax.jms.Queue queue,
java.lang.String messageSelector,
java.lang.Object payload_factory)
throws JMSException
Queue to access.
Only messages with properties matching the message selector expression are delivered.
CustomDatumFactory or ORADataFactory for the java class that maps to the Oracle ADT.
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
The CustomDatum factory for a particular java class that maps to the SQL object type payload can be obtained using the getFactory static method.
For queues containing AdtMessages the selector for the 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. In this case message IDs must NOT be prefixed with ID:
msgid = '23434556566767676'
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
Assume the queue test_queue has payload of type SCOTT.EMPLOYEE and the java class that is generated by Jpublisher for this Oracle object type 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());
|
 Copyright © 1996, 2003 Oracle Corporation All Rights Reserved. |
|