libQtCassandra: QtCassandra::QCassandraCell Class Reference

QtCassandra::QCassandraCell Class Reference

A cell holds a name and value pair. More...

#include <include/QtCassandra/QCassandraCell.h>

Inheritance diagram for QtCassandra::QCassandraCell:
Collaboration diagram for QtCassandra::QCassandraCell:

List of all members.

Public Member Functions

virtual ~QCassandraCell ()
 Clean up the QCassandraCell object.

void add (int64_t value)
 Add a value to a counter.

void clearCache ()
 The value of a cell is automatically cached in memory.

const QByteArray & columnKey () const
 Retrieve the column key.

QString columnName () const
 Retrieve the name of the column.

consistency_level_t consistencyLevel () const
 Retrieve the current consistency level of this value.

 operator QCassandraValue () const
 Retrieve the cell value.

QCassandraCelloperator++ ()
 Increment a counter.

QCassandraCelloperator++ (int)
 Increment a counter.

QCassandraCelloperator+= (int64_t value)
 Add to a counter.

QCassandraCelloperator-- ()
 Decrement a counter.

QCassandraCelloperator-- (int)
 Decrement a counter.

QCassandraCelloperator-= (int64_t value)
 Subtract from a counter.

QCassandraCelloperator= (const QCassandraValue &value)
 Set the cell value.

void setConsistencyLevel (consistency_level_t level)
 Define the consistency level of this cell.

void setTimestamp (int64_t timestamp)
 Define your own timestamp for this cell value.

void setValue (const QCassandraValue &value)
 Change the value.

int64_t timestamp () const
 Retrieve the current timestamp of this cell value.

const QCassandraValuevalue () const
 Retrieve the cell value.

Private Member Functions

 QCassandraCell (QCassandraRow *row, const QByteArray &column_key)
 Initialize a QCassandraRow object.

void assignValue (const QCassandraValue &value)
 Change the value as if read from Cassandra.

void unparent ()
 Internal function used to remove the parent row.

Private Attributes

controlled_vars::fbool_t f_cached
 Whether a cell is a cache.

QByteArray f_key
 The column name of this cell.

QCassandraRowf_row
 A pointer back to the row onwer.

QCassandraValue f_value
 A cell value.

Friends

class QCassandraRow
class QCassandraTable

Detailed Description

A cell represents the value of a column in a row. The name of a cell is the name of the corresponding column. The value is the data saved in the Cassandra database.

The name of the cell is kept as a binary key (it can be binary.) It is limited it length to a little under 64Kb.

Cells are loaded from the Cassandra database whenever the user reads its value. Actually, the value is marked as cached once read the first time. Each further access is done using the memory value thus avoiding accessing the Cassandra server each time. Note that may have some side effects if your process runs for a long time. Use the cell, row, table, or context clearCache() functions to palliate to this problem.

Cells are saved to the Cassandra database whenever the user overwrite its current value. In this case the cache is updated but the data is non the less written to Cassandra except if the value was not modified and the cache was marked as active.

Definition at line 51 of file QCassandraCell.h.


Constructor & Destructor Documentation

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

Definition at line 145 of file QCassandraCell.cpp.

QtCassandra::QCassandraCell::QCassandraCell ( QCassandraRow row,
const QByteArray &  column_key 
) [private]

This function initializes a QCassandraCell object. You must specify the key of the column.

In this case, the key of the cell is a binary buffer of data. Remember however that the column names that are not ASCII may cause problems (i.e. with CQL and the Cassandra CLI.)

A cell is set to the NULL value by default.

Exceptions:
std::runtime_errorThe key of the column cannot be empty or more than 64Kb. If that happens, this exception is raised.
Parameters:
[in]rowThe parent row of this cell.
[in]column_keyThe binary key of this cell.

Definition at line 126 of file QCassandraCell.cpp.

References f_key.


Member Function Documentation

void QtCassandra::QCassandraCell::add ( int64_t  value)

This function is used to add a value to a counter.

The current cell value is expected to be 8 bytes, although we support 1, 2, 4, and 8 byte integers. The result is saved back in this cell as a 64 bits value (8 bytes).

Parameters:
[in]valueThe value to add to the counter. It may be negative.
Returns:
The expected value defined in the cell.

Definition at line 358 of file QCassandraCell.cpp.

References QtCassandra::QCassandraRow::addValue(), f_cached, f_key, f_row, f_value, QtCassandra::QCassandraValue::int16Value(), QtCassandra::QCassandraValue::int32Value(), QtCassandra::QCassandraValue::int64Value(), QtCassandra::QCassandraValue::nullValue(), QtCassandra::QCassandraValue::setInt64Value(), QtCassandra::QCassandraValue::signedCharValue(), QtCassandra::QCassandraValue::size(), and value().

Referenced by operator++(), operator+=(), operator--(), and operator-=().

void QtCassandra::QCassandraCell::assignValue ( const QCassandraValue value) [private]

This function assigns the specified value as if it had been read from Cassandra. This way the Row can set a value it just read and avoid another read() (or worse, a write!)

