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) publish/subscribe operational interface to Oracle Streams Advanced Queuing (AQ).
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 TopicConnection with Default Connection Factory Parameters
Creating a TopicConnection with an Open OracleOCIConnectionPool
Creates a TopicConnection
with username/password.
public javax.jms.TopicConnection createTopicConnection( java.lang.String username, java.lang.String password) throws JMSException
Name of the user connecting to the database for queuing.
Password for the user creating the connection.
TopicConnectionFactory tc_fact = AQjmsFactory.getTopicConnectionFactory("sun123", "oratest", 5521, "thin"); /* Create a TopicConnection using a username/password */ TopicConnection tc_conn = tc_fact.createTopicConnection("jmsuser", "jmsuser");
Creates a TopicConnection
with open JDBC connection.
public static javax.jms.TopicConnection createTopicConnection( java.sql.Connection jdbc_connection) throws JMSException
Valid open connection to the database.
Connection db_conn; /*previously opened JDBC connection */ TopicConnection tc_conn = AQjmsTopicConnectionFactory createTopicConnection(db_conn);
OracleDriver ora = new OracleDriver(); TopicConnection tc_conn = AQjmsTopicConnectionFactory.createTopicConnection(ora.defaultConnection());
Creates a TopicConnection
with default connection factory parameters.
public javax.jms.TopicConnection createTopicConnection() throws JMSException
Creates a TopicConnection
with an open OracleOCIConnectionPool
.
public static javax.jms.TopicConnection createTopicConnection( oracle.jdbc.pool.OracleOCIConnectionPool cpool) 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 OracleOCIConnectionPool
instance for JMS operations. In this case JMS does not open an new OracleOCIConnectionPool
instance, but instead use the supplied OracleOCIConnectionPool
instance to create the JMS TopicConnection
object.
OracleOCIConnectionPool cpool; /* previously created OracleOCIConnectionPool */ TopicConnection tc_conn = AQjmsTopicConnectionFactory.createTopicConnection(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.
Creates a TopicSession
.
public javax.jms.TopicSession createTopicSession(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
.
TopicConnection tc_conn; TopicSession t_sess = tc_conn.createTopicSession(true,0);
Creates a TopicPublisher
.
public javax.jms.TopicPublisher createPublisher(javax.jms.Topic topic) throws JMSException
Topic to publish to, or null if this is an unidentified producer.
You can publish a message using a:
Publishes a message with minimal specification.
public void publish(javax.jms.Message message) throws JMSException
Message to publish.
If the TopicPublisher
has been created with a default topic, then the topic parameter may not be specified in the publish call. If a topic is specified in the send operation, then that value overrides the default in the TopicPublisher
. If the TopicPublisher
has been created without a default topic, then the topic must be specified with the publish. The TopicPublisher
uses the default values for message priority
(1
) and timeToLive
(infinite
).
/* Publish specifying topic */ TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicPublisher publisher1; 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); /* create TopicPublisher */ publisher1 = jms_sess.createPublisher(null); /* get topic object */ shipped_orders = ((AQjmsSession )jms_sess).getTopic( 'WS', 'Shipped_Orders_Topic'); /* create text message */ TextMessage jms_sess.createTextMessage(); /* publish specifying the topic */ publisher1.publish(shipped_orders, text_message);
/* Publish without specifying topic */ TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicPublisher publisher1; 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"); /* create TopicSession */ jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE); /* get shipped orders topic */ shipped_orders = ((AQjmsSession )jms_sess).getTopic( "OE", "Shipped_Orders_Topic"); publisher1 = jms_sess.createPublisher(shipped_orders); /* create text message */ TextMessage jms_sess.createTextMessage(); /* publish without specifying the topic */ publisher1.publish(text_message);
Publishes a message specifying correlation and delay.
public void publish(javax.jms.Message message) throws JMSException
Message to publish.
The publisher can set the message properties like delay and correlation before publishing.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicPublisher publisher1; 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( "OE", "Shipped_Orders_Topic"); publisher1 = jms_sess.createPublisher(shipped_orders); /* Create text message */ TextMessage jms_sess.createTextMessage(); /* Set correlation and delay */ /* Set correlation */ jms_sess.setJMSCorrelationID("FOO"); /* Set delay of 30 seconds */ jms_sess.setLongProperty("JMS_OracleDelay", 30); /* Publish */ publisher1.publish(text_message);
Publishes a message specifying priority and TimeToLive
.
public void publish(javax.jms.Topic topic, javax.jms.Message message, oracle.jms.AQjmsAgent[] recipient_list, int deliveryMode, int priority, long timeToLive) throws JMSException
Topic to which to publish the message. This overrides the default topic of the MessageProducer
.
Message to be published.
List of recipients to which the message is published. Recipients are of type AQjmsAgent.
Delivery mode. The options are PERSISTENT
or NON_PERSISTENT
, but only PERSISTENT
is supported in this release.
Priority of the message.
Message time to live in milliseconds; zero is unlimited.
Message priority
and timeToLive
can be specified with the publish call. The only delivery mode supported for this release is PERSISTENT
.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicPublisher publisher1; 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( "OE", "Shipped_Orders_Topic"); publisher1 = jms_sess.createPublisher(shipped_orders); /* Create text message */ TextMessage jms_sess.createTextMessage(); /* Publish message with priority 1 and time to live 200 seconds */ publisher1.publish(text_message, DeliveryMode.PERSISTENT, 1, 200000);
Publishes a message specifying a recipient list overriding topic subscribers.
public void publish(javax.jms.Message message, oracle.jms.AQjmsAgent[] recipient_list) throws JMSException
The message to be published.
The list of recipients to which the message is published. The recipients are of type AQjmsAgent.
The subscription list of the topic can be overridden by specifying the recipient list with the publish call.
/* Publish specifying priority and timeToLive */ TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicPublisher publisher1; Topic shipped_orders; int myport = 5521; AQjmsAgent[] recipList; /* 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( "OE", "Shipped_Orders_Topic"); publisher1 = jms_sess.createPublisher(shipped_orders); /* create text message */ TextMessage jms_sess.createTextMessage(); /* create two receivers */ recipList = new AQjmsAgent[2]; recipList[0] = new AQjmsAgent( "ES", "ES.shipped_orders_topic", AQAgent.DEFAULT_AGENT_PROTOCOL); recipList[1] = new AQjmsAgent( "WS", "WS.shipped_orders_topic", AQAgent.DEFAULT_AGENT_PROTOCOL); /* publish message specifying a recipient list */ publisher1.publish(text_message, recipList);
CreateDurableSubscriber
requires exclusive access to the topics. If there are pending JMS send, publish, or receive operations on the same topic when this call is applied, then exception ORA - 4020 is raised. There are two solutions to the problem:
Limit calls to createDurableSubscriber
at the setup or cleanup phase when there are no other JMS operations pending on the topic. That makes sure that the required resources are not held by other JMS operational calls.
Call TopicSession.commit
before calling createDurableSubscriber
.
This section contains these topics:
Creating a Durable Subscriber for a JMS Topic Without Selector
Creating a Durable Subscriber for an Oracle Object Type Topic Without Selector
Creating a Durable Subscriber for an Oracle Object Type Topic With Selector
Creates a durable subscriber for a JMS topic without selector.
public javax.jms.TopicSubscriber createDurableSubscriber( javax.jms.Topic topic, java.lang.String subs_name) throws JMSException
Non-temporary topic to subscribe to.
Name used to identify this subscription.
The subscriber name and JMS topic must be specified to create a durable subscriber. An unsubscribe call ends the subscription to the topic.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int myport = 5521; AQjmsAgent[] recipList; /* 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( "OE", "Shipped_Orders_Topic"); /* create a durable subscriber on the shipped_orders topic*/ subscriber1 = jms_sess.createDurableSubscriber( shipped_orders, 'WesternShipping');
Creates a durable subscriber for a JMS topic with selector.
public javax.jms.TopicSubscriber createDurableSubscriber( javax.jms.Topic topic, java.lang.String subs_name, java.lang.String messageSelector, boolean noLocal) throws JMSException
Non-temporary topic to subscribe to.
Name used to identify this subscription.
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.
If set to true, then it inhibits the delivery of messages published by its own connection.
The client creates a durable subscriber by specifying a subscriber name and JMS topic. Optionally, a message selector can be specified. Only messages with properties matching the message selector expression are delivered to the subscriber. The selector value can be null. The selector can contain any SQL92 expression that has a combination of one or more of the following:
For example:
JMSPriority < 3 AND JMSCorrelationID = 'Fiction'
JMS message header fields or properties:
JMSPriority (int)
JMSCorrelationID (string)
JMSType (string)
JMSXUserID (string)
JMSXAppID (string)
JMSXGroupID (string)
JMSXGroupSeq (int)
User-defined message properties
For example:
color IN ('RED', BLUE', 'GREEN') AND price < 30000
Operators allowed are:
Logical operators in precedence order NOT
, AND
, OR
comparison operators
=
, >
, >=
, <
, <=
, <>
, !
(both <>
and !
can be used for not equal)
Arithmetic operators in precedence order +
, -
unary, *
, /
, +
, -
Identifier [NOT] IN (string-literal1, string-literal2, ..)
Arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 and arithmetic-expr3
Identifier [NOT] LIKE pattern-value [ESCAPE escape-character]
Pattern-value is a string literal where % refers to any sequence of characters and _ refers to any single character. The optional escape-character is used to escape the special meaning of the '_' and '%' in pattern-value
Identifier IS [NOT] NULL
A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and a different message selector. An unsubscribe call is needed to end the subscription to the topic.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int myport = 5521; AQjmsAgent[] recipList; /* 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( "OE", "Shipped_Orders_Topic"); /* create a subscriber */ /* with condition on JMSPriority and user property 'Region' */ subscriber1 = jms_sess.createDurableSubscriber( shipped_orders, 'WesternShipping', "JMSPriority > 2 and Region like 'Western%'", false);
Creates a durable subscriber for an Oracle object type topic without selector.
public javax.jms.TopicSubscriber createDurableSubscriber( javax.jms.Topic topic, java.lang.String subs_name, java.lang.Object payload_factory) throws JMSException
Non-temporary topic to subscribe to.
Name used to identify this subscription.
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. |
To create a durable subscriber for a topic of Oracle object type, the client must specify the CustomDatumFactory for the Oracle object type in addition to the topic and subscriber name.
/* Subscribe to an ADT queue */ TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int my[port = 5521; AQjmsAgent[] recipList; /* the java mapping of the oracle object type created by J Publisher */ ADTMessage message; /* 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( "OE", "Shipped_Orders_Topic"); /* create a subscriber, specifying the correct CustomDatumFactory */ subscriber1 = jms_sess.createDurableSubscriber( shipped_orders, 'WesternShipping', AQjmsAgent.getFactory());
Creates a durable subscriber for an Oracle object type topic with selector.
public javax.jms.TopicSubscriber createDurableSubscriber( javax.jms.Topic topic, java.lang.String subs_name, java.lang.String messageSelector, boolean noLocal, java.lang.Object payload_factory) throws JMSException
Non-temporary topic to subscribe to.
Name used to identify this subscription.
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.
If set to true, then it inhibits the delivery of messages published by its own connection.
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. |
To create a durable subscriber for a Topic of Oracle object type, the client must specify the CustomDatumFactory for the Oracle object type in addition to the topic and subscriber name.
Optionally, a message selector can be specified. Only messages matching the selector are delivered to the subscriber.
Oracle object type 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 Oracle object type messages is different from the syntax for selectors on queues containing standard JMS payloads (text, stream, object, bytes, map).
The selector is similar to the Oracle Streams AQ rules syntax. An example of a selector on priority or correlation is:
priority > 3 AND corrid = 'Fiction'
An example of a selector on message payload is:
tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000
The attribute name must be prefixed with tab.user_data
.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int myport = 5521; AQjmsAgent[] recipList; /* the java mapping of the oracle object type created by J Publisher */ ADTMessage message; /* 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( "OE", "Shipped_Orders_Topic"); /* create a subscriber, specifying correct CustomDatumFactory and selector */ subscriber1 = jms_sess.createDurableSubscriber( shipped_orders, "WesternShipping", "priority > 1 and tab.user_data.region like 'WESTERN %'", false, ADTMessage.getFactory());
This section contains these topics:
Creates a remote subscriber for topics of JMS messages without selector.
public void createRemoteSubscriber(javax.jms.Topic topic, oracle.jms.AQjmsAgent remote_subscriber, java.lang.String messageSelector) throws JMSException
Topic to subscribe to.
AQjmsAgent that refers to the remote subscriber.
Only messages with properties matching the message selector expression are delivered. This value can be null. The selector syntax is the same as that for createDurableSubscriber
.
Oracle Streams AQ allows topics to have remote subscribers, for example, subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the local and remote topic.
Remote subscribers can 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].
a) 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
b) 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
A message selector can also be specified. Only messages that satisfy the selector are delivered to the remote subscriber. The message selector can be null. The syntax for the selector is the same as that for createDurableSubscriber. The selector can be null.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int my[port = 5521; AQjmsAgent remoteAgent; /* 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( "OE", "Shipped_Orders_Topic"); remoteAgent = new AQjmsAgent("WesternRegion", "WS.shipped_orders_topic", null); /* create a remote subscriber (selector is null )*/ subscriber1 = ((AQjmsSession)jms_sess).createRemoteSubscriber( shipped_orders, remoteAgent, null);
Creates a remote subscriber for topics of Oracle object type messages.
public void createRemoteSubscriber(javax.jms.Topic topic, oracle.jms.AQjmsAgent remote_subscriber, java.lang.String messageSelector, java.lang.Object payload_factory) throws JMSException
Topic to subscribe to.
AQjmsAgent that refers to the remote subscriber.
Only messages with properties matching the message selector expression are delivered. This value can be null. The selector syntax is the same as that for createDurableSubscriber
.
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. |
Oracle Streams AQ allows topics to have remote subscribers, for example, subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the local and remote topic.
Remote subscribers can 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].
a) 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
b) 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
The CustomDatumFactory of the Oracle object type of the topic must be specified. A message selector can also be specified. Only messages that satisfy the selector are delivered to the remote subscriber. The message selector can be null. The syntax for message selector is the same as that for createDurableSubscriber with Topics of Oracle object type messages. The message selector can be null.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int my[port = 5521; AQjmsAgent remoteAgent; ADTMessage message; /* create connection and session */ tc_fact = AQjmsFactory.getTopicConnectionFactory( "MYHOSTNAME", "MYSID", myport, "oci8"); t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic"); /* create TopicSession */ jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE); /* get the Shipped order topic */ shipped_orders = ((AQjmsSession )jms_sess).getTopic( "OE", "Shipped_Orders_Topic"); /* create a remote agent */ remoteAgent = new AQjmsAgent("WesternRegion", "WS.shipped_orders_topic", null); /* create a remote subscriber with null selector*/ subscriber1 = ((AQjmsSession)jms_sess).createRemoteSubscriber( shipped_orders, remoteAgent, null, message.getFactory);
Unsubscribe
requires exclusive access to the topics. If there are pending JMS send, publish, or receive operations on the same topic when this call is applied, then exception ORA - 4020 is raised. There are two solutions to the problem:
Limit calls to unsubscribe
at the setup or cleanup phase when there are no other JMS operations pending on the topic. That makes sure that the required resources are not held by other JMS operational calls.
Call TopicSession.commit
before calling unsubscribe
.
This section contains these topics:
Unsubscribes a durable subscription for a local subscriber.
public void unsubscribe(javax.jms.Topic topic, java.lang.String subs_name) throws JMSException
Non-temporary topic to subscribe to.
Name used to identify this subscription.
Unsubscribe a durable subscription that has been created by a client on the specified topic.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession jms_sess; TopicSubscriber subscriber1; Topic shipped_orders; int myport = 5521; AQjmsAgent[] recipList; /* 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( "OE", "Shipped_Orders_Topic"); /* unsusbcribe "WesternShipping" from shipped_orders */ jms_sess.unsubscribe(shipped_orders, "WesternShipping");
Unsubscribes a durable subscription for a remote subscriber.
public void unsubscribe(javax.jms.Topic topic, oracle.jms.AQjmsAgent remote_subscriber) throws JMSException
Non-temporary topic to subscribe to.
AQjmsAgent
that refers to the remote subscriber. The address field of the AQjmsAgent
cannot be null.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = null; TopicSession jms_sess; Topic shipped_orders; int myport = 5521; AQjmsAgent remoteAgent; /* 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( "OE", "Shipped_Orders_Topic"); remoteAgent = new AQjmsAgent("WS", "WS.Shipped_Orders_Topic", null); /* unsubscribe the remote agent from shipped_orders */ ((AQjmsSession)jms_sess).unsubscribe(shipped_orders, remoteAgent);
This section contains these topics:
Creating a TopicReceiver for a Topic of Standard JMS Type Messages
Creating a TopicReceiver for a Topic of Oracle Object Type Messages
Creates a TopicReceiver
for a topic of standard JMS type messages.
public oracle.jms.AQjmsTopicReceiver createTopicReceiver( javax.jms.Topic topic, java.lang.String receiver_name, java.lang.String messageSelector) throws JMSException
Topic to access.
Name of message receiver.
Only messages with properties matching the message selector expression are delivered. This value can be null. The selector syntax is the same as that for createDurableSubscriber
.
Oracle Streams AQ allows messages to be sent to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, then it receives only those messages that are explicitly addressed to it.
This method must be used order to create a TopicReceiver
object for consumers that are not durable subscribers. A message selector can be specified. The syntax for the message selector is the same as that of a QueueReceiver
for a queue of standard JMS type messages.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = ull; TopicSession jms_sess; Topic shipped_orders; int myport = 5521; TopicReceiver receiver; /* 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"); receiver = ((AQjmsSession)jms_sess).createTopicReceiver( shipped_orders, "WesternRegion", null);
Creates a TopicReceiver
for a topic of Oracle object type messages with selector.
public oracle.jms.AQjmsTopicReceiver createTopicReceiver( javax.jms.Topic topic, java.lang.String receiver_name, java.lang.String messageSelector, java.lang.Object payload_factory) throws JMSException
Topic to access.
Name of message receiver.
Only messages with properties matching the message selector expression are delivered. This value can be null. The selector syntax is the same as that for createDurableSubscriber
.
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. |
Oracle Streams AQ allows messages to be sent to all subscribers of a topic or to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, then it receives only those messages that are explicitly addressed to it.
This method must be used order to create a TopicReceiver
object for consumers that are not durable subscribers. The CustomDatumFactory of the Oracle object type of the queue must be specified. A message selector can also be specified. This can be null. The syntax for the message selector is the same as that of a QueueReceiver
for queues with Oracle object type messages.
TopicConnectionFactory tc_fact = null; TopicConnection t_conn = null; TopicSession t_sess = null; TopicSession jms_sess; Topic shipped_orders; int myport = 5521; TopicReceiver receiver; /* 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"); receiver = ((AQjmsSession)jms_sess).createTopicReceiver( shipped_orders, "WesternRegion", null);
You can create a TopicBrowser
for:
Creates a TopicBrowser
for topics with text, stream, objects, bytes, or map messages.
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic, java.lang.String cons_name, java.lang.String messageSelector) throws JMSException
Topic to access.
Name of the durable subscriber or consumer.
Only messages with properties matching the message selector expression are delivered.
To retrieve messages that have a certain correlationID
, the selector for the TopicBrowser
can be one 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 a list of messages.
/* Create a browser without a selector */ TopicSession jms_session; TopicBrowser browser; Topic topic; browser = ((AQjmsSession) jms_session).createBrowser(topic, "SUBS1");
/* Create a browser for topics with a specified selector */ TopicSession jms_session; TopicBrowser browser; Topic topic; /* create a Browser to look at messages with correlationID = RUSH */ browser = ((AQjmsSession) jms_session).createBrowser( topic, "SUBS1", "JMSCorrelationID = 'RUSH'");
Creates a TopicBrowser
for topics with text, stream, objects, bytes or map messages, locking messages while browsing.
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic, java.lang.String cons_name, java.lang.String messageSelector, boolean locked) throws JMSException
Topic to access.
Name of the durable subscriber or consumer.
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).
If a locked parameter is specified as true, then messages are locked as they are browsed. Hence these messages cannot be removed by other consumers until the browsing session ends the transaction.
/* Create a browser without a selector */ TopicSession jms_session; TopicBrowser browser; Topic topic; browser = ((AQjmsSession) jms_session).createBrowser( topic, "SUBS1", true);
/* Create a browser for topics with a specified selector */ TopicSession jms_session; TopicBrowser browser; Topic topic; /* create a Browser to look at messages with correlationID = RUSH in lock mode */ browser = ((AQjmsSession) jms_session).createBrowser( topic, "SUBS1", "JMSCorrelationID = 'RUSH'", true);
Creates a TopicBrowser
for topics of Oracle object type messages.
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic, java.lang.String cons_name, java.lang.String messageSelector, java.lang.Object payload_factory) throws JMSException
Topic to access.
Name of the durable subscriber or consumer.
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 topics containing AdtMessages,
the selector for TopicBrowser
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 type payload can be obtained using the getFactory
static method. Assume the Topic - test_topic
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 Topic with Adt messages of type EMPLOYEE*/ TopicSession jms_session TopicBrowser browser; Topic test_topic; browser = ((AQjmsSession) jms_session).createBrowser( test_topic, "SUBS1", Employee.getFactory());
Creates a TopicBrowser
for topics of Oracle object type messages, locking messages while browsing.
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic, java.lang.String cons_name, java.lang.String messageSelector, java.lang.Object payload_factory, boolean locked) throws JMSException
Topic to access.
Name of the durable subscriber or consumer.
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 Topic with ADT messages of type EMPLOYEE* in lock mode/ TopicSession jms_session TopicBrowser browser; Topic test_topic; browser = ((AQjmsSession) jms_session).createBrowser( test_topic, "SUBS1", Employee.getFactory(), true);
Browses messages using a TopicBrowser
.
public void purgeSeen() throws JMSException
Use methods in java.util.Enumeration
to go through the list of messages. Use the method purgeSeen
in TopicBrowser
to purge messages that have been seen during the current browse.
/* Create a browser for topics with a specified selector */ public void browse_rush_orders(TopicSession jms_session) TopicBrowser browser; Topic topic; ObjectMessage obj_message BolOrder new_order; Enumeration messages; /* get a handle to the new_orders topic */ topic = ((AQjmsSession) jms_session).getTopic("OE", "OE_bookedorders_topic"); /* create a Browser to look at RUSH orders */ browser = ((AQjmsSession) jms_session).createBrowser( topic, "SUBS1", "JMSCorrelationID = 'RUSH'"); /* Browse through the messages */ for (messages = browser.elements() ; message.hasMoreElements() ;) {obj_message = (ObjectMessage)message.nextElement();} /* Purge messages seen during this browse */ browser.purgeSeen()