libQtCassandra: QtCassandra::QCassandraContext Class Reference

Hold a Cassandra keyspace definition. More...

#include <include/QtCassandra/QCassandraContext.h>

Inheritance diagram for QtCassandra::QCassandraContext:
Collaboration diagram for QtCassandra::QCassandraContext:

List of all members.

Public Types

typedef unsigned short host_identifier_t
 Define host identifiers.

typedef QMap< QString, QString > QCassandraContextOptions
 A map of context options.

Public Member Functions

virtual ~QCassandraContext ()
 Clean up the QCassandraContext object.

void addLockHost (const QString &host_name)
 Add a new host to the existing list of hosts.

void clearCache ()
 Clear the context cache.

QString contextName () const
 Retrieve the name of this context.

void create ()
 Create a new context.

QString descriptionOption (const QString &option) const
 Retrieve a description option.

const QCassandraContextOptionsdescriptionOptions () const
 Get the map of all description options.

void drop ()
 Drop this context.

void dropTable (const QString &table_name)
 Drop the specified table from the Cassandra database.

bool durableWrites () const
 Retrieve the durable write flag.

void eraseDescriptionOption (const QString &option)
 Delete an option from the current list of options.

QSharedPointer< QCassandraTablefindTable (const QString &table_name) const
 Search for a table.

bool hasDurableWrites () const
 Check whether the durable writes is defined.

bool hasReplicationFactor () const
 Check whether the replication factor is defined.

QString hostName () const
 Get the name of the host using this instance.

QString lockHostsKey () const
 The hosts are listed in the locks table under this name.

QSharedPointer< QCassandraTablelockTable ()
 Retrieve the table used by the Lock implementation.

const QString & lockTableName () const
 Retrieve the current lock table name.

int lockTimeout () const
 Retrieve the lock time out.

int lockTtl () const
 Retrieve the lock TTL.

QCassandraTableoperator[] (const QString &table_name)
 Retrieve a table reference from a context.

const QCassandraTableoperator[] (const QString &table_name) const
 Retrieve a constant table reference.

void removeLockHost (const QString &host_name)
 Remove a lock host name from the database.

int32_t replicationFactor () const
 Retrieve the current replication factor.

void setDescriptionOption (const QString &option, const QString &value)
 Add or replace one of the context description options.

void setDescriptionOptions (const QCassandraContextOptions &options)
 Replace all the context description options.

void setDurableWrites (bool durable_writes)
 Set whether the writes are durable.

void setHostName (const QString &host_name)
 Set the name of the host using this instance.

void setLockTableName (const QString &lock_table_name)
 Set the name of the lock table in this context.

void setLockTimeout (int timeout)
 Set the lock timeout.

void setLockTtl (int ttl)
 Set a different TTL for lock variables.

void setReplicationFactor (int32_t factor)
 Set the replication factor.

void setStrategyClass (const QString &strategy_class)
 Set the context strategy class.

QString strategyClass () const
 Retrieve the name of the strategy class of this context.

QSharedPointer< QCassandraTabletable (const QString &table_name)
 Retrieve a table definition by name.

const QCassandraTablestables () const
 Retrieve a reference to the tables.

void unsetDurableWrites ()
 Unset the durable writes flag.

void unsetReplicationFactor ()
 Unset the replication factor.

void update ()
 Update a context with new properties.

Static Public Attributes

static const host_identifier_t LARGEST_HOST_ID = 10000
 The largest acceptable host identifier.

static const host_identifier_t NULL_HOST_ID = 0
 The NULL host identifier.

Private Types

typedef
controlled_vars::auto_init
< int32_t, 5 > 
lock_timeout_t
 The internal type for the lock timeout value.

typedef
controlled_vars::auto_init
< int32_t, 60 > 
lock_ttl_t
 The internal type for the time to live of a lock.

Private Member Functions

 QCassandraContext (QCassandra *cassandra, const QString &context_name)
 Initialize a QCassandraContext object.

void addValue (const QString &table_name, const QByteArray &row_key, const QByteArray &column_key, int64_t value)
 Add a value to a Cassandra counter.

void createTable (const QCassandraTable *table)
 Create a Cassandra table.

int32_t getCellCount (const QString &table_name, const QByteArray &row_key, const QCassandraColumnPredicate &column_predicate)
 Get a table slice.

void getColumnSlice (QCassandraTable &table, const QByteArray &row_key, QCassandraColumnPredicate &column_predicate)
 Get a table slice.

bool getCounter (const QString &table_name, const QByteArray &row_key, const QByteArray &column_key, QCassandraValue &value)
 Retrieve a counter from the Cassandra database.

uint32_t getRowSlices (QCassandraTable &table, QCassandraRowPredicate &row_predicate)
 Retrieve a slice of rows from Cassandra.

bool getValue (const QString &table_name, const QByteArray &row_key, const QByteArray &column_key, QCassandraValue &value)
 Retrieve a value from the Cassandra database.

void insertValue (const QString &table_name, const QByteArray &row_key, const QByteArray &column_key, const QCassandraValue &value)
 Insert a new value in the Cassandra database.

void makeCurrent ()
 Make this context the current context.