The value is marked as cached meaning that it was read or written to the Cassandra database.

This generally happens when you call value(). There is a simplified view of what happens (without the QCassandraRow, QCassandraTable, QCassandra, and Thrift shown):

msc_inline_mscgraph_1

Note that similar calls happen whenever you call QCassandraRow::readCells() and QCassandraTable::readRows().

Parameters:
[in]valueThe new value to assign to this cell.

Definition at line 288 of file QCassandraCell.cpp.

References f_cached, f_value, and value().

This function can be used to mark that the currently cached value need to be reset on the next call to the QCassandraValue casting operator.

However, note that the data of the cell is NOT released by this call. To release the data, look into clearing the row cache instead.

Note:
Setting a cell to the null value (i.e. value.setNullValue()) will clear the data in the Cassandra database too. So don't use that function to clear the data from memory!
See also:
QCassandraRow::clearCache()

Definition at line 553 of file QCassandraCell.cpp.

References f_cached, f_value, and QtCassandra::QCassandraValue::setNullValue().

Referenced by unparent().

const QByteArray & QtCassandra::QCassandraCell::columnKey ( ) const

This function returns the column key of this cell. The key is a binary buffer of data. This function works whether the cell was created with a name or a key.

Note that when creating a cell with a binary key, you cannot retrieve it using the columnName() function.

Returns:
A buffer of data representing the column key.
See also:
columnName()

Definition at line 186 of file QCassandraCell.cpp.

References f_key.

This function returns the name of the column as specified in the constructor.

The name cannot be changed.

Note that if you created the cell with a binary key (i.e. a QByteArray parameter) then you CANNOT retrieve the column name. Instead, use the columnKey() function.

Exceptions:
std::runtime_errorThis function raises an exception if the cell was created with a binary key.
Returns:
A string with the column name.
See also:
rowKey()

Definition at line 168 of file QCassandraCell.cpp.

References f_key.

This function returns the consistency level of this value. By default it is set to one (CONSISTENCY_LEVEL_ONE.)

The consistency level can be set using the setConsistencyLevel() function.

Returns:
The consistency level of this value.
See also:
setConsistencyLevel()
QCassandraValue::consistencyLevel()

Definition at line 584 of file QCassandraCell.cpp.

References QtCassandra::QCassandraValue::consistencyLevel(), and f_value.

QtCassandra::QCassandraCell::operator QCassandraValue ( ) const

This function is called whenever you read a value from the Cassandra database using the array syntax such as:

 QCassandraValue value = cluster["context"]["table"]["row"]["column"];

Note that the value gets cached. That means if you call the function again, then the same value will be returned (although the setValue() can be used to change the cached value.)

To reset the cache, use the clearCache() function.

Returns:
The current value defined in the cell
See also:
clearCache()
setValue()

Definition at line 341 of file QCassandraCell.cpp.

References value().

QCassandraCell & QtCassandra::QCassandraCell::operator++ ( )

This operator is used to add one to a counter.

 ++cluster["context"]["table"]["row"]["column"];
Returns:
A reference to this Cassandra cell.
See also:
add()
operator + ()

Definition at line 436 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator++ ( int  )

This operator is used to add one to a counter.

 cluster["context"]["table"]["row"]["column"]++;
Warning:
Note that this operator returns this QCassandraCell and not a copy because we cannot create a copy of the cell.
Returns:
A reference to this Cassandra cell.
See also:
add()
operator + ()

Definition at line 459 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator+= ( int64_t  value)

This operator adds a value to a counter.

 cluster["context"]["table"]["row"]["column"] += 5;

Note that the resulting value gets cached. That means if reading the value after this call, the cached value is returned. To reset the cache, use the clearCache() function.

Warning:
The value in the cell after this call is an approximation of the counter value. The operator does not read the most current value.
Parameters:
[in]valueThe value to add to the existing value of this cell.
Returns:
A reference to this Cassandra cell.
See also:
clearCache()
add()

Definition at line 417 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator-- ( )

This operator is used to subtract one from a counter.

 --cluster["context"]["table"]["row"]["column"];
Returns:
A reference to this Cassandra cell.
See also:
add()
operator - ()

Definition at line 507 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator-- ( int  )

This operator is used to subtract one from a counter.

 cluster["context"]["table"]["row"]["column"]--;
Warning:
Note that this operator returns this QCassandraCell and not a copy because we cannot create a copy of the cell.
Returns:
A reference to this Cassandra cell.
See also:
add()
operator - ()

Definition at line 530 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator-= ( int64_t  value)

This operator subtract a value from a counter.

 cluster["context"]["table"]["row"]["column"] -= 9;

Note that the resulting value gets cached. That means if reading the value after this call, the cached value is returned. To reset the cache, use the clearCache() function.

Warning:
The value in the cell after this call is an approximation of the counter value. The operator does not read the most current value.
Parameters:
[in]valueThe value to subtract from the current content of the cell.
Returns:
A reference to this Cassandra cell.
See also:
clearCache()
add()

