A smart pointer for database objects. More...
#include <Wt/Dbo/ptr>
Inherits Wt::Dbo::ptr_base.
Public Member Functions | |
ptr (C *obj=0) | |
Creates a new pointer. | |
ptr (const ptr< C > &other) | |
Copy constructor. | |
virtual | ~ptr () |
Destructor. | |
void | reset (C *obj=0) |
Resets the pointer. | |
ptr< C > & | operator= (const ptr< C > &other) |
Assignment operator. | |
const C * | operator-> () const |
Dereference operator. | |
const C & | operator* () const |
Dereference operator. | |
C * | modify () const |
Dereference operator, for writing. | |
bool | operator== (const ptr< C > &other) const |
Comparison operator. | |
bool | operator< (const ptr< C > &other) const |
Comparison operator. | |
operator bool () const | |
Checks for null. | |
void | flush () const |
Flushes the object. | |
void | remove () |
Removes an object from the database. | |
void | reread () |
Rereads the database version. | |
void | purge () |
Purges an object from memory. | |
long long | id () const |
Returns the object id. |
A smart pointer for database objects.
This smart pointer class implements a reference counted shared pointer for database objects, which also keeps tracking of synchronization between the in-memory copy and the database copy. You should always use this pointer class to reference a database object.
Unlike typical C++ data structures, classes mapped to database tables do not have clear ownership relationships. Therefore, the conventional ownership-based memory allocation/deallocation does not work naturally for database classes.
A pointer may point to a transient object or a persisted object. A persisted object has a corresponding copy in the database while a transient object is only present in memory. To persist a new object, use Session::add(). To make a persisted object transient, use remove().
Unlike a typical smart pointer, this pointer only allows read access to the underlying object by default. To modify the object, you should explicitly use modify(). This is used to mark the underyling object as dirty to add it to the queue of objects to be synchronized with the database.
The pointer class provides a number of methods to deal with the persistence state of the object:
Wt::Dbo::ptr< C >::ptr | ( | C * | obj = 0 |
) | [inline] |
Creates a new pointer.
When obj
is not 0, the pointer points to the new unpersisted object. Use Session::add() to persist the newly created object.
Wt::Dbo::ptr< C >::~ptr | ( | ) | [inline, virtual] |
Destructor.
This method will delete the transient copy of the database object if it is not referenced by any other pointer.
void Wt::Dbo::ptr< C >::flush | ( | ) | const [inline] |
Flushes the object.
If dirty, the object is synchronized to the database. This will automatically also flush objects that are referenced by this object if needed. The object is not actually committed to the database before the active transaction has been committed.
Since this may persist object to the database, you should have an active transaction.
long long Wt::Dbo::ptr< C >::id | ( | ) | const [inline] |
Returns the object id.
This returns -1 for a transient object.
C * Wt::Dbo::ptr< C >::modify | ( | ) | const [inline] |
Dereference operator, for writing.
Returns the underlying object with the intention to modify it. It marks the underlying object as dirty.
Since this may lazy-load the underlying database object, you should have an active transaction.
Wt::Dbo::ptr< C >::operator bool | ( | ) | const [inline] |
Checks for null.
Returns true if the pointer is pointing to a non-null object.
const C & Wt::Dbo::ptr< C >::operator* | ( | ) | const [inline] |
Dereference operator.
Note that this operator returns a const copy of the referenced object. Use modify() to get a non-const reference.
Since this may lazy-load the underlying database object, you should have an active transaction.
const C * Wt::Dbo::ptr< C >::operator-> | ( | ) | const [inline] |
Dereference operator.
Note that this operator returns a const copy of the referenced object. Use modify() to get a non-const reference.
Since this may lazy-load the underlying database object, you should have an active transaction.
bool Wt::Dbo::ptr< C >::operator< | ( | const ptr< C > & | other | ) | const [inline] |
Comparison operator.
This operator is implemented to be able to store pointers in std::set or std::map containers.
bool Wt::Dbo::ptr< C >::operator== | ( | const ptr< C > & | other | ) | const [inline] |
Comparison operator.
Two pointers are equal if and only if they reference the same databse object.
void Wt::Dbo::ptr< C >::purge | ( | ) | [inline] |
Purges an object from memory.
When the object is not dirty, the memory copy of the object is deleted, and the object will be reread from the database on the next access.
Purging an object can be useful to conserve memory, but you should never purge an object while the user is editing if you wish to rely on the optimistick locking for detecting concurrent modifications.
void Wt::Dbo::ptr< C >::remove | ( | ) | [inline] |
Removes an object from the database.
The object is removed from the database, and becomes transient again.
Note that the object is not deleted in memory: you can still continue to read and modify the object, but there will no longer be a database copy of the object, and the object will effectively be treated as a new object (which may be re-added to the database at a later point).
This is the opposite operation of Session::add().
void Wt::Dbo::ptr< C >::reread | ( | ) | [inline] |
Rereads the database version.
Rereads a persisted object from the database, discarding any possible changes and updating to the latest database version.
This does not actually load the database version, since loading is lazy.
void Wt::Dbo::ptr< C >::reset | ( | C * | obj = 0 |
) | [inline] |
Resets the pointer.
This is equivalent to:
p = ptr<C>(obj);