Wt: Wt::Dbo::ptr< C > Class Template Reference

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions
Wt::Dbo::ptr< C > Class Template Reference
Database Objects (Wt::Dbo)

A smart pointer for a database object. 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 * | get () const
| Returns the pointer.
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.
bool | isTransient () const
| Returns whether the object is transient.
Session * | session () const
| Returns the session with which this pointer is associated.

## Detailed Description

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

A smart pointer for a database object.

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:

- id(): returns the database id
- flush(): forces the object to be synchronized to the database
- remove(): deletes the object in the underlying database
- reread(): rereads the database copy of the object
- purge(): purges the transient version of a non-dirty 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 >

const C * Wt::Dbo::ptr< C >::get | ( |  | ) | const

Returns the pointer.

Note that returns a const pointer. Use modify() to get a non-const pointer.

Since this may lazy-load the underlying database object, you should have an active transaction.

See also:
  modify()

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 >

bool Wt::Dbo::ptr< C >::isTransient | ( |  | ) | const

Returns whether the object is transient.

This returns true for a transient object.

template<class C >

ptr< C >::mutator Wt::Dbo::ptr< C >::modify | ( |  | ) | const

Dereference operator, for writing.

Returns the underlying object (or, rather, a proxy for it) with the intention to modify it. The proxy object will mark the object as dirty from its destructor. An involved modification should therefore preferably be implemented as a separate method or function to make sure that the object is marked as dirty after the whole modification:

       ptr<A> a = ...;
       a.modify()->doSomething();

Since this may lazy-load the underlying database object, you should have an active transaction.

See also:
  get()

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 >

Session * Wt::Dbo::ptr< C >::session | ( |  | ) | const

Returns the session with which this pointer is associated.

This may return 0 if the pointer is null or not added to a session.

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