void parseContextDefinition (const void *data)
 This is an internal function used to parse a KsDef structure.

void prepareContextDefinition (void *data) const
 Prepare the context.

void remove (const QString &table_name, const QByteArray &row_key, const QByteArray &column_key, int64_t timestamp, consistency_level_t consistency_level)
 Remove a cell from the Cassandra database.

void synchronizeSchemaVersions ()
 Synchronize the schema versions.

void truncateTable (const QCassandraTable *table)
 Truncate a Cassandra table.

void unparent ()
 Unparent the context.

void updateTable (const QCassandraTable *table)
 Update a Cassandra table.

Private Attributes

QCassandraf_cassandra
 A pointer back to the QCassandra object.

QString f_host_name
 The name of the host running this QCassandra instance.

controlled_vars::zbool_t f_lock_accessed
 Internal flag to know that a lock was accessed.

QString f_lock_table_name
 The name of the table used to create locks.

lock_timeout_t f_lock_timeout
 The lock timeout value.

lock_ttl_t f_lock_ttl
 The lock time to live value.

QCassandraContextOptions f_options
 List of tables.

std::auto_ptr
< QCassandraContextPrivate
f_private
 The pointer to the QCassandraContextPrivate object.

QCassandraTables f_tables
 List of tables.

Friends

class QCassandra
class QCassandraContextPrivate
class QCassandraLock
class QCassandraPrivate
class QCassandraTable

Detailed Description

This class defines objects that can hold all the necessary information for a Cassandra keyspace definition.

A keyspace is similar to a context in the sense that to work on a keyspace you need to make it the current context. Whenever you use a context, this class automatically makes it the current context. This works well in a non threaded environment. In a threaded environment, you want to either make sure that only one thread makes use of the Cassandra objects or that you protect all the calls. This library does not.

You may think of this context as one database of an SQL environment. If you have used OpenGL, this is very similar to the OpenGL context.

Definition at line 49 of file QCassandraContext.h.


Member Typedef Documentation

This type is used to hold host identifiers. It is used when transforming a host name to a host identifier. The identifier is unique and represents an order in which each client are sorted.

See the QCassandraLock object for more information about how this information is used to create an inter-client lock.

Definition at line 53 of file QCassandraContext.h.

This type is internally used to hold the lock timeout. It is initialized to 5 by default. It is defined in seconds.

See also:
setLockTimeout()
lockTimeout()

Definition at line 111 of file QCassandraContext.h.

This type is internally used to hold the lock time to live value. It is initialized to 60 by default. It is defined in seconds.

See also:
setLockTtl()
lockTtl()

Definition at line 112 of file QCassandraContext.h.

This map defines options as name / value pairs.

Only known otion names should be used or a protocol error may result.

Definition at line 52 of file QCassandraContext.h.


Constructor & Destructor Documentation

This function ensures that all resources allocated by the QCassandraContext are released.

Note that does not in any way destroy the context in the Cassandra cluster.

Definition at line 323 of file QCassandraContext.cpp.

QtCassandra::QCassandraContext::QCassandraContext ( QCassandra cassandra,
const QString &  context_name 
) [private]

This function initializes a QCassandraContext object.

Note that the constructor is private. To create a new context, you must use the QCassandra::context() function.

All the parameters are set to the defaults as defined in the Cassandra definition of the KsDef message. You can use the different functions to change the default values.

A context name must be composed of letters (A-Za-z), digits (0-9) and underscore (_). It must start with a letter. The corresponding lexical expression is: /[A-Za-z][A-Za-z0-9_]*\/

The name of the lock table is defined at the time a cassandra context object is created in memory. You must change it immediately with the setLockTableName() if you do not want to use the default which is: "libQtCassandraLockTable". See the QCassandraLock object for more information about locks in a Cassandra environment.

Note:
A context can be created, updated, and dropped. In all those cases, the functions return once the Cassandra instance with which you are connected is ready. However, that is not enough if you are working with a cluster because the other nodes do not get updated instantaneously. Instead, you have to call the QCassandra::synchronizeSchemaVersions() function of the QCassandra object to make sure that the context is fully available across your cluster.
Parameters:
[in]cassandraThe QCassandra object owning this context.
[in]context_nameThe name of the Cassandra context.
See also:
setLockTableName()
setLockHostName()
QCassandra::context()
QCassandra::synchronizeSchemaVersions()

Definition at line 288 of file QCassandraContext.cpp.

References f_host_name, and f_private.


Member Function Documentation

void QtCassandra::QCassandraContext::addLockHost ( const QString &  host_name)

This function adds the name of a host and assign it an identifier between 1 and LARGEST_HOST_ID. If you have more hosts than LARGEST_HOST_ID then you will have to recompile Snap with a larger number (really? more than 10,000 computers?)

The addition of hosts in this way is safe on a running system as long as:

  • (1) the host being added is not already running;
  • (2) only one instance of the process calling this function runs at a time.

The new identifier is added after looking at all the existing identifiers (i.e. if one is available, it is used, if none are available, a new one is created.)

Note:
If the named host already exists in the list of hosts, then it is not added a second time. Be careful because the remove removes at once (i.e. if you added the same host name 10 times, only 1 remove and it is gone.)
Parameters:
[in]host_nameThe name of the host to be added.

