MySQL :: MySQL NDB Cluster API Developer Guide

Event Class Overview

Parent class

NdbDictionary

Child classes

None

Description

This class represents a database event in an NDB Cluster.

Methods

The following table lists the public methods of the Event class and the purpose or use of each method:

Table 2.14 Event class methods and descriptions

Name	Description
`Event()`	Class constructor
`~Event()`	Destructor
`addEventColumn()`	Adds a column on which events should be detected
`addEventColumns()`	Adds multiple columns on which events should be detected
`addTableEvent()`	Adds the type of event that should be detected
`getDurability()`	Gets the event's durability
`getEventColumn()`	Gets a column for which an event is defined
`getName()`	Gets the event's name
`getNoOfEventColumns()`	Gets the number of columns for which an event is defined
`getObjectId()`	Gets the event's object ID
`getObjectStatus()`	Gets the event's object status
`getObjectVersion()`	Gets the event's object version
`getReport()`	Gets the event's reporting options
`getTable()`	Gets the `Table` object on which the event is defined
`getTableEvent()`	Checks whether an event is to be detected
`getTableName()`	Gets the name of the table on which the event is defined
`mergeEvents()`	Sets the event's merge flag
`setDurability()`	Sets the event's durability
`setName()`	Sets the event's name
`setReport()`	The the event's reporting options
`setTable()`	Sets the `Table` object on which the event is defined

Improved Event API (NDB 7.4 and later). NDB 7.4 introduces an epoch-driven Event API that supercedes the earlier GCI-based model. The new version of the API also simplifies error detection and handling. These changes are realized in the NDB API by implementing a number of new methods for Ndb and NdbEventOperation, deprecating several other methods of both classes, and adding new type values to TableEvent.

Some of the new methods directly replace or stand in for deprecated methods, but not all of the deprecated methods map to new ones, some of which are entirely new. Old (deprecated) methods are shown in the first column of the following table, and new methods in the second column; old methods corresponding to new methods are shown in the same row.

Table 2.15 Deprecated and new Event API methods in the NDB API, NDB 7.4

Old Method	New Method
`NdbEventOperation::getEventType()`	`NdbEventOperation::getEventType2()`
`NdbEventOperation::getGCI()`	`NdbEventOperation::getEpoch`
`NdbEventOperation::getLatestGCI()`	`Ndb::getHighestQueuedEpoch()`
`NdbEventOperation::isOverrun()`	None; use `NdbEventOperation::getEventType2()`
`NdbEventOperation::hasError()`	None; use `NdbEventOperation::getEventType2()`
`NdbEventOperation::clearError()`	None
None	`NdbEventOperation::isEmptyEpoch()`
None	`NdbEventOperation::isErrorEpoch()`
`Ndb::pollEvents()`	`Ndb::pollEvents2()`
`Ndb::nextEvent()`	`Ndb::nextEvent2()`
`Ndb::getLatestGCI()`	`Ndb::getHighestQueuedEpoch()`
`Ndb::getGCIEventOperations()`	`Ndb::getNextEventOpInEpoch2()`
`Ndb::isConsistent()`	None
`Ndb::isConsistentGCI()`	None

Error handling using the new API is accomplished by checking the value returned from getEventType2(), and is no longer handled using the methods hasError() and clearError(), which are now deprecated and subject to removal in a future release of NDB Cluster. In support of this change, the range of possible TableEvent types has been expanded by those listed here:

TE_EMPTY: Empty epoch
TE_INCONSISTENT: Inconsistent epoch; missing data or overflow
TE_OUT_OF_MEMORY: Inconsistent data; event buffer out of memory or overflow

The result of these changes is that, in NDB 7.4 and later, you can check for errors while checking a table event's type, as shown here:

NdbDictionary::Event::TableEvent* error_type = 0;
NdbEventOperation* pOp = nextEvent2();

