2.3.6 The Event Class

2.3.6.1 Event Types
2.3.6.2 Event Methods

Abstract

This section discusses the Event class, its methods and defined types.

Parent class.  NdbDictionary

Child classes.  None

Description.  This class represents a database event in a MySQL Cluster.

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

MethodPurpose / Use
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 (MySQL Cluster NDB 7.4.3 and later).  MySQL Cluster NDB 7.4.3 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.

Old methodNew 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
NoneNdbEventOperation::isEmptyEpoch()
NoneNdbEventOperation::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 MySQL Cluster. In support of this change, the range of possible TableEvent types has been expanded by those listed here:

The result of these changes is that, in MySQL Cluster NDB 7.4.3 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 Section 2.3.6.1.1, “The Event::TableEvent Type”.

For detailed descriptions, signatures, and examples of use for each of these methods, see Section 2.3.6.2, “Event Methods”.

Types.  These are the public types of the Event class:

TypePurpose / Use
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

For a discussion of each of these types, along with its possible values, see Section 2.3.6.1, “Event Types”.

Class diagram.  This diagram shows all the available methods and enumerated types of the Event class:

Figure 2.5 NdbDictionary::Object::Event

Public methods and enumerated types of the Event class.