The Cassandra class definition. More...

Inheritance diagram for QtCassandra::QCassandra:

Collaboration diagram for QtCassandra::QCassandra:

Public Member Functions
	QCassandra ()
	Initialize the QCassandra object.
virtual	~QCassandra ()
	Cleanup the Cassandra object.
const QString &	clusterName () const
	Get the name of the Cassandra cluster.
bool	connect (const QString &host="localhost", int port=9160)
	Connect to a Cassandra Cluster.
QSharedPointer< QCassandraContext >	context (const QString &context_name)
	Retrieve a context by name.
const QCassandraContexts &	contexts () const
	Get the map of contexts.
consistency_level_t	defaultConsistencyLevel () const
	Retrieve the current default consistency level.
void	disconnect ()
	Break the connection to Cassandra.
void	dropContext (const QString &context_name)
	Drop a context from the database and memory.
QSharedPointer< QCassandraContext >	findContext (const QString &context_name) const
	Search for a context.
bool	isConnected () const
	Check whether the object is connected to the server.
QCassandraContext &	operator[] (const QString &context_name)
	Retrieve a context reference.
const QCassandraContext &	operator[] (const QString &context_name) const
	Retrieve a constant context reference.
const QString &	protocolVersion () const
	Get the version of the cluster protocol.
void	setDefaultConsistencyLevel (consistency_level_t default_consistency_level)
	Change the current default consistency level.
Static Public Member Functions
static int64_t	timeofday ()
	Get the time of day.
static const char *	version ()
	Retrieve the library version number in the form of a string.
static int	versionMajor ()
	Retrieve the major version number.
static int	versionMinor ()
	Retrieve the minor version number.
static int	versionPatch ()
	Retrieve the patch version number.
Private Member Functions
void	clearCurrentContextIf (const QCassandraContext &c)
	Internal function that clears the current context as required.
QCassandraPrivate *	getPrivate ()
	Internal function to give others access to the Cassandra server.
void	setCurrentContext (QSharedPointer< QCassandraContext > c)
	Make the specified context the current context.
Private Attributes
QString	f_cluster_name
	The name of the cluster we're connected to.
QCassandraContexts	f_contexts
	The map of contexts defined in memory.
controlled_vars::zbool_t	f_contexts_read
	Whether the map of contexts were read from Cassandra.
QSharedPointer< QCassandraContext >	f_current_context
	A pointer to the current context.
consistency_level_t	f_default_consistency_level
	The consistency level used by default.
std::auto_ptr< QCassandraPrivate >	f_private
	A pointer to a QCassandraPrivate object.
QString	f_protocol_version
	The version of the protocol we're connected to.
Friends
class	QCassandraContext
class	QCassandraPrivate

Detailed Description

This class is used to handle a Cassandra connection and read/write data to and from a Cassandra database.

This is the first object you want to create as all things come out of it.

Definition at line 55 of file QCassandra.h.in.

Constructor & Destructor Documentation

QtCassandra::QCassandra::QCassandra ( )

This function makes the QCassandra object ready.

Mainly, it allocates a QCassandraPrivate object that handles all the necessary data transfers between the QCassandra object and the Cassandra server.

Next you are expected to connect to the server and eventually change the default consistency server.

See also:: connect(); setDefaultConsistencyLevel()

Definition at line 609 of file QCassandra.cpp.

QtCassandra::QCassandra::~QCassandra ( ) [virtual]

This function cleans up the QCassandra object.

This includes disconnecting from the Cassandra server and release memory resources tight to this object.

Definition at line 630 of file QCassandra.cpp.

Member Function Documentation

void QtCassandra::QCassandra::clearCurrentContextIf ( const QCassandraContext & c ) [private]

Whenever a context is being dropped, it cannot remain the current context. This function is used to remove it from being current.

Parameters:

[in] c The context that is about to be dropped.

Definition at line 857 of file QCassandra.cpp.

References f_current_context.

Referenced by QtCassandra::QCassandraPrivate::dropContext().

const QString & QtCassandra::QCassandra::clusterName ( ) const

This function determines the name of the cluster. The name cannot change unless you renew the connection to a different Cassandra cluster.

The QCassandra object remembers the name. Calling this function more than once is very fast.

You must be connected for this function to work.

Note:: The f_cluster_name variable will be set even though the function is a const. This is a cache so it makes sense. The variable is NOT marked mutable because this is the only case where it happens.

Returns:: The name of the cluster.

Definition at line 731 of file QCassandra.cpp.

References f_cluster_name, and f_private.

bool QtCassandra::QCassandra::connect	(	const QString &	host = `"localhost"`,
		int	port = `9160`
	)

This function connects to a Cassandra Cluster. Which cluster is determined by the host and port parameters.

One cluster may include many database systems (i.e. keyspaces.) Each database system (keyspace) has a set of parameters defining its duplication mechanism among other things. Before working with a database system, one must call the the set_context() function.

The function first disconnects the existing connection when there is one.

Many other functions require you to call this connect() function first. You are likely to get a runtime exception if you don't.

Note that the previous connection is lost whether or not the new one succeeds.

Parameters:

[in]	host	The host, defaults to "localhost" (an IP address, computer hostname, domain name, etc.)
[in]	port	The connection port, defaults to 9160

Returns:: true if the connection succeeds, false otherwise

Definition at line 673 of file QCassandra.cpp.

References disconnect(), and f_private.

QSharedPointer< QCassandraContext > QtCassandra::QCassandra::context ( const QString & context_name )

This function searches for a context by name. If the context does not exist yet, then it gets created in memory.

You must be connected for this function to work.

The context is not created in the Cassandra database. If it doesn't exist in Cassandra, it is only created in memory until you call the create() function. This gives you an opportunity to setup the context including its tables.

The following shows you an example:

    context = cassandra.context(context_name);
    context->setStrategyClass("org.apache.cassandra.locator.SimpleStrategy");
    context->setReplicationFactor(1);
    context->create();

Note that if you do not know whether the context exists, use the findContext() function first, then check whether the ontext was found.

Parameters:

[in] context_name The name of the context to search.

Returns:: A shared pointer to a cassandra context.

Definition at line 795 of file QCassandra.cpp.

References contexts(), f_contexts, and QCassandraContext.

Referenced by QtCassandra::QCassandraPrivate::contexts(), dropContext(), QtCassandra::QCassandraContext::makeCurrent(), and operator[]().

const QCassandraContexts & QtCassandra::QCassandra::contexts ( ) const

This function returns the map of contexts (keyspaces) help in this Cassandra cluster.

The cluster may include any number of contexts also it is wise to limit yourself to a relatively small number of contexts since it is loaded each time you connect to the database.

Note that the function returns a reference to the internal map of contexts. It is wise to stop using it if you call a function that may change the map (createContext(), dropContext(), etc.)

You must be connected for this function to work.

Returns:: A reference to the internal map of contexts.

Definition at line 881 of file QCassandra.cpp.

References f_contexts, f_contexts_read, and f_private.

Referenced by context().

consistency_level_t QtCassandra::QCassandra::defaultConsistencyLevel ( ) const

This function returns the current default consistency level used by most of the server functions. You may change the default from the default Cassandra value of ONE. In many cases, it is recommended that you use QUORUM.

Different predicate and the value object have their own consistency levels. If those are set to DEFAULT, then this very value is used instead.

Returns:: The current default consistency level.

Definition at line 1002 of file QCassandra.cpp.

References f_default_consistency_level.

Referenced by QtCassandra::QCassandraPrivate::getCellCount(), QtCassandra::QCassandraPrivate::getColumnSlice(), QtCassandra::QCassandraPrivate::getRowSlices(), QtCassandra::QCassandraPrivate::getValue(), QtCassandra::QCassandraPrivate::insertValue(), and QtCassandra::QCassandraPrivate::remove().

void QtCassandra::QCassandra::disconnect ( )

This function breaks the connection to Cassandra.

This function has the side effect of clearing the cluster name, protocol version, and current context.

Definition at line 689 of file QCassandra.cpp.

References f_cluster_name, f_contexts, f_current_context, f_private, and f_protocol_version.

Referenced by connect().

void QtCassandra::QCassandra::dropContext ( const QString & context_name )

Use this function when you want to completely drop a context from the Cassandra system and from memory. After this call the context, its tables, their rows, and cells are all marked as dead whether you still have shared pointers on them or not.

Parameters:

[in] context_name The name of the context to drop.

Definition at line 975 of file QCassandra.cpp.

References context(), and f_contexts.

QSharedPointer< QCassandraContext > QtCassandra::QCassandra::findContext ( const QString & context_name ) const

This function searches for a context. If it exists, its shared pointer is returned. Otherwise, it returns a NULL pointer (i.e. the QSharedPointer::isNull() function returns true.)

Parameters:

