Represents a backing store for persistent object storage. More...

#include <Storage.hpp>

Inheritance diagram for Sirikata::OH::Storage:

Collaboration diagram for Sirikata::OH::Storage:

Public Types
enum	Result { SUCCESS = 0, LOCK_ERROR = 1, TRANSACTION_ERROR = 2 }
	Small number of results. More...
typedef UUID	Bucket
typedef String	Key
typedef std::tr1::unordered_map< Key, String >	ReadSet
typedef std::tr1::function < void(Result result, ReadSet *rs)	CommitCallback )
	CommitCallbacks are invoked when a response is received back from the underlying storage system (or timeout occurs).
typedef std::tr1::function < void(Result result, int32 count)>	CountCallback
Public Member Functions
virtual	~Storage ()
virtual void	start ()
	Service Interface.
virtual void	stop ()
virtual void	leaseBucket (const Bucket &bucket)=0
	Trigger a lease on a bucket.
virtual void	releaseBucket (const Bucket &bucket)=0
	Release whatever lease or lock was acquired by the corresponding call to leaseBucket.
virtual void	beginTransaction (const Bucket &bucket)=0
	Begin a transaction.
virtual void	commitTransaction (const Bucket &bucket, const CommitCallback &cb=0, const String &timestamp="current")=0
	Completes a transaction and requests that it be written to Flushes all outstanding events (writes and removes) from pending queue.
virtual bool	erase (const Bucket &bucket, const Key &key, const CommitCallback &cb=0, const String &timestamp="current")=0
virtual bool	write (const Bucket &bucket, const Key &key, const String &value, const CommitCallback &cb=0, const String &timestamp="current")=0
	Queues writes to the item named by entryName:itemName.
virtual bool	read (const Bucket &bucket, const Key &key, const CommitCallback &cb=0, const String &timestamp="current")=0
virtual bool	rangeRead (const Bucket &bucket, const Key &start, const Key &finish, const CommitCallback &cb=0, const String &timestamp="current")=0
virtual bool	compare (const Bucket &bucket, const Key &key, const String &value, const CommitCallback &cb=0, const String &timestamp="current")=0
	Add a comparison operation to the transaction.
virtual bool	rangeErase (const Bucket &bucket, const Key &start, const Key &finish, const CommitCallback &cb=0, const String &timestamp="current")=0
virtual bool	count (const Bucket &bucket, const Key &start, const Key &finish, const CountCallback &cb=0, const String &timestamp="current")=0

Detailed Description

Represents a backing store for persistent object storage.

Each object is assigned an identifier which maps to a 'bucket' of values in the backing store, keeping each object isolated. Within that bucket, objects can write to keys, specified as strings.

Storage implementations *must* support transactions for atomic commits to multiple keys. There are two modes - transactions and single-key operations. In transactional mode, you call beginTransaction(), call other methods to add operations to the transaction, and finally call commit() to run the transaction. Single-key operations are called without any surrounding invokations of transaction methods. The implementation can send them to be performed immediately. Single-key operations are really transactions, but elide the beginTransaction() and commit() calls.

Ordering of transactions (and single-key transactions) are not guaranteed: if you need to ensure operations happen in order you should either batch them in a transaction or wait for the callback for each one before processing the next.

Implementations may use locks or leases to implement transactions. In that case, it is possible that they fail to execute a transaction because the database is currently locked. Users are responsible for resolving these problems by retrying or dropping the transaction. Implementations can expose control over leases and locks via their settings so they can, e.g., ensure only one OH accesses a storage bucket at once.

Member Typedef Documentation

typedef UUID Sirikata::OH::Storage::Bucket

typedef std::tr1::function<void(Result result, ReadSet* rs) Sirikata::OH::Storage::CommitCallback)

CommitCallbacks are invoked when a response is received back from the underlying storage system (or timeout occurs).

If successful, the second parameter contains the values of any read operations that were requested (or is NULL if none were requested). If non-empty, ownership transfers to the caller.

typedef std::tr1::function<void(Result result, int32 count)> Sirikata::OH::Storage::CountCallback

typedef String Sirikata::OH::Storage::Key

typedef std::tr1::unordered_map<Key, String> Sirikata::OH::Storage::ReadSet

Member Enumeration Documentation

enum Sirikata::OH::Storage::Result

Small number of results.

These indicate a few standard error conditions or success.

Enumerator:

SUCCESS
LOCK_ERROR
TRANSACTION_ERROR

Constructor & Destructor Documentation

