Add a Subscriber

Figure 9-16 Use Case Diagram: Add a Subscriber

To refer to the table of all basic operations having to do with the Administrative Interface see: "Use Case Model: Administrative Interface -- Basic Operations"

Purpose:

Adds a default subscriber to a queue.

Usage Note:

• A program can enqueue messages to a specific list of recipients or to the default list of subscribers. This operation will only succeed on queues that allow multiple consumers. This operation takes effect immediately and the containing transaction is committed. Enqueue requests that are executed after the completion of this call will reflect the new behavior.

• Note that any string within the rule has to be quoted as shown below;

  rule   => 'PRIORITY <= 3 AND CORRID =  ''FROM JAPAN'''
  

  Note that these are all single quotation marks.

Syntax

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Use the following syntax references for each programmatic environment:

• PL/SQL (DBMS_AQADM Package): Oracle8i Supplied PL/SQL Packages Reference DBMS_AQADM, ADD_SUBSCRIBER procedure

• Visual Basic (OO4O): There is no applicable syntax reference for this use case

• Java (JDBC): Oracle8i Supplied Java Packages Reference oracle.AQ, addSubscriber

Examples

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment. Examples are provided in the following programmatic environments:

• PL/SQL (DBMS_AQADM): Add Subscriber

• VB (OO4O): Example not provided.

• Java (JDBC): Add a Subscriber

PL/SQL (DBMS_AQADM): Add Subscriber

/* Anonymous PL/SQL block for adding a subscriber at a designated queue in a 
designated schema at a database link: */ 
DECLARE 
   subscriber          sys.aq$_agent; 
BEGIN 
   subscriber := sys.aq$_agent ('subscriber1', 'aq2.msg_queue2@london', null); 
   DBMS_AQADM.ADD_SUBSCRIBER(
     queue_name         => 'aq.multi_queue', 
      subscriber            =>  subscriber); 
 END; 

/* Add a subscriber with a rule: */ 
DECLARE 
   subscriber       sys.aq$_agent; 
BEGIN 
   subscriber := sys.aq$_agent('subscriber2', 'aq2.msg_queue2@london', null); 
   DBMS_AQADM.ADD_SUBSCRIBER(
     queue_name         =>  'aq.multi_queue', 
      subscriber            =>    subscriber, 
      rule                  =>    'priority < 2'); 
END; 

PL/SQL (DBMS_AQADM): Add Rule-Based Subscriber

DECLARE 
   subscriber          sys.aq$_agent; 
BEGIN 
   subscriber :=  sys.aq$_agent('East_Shipping','ES.ES_bookedorders_que',null); 
   DBMS_AQADM.ADD_SUBSCRIBER(
      queue_name           => 'OE.OE_bookedorders_que', 
      subscriber           => subscriber, 
      rule                 => 'tab.user_data.orderregion =  ''EASTERN'' OR 
                              (tab.user_data.ordertype =  ''RUSH'' AND 
                               tab.user_data.customer.country = ''USA'') '); 
END; 

Java (JDBC): Add a Subscriber

/* Setup */
public static void setup(AQSession aq_sess) throws AQException
{
     AQQueueTableProperty    qtable_prop;
     AQQueueProperty         queue_prop;
     AQQueueTable            q_table;
     AQQueue                 queue;

     /* Create a AQQueueTable property object */
     qtable_prop = new AQQueueTableProperty("AQ.MESSAGE_TYP"); 
     qtable_prop.setMultiConsumer(true);

     q_table = aq_sess.createQueueTable ("aq", "multi_qtab", qtable_prop);

     /* Create a new AQQueueProperty object: */
     queue_prop = new AQQueueProperty();
     queue = aq_sess.createQueue (q_table, "multi_queue", queue_prop);

}

/* Add subscribers to a queue */
public static void example(AQSession aq_sess) throws AQException
{
     AQQueue         queue;
     AQAgent         agent1;        
     AQAgent         agent2;        

     /* Get the queue object */
     queue = aq_sess.getQueue("AQ", "multi_queue");

     /* add a subscriber */
     agent1 = new AQAgent("subscriber1", "aq2.msg_queue2@london");
     queue.addSubscriber(agent1, null);

     /* add a subscriber with a rule */
     agent2 = new AQAgent("subscriber2", "aq2.msg_queue2@london");

     queue.addSubscriber(agent2, "priority < 2");
}

/* Add a subscriber with a rule */
public static void example(AQSession aq_sess) throws AQException
{
     AQQueue         queue;
     AQAgent         agent1;        

     /* Get the queue object */
     queue = aq_sess.getQueue("OE", "OE_bookedorders_que");

     /* add a subscriber */
     agent1 = new AQAgent("East_Shipping", "ES.ES_bookedorders_que");

     queue.addSubscriber(agent1, 
			 "tab.user_data.orderregion='EASTERN' OR " +
			 "(tab.user_data.ordertype='RUSH' AND " +
			 "tab.user_data.customer.country='USA')");
}