15
JMS Operational Interface: Basic Operations (Publish-Subscribe)

In this chapter we describe the operational interface (publish-subscribe) to Oracle Advanced Queuing in terms of use cases. That is, we discuss each operation (such as "Publish a Message") as a use case by that name. The table listing all the use cases is provided at the head of the chapter (see "Use Case Model: Operational Interface -- Basic Operations" on page 14-2).

A summary figure, "Use Case Diagram: Operational Interface -- Basic Operations", locates all the use cases in single drawing. If you are using the HTML version of this document, you can use this figure to navigate to the use case that interests you by clicking on the relevant use case title.

The individual use cases are themselves laid out as follows:

Each use case is laid out as follows:

• Use case figure. A figure that depicts the use case.
• Purpose. The purpose of this use case.
• Usage Notes. Guidelines to assist implementation.
• Syntax. The main syntax used to perform this activity.
• Examples. Examples in each programmatic environment that illustrate the use case.

Use Case Model: JMS Operational Interface -- Basic Operations (Publish-Subscribe)

Table 15-1  JMS Operational Interface--Basic Operations (Publish-Subscribe)

Use Case
Creating a Topic Connection with Username/Password
Creating a Topic Connection with Open JDBC Connection
Creating a Topic Connection with Default Connection Factory Parameters
Creating a Topic Connection with an Open OracleOCIConnectionPool
Creating a Topic Session
Creating a Topic Publisher
Publishing a Message Using a Topic Publisher--with Minimal Specification
Publishing a Message Using a Topic Publisher--Specifying Correlation and Delay
Publishing a Message Using a Topic Publisher--Specifying Priority and Time-To-Live
Publishing a Message Using a Topic Publisher--Specifying a Recipient List Overriding Topic Subscribers
Creating a Durable Subscriber for a JMS Topic without Selector
Creating a Durable Subscriber for a JMS Topic with Selector
Creating a Durable Subscriber for an ADT Topic without Selector
Creating a Durable Subscriber for an ADT Topic with Selector
Creating a Remote Subscriber for Topics of JMS Messages
Creating a Remote Subscriber for Topics of Oracle Object Type (ADT) Messages
Unsubscribing a Durable Subscription for a Local Subscriber
Unsubscribing a Durable Subscription for a Remote Subscriber
Creating a Topic Receiver for a Topic of Standard JMS Type Messages
Creating a Topic Receiver for a Topic of Oracle Object Type (ADT) Messages
Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes or Map Messages
Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes, Map Messages, Locking Messages While Browsing
Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages
Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages, Locking Messages While Browsing
Browsing Messages Using a Topic Browser

Creating a Topic Connection with Username/Password

Figure 15-1 Publish-Subscribe--Creating a Topic Connection with Username/Password

Text description of the illustration adque116.gif

Purpose

Create a topic connection with username/password

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicConnectionFactory.createTopicConnection

Example

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

Creating a Topic Connection with Open JDBC Connection

Figure 15-2 Publish-Subscribe--Creating a Topic Connection with Open JDBC Connection

Text description of the illustration adque118.gif

Purpose

Create a topic connection with open JDBC connection.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicConnectionFactory.createTopicConnection

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 Topic Connection with Default Connection Factory Parameters

Figure 15-3 Publish-Subscribe--Creating a Topic Connection with Default Connection Factory Parameters

Text description of the illustration adque117.gif

Purpose

Create a topic connection with default connection factory parameters.

Usage Notes

Not applicable.

Syntax

• Java (JDBC): X,oracle.jms, AQjmsTopicConnectionFactory.createTopicConnection

Creating a Topic Connection with an Open OracleOCIConnectionPool

Figure 15-4 Publish-Subscribe--Creating a Topic Connection with an Open OracleOCIConnectionPool

Text description of the illustration adque427.gif

Purpose

Create a topic connection with an open OracleOCIConnectionPool.

Usage notes

This is a static method.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicConnectionFactory.createTopicConnection

Example

This method may be used if the user wants to use an existing OracleOCIConnectionPool instance for JMS operations. In this case JMS will 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 Topic Session

Figure 15-5 Publish-Subscribe--Creating a Topic Session