Definition at line 488 of file QCassandraCell.cpp.

References add().

QCassandraCell & QtCassandra::QCassandraCell::operator= ( const QCassandraValue value)

This function is called whenever you write a value to the Cassandra database using the array syntax such as:

 cluster["context"]["table"]["row"]["column"] = value;

Note that the value gets cached. That means if you call a getValue() function, you get a copy of the value you saved here.

To reset the cache, use the clearCache() function.

Parameters:
[in]valueThe new cell value.
Returns:
A reference to this cell.
See also:
clearCache()
setValue()

Definition at line 315 of file QCassandraCell.cpp.

References setValue().

This function sets the consistency of the f_value field of this cell. This can be used to ensure the proper consistency on a read. In case of a write, the consistency is always taken from the value parameter. For a read this is the only way to specify the consistency.

By default, the consistency level is set to CONSISTENCY_LEVEL_DEFAULT which means: use the consistency level defined in the QCassandra object linked with this cell. It is possible to set the consistency level back to CONSISTENCY_LEVEL_DEFAULT.

Parameters:
[in]levelThe new consistency level for this cell next read.
See also:
consistencyLevel()
QCassandraValue::setConsistencyLevel()

Definition at line 606 of file QCassandraCell.cpp.

References f_value, and QtCassandra::QCassandraValue::setConsistencyLevel().

void QtCassandra::QCassandraCell::setTimestamp ( int64_t  timestamp)

Set the timestamp of the value variable member of this cell.

Parameters:
[in]timestampThe time used to mark this value.
See also:
timestamp()
QCassandraValue::setTimestamp()

Definition at line 636 of file QCassandraCell.cpp.

References f_value, and QtCassandra::QCassandraValue::setTimestamp().

This function changes the value of this cell. If the cell is currently attached to a table in the Cassandra server, then it is written to the server except if the value does not change.

In other words, we avoid sending the same value to the Cassandra server over and over again. To force a write to the Cassandra server, call the clearCache() function before the setValue() function.

Todo:
If setting a counter, "value" is save in the cache as is. This means the value may be an integer of any size instead of being a 64 bit integer.
Note:
When the values are compared, the timestamp is ignored.
Parameters:
[in]valueThe new value for this cell.

Definition at line 238 of file QCassandraCell.cpp.

References f_cached, f_key, f_row, f_value, QtCassandra::QCassandraRow::insertValue(), and value().

Referenced by operator=().

This function returns the timestamp of the value variable member defined in the cell. This value may be incorrect if the value wasn't read from the Cassandra database or was never set with setTimestamp().

Returns:
The timestamp 64bit value.
See also:
setTimestamp()
QCassandraValue::timestamp()

Definition at line 622 of file QCassandraCell.cpp.

References f_value, and QtCassandra::QCassandraValue::timestamp().

This function is used to mark the cell as "lost". It is used whenever the user calls QCassandraRow::dropCell(). It is expected that after such a call the cell will not be used again.

Definition at line 566 of file QCassandraCell.cpp.

References clearCache(), and f_row.

This function is used to retrieve the cell value.

Note that the value gets cached. That means if you call the function again, then the same value will be returned (although the setValue() can be used to change the cached value.)

To reset the cache, use the clearCache() function.

Returns:
The current value defined in the cell
See also:
clearCache()
setValue()

Definition at line 206 of file QCassandraCell.cpp.

References f_cached, f_key, f_row, f_value, and QtCassandra::QCassandraRow::getValue().

Referenced by add(), assignValue(), operator QCassandraValue(), and setValue().


Friends And Related Function Documentation

friend class QCassandraRow [friend]

Definition at line 86 of file QCassandraCell.h.

friend class QCassandraTable [friend]

Definition at line 87 of file QCassandraCell.h.


Member Data Documentation

This flag mark the cell as being a cache for the value defined in it. By default a cell is marked as not caching anything. It becomes a cached value once the value was saved in the Cassandra database or read from the Cassandra system.

Note however that the cell is no aware of whether the table is a memory or Cassandra table. As such, the cache flag may be lying.

Definition at line 91 of file QCassandraCell.h.

Referenced by add(), assignValue(), clearCache(), setValue(), and value().

This cell has a name paired with its value. This is the name part. The key is saved in binary form only.

Definition at line 90 of file QCassandraCell.h.

Referenced by add(), columnKey(), columnName(), QCassandraCell(), setValue(), and value().

This bare pointer back to the row owner is used whenever the value is read (and not yet cached) or written. This way we can send the data back to the Cassandra database.

Definition at line 89 of file QCassandraCell.h.

Referenced by add(), setValue(), unparent(), and value().

This member represents the value of this cell.

Note that by default when you copy a cell value the value buffer itself is not copied, instead it is shared. This is quite useful to avoid many memory copies.

Definition at line 92 of file QCassandraCell.h.

Referenced by add(), assignValue(), clearCache(), consistencyLevel(), setConsistencyLevel(), setTimestamp(), setValue(), timestamp(), and value().


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