libQtCassandra: QtCassandra::QCassandraRow Class Reference

libQtCassandra 1.0

The row class to hold a set of cells. More...

#include <QCassandraRow.h>

Inheritance diagram for QtCassandra::QCassandraRow:
Collaboration diagram for QtCassandra::QCassandraRow:

List of all members.

Public Member Functions

virtual ~QCassandraRow ()
 Clean up the QCassandraRow object.

QSharedPointer< QCassandraCellcell (const QString &column_name)
 Retrieve a cell from the row.

QSharedPointer< QCassandraCellcell (const QByteArray &column_key)
 Retrieve a cell from the row.

int cellCount (const QCassandraColumnPredicate &column_predicate=QCassandraColumnPredicate())
 Retrieve the number of cells defined in this row.

const QCassandraCellscells () const
 Retrieve the map of cells.

void clearCache ()
 Clear the cached cells.

void dropCell (const QByteArray &column_key, QCassandraValue::timestamp_mode_t mode=QCassandraValue::TIMESTAMP_MODE_AUTO, int64_t timestamp=0)
 Drop the specified cell from the Cassandra database.

void dropCell (const QString &column_name, QCassandraValue::timestamp_mode_t mode=QCassandraValue::TIMESTAMP_MODE_AUTO, int64_t timestamp=0)
 Drop the named cell.

bool exists (const QString &column_name) const
 Check whether a cell exists in this row.

bool exists (const QByteArray &column_key) const
 Check whether a cell exists in this row.

QSharedPointer< QCassandraCellfindCell (const QByteArray &column_key) const
 Retrieve a cell from the row.

QSharedPointer< QCassandraCellfindCell (const QString &column_name) const
 Retrieve a cell from the row.

const QCassandraCelloperator[] (const QString &column_name) const
 Retrieve a cell from the row.

const QCassandraCelloperator[] (const QByteArray &column_key) const
 Retrieve a cell from the row.

QCassandraCelloperator[] (const QByteArray &column_key)
 Retrieve a cell from the row.

QCassandraCelloperator[] (const QString &column_name)
 Retrieve a cell from the row.

void readCells (const QCassandraColumnPredicate &column_predicate=QCassandraColumnPredicate())
 Read the cells as defined by the predicate.

const QByteArray & rowKey () const
 Retrieve the row key.

QString rowName () const
 Retrieve the name of the row.

Private Member Functions

 QCassandraRow (QCassandraTable *table, const QByteArray &row_key)
 Initialize a QCassandraRow object.

void getValue (const QByteArray &column_key, QCassandraValue &value)
 Get a cell value from Cassandra.

void insertValue (const QByteArray &column_key, const QCassandraValue &value)
 Save a cell value that changed.

void unparent ()
 This internal function marks the row as unusable.

Private Attributes

QCassandraCells f_cells
 The array of cells defined in this row.

QByteArray f_key
 The binary key of the row.

QCassandraTablef_table
 The table this row is part of.

Friends

class QCassandraCell
class QCassandraTable

Detailed Description

These objects are created by the QCassandraTable whenever data is being read or written to a cell. Rows have a binary key (may be set as a UTF-8 string) and a map of cells indexed by the names of the cells.

The name of a row is limited to nearly 64Kb. Although, if you have a table with very long names, you may want to consider computing an md5sum or equivalent. This is important if you want to avoid slowing down the Cassandra server. Searching through a large set of 60Kb keys is much slower than doing the same through their md5sums. Of course, that means you lose the automatic sorting of the original key.

By default, most of the functions will create a new cell. If you need to test the existance without creating a cell, use the exists() function with the column name of the cell check out.

See also:
exists()

Definition at line 48 of file QCassandraRow.h.


Constructor & Destructor Documentation

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

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

Definition at line 122 of file QCassandraRow.cpp.

QtCassandra::QCassandraRow::QCassandraRow ( QCassandraTable table,
const QByteArray &  row_key 
) [private]

