spunQ_db Class Reference

Common functions for the db module. More...

Inheritance diagram for spunQ_db:

List of all members.

Public Member Functions
	startTransaction ()
	Starts a transaction.
	commitTransaction ()
	Commits a pending transaction.
	rollbackTransaction ()
	Cancels the current transaction.
	createTypeStorage (spunQ_UserType $type)
	Creates type storages for a type.
	getAllTypeStorages ()
	Will return all available type storages, mapped by the type names.
	getTypeStorage ($type, $throwException=true)
	Will return the type storage of a certain type.
	addDatabaseListener (spunQ_IDatabaseListener $listener, $types=NULL)
	Adds an observer to the database connection.
	removeDatabaseListener (spunQ_IDatabaseListener $listener, $types=NULL)
	Removes an observer from the database connection.
	executeInsertQuery (spunQ_InsertQuery $query)
	Execute an insert query.
	executeSelectQuery (spunQ_SelectQuery $query, array $parameters=array())
	Execute a select query.
	countSelectQuery (spunQ_SelectQuery $query, array $parameters=array())
	Returns number of matching objects for a select query.
	executeUpdateQuery (spunQ_UpdateQuery $query, array $parameters=array())
	Execute an update query.
	executeDeleteQuery (spunQ_DeleteQuery $query, array $parameters=array())
	Execute a delete query.
	getAll ($typeName)
	Retrieves all objects of given type.
	getByCondition ($typeName, $condition, $parameters)
	Retrieves all objects meeting a given condition.
	getByMember ($typeName, $memberName, $value)
	Retrieves all objects where a member has given value.
	getById ($id, $typeName=NULL, $throwException=true)
	Retrieves the object with given id.
	getByIds (array $ids, $typeName=NULL)
	Retrieves the object with the requested ids.
	loadOnDemand ($object, array $members)
	Intended for internal use only.
Static Public Member Functions
static	getConnection ($name= 'default')
	Gets the connection with the requested name.
static	observeInitializations (spunQ_IDatabaseInstantiationListener $listener)
	Adds a listener.
static	getDefaultConnection ()
	Gets the defined default database connection.
static	registerDbmsHandler ($dbms, spunQ_IDatabaseConnectionFactory $factory)
	Registers a dbms handler.
static	getMissingTypes ($connection=NULL)
	Gets the list of types that are not present in the database.
static	getAdditionalTypes ($connection=NULL)
	Gets the list of types that do not exist locally.
static	getChangedTypes ($connection=NULL)
	Gets the list of types that have a different parent.
static	getMissingTypeMembers ($connection=NULL)
	Gets the list of type members that do not exist locally.
static	getAdditionalTypeMembers ($connection=NULL)
	Gets the list of types that are not present in the database.
static	getChangedTypeMembers ($connection=NULL)
	Gets the list of type members with a different type.
Static Protected Member Functions
static	sanityCheck ($connection=NULL)
	Will ensure that all defined user types can be stored by a connection.
Static Protected Attributes
static	$handlers = NULL
	The registered spunQ_IDatabaseConnectionFactory objects.
Static Private Attributes
static	$connections = array()
	All established connections.
static	$listeners = array()
	Listeners for connections.

---

Detailed Description

Common functions for the db module.

This class mainly holds the default database connection. The default database connection is only initiated on demand, i.e. when the function getDefaultConnection() is called. If no connection was set as default (using setDefaultConnection()), one will be generated using the data in the spunQ configuration. Database connections in the configuration start with spunQ.db.connection. and have a unique name appended. The default connection has to be named 'default', resulting in the config value spunQ.db.connection.default. All configuration values starting with this string are considered to be part of the connection definition. The only required value therein is the value dbms, which indicates how the config values can be turned into spunQ_IDatabaseConnection object. This class itself does not instantiate any such objects, but makes use of spunQ_IDatabaseConnectionFactory objects, which need to be rtegistered through registerDbmsHandler(). Every connection factory is associated with a dbms alias. If the dbms value in the configuration matches this string, the associated connection factory is held authorative on this alias and all configuration values are passed to its spunQ_IDatabaseConnectionFactory::createInstance() function. The lack of an adequate connection factory causes a spunQ_InitializationError to be thrown.

Definition at line 53 of file db.class.php.

---

Member Function Documentation

spunQ_IDatabaseConnection::addDatabaseListener	(	spunQ_IDatabaseListener $	listener,
		$	types = NULL
	)			[inherited]

Adds an observer to the database connection.

Parameters:

	$listener	The observer.
	$types	The types to listen on. NULL for all types

Returns:

spunQ_IDatabaseConnection $this

spunQ_IDatabaseConnection::commitTransaction

(

)

[inherited]

Commits a pending transaction.

Returns:

void

spunQ_IDatabaseConnection::countSelectQuery	(	spunQ_SelectQuery $	query,
		array $	parameters = array()
	)			[inherited]

Returns number of matching objects for a select query.

