Class of operations for getting change events from database. More...

#include <NdbEventOperation.hpp>

Inheritance diagram for NdbEventOperation:

Public Types
enum	State { EO_CREATED, EO_EXECUTING, EO_DROPPED, EO_ERROR }

Public Member Functions
State	getState ()
void	mergeEvents (bool flag)
int	execute ()
NdbRecAttr *	getValue (const char anAttrName, char aValue=0)
NdbRecAttr *	getPreValue (const char anAttrName, char aValue=0)
NdbBlob *	getBlobHandle (const char *anAttrName)
NdbBlob *	getPreBlobHandle (const char *anAttrName)
int	isOverrun () const
bool	isConsistent () const
NdbDictionary::Event::TableEvent	getEventType () const
bool	tableNameChanged () const
bool	tableFrmChanged () const
bool	tableFragmentationChanged () const
bool	tableRangeListChanged () const
Uint64	getGCI () const
Uint32	getAnyValue () const
Uint64	getLatestGCI () const
Uint64	getTransId () const
struct NdbError &	getNdbError () const
const NdbDictionary::Table *	getTable () const
const NdbDictionary::Event *	getEvent () const
const NdbRecAttr *	getFirstPkAttr () const
const NdbRecAttr *	getFirstPkPreAttr () const
const NdbRecAttr *	getFirstDataAttr () const
const NdbRecAttr *	getFirstDataPreAttr () const
void	setCustomData (void *data)
void *	getCustomData () const
void	clearError ()
int	hasError () const
int	getReqNodeId () const
int	getNdbdNodeId () const
void	print ()

Friends
class	NdbEventOperationImpl
class	NdbEventBuffer

Detailed Description

Class of operations for getting change events from database.

Brief description on how to work with events:

An event, represented by an NdbDictionary::Event, i created in the Database through NdbDictionary::Dictionary::createEvent() (note that this can be done by any application or thread and not necessarily by the "listener")
To listen to events, an NdbEventOperation object is instantiated by Ndb::createEventOperation()
execute() starts the event flow. Use Ndb::pollEvents() to wait for an event to occur. Use Ndb::nextEvent() to iterate through the events that have occured.
The instance is removed by Ndb::dropEventOperation()

For more info see: ndbapi_event.cpp

Known limitations:

Maximum number of active NdbEventOperations are now set at compile time. Today 100. This will become a configuration parameter later.
Maximum number of NdbEventOperations tied to same event are maximum 16 per process.

Known issues:

When several NdbEventOperation's are tied to the same event in the same process they will share the circular buffer. The BufferLength will then be the same for all and decided by the first NdbEventOperation instantiation. Just make sure to instantiate the "largest" one first.
Today all events INSERT/DELETE/UPDATE and all changed attributes are sent to the API, even if only specific attributes have been specified. These are however hidden from the user and only relevant data is shown after Ndb::nextEvent().
"False" exits from Ndb::pollEvents() may occur and thus the subsequent Ndb::nextEvent() will return NULL, since there was no available data. Just do Ndb::pollEvents() again.
Event code does not check table schema version. Make sure to drop events after table is dropped. Will be fixed in later versions.
If a node failure has occured not all events will be recieved anymore. Drop NdbEventOperation and Create again after nodes are up again. Will be fixed in later versions.

Test status:

Tests have been run on 1-node and 2-node systems

Useful API programs:

ndb_select_all -d sys 'NDB$EVENTS_0' shows contents in the system table containing created events.

Note: this is an inteface to viewing events that is subject to change

Definition at line 83 of file NdbEventOperation.hpp.

Member Enumeration Documentation

enum NdbEventOperation::State

State of the NdbEventOperation object

Enumerator:

EO_CREATED	Created but execute() not called.
EO_EXECUTING	execute() called
EO_DROPPED	Waiting to be deleted, Object unusable.
EO_ERROR	An error has occurred. Object unusable.

Definition at line 88 of file NdbEventOperation.hpp.

Member Function Documentation

int NdbEventOperation::execute ( )

Activates the NdbEventOperation to start receiving events. The changed attribute values may be retrieved after Ndb::nextEvent() has returned not NULL. The getValue() methods must be called prior to execute().

Returns: 0 if successful otherwise -1.

Reimplemented in NdbEventOperationImpl.

Definition at line 73 of file NdbEventOperation.cpp.

Here is the call graph for this function:

Uint32 NdbEventOperation::getAnyValue ( ) const

Retrieve the AnyValue of the latest retrieved event

Returns: AnyValue

Reimplemented in NdbEventOperationImpl.

Definition at line 129 of file NdbEventOperation.cpp.

Here is the call graph for this function:

NdbBlob * NdbEventOperation::getBlobHandle ( const char * anAttrName )

These methods replace getValue/getPreValue for blobs. Each method creates a blob handle NdbBlob. The handle supports only read operations. See NdbBlob.

Definition at line 61 of file NdbEventOperation.cpp.

NdbDictionary::Event::TableEvent NdbEventOperation::getEventType ( ) const

Query for occured event type.

Note: Only valid after Ndb::nextEvent() has been called and returned a not NULL value

Returns: type of event

Definition at line 147 of file NdbEventOperation.cpp.

Uint64 NdbEventOperation::getGCI ( ) const

Retrieve the GCI of the latest retrieved event

Returns: GCI number

Definition at line 123 of file NdbEventOperation.cpp.

Uint64 NdbEventOperation::getLatestGCI ( ) const

Retrieve the complete GCI in the cluster (not necessarily associated with an event)

Returns: GCI number

Definition at line 135 of file NdbEventOperation.cpp.

struct NdbError & NdbEventOperation::getNdbError ( ) const

read

Get the latest error

Returns: Error object.

Reimplemented in NdbEventOperationImpl.

Definition at line 225 of file NdbEventOperation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

NdbRecAttr * NdbEventOperation::getPreValue	(	const char *	anAttrName,
		char *	aValue = `0`
	)

See getValue().

Definition at line 55 of file NdbEventOperation.cpp.

NdbEventOperation::State NdbEventOperation::getState ( )

Retrieve current state of the NdbEventOperation object

Reimplemented in NdbEventOperationImpl.

Definition at line 38 of file NdbEventOperation.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

const NdbDictionary::Table * NdbEventOperation::getTable ( ) const

these are subject to change at any time

Definition at line 161 of file NdbEventOperation.cpp.

Uint64 NdbEventOperation::getTransId ( ) const

Retrieve the TransId of the latest retrieved event

Only valid for data events. If the kernel does not support transaction ids with events, the max Uint64 value is returned.

Returns: TransId

Reimplemented in NdbEventOperationImpl.

Definition at line 141 of file NdbEventOperation.cpp.

Here is the call graph for this function:

NdbRecAttr * NdbEventOperation::getValue	(	const char *	anAttrName,
		char *	aValue = `0`
	)

Defines a retrieval operation of an attribute value. The NDB API allocate memory for the NdbRecAttr object that will hold the returned attribute value.

Note: Note that it is the applications responsibility to allocate enough memory for aValue (if non-NULL). The buffer aValue supplied by the application must be aligned appropriately. The buffer is used directly (avoiding a copy penalty) only if it is aligned on a 4-byte boundary and the attribute size in bytes (i.e. NdbRecAttr::attrSize() times NdbRecAttr::arraySize() is a multiple of 4).; There are two versions, getValue() and getPreValue() for retrieving the current and previous value repectively.; This method does not fetch the attribute value from the database! The NdbRecAttr object returned by this method is not readable/printable before the execute() has been made and Ndb::nextEvent() has returned not NULL. If a specific attribute has not changed the corresponding NdbRecAttr will be in state UNDEFINED. This is checked by NdbRecAttr::isNULL() which then returns -1.

Parameters

anAttrName	Attribute name
aValue	If this is non-NULL, then the attribute value will be returned in this parameter. If NULL, then the attribute value will only be stored in the returned NdbRecAttr object.