virtual Sirikata::OH::Storage::~Storage ( ) [inline, virtual]

Member Function Documentation

virtual void Sirikata::OH::Storage::beginTransaction ( const Bucket & bucket ) [pure virtual]

Begin a transaction.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageBeginTransaction().

virtual void Sirikata::OH::Storage::commitTransaction	(	const Bucket &	bucket,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Completes a transaction and requests that it be written to Flushes all outstanding events (writes and removes) from pending queue.

Resets pending queue as well.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageCommit().

virtual bool Sirikata::OH::Storage::compare	(	const Bucket &	bucket,
		const Key &	key,
		const String &	value,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Add a comparison operation to the transaction.

The given key is read and compared to the value. If the comparison is false, it causes the entire transaction to fail.

Parameters:

{Key}	key the key to compare to
{String}	value What should be written into that item
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the read is queued, false otherwise. Does not indicated success of actual read operation.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

virtual bool Sirikata::OH::Storage::count	(	const Bucket &	bucket,
		const Key &	start,
		const Key &	finish,
		const CountCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Parameters:

{Key}	from the start key of range of keys to count
{Key}	finish the end key of range of keys to count
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if operation is successful, false otherwise

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageCount().

virtual bool Sirikata::OH::Storage::erase	(	const Bucket &	bucket,
		const Key &	key,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Parameters:

{Key}	key the key to erase
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the erase is queued, false otherwise. Does not indicated success of actual erase operation.

Queues the item to be removed from the backend. Does not actually delete until the flush operation is called.

Erasing a non-existant key does not cause an error -- it's just treated as a noop. If you care that a key is actually erase, use a compare + delete combination.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageErase().

virtual void Sirikata::OH::Storage::leaseBucket ( const Bucket & bucket ) [pure virtual]

Trigger a lease on a bucket.

This is just a signal to the storage layer that it should try to make sure it can commit transactions for the bucket. Depending on the implementation and options, this could mean anything from doing nothing (single process, local operation) to a full lease or lock (distributed storage).

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::HostedObject::initializeScript().

virtual bool Sirikata::OH::Storage::rangeErase	(	const Bucket &	bucket,
		const Key &	start,
		const Key &	finish,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Parameters:

{Key}	from the start key of range of keys to erase
{Key}	finish the end key of range of keys to erase
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the read is queued, false otherwise. Does not indicated success of actual erase operation.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageRangeErase().

virtual bool Sirikata::OH::Storage::rangeRead	(	const Bucket &	bucket,
		const Key &	start,
		const Key &	finish,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Parameters:

{Key}	from the start key of range of keys to read
{Key}	finish the end key of range of keys to read
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the read is queued, false otherwise. Does not indicated success of actual read operation.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageRangeRead().

virtual bool Sirikata::OH::Storage::read	(	const Bucket &	bucket,
		const Key &	key,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Parameters:

{Key}	key the key to read
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the read is queued, false otherwise. Does not indicated success of actual read operation.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageRead().

virtual void Sirikata::OH::Storage::releaseBucket ( const Bucket & bucket ) [pure virtual]

Release whatever lease or lock was acquired by the corresponding call to leaseBucket.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::HostedObject::destroy(), and Sirikata::HostedObject::stop().

virtual void Sirikata::OH::Storage::start ( ) [inline, virtual]

Service Interface.

Implements Sirikata::Service.

Reimplemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

virtual void Sirikata::OH::Storage::stop ( ) [inline, virtual]

Implements Sirikata::Service.

Reimplemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

virtual bool Sirikata::OH::Storage::write	(	const Bucket &	bucket,
		const Key &	key,
		const String &	value,
		const CommitCallback &	cb = `0`,
		const String &	timestamp = `"current"`
	)		`[pure virtual]`

Queues writes to the item named by entryName:itemName.

Writes will not be committed until flush command. Note, if issue this command multiple times with the same entryName:itemName, will only process the last when calling flush.

Parameters:

{Key}	key the key to erase
{String}	value What should be written into that item
{CommitCallback}	cb optional commit callback which is invoked if this is a single operation transaction.
{String}	timestamp the timestamp of the operation

Returns:: {bool} true if the write is queued, false otherwise. Does not indicated success of actual write operation.

Implemented in Sirikata::OH::CassandraStorage, and Sirikata::OH::SQLiteStorage.

Referenced by Sirikata::JS::JSObjectScript::eStorageWrite().

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

liboh/include/sirikata/oh/Storage.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation