Dataquay::ObjectMapper Class Reference

ObjectMapper manages a set of objects, maintaining a consistent record of their state in a TransactionalStore by mapping changes in both directions between objects and store. More...

#include <dataquay/objectmapper/ObjectMapper.h>

Inheritance diagram for Dataquay::ObjectMapper:

Public Slots
void	add (QObject *)
	Add a new object to the store.
void	add (QObjectList)
	Add a list of new objects to the store.
void	manage (QObject *)
	Tell ObjectMapper to start managing an object.
void	manage (QObjectList)
	Tell ObjectMapper to start managing a list of objects.
void	unmanage (QObject *)
	Tell ObjectMapper to stop managing the given object.
void	unmanage (QObjectList)
	Tell ObjectMapper to stop managing the given objects.
void	commit ()
	Commit to the store any changes that have happened to the currently managed objects since the last commit.
ChangeSet	commitAndObtain ()
	Commit to the store any changes that have happened to the currently managed objects since the last commit, and return the changes committed.
void	objectModified (QObject *)
	Notify ObjectMapper that the given object has changed.
void	objectDestroyed (QObject *)
	Notify ObjectMapper that the given object is being destroyed.

Signals
void	committed ()

Public Member Functions
	ObjectMapper (TransactionalStore *ts)
	Construct an object mapper backed by the given store.
	~ObjectMapper ()
TransactionalStore *	getStore ()
	Obtain the TransactionalStore that was passed to the constructor.
void	setTypeMapping (const TypeMapping &)
	Supply a TypeMapping object describing the RDF URIs that should be used to encode each object's property and class names.
const TypeMapping &	getTypeMapping () const
	Obtain the TypeMapping previously set using setTypeMapping, or the default (empty) TypeMapping if none has been set.
void	setBlankNodePolicy (BlankNodePolicy policy)
	Set the policy used to determine whether to give an object a URI or use a blank node for it.
BlankNodePolicy	getBlankNodePolicy () const
	Retrieve the current policy used to determine whether to give an object a URI or use a blank node for it.
Node	getNodeForObject (QObject *o) const
	Obtain the RDF node to which the given object has been mapped, or a null Node if the object has not yet been stored by this ObjectMapper.
QObject *	getObjectByNode (Node n) const
	Obtain the QObject which has been mapped to the given node, or NULL if the node is not one that has been stored by this ObjectMapper.
QObject *	load (Node node)
	!!doc
QObjectList	loadType (Uri type)
	!!doc

Detailed Description

ObjectMapper manages a set of objects, maintaining a consistent record of their state in a TransactionalStore by mapping changes in both directions between objects and store.

It uses ObjectStorer to map objects (derived from QObject) to the store, and then watches both the objects and the store for changes, applying to the store any changes in the objects and using ObjectLoader to bring the objects up to date with any changes in the store.

See ObjectStorer for details of how objects are mapped to the RDF store, and ObjectLoader for details of how changes in the RDF store are mapped back to the objects.

ObjectMapper watches QObject properties' notify signals to determine when a property has changed, and uses QObject::destroyed to determine when an object has been deleted. You can also advise it of changes using the objectModified slot directly (for example where a property has no notify signal).

ObjectMapper requires a TransactionalStore as its backing RDF store, and uses the TransactionalStore's transactionCommitted signal to tell it when a change has been made to the store which should be mapped back to the object structure.

You must call the commit() method to cause any changes to be written to the store. This also commits the underlying transaction.

Call add() to add a new object to the store (managing it, and also marking it to be stored on the next commit). ObjectMapper does not have any other way to find out about new objects, even if they are properties or children of existing managed objects.

Alternatively, call manage() to manage an object without marking it as needing to be written – implying that the object is known to be up-to-date with the store already. ObjectMapper will refuse to manage any object that lacks a uri property, as any objects that have not previously been mapped will normally need to be add()ed (which gives them URIs) rather than manage()d.

It is safe to call add() or manage() with an object that is already managed; if add() is called with such an object it will be rescheduled to be stored, but there will be no other effect.

Call unmanage() to tell ObjectMapper to stop watching an object. You should not call this when the object is destroyed, unless you want to ensure that destroying it does not remove it from the store. Managed objects are automatically monitored for destruction and removed from the store and unmanaged appropriately.

ObjectMapper is thread-safe.

Definition at line 104 of file ObjectMapper.h.

Constructor & Destructor Documentation

ObjectMapper()

Dataquay::ObjectMapper::ObjectMapper

(

TransactionalStore *

ts

)

Construct an object mapper backed by the given store.

The mapper is initially managing no objects.

The store must be a TransactionalStore (rather than for example a BasicStore) because the object mapper commits each update as a single transaction and relies on the TransactionalStore::transactionCommitted signal to learn about changes in the store.

~ObjectMapper()

Dataquay::ObjectMapper::~ObjectMapper

(

)

Member Function Documentation

getStore()

TransactionalStore * Dataquay::ObjectMapper::getStore

(

)

Obtain the TransactionalStore that was passed to the constructor.

setTypeMapping()

