Posting for Subscriber Notification

Figure 11-16 Use Case Diagram: Posting for Subscriber Notification

Text description of the illustration adq11qop9.gif

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

Purpose

To post to a list of anonymous subscriptions so clients registered for the subscription get notifications.

Usage Notes

Several subscriptions can be posted to at one time. Posting to a subscription involves identifying the subscription name and the payload, if desired. It is possible for no payload to be associated with this call. This call provides a best-effort guarantee. A notification goes to registered clients at most once.

This call is primarily used for lightweight notification and is useful in the case of several system events. If an application needs more rigid guarantees, it can use AQ functionality by enqueuing to a queue.

When using OCI, the user must specify a subscription handle at registration time with the namespace attribute set to OCI_SUBSCR_NAMESPACE_ANONYMOUS.

When using PL/SQL, the namespace attribute in aq$_post_info must be set to DBMS_AQ.NAMESPACE_ANONYMOUS.

Related functions: OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(), OCISubscriptionRegister(), OCISubscriptionUnRegister(), dbms_aq.register, dbms_aq.unregister.

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_AQ Package): POST procedure.

• C (OCI): Oracle Call Interface Programmer's Guide OCI Programming Advanced Topics, Publish-Subscribe Notification

• Visual Basic (OO4O) (Oracle Objects for OLE (OO4O) Online Help): Not supported.

• Java (JDBC): Not supported.

Examples

See Chapter 3, "AQ Programmatic Environments" for a list of available functions in each programmatic environment.

PL/SQL (DBMS_AQ Package): Post of Object-Type Messages

-- Register for notification
DECLARE

  reginfo             sys.aq$_reg_info;
  reginfolist         sys.aq$_reg_info_list;

BEGIN
  -- Register for anonymous subscription PUBSUB1.ANONSTR, consumer_name ADMIN
  -- The PL/SQL callback pubsub1.mycallbk will be invoked 
  -- when a notification is received
  reginfo := sys.aq$_reg_info('PUBSUB1.ANONSTR:ADMIN',
			      DBMS_AQ.NAMESPACE_ANONYMOUS,
      'plsql://PUBSUB1.mycallbk', HEXTORAW('FF'));

  reginfolist := sys.aq$_reg_info_list(reginfo);

  sys.dbms_aq.register(reginfolist, 1);

  commit;
END;
/

-- Post to an anonymous subscription
DECLARE

  postinfo            sys.aq$_post_info;
  postinfolist        sys.aq$_post_info_list;

BEGIN

  -- Post to the anonymous subscription PUBSUB1.ANONSTR, consumer_name ADMIN
  postinfo := sys.aq$_post_info('PUBSUB1.ANONSTR:ADMIN',0,HEXTORAW('FF'));
  postinfolist := sys.aq$_post_info_list(postinfo);

  sys.dbms_aq.post(postinfolist, 1);

  commit;

END;
/