Text description of the illustration adque123.gif

Purpose

Create a topic session.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsConnection.createTopicSession

Example

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

Creating a Topic Publisher

Figure 15-6 Publish-Subscribe--Creating a Topic Publisher

Text description of the illustration adque164.gif

Purpose

Create a topic publisher.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createPublisher

Publishing a Message Using a Topic Publisher--with Minimal Specification

Figure 15-7 Publish-Subscribe--Publishing a Message with Minimal Specification

Text description of the illustration adque166.gif

Purpose

Publish a message with minimal specification.

Usage Notes

If the Topic Publisher 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 will override 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).

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicPublisher.publish

Example

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 topic publisher */
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 topic session */
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);

Publishing a Message Using a Topic Publisher--Specifying Correlation and Delay

Figure 15-8 Publish-Subscribe--Publishing a Message Specifying Correlation and Delay

Text description of the illustration adque167.gif

Purpose

Publish a message specifying correlation and delay.

Usage Notes

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicPublisher.publish()

Example

 Example 1 - publish specifying delay, correlation

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

Publishing a Message Using a Topic Publisher--Specifying Priority and Time-To-Live

Figure 15-9 Publish-Subscribe--Publishing Messages Specifying Priority and Time-To-Live

Text description of the illustration adque168.gif

Purpose

Publish a message specifying priority and time-to-live.

Usage Notes

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicPublisher.publish

Example

 Example 1 - publish specifying priority, timeToLive

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

Publishing a Message Using a Topic Publisher--Specifying a Recipient List Overriding Topic Subscribers

Figure 15-10 Publish-Subscribe--Publishing a Message Specifying a Recipient List Overriding Topic Subscribers

Text description of the illustration adque169.gif

Purpose

Publish a messages specifying a recipient list overriding topic subscribers.

Usage Notes

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicPublisher.publish

Example

 Example 1 - publish specifying priority, 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 for a JMS Topic without Selector

Figure 15-11 Publish-Subscribe--Creating a Durable Subscriber for JMS Topic without Selector

Text description of the illustration adque171.gif

Purpose

Create a durable subscriber for a JMS topic without selector.

Usage Notes

The subscriber name and JMS topic need to be specified to create a durable subscriber. An unsubscribe call is needed to end the subscription to the topic.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.CreateDurableSubscriber

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

Figure 15-12 Publish-Subscribe--Creating a Durable Subscriber for a JMS Topic with Selector

Text description of the illustration adque172.gif

Purpose

Create a durable subscriber for a jms topic with selector.

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 may be null. The selector can contain any SQL92 expression that has a combination of one or more of the following:

• JMS Message header fields or properties: JMSPriority (int), JMSCorrelationID (string), JMSType (string), JMSXUserID (string), JMSXAppID (string), JMSXGroupID (string) JMSXGroupSeq (int)

  For example:

  JMSPriority < 3 AND JMSCorrelationID = 'Fiction' 
  
  

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsTopicPublisher.publish

Example

Example 1 - subscribe specifying selector

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 ADT Topic without Selector

Figure 15-13 Publish-Subscribe--Creating a Durable Subscriber for an ADT Topic without Selector

Text description of the illustration adque174.gif

Purpose

Create a durable subscriber for an ADT topic without selector.

Usage Notes

To create a durable subscriber for a Topic of Oracle Object type, the client needs to specify the CustomDatumFactory for the Oracle Object Type in addition to the Topic and subscriber name.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createDurableSubscriber

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 ADT Topic with Selector

Figure 15-14 Publish-Subscribe--Creating a Durable Subscriber for an ADT Topic with Selector

Text description of the illustration adque175.gif

Purpose

Create a durable subscriber for an ADT topic with selector.

Usage Notes

To create a durable subscriber for a Topic of Oracle Object type, the client needs to specify the CustomDatumFactory for the Oracle Object Type in addition to the Topic and subscriber name.

Optionally, a message selector may be specified. Only messages matching the selector will be delivered to the subscriber.

ADT 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 ADT 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 AQ rules syntax

a. Selector on priority or correlation is specified as follows

For example.:- priority > 3 AND corrid = 'Fiction'

