libQtCassandra: QtCassandra::QCassandraCell Class Reference

libQtCassandra 1.0

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

#include <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 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.

 operator QCassandraValue () const
 Retrieve the cell value.

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

void setValue (const QCassandraValue &value)
 Change the 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::zbool_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 52 of file QCassandraCell.h.


Constructor & Destructor Documentation

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

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

Definition at line 142 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 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::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 worst, 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):

inline_mscgraph_3

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 278 of file QCassandraCell.cpp.

References f_cached, f_value, and value().

void QtCassandra::QCassandraCell::clearCache ( )

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 353 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 183 of file QCassandraCell.cpp.

References f_key.

QString QtCassandra::QCassandraCell::columnName ( ) const

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 165 of file QCassandraCell.cpp.

References f_key.

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 331 of file QCassandraCell.cpp.

References value().

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 305 of file QCassandraCell.cpp.

References setValue().

void QtCassandra::QCassandraCell::setValue ( const QCassandraValue value)

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.

Note:
When the values are compared, the timestamp is ignored.
Parameters:
[in]valueThe new value for this cell.

Definition at line 230 of file QCassandraCell.cpp.

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

Referenced by operator=().

void QtCassandra::QCassandraCell::unparent ( ) [private]

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 366 of file QCassandraCell.cpp.

References clearCache(), and f_row.

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

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 203 of file QCassandraCell.cpp.

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

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


Friends And Related Function Documentation

friend class QCassandraRow [friend]

Definition at line 73 of file QCassandraCell.h.

friend class QCassandraTable [friend]

Definition at line 74 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 78 of file QCassandraCell.h.

Referenced by 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 77 of file QCassandraCell.h.

Referenced by 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 76 of file QCassandraCell.h.

Referenced by 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 79 of file QCassandraCell.h.

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


The documentation for this class was generated from the following files:
  • /home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/include/QtCassandra/QCassandraCell.h
  • /home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/src/QCassandraCell.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