This function initializes a QCassandraRow object. You must specify the key of the row and that's the only parameter that a row supports at this time.

The key of the row is a binary buffer of data.

A row is composed of multiple cells (called columns in Cassandra.)

Parameters:
[in]tableThe parent table of this row.
[in]row_keyThe key of this row.

Definition at line 107 of file QCassandraRow.cpp.

References f_key.


Member Function Documentation

QSharedPointer< QCassandraCell > QtCassandra::QCassandraRow::cell ( const QString &  column_name)

This function retrieves a cell from this row. If the cell does not exist, it is created.

Note that the cell is not saved in the Cassandra database unless you save a value in it (and assuming the context does not only exist in memory.)

This function accepts a column name. The UTF-8 version of it is used to retrieve the data from Cassandra.

Parameters:
[in]column_nameThe name of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 226 of file QCassandraRow.cpp.

Referenced by dropCell(), exists(), and operator[]().

QSharedPointer< QCassandraCell > QtCassandra::QCassandraRow::cell ( const QByteArray &  column_key)

This function retrieves a cell from this row. If the cell does not exist, it is created.

Note that the cell is not saved in the Cassandra database unless you save a value in it (and assuming the context does not only exist in memory.)

This function makes use of a binary key to reference the cell.

Parameters:
[in]column_keyThe binary key of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 246 of file QCassandraRow.cpp.

References f_cells, and QCassandraCell.

int QtCassandra::QCassandraRow::cellCount ( const QCassandraColumnPredicate column_predicate = QCassandraColumnPredicate())

This function retrieves the number of cells currently defined in this row, depending on the specified predicate (by default, all the cells.)

This counts the number of cells available in the Cassandra database. It may be different from the number of cells in the memory cache. (i.e. the value returned by cells().size())

Parameters:
[in]column_predicateThe predicate used to select which columns to count.
Returns:
The number of cells defined in this row.
See also:
cells()

Definition at line 179 of file QCassandraRow.cpp.

References f_key, f_table, and QtCassandra::QCassandraTable::getCellCount().

const QCassandraCells & QtCassandra::QCassandraRow::cells ( ) const

This function returns a constant reference to the map of cells defined in the row.

This map does not generally represent all the cells of a row as only those that you already accessed in read or write mode will be defined in memory.

Returns:
The map of cells referenced by column keys.

Definition at line 270 of file QCassandraRow.cpp.

References f_cells.

void QtCassandra::QCassandraRow::clearCache ( )

This function is used to clear all the cells that were cached in this row.

As a side effect, all the QCassandraCell objects are unparented which means that you cannot use them anymore (doing so raises an exception.)

Definition at line 458 of file QCassandraRow.cpp.

References f_cells.

Referenced by unparent().

void QtCassandra::QCassandraRow::dropCell ( const QByteArray &  column_key,
QCassandraValue::timestamp_mode_t  mode = QCassandraValue::TIMESTAMP_MODE_AUTO,
int64_t  timestamp = 0 
)

This function deletes the specified cell and its data from the Cassandra database and from memory.

The timestamp mode can be set to QCassandraValue::TIMESTAMP_MODE_DEFINED in which case the value defined in the timestamp parameter is used by the Cassandra remove() function.

By default the mode parameter is set to QCassandraValue::TIMESTAMP_MODE_AUTO which means that the timestamp value of the cell f_value parameter is used. This will not work right if the timestamp of the cell value was never set properly (i.e. you never read the cell from the Cassandra database and never called the setTimestamp() function on the cell value.)

Warning:
The corresponding cell is marked as dropped, whether you kept a shared pointer of that cell does not make it reusable. You must forget about it after this call.
Parameters:
[in]column_keyA shared pointer to the cell to remove.
[in]modeSpecify the timestamp mode.
[in]timestampSpecify the timestamp to remove only cells that are equal or older.

Definition at line 491 of file QCassandraRow.cpp.

