iopc::DbPtr< T > Class Template Reference
[iopclib]

A database pointer class. More...

#include <dbPtr.h>

Inheritance diagram for iopc::DbPtr< T >:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 DbPtr ()
 Crates a transient instance of the template parameter type.
 DbPtr (const DbPtr< T > &src)
 Creates a copy of an existing database pointer.
 DbPtr (Cursor &cur)
 Loads a database object from an open cursor.
 DbPtr (CachedConnection *conn, const OidType &oid, bool loadRealType=true)
 Initializes the identity of this database pointer from an OID.
 DbPtr (CachedConnection *conn, const KeyValues &keyVals)
 Initializes the identity of this database pointer from a set of key values.
CachePtr< T > bePersistent (CachedConnection *conn)
 Makes the referenced object persistent.
CachePtr< T > operator* () const
 Dereferences the database pointer.
CachePtr< T > operator-> () const
 Dereferences the database pointer.
CachePtr< T > getCachePtr () const
 Dereferences the database pointer.
ConstCachePtr< T > getConstCachePtr () const
 Dereferences the database pointer for reading.


Detailed Description

template<typename T>
class iopc::DbPtr< T >

A database pointer class.

Database pointer is an abstraction of a persistent object reference. Database pointer may point to a persistent object in several states:

Last object state, the locked local copy, is implemented as an additional level of indirection when dereferencing the database pointer. By dereferencing it using the * operator (or using the -> operator or by calling the getCachePtr() or getConstCachePtr method), user receives an instance of a cache pointer (CachePtr<T> or ConstCachePtr<T>).

Database pointer can be used in the following way:

 // Create a new empty Person persistent class instance
 // The class is required to have an implitit or an explicit non-parametric constructor
 DbPtr<Person> person;
 // Assign values to its attributes
 person->name = "Mary Major";
 person->age = 60;
 // Transfer the ownership of the object to a cache associated with the connection conn.
 person.bePersistent(conn);
 // Now the object data may be present either in the cache, in the cache and in the database, or in the database only
 // So to be able to access its attributes the cache may need to load it from the database again.
 // To prevent this behavior each time we access the cache, the object can be locked in a @a CachePtr cache pointer
 // in the following way:
 CachePtr<Person> p = *person;   // Finds the object in cache and loads it from a database if needed
 p->name = "Mary Major 2";       // No cache lookup is necessare as the instance is locked in the @a CachePtr
 p->age = 70;
 p.release();                    // Now the instance is unlocked and the cache is free to store it to the database again.

Constructor & Destructor Documentation

template<typename T>
iopc::DbPtr< T >::DbPtr ( const DbPtr< T > &  src  )  [inline]

Creates a copy of an existing database pointer.

If src points to a transient instance, this action adds 1 to its reference counter. The instance can't be delegated to a cache unless the reference count drops back to 1 (only one referencing database pointer).

Parameters:
src Source database pointer

template<typename T>
iopc::DbPtr< T >::DbPtr ( Cursor cur  )  [inline]

Loads a database object from an open cursor.

Used by Result<T> to fetch transient query result. Loaded object has no identity and can't be modified and made persistent.

Parameters:
cur An open cursor from which one row will be fetched.

template<typename T>
iopc::DbPtr< T >::DbPtr ( CachedConnection conn,
const OidType oid,
bool  loadRealType = true 
) [inline]

Initializes the identity of this database pointer from an OID.

This constructor makes the DbPtr<T> point to an object of the specified OID. State of the pointer will be DbPtrBase::PERSISTENT and the object will be looked up in the cache and eventually loaded from a database when one of its attributes is accessed.

Parameters:
conn A cached connection with an associated cache
oid OID of the object this pointer will refer to
loadRealType Determines whether polymorphism is used when loading the object instance If false, a T template parameter instance is created and loaded. If true, the actual type the oid represents is first looked up in the Oid-classname catalogue and according to it a persistent object instance is created. I.e. if OID 2 refers to a Student class and the database pointer is declared as DbPtr<Person>, a Student instance will be created and loaded. The instance can be then obtained via
 dynamic_cast<Student&>(*(getCachePtr().getObjectPtr()))

template<typename T>
iopc::DbPtr< T >::DbPtr ( CachedConnection conn,
const KeyValues keyVals 
) [inline]

Initializes the identity of this database pointer from a set of key values.

This constructor makes the DbPtr<T> point to an object of the specified key values. State of the pointer will be DbPtrBase::PERSISTENT and the object will be looked up in the cache and eventually loaded from a database when one of its attributes is accessed.

Parameters:
conn A cached connection with an associated cache
keyVals Values of the object primary key


Member Function Documentation

template<typename T>
CachePtr< T > iopc::DbPtr< T >::bePersistent ( CachedConnection conn  )  [inline]

Makes the referenced object persistent.

Generates a new identity for the object and transfers the referenced object ownership to an associated cache

Reimplemented from iopc::DbPtrBase.

template<typename T>
CachePtr< T > iopc::DbPtr< T >::operator* (  )  const [inline]

Dereferences the database pointer.

Returns:
An instance representing locked copy of referenced object.

template<typename T>
CachePtr< T > iopc::DbPtr< T >::operator-> (  )  const [inline]

Dereferences the database pointer.

Returns:
An instance representing locked copy of referenced object.

template<typename T>
CachePtr< T > iopc::DbPtr< T >::getCachePtr (  )  const [inline]

Dereferences the database pointer.

Returns:
An instance representing locked copy of referenced object.

template<typename T>
ConstCachePtr< T > iopc::DbPtr< T >::getConstCachePtr (  )  const [inline]

Dereferences the database pointer for reading.

Returns:
An instance representing copy locked for reading (shared lock).


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

Generated on Tue Apr 14 16:46:49 2009 for IOPC 2 by  doxygen 1.5.6