b. Selector on message payload is specified as follows. The attribute

name must be prefixed with tab.user_data.

For example:-

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createDurableSubscriber

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 the 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 for Topics of JMS Messages

Figure 15-15 Publish-Subscribe--Creating a Remote Subscriber for Topics of Standard JMS Type Messages

Text description of the illustration adque217.gif

Purpose

Create a remote subscriber for topics of jms messages without selector.

Usage Notes

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createRemoteSubscriber

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 (ADT) Messages

Figure 15-16 Publish-Subscribe--Creating a Remote Subscriber for Topics of Oracle Object Type (ADT) Messages

Text description of the illustration adque176.gif

Purpose

Create a remote subscriber for topics of oracle object type (ADT) messages.

Usage Notes

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 may 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 that same as that for createDurableSubscriber with Topics of ADT type messages. The message selector may be null.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createRemoteSubscriber

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 Topic session */
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 for a Local Subscriber

Figure 15-17 Publish-Subscribe--Unsubscribing a Durable Subscription for a Local Subscriber

Text description of the illustration adque177.gif

Purpose

Unsubscribe a durable subscription for a local subscriber.

Usage Notes

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

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.unsubscribe

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

Figure 15-18 Publish-Subscribe--Unsubscribing a Durable Subscription for a Remote Subscriber

Text description of the illustration adque228.gif

Purpose

Unsubscribe a durable subscription for a remote subscriber.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.unsubscribe

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 Topic Receiver for a Topic of Standard JMS Type Messages

Figure 15-19 Publish-Subscribe--Creating a Topic Receiver for a Topic of Standard JMS Type Messages

Text description of the illustration adque237.gif

Purpose

Create a topic receiver for a topic of standard jms type messages.

Usage Notes

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, it will receive 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.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createTopicReceiver

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 Topic Receiver for a Topic of Oracle Object Type (ADT) Messages

Figure 15-20 Publish-Subscribe--Creating a Topic Receiver for a Topic of Oracle Object Type (ADT) Messages

Text description of the illustration adque238.gif

Purpose

Create a topic receiver for a topic of ADT messages with selector.

Usage Notes

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, it will receive 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 ADT messages.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createTopicReceiver

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 Topic Browser for Topics with Text, Stream, Objects, Bytes or Map Messages

Figure 15-21 Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes or Map Messages

Text description of the illustration adque420.gif

Purpose

Create a topic browser for topics with text, stream, objects, bytes, or map messages.

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.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

Example 1

/* Create a browser without a selector */
TopicSession    jms_session;
TopicBrowser    browser;
Topic           topic;

browser = ((AQjmsSession) jms_session).createBrowser(topic, "SUBS1");

Example2

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

Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes, Map Messages, Locking Messages While Browsing

Figure 15-22 Creating a Topic Browser for Topics with Text, Stream, Objects, Bytes or Map Messages, Locking Messages While Browsing

Text description of the illustration adque421.gif

Purpose

Create a topic browser for topics with text, stream, objects, bytes or map messages, locking messages while browsing.

Usage Notes

If a locked parameter is specified as true, messages are locked as they are browsed. Hence these messages cannot be removed by other consumers until the browsing session ends the transaction.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

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

Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages

Figure 15-23 Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages

Text description of the illustration adque423.gif

Purpose

Create a topic browser for topics of Oracle object type (ADT) messages.

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
  

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

Example

The CustomDatum factory for a particular Java class that maps to the SQL ADT 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 ADT 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());

Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages, Locking Messages While Browsing

Figure 15-24 Creating a Topic Browser for Topics of Oracle Object Type (ADT) Messages, Locking Messages while Browsing

Text description of the illustration adque424.gif

Purpose

Create a topic browser for topics of Oracle object type (ADT) messages, locking messages while browsing.

Usage Notes

Not applicable.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, AQjmsSession.createBrowser

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 Topic Browser

Figure 15-25 Browsing Messages Using a Topic Browser

Text description of the illustration adque425.gif

Purpose

Browse messages using a topic browser.

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.

Syntax

Java (JDBC): Oracle9i Supplied Java Packages Reference oracle.jms, TopicBrowser, AQjmsTopicBrowser

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