NdbEventOperation Class Reference

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

#include <NdbEventOperation.hpp>

List of all members.

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
const bool	tableNameChanged () const
const bool	tableFrmChanged () const
const bool	tableFragmentationChanged () const
const bool	tableRangeListChanged () const
Uint64	getGCI () const
Uint32	getAnyValue () const
Uint64	getLatestGCI () const
struct NdbError &	getNdbError () const
Private Member Functions
	NdbEventOperation (Ndb *theNdb, const char *eventName)
	~NdbEventOperation ()
	NdbEventOperation (NdbEventOperationImpl &impl)
	NdbEventOperation (const NdbEventOperation &)
NdbEventOperation &	operator= (const NdbEventOperation &)
Private Attributes
class NdbEventOperationImpl &	m_impl

---

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

---

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.

---

Constructor & Destructor Documentation

NdbEventOperation::NdbEventOperation	(	Ndb *	theNdb,
		const char *	eventName
	)			[private]

NdbEventOperation::~NdbEventOperation

(

)

[private]

NdbEventOperation::NdbEventOperation

(

NdbEventOperationImpl &

impl

)

[private]

NdbEventOperation::NdbEventOperation

(

const NdbEventOperation &

)

[private]

---

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.

Uint32 NdbEventOperation::getAnyValue

(

)

const

Retrieve the AnyValue of the latest retrieved event

Returns:

AnyValue

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.

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

Uint64 NdbEventOperation::getGCI

(

)

const

Retrieve the GCI of the latest retrieved event

Returns:

GCI number

Uint64 NdbEventOperation::getLatestGCI

(

)

const

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

Returns:

GCI number

struct NdbError& NdbEventOperation::getNdbError

(

)

const [read]

Get the latest error

Returns:

Error object.

NdbBlob* NdbEventOperation::getPreBlobHandle

(

const char *

anAttrName

)

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

See getValue().

State NdbEventOperation::getState

(

)

Retrieve current state of the NdbEventOperation object

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.

Returns:

An NdbRecAttr object to hold the value of the attribute, or a NULL pointer (indicating error).

bool NdbEventOperation::isConsistent

(

)

const

In the current implementation a nodefailiure may cause loss of events, in which case isConsistent() will return false

int NdbEventOperation::isOverrun

(

)

const

void NdbEventOperation::mergeEvents

(

bool

flag

)

See NdbDictionary::Event. Default is false.

NdbEventOperation& NdbEventOperation::operator=

(

const NdbEventOperation &

)

[private]

const bool NdbEventOperation::tableFragmentationChanged

(

)

const

Check if table fragmentation has changed, for event TE_ALTER

const bool NdbEventOperation::tableFrmChanged

(

)

const

Check if table frm has changed, for event TE_ALTER

const bool NdbEventOperation::tableNameChanged

(

)

const

Check if table name has changed, for event TE_ALTER

const bool NdbEventOperation::tableRangeListChanged

(

)

const

Check if table range partition list name has changed, for event TE_ALTER

---

Member Data Documentation

class NdbEventOperationImpl& NdbEventOperation::m_impl [private]

---

The documentation for this class was generated from the following file:

• include/ndbapi/NdbEventOperation.hpp