presentation.doxy

/*!
\page presentation Presentation
<div class="has-toc"></div>
 
# Presentation # {#pres_main}
 
Presentation refers to the part of the application that is visible to the user -
the _user interface_ - and the handling of user interaction.
 
## Services ## {#pres_services}
 
The presentation layer usually depends on underlying services like persistency,
event handling, caching - just to name a few. These services typically exist as
one instance that is created on application startup and is used throughout the
whole application lifetime.
 
The preferred way to get access to a service instance in client code is to set
the dependency explicitly or let it be injected, if the instance is not created
explicitly (see \ref conf_di). But there are also situations where this is not
possible (e.g. a global function that is used by third party code). Since most
of these services are registered with
\link wcmf::lib::core::ObjectFactory `ObjectFactory`\endlink, it's
\link wcmf::lib::core::ObjectFactory::getInstance `getInstance`\endlink method
is used as a [service locator](https://en.wikipedia.org/wiki/Service_locator_pattern).
 
The following example shows how to get the persistence service at any code location:
 
<div class="php">
```
$persistenceFacade = ObjectFactory::getInstance('persistenceFacade');
```
</div>
 
## Application ## {#pres_application}
 
Web applications typically implement a _request-response pattern_, where a
client sends a
([HTTP](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol)-)request to the
application, which returns a response after processing it. wCMF encapsulates the
described procedure inside the
\link wcmf::lib::presentation::Application `Application`\endlink class. The
following code demonstrates the usage of this class in the main entry script of
the \ref app "default application".
 
<div class="php">
```
$application = new Application();
try {
  // initialize the application
  $request = $application->initialize('', '', 'cms');
 
  // run the application
  $response = $application->run($request);
}
catch (Exception $ex) {
  try {
    $application->handleException($ex);
  }
  catch (Exception $unhandledEx) {
    echo("An unhandled exception occured. Please see log file for details.");
  }
}
```
</div>
 
The example shows the three important methods of the
\link wcmf::lib::presentation::Application `Application`\endlink class:
 
- The \link wcmf::lib::presentation::Application::initialize `initialize`\endlink
  method is used to __setup__ the
  \link wcmf::lib::presentation::Application `Application`\endlink. It returns a
  \link wcmf::lib::presentation::Request `Request`\endlink instance, that could be
  modified before execution.
- The \link wcmf::lib::presentation::Application::run `run`\endlink method is
  called to __execute__ the given request. The method returns a
  \link wcmf::lib::presentation::Response `Response`\endlink instance, that is not
  used in this example.
- The \link wcmf::lib::presentation::Application::handleException `handleException`\endlink
  method is called, if an __exception__ occurs. The method rolls back the database
  transaction and calls the _failure_ action.
 
The details of request execution are the topic of the next section.
 
## Request processing ## {#pres_request}
 
The \link wcmf::lib::presentation::Request `Request`\endlink instance created
on initialization of the application provides all information about the incoming
HTTP request, that is necessary for execution. Upon execution, the following
actions are performed:
 
1. The \link wcmf::lib::presentation::Request `Request`\endlink instance is passed
   to \link wcmf::lib::presentation::ActionMapper `ActionMapper`\endlink for further
   processing.
2. The \ref arch_actionkey is determined from the request parameters.
3. \link wcmf::lib::security::PermissionManager `PermissionManager`\endlink is
   asked to authorize the action key for the current user (see \ref sec_perm_check).
4. If authorization is successful, the request data is transformed into the internal
   application format (see \ref pres_format).
5. The \link wcmf::lib::presentation::Controller `Controller`\endlink instance
   matching the request is determined (see \ref pres_routing) and executed.
6. The \link wcmf::lib::presentation::Response `Response`\endlink instance is
   obtained after execution.
7. The response data is transformed into the requested response format (see
   \ref pres_format).
8. Execution returns to step 3, if a valid action key is contained in the response
   data. It terminates, if either no action key is found or the next action key
   would be the same as the previous (to prevent recursion).
 
### Formats ### {#pres_format}
 
wCMF is designed to be able to consume various request formats and produce
several response formats. While some clients communicate using
[JSON](http://en.wikipedia.org/wiki/JSON) format, others might prefer to encode
data in [XML](http://en.wikipedia.org/wiki/XML).
\link wcmf::lib::presentation::format::Formatter `Formatter`\endlink
is used to determine the required format and delegate the actual formatting to
the correct \link wcmf::lib::presentation::format::Format `Format`\endlink
implementation. wCMF currently provides the following __implementations__:
 
- \link wcmf::lib::presentation::format::impl::HtmlFormat `HtmlFormat`\endlink
  expects all data to be sent as key-value-pairs. Object data are transferred in
  parameters named `value-`<em>name-oid</em> (e.g. `value-title-Book:3`).
  Responses in this format are rendered as HTML views (see \ref pres_views).
- \link wcmf::lib::presentation::format::impl::JsonFormat `JsonFormat`\endlink
  handles JSON encoded request data and encodes response data into the same format.
- \link wcmf::lib::presentation::format::impl::SoapFormat `SoapFormat`\endlink
  is used together with the [NuSOAP](http://sourceforge.net/projects/nusoap/)
  library to implement a SOAP interface.
- \link wcmf::lib::presentation::format::impl::GenericFormat `GenericFormat`\endlink
  is used to output arbitrary responses.
- \link wcmf::lib::presentation::format::impl::DownloadFormat `DownloadFormat`\endlink
  is used to create a downloadable reponse document. It is automatically chosen, if
  the \link wcmf::lib::presentation::Response::setDocument `Response::setDocument`\endlink
  method is called with a \link wcmf::lib::presentation::ResponseDocument `ResponseDocument`\endlink.
- \link wcmf::lib::presentation::format::impl::NullFormat `NullFormat`\endlink
  is used internally, if no formatting is required, e.g. if one controller calls
  another controller.
 
If not explicitely set, the request and response format is automatically
determined from the __HTTP headers__ sent with the request:
 
- The `Content-Type` header defines the __request__ format
- The `Accept` header defines the __response__ format
 
To find the correct format, the
[Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml)
value set in those headers is matched against the mime type of all registered
formats (see
\link wcmf::lib::presentation::format::Format::getMimeType `Format::getMimeType`\endlink).
 
Formats are defined in the `Formats` configuration section as shown in the following
example:
 
<div class="ini">
```
[Formats]
html = $htmlFormat
null = $nullFormat
 
[HtmlFormat]
__class = wcmf\lib\presentation\format\impl\HtmlFormat
 
[NullFormat]
__class = wcmf\lib\presentation\format\impl\NullFormat
```
</div>
 
### Routing ### {#pres_routing}
 
Routing is the process of selecting the correct
\link wcmf::lib::presentation::Controller `Controller`\endlink for a given request.
wCMF distinguishes between _internal_ and _external_ routing.
 
#### Internal routing #### {#pres_routingint}
 
Internal routing takes place after the \link wcmf::lib::presentation::Request `Request`\endlink
instance is created and initialized. wCMF inspects the __action key__ formed from
it's _sender_, _context_ and _action_ parameters (see \ref arch_actionkey) to
determine the controller to be executed for the request. The mapping of action
keys to controllers is defined in the `ActionMapping` configuration section.
 
If the executed controller together with the _context_ and _action_ parameters of
the response match another action key, the corresponding controller
will be executed afterwards. This allows to __chain actions__ together. If no
matching action key is found, the response is returned to the client.
 
The following code is taken from the \ref app "default application" configuration
and shows the configuration of the indexing process (see \ref pres_longrequest):
 
<div class="ini">
```
[ActionMapping]
??indexAll = wcmf\application\controller\SearchIndexController
wcmf\application\controller\SearchIndexController??continue =
                            wcmf\application\controller\SearchIndexController
```
</div>
 
- The first line states that the action _indexAll_ called from _any_ controller and
  in _any_ context will invoke
  \link wcmf::application::controller::SearchIndexController `SearchIndexController`\endlink,
  which will set a state dependent action name on the response (see
  \link wcmf::application::controller::BatchController `BatchController`\endlink).
- The second line tells \link wcmf::lib::presentation::ActionMapper `ActionMapper`\endlink
  to re-invoke
  \link wcmf::application::controller::SearchIndexController `SearchIndexController`\endlink,
  if it was the last controller and the action is _continue_. So this action key
  only matches, if the last controller was
  \link wcmf::application::controller::SearchIndexController `SearchIndexController`\endlink.
 
##### Controller methods ##### {#pres_controller_methods}
 
The previous example maps the action keys to a controller class without specifying
a method to be called. In these cases, the framework calls the default method
`doExecute`, which must then be defined in the controller class (see \ref pres_controllers).
 
Alternatively a specific __controller method__ to be called could be defined in the
action mapping, like illustrated in the following example:
 
<div class="ini">
```
[ActionMapping]
??indexAll = wcmf\application\controller\SearchIndexController::doBegin
wcmf\application\controller\SearchIndexController??continue =
                            wcmf\application\controller\SearchIndexController::doContinue
```
</div>
 
In this case \link wcmf::application::controller::SearchIndexController `SearchIndexController`\endlink
would have to define the methods `doBegin` and `doContinue` which are called
for the appropriate action keys.
 
#### External routing #### {#pres_routingext}
 
The mapping of the current __request uri__ to an __action key__ is called external
routing. The default mapping logic is implemented in the
\link wcmf::lib::presentation::impl::DefaultRequest::initialize `DefaultRequest::initialize`\endlink
method. The method matches the _path part_ of the request uri against the entries
of the `Routes` configuration section to find an appropriate action key.
 
__Variables__ declared in path segments will be automatically passed as request parameters,
but would be overwritten by explicit request parameters if provided. The character <em>*</em> is used
as _wildcard_. Regular expression __patterns__ can be added to variables to narrow
the set of possibilities.
 
The following example configuration taken from the \ref app "default application"
illustrates the concept:
 
<div class="ini">
```
[Routes]
POST/session = action=login
DELETE/session = action=logout
/rest/{language}/{className} = action=restAction&collection=1
/rest/{language}/{className}/{id|[0-9]+} = action=restAction&collection=0
GET/* = action=cms
```
</div>
 
- The first two entries define the login and logout routes using the appropriate
  HTTP methods.
- The third entry defines the _language_ and _className_ variables (surrounded
  by curly braces) and would be matched by the request uris <em>/rest/de/Author</em>
  or <em>/rest/en/Book</em>. The executed action would be _restAction_.
- The _id_ variable in the next entry must be an integer because of the regular
  expression constraint `[0-9]+`.
- The last entry is matched by any GET request to a path that was not matched before.
  It is mapped to the _cms_ action - corresponding to the action key <em>??cms</em>.
 
@note Any requests on routes that are __not__ defined in the `Routes` configuration
section will cause a `404` error. This is why this section is also considered the
_public_ interface of the application.
 
##### Precedence rules #####
 
Due to the use of variables in route definitions several routes might match a given
request. This leads to the question which route to take, since the application only
processes one per request. To find the best matching route
\link wcmf::lib::presentation::impl::DefaultRequest `DefaultRequest`\endlink orders
all matching routes and takes the first one. The sorting is done under the assumption
that a more specific route is a better match.
 
The following __rules__ are implemented to find the more specific route:
- the route with _less variables_ is more specific and if two routes have the same number of variables
- the route with _more patterns_ in the variable definitions is more specific.
 
In cases where these simple rules are not sufficient, you could configure a __custom__
\link wcmf::lib::presentation::Request `Request`\endlink implementation (see \ref conf_di)
which overrides the \link wcmf::lib::presentation::impl::DefaultRequest::isMatch `DefaultRequest::isMatch`\endlink
method.
 
##### HTTP methods #####
 
To restrict a path to one or more __HTTP methods__, they are added in front of
the route definition. In the following example the _cms_ action is only available
for the _GET_ method, while the other actions accept _GET_, _POST_, _PUT_ and
_DELETE_ requests:
 
<div class="ini">
```
[Routes]
GET/ = action=cms
GET,POST,PUT,DELETE/rest/{language}/{className} = action=restAction&collection=1
GET,POST,PUT,DELETE/rest/{language}/{className}/{id|[0-9]+} = action=restAction&collection=0
```
</div>
 
If no method is added to a route, all methods are accepted.
 
## Controllers ## {#pres_controllers}
 
Controllers take the user input from the request and modify the model according
to it. As a result a response is created which is presented to the user in a view
or any other format. Which controller is executed on a specific request is
determined in the routing process (see \ref pres_routing).
 
wCMF provides \link wcmf::lib::presentation::Controller `Controller`\endlink as
abstract base class for controller implementations. There are three important
methods defined in this class, which are called by
\link wcmf::lib::presentation::ActionMapper `ActionMapper`\endlink in the following order:
 
1. \link wcmf::lib::presentation::Controller::initialize `Controller::initialize`\endlink
  is called directly after instantiation of the controller. The current
  \link wcmf::lib::presentation::Request `Request`\endlink and
  \link wcmf::lib::presentation::Response `Response`\endlink instances are passed
  as parameters and subclasses can override this method to implement task specific
  initializations.
2. \link wcmf::lib::presentation::Controller::validate `Controller::validate`\endlink
  is called afterwards to check the validity of the request parameters. The default
  implementation returns _true_ and subclasses are assumed to override this method
  if necessary to do task specific validations.
3. \link wcmf::lib::presentation::Controller::execute `Controller::execute`\endlink
  is called finally. This method accepts a parameter, that defines the actual
  method to be called on the subclass. If the parameter is omitted it defaults
  to `doExecute` which must then be defined in the subclass (see \pres_controller_methods).
 
Controllers can _redirect_ to other controllers by using the
\link wcmf::lib::presentation::Controller::redirect `Controller::redirect`\endlink
method.
 
If variables need to be shared between several requests to the same controller they can
be stored in _local session variables_ to avoid side effects (see
\link wcmf::lib::presentation::Controller::setLocalSessionValue `Controller::setLocalSessionValue`\endlink).
 
### Error handling ### {#pres_errors}
 
Errors are typically divided into __fatal errors__ and __non-fatal errors__.
 
By definition the application is not able to recover from a _fatal error_, meaning
that it's not functioning correctly. An example would be a programming error or
a missing vital resource. These errors normally need to be fixed by the application
maintainer. In case of _non-fatal errors_ a notice to the user is sufficient in most
cases. A typical example would be invalid user input, that can be fixed by the user
itself.
 
In wCMF the following two strategies are recommended for handling these kind of
situations:
 
- In case of a __fatal error__, an exception should be thrown. If it is not caught
  inside the application code, it will bubble up to the main script (usually
  _index.php_). In case the application is set up like in the \ref pres_application
  section, the method
  \link wcmf::lib::presentation::Application::handleException `Application::handleException`\endlink
  will be called. This method rolls back the current transaction and calls the
  _failure_ action, which is executed by
  \link wcmf::application::controller::FailureController `FailureController`\endlink
  by default.
 
- If a __non-fatal error__ occurs, an instance of
  \link wcmf::lib::presentation::ApplicationError `ApplicationError`\endlink
  should be created and added to the response using the
  \link wcmf::lib::presentation::Response::addError `Response::addError`\endlink
  method. The error class provides the
  \link wcmf::lib::presentation::ApplicationError::get `ApplicationError::get`\endlink
  method to retrieve predefined errors. The following example shows how to signal
  an invalid _type_ parameter while request validation:
 
<div class="php">
```
$response->addError(ApplicationError::get('PARAMETER_INVALID',
  ['invalidParameters' => ['type']]));
```
</div>
 
### Action composition ### {#pres_controllers_composite}
 
The \ref pres_routingint section describes how chaining controller actions works.
This is usefull, if there is a sequence of actions to be executed. If a complex action
can be composed from simpler (already existing) actions, it is also possible to
execute another controller _inside_ a controller action and return to that action afterwards.
This is done using the
\link wcmf::lib::presentation::Controller::executeSubAction `Controller::executeSubAction`\endlink
method. An example is \link wcmf::application::controller::RESTController `RESTController`\endlink
which serves as a facade to the CRUD controllers.
 
### Automatic transactions ### {#pres_controllers_transaction}
 
To run a controller method inside a persistence transaction the convenience method 
\link wcmf::lib::presentation::Controller::requireTransaction `Controller::requireTransaction`\endlink
can be called at the beginning of the method. This call will start a transaction or join the already
opened one. The transaction will be automatically committed after method execution or rolled back in
case of an exception. Calls to \link wcmf::lib::presentation::Controller::executeSubAction `Controller::executeSubAction`\endlink
will use the same transaction.
 
### Long running requests ### {#pres_longrequest}
 
There are situations where you want to split a long running process into parts,
because it's exceeding memory or time limits or simply to give the user feedback
about the progress. By subclassing
\link wcmf::application::controller::BatchController `BatchController`\endlink
the implementation of this behavior is as simple as defining the steps of
the process in the
\link wcmf::application::controller::BatchController::getWorkPackage `BatchController::getWorkPackage`\endlink
method.
 
\link wcmf::application::controller::SearchIndexController `SearchIndexController`\endlink
is an example for a controller implementing a long running process. It is used
to create a Lucene search index over all searchable entity objects. The process
is split into collecting all object ids and then indexing them. In the final
step the index is optimized.
 
## Views ## {#pres_views}
 
Views are used to present application information to the user. In a web application
they are typically HTML pages displayed in the browser.
 
In wCMF the response will be turned into an HTML page, if the `Accept` HTTP header
is set to _text/html_ (see \ref pres_format). The appropriate
\link wcmf::lib::presentation::format::Format `Format`\endlink implementation is
\link wcmf::lib::presentation::format::impl::HtmlFormat `HtmlFormat`\endlink.
It renders the response into a template file using the configured
\link wcmf::lib::presentation::view::View `View`\endlink implementation. The format
of the template files depends on that implementation. Since different
actions could require different views to be displayed, a mapping of action keys to
view templates is defined in the `Views` configuration section.
 
The following example shows the configuration of the
\link wcmf::lib::presentation::view::impl::SmartyView `SmartyView`\endlink class
and the mapping of action keys to views in the \ref app "default application":
 
<div class="ini">
```
[View]
__class = wcmf\lib\presentation\view\impl\SmartyView
__shared = false
compileCheck = true
caching = false
cacheLifetime = 3600
cacheDir = app/cache/smarty/
 
[Views]
app\src\controller\RootController?? = app/src/views/cms.tpl
```
</div>
 
Since the \ref app "default application" only uses an HTML page to bootstrap the
actual [Dojo](https://dojotoolkit.org/) application, there is only one view mapping
for `RootController`.
 
### Device dependent views ###
 
\link wcmf::lib::presentation::format::impl::HtmlFormat `HtmlFormat`\endlink
allows to provide different versions of a view template. This is especially
useful, if you want to deliver device dependent content for the same action key.
 
To select a specific template version, the property `html_tpl_format` has to be set
on the response instance (see \link wcmf::lib::presentation::ControllerMessage::setProperty `ControllerMessage::setProperty`\endlink). 
E.g. if the template file would be _home.tpl_, setting the value to _mobile_ would 
select the template file _home-mobile.tpl_. If the requested version does not exist, 
it is ignored and the default template is used (_home.tpl_ in this example).
 
## Webservice APIs ## {#pres_apis}
 
Besides the user interface driven \ref app "default application" wCMF provides
APIs for using the application as a [web service](https://en.wikipedia.org/wiki/Web_service).
These APIs provide create/read/update/delete
([CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete))
operations on all entity types.
 
### RESTful API ###
 
The [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)ful
interface is implemented in
\link wcmf::application::controller::RESTController `RESTController`\endlink,
which basically acts as a facade in front of the application. That means the
controller checks the request data only and delegates the actual processing to
the action specific controller.
 
The following example shows the configuration of the RESTful interface in the
\ref app "default application":
 
<div class="ini">
```
[Routes]
/rest/{language}/{className} = action=restAction&collection=1
/rest/{language}/{className}/{id|[0-9]+} = action=restAction&collection=0
/rest/{language}/{className}/{sourceId|[0-9]+}/{relation} = action=restAction&collection=1
/rest/{language}/{className}/{sourceId|[0-9]+}/{relation}/{targetId|[0-9]+} = action=restAction&collection=0
 
[ActionMapping]
??restAction = wcmf\application\controller\RESTController
```
</div>
 
The `Routes` configuration section defines the urls for the interface. They all
call the action _restAction_ internally, which is handled by
\link wcmf::application::controller::RESTController `RESTController`\endlink as
defined in the `ActionMapping` section. For example the english version of
the `Author` instance with id _1_ is retrieved by making a GET request to
the url <em>/rest/en/Author/1</em>.
 
### SOAP API ###
 
wCMF uses the [NuSOAP](http://sourceforge.net/projects/nusoap/) library for
implementing the SOAP interface. It consists of the
\link wcmf::lib::service::SoapServer `SoapServer`\endlink and
\link wcmf::application::controller::SOAPController `SOAPController`\endlink classes.
The controller class handles all requests and delegates the processing to the
server class. The service description in the
[WSDL](https://en.wikipedia.org/wiki/Web_Services_Description_Language) format
is generated by the code generator into a file called _soap-interface.php_
(see \ref generator_artefacts_php).
 
The following example shows the configuration of the SOAP interface in the
\ref app "default application":
 
<div class="ini">
```
[Routes]
/soap = action=soapAction
 
[ActionMapping]
??soapAction = wcmf\application\controller\SOAPController
```
</div>
 
The `Routes` configuration section defines that the url <em>/soap</em> redirects
to the action _soapAction_ internally. The `ActionMapping` section defines that
this action is handled by
\link wcmf::application::controller::SOAPController `SOAPController`\endlink.
The interface description is available at the url <em>/soap?wsdl</em>.
 
## Caching ## {#pres_caching}
 
Caching is an effective method to improve application performance. Caches in wCMF
are supposed to be divided into sections, which hold key-value pairs (see
\link wcmf::lib::io::Cache `Cache`\endlink interface). Cache instances are
defined in the application configuration and retrieved by using
\link wcmf::lib::core::ObjectFactory `ObjectFactory`\endlink, which makes it easy
to exchange the underlying caching implementation.
 
The following example shows the configuration of a
\link wcmf::lib::io::impl::FileCache `FileCache`\endlink instance in the
\ref app "default application":
 
<div class="ini">
```
[Cache]
__class = wcmf\lib\io\impl\FileCache
cacheDir = app/cache/
```
</div>
 
The usage of this cache is illustrated in the code example:
 
<div class="php">
```
$cache = ObjectFactory::getInstance('cache');
$cacheSection = 'calculations';
 
$cacheKey = 'resultA';
if (!$cache->exists($cacheSection, $cacheKey)) {
  // calculate the result and store it in the cache
  $result = complexCalculationA();
  $cache->put($cacheSection, $cacheKey, $value);
}
else {
  // retrieve the result from the cache
  $resultA = $cache->get($cacheSection, $cacheKey);
}
```
</div>
 
Supposed that `complexCalculationA` in this example takes long to finish, it
should only run once at the first time the result is needed. So we check if
_resultA_ is already cached and calculate it, if not. Since it is put it into the
cache after calculation, it can be retrieved _resultA_ directly from there the
next time it is needed.
 
### Response caching ### {#pres_response_caching}
 
Besides setting caching headers by using the
\link wcmf::lib::presentation::Response::setHeader `Response::setHeader`\endlink
method, wCMF provides a convenient way to set the `Etag` and `Last Modified`
headers on the response.
 
All one needs to do is derive a _cache identifier_ from the request data, that
allows to distinguish different requests and set it on the response
using the \link wcmf::lib::presentation::Response::setCacheId `Response::setCacheId`\endlink
method. If the used \link wcmf::lib::presentation::format::Format `Format`\endlink
is capable of caching
(e.g. \link wcmf::lib::presentation::format::impl::HtmlFormat `HtmlFormat`\endlink)
it will provide the _last modified date_ from the cached data.
\link wcmf::lib::presentation::format::impl::DefaultFormatter `DefaultFormatter`\endlink
will then use this information to create the `Etag` and `Last Modified` headers:
 
<div class="shell">
```
...
Cache-Control:public
ETag:"93256174cf75e43ba8172a6ce01ceded"
Last-Modified:Fri, 07 Oct 2016 19:19:13 GMT
...
```
</div>
 
Another advantage of using a _cache identifier_ is the possibility to avoid
expensive calculations in \link wcmf::lib::presentation::Controller `Controller`\endlink
implementations by using the
\link wcmf::lib::presentation::Response::isCached `Response::isCached`\endlink
method. The following example shows it's usage:
 
<div class="php">
```
// define a unique id for the request data and set it on the response
$cacheId = $pageId.$language;
$response->setCacheId($cacheId);
 
if (!$response->isCached()) {
  // this will be executed only, if the response is not cached yet
  ...
}
```
</div>
 
## Events ## {#pres_events}
 
Events are a way to decouple parts of a software by introducing an indirect
communication. They allow clients to react to certain application events without
the event source knowing them. wCMF uses the
[publish-subscribe](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern)
messaging pattern, in which \link wcmf::lib::core::EventManager `EventManager`\endlink
acts as the message broker. Subscribers use this class to register for certain
\link wcmf::lib::core::Event `Event`\endlink types and publishers to send the
events.
 
The following events are defined in wCMF:
 
- \link wcmf::lib::persistence::PersistenceEvent `PersistenceEvent`\endlink
  is sent whenever a \link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink
  instance is created, updated or deleted.
- \link wcmf::lib::persistence::PropertyChangeEvent `PropertyChangeEvent`\endlink,
  \link wcmf::lib::persistence::ValueChangeEvent `ValueChangeEvent`\endlink and
  \link wcmf::lib::persistence::StateChangeEvent `StateChangeEvent`\endlink
  signal changes in \link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink
  instances.
- \link wcmf::lib::persistence::TransactionEvent `TransactionEvent`\endlink
  is fired at different phases of a transaction.
- \link wcmf::lib::presentation::ApplicationEvent `ApplicationEvent`\endlink
  allows to listen to the different steps of the request handling process.
 
The event system can be extended by custom events by inheriting from the
\link wcmf::lib::core::Event `Event`\endlink class.
 
The class below is a basic example for a listener that subscribes to persistence
events:
 
<div class="php">
```
class PersistenceEventListener {
  private $_eventListener = null;
 
  public function __construct(EventListener $eventListener) {
    $this->_eventListener = $eventListener;
    $this->_eventListener->addListener(PersistenceEvent::NAME,
      [$this, 'persisted']);
  }
 
  public function __destruct() {
    $this->_eventListener->removeListener(PersistenceEvent::NAME,
      [this, 'persisted']);
  }
 
  /**
   * Listen to PersistenceEvent
   * @param $event PersistenceEvent instance
   */
  public function persisted(PersistenceEvent $event) {
    // do something on any create/update/delete
  }
}
```
</div>
 
@note To prevent memory leaks the
\link wcmf::lib::core::EventManager::removeListener `EventManager::removeListener`\endlink
method __must__ be called, if the event listener is destroyed.
 
To send a persistence event, the following code is used:
 
<div class="php">
```
$eventListener = ObjectFactory::getInstance('eventManager');
$eventListener->dispatch(PersistenceEvent::NAME,
        new PersistenceEvent($object, PersistenceAction::UPDATE));