Parameters:

	$query	The query to execute
	$parameters	Parameters to PL strings in the query.

Returns:

integer

Exceptions:

spunQ_DatabaseException

spunQ_IDatabaseConnection::createTypeStorage

(

spunQ_UserType $

type

)

[inherited]

Creates type storages for a type.

Parameters:

$type

Type to create storage for.

Exceptions:

	spunQ_TypeStorageNotFoundException	If the type storage for its parent type does not exist.
	spunQ_TypeStorageAlreadyExistsException	If the type storage for this type already exists.
	spunQ_DatabaseException	On all other database errors.

Returns:

spunQ.db.ITypeStorage

spunQ_IDatabaseConnection::executeDeleteQuery	(	spunQ_DeleteQuery $	query,
		array $	parameters = array()
	)			[inherited]

Execute a delete query.

Parameters:

	$query	The query to execute
	$parameters	Parameters to PL strings in the query.

Returns:

Whatever the query is configured to return.

Exceptions:

spunQ_DatabaseException

spunQ_IDatabaseConnection::executeInsertQuery

(

spunQ_InsertQuery $

query

)

[inherited]

Execute an insert query.

Parameters:

$query

The query to execute

Returns:

Whatever the query is configured to return.

Exceptions:

spunQ_DatabaseException

spunQ_IDatabaseConnection::executeSelectQuery	(	spunQ_SelectQuery $	query,
		array $	parameters = array()
	)			[inherited]

Execute a select query.

Parameters:

	$query	The query to execute
	$parameters	Parameters to PL strings in the query.

Returns:

Whatever the query is configured to return.

Exceptions:

spunQ_DatabaseException

spunQ_IDatabaseConnection::executeUpdateQuery	(	spunQ_UpdateQuery $	query,
		array $	parameters = array()
	)			[inherited]

Execute an update query.

Parameters:

	$query	The query to execute
	$parameters	Parameters to PL strings in the query.

Returns:

Whatever the query is configured to return.

Exceptions:

spunQ_DatabaseException

static spunQ_db::getAdditionalTypeMembers

(

$

connection = NULL

)

[static]

Gets the list of types that are not present in the database.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

array<spunQ.Type>

Definition at line 311 of file db.class.php.

static spunQ_db::getAdditionalTypes

(

$

connection = NULL

)

[static]

Gets the list of types that do not exist locally.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

array<spunQ.Type>

Definition at line 231 of file db.class.php.

spunQ_IDatabaseConnection::getAll

(

$

typeName

)

[inherited]

Retrieves all objects of given type.

Parameters:

$typeName

Name of the type to retrieve objects for.

Returns:

array<spunQ.db.StorableObject>

spunQ_IDatabaseConnection::getAllTypeStorages

(

)

[inherited]

Will return all available type storages, mapped by the type names.

Returns:

map<string,spunQ_ITypeStorage>

Exceptions:

spunQ_DatabaseException

If the type does not exist.

spunQ_IDatabaseConnection::getByCondition	(	$	typeName,
		$	condition,
		$	parameters
	)			[inherited]

Retrieves all objects meeting a given condition.

Parameters:

	$typeName	Name of the type to retrieve objects for.
	$condition	The PL string to check on the stored objects.
	$parameters	Paramters to the PL string.

Returns:

array<spunQ.db.StorableObject>

spunQ_IDatabaseConnection::getById	(	$	id,
		$	typeName = NULL,
		$	throwException = true
	)			[inherited]

Retrieves the object with given id.

Parameters:

	$id	The id to retrieve. This is the only mandatory parameter - everything else is optional.
	$typeName	The name of the type the object should have. Defaults to spunQ.db.StorableObject. Providing this value will allow the underlying database manager to cache more efficiently.
	$throwException	Whether the function should throw an exception if no object with the given id was found. Will return NULL in that case if this value is false.

Returns:

spunQ.db.StorableObject

Exceptions:

spunQ_InvalidObjectException

spunQ_IDatabaseConnection::getByIds	(	array $	ids,
		$	typeName = NULL
	)			[inherited]

Retrieves the object with the requested ids.

See also:

getById()

Parameters:

	$id	The ids to retrieve.
	$typeName	The name of the type the objects should have. Defaults to spunQ.db.StorableObject. Providing this value will allow the underlying database manager to cache more efficiently.

Returns:

array<spunQ.db.StorableObject> Keys of the array are the ids of the objects.

spunQ_IDatabaseConnection::getByMember	(	$	typeName,
		$	memberName,
		$	value
	)			[inherited]

Retrieves all objects where a member has given value.

This is basically the same as calling getByCondition($typeName, "$memberName = {0}", array($value)).

Parameters:

	$typeName	Name of the type to retrieve objects for.
	$memberName	Name of the member to check.
	$value	Value the provided member must have to be returned.

Returns:

array<spunQ.db.StorableObject>

static spunQ_db::getChangedTypeMembers

(

$

connection = NULL

)

