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

14 Oracle Streams AQ JMS Operational Interface: Publish/Subscribe

This chapter describes the Java Message Service (JMS) publish/subscribe operational interface to Oracle Streams Advanced Queuing (AQ).

This chapter contains these topics:

Creating a Connection

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:

Creating a Connection with Username/Password


Purpose

Creates a connection with username and password.


Syntax
public javax.jms.Connection createConnection(
             java.lang.String username,
             java.lang.String password)
      throws JMSException

Parameters
username

Name of the user connecting to the database for queuing.

password

Password for creating the connection to the server.


Usage Notes

This connection supports both point-to-point and publish/subscribe operations.

Creating a Connection with Default Connection Factory Parameters


Purpose

Creates a connection with default connection factory parameters.


Syntax
public javax.jms.Connection createConnection()
      throws JMSException

Usage Notes

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.

Creating a TopicConnection

This section contains these topics:

Creating a TopicConnection with Username/Password


Purpose

Creates a TopicConnection with username/password.


Syntax
public javax.jms.TopicConnection createTopicConnection(
             java.lang.String username,
             java.lang.String password)
      throws JMSException

Parameters
username

Name of the user connecting to the database for queuing.

password

Password for the user creating the connection.


Example
TopicConnectionFactory tc_fact = AQjmsFactory.getTopicConnectionFactory("sun123", "oratest", 5521, "thin");
/* Create a TopicConnection using a username/password */
TopicConnection tc_conn = tc_fact.createTopicConnection("jmsuser", "jmsuser");

Creating a TopicConnection with Open JDBC Connection


Purpose

Creates a TopicConnection with open JDBC connection.


Syntax
public static javax.jms.TopicConnection createTopicConnection(
              java.sql.Connection jdbc_connection)
       throws JMSException

Parameters
jdbc_connection

Valid open connection to the database.


Example 1
Connection db_conn;   /*previously opened JDBC connection */
TopicConnection tc_conn = AQjmsTopicConnectionFactory createTopicConnection(db_conn);

Example 2
OracleDriver ora = new OracleDriver();
TopicConnection tc_conn = 
AQjmsTopicConnectionFactory.createTopicConnection(ora.defaultConnection());

Creating a TopicConnection with Default Connection Factory Parameters


Purpose

Creates a TopicConnection with default connection factory parameters.


Syntax
public javax.jms.TopicConnection createTopicConnection()
         throws JMSException

Creating a TopicConnection with an Open OracleOCIConnectionPool


Purpose

Creates a TopicConnection with an open OracleOCIConnectionPool.


Syntax
public static javax.jms.TopicConnection createTopicConnection(
              oracle.jdbc.pool.OracleOCIConnectionPool cpool)
       throws JMSException

Parameters
cpool

Valid open connection to the database.


Usage notes

This is a static method.


Example

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);

Creating a Session


Purpose

Creates a Session, which supports both point-to-point and publish/subscribe operations.


Syntax
public javax.jms.Session createSession(boolean transacted,
                                                 int ack_mode)
                                          throws JMSException

Parameters
transacted

If set to true, then the session is transactional.

ack_mode

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.


Usage Notes

This method is new and supports JMS version 1.1 specifications.

Creating a TopicSession


Purpose

Creates a TopicSession.


Syntax
public javax.jms.TopicSession createTopicSession(boolean transacted,
                                                 int ack_mode)
                                          throws JMSException

Parameters
transacted

If set to true, then the session is transactional.

ack_mode

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.


Example
TopicConnection tc_conn;
TopicSession t_sess = tc_conn.createTopicSession(true,0);

Creating a TopicPublisher


Purpose

Creates a TopicPublisher.


Syntax
public javax.jms.TopicPublisher createPublisher(javax.jms.Topic topic)
                                         throws JMSException

Parameters
topic

Topic to publish to, or null if this is an unidentified producer.

Publishing a Message

You can publish a message using a:

TopicPublisher with Minimal Specification


Purpose

Publishes a message with minimal specification.


Syntax
public void publish(javax.jms.Message message)
             throws JMSException

Parameters
message

Message to publish.


Usage Notes

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).


Example 1
/* 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);

Example 2
/* 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);

TopicPublisher and Specifying Correlation and Delay


Purpose

Publishes a message specifying correlation and delay.


Syntax
public void publish(javax.jms.Message message)
             throws JMSException

Parameters
message

Message to publish.


Usage Notes

The publisher can set the message properties like delay and correlation before publishing.


Example
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);

TopicPublisher and Specifying Priority and TimeToLive


Purpose

Publishes a message specifying priority and TimeToLive.


Syntax
public void publish(javax.jms.Topic topic,
                    javax.jms.Message message,
                    oracle.jms.AQjmsAgent[] recipient_list,
                    int deliveryMode,
                    int priority,
                    long timeToLive)
             throws JMSException

Parameters
topic

Topic to which to publish the message. This overrides the default topic of the MessageProducer.

message

Message to be published.

recipient_list

List of recipients to which the message is published. Recipients are of type AQjmsAgent.

deliveryMode

Delivery mode. The options are PERSISTENT or NON_PERSISTENT, but only PERSISTENT is supported in this release.

priority

Priority of the message.

timeToLive

Message time to live in milliseconds; zero is unlimited.


Usage Notes

Message priority and timeToLive can be specified with the publish call. The only delivery mode supported for this release is PERSISTENT.


Example
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);

TopicPublisher and Specifying a Recipient List Overriding Topic Subscribers


Purpose

Publishes a message specifying a recipient list overriding topic subscribers.


Syntax
public void publish(javax.jms.Message message,
                    oracle.jms.AQjmsAgent[] recipient_list)
             throws JMSException

Parameters
message

The message to be published.

recipient_list

The list of recipients to which the message is published. The recipients are of type AQjmsAgent.


Usage Notes

The subscription list of the topic can be overridden by specifying the recipient list with the publish call.


Example
/* 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);

Creating a Durable Subscriber

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:

This section contains these topics:

Creating a Durable Subscriber for a JMS Topic Without Selector


Purpose

Creates a durable subscriber for a JMS topic without selector.


Syntax
public javax.jms.TopicSubscriber createDurableSubscriber(
             javax.jms.Topic topic,
             java.lang.String subs_name)
      throws JMSException

Parameters
topic

Non-temporary topic to subscribe to.

subs_name

Name used to identify this subscription.


Usage Notes

The subscriber name and JMS topic must be specified to create a durable subscriber. An unsubscribe call ends the subscription to the topic.


Example
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');

Creating a Durable Subscriber for a JMS Topic With Selector


Purpose

Creates a durable subscriber for a JMS topic with selector.


Syntax
public javax.jms.TopicSubscriber createDurableSubscriber(
             javax.jms.Topic topic,
             java.lang.String subs_name,
             java.lang.String messageSelector,
             boolean noLocal)
      throws JMSException

Parameters
topic

Non-temporary topic to subscribe to.

subs_name

Name used to identify this subscription.

messageSelector

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.

noLocal

If set to true, then it inhibits the delivery of messages published by its own connection.


Usage Notes

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.


Example
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);

Creating a Durable Subscriber for an Oracle Object Type Topic Without Selector


Purpose

Creates a durable subscriber for an Oracle object type topic without selector.


Syntax
public javax.jms.TopicSubscriber createDurableSubscriber(
             javax.jms.Topic topic,
             java.lang.String subs_name,
             java.lang.Object payload_factory)
      throws JMSException

Parameters
topic

Non-temporary topic to subscribe to.

subs_name

Name used to identify this subscription.

payload_factory

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.


Usage Notes

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.


Example
/* 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());

Creating a Durable Subscriber for an Oracle Object Type Topic With Selector


Purpose

Creates a durable subscriber for an Oracle object type topic with selector.


Syntax
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

Parameters
topic

Non-temporary topic to subscribe to.

subs_name

Name used to identify this subscription.

messageSelector

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.

noLocal

If set to true, then it inhibits the delivery of messages published by its own connection.

payload_factory

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.


Usage Notes

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.


Example
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());

Creating a Remote Subscriber

This section contains these topics:

Creating a Remote Subscriber for Topics of JMS Messages


Purpose

Creates a remote subscriber for topics of JMS messages without selector.


Syntax
public void createRemoteSubscriber(javax.jms.Topic topic,
                                   oracle.jms.AQjmsAgent remote_subscriber,
                                   java.lang.String messageSelector)
                            throws JMSException

Parameters
topic

Topic to subscribe to.

remote_subscriber

AQjmsAgent that refers to the remote subscriber.

messageSelector

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.


Usage Notes

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.


Example
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);

Creating a Remote Subscriber for Topics of Oracle Object Type Messages


Purpose

Creates a remote subscriber for topics of Oracle object type messages.


Syntax
public void createRemoteSubscriber(javax.jms.Topic topic,
                                   oracle.jms.AQjmsAgent remote_subscriber,
                                   java.lang.String messageSelector,
                                   java.lang.Object payload_factory)
                            throws JMSException

Parameters
topic

Topic to subscribe to.

remote_subscriber

AQjmsAgent that refers to the remote subscriber.

messageSelector

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.

payload_factory

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.


Usage Notes

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.


Example
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);

Unsubscribing a Durable Subscription

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:

This section contains these topics:

Unsubscribing a Durable Subscription for a Local Subscriber


Purpose

Unsubscribes a durable subscription for a local subscriber.


Syntax
public void unsubscribe(javax.jms.Topic topic,
                        java.lang.String subs_name)
                 throws JMSException

Parameters
topic

Non-temporary topic to subscribe to.

subs_name

Name used to identify this subscription.


Usage Notes

Unsubscribe a durable subscription that has been created by a client on the specified topic.


Example
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");

Unsubscribing a Durable Subscription for a Remote Subscriber


Purpose

Unsubscribes a durable subscription for a remote subscriber.


Syntax
public void unsubscribe(javax.jms.Topic topic,
                        oracle.jms.AQjmsAgent remote_subscriber)
                 throws JMSException

Parameters
topic

Non-temporary topic to subscribe to.

remote_subscriber

AQjmsAgent that refers to the remote subscriber. The address field of the AQjmsAgent cannot be null.


Example
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);

Creating a TopicReceiver

This section contains these topics:

Creating a TopicReceiver for a Topic of Standard JMS Type Messages


Purpose

Creates a TopicReceiver for a topic of standard JMS type messages.


Syntax
public oracle.jms.AQjmsTopicReceiver createTopicReceiver(
              javax.jms.Topic topic,
              java.lang.String receiver_name,
              java.lang.String messageSelector)
       throws JMSException

Parameters
topic

Topic to access.

receiver_name

Name of message receiver.

messageSelector

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.


Usage Notes

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.


Example
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); 

Creating a TopicReceiver for a Topic of Oracle Object Type Messages


Purpose

Creates a TopicReceiver for a topic of Oracle object type messages with selector.


Syntax
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

Parameters
topic

Topic to access.

receiver_name

Name of message receiver.

messageSelector

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.

payload_factory

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.


Usage Notes

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.


Example
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);

Creating a TopicBrowser

You can create a TopicBrowser for:

Topics with Text, Stream, Objects, Bytes or Map Messages


Purpose

Creates a TopicBrowser for topics with text, stream, objects, bytes, or map messages.


Syntax
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
                                             java.lang.String cons_name,
                                             java.lang.String messageSelector)
                                      throws JMSException

Parameters
topic

Topic to access.

cons_name

Name of the durable subscriber or consumer.

messageSelector

Only messages with properties matching the message selector expression are delivered.


Usage Notes

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.


Example 1
/* Create a browser without a selector */
TopicSession    jms_session;
TopicBrowser    browser;
Topic           topic;
browser = ((AQjmsSession) jms_session).createBrowser(topic, "SUBS1");