void Dataquay::ObjectMapper::setTypeMapping

(

const TypeMapping &

)

Supply a TypeMapping object describing the RDF URIs that should be used to encode each object's property and class names.

Without this, ObjectMapper (or rather its ObjectStorer and ObjectLoader classes) will generate suitable-looking URIs for each class and property names.

getTypeMapping()

const TypeMapping & Dataquay::ObjectMapper::getTypeMapping

(

)

const

Obtain the TypeMapping previously set using setTypeMapping, or the default (empty) TypeMapping if none has been set.

setBlankNodePolicy()

void Dataquay::ObjectMapper::setBlankNodePolicy

(

BlankNodePolicy

policy

)

Set the policy used to determine whether to give an object a URI or use a blank node for it.

The default is BlankNodesAsNeeded.

getBlankNodePolicy()

BlankNodePolicy Dataquay::ObjectMapper::getBlankNodePolicy

(

)

const

Retrieve the current policy used to determine whether to give an object a URI or use a blank node for it.

getNodeForObject()

Node Dataquay::ObjectMapper::getNodeForObject

(

QObject *

o

)

const

Obtain the RDF node to which the given object has been mapped, or a null Node if the object has not yet been stored by this ObjectMapper.

getObjectByNode()

QObject * Dataquay::ObjectMapper::getObjectByNode

(

Node

n

)

const

Obtain the QObject which has been mapped to the given node, or NULL if the node is not one that has been stored by this ObjectMapper.

load()

QObject * Dataquay::ObjectMapper::load

(

Node

node

)

!!doc

loadType()

QObjectList Dataquay::ObjectMapper::loadType

(

Uri

type

)

!!doc

committed

void Dataquay::ObjectMapper::committed ( )

signal

add [1/2]

void Dataquay::ObjectMapper::add ( QObject * )

slot

Add a new object to the store.

This tells ObjectMapper to manage the object, and also marks it to be stored the next time commit is called.

You must call add or manage for every new object that needs to be managed; ObjectMapper does not have any other way to find out about new objects, even if they are properties or children of existing managed objects. !!! above is no longer correct (anything stored or loaded is managed automatically), document

add [2/2]

void Dataquay::ObjectMapper::add ( QObjectList )

slot

Add a list of new objects to the store.

This tells ObjectMapper to manage the objects, and also marks them to be stored the next time commit is called.

You must call add or manage for every new object that needs to be managed; ObjectMapper does not have any other way to find out about new objects, even if they are properties or children of existing managed objects. !!! above is no longer correct (anything stored or loaded is managed automatically), document

manage [1/2]

void Dataquay::ObjectMapper::manage ( QObject * )

slot

Tell ObjectMapper to start managing an object.

This tells ObjectMapper to watch the object and commit to the store any changes that it detects in the object's properties, or when the object is destroyed. If the object was managed already, nothing happens.

This does not mark the object as needing to be written; it implies that the object is known to be up-to-date with the store already. ObjectMapper will refuse to manage any object that lacks a uri property; if your object is a "new" one, you should use add instead of manage. !!! above is no longer enough (anything stored or loaded is managed automatically), document

manage [2/2]

void Dataquay::ObjectMapper::manage ( QObjectList )

slot

Tell ObjectMapper to start managing a list of objects.

This tells ObjectMapper to watch the objects and commit to the store any changes that it detects in the objects' properties, or when the objects are destroyed.

Any objects that were managed already are ignored: there is no harm in passing them more than once, except a small time penalty.

This does not mark the objects as needing to be written; it implies that the objects are known to be up-to-date with the store already. ObjectMapper will refuse to manage any object that lacks a uri property; if your object is a "new" one, you should use add instead of manage. !!! above is no longer enough (anything stored or loaded is managed automatically), document

unmanage [1/2]

void Dataquay::ObjectMapper::unmanage ( QObject * )

slot

Tell ObjectMapper to stop managing the given object.

unmanage [2/2]

void Dataquay::ObjectMapper::unmanage ( QObjectList )

slot

Tell ObjectMapper to stop managing the given objects.

commit

void Dataquay::ObjectMapper::commit ( )

slot

Commit to the store any changes that have happened to the currently managed objects since the last commit.

You need to call this (or commitAndObtain) if you want any changes to appear in the store.

commitAndObtain

ChangeSet Dataquay::ObjectMapper::commitAndObtain ( )

slot

Commit to the store any changes that have happened to the currently managed objects since the last commit, and return the changes committed.

You need to call this (or commit) if you want any changes to appear in the store.

objectModified

void Dataquay::ObjectMapper::objectModified ( QObject * )

slot

Notify ObjectMapper that the given object has changed.

ObjectMapper automatically watches the notify signals for an object's properties, but it will not spot any changes that do not have an associated notify signal.

objectDestroyed

void Dataquay::ObjectMapper::objectDestroyed ( QObject * )

slot

Notify ObjectMapper that the given object is being destroyed.

This should not normally be necessary, as ObjectMapper automatically watches the destroyed signals for objects it manages.

---

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

• ObjectMapper.h