if (pOp->isErrorEpoch(error_type)
{
  switch (error_type)
  {
    case TE_INCONSISTENT :
      // Handle error/inconsistent epoch...
      break;

    case TE_OUT_OF_MEMORY :
      // Handle error/inconsistent data...
      break;

    //  ...
  }
}

For more information, see the detailed descriptions for the Ndb and NdbEventOperation methods shown in the table previously, as well as Event::TableEvent.

Types

These are the public types of the Event class:

Table 2.16 Event class types and descriptions

Name	Description
`TableEvent()`	Represents the type of a table event
`EventDurability()`	Specifies an event's scope, accessibility, and lifetime
`EventReport()`	Specifies the reporting option for a table event

Event::addEventColumn()

Description

This method is used to add a column on which events should be detected. The column may be indicated either by its ID or its name.

You must invoke Dictionary::createEvent() before any errors will be detected. See Dictionary::createEvent().

If you know several columns by name, you can enable event detection on all of them at one time by using addEventColumns(). See Event::addEventColumns().

Signatures

This method can be invoked in either of the following ways:

Identifying the event using its column ID:

void addEventColumn
    (
      unsigned attrId
    )

Identifying the column by name:

void addEventColumn
    (
      const char* columnName
    )

Parameters

This method takes a single argument, which may be either one of the following:

The column ID (attrId), which should be an integer greater than or equal to 0, and less than the value returned by getNoOfEventColumns().
The column's name (as a constant character pointer).

Return value

None.

Event::addEventColumns()

Description

This method is used to enable event detection on several columns at the same time. You must use the names of the columns.

As with addEventColumn(), you must invoke Dictionary::createEvent() before any errors will be detected. See Dictionary::createEvent().

Signature

void addEventColumns
    (
      int          n,
      const char** columnNames
    )

Parameters

This method requires the two arguments listed here:

The number of columns n (an integer).
The names of the columns columnNames—this must be passed as a pointer to a character pointer.

Return value

None.

Event::addTableEvent()

Description

This method is used to add types of events that should be detected.

Signature

void addTableEvent
    (
      const TableEvent te
    )

Parameters

This method requires a TableEvent value.

Return value

None.

Event Constructor

Description

The Event constructor creates a new instance with a given name, and optionally associated with a table.

You should keep in mind that the NDB API does not track allocated event objects, which means that the user must explicitly delete the Event thus created after it is no longer in use.

Signatures

It is possible to invoke this method in either of two ways, the first of these being by name only, as shown here:

Event
    (
      const char* name
    )

Alternatively, you can use the event name and an associated table, like this:

Event
    (
      const char*                  name,
      const NdbDictionary::Table& table
    )

Parameters

At a minimum, a name (as a constant character pointer) for the event is required. Optionally, an event may also be associated with a table; this argument, when present, is a reference to a Table object (see Section 2.3.27, “The Table Class”).

Return value

A new instance of Event.

Destructor. A destructor for this class is supplied as a virtual method which takes no arguments and whose return type is void.

Event::EventDurability

This section provides information about EventDurability, a type defined by the Event class.

Description

The values of this type are used to describe an event's lifetime or persistence as well as its scope.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.17 Event::EventDurability data type values and descriptions

Name	Description
`ED_UNDEFINED`	The event is undefined or of an unsupported type.
`ED_SESSION`	This event persists only for the duration of the current session, and is available only to the current application. It is deleted after the application disconnects or following a cluster restart. Important The value `ED_SESSION` is reserved for future use and is not yet supported in any NDB Cluster release.
`ED_TEMPORARY`	Any application may use the event, but it is deleted following a cluster restart. Important The value `ED_TEMPORARY` is reserved for future use and is not yet supported in any NDB Cluster release.
`ED_PERMANENT`	Any application may use the event, and it persists until deleted by an application—even following a cluster. restart Important The value `ED_PERMANENT` is reserved for future use and is not yet supported in any NDB Cluster release.

Event::EventReport

This section provides information about EventReport, a type defined by the Event class.

Description

The values of this type are used to specify reporting options for table events.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.18 Event::EventReport type values and descriptions

Name	Description
`ER_UPDATED`	Reporting of update events
`ER_ALL`	Reporting of all events, except for those not resulting in any updates to the inline parts of blob columns
`ER_SUBSCRIBE`	Reporting of subscription events
`ER_DDL`	Reporting of DDL events (see Event::setReport(), for more information)

Event::getDurability()

Description

This method gets the event's lifetime and scope (that is, its EventDurability).

Signature

EventDurability getDurability
    (
      void
    ) const

Parameters

None.

Return value

An EventDurability value.

Event::getEventColumn()

Description

This method is used to obtain a specific column from among those on which an event is defined.

Signature

const Column* getEventColumn
    (
      unsigned no
    ) const

Parameters

The number (no) of the column, as obtained using getNoOfColumns() (see Event::getNoOfEventColumns()).

Return value

A pointer to the Column corresponding to no.

Event::getName()

Description

This method obtains the name of the event.

Signature

const char* getName
    (
      void
    ) const

Parameters

None.

Return value

The name of the event, as a character pointer.

Event::getNoOfEventColumns()

Description

This method obtains the number of columns on which an event is defined.

Signature

int getNoOfEventColumns
    (
      void
    ) const

Parameters

None.

Return value

The number of columns (as an integer), or -1 in the case of an error.

Event::getObjectStatus()

Description

This method gets the object status of the event.

Signature

virtual Object::Status getObjectStatus
    (
      void
    ) const

Parameters

None.

Return value

The object status of the event. For possible values, see Object::Status.

Event::getObjectVersion()

Description

This method gets the event's object version (see NDB Schema Object Versions).

Signature

virtual int getObjectVersion
    (
      void
    ) const

Parameters

None.

Return value

The object version of the event, as an integer.

Event::getObjectId()

Description

This method retrieves an event's object ID.

Signature

virtual int getObjectId
    (
      void
    ) const

Parameters

None.

Return value

The object ID of the event, as an integer.

Event::getReport()

Description

This method is used to obtain the reporting option in force for this event.

Signature

EventReport getReport
    (
      void
    ) const

Parameters

None.

Return value

One of the reporting options specified in Event::EventReport.

Event::getTable()

Description

This method is used to find the table with which an event is associated. It returns a reference to the corresponding Table object. You may also obtain the name of the table directly using getTableName().

Signature

const NdbDictionary::Table* getTable
    (
      void
    ) const

Parameters

None.

Return value

The table with which the event is associated—if there is one—as a pointer to a Table object; otherwise, this method returns NULL. (See Section 2.3.27, “The Table Class”.)

Event::getTableEvent()

Description

This method is used to check whether a given table event will be detected.

Signature

bool getTableEvent
    (
      const TableEvent te
    ) const

Parameters

This method takes a single parameter, the table event's type—that is, a TableEvent value.

Return value

This method returns true if events of TableEvent type te will be detected. Otherwise, the return value is false.

Event::getTableName()

Description

This method obtains the name of the table with which an event is associated, and can serve as a convenient alternative to getTable(). (See Event::getTable().)

Signature

const char* getTableName
    (
      void
    ) const

Parameters

None.

Return value

The name of the table associated with this event, as a character pointer.

Event::mergeEvents()

Description

This method is used to set the merge events flag, which is false by default. Setting it to true implies that events are merged as follows:

For a given NdbEventOperation associated with this event, events on the same primary key within the same global checkpoint index (GCI) are merged into a single event.
A blob table event is created for each blob attribute, and blob events are handled as part of main table events.
Blob post/pre data from blob part events can be read via NdbBlob methods as a single value.

This flag is not inherited by NdbEventOperation, and must be set on NdbEventOperation explicitly.

Signature

void mergeEvents
    (
      bool flag
    )

Parameters

A Boolean flag value.

Return value

None.

Event::setDurability()

Description

This method sets an event's durability—that is, its lifetime and scope.

Signature

void setDurability(EventDurability ed)

Parameters

This method requires a single EventDurability value as a parameter.

Return value

None.

Event::setReport()

Description

This method is used to set a reporting option for an event. Possible option values may be found in Event::EventReport.

Reporting of DDL events

You must call setReport() using the EventReport value ER_DDL (added in the same NDB Cluster versions).

For example, to enable DDL event reporting on an Event object named myEvent, you must invoke this method as shown here:

myEvent.setReport(NdbDictionary::Event::ER_DDL);

Signature

void setReport
    (
      EventReport er
    )

Parameters

An EventReport option value.

Return value

None.

Event::setName()

Description

This method is used to set the name of an event. The name must be unique among all events visible from the current application (see Event::getDurability()).

You can also set the event's name when first creating it. See Event Constructor.

Signature

void setName
    (
      const char* name
    )

Parameters

The name to be given to the event (as a constant character pointer).

Return value

None.

Event::setTable()

Description

This method defines a table on which events are to be detected.

By default, event detection takes place on all columns in the table. Use addEventColumn() to override this behavior. For details, see Event::addEventColumn().

Signature

void setTable
    (
      const NdbDictionary::Table& table
    )

You can also use a pointer with this method, as shown here:

void setTable
    (
      const NdbDictionary::Table*; table
    )

When so used, this version of setTable() returns -1 if the table pointer is NULL.

Parameters

This method requires a single parameter, a reference or a pointer to the table (see Section 2.3.27, “The Table Class”) on which events are to be detected.

Return value

-1 if a null table pointer is used, otherwise null.

Event::TableEvent

This section describes TableEvent, a type defined by the Event class.

Description

TableEvent is used to classify the types of events that may be associated with tables in the NDB API.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.19 Event::TableEvent type values and descriptions

Name	Description
`TE_INSERT`	Insert event on a table
`TE_DELETE`	Delete event on a table
`TE_UPDATE`	Update event on a table
`TE_DROP`	Occurs when a table is dropped
`TE_ALTER`	Occurs when a table definition is changed
`TE_CREATE`	Occurs when a table is created
`TE_GCP_COMPLETE`	Occurs on the completion of a global checkpoint
`TE_CLUSTER_FAILURE`	Occurs on Cluster failures
`TE_STOP`	Occurs when an event operation is stopped
`TE_NODE_FAILURE`	Occurs when a Cluster node fails
`TE_SUBSCRIBE`	Occurs when a cluster node subscribes to an event
`TE_UNSUBSCRIBE`	Occurs when a cluster node unsubscribes from an event
`TE_EMPTY`	Empty epoch received from data nodes
`TE_INCONSISTENT`	Missing data or buffer overflow at data node
`TE_OUT_OF_MEMORY`	Overflow in event buffer
`TE_ALL`	Occurs when any event occurs on a table (not relevant when a specific event is received)

TE_EMPTY, TE_INCONSISTENT, and TE_OUT_OF_MEMORY were added in NDB 7.4.

2.3.5 The Event Class

Event Class Overview

Event::addEventColumn()

Event::addEventColumns()

Event::addTableEvent()

Event Constructor

Event::EventDurability

Event::EventReport

Event::getDurability()

Event::getEventColumn()

Event::getName()

Event::getNoOfEventColumns()

Event::getObjectStatus()

Event::getObjectVersion()

Event::getObjectId()

Event::getReport()

Event::getTable()

Event::getTableEvent()

Event::getTableName()

Event::mergeEvents()

Event::setDurability()

Event::setReport()

Event::setName()

Event::setTable()

Event::TableEvent