OTL 4.0, OTL subscriber interface

This class is Oracle 10gR2 (or higher) specific, and optional. It can be enabled by defining #define OTL_ORA_SUBSCRIBE. otl_subscriber uses the Oracle Database Change Notification Interface, which allows the user to get Change Notifications on database tables of interest. The class implements basic functions like subscribe / unsubscribe, plus pure virtual functions that need to be overriden in a derived class. The pure virtual functions are actually a callback mechanism for delivering change notifications back to the user. See also example 585 for more detail.

Potentially, the otl_subscriber class may throw the following OTL defined exception.

class otl_subscriber {
public:

General constructor. It accepts a pointer to an otl_connect object. When the constructor is called, the otl_connect object doesn't necessarily have to be connected to the database. It needs to be connected by the time of the first subscribe() call.

     otl_subscriber(otl_connect* adb);

Destructor. Closes all active subscriptions automatically.

virtual ~otl_subscriber();

Subscribe to Change Notifications / activate Change Notification Interface

     void subscribe(const char *name=0, // optional subscription name
                    int port=0, // Application listening TCP port number to receive
                                // subscription notifications (optional). When it's left
                                // as defualt, the OCI layer gets the next available port.
                    int timeout=1800 // Subscription expiration time, seconds (optional,
                                     // default value is 1800 sec, 0 means "never expires").
                                     // When subscription expires, OnDeRegistration() is called.
                   );

Unsubscribe / deactivate Change Notification Interface

     void unsubscribe();

Associate a table / view of interest with the current subscription. In other words, add a table / view name to the list of tables / views which we want to get change notifications on. There may be more than one table / view in the list

     void associate_table(const char *table_name);

Associate a query of interest with the current subscription. In other words, add a query to the list of queries which we want to get change notifications on. There may be more than one query in the list. This function is a more generic version of the associate_table() function. When the query gets executed, all the underlying objects of the query get identified. The query format should be as follows:

      SELECT :arg<int> FROM...the rest of the query...

:arg<int> is needed in order to postpone the execution of the query, when the query gets opened in an otl_stream inside the funcion:

      otl_stream s(1,stmt,*db);
      ...
   s<<0;
...

Here's the function signature:

void associate_query(const char *query_stmt);

protected:

// Pure virtual functions // callbacks to be implemented in a derived class

virtual void OnException(otl_exception& e) = 0;
      // "On otl_exception" callback. When OTL throws otl_exception,
      // this function is called.

virtual void OnDeRegistration(void) = 0;
      // "On deregistration" callback. This function gets called
      // when the current subscription expires. Inside this function,
      // repeated calls to subscribe(), associate_table(), associate_query()
      // are allowed.

// --- DB-wide events:
virtual void OnStartup(void) = 0;
      // "On Oracle Instance startup" callback. This function gets called
      // on the Oracle Instance startup

virtual void OnInstanceShutdown(void) = 0;
      // "On Oracle Instance shutdown" callback. This function gets called
      // when the Oracle Instance which the client
      // program is connected to shuts down.

virtual void OnAnyInstanceShutdown(void) = 0;
      // "On Any Oracle Instance shutdown" callback. This function gets called
      // when Any Oracle Instance in the RAC which the client
      // program is connected to shuts down.

// --- Table-wide events:
virtual void OnTableInvalidate(text *table_name) = 0;
       // "On table invalidate" callback. This function gets called
       // when the table gets invalidated.

virtual void OnTableAlter(text *table_name) = 0;
       // "On table alter" callback. This function gets called
       // when the table gets ALTERed.

virtual void OnTableDrop(text *table_name) = 0;
       // "On table drop" callback. This function gets called
       // when the table gets DROPped.

virtual void OnTableChange(text *table_name) = 0;
       // "On table change" callback. This function gets called
       // when the table gets changed: INSERT, UPDATE, DELETE. This
       // callback only informs of the fact that the table got
       // changed, but it doesn't specify which row(s) got changed.
       // In order to get the info on individual rows, see "Row events".

// --- Row events:
virtual void OnRowInsert(text *table_name, text *row_id ) = 0;
       // "On row insert" callback. This function gets called when a row
       // is inserted into the table. If a query was
       // associated with the current subscription that involves more than one
       // table, this callback will be invoked for each table of the query.
       // "row_id" is the ROWID of the inserted row.

virtual void OnRowUpdate(text *table_name, text *row_id ) = 0;
       // "On row update" callback. This function gets called when a table row
       // is updated. If a query was
       // associated with the current subscription that involves more than one
       // table, this callback will be invoked for each table of the query.
       // "row_id" is the ROWID of the updated row.

virtual void OnRowDelete(text *table_name, text *row_id ) = 0;
       // "On row delete" callback. This function gets called when a table row
       // is updated. If a query was
       // associated with the current subscription that involves more than one
       // table, this callback will be invoked for each table of the query.
       // "row_id" is the ROWID of the updated row.

public:

Check if the current subscription is active (online). This function is convenient to call from OnDeRegistration() in order to identify whether the subscription was expired by the client or by the server timeout.

bool is_online(void);

}; // end of otl_subscriber

Oracle user id that is used to connect to the database and get Change Notifications needs to have the CHANGE NOTIFICATION privilege given by the DBA, for example:

grant change notification to scott;

Active subscriptions can be viewed via the USER_CHANGE_NOTIFICATION_REGS system view by the current Oracle user:

    select * from USER_CHANGE_NOTIFICATION_REGS

When a subscription gets registered, the OCI layer opens a specified TCP/IP port, and spawns a new listener thread. Firewalls need to take the TCP/IP port into account.

Prev Next Contents Go Home

Permission to use, copy, modify and redistribute this document for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies.