libQtCassandra: QtCassandra::QCassandra Class Reference

libQtCassandra 1.0

The Cassandra class definition. More...

Inheritance diagram for QtCassandra::QCassandra:
Collaboration diagram for QtCassandra::QCassandra:

List of all members.

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< QCassandraContextcontext (const QString &context_name)
 Retrieve a context by name.

const QCassandraContextscontexts () const
 Get the map of contexts.

consistency_level_t defaultConsistencyLevel () const
 Retrieve the current default consistency level.

void disconnect ()
 Break the connection to Cassandra.

QSharedPointer< QCassandraContextfindContext (const QString &context_name) const
 Search for a context.

bool isConnected () const
 Check whether the object is connected to the server.

QCassandraContextoperator[] (const QString &context_name)
 Retrieve a context reference.

const QCassandraContextoperator[] (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.

QCassandraPrivategetPrivate ()
 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< QCassandraContextf_current_context
 A pointer to the current context.

consistency_level_t f_default_consistency_level
 The consistency level used by default.

std::auto_ptr< QCassandraPrivatef_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 510 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 531 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]cThe context that is about to be dropped.

Definition at line 758 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 632 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]hostThe host, defaults to "localhost" (an IP address, computer hostname, domain name, etc.)
[in]portThe connection port, defaults to 9160
Returns:
true if the connection succeeds, false otherwise

Definition at line 574 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.

You must be connected for this function to work.

Parameters:
[in]context_nameThe name of the context to search.
Returns:
A shared pointer to a cassandra context.

Definition at line 679 of file QCassandra.cpp.

References contexts(), f_contexts, and QCassandraContext.

Referenced by QtCassandra::QCassandraPrivate::contexts(), 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 782 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 880 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 590 of file QCassandra.cpp.

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

Referenced by connect().

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_nameThe name of the context to retrieve.
Returns:
A shared pointer to the context.

Definition at line 801 of file QCassandra.cpp.

References f_contexts.

Referenced by operator[]().

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 609 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_errorIf the context doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.
Parameters:
[in]context_nameThe name of the context to retrieve.
Returns:
A reference to the named context.

Definition at line 829 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_errorIf the context doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.
Parameters:
[in]context_nameThe name of the context to retrieve.
Returns:
A constant reference to the named context.

Definition at line 857 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 659 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]cThe context to set as current.
See also:
currentContext()
QCassandraContext::makeCurrent()

Definition at line 740 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_levelThe new default consistency level.

Definition at line 898 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 969 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 956 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 921 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 932 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 943 of file QCassandra.cpp.

References QtCassandra::QT_CASSANDRA_LIBRARY_VERSION_PATCH.


Friends And Related Function Documentation

friend class QCassandraContext [friend]

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

Referenced by context().

friend class QCassandraPrivate [friend]

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


Member Data Documentation

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 99 of file QCassandra.h.in.

Referenced by clusterName(), and disconnect().

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 98 of file QCassandra.h.in.

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

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 97 of file QCassandra.h.in.

Referenced by contexts().

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 96 of file QCassandra.h.in.

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

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 101 of file QCassandra.h.in.

Referenced by defaultConsistencyLevel(), and setDefaultConsistencyLevel().

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 95 of file QCassandra.h.in.

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

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 100 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

This document is part of the libQtCassandra Project.

Copyright by Made to Order Software Corp.

Syndicate content

Snap! Websites
An Open Source CMS System in C++

Contact Us Directly