References cell(), f_cells, f_key, f_table, QtCassandra::QCassandraTable::remove(), QtCassandra::QCassandraValue::TIMESTAMP_MODE_AUTO, and QtCassandra::QCassandraValue::TIMESTAMP_MODE_DEFINED.

Referenced by dropCell().

void QtCassandra::QCassandraRow::dropCell ( const QString &  column_name,
QCassandraValue::timestamp_mode_t  mode = QCassandraValue::TIMESTAMP_MODE_AUTO,
int64_t  timestamp = 0 
)

This function is the same as the dropCell() that uses the column key to specify the cell. It simply calls it after changing the column name into a key.

Parameters:
[in]column_nameThe name of the column to drop.
[in]modeSpecify the timestamp mode.
[in]timestampSpecify the timestamp to remove only cells that are equal or older.

Definition at line 525 of file QCassandraRow.cpp.

References dropCell().

bool QtCassandra::QCassandraRow::exists ( const QString &  column_name) const

The check is happening in memory first. If the cell doesn't exist in memory, then the row checks in the Cassandra database.

Parameters:
[in]column_nameThe column name.
Returns:
true if the cell exists, false otherwise.

Definition at line 324 of file QCassandraRow.cpp.

bool QtCassandra::QCassandraRow::exists ( const QByteArray &  column_key) const

The check is happening in memory first. If the cell doesn't exist in memory, then the row checks in the Cassandra database.

Parameters:
[in]column_keyThe column binary key.
Returns:
true if the cell exists, false otherwise.

Definition at line 338 of file QCassandraRow.cpp.

References cell(), f_cells, f_key, f_table, and QtCassandra::QCassandraTable::getValue().

QSharedPointer< QCassandraCell > QtCassandra::QCassandraRow::findCell ( const QString &  column_name) const

This function retrieves a cell from this row. If the cell does not exist, it returns a NULL pointer (i.e. isNull() on the shared pointer returns true.)

This function accepts a column name. The UTF-8 version of it is used to retrieve the data from Cassandra.

Parameters:
[in]column_nameThe name of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 288 of file QCassandraRow.cpp.

Referenced by operator[]().

QSharedPointer< QCassandraCell > QtCassandra::QCassandraRow::findCell ( const QByteArray &  column_key) const

This function retrieves a cell from this row. If the cell does not exist, it returns a NULL pointer (i.e. isNull() on the shared pointer returns true.)

This function makes use of a binary key to reference the cell.

Parameters:
[in]column_keyThe binary key of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 305 of file QCassandraRow.cpp.

References f_cells.

void QtCassandra::QCassandraRow::getValue ( const QByteArray &  column_key,
QCassandraValue value 
) [private]

This function calls the table getValue() function to retrieve the currrent value that defined in a cell.

Parameters:
[in]column_keyThe key used to identify the column.
[out]valueTo return the value of the cell.

Definition at line 554 of file QCassandraRow.cpp.

References f_key, f_table, and QtCassandra::QCassandraTable::getValue().

Referenced by QtCassandra::QCassandraCell::value().

void QtCassandra::QCassandraRow::insertValue ( const QByteArray &  column_key,
const QCassandraValue value 
) [private]

This function calls the table insertValue() function to save the new value that was defined in a cell.

Parameters:
[in]column_keyThe key used to identify the column.
[in]valueThe new value of the cell.

Definition at line 538 of file QCassandraRow.cpp.

References f_key, f_table, and QtCassandra::QCassandraTable::insertValue().

Referenced by QtCassandra::QCassandraCell::setValue().

QCassandraCell & QtCassandra::QCassandraRow::operator[] ( const QByteArray &  column_key)

This function retrieves a reference to a cell from this row in array syntax.

This version returns a writable cell and it creates a new cell when one with the specified name doesn't already exist.

This function makes use of a binary key to reference the cell.

Parameters:
[in]column_keyThe binary key of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 399 of file QCassandraRow.cpp.

References cell().

const QCassandraCell & QtCassandra::QCassandraRow::operator[] ( const QByteArray &  column_key) const

