Adding a Subscriber

Figure 9-20 Use Case Diagram: Adding a Subscriber

Text description of the illustration adq09qad16.gif

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.

• When a queue, queue table, or subscriber is created and if GLOBAL_TOPIC_ENABLED = TRUE, a corresponding LDAP entry is also created.

• Specify the name of the transformation to be applied during dequeue or propagation. The transformation must be created using the DBMS_TRANSFORM package. (See theOracle9i Supplied PL/SQL Packages and Types Reference for more information.)

• For queues that contain payloads with XMLType attributes, you can specify rules that contain operators such as XMLType.existsNode() and XMLType.extract().

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): Oracle9i Supplied PL/SQL Packages and Types Reference DBMS_AQADM, ADD_SUBSCRIBER procedure

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

• Java (JDBC): Oracle9i 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): Adding Subscriber

• VB (OO4O): Example not provided.

• Java (JDBC): Adding a Subscriber

PL/SQL (DBMS_AQADM): Adding 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; 

Add a Subscriber and Specify a Transformation

/* Add a subscriber with a rule and specify a transformation */ 
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, 
      transformation        => 'AQ.msg_map');
/* Where the transformation was created as */ 
EXECUTE DBMS_TRANSFORM.CREATE_TRANSFORMATION
 ( schema => 'AQ',
   name => 'msg_map',
   from_schema => 'AQ',
   from_type => 'purchase_order1',
   to_schema => 'AQ',
   to_type => 'purchase_order2',
   transformation => 'AQ.transform_PO(source.user_data)');
END; 

PL/SQL (DBMS_AQADM): Adding a 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; 

/* Add a rule-based subscriber for Overseas Shipping */
DECLARE 
  subscriber     aq$_agent; 
BEGIN 
  subscriber := aq$_agent('Overseas_DHL', null, null); 

  dbms_aqadm.add_subscriber( 
        queue_name     => 'OS.OS_bookedorders_que', 
        subscriber     => subscriber, 
        rule           => 'tab.user_data.xdata.extract(''/ORDER_
TYP/ORDERTYPE/text()'').getStringVal()=''RUSH''');

END; 

Java (JDBC): Adding 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')");
}