persistence.doxy

/*!
\page persistence Persistence
<div class="has-toc"></div>
 
# Persistence # {#pers_main}
 
Persistence refers to that part of the domain model, which we could call the data model.
 
## Data model ## {#pers_datamodel}
 
The data model consists of domain classes whose instances are saved in the storage.
The following steps need to be accomplished to make domain class instances
persistent.
 
- Definition and creation of the database tables, if using a database storage.
- Implementation of the \link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink
  classes, which map the domain classes to these tables, or anything else that is used as storage.
- Implementation of the domain classes as subclasses of \link wcmf::lib::model::Node `Node`\endlink.
- Configuration of the persistence layer.
 
@note If you are using the generator to create the application from a model
(see \ref model), all necessary code will be generated automatically.
 
### Database tables ### {#pers_tables}
 
Still the most common storage for web applications is a _SQL_ database (e.g.
[MySQL](http://www.mysql.com/)). It is also wCMF's default storage. Although not
strictly necessary it is recommended to use one database table for each persistent
class, where each class property maps to one table column and each row stores one
instance. The object identity is stored in the primary key column, which is named
_id_ by default.
 
@note wCMF uses a table called `DBSequence` for retrieving the next id value used for
insertion, since _autoincrement_ columns are not supported on all database servers.
 
#### Primary keys #### {#pers_id}
 
Primary keys are used to clearly identify an object in the database. They can consist
of one (_simple_) or more (_compound_) columns. The default name for a primary
key column is _id_. wCMF stores the primary key of an object together with it's type
name in an \link wcmf::lib::persistence::ObjectId `ObjectId`\endlink instance.
 
#### Relations #### {#pers_relations}
 
The following two relations types must be considered, when modeling the data
tables:
 
- __One-To-Many__ relations are realized by adding a foreign key column to the
child table (_many_-side), which points to the parent table (_one_-side). This
column is named _fk_ _ + parent table name  + _ _id_ by default (e.g. _fk_author_id_).
 
- __Many-To-Many__ relations between two domain classes, are established by defining
a connection table. This table contains two primary keys, which point to the two
connected tables.
 
### Persistence Mappers ### {#pers_mappers}
 
wCMF uses persistence mapper classes to communicate between the application and
the persistent storage (see \ref arch_main). These classes implement the
\link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink interface,
which defines methods for all persistence actions. By using this pattern wCMF
does not make any assumptions about the actual storage, which can be flat files,
a database, a remote service or anything else a mapper is able to handle. This approach 
also makes it easy to connect an existing storage to a newly created wCMF application.
 
To simplify the implementation of mapper classes, wCMF already contains
a class hierarchy for a common mapping approach, which maps each concrete class
to one database table ([Concrete Table Inheritance]
(http://martinfowler.com/eaaCatalog/concreteTableInheritance.html)). In this
hierarchy \link wcmf::lib::model::mapper::impl::AbstractRDBMapper `AbstractRDBMapper`\endlink handles
the communication with the relational database, while
\link wcmf::lib::model::mapper::NodeUnifiedRDBMapper `NodeUnifiedRDBMapper`\endlink
defines the actual mapping rules. Application developers simply need to implement
one subclass of \link wcmf::lib::model::mapper::NodeUnifiedRDBMapper `NodeUnifiedRDBMapper`\endlink
for each persistent domain class, which declares the mapping of the attributes and
relations of that class.
 
@note All mapper classes, that are created by the generator are
\link wcmf::lib::model::mapper::NodeUnifiedRDBMapper `NodeUnifiedRDBMapper`\endlink
subclasses.
 
### Domain Classes ### {#pers_classes}
 
Domain class instances hold the data that are used in the application and persisted
in the storage.
 
Persistent domain classes either inherit from
- \link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink, which
is a container with value getter and setter methods, or from
- \link wcmf::lib::model::Node `Node`\endlink, which adds methods for managing
relations.
 
These two classes are completely generic, the actual identity of the domain class -
that is the _properties_ and the _relations_ - are defined by the related
\link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink.
 
So if no additional domain logic is required in the domain class, it would be
sufficient to use \link wcmf::lib::model::Node `Node`\endlink as domain class.
But in many cases you will want to execute custom code for \ref pers_hooks,
\ref pers_validation and other business logic and therefor create a custom subclass of
\link wcmf::lib::model::Node `Node`\endlink.
 
@note All domain classes, that are created by the generator are
\link wcmf::lib::model::Node `Node`\endlink subclasses.
 
#### Persistence Hooks #### {#pers_hooks}
 
Persistence hooks are methods that are called at certain points of the lifecycle of
an instance. The default implementation of these methods is empty - in fact their
sole purpose is to be overwritten in subclasses on order to implement special
functionality that should be executed at those points.
\link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink defines
the following persistence hooks:
 
- \link wcmf::lib::persistence::PersistentObject::afterCreate `afterCreate`\endlink
- \link wcmf::lib::persistence::PersistentObject::beforeInsert `beforeInsert`\endlink
- \link wcmf::lib::persistence::PersistentObject::afterInsert `afterInsert`\endlink
- \link wcmf::lib::persistence::PersistentObject::afterLoad `afterLoad`\endlink
- \link wcmf::lib::persistence::PersistentObject::beforeUpdate `beforeUpdate`\endlink
- \link wcmf::lib::persistence::PersistentObject::afterUpdate `afterUpdate`\endlink
- \link wcmf::lib::persistence::PersistentObject::beforeDelete `beforeDelete`\endlink
- \link wcmf::lib::persistence::PersistentObject::afterDelete `afterDelete`\endlink
 
#### Values, Properties and Tags #### {#pers_values}
 
The following terms are important to know when working with wCMF's domain classes:
 
- __Values__ are the persistent attributes of a domain class. You can think
  of them as class members. Values are accessed using the methods
  \link wcmf::lib::persistence::PersistentObject::getValue `getValue`\endlink
  and \link wcmf::lib::persistence::PersistentObject::setValue `setValue`\endlink.
- __Properties__ apply to domain classes and domain class values. They describe
  static features like the `displayValues` of the class or the `inputType`
  of a value. Properties are defined in the model as _tags_ (see \ref model_profile)
  and are accessed using the methods
  \link wcmf::lib::persistence::PersistentObject::getProperty `getProperty`\endlink/
  \link wcmf::lib::persistence::PersistentObject::setProperty `setProperty`\endlink
  and
  \link wcmf::lib::persistence::PersistentObject::getValueProperty `getValueProperty`\endlink/
  \link wcmf::lib::persistence::PersistentObject::setValueProperty `setValueProperty`\endlink
- __Tags__ are a special property used on values to group them by certain
  aspects. For example the edit forms in the \ref app "default application" only
  display domain class values that are tagged with `DATATYPE_ATTRIBUTE` and only those
  attributes are editable in the translation form that are tagged with `TRANSLATABLE`.
  The `SEARCHABLE` tag defines that an entity type should be included in the search index.
  Tags are defined in the model using the _tag_ `app_data_type` (see \ref model_chivalue).
 
### Configuration ### {#pers_config}
 
Entry point of configuring the persistence layer is
\link wcmf::lib::persistence::PersistenceFacade `PersistenceFacade`\endlink
(see \ref pers_usage).
The configuration mainly tells the facade which mapper classes are responsible
for which domain classes. This assignment is defined in the `TypeMapping`
configuration section. The following example shows the appropriate entries
for the `Author` domain class:
 
<div class="ini">
```
[PersistenceFacade]
__class = wcmf\lib\persistence\impl\DefaultPersistenceFacade
mappers = $typeMapping
logging = false
logStrategy = $auditingLogStragegy
 
[AuditingLogStragegy]
__class = wcmf\lib\persistence\output\impl\AuditingOutputStrategy
 
[TypeMapping]
app.src.model.Author = $app_src_model_AuthorRDBMapper
 
[app_src_model_AuthorRDBMapper]
__class = app\src\model\AuthorRDBMapper
connectionParams = $database
 
[Database]
dbType = sqlite
dbHostName = 127.0.0.1
dbName = app/test-db.sq3
dbUserName =
dbPassword =
dbCharSet = utf8
```
</div>
 
## Usage ## {#pers_usage}
 
\link wcmf::lib::persistence::PersistenceFacade `PersistenceFacade`\endlink is
the main entry point to the persistence layer. It is  used to create and retrieve
\link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink instances.
The following sections show some basic examples for using the persistence layer.
 
### Loading objects ### {#pers_load}
 
To load a __single object__, the
\link wcmf::lib::persistence::PersistenceFacade::load `PersistenceFacade::load`\endlink
method is used:
 
<div class="php">
```
$oid = new ObjectId('Author', 1);
 
// load the Author instance with id 1
$author = ObjectFactory::getInstance('persistenceFacade')->load($oid);
 
// PersistenceFacade will return null, if an instance does not exist
if($author == null) {
  echo("An Author with object id ".$oid." does not exist.");
}
```
</div>
 
In the example the `Author` instance with id _1_ is loaded.
 
A __list of objects__ is loaded using the
\link wcmf::lib::persistence::PersistenceFacade::loadObjects `PersistenceFacade::loadObjects`\endlink
method:
 
<div class="php">
```
// load all Author instances
$authors = ObjectFactory::getInstance('persistenceFacade')->loadObjects('Author');
```
</div>
 
This \link wcmf::lib::persistence::PersistenceFacade::loadObjects `PersistenceFacade::loadObjects`\endlink
method provides several parameters that allow to specify which instances should
be loaded and how the list should be ordered. The next sections explain these
parameters.
 
#### Eager relation loading #### {#pers_builddepth}
 
When loading objects we generally distinguish between __eager__ and __lazy__ loading
(see [Lazy loading](http://en.wikipedia.org/wiki/Lazy_loading)).
By default \link wcmf::lib::persistence::PersistenceFacade `PersistenceFacade`\endlink
performs _lazy loading_ by using _virtual proxies_ (instances of
\link wcmf::lib::persistence::PersistentObjectProxy `PersistentObjectProxy`\endlink).
That means that related objects are retrieved from the store, only when they are
actually accessed. To perform _eager loading_, a
\link wcmf::lib::persistence::BuildDepth `BuildDepth`\endlink
value is passed in the method calls:
 
<div class="php">
```
$oid = new ObjectId('Author', 1);
 
// load the Author instance with id 1 together with all related objects
$author = ObjectFactory::getInstance('persistenceFacade')->load($oid, BuildDepth::INFINITE);
```
</div>
 
In this example the `Author` instance with id _1_ is loaded together with all related
objects recursively.
 
Instead of a \link wcmf::lib::persistence::BuildDepth `BuildDepth`\endlink
value, an integer number could be passed indicating the depth of relations to load.
The following image illustrates the _build depth_ parameter for a simple model.
 
\image html builddepth.png "Build depth"
 
If using a build depth value of _1_ the `Author` instance _Author A_ will be loaded together
with it's related `Articles` instances (_Article A_, _Article B_). A value of _2_ will also load
the `Chapter` instances (_Chapter A1_, _Chapter A2_). The default value is
\link wcmf::lib::persistence::BuildDepth::SINGLE `BuildDepth::SINGLE`\endlink,
which means that only the _Author A_ instance is loaded. In the above illustration
the value of _2_ is equal to passing
\link wcmf::lib::persistence::BuildDepth::INFINITE `BuildDepth::INFINITE`\endlink.
 
#### Sorting #### {#pers_sorting}
 
When loading a list of objects, the default order of the
\link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink
class is used for sorting. This default order is defined in the model (_orderby_ tag
of _ChiNode_, see \ref model_chinode). Besides this, all loading methods (e.g.
\link wcmf::lib::persistence::PersistenceFacade::loadObjects `PersistenceFacade::loadObjects`\endlink)
accept an `orderby` parameter for explicitly setting a different order.
 
A list of already loaded \link wcmf::lib::model::Node `Node`\endlink
instances is sorted by using \link wcmf::lib::model::NodeComparator `NodeComparator`\endlink
in the following way:
 
<div class="php">
```
$nodeList = [...];
 
// set up a comparator for node type and created date
$sortCriteria = [
  NodeComparator::ATTRIB_TYPE => NodeComparator::SORTTYPE_ASC,
  'created' => NodeComparator::SORTTYPE_DESC
];
$comparator = new NodeComparator($sortCriteria);
 
// sort node list
usort($nodeList, [$comparator, 'compare']);
```
</div>
 
#### Pagination #### {#pers_pagination}
 
A common pattern for reducing the response time of an application when displaying large lists
of objects is [pagination](http://en.wikipedia.org/wiki/Pagination#Pagination_in_web_content).
This technique splits the list into smaller parts (_pages_) that are displayed
one by one. In wCMF the class \link wcmf::lib::persistence::PagingInfo `PagingInfo`\endlink
implements the concept.
 
The following code shows how to load _25_ `Author` instances starting from
position _50_:
 
<div class="php">
```
// setup paging
$pagingInfo = new PagingInfo(25);
$pagingInfo->setOffset(50);
 
// load Author instances
$authors = ObjectFactory::getInstance('persistenceFacade')->loadObjects('Author', BuildDepth::SINGLE, null, null, $pagingInfo);
```
</div>
 
Pagination is also possible over __multiple entity types__:
 
<div class="php">
```
// setup paging
$pagingInfo = new PagingInfo(25);
$pagingInfo->setOffset(50);
 
// load Author and Publisher instances ordered by creation date
$types = ['Author', 'Publisher'];
$order = ['created'];
$objects = ObjectFactory::getInstance('persistenceFacade')->loadObjects($types, BuildDepth::SINGLE, null, $order, $pagingInfo);
```
</div>
 
### Searching objects ### {#pers_search}
 
To search objects in the store the
\link wcmf::lib::persistence::PersistenceFacade::loadObjects `PersistenceFacade::loadObjects`\endlink
method is used. It allows to set the conditions that loaded objects should match.
 
<div class="php">
```
$criteria = [
  new Criteria("Article", "title", "LIKE", "A%"),
  new Criteria("Article", "year", ">=", "2014")
]
 
// load all Article instances with titles starting with A and release date 2014 or later
$articles = ObjectFactory::getInstance('persistenceFacade')->loadObjects("Article", BuildDepth::SINGLE, $criteria);
```
</div>
 
In this example all `Article` instances with titles starting with _A_ and release date
_2014 or later_ are loaded.
 
#### Null values #### {#pers_search_null}
 
Null values are matched/not matched using the following criteria:
 
<div class="php">
```
new Criteria("Article", "title", "=", null); // translates to Article.title IS NULL
new Criteria("Article", "title", "!=", null); // translates to Article.title IS NOT NULL
```
</div>
 
#### Object queries #### {#pers_search_object_queries}
 
More complex use cases are supported by the \link wcmf::lib::model::ObjectQuery `ObjectQuery`\endlink
class. For example it allows to set search constraints on connected objects as
shown in the following example:
 
<div class="php">
```
// create a Author query
$query = new ObjectQuery('Author');
 
// query part: Author.name LIKE 'A%' OR Author.name LIKE 'B%'
$authorTpl1 = $query->getObjectTemplate("Author");
$authorTpl1->setValue("name", Criteria::asValue("LIKE", "A%"));
$authorTpl2 = $query->getObjectTemplate("Author", null, Criteria::OPERATOR_OR);
$authorTpl2->setValue("name", Criteria::asValue("LIKE", "B%"));
 
// query part: Article.created >= '2004-01-01' AND Article.created < '2005-01-01'
$articleTpl1 = $query->getObjectTemplate("Article");
$articleTpl1->setValue("created", Criteria::asValue(">=", "2004-01-01"));
$articleTpl2 = $query->getObjectTemplate("Article");
$articleTpl2->setValue("created", Criteria::asValue("<", "2005-01-01"));
 
// connect query nodes
$authorTpl1->addNode($articleTpl1);
$authorTpl1->addNode($articleTpl2);
 
// load result
$authorList = $query->execute(BuildDepth::SINGLE);
```
</div>
 
In this example all `Author` instances are loaded which have names starting with
_A_ or _B_ and which have `Article` instances connected that are created in the
year _2014_.
 
It is possible to combine several object queries to apply pagination over __multiple entity types__
using the \link wcmf::lib::persistence::UnionQuery `UnionQuery`\endlink class:
 
<div class="php">
```
// create a Author query
$authorQuery = new ObjectQuery('Author');
// ... define query
 
// create a Publisher query
$publisherQuery = new ObjectQuery('Publisher');
// ... define query
 
// setup paging
$pagingInfo = new PagingInfo(25);
$pagingInfo->setOffset(50);
 
// load Author and Publisher instances ordered by creation date
$queryProvider = new ObjectQueryUnionQueryProvider([$authorQuery, $publisherQuery]);
$order = ['created'];
$objects = UnionQuery::execute($queryProvider, BuildDepth::SINGLE, $order, $pagingInfo);
```
</div>
 
Besides this, wCMF integrates the
[Lucene](http://framework.zend.com/manual/1.12/en/zend.search.lucene.overview.html)
search engine in the class \link wcmf::lib::search::impl::LuceneSearch `LuceneSearch`\endlink.
 
### Iterating objects ### {#pers_iter}
 
wCMF provides several [iterator](http://php.net/manual/en/class.iterator.php)
classes for traversing objects and values.
 
\link wcmf::lib::model::NodeIterator `NodeIterator`\endlink allows to traverse
object graphs starting from a root \link wcmf::lib::model::Node `Node`\endlink.
The algorithm used is [depth-first search](http://en.wikipedia.org/wiki/Depth-first_search).
 
<div class="php">
```
// traverse $root and all descendents
$it = new NodeIterator($root);
foreach($it as $oid => $obj) {
  echo "current object id: $oid";
  echo "current object: $obj";
}
```
</div>
 
\link wcmf::lib::model::NodeValueIterator `NodeValueIterator`\endlink is used
to iterate over all persistent values of a \link wcmf::lib::model::Node `Node`\endlink.
 
<div class="php">
```
// traverse all values of $object
$it = new NodeValueIterator($object);
for($it->rewind(); $it->valid(); $it->next()) {
  echo "current object: ".$it->currentNode();
  echo "current attribute name: ".$it->key();
  echo "current attribute value: ".$it->current();
}
```
</div>
 
\link wcmf::lib::model::PersistentIterator `PersistentIterator`\endlink allows
to traverse object graphs as well, but it's state could be persisted to split the
iteration of large lists into smaller parts.
 
<div class="php">
```
// traverse 10 nodes starting from $oid
$counter = 0;
$it = new PersistentIterator($oid);
while($it->valid() && $counter < 10) {
  echo "current object: ".$it->currentNode();
  $it->next();
  $counter++;
}
 
// save iterator state in the session
$iterId = $it->save();
 
// load the iterator state later and traverse the remaining nodes
$it = PersistentIterator::load($iterId);
while($it->valid()) {
  echo "current object: ".$it->currentNode();
  $it->next();
}
```
</div>
 
### Creating / Modifying objects ### {#pers_create_modify}
 
Domain class instances are created by calling the
\link wcmf::lib::persistence::PersistenceFacade::create `PersistenceFacade::create`\endlink
method or simply the class constructor, where the first approach is preferred
over the second because it also sets the default values on attributes.
 
Changes on instances are persisted automatically, when the current transaction
is committed (see \ref pers_tx). Objects are removed from the store by calling the
\link wcmf::lib::persistence::PersistentObject::delete `PersistentObject::delete`\endlink
method.
 
<div class="php">
```
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
$tx = $persistenceFacade->getTransaction();
 
// create an Author instance
$author = $persistenceFacade->create('Author');
$author->setValue('name', 'Author A');
 
// create an Article instance and attach it to the author
$article = $persistenceFacade->create('Article');
$article->setValue('title', 'Article A');
$author->addNode($article);
 
// save everything
$tx->commit();
 
// get the author's object id
$oid = $author->getOID()
 
// delete the author instance
$author = $persistenceFacade->load($oid);
$author->delete();
 
// save everything
$tx->commit();
```
</div>
 
## Validation ## {#pers_validation}
 
Before persisting objects, their content has to be validated according to the
application requirements. Validation is handled in
\link wcmf::lib::persistence::PersistentObject::validateValue `PersistentObject::validateValue`\endlink
(for a single attribute) or
\link wcmf::lib::persistence::PersistentObject::validateValues `PersistentObject::validateValues`\endlink
(for the complete instance). These methods are called when values are changed via
\link wcmf::lib::persistence::PersistentObject::setValue `PersistentObject::setValue`\endlink
or right before persisting the object in
\link wcmf::lib::persistence::impl::AbstractMapper::save `AbstractMapper::save`\endlink.
Both validation methods throw a
\link wcmf::lib::persistence::ValidationException `ValidationException`\endlink, if
validation fails.
 
### Validation types ### {#pers_validation_types}
 
The actual validation is delegated to the
\link wcmf::lib::validation::Validator::validate `Validator::validate`\endlink
method, which gets a __validation description string__ passed. This string defines
a single \link wcmf::lib::validation::ValidateType `ValidateType`\endlink or a
combination of those. The
\link wcmf::lib::validation::ValidateType::validate `ValidateType::validate`\endlink
method accepts an associative array of configuration options, that is encoded into
a JSON string when being used in the validation description string. An additional
__validation context__ might be passed to the method (e.g. the entity instance and
the currently validated entity attribute), when validation entity values.
 
To define which validation should be applied to a domain class attribute, the
_tag_ `restrictions_match` is used in the model (see \ref model_chivalue).
 
Currently the following validation types exist (the examples show their usage
in a validation description string):
 
\link wcmf::lib::validation::impl::Date `Date`\endlink
validates against a date format, e.g.
 
<div class="php">
```
// validate against the default date format ('Y-m-d')
date
 
// validate against a custom date format ('Y-m-d')
date:{"format":"j-M-Y"}
```
</div>
 
\link wcmf::lib::validation::impl::Filter `Filter`\endlink
validates against a PHP filter (see [filter_var](http://php.net/manual/en/function.filter-var.php)), e.g.
 
<div class="php">
```
// FILTER_VALIDATE_INT with min_range option and FILTER_FLAG_ALLOW_HEX flag
filter:{"type":"int","options":{"options":{"min_range":0},"flags":2}}
```
</div>
 
\link wcmf::lib::validation::impl::Image `Image`\endlink
checks _width_ and _height_ of the referred image file e.g.
 
<div class="php">
```
// image width exactly 200px, height less than 100px
image:{"width":[200,1],"height":[100,0]}
```
</div>
 
\link wcmf::lib::validation::impl::RegExp `RegExp`\endlink
validates against a regular expression (see [preg_match](http://php.net/manual/en/function.preg-match.php)) e.g.
 
<div class="php">
```
// integer or empty
regexp:{"pattern":"/^[0-9]*$/"}
```
</div>
 
\link wcmf::lib::validation::impl::Required `Required`\endlink
checks if the value is not empty e.g.
 
<div class="php">
```
required
```
</div>
 
\link wcmf::lib::validation::impl::Unique `Unique`\endlink
checks if the value is unique regarding the given entity attribute e.g.
 
<div class="php">
```
// explicitly define Keyword.name as being unique ...
unique:{"type":"Keyword","value":"name"}
 
// ... or implicitly when used in the entity validation context of the Keyword.name
unique
```
</div>
 
\note The validation type is derived from the part of the configuration string,
that precedes the first colon.
 
Custom validation types can be added in the configuration. For example
after adding `myValidator` (implemented in `MyValidator` class):
 
<div class="ini">
```
[Validators]
regexp = $regexpValidator
filter = $filterValidator
image = $imageValidator
myValidator = $myValidator
 
[MyValidator]
__class = path\to\MyValidator
```
</div>
 
it is used in the following way:
 
<div class="php">
```
myValidator:custom_configuration_string_passed_by_MyValidator
```
</div>
 
### Complex validation ### {#pers_validation_custom}
 
The described validation types only operate on one attribute. If more complex
validation is required, e.g. if dependencies between several attributes exist, the method
\link wcmf::lib::persistence::PersistentObject::validateValue `PersistentObject::validateValue`\endlink
could be overriden in the appropriate domain class.
 
## Concurrency ## {#pers_concurrency}
 
When two or more users try to access the same object at the same time problems
like _lost updates_ might occur. These issues are avoided by _concurrency control_
mechanisms, typically _object locking_.
 
### Locking ### {#pers_locking}
 
wCMF provides two locking strategies:
 
- __Pessimistic locking__: An explicit lock is obtained by one user, that blocks
  write access to the object for other users until the lock is released.
- __Optimistic locking__: A copy of the initial object data is stored for each user
  and checked against later, when the user tries to store the object. The operation
  fails, if another user has updated the object data in the meantime.
 
For more detailed information see
[database locks](http://en.wikipedia.org/wiki/Lock_%28computer_science%29#Database_locks).
 
\link wcmf::lib::persistence::concurrency::Lock `Lock`\endlink instances are
obtained by calling
\link wcmf::lib::persistence::concurrency::ConcurrencyManager::aquireLock `ConcurrencyManager::aquireLock`\endlink
and released using
\link wcmf::lib::persistence::concurrency::ConcurrencyManager::releaseLock `ConcurrencyManager::releaseLock`\endlink
like shown in the following example:
 
<div class="php">
```
// object id of the object to lock
$oid = new ObjectId('Author', 1);
 
// aquire an optimistic lock for the object
$lockType = Lock::TYPE_OPTIMISTIC;
$concurrencyManager = ObjectFactory::getInstance('concurrencyManager');
try {
  $concurrencyManager->aquireLock($oid, $lockType);
}
catch(PessimisticLockException $ex) {
  // another user already holds a lock on this object
  echo $ex->getMessage();
}
 
// release lock later
$concurrencyManager->releaseLock($oid, $lockType);
```
</div>
 
The actual storage and retrieval of
\link wcmf::lib::persistence::concurrency::Lock `Lock`\endlink instances is
delegated to
\link wcmf::lib::persistence::concurrency::LockHandler `LockHandler`\endlink.
The following lines show the concurrency configuration in the \ref app "default application":
 
<div class="ini">
```
[ConcurrencyManager]
__class = wcmf\lib\persistence\concurrency\impl\DefaultConcurrencyManager
lockHandler = $lockHandler
 
[LockHandler]
__class = wcmf\lib\persistence\concurrency\impl\DefaultLockHandler
lockType = app.src.model.wcmf.Lock
```
</div>
 
As you can see the
\link wcmf::lib::persistence::concurrency::LockHandler `LockHandler`\endlink
implementation is exchangeable.
 
## Transactions ## {#pers_tx}
 
wCMF supports [database transactions](http://en.wikipedia.org/wiki/Database_transaction).
There is only __one transaction at the same time__ and it is be obtained using the
\link wcmf::lib::persistence::PersistenceFacade::getTransaction `PersistenceFacade::getTransaction`\endlink
method. The transaction has an _active_ state, which is set in the
\link wcmf::lib::persistence::Transaction::begin `Transaction::begin`\endlink
method and reset on commit or rollback.
 
The following example shows, how to use transactions:
 
<div class="php">
```
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
 
// get the current transaction and start it
$transaction = $persistenceFacade->getTransaction();
$transaction->begin();
try {
  // load the the Author instance with id 1 and make changes to it
  $author = $persistenceFacade->load(new ObjectId('Author', 1));
  $author->setValue("name", "Author B");
 
  // save the changes
  $transaction->commit();
}
catch(Exception $ex) {
  // rollback the transaction if the commit fails
  echo $ex->getMessage();
  $transaction->rollback();
}
```
</div>
 
\note Even if not obtained explicitely, there is always a transaction existing
in the background, to which objects loaded from the store are attached. But to
persist changes when doing a commit, the transaction has to be set _active_
_before_ loading or creating the object.
 
There are situations where you want to let the current transaction __ignore changes__
made to newly created objects or objects loaded from the store. In these cases you
can use the method
\link wcmf::lib::persistence::Transaction::detach `Transaction::detach`\endlink
to disconnect the object from the transaction.
 
### Dry runs ### {#pers_tx_dry}
 
wCMF applies all database changes directly when committing the database transaction.
 
But there are situations where this is not desirable or just not possible. For example you might want
to review the changes bevor applying them finally. Or the work to be done inside the transaction
would exceed the provided resources (time and/or memory) and therefor must be split into smaller
pieces but still need to be carried out in a one fails, all fail manner. A typical use case for the
latter would be a large data import from external sources.
 
For these cases wCMF transactions offer the \link wcmf::lib::persistence::Transaction::commitCollect `Transaction::commitCollect`\endlink
method, which returns all statements that would be executed, if the transaction would be
commited regularly.
 
The following script shows how to do a dry run first and commit the collected statements later:
 
<div class="php">
```
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
$transaction = $this->persistenceFacade->getTransaction();
 
// create/modify/delete objects inside transaction
$transaction->begin();
// ...
// dry run after finish
$statements = $transaction->commitCollect();
 
// apply collected statements to the database
try {
  $transaction->begin();
  $conn = $this->persistenceFacade->getMapper('Project')->getConnection();
  foreach ($statements as $statement) {
    list($stmt, $params) = $statement;
    $conn->prepare($stmt)->execute($params);
  }
  $transaction->commit();
}
catch (\Exception $ex) {
  $transaction->rollback();
}
```
</div>
*/