[in] context_name The name of the context to retrieve.

Returns:: A shared pointer to the context.

Definition at line 900 of file QCassandra.cpp.

References f_contexts.

Referenced by operator[]().

QCassandraPrivate * QtCassandra::QCassandra::getPrivate ( ) [private]

This function internally gives other objects a way to access the private definitions.

For example, the QCassandraContext uses this function to call functions such as createContext().

Returns:: A bare pointer to the QCassandraPrivate object attached to this QCassandra instance.

Definition at line 644 of file QCassandra.cpp.

References f_private.

bool QtCassandra::QCassandra::isConnected ( ) const

This function returns true when this object is connected to the backend Cassandra server.

The function is fast and does not actually verify that the TCP/IP connection is still up.

Returns:: true if connect() was called and succeeded.

Definition at line 708 of file QCassandra.cpp.

References f_private.

QCassandraContext & QtCassandra::QCassandra::operator[] ( const QString & context_name )

The array operator searches for a context by name and returns its reference. This is useful to access data with array like syntax as in:

 cluster[context_name][table_name][column_name] = value;

Exceptions:

std::runtime_error If the context doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.

Parameters:

[in] context_name The name of the context to retrieve.

Returns:: A reference to the named context.

Definition at line 928 of file QCassandra.cpp.

References context(), and findContext().

const QCassandraContext & QtCassandra::QCassandra::operator[] ( const QString & context_name ) const

This array operator is the same as the other one, just this one deals with constant contexts. It can be used to retrieve values from the Cassandra cluster you're connected to:

 value = cluster[context_name][table_name][column_name];

Exceptions:

std::runtime_error If the context doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.

Parameters:

[in] context_name The name of the context to retrieve.

Returns:: A constant reference to the named context.

Definition at line 956 of file QCassandra.cpp.

References context(), and findContext().

const QString & QtCassandra::QCassandra::protocolVersion ( ) const

This function determines the version of the protocol. The version cannot change unless you renew the connection to a different Cassandra cluster.

The QCassandra object remembers the version. Calling this function more than once is very fast.

You must be connected for this function to work.

Note:: The f_protocol_version variable will be set even though the function is a const. This is a cache so it makes sense. The variable is NOT marked mutable because this is the only case where it happens.

Returns:: The version of the protocol.

Definition at line 758 of file QCassandra.cpp.

References f_private, and f_protocol_version.

void QtCassandra::QCassandra::setCurrentContext ( QSharedPointer< QCassandraContext > c ) [private]

This function assigns the specified context as the current context of the Cassandra server.

The Cassandra servers work with keyspaces. One keyspace is similar to a database. This defines what we call a context. The setCurrentContext() function defines the active context.

If the QCassandra object is not yet connected, the context is saved as the current context of the QCassandra object, but it gets lost once you connect.

The only way to make a context not the current one is by setting another context as the current one.

You must be connected for this function to work.

Note:: It is wiser to create multiple QCassandra objects than to swap contexts all the time.

Parameters:

[in] c The context to set as current.

See also:: currentContext(); QCassandraContext::makeCurrent()

Definition at line 839 of file QCassandra.cpp.

References f_current_context, and f_private.

Referenced by QtCassandra::QCassandraContext::makeCurrent().

void QtCassandra::QCassandra::setDefaultConsistencyLevel ( consistency_level_t default_consistency_level )

This function changes the current default consistency level used by most of the server functions. In many cases, it is recommended that you use QUORUM, but it very much depends on your application and node setup.

Different predicate and the value object have their own consistency levels. If those are set to DEFAULT (their default,) then this very value is used instead.

Parameters:

[in] default_consistency_level The new default consistency level.

Definition at line 1020 of file QCassandra.cpp.

References QtCassandra::CONSISTENCY_LEVEL_ALL, QtCassandra::CONSISTENCY_LEVEL_ANY, QtCassandra::CONSISTENCY_LEVEL_EACH_QUORUM, QtCassandra::CONSISTENCY_LEVEL_LOCAL_QUORUM, QtCassandra::CONSISTENCY_LEVEL_ONE, QtCassandra::CONSISTENCY_LEVEL_QUORUM, QtCassandra::CONSISTENCY_LEVEL_THREE, QtCassandra::CONSISTENCY_LEVEL_TWO, and f_default_consistency_level.

int64_t QtCassandra::QCassandra::timeofday ( ) [static]

This function returns the time of day in micro seconds. It is a static function since there is no need for the this pointer in this helper function.