This function retrieves a cell from this row in array syntax.

This version returns a writable cell and it creates a new cell when one with the specified name doesn't already exist.

This function makes use of a binary key to reference the cell.

Parameters:
[in]column_keyThe binary key of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 441 of file QCassandraRow.cpp.

References cell(), and findCell().

const QCassandraCell & QtCassandra::QCassandraRow::operator[] ( const QString &  column_name) const

This function retrieves a constant reference to a cell from this row in array syntax.

This version returns a read-only cell. If the cell doesn't exist, the funtion raises an exception.

This function accepts a column name. The UTF-8 version of it is used to retrieve the data from Cassandra.

Exceptions:
std::runtime_errorThis function requires that the cell being accessed already exist in memory. If not, this exception is raised.
Parameters:
[in]column_nameThe name of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 423 of file QCassandraRow.cpp.

References operator[]().

QCassandraCell & QtCassandra::QCassandraRow::operator[] ( const QString &  column_name)

This function retrieves a reference to a cell from this row in array syntax.

This version returns a writable cell and it creates a new cell when one with the specified name doesn't already exist.

This function accepts a column name. The UTF-8 version of it is used to retrieve the data from Cassandra.

Parameters:
[in]column_nameThe name of the column referencing this cell.
Returns:
A shared pointer to the cell.

Definition at line 380 of file QCassandraRow.cpp.

References cell().

Referenced by operator[]().

void QtCassandra::QCassandraRow::readCells ( const QCassandraColumnPredicate column_predicate = QCassandraColumnPredicate())

This function reads a set of cells as specified by the specified predicate. If you use the default QCassandraColumnPredicate, then the first 100 cells are read.

See the QCassandraColumnPredicate for more information on how to select columns.

This function is often called to read an entire row in memory all at once (this is faster than reading the row one value at a time if you anyway are likely to near most of the columns.)

Parameters:
column_predicateThe predicate used to select which columns to read.

Definition at line 202 of file QCassandraRow.cpp.

References f_key, f_table, and QtCassandra::QCassandraTable::getColumnSlice().

const QByteArray & QtCassandra::QCassandraRow::rowKey ( ) const

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

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

Returns:
A buffer of data representing the row key.
See also:
rowName()

Definition at line 159 of file QCassandraRow.cpp.

References f_key.

QString QtCassandra::QCassandraRow::rowName ( ) const

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

The name cannot be changed.

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

Returns:
A string with the key name.
See also:
rowKey()

Definition at line 141 of file QCassandraRow.cpp.

References f_key.

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

This function is called whenever you drop a row which means that all the data in that row is now not accessible (at least not on Cassandra.)

Any future function call that require the parent will fail with an exception.

Further, this call releases its cells also calling unparent() on them.

Definition at line 572 of file QCassandraRow.cpp.

References clearCache(), and f_table.


Friends And Related Function Documentation

friend class QCassandraCell [friend]

Definition at line 85 of file QCassandraRow.h.

Referenced by cell().

friend class QCassandraTable [friend]

Definition at line 84 of file QCassandraRow.h.


Member Data Documentation

This is a map of cells. Cells are names and values pairs.

The values are defined with a timestamp and ttl value.

Definition at line 92 of file QCassandraRow.h.

Referenced by cell(), cells(), clearCache(), dropCell(), exists(), and findCell().

The binary key of the row is set to UTF-8 when defined with a string. Otherwise it is defined as specified by the user.

Definition at line 91 of file QCassandraRow.h.

Referenced by cellCount(), dropCell(), exists(), getValue(), insertValue(), QCassandraRow(), readCells(), rowKey(), and rowName().

This bare pointer is used to access the table this row is part of. It is a bare pointer because you cannot create a row without having a table and the table keeps a tight reference on the row.

Definition at line 90 of file QCassandraRow.h.

Referenced by cellCount(), dropCell(), exists(), getValue(), insertValue(), readCells(), and unparent().


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