Definition at line 1368 of file QCassandraContext.cpp.

References QtCassandra::CONSISTENCY_LEVEL_QUORUM, lockHostsKey(), lockTable(), QtCassandra::QCassandraColumnPredicate::setConsistencyLevel(), and QtCassandra::QCassandraValue::setConsistencyLevel().

void QtCassandra::QCassandraContext::addValue ( const QString &  table_name,
const QByteArray &  row_key,
const QByteArray &  column_key,
int64_t  value 
) [private]

This function adds value to a Cassandra counter as referenced by the row_key and column_key.

Parameters:
[in]table_nameName of the table where the value is inserted.
[in]row_keyThe key used to identify the row.
[in]column_keyThe key used to identify the column.
[out]valueThe value to add to this counter.

Definition at line 1157 of file QCassandraContext.cpp.

References QtCassandra::QCassandraPrivate::addValue(), f_cassandra, QtCassandra::QCassandra::getPrivate(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::addValue(), and QtCassandra::QCassandraTable::insertValue().

This function clears the context cache. This means all the tables, their rows, and the cells of those rows all get cleared. None of these can be used after this call even if you kept a shared pointer to any of these objects.

Definition at line 1242 of file QCassandraContext.cpp.

References f_tables.

Referenced by unparent().

This function returns the name of this context.

Note that the name cannot be modified. It is set by the constructor as you create a QCassandraContext.

Returns:
A QString with the context name.

Definition at line 336 of file QCassandraContext.cpp.

References f_private.

Referenced by QtCassandra::QCassandraPrivate::dropContext(), and QtCassandra::QCassandraTable::QCassandraTable().

This function is used to create a new context (keyspace) in the current Cassandra cluster. Once created, you can make use of it whether it is attached to the Cassandra cluster or not.

If you want to include tables in your new context, then create them before calling this function. It will be faster since you'll end up with one single request.

There is an example on how to create a new context with this library:

 QtCassandra::QCassandraContext context("qt_cassandra_test_context");
 // default strategy is LocalStrategy which you usually don't want
 context.setStrategyClass("org.apache.cassandra.locator.SimpleStrategy");
 context.setDurableWrites(true); // by default this is 'true'
 context.setReplicationFactor(1); // by default this is undefined
 ...  // add tables before calling create() if you also want tables
 context.create(context);

Note that the replication factor is not set by default, but it is a required parameter unless you use a Network cluster settings.

Also, the replication factor cannot be set to 1 if you have more than one node (I may be wrong, but in my tests it failed with a replication factor of one in a cluster of 3 nodes.)

Warning:
After this call, if you are to use the context immediately, you want to first call the synchronization function, QCassandra::synchronizeSchemaVersions(), to make sure that all the nodes are ready to use the new context. Otherwise you are likely to get errors about things not being compatible or up to date.
See also:
QCassandraTable::create()
QCassandra::synchronizeSchemaVersions()

Definition at line 891 of file QCassandraContext.cpp.

References QtCassandra::QCassandraPrivate::createContext(), f_cassandra, f_tables, and QtCassandra::QCassandra::getPrivate().

This function creates a Cassandra table by sending the corresponding order to the connected server.

The creation of a table is not instantaneous in all the nodes of your cluster. When this function returns, the table was created in the node you're connected with. To make sure that all the nodes are up to date (and before using this newly created table) you must call the QCassandra::synchronizeSchemaVersions() function. You may create any number of tables at once, then call the synchronization function to make sure that your entire cluster is ready.

Parameters:
[in]tableThe table definition used to create the Cassandra table.
See also:
QCassandra::synchronizeSchemaVersions()

Definition at line 1020 of file QCassandraContext.cpp.

References QtCassandra::QCassandraPrivate::createTable(), f_cassandra, QtCassandra::QCassandra::getPrivate(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::create().

QString QtCassandra::QCassandraContext::descriptionOption ( const QString &  option) const

This function retrieves the description option named by the option parameter.

Note:
Versions of this function in libQtCassandra before 0.4.2 would add an empty version of the option if it wasn't defined yet.
Parameters:
[in]optionThe name of the option to retrieve.
Returns:
The value of the named option or an empty string.

Definition at line 443 of file QCassandraContext.cpp.

References f_options.

The context maintains a map indexed by option name of all the description options of the context. This function retreives a constant reference to that list.

If you keep the return reference as such (i.e. a reference) then make sure you do not modify the options (calling one of the setDescriptionOptions() or setDescriptionOption() functions.) Otherwise the reference may become invalid. If you are going to modify the options, make a copy of the map.

Returns:
A reference to the map of context options.

Definition at line 409 of file QCassandraContext.cpp.

References f_options.

This function drops this context in the Cassandra database.

Note that contexts are dropped by name so we really only use the name of the context in this case.

The QCassandraContext object is still valid afterward, although, obviously no data can be read from or written to the Cassandra server since the context is gone from the cluster.

You may change the parameters of the context and call create() to create a new context with the same name.

Warning:
If the context does not exist in Cassandra, this function call raises an exception in newer versions of the Cassandra system (in version 0.8 it would just return silently.) You may want to call the QCassandra::findContext() function first to know whether the context exists before calling this function.
See also:
QCassandra::dropContext()
QCassandra::findContext()

Definition at line 958 of file QCassandraContext.cpp.

References QtCassandra::QCassandraPrivate::dropContext(), f_cassandra, and QtCassandra::QCassandra::getPrivate().

void QtCassandra::QCassandraContext::dropTable ( const QString &  table_name)

This function sends a message to the Cassandra server so the named table gets droped from it.

The function also deletes the table from memory (which means all its rows and cells are also deleted.) Do not use the table after this call, even if you kept a shared pointer to it. You may create a new one with the same name though.

Note that tables get dropped immediately from the Cassandra database (contrary to rows.) However, it can be a slow operation since all the nodes need to be notified (i.e. consistency of ALL.) If you need to know when the table is dropped from the entire cluster, call the QCassandra::synchronizeSchemaVersions() function.

Parameters:
[in]table_nameThe name of the table to drop.
See also:
QCassandra::synchronizeSchemaVersions()

Definition at line 987 of file QCassandraContext.cpp.

References QtCassandra::QCassandraPrivate::dropTable(), f_cassandra, f_tables, QtCassandra::QCassandra::getPrivate(), makeCurrent(), and table().

This function returns the durable flag that determines whether a context is temporary (false) or permanent (true).

Returns:
The current durable writes flag status.

Definition at line 706 of file QCassandraContext.cpp.

References f_private.

This function deletes the specified option from the list of description options in memory. If the option was not defined, the function has no effect.

Note:
This is useful to manage the list of options, however, erasing an option here only tells the system to use the default value. It does not prevent the system from having that option defined.
Parameters:
[in]optionThe name of the option to delete.

Definition at line 464 of file QCassandraContext.cpp.

References f_options, and f_private.

Referenced by unsetReplicationFactor().

QSharedPointer< QCassandraTable > QtCassandra::QCassandraContext::findTable ( const QString &  table_name) const

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

Note:
Since the system reads the list of existing tables when it starts, this function returns tables that exist in the database and in memory only.
Parameters:
[in]table_nameThe name of the table to retrieve.
Returns:
A shared pointer to the table.

Definition at line 535 of file QCassandraContext.cpp.

References f_tables.

Referenced by lockTable(), and operator[]().

int32_t QtCassandra::QCassandraContext::getCellCount ( const QString &  table_name,
const QByteArray &  row_key,
const QCassandraColumnPredicate column_predicate 
) [private]

This function reads a table slice from the Cassandra database.

Parameters:
[in]table_nameThe name of the table where the row is check is defined.
[in]row_keyThe row for which this data is being counted.
[in]column_predicateThe predicate to use to count the cells.
Returns:
The number of columns defined in the specified row.

Definition at line 1173 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandraPrivate::getCellCount(), QtCassandra::QCassandra::getPrivate(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::getCellCount().

void QtCassandra::QCassandraContext::getColumnSlice ( QCassandraTable table,
const QByteArray &  row_key,
QCassandraColumnPredicate column_predicate 
) [private]

This function reads a table slice from the Cassandra database.

Note:
The column_predicate is an [in,out] parameter because the start column name is set to the name of the last column read. This allows for reading all the columns of a row used as an index.
Parameters:
[in]tableThe table where the results is saved.
[in]row_keyThe row for which this data is being counted.
[in,out]column_predicateThe predicate to use to count the cells.

Definition at line 1192 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandraPrivate::getColumnSlice(), QtCassandra::QCassandra::getPrivate(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::getColumnSlice().

bool QtCassandra::QCassandraContext::getCounter ( const QString &  table_name,
const QByteArray &  row_key,
const QByteArray &  column_key,
QCassandraValue value 
) [private]

This function gets a counter value from the Cassandra database referenced by the table_name, row_key, and column_key.

If the column is not found, then the value parameter is set to zero and the function returns false.

Warning:
This function only works on counters, see getValue() for any other type of data.
Parameters:
[in]table_nameName of the table where the value is inserted.
[in]row_keyThe key used to identify the row.
[in]column_keyThe key used to identify the column.
[out]valueThe new value of the cell.
Returns:
false when the value was not found in the database, true otherwise
See also:
getValue()

Definition at line 1134 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandraPrivate::getCounter(), QtCassandra::QCassandra::getPrivate(), makeCurrent(), and QtCassandra::QCassandraValue::setInt64Value().

Referenced by QtCassandra::QCassandraTable::getValue(), and QtCassandra::QCassandraTable::insertValue().

uint32_t QtCassandra::QCassandraContext::getRowSlices ( QCassandraTable table,
QCassandraRowPredicate row_predicate 
) [private]

This function calls the Cassandra server to retrieve a set of rows as defined by the row predicate. These rows get cells as defined by the column predicate defined inside the row predicate object.

Note that the function updates the predicate so the next call returns the following rows as expected.

Parameters:
[in]tableThe table which is emitting this call.
[in,out]row_predicateThe predicate used to select the rows.
Returns:
The number of rows read on this call.

Definition at line 1229 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), QtCassandra::QCassandraPrivate::getRowSlices(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::readRows().

bool QtCassandra::QCassandraContext::getValue ( const QString &  table_name,
const QByteArray &  row_key,
const QByteArray &  column_key,
QCassandraValue value 
) [private]

This function gets a value from the Cassandra database referenced by the row_key and column_key.

If the column is not found, then the value parameter is set to the null value and the function returns false.

Warning:
This function does not work for counters, use getCounter() instead.
Parameters:
[in]table_nameName of the table where the value is inserted.
[in]row_keyThe key used to identify the row.
[in]column_keyThe key used to identify the column.
[out]valueThe new value of the cell.
Returns:
false when the value was not found in the database, true otherwise
See also:
getCounter()

Definition at line 1100 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), QtCassandra::QCassandraPrivate::getValue(), makeCurrent(), and QtCassandra::QCassandraValue::setNullValue().

Referenced by QtCassandra::QCassandraTable::getValue().

This function retrieves the current status of the durable writes parameter.

Returns:
True if the durable writes parameter is defined.

Definition at line 694 of file QCassandraContext.cpp.

References f_private.

This function retrieves the current status of the replication factor parameter.

Returns:
True if the replication factor parameter is defined.

Definition at line 642 of file QCassandraContext.cpp.

References f_private.

This function returns the name of the host using this QCassandraContext. The name is defined by calling hostname() by default. However, it can be modified by calling the setHostName() function.

Returns:
The name of the host as set by setHostName().

Definition at line 1467 of file QCassandraContext.cpp.

References f_host_name, and f_lock_accessed.

void QtCassandra::QCassandraContext::insertValue ( const QString &  table_name,
const QByteArray &  row_key,
const QByteArray &  column_key,
const QCassandraValue value 
) [private]

This function inserts a new value in this Context of the Cassandra database referenced by the row_key and column_key.

Parameters:
[in]table_nameName of the table where the value is inserted.
[in]row_keyThe key used to identify the row.
[in]column_keyThe key used to identify the column.
[in]valueThe new value of the cell.

Definition at line 1074 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), QtCassandra::QCassandraPrivate::insertValue(), and makeCurrent().

Referenced by QtCassandra::QCassandraTable::insertValue().

The lock table uses rows named after the objects that you want to lock. It also includes the list of all the hosts that access your Cassandra system.

Returns:
The name used for row holding the list of host names and their identifiers.

Definition at line 1291 of file QCassandraContext.cpp.

Referenced by addLockHost(), and removeLockHost().

This function retrieves the "libQtCassandraLockTable" table to use with the different functions that handle the Cassandra interprocess locking implementation.

If the table doesn't exist yet, then it gets created. The function also synchronize the cluster so as to allow other functions to instantly make use of the table on return.

Note:
Remember that the lock is inter-PROCESS and not inter-threads. This library is not thread safe.
Returns:
The function returns a pointer to the Cassandra table.

Definition at line 1312 of file QCassandraContext.cpp.

References findTable(), lockTableName(), synchronizeSchemaVersions(), and table().

Referenced by addLockHost().

The lock table name is set to "libQtCassandraLockTable"

Returns:
The name of the table used to create locks.

Definition at line 1502 of file QCassandraContext.cpp.

References f_lock_accessed, and f_lock_table_name.

Referenced by lockTable().

By default retrieving a lock times out in 5 seconds. In other words, if the acquisition of the lock takes more than 5 seconds, the function times out and returns false.

Returns:
The current lock time out.

Definition at line 1536 of file QCassandraContext.cpp.

References f_lock_timeout.

This function returns the lock TTL as defined by the set_lock_ttl(). By default the TTL value is set to 1 minute.

The value is specified in seconds.

Returns:
The current TTL value.

Definition at line 1569 of file QCassandraContext.cpp.

References f_lock_ttl.

This function marks this context as the current context where further function calls will be made (i.e. table and cell editing.)

Note that whenever you call a function that requires this context to be current, this function is called automatically. If the context is already the current context, then no message is sent to the Cassandra server.

Note:
If you just created a context, you want to call the QCassandra::synchronizeSchemaVersions() function before calling this function or you may get an exception saying that the context is not availabe across your Cassandra cluster.
See also:
QCassandra::setContext()
QCassandra::synchronizeSchemaVersions()

Definition at line 838 of file QCassandraContext.cpp.

References QtCassandra::QCassandra::context(), f_cassandra, f_private, and QtCassandra::QCassandra::setCurrentContext().

Referenced by addValue(), createTable(), dropTable(), getCellCount(), getColumnSlice(), getCounter(), getRowSlices(), getValue(), insertValue(), remove(), truncateTable(), and updateTable().

QCassandraTable & QtCassandra::QCassandraContext::operator[] ( const QString &  table_name)

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

 context[table_name][column_name] = value;
Exceptions:
std::runtime_errorIf the table doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.
Parameters:
[in]table_nameThe name of the table to retrieve.
Returns:
A reference to the named table.

Definition at line 563 of file QCassandraContext.cpp.

References findTable(), and table().

const QCassandraTable & QtCassandra::QCassandraContext::operator[] ( const QString &  table_name) const

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

 value = context[table_name][column_name];
Exceptions:
std::runtime_errorIf the table doesn't exist, this function raises an exception since otherwise the reference would be a NULL pointer.
Parameters:
[in]table_nameThe name of the table to retrieve.
Returns:
A constant reference to the named table.

Definition at line 591 of file QCassandraContext.cpp.

References findTable(), and table().

void QtCassandra::QCassandraContext::parseContextDefinition ( const void *  data) [private]

This function is called internally to parse a KsDef object.

Parameters:
[in]dataThe pointer to the KsDef object.

Definition at line 720 of file QCassandraContext.cpp.

References f_options, f_private, f_tables, and table().

void QtCassandra::QCassandraContext::prepareContextDefinition ( void *  data) const [private]

This function prepares the context so it can be copied in a keyspace definition later used to create a keyspace or to update an existing keyspace.

Parameters:
[out]dataThe output keyspace definition.

Definition at line 779 of file QCassandraContext.cpp.

References f_options, f_private, and f_tables.

Referenced by QtCassandra::QCassandraPrivate::createContext(), and QtCassandra::QCassandraPrivate::updateContext().

void QtCassandra::QCassandraContext::remove ( const QString &  table_name,
const QByteArray &  row_key,
const QByteArray &  column_key,
int64_t  timestamp,
consistency_level_t  consistency_level 
) [private]

This function calls the Cassandra server to remove a cell in the Cassandra database.

Parameters:
[in]table_nameThe name of the column where the row is defined.
[in]row_keyThe row in which the cell is to be removed, if empty all the rows.
[in]column_keyThe cell to be removed, if empty all the cells.
[in]timestampThe time when the key to be removed was created.
[in]consistency_levelThe consistency level to use to remove this cell.

Definition at line 1209 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), makeCurrent(), and QtCassandra::QCassandraPrivate::remove().

Referenced by QtCassandra::QCassandraTable::remove().

void QtCassandra::QCassandraContext::removeLockHost ( const QString &  host_name)

This function removes the specified host name from the database. The identifier of the host is then released, but all existing identifiers are not modified. It will be reused next time a host is added to the database.

It is safe to remove a host on a running system as long as the host being removed does not run anymore at the time it is removed.

Parameters:
[in]host_nameThe name of the host to be removed from the database.

Definition at line 1428 of file QCassandraContext.cpp.

References f_lock_table_name, lockHostsKey(), and table().

This function reads and return the current replication factor of the context.

If the replication factor is not defined, zero is returned.

Returns:
The current replication factor.

Definition at line 656 of file QCassandraContext.cpp.

References f_private.

void QtCassandra::QCassandraContext::setDescriptionOption ( const QString &  option,
const QString &  value 
)

This function sets the specified option to the specified value.

Parameters:
[in]optionThe option to set.
[in]valueThe new value the option to set.

Definition at line 421 of file QCassandraContext.cpp.

References f_options, and f_private.

Referenced by setReplicationFactor().

This function overwrites all the description options with the ones specified in the input parameter.

This function can be used to clear all the options by passing an empty options parameter.

Warning:
Since version 1.1, the replication_factor has become a full option and the definition found directly in the KsDef structure is ignored. This means overwriting all the options may have the unwanted side effect of deleting the replication_factor under your feet.
Parameters:
[in]optionsThe replacing options

Definition at line 384 of file QCassandraContext.cpp.

References f_options, and f_private.

void QtCassandra::QCassandraContext::setDurableWrites ( bool  durable_writes)

Temporary and permanent contexts can be created. This option defines whether it is one of the other. Set to true to create a permanent context (this is the default.)

Parameters:
[in]durable_writesSet whether writes are durable.

Definition at line 672 of file QCassandraContext.cpp.

References f_private.

void QtCassandra::QCassandraContext::setHostName ( const QString &  host_name)

Each host must have a unique name which the libQtCassandra system can transform in an identifier (a number from 1 to 10000).

For locks to function (see QCassandraLock), it is a requirement to call this function because each host must be given a unique identifier used in the lock implementation to know who gets the lock next.

Exceptions:
std::logic_errorThis exception is raised if the lock was already accessed.
Parameters:
[in]host_nameThe name of the host running this instance of QtCassandra.
See also:
QCassandraLock

Definition at line 1450 of file QCassandraContext.cpp.

References f_host_name, and f_lock_accessed.

void QtCassandra::QCassandraContext::setLockTableName ( const QString &  lock_table_name)

The QCassandraContext uses a default name to lock tables, rows, cells. This name can be changed by calling this function until a lock was used. Once a lock was used, the name cannot be changed anymore. Note that you MUST always have exactly the same name for all your application processes or the lock won't work properly. This function should be called very early on to ensure consistency.

Exceptions:
std::logic_errorThis exception is raised if the lock was already accessed.
Parameters:
[in]lock_table_nameThe name to use as the lock table.

Definition at line 1487 of file QCassandraContext.cpp.

References f_lock_accessed, and f_lock_table_name.

Set the time out of the lock function in seconds. This amount is used to time the function while acquiring a lock. If more than this number of seconds, then the function fails and returns false.

The default lock timeout is 5 seconds. It cannot be set to less than 1 second. There is no option to set a lock that never times out, although if you use a very large number, it is pretty much the same.

Parameters:
[in]timeoutThe new timeout in seconds.

Definition at line 1520 of file QCassandraContext.cpp.

References f_lock_timeout.

Whenever creating lock variables in the database, this TTL is used. This ensures that the lock variables are not permanent in the database. This will automatically unlock everything.

The value is defined in seconds although a lock should be returns in milliseconds, it may take a little bit of time if you have several data centers accross the Internet.

The default is 1 minute (60 seconds.)

Parameters:
[in]ttlThe new time to live value in seconds.

Definition at line 1555 of file QCassandraContext.cpp.

References f_lock_ttl.

This function sets the replication factor of the context.

Deprecated:
Since version 1.1 of Cassandra, the context replication factor is viewed as a full option. This function automatically sets the factor using the setDescriptionOption() function. This means calling the setDescriptionOptions() and overwriting all the options has the side effect of cancelling this call. Note that may not work right with older version of Cassandra. Let me know if that's the case.
Parameters:
[in]factorThe new replication factor.

Definition at line 616 of file QCassandraContext.cpp.

References setDescriptionOption().

void QtCassandra::QCassandraContext::setStrategyClass ( const QString &  strategy_class)

This function is used to change the class of the context to a new strategy. The strategy class is used to handle reads and writes according to the use of the corresponding context.

Parameters:
[in]strategy_classThe new strategy class.

Definition at line 349 of file QCassandraContext.cpp.

References f_private.

This function returns the strategy class of this context. This is a name defining how the data in this context is duplicated accross the nodes of the Cassandra system.

Returns:
The strategy class.

Definition at line 362 of file QCassandraContext.cpp.

References f_private.

This function calls the cassandra synchronizeSchemaVersions(). This can be called by the context children as required.

If the context was already unparented, then nothing happens.

See also:
unparent()
QCassandra::synchronizeSchemaVersions()

Definition at line 1261 of file QCassandraContext.cpp.

References f_cassandra, and QtCassandra::QCassandra::synchronizeSchemaVersions().

Referenced by lockTable().

QSharedPointer< QCassandraTable > QtCassandra::QCassandraContext::table ( const QString &  table_name)

This function is used to retrieve a table definition by name. If the table doesn't exist, it gets created.

Note that if the context is just a memory context (i.e. it does not yet exist in the Cassandra cluster,) then the table is just created in memory. This is useful to create a new context with all of its tables all at once. The process is to call the QCassandra::context() function to get an in memory context, and then call this table() function for each one of the table you want to create. Finally, to call the create() function to actually create the context and its table in the Cassandra cluster.

You can test whether the result is null with the isNull() function of the QSharedPointer class.

Parameters:
[in]table_nameThe name of the table to retrieve.
Returns:
A shared pointer to the table definition found or a null shared pointer.

Definition at line 493 of file QCassandraContext.cpp.

References f_tables, and QCassandraTable.

Referenced by dropTable(), lockTable(), operator[](), parseContextDefinition(), and removeLockHost().

This function retrieves a constant reference to the map of table definitions. The list is read-only, however, it is strongly suggested that you make a copy if your code is going to modifiy tables later (i.e. calling table() may affect the result of this call if you did not first copy the map.)

Returns:
A reference to the table definitions of this context.

Definition at line 516 of file QCassandraContext.cpp.

References f_tables.

This function truncates a Cassandra table by sending the corresponding order to the connected server.

Parameters:
[in]tableThe table to drop from the Cassandra server.

Definition at line 1058 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), makeCurrent(), and QtCassandra::QCassandraPrivate::truncateTable().

