Public Member Functions

Wt::Dbo::Session Class Reference
[Database Objects library (Dbo)]

A database session. More...

#include <Wt/DboSession>

List of all members.

Public Member Functions

 Session ()
 Creates a database session.
 ~Session ()
 Destructor.
void setConnection (SqlConnection &connection)
 Sets a connection.
template<class C >
void mapClass (const char *tableName)
 Maps a class to a database table.
template<class C >
const char * tableName () const
 Returns the mapped table name for a class.
template<class C >
ptr< C > add (ptr< C > &ptr)
 Persists a transient object.
template<class C >
ptr< C > add (C *obj)
 Persists a transient object.
template<class C >
ptr< C > load (long long id)
 Loads a persisted object.
template<class C >
Query< ptr< C > > find (const std::string &where=std::string())
 Creates a query for finding database objects.
template<class Result >
Query< Result > query (const std::string &sql)
 Creates a query for finding objects of type Result.
void createTables ()
 Creates the database schema.
void dropTables ()
 Drops the database schema.
void flush ()
 Flushes the session.

Detailed Description

A database session.

A database session manages meta data about the mapping of C++ classes to database tables, and keeps track of a collection of in-memory objects.

It also manages transactions that you need to create when accessing database objects.

In its current form, the session uses a dedicated database connection that must be set using setConnection(), but its implementation is ready to use a connection pool in a later version.

A session will typically be a long-lived object in your application.


Constructor & Destructor Documentation

Wt::Dbo::Session::~Session (  )

Destructor.

A session must survive all database objects that have been loaded through it, and will warning during this destructor if there are still database objects that are being referenced from a ptr.


Member Function Documentation

template<class C >
ptr< C > Wt::Dbo::Session::add ( ptr< C > &  ptr )

Persists a transient object.

The transient object pointed to by ptr is added to the session, and will be persisted when the session is flushed.

A transient object is usually a newly created object which want to add to the database.

The method returns ptr.

template<class C >
ptr< C > Wt::Dbo::Session::add ( C *  obj )

Persists a transient object.

This is an overloaded method for convenience, and is implemented as:

 return add(ptr<C>(obj));

The method returns a database pointer to the object.

void Wt::Dbo::Session::createTables (  )

Creates the database schema.

This will create the database schema of the mapped tables. Schema creation will fail if one or more tables already existed.

See also:
mapClass(), dropTables()
void Wt::Dbo::Session::dropTables (  )

Drops the database schema.

This will drop the database schema. Dropping the schema will fail if one or more tables did not exist.

See also:
createTables()
template<class C >
Query< ptr< C > > Wt::Dbo::Session::find ( const std::string &  where = std::string() )

Creates a query for finding database objects.

This method creates a query for finding objects of type C.

When passing an empty where parameter, it will return all objects of type C. You may narrow down the search (using SQL WHERE), add ordering (using ORDER BY) or limits (using LIMIT) by sepecifying the SQL that should come after the 'select ... from ..."

This method is convenient when you are querying only results from a single table. For more generic query support, see query().

See also:
query()
void Wt::Dbo::Session::flush (  )

Flushes the session.

This flushes all modified objects to the database. This does not commit the transaction.

Normally, you need not to call this method as the session is flushed automatically before committing a transaction, or before running a query (to be sure to take into account pending modifications).

template<class C >
ptr< C > Wt::Dbo::Session::load ( long long  id )

Loads a persisted object.

This method returns a database object with the given object id. If the object was already loaded in the session, the loaded object is returned, otherwise the object is loaded from the database.

Throws an ObjectNotFoundException when the object was not found.

See also:
ptr::id()
template<class C >
void Wt::Dbo::Session::mapClass ( const char *  tableName )

Maps a class to a database table.

The class C is mapped to table with name tableName. You need to map classes to tables.

You may provide a schema-qualified table name, if the underlying database supports this, eg. "myschema.users".

template<class Result >
Query< Result > Wt::Dbo::Session::query ( const std::string &  sql )

Creates a query for finding objects of type Result.

The sql statement should be a complete SQL statement, however the columns listed (in the SELECT part) will be edited depending on the Result type.

For example, the following query (where class A is mapped onto table 'table_a'):

 return session.query<ptr<A> >("select A from table_a A where A.name = ?");

is the more general version of:

 return session.find<A>("where A.name = ?");

The power of query() versus find() is however that it may support other result types.

Thus, it may return plain values:

 return session.query<int>("select count(*) from ...");

Or Boost.Tuple for an arbitrary combination of result values:

 return session.query< boost::tuple<int, int> >("select A.id, B.id from table_a A, table_b B where ...");

A tuple may combine any kind of object that is supported as a result, including database objects (see also ptr_tuple):

 return session.query< boost::tuple<ptr<A>, ptr<B> >("select A, B from table_a A, table_b B where ...");

This method uses sql_result_traits to unmarshal the query result into the Result type.

void Wt::Dbo::Session::setConnection ( SqlConnection connection )

Sets a connection.

The connection will be used exclusively by this session.

Note:
Currently, a session uses a dedicated connection. Support for a connection pool will be added later.
template<class C >
const char * Wt::Dbo::Session::tableName (  ) const

Returns the mapped table name for a class.

See also:
mapClass()

Generated on Sat Dec 4 2010 06:32:36 for Wt by doxygen 1.7.2