[static]

Gets the list of type members with a different type.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

map<spunQ.Member,string> Type member to type description in the database mapping.

Definition at line 337 of file db.class.php.

static spunQ_db::getChangedTypes

(

$

connection = NULL

)

[static]

Gets the list of types that have a different parent.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

map<spunQ.Type,string> Local type to type description in the database mapping.

Definition at line 253 of file db.class.php.

static spunQ_db::getConnection

(

$

name = 'default'

)

[static]

Gets the connection with the requested name.

Parameters:

$name

The name of the connection.

Returns:

spunQ_IDatabaseConnection

Exceptions:

spunQ_InitializationError

Definition at line 80 of file db.class.php.

static spunQ_db::getDefaultConnection

(

)

[static]

Gets the defined default database connection.

Returns:

spunQ_IDatabaseConnection

Definition at line 115 of file db.class.php.

static spunQ_db::getMissingTypeMembers

(

$

connection = NULL

)

[static]

Gets the list of type members that do not exist locally.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

array<spunQ.Type>

Definition at line 282 of file db.class.php.

static spunQ_db::getMissingTypes

(

$

connection = NULL

)

[static]

Gets the list of types that are not present in the database.

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

array<spunQ.Type>

Definition at line 208 of file db.class.php.

spunQ_IDatabaseConnection::getTypeStorage	(	$	type,
		$	throwException = true
	)			[inherited]

Will return the type storage of a certain type.

Parameters:

	$type	The type to get storage for. This is either a string describing a type or a spunQ_Type object.
	$throwException	Whether the function should throw an exception if no type storage for given type was found. Will return NULL in that case if this value is false.

Returns:

spunQ_ITypeStorage

Exceptions:

spunQ_DatabaseException

If the type does not exist.

spunQ_IDatabaseConnection::loadOnDemand	(	$	object,
		array $	members
	)			[inherited]

Intended for internal use only.

spunQ.db.StorableObject needs to call this function to load missing members from the database. The connection will call spunQ_StorableObject::_loadRemoteValues() on the $object. It is perfectly valid for this connection to load additional members if this reduces overall query overhead.

Parameters:

	$object	The object to load members for. It must have an id.
	$members	Names of the members that needs to be loaded. The first entry in this array is needed, all others are further members that have not yet been loaded. The database is free to load any of these additional members.

Returns:

spunQ_IDatabaseConnection $this

static spunQ_db::observeInitializations

(

spunQ_IDatabaseInstantiationListener $

listener

)

[static]

Adds a listener.

Parameters:

$listener

The listener to notify on connection establishment.

Returns:

void

Definition at line 106 of file db.class.php.

static spunQ_db::registerDbmsHandler	(	$	dbms,
		spunQ_IDatabaseConnectionFactory $	factory
	)			[static]

Registers a dbms handler.

Parameters:

	$dbms	The name of the dbms
	$factory	The factory that is able to create spunQ_IDatabaseConnection instances for the dbms referenced with the name $dbms.

Returns:

void

Definition at line 127 of file db.class.php.

spunQ_IDatabaseConnection::removeDatabaseListener	(	spunQ_IDatabaseListener $	listener,
		$	types = NULL
	)			[inherited]

Removes an observer from the database connection.

Parameters:

	$listener	The observer.
	$types	The types to listen on. NULL for all types

Returns:

spunQ_IDatabaseConnection $this

spunQ_IDatabaseConnection::rollbackTransaction

(

)

[inherited]

Cancels the current transaction.

Returns:

void

static spunQ_db::sanityCheck

(

$

connection = NULL

)

[static, protected]

Will ensure that all defined user types can be stored by a connection.

Will ensure that the following functions return empty values and throw an exception otherwise:

• getAdditionalTypes()
• getAdditionalTypeMembers()
• getChangedTypes()
• getChangedTypeMembers()
• getMissingTypes()
• getMissingTypeMembers()

Parameters:

$connection

The connection to check. Defaults to the default connection.

Returns:

void

Exceptions:

spunQ_InitializationError

Definition at line 151 of file db.class.php.

spunQ_IDatabaseConnection::startTransaction

(

)

[inherited]

Starts a transaction.

Exceptions:

spunQ_DatabaseException

If transactions are not supported.

Returns:

void

---

Member Data Documentation

spunQ_db::$connections = array() [static, private]

All established connections.

The array is indexed with the names of the connections.

Type:

array<spunQ_IDatabaseConnection>

Definition at line 66 of file db.class.php.

spunQ_db::$handlers = NULL [static, protected]

The registered spunQ_IDatabaseConnectionFactory objects.

Type:

map<string,spunQ_IDatabaseConnectionFactory> Dbms alias to object.

Definition at line 59 of file db.class.php.

spunQ_db::$listeners = array() [static, private]

Listeners for connections.

Type:

array<spunQ_IDatabaseInstantiationListener>

Definition at line 72 of file db.class.php.

---

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

• db.class.php