MySQL NDB Cluster API Developer Guide
This section provides information about the Event
class.
None
This class represents a database event in an NDB Cluster.
The following table lists the public methods of the
Event
class and the purpose or use of
each method:
Table 2.13 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.3 and later).
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.
Table 2.14 Deprecated and new Event API methods in the NDB API, NDB 7.4.3
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.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
Event::TableEvent.
These are the public types of the Event
class:
Table 2.15 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 |
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().
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
)
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).
None.
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().
void addEventColumns ( intn
, const char**columnNames
)
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.
None.
This method is used to add types of events that should be detected.
void addTableEvent
(
const TableEvent te
)
This method requires a
TableEvent
value.
None.
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.
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
)
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”).
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
.
This section provides information about
EventDurability
, a type defined by the
Event
class.
The values of this type are used to describe an event's lifetime or persistence as well as its scope.
Possible values are shown, along with descriptions, in the following table:
Table 2.16 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_TEMPORARY |
Any application may use the event, but it is deleted following a cluster
restart. Important
The value |
ED_PERMANENT |
Any application may use the event, and it persists until deleted by an
application—even following a cluster. restart Important
The value |
This section provides information about
EventReport
, a type defined by the
Event
class.
The values of this type are used to specify reporting options for table events.
Possible values are shown, along with descriptions, in the following table:
Table 2.17 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) |
This method gets the event's lifetime and scope (that
is, its
EventDurability
).
EventDurability getDurability ( void ) const
None.
An EventDurability
value.
This method is used to obtain a specific column from among those on which an event is defined.
const Column* getEventColumn
(
unsigned no
) const
The number (no
) of the column, as
obtained using getNoOfColumns()
(see
Event::getNoOfEventColumns()).
A pointer to the Column
corresponding to no
.
This method obtains the name of the event.
const char* getName ( void ) const
None.
The name of the event, as a character pointer.
This method obtains the number of columns on which an event is defined.
int getNoOfEventColumns ( void ) const
None.
The number of columns (as an integer), or
-1
in the case of an error.
This method gets the object status of the event.
virtual Object::Status getObjectStatus ( void ) const
None.
The object status of the event. For possible values, see Object::Status.
This method gets the event's object version (see NDB Schema Object Versions).
virtual int getObjectVersion ( void ) const
None.
The object version of the event, as an integer.
This method retrieves an event's object ID.
virtual int getObjectId ( void ) const
None.
The object ID of the event, as an integer.
This method is used to obtain the reporting option in force for this event.
EventReport getReport ( void ) const
None.
One of the reporting options specified in Event::EventReport.
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()
.
const NdbDictionary::Table* getTable ( void ) const
None.
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”.)
This method is used to check whether a given table event will be detected.
bool getTableEvent
(
const TableEvent te
) const
This method takes a single parameter, the table event's
type—that is, a
TableEvent
value.
This method returns true
if events of
TableEvent
type
te
will be detected. Otherwise,
the return value is false
.
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().)
const char* getTableName ( void ) const
None.
The name of the table associated with this event, as a character pointer.
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.
void mergeEvents
(
bool flag
)
A Boolean flag
value.
None.
This method sets an event's durability—that is, its lifetime and scope.
void setDurability(EventDurability ed
)
This method requires a single
EventDurability
value
as a parameter.
None.
This method is used to set a reporting option for an event. Possible option values may be found in Event::EventReport.
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);
void setReport
(
EventReport er
)
An EventReport
option
value.
None.
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.
void setName
(
const char* name
)
The name
to be given to the event
(as a constant character pointer).
None.
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().
void setTable
(
const NdbDictionary::Table& table
)
NDB 7.3.3 and later NDB Cluster releases support the use of 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
.
(Bug #16329082)
This method requires a single parameter, a reference to the table (see Section 2.3.27, “The Table Class”) on which events are to be detected. NDB 7.3.3 and later: A reference or a pointer to the table can be used.
None. NDB 7.3.3 and later: -1, if a null table pointer is used.
This section describes TableEvent
, a type
defined by the Event
class.
TableEvent
is used to classify the types
of events that may be associated with tables in the NDB API.
Possible values are shown, along with descriptions, in the following table:
Table 2.18 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.3.