architecture.doxy

/*!
\page architecture Architecture
<div class="has-toc"></div>

# Architecture # {#arch_main}

The main architectural concept of wCMF is the well known [Model-View-Controller]
(http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) pattern.
The following sections describe it's implementation in wCMF and introduce some
other key concepts, that are useful to know when using wCMF.

## Model ## {#arch_model}

An application is usually based on a _domain model_ that represents the real-world
concepts of the domain of interest. In object oriented programming this model is
implemented using classes. Depending on the application requirements the instances
of several of these classes have to be persisted in a storage to keep the contained
data. These classes represent the _data model_. The classes that provide the
infrastructure for storing data form the _persistence layer_.

wCMF defines \link wcmf::lib::persistence::PersistentObject `PersistentObject`\endlink
as base class for persistent domain classes. It mainly implements an unique identifier
for each instance (see \ref arch_oid), tracking of the persistent state, methods for setting
and getting values as well as callback methods for lifecycle events. For the composition
of object graphs the derived class \link wcmf::lib::model::Node `Node`\endlink is used
as base class. It implements relation support for persistent objects.

To retrieve persisted objects \link wcmf::lib::persistence::PersistenceFacade `PersistenceFacade`\endlink
is used. The actual operations for creating, reading, updating and deleting objects
(e.g. SQL commands) are defined in classes implementing the
\link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink interface
(see [Data Mapper Pattern](http://martinfowler.com/eaaCatalog/dataMapper.html)).
Although not necessary there usually exists one mapper class for each persistent
domain class. Mapper classes are introduced to the persistent facade by configuration.

\image html persistence.png "Persistence layer"

Please refer to the section \ref persistence for a more detailed description of the
persistence layer.

### Object Identifier ### {#arch_oid}

For handling lots of different domain objects an unique identification is crucial.
To achieve this, so-called _Object Identifiers_ (_OID_ or _object id_) are used.
Various strategies are possible to obtain these identifiers, e.g. a central registry.

wCMF composes these object ids from the type of the persistent domain class and a
number, which is unique for each type (e.g. _Author::1_). It is important that the object's
type can be derived from the object id, because this enables the
\link wcmf::lib::persistence::PersistenceFacade `PersistenceFacade`\endlink to
determine the \link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink
for the given object from the configuration. The class
\link wcmf::lib::persistence::ObjectId `ObjectId`\endlink implements this concept.

## Presentation ## {#arch_presentation}

The _presentation layer_ of a wCMF application enables users to interact with the
domain model.

Each interaction is initiated by a _request_ and results in a _response_. In a web
application the request data is sent by the user's browser to the server as GET or
POST variables.

wCMF's \link wcmf::lib::presentation::Application `Application`\endlink class
transforms the request data into a \link wcmf::lib::presentation::Request `Request`\endlink
instance. This instance is then passed to a
\link wcmf::lib::presentation::ActionMapper `ActionMapper`\endlink instance, which
creates the \link wcmf::lib::presentation::Response `Response`\endlink instance
and delegates the actual execution of the request to a
\link wcmf::lib::presentation::Controller `Controller`\endlink instance. Different
controllers exist for different actions (e.g.
\link wcmf::application::controller::ListController `ListController`\endlink for
listing objects, \link wcmf::application::controller::SearchController `SearchController`\endlink
for searching objects).

The controller is determined by matching specific request parameters against a list
of so called _action keys_ (see \ref arch_actionkey). As the result of it's execution
each controller returns action key parameters in the response data. If these parameters
match an existing action key, the associated controller will be executed by passing
the current response as input. In this way complex tasks may be executed by chaining
several controller calls together.

To support various data representations, a
\link wcmf::lib::presentation::format::Format `Format`\endlink instance is associated
with each request and response. The format is automatically determined by the HTTP
_Content-Type_ resp. _Accept_ headers. \link wcmf::lib::presentation::format::Format `Format`\endlink
implementations are responsible for de-/serializing the request and response data
into the desired format (e.g. _JSON_ or _SOAP_).
\link wcmf::lib::presentation::format::impl::HtmlFormat `HtmlFormat`\endlink especially
uses a \link wcmf::lib::presentation::view::View `View`\endlink instance to render
the response data into a HTML page. wCMF's uses [Smarty](http://www.smarty.net/)
as the default template engine for HTML output.

\image html presentation.png "Presentation layer"

Please refer to the section \ref presentation for a more detailed description of the
presentation layer.

### Action Key ### {#arch_actionkey}

An important concept of wCMF is that of _Action Keys_. An action key describes the
state of the application together with the __action__ to be performed next. The state,
which the application is in, results from the current __controller__ and the __context__,
in which it is executed. Controllers must exist as classes, whereas contexts and
actions may be arbitrary strings.

The string representation of an action key is as follows:

~~~~~~~~~~~~~{.ini}
controller?context?action
~~~~~~~~~~~~~

@note Since question marks (?) are used to separate the parts of an action key,
a question mark is not allowed inside the parts itself.

wCMF uses action keys for the following concerns:

1. In __routing definitions__ controller names are assigned action keys.
   \link wcmf::lib::presentation::ActionMapper `ActionMapper`\endlink uses these
   definitions to execute the correct controller when the application is in a
   certain state.
2. In __view definitions__ template filenames are assigned to action keys.
   \link wcmf::lib::presentation::view::View `View`\endlink determines the view
   template to be displayed for the current application state.
3. In __permission definitions__ roles are assigned to action keys. In this case
   the controller value of the action key is interpreted as resource and can
   also define an entity type or entity instance.
   \link wcmf::lib::security::PermissionManager `PermissionManager`\endlink uses
   this when checking permissions on a given resource.

Since parts of the action key can be omitted in the definition, an algorithm has
to choose, which action key fits a given value triplet best. This algorithm is
implemented in the method
\link wcmf::lib::config::ActionKey::getBestMatch `ActionKey::getBestMatch`\endlink.
It checks action key lists against the following search values until a match is
found:

~~~~~~~~~~~~~{.ini}
 1. controller?context?action
 2. controller??action
 3. controller?context?
 4. ?context?action
 5. ??action
 6. controller??
 7. ?context?
~~~~~~~~~~~~~

As a rule of thumb the action key which describes the state of the application the
most accurate is favored.

__Examples:__

The following examples are taken from the `ActionMapping` configuration section,
which defines which \link wcmf::lib::presentation::Controller `Controller`\endlink
to execute for a given action key (see \ref pres_routingint).

Always execute \link wcmf::application::controller::SaveController `SaveController`\endlink
when action _update_ is requested, no matter which state the application is in:

~~~~~~~~~~~~~{.ini}
??update = wcmf\application\controller\SaveController
~~~~~~~~~~~~~

Always execute `AuthorController` when the application context is _author_ as
long as no action is specified:

~~~~~~~~~~~~~{.ini}
?author? = app\src\controller\AuthorController
~~~~~~~~~~~~~
*/