Documentation Home
MySQL NDB Cluster API Developer Guide
Related Documentation Download this Manual
PDF (US Ltr) - 3.6Mb
PDF (A4) - 3.6Mb


2.3.5 The Event Class

This section provides information about the Event class.

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.


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.