Referenced by QtCassandra::QCassandraTable::truncate().

This function is called internally to mark the context as unparented. This means you cannot use it anymore. This happens whenever you call the dropContext() funtion on a QCassandra object.

See also:
QCassandra::dropContext()

Definition at line 1276 of file QCassandraContext.cpp.

References clearCache(), and f_cassandra.

This function marks the durable write flag as not set. This does not otherwise change the flag. It will just not be sent over the network and the default will be used when required.

Definition at line 683 of file QCassandraContext.cpp.

References f_private.

This function unsets the replication factor in case it was set. In general it is not necessary to call this function unless you are initializing a new context and you want to make sure that the default replication factor is used.

Definition at line 631 of file QCassandraContext.cpp.

References eraseDescriptionOption().

This function defines a new set of properties in the specified context. In general, the context will be searched in the cluster definitions, updated in memory then this function called.

Definition at line 925 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), and QtCassandra::QCassandraPrivate::updateContext().

This function updates a Cassandra table by sending the corresponding order to the connected server.

It can be used to define new column types or changing existing columns (although changing existing columns may not work as expected, from what I understand.)

This function is not instantaneous and will slowly replicate to all your nodes. In other words, you cannot access the table until the schema is full propagated throughout your cluster. If you need to access the table immediately after an update, make sure to call the QCassandra::synchronizeSchemaVersions()