```
</div>
 
### Implicit listener installation ### {#pres_listeners}
 
In some cases you might want to install event listeners without explicitely
instantiating them, because there is no appropriate place for that. For these
cases the \link wcmf::lib::presentation::Application `Application`\endlink class
reads the `listeners` value of the `Application` configuration section and
initializes all instances listed there.
 
The \ref app "default application" defines two listeners as shown in the following
example:
 
<div class="ini">
```
[Application]
listeners = {Search, EventListener}
```
</div>
 
Each entry in the `listeners` array is supposed to refer to an instance
configuration (see \ref conf_di).
 
## Logging ## {#pres_log}
 
wCMF integrates the logging frameworks [log4php](http://logging.apache.org/log4php/)
and [Monolog](https://github.com/Seldaek/monolog). To abstract from these libraries
wCMF defines the \link wcmf::lib::core::Logger `Logger`\endlink interface and
implementations for each framework. The decision, which framework to use is made
by instantiating the appropriate \link wcmf::lib::core::Logger `Logger`\endlink
instance and passing it to the
\link wcmf::lib::core::LogManager::configure `LogManager::configure`\endlink
method as shown for _Monolog_ in the following example:
 
<div class="php">
```
$logger = new MonologFileLogger('main', WCMF_BASE.'app/config/log.ini');
LogManager::configure($logger);
```
</div>
 
Afterwards \link wcmf::lib::core::Logger `Logger`\endlink instances can be retrieved
using the following code:
 
<div class="php">
```
$logger = LogManager::getLogger(__CLASS__);
```
</div>
 
The parameter used in the
\link wcmf::lib::core::LogManager::getLogger `LogManager::getLogger`\endlink method
is the _logger name_. It's a good practice to use the `__CLASS__` constant as logger
 name, since this allows to enable/disable loggers by class names in the configuration
(see \ref conf_logging).
 
The following example shows how to log an error message with a stack trace
appended (see
\link wcmf::lib::core::ErrorHandler::getStackTrace `ErrorHandler::getStackTrace`\endlink):
 
<div class="php">
```
$logger->error("An error occured.\n".ErrorHandler::getStackTrace());
```
</div>
*/