Example 2
/* 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'");

Topics with Text, Stream, Objects, Bytes, Map Messages, Locking Messages


Purpose

Creates a TopicBrowser for topics with text, stream, objects, bytes or map messages, locking messages while browsing.


Syntax
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
                                             java.lang.String cons_name,
                                             java.lang.String messageSelector,
                                             boolean locked)
                                      throws JMSException

Parameters
topic

Topic to access.

cons_name

Name of the durable subscriber or consumer.

messageSelector

Only messages with properties matching the message selector expression are delivered.

locked

If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE).


Usage Notes

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.


Example 1
/* Create a browser without a selector */
TopicSession    jms_session;
TopicBrowser    browser;
Topic           topic;
browser = ((AQjmsSession) jms_session).createBrowser(
          topic,
         "SUBS1", 
          true);

Example 2
/* 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);

Topics of Oracle Object Type Messages


Purpose

Creates a TopicBrowser for topics of Oracle object type messages.


Syntax
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

Parameters
topic

Topic to access.

cons_name

Name of the durable subscriber or consumer.

messageSelector

Only messages with properties matching the message selector expression are delivered.

payload_factory

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.


Usage Notes

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
    

Example

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());

Topics of Oracle Object Type Messages, Locking Messages


Purpose

Creates a TopicBrowser for topics of Oracle object type messages, locking messages while browsing.


Syntax
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

Parameters
topic

Topic to access.

cons_name

Name of the durable subscriber or consumer.

messageSelector

Only messages with properties matching the message selector expression are delivered.

payload_factory

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.

locked

If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE).


Example
/* 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);

Browsing Messages Using a TopicBrowser


Purpose

Browses messages using a TopicBrowser.


Syntax
public void purgeSeen()
               throws JMSException

Usage Notes

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.


Example
/* 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()