Parameters:
[in]tableThe table to update in the Cassandra server.
See also:
QCassandra::synchronizeSchemaVersions()

Definition at line 1045 of file QCassandraContext.cpp.

References f_cassandra, QtCassandra::QCassandra::getPrivate(), makeCurrent(), and QtCassandra::QCassandraPrivate::updateTable().

Referenced by QtCassandra::QCassandraTable::update().


Friends And Related Function Documentation

friend class QCassandra [friend]

Definition at line 134 of file QCassandraContext.h.

friend class QCassandraContextPrivate [friend]

Definition at line 136 of file QCassandraContext.h.

friend class QCassandraLock [friend]

Definition at line 138 of file QCassandraContext.h.

friend class QCassandraPrivate [friend]

Definition at line 135 of file QCassandraContext.h.

friend class QCassandraTable [friend]

Definition at line 137 of file QCassandraContext.h.

Referenced by table().


Member Data Documentation

The bare pointer is used by the context to access the cassandra private object and make the context the current context. It is a bare pointer because the QCassandra object cannot be deleted without the context getting deleted first.

Note that when deleting a QCassandraContext object, you may still have a shared pointer referencing the object. This means the object itself will not be deleted. In that case, the f_cassandra parameter becomes NULL and calling functions that make use of it throw an error.

Note:
If you look at the implementation, many functions call the makeCurrent() which checks the f_cassandra pointer, thus these functions don't actually test the pointer.

Definition at line 144 of file QCassandraContext.h.

Referenced by addValue(), create(), createTable(), drop(), dropTable(), getCellCount(), getColumnSlice(), getCounter(), getRowSlices(), getValue(), insertValue(), makeCurrent(), remove(), synchronizeSchemaVersions(), truncateTable(), unparent(), update(), and updateTable().

This variable holds the name of the host running this instance. This is most often the name of the computer (what the hostname() function returns, which is taken as the default value.) You may use a different name by calling the setHostName() function.

See also:
setHostName()
hostName()

Definition at line 147 of file QCassandraContext.h.

Referenced by hostName(), QCassandraContext(), and setHostName().

This variable is set to true as soon as a value used by the QCassandraLock is read. This tells the context that some parameters such as the host name and the table name used to create locks cannot be changed anymore.

Definition at line 149 of file QCassandraContext.h.

Referenced by hostName(), lockTableName(), setHostName(), and setLockTableName().

This variable holds the name of the table used by the QCassandraLock implementation. This name should be set once early on when creating the context. It cannot be changed once a lock was created.

By default this name is set to: "libQtCassandraLockTable". You should not have to ever change it.

Definition at line 148 of file QCassandraContext.h.

Referenced by lockTableName(), removeLockHost(), and setLockTableName().

This value is used by the QCassandraLock implementation to know how long to wait before timing out when trying to obtain a lock.

Note that the minimum is 1 second. Remember that if you are using a cluster with computers in multiple centers throughout the world, 1 second is not very much to ensure QUORUM consistency.

Definition at line 150 of file QCassandraContext.h.

Referenced by lockTimeout(), and setLockTimeout().

This variable holds locks time to live (TTL).

The QCassandraLock object saves all the lock values using this TTL so as to ensure that the lock data does not live forever (otherwise it would lock things for that long: forever.)

In most cases the TTL is not necessary since the lock is released (and thus deleted from the database) way before the TTL enters in action. However, if your application crashes and the intended RAII implementation does not run (i.e. SEGV that aborts the process immediately?) then at least the lock system will recover after a little while.

Definition at line 151 of file QCassandraContext.h.

Referenced by lockTtl(), and setLockTtl().

A map of name and value pairs representing options of the context. Each context can have many options.

The libQtCassandra doesn't make use of these options. It's only used by the Cassandra server.

Definition at line 145 of file QCassandraContext.h.

Referenced by descriptionOption(), descriptionOptions(), eraseDescriptionOption(), parseContextDefinition(), prepareContextDefinition(), setDescriptionOption(), and setDescriptionOptions().

This pointer is a shared pointer to the private definition of the Cassandra context (i.e. a keyspace definition.)

The pointer is created at the time the context is created.

Definition at line 140 of file QCassandraContext.h.

Referenced by contextName(), durableWrites(), eraseDescriptionOption(), hasDurableWrites(), hasReplicationFactor(), makeCurrent(), parseContextDefinition(), prepareContextDefinition(), QCassandraContext(), replicationFactor(), setDescriptionOption(), setDescriptionOptions(), setDurableWrites(), setStrategyClass(), strategyClass(), and unsetDurableWrites().

A list of the tables defined in this context. The tables may be created in memory only.

The list is a map using the table binary key as the its own key.

Definition at line 146 of file QCassandraContext.h.

Referenced by clearCache(), create(), dropTable(), findTable(), parseContextDefinition(), prepareContextDefinition(), table(), and tables().

This value represents the largest accepted host identifier. If you try to define more identifiers, then you get an error.

This limit was randomly chosen. However, it represents the number of computers that could ever connect to your Cassandra cluster. If you really have more than that, update the value!

Definition at line 55 of file QCassandraContext.h.

When querying for a host that was not yet defined in the cluster, this value is returned. It tells you that the host identifier wasn't defined yet.

This is used by the QCassandraLock to determine whether the host identifier was defined.

Definition at line 54 of file QCassandraContext.h.


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

This document is part of the Snap! Websites Project.

Copyright © 2011-2013 by Made to Order Software Corp.

Syndicate content

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

Contact Us Directly