Public Member Functions

Wt::Dbo::ptr< C > Class Template Reference
[Database Objects (Dbo)]

A smart pointer for database objects. More...

#include <Wt/Dbo/ptr>

Inherits Wt::Dbo::ptr_base.

List of all members.

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.
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.
dbo_traits< C >::IdType id () const
 Returns the object id.
int version () const
 Returns the object version.

Detailed Description

template<class C>
class Wt::Dbo::ptr< C >

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:


Constructor & Destructor Documentation

template<class C >
Wt::Dbo::ptr< C >::ptr ( C *  obj = 0 )

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.

template<class C >
Wt::Dbo::ptr< C >::~ptr (  ) [virtual]

Destructor.

This method will delete the transient copy of the database object if it is not referenced by any other pointer.


Member Function Documentation

template<class C >
void Wt::Dbo::ptr< C >::flush (  ) const

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.

template<class C >
dbo_traits< C >::IdType Wt::Dbo::ptr< C >::id (  ) const

Returns the object id.

This returns dbo_traits<C>::invalidId() for a transient object.

template<class C >
C * Wt::Dbo::ptr< C >::modify (  ) const

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.

template<class C >
Wt::Dbo::ptr< C >::operator bool (  ) const

Checks for null.

Returns true if the pointer is pointing to a non-null object.

template<class C >
bool Wt::Dbo::ptr< C >::operator!= ( const ptr< C > &  other ) const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

template<class C >
const C & Wt::Dbo::ptr< C >::operator* (  ) const

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.

template<class C >
const C * Wt::Dbo::ptr< C >::operator-> (  ) const

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.

template<class C >
bool Wt::Dbo::ptr< C >::operator< ( const ptr< C > &  other ) const

Comparison operator.

This operator is implemented to be able to store pointers in std::set or std::map containers.

template<class C >
bool Wt::Dbo::ptr< C >::operator== ( const ptr< C > &  other ) const

Comparison operator.

Two pointers are equal if and only if they reference the same database object.

template<class C >
void Wt::Dbo::ptr< C >::purge (  )

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.

template<class C >
void Wt::Dbo::ptr< C >::remove (  )

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().

template<class C >
void Wt::Dbo::ptr< C >::reread (  )

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.

template<class C >
void Wt::Dbo::ptr< C >::reset ( C *  obj = 0 )

Resets the pointer.

This is equivalent to:

 p = ptr<C>(obj);
template<class C >
int Wt::Dbo::ptr< C >::version (  ) const

Returns the object version.

This returns -1 for a transient object or when versioning is not enabled.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator

Generated on Fri Feb 4 2011 for the C++ Web Toolkit (Wt) by doxygen 1.7.2