Returns:: The time of day in microseconds.

Definition at line 1091 of file QCassandra.cpp.

Referenced by QtCassandra::QCassandraTable::dropRow(), and QtCassandra::QCassandraPrivate::insertValue().

const char * QtCassandra::QCassandra::version ( ) [static]

This function dynamically returns the library version as a string. This string includes all 3 parts of the version number separated by period (.) characters.

Returns:: The patch version number.

Definition at line 1078 of file QCassandra.cpp.

References QtCassandra::QT_CASSANDRA_LIBRARY_VERSION_STRING.

int QtCassandra::QCassandra::versionMajor ( ) [static]

This function dynamically returns the library major version.

Returns:: The major version number.

Definition at line 1043 of file QCassandra.cpp.

References QtCassandra::QT_CASSANDRA_LIBRARY_VERSION_MAJOR.

int QtCassandra::QCassandra::versionMinor ( ) [static]

This function dynamically returns the library minor version.

Returns:: The minor version number.

Definition at line 1054 of file QCassandra.cpp.

References QtCassandra::QT_CASSANDRA_LIBRARY_VERSION_MINOR.

int QtCassandra::QCassandra::versionPatch ( ) [static]

This function dynamically returns the library patch version.

Returns:: The patch version number.

Definition at line 1065 of file QCassandra.cpp.

References QtCassandra::QT_CASSANDRA_LIBRARY_VERSION_PATCH.

Friends And Related Function Documentation

friend class QCassandraContext [friend]

Definition at line 97 of file QCassandra.h.in.

Referenced by context().

friend class QCassandraPrivate [friend]

Definition at line 96 of file QCassandra.h.in.

Member Data Documentation

QtCassandra::QCassandra::f_cluster_name [private]

This variable holds the name of the cluster the QCassandra object is connected to. This variable caches the cluster name so we don't have to query the cluster about its name more than once.

Definition at line 103 of file QCassandra.h.in.

Referenced by clusterName(), and disconnect().

QtCassandra::QCassandra::f_contexts [private]

This variable holds the list of contexts defined in memory. Whenever you try to access a context the system reads the cluster description (once) and return the corresponding Cassandra database context.

It is possible to create a memory context (i.e. get a context that doesn't exist in the Cassandra database and never call the Context::create() function.)

Definition at line 102 of file QCassandra.h.in.

Referenced by context(), contexts(), disconnect(), dropContext(), and findContext().

QtCassandra::QCassandra::f_contexts_read [mutable, private]

This flag defines whether the f_contexts was already initialized or not. This allows to call the describe_keyspaces() function a maximum of one time per connection.

Definition at line 101 of file QCassandra.h.in.

Referenced by contexts().

QtCassandra::QCassandra::f_current_context [private]

The current context has to be set once. We save the pointer that way we can avoid call the set_keyspace() function if the context you are trying to make current already is current.

The libQtCassandra library does not give you access to the QCassandraContext::makeCurrent() function

Definition at line 100 of file QCassandra.h.in.

Referenced by clearCurrentContextIf(), disconnect(), and setCurrentContext().

QtCassandra::QCassandra::f_default_consistency_level [private]

Whenever a value or some other function makes use of the special consistency named CONSISTENCY_LEVEL_DEFAULT this default value is used instead.

By default, the default consistency is set to CONSISTENCY_LEVEL_ONE.

It is not uncommon to change this default value to CONSISTENCY_LEVEL_QUORUM.

Definition at line 105 of file QCassandra.h.in.

Referenced by defaultConsistencyLevel(), and setDefaultConsistencyLevel().

QtCassandra::QCassandra::f_private [private]

The QCassandra object accesses the Cassandra server via functions defined in the QCassandraPrivate object. This pointer holds that object.

This pointer is assigned at the time the QCassandra object gets allocated.

Definition at line 99 of file QCassandra.h.in.

Referenced by clusterName(), connect(), contexts(), disconnect(), getPrivate(), isConnected(), protocolVersion(), and setCurrentContext().

QtCassandra::QCassandra::f_protocol_version [private]

This variable holds the version of the protocol the QCassandra object is connected to. This variable caches the protocol version so we don't have to query the cluster about its protocol version more than once.

Definition at line 104 of file QCassandra.h.in.

Referenced by disconnect(), and protocolVersion().

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

/home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/include/QtCassandra/QCassandra.h.in
/home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/src/QCassandra.cpp

QtCassandra::QCassandra Class Reference

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation