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 overridden 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:

Function

Description

otl_subscriber(otl_connect* adb);

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.

virtual ~otl_subscriber();

Destructor. Closes all active subscriptions automatically.

void subscribe(...);

Parameter	Description
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 default, 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.
const char* ipaddr=0	Optional IP address. This parameter is only available under #define OTL_ORA11G_R2, and OTL_ORA12C. Note: This parameter seems to be mandatory at least for Oracle 11.2.x . A bug was reported against OCI 11.2.0.4 that when the IP address is not specified, the feature does not work.

Subscribes to Change Notifications / activate Change Notification Interface

void unsubscribe();

Unsubscribes / deactivates Change Notification Interface

void associate_table
(const char *table_name);

Associates 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_query(const char *query_stmt);

Associates a query of interest with the current subscription. In other words, adds 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 function:

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

bool is_online(void);

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

protected:

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

Function	Description
virtual void OnException (OTL_CONST_EXCEPTION otl_exception& e) = 0;	"On otl_exception" callback. When OTL throws otl_exception, this function is called. OTL_CONST_EXCEPTION is defined as "const" under #define OTL_ANSI_CPP. Otherwise, it is empty ("").
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.
virtual void OnStartup(void) = 0;	DB-wide event. "On Oracle Instance startup" callback. This function gets called on the Oracle Instance startup
virtual void OnInstanceShutdown (void) = 0;	DB-wide event. "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;	DB-wide event. "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.
virtual void OnTableInvalidate (text *table_name) = 0;	Table-wide event. "On table invalidate" callback. This function gets called when the table gets invalidated.
virtual void OnTableAlter(text *table_name, bool all_rows=false) = 0;	Table-wide event. "On table alter" callback. This function gets called when the table gets ALTERed. If all_rows is true then the whole table has been affected
virtual void OnTableDrop (text *table_name, bool all_rows=false) = 0;	Table-wide event. "On table drop" callback. This function gets called when the table gets DROPped. If all_rows is true then the whole table has been affected
virtual void OnTableChange (text *table_name, bool all_rows=false) = 0;	Table-wide event. "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". If all_rows is true then the whole table has been affected.
virtual void OnRowInsert (text table_name, text row_id ) = 0;	Row event. "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;	Row event. "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;	Row event. "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.

}; // 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. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.