model.doxy

/*!
\page model Model
<div class="has-toc"></div>
 
# Model # {#model_main}
 
wCMF applications are based on a model. The model defines the key aspects of the
application on a higher abstraction level than code does. You can think of it as
a condensed description of the application.
 
A template based code generator transforms the model into source code that will
run inside the wCMF framework. Where necessary, the code can then be enhanced
manually inside pre-defined regions. Further generation runs will protect these
manual additions.
 
We believe that this approach helps to develop a clear concept of the application
and improves code quality and maintainability dramatically.
 
## Modeling ## {#model_create}
 
Technically the model is an [UML](http://en.wikipedia.org/wiki/Unified_Modeling_Language)
model that uses the _Chronos_ [profile](http://en.wikipedia.org/wiki/Profile_%28UML%29)
from the [Olympos](http://sourceforge.net/projects/olympos/) project. It is stored
in an [Eclipse MDT/UML2](http://wiki.eclipse.org/MDT-UML2) compatible XML file
(e.g. `model.uml`). This file can be directly edited using
[Eclipse Papyrus](http://www.eclipse.org/papyrus/) or any other [compatible UML
modeling tool](http://wiki.eclipse.org/MDT-UML2-Tool-Compatibility). Alternatively
you can use the [Chronos Web Modeler](http://sourceforge.net/projects/olympos/)
that allows browser based collaborative modeling. wCMF uses a minimized version
of the code generator from the Olympos project with wCMF specific templates.
 
The following diagram shows the workflow of the generator.
 
\image html generator.png "Generator workflow"
 
### Chronos profile ### {#model_profile}
 
_Profiles_ are used to extend UML for different domains. They consist of __stereotypes__
and __tags__ that are applied to model elements to express domain specific
features. The following sections describe the stereotypes and tags of the _Chronos_
profile that are used to define various aspects of a wCMF application. The complete
[Chronos profile](https://raw.githubusercontent.com/iherwig/wcmf-default-app/master/model/chronos.profile.uml)
is available on GitHub.
 
You will notice that only a small part of UML is used to define the application
and not all aspects of the application are defined in the model. Especially the
actual behavior of controllers and domain classes is omitted, since we believe
that this is more efficiently expressed in code. For simplicity and compatibility
reasons all aspects can be modeled in __class diagrams__ using __classes__,
__attributes__ and __associations__.
 
\note UML elements and concepts that are not mentioned in the following sections
are most likely not supported by the generator and will be ignored.
 
### Domain classes ### {#model_classes}
 
The following __stereotypes__ are used to model persistent domain classes and their relations.
 
| Name | UML meta class | Description | Example
|------|----------------|-------------|--------
| _ChiNode_ | Class | Persistent domain class, must inherit from \link wcmf::lib::model::Node `Node`\endlink | _Article_
| _ChiValue_ | Attribute | Persistent attribute in a _ChiNode_ | _headline_ of Article
| _ChiValueRef_ | Attribute | ReadOnly-reference to an attribute of another _ChiNode_ | _author_name_ in Article references _name_ in Author
| _ChiManyToMany_ | Class | Connection class in a many to many relation between _ChiNode_ classes, must inherit from \link wcmf::lib::model::Node `Node`\endlink | One _Author_ writes nultiple _Articles_ and one _Article_ has multiple _Authors_
| _ChiAssociation_ | Association | Optional, e.g. used to define a foreign key name in a relation between _ChiNode_ instances | _author_id_ in Article as foreign key to Author table
 
#### ChiNode / ChiManyToMany #### {#model_chinode}
 
The following __tags__ are defined on the _ChiNode_ / _ChiManyToMany_ stereotypes.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _initparams_ | Name of the configuration section, which defines initialization parameters for the \link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink instance | _database_ | _database_
| _display_value_ | Attributes to display in a list view: A single attribute name or comma separated list of attribute names | _name,date_ | |
| _orderby_ | Definition of default sorting: _none_ (no order), _sortkey_ (generates a _sortkey_ column, that is used for explicit sorting) or the name of any attribute optionally followed by _ASC_ or _DESC_ | _name ASC_ | _none_
| _is_searchable_ | Boolean, indicating whether this type should be included in the default search | _true_ | _true_
| _is_soap_ | Boolean, indicating whether this type should be exposed to the SOAP interface | _true_ | _true_
| _table_name_ | The name of the database table in which instances will be stored | _Author_ | Class name
| _pk_name_ | The name of the primary key column: A single value or comma separated list of values (the generator will add this automatically, if there is no appropriate attribute) | _fk_user_id,fk_role_id_ | _id_
| _child_order_ | The order of the associated relations: A comma separated list of role names | _Author,Publisher,Image,Textblock,Attachment_ in Article type | |
| _parent_order_ | _not used_ | | |
 
\note Some of these tags are accessible in the application through the
\link wcmf::lib::persistence::PersistentObject::getProperty `PersistentObject::getProperty`\endlink
method.
 
#### ChiValue #### {#model_chivalue}
 
The following __tags__ are defined on the _ChiValue_ stereotype.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _app_data_type_ | Application specific attribute tags: A single value or comma separated list of values (see \ref pers_values) | _TAG_A,TAG_B_ | _DATATYPE_ATTRIBUTE_
| _db_data_type_ | The attribute's database type | _TEXT_ | _VARCHAR(255)_ |
| _is_editable_ | Boolean, indicating whether this attribute is editable | _true_ | _true_
| _input_type_ | Name of the attribute's input control as listed in the _InputTypes_ configuration section and additional configuration encoded as JSON string | _filebrowser_ or _ckeditor:{"toolbarSet":"full"}_ | _text_
| _display_type_ | Name of the attribute's display type as listed in the _DisplayTypes_ configuration section | _image_ | _text_
| _restrictions_match_ | Name of the attribute's validation type or comma separated list of validation types as listed in the _Validator_ configuration section (see \ref pers_validation) and additional configuration encoded as JSON string | _date,required_ or _regexp:{"pattern":"^[0-9]*$"}_ or _image:{"height":[300,0]}_ | |
| _restrictions_not_match_ | _not used_ | | |
| _restrictions_description_ | Validation description used in case of a validation error | _The value must be an integer or empty_ | |
| _column_name_ | The name of the database column in which the attribute will be stored | _name_ | Attribute name
 
\note Some of these tags are accessible in the application through the
\link wcmf::lib::persistence::PersistentObject::getValueProperty `PersistentObject::getValueProperty`\endlink
method.
 
#### ChiValueRef #### {#model_chivalueref}
 
The following __tags__ are defined on the _ChiValueRef_ stereotype.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _reference_type_ |  Type, that owns the referenced attribute | _Author_ | |
| _reference_value_ | Name of the references attribute | _name_ | |
 
#### Transient properties #### {#model_transient}
 
All class properties without a _ChiValue_ or _ChiValueRef_ stereotype are considered
to be <strong>transient</strong>/<strong>computed</strong> properties.
 
#### ChiAssociation #### {#model_association}
 
The following __tags__ are defined on the _ChiAssociation_ stereotype.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _fk_name_ | Name of the foreign key attribute (the generator will add this automatically, if there is no appropriate attribute) | _author_id_ | _fk_\_type\_ _id_ |
 
#### Example class diagram #### {#model_class_example}
 
A simple data model is shown in the diagram below. Each of the domain classes
_Author_, _Article_ and _Image_ is modeled with _ChiNode_ stereotype, their
attributes with _ChiValue_ stereotype. The only exception is the _author_name_ attribute,
which is a reference to the _name_ attribute of _Author_ and therefore uses the
stereotype _ChiValueRef_. As the relations between the classes show, one _Author_
can own several _Articles_ and each _Article_ in turn can contain several _Images_.
 
All \link wcmf::lib::persistence::PersistenceMapper `PersistenceMapper`\endlink instances
are initialized using the parameters defined in the _database_ configuration section.
 
In list views _Author_ instances are sorted by _name_ while _Article_ and _Image_
instances get an attribute _sortkey_ which is used to define an explicit order.
 
\image html model.png "Example class diagram"
 
#### Associations #### {#model_associations}
 
Relations between domain classes - e.g. parent-child relations - are modeled as
associations. Three different __types of associations__ are supported: _compositions_,
_aggregations_ and _one-directional associations_ as shown in the following
diagram.
 
\image html associations.png "Association types"
 
It is important to understand how wCMF recognizes __parents and children__ in an
association. In case of compositions and aggregations the parent is always
the class, that is connected with the diamond end of the association. Other
associations are treated as parent-child relation, if they are only navigable
in one direction, which is then defined as the child to parent direction.
 
The association types differ in the treatment of children in case of __deletion__
of the parent. In aggregations and normal associations children are not deleted,
while composite children are deleted on parent deletion. On the other hand the
\ref app "default application" allows __creation__ of child instances in a
composition, while the other two types only allow adding existing instances.
 
The following table summarizes the behavior of the different association types
regarding the operations allowed on child instances:
 
| Association type | Delete children | Create children | Associate children
|------------------|-----------------|-----------------|-------------------
| Composition      | Yes             | Yes             | No
| Aggregation      | No              | Yes             | Yes
| Association      | No              | No              | Yes
 
##### Multiplicity #####
 
The multiplicity at the association ends limits the amount of instances that
are allowed at that relation end. In a typical parent-child relation the parent
end has a value of `1` and the child end has a value of `0..*` meaning that a
child instance is connected to exactly one parent instance, while any number
of child instances can be connected to the parent instance (including zero).
This kind of relation is called __one-to-many relation__ and is easy to realize
in a database by using a _foreign key_ column.
 
__Many-to-many relations__ on the other hand allow an arbitrary number of
instances at both ends and are typically realized in an database using a
_junction table_. The Chronos profile allows for this by providing the `ChiManyToMany`
stereotype. The following diagram shows how to model a many-to-many relation:
 
\image html many-to-many.png "Many-to-many relation"
 
Using compositions ensures that many-to-many instances are deleted correctly,
when the parent instances are deleted.
 
##### Navigability #####
 
Another aspect of associations is the use of __arrow ends__ that define the
navigability. If an arrow end is omitted on one end, instances at that end
are not accessible from the other end. Regarding the database schema all three
association types will result in the creation of a foreign key column in the
child table that points to the parent table.
 
##### Role names #####
 
Each end of an association can have a _role name_ assigned. It describes how the
element at that end participates in the relation. Generally the role name
defaults to the element's name, but there are two cases where it is necessary to
assign a dedicated name:
 
- _Multiple associations_
- _Self associations_
 
Sometimes __multiple associations__ have to be defined between two domain classes.
For example if there are `Person` and `Task` domain classes and tasks should be
associated with persons. If each task should have an owner and a creator, there
will be two aggregations between the two domain classes. To allow wCMF to know
which role a person has in relation to a given task, role names have to be
assigned to the association ends.
 
The following diagram illustrates the given example:
 
\image html multiple-associations.png "Role names in multiple associations"
 
To build a hierarchy where one item contains items of the same type, an
association from the domain class to itself is required. An example would be a file
system with nested directories. In this case, role names are required at each end
of this __self association__.
 
The following diagram illustrates the given example:
 
\image html self-associations.png "Role names in self associations"
 
#### Inheritance #### {#model_inheritance}
 
If different domain classes should have the same attributes, a common base class
can make these available to inheriting classes. An example would be an `EntityBase` type,
which defines meta information like creation date and last modification date for
all domain classes. The diagram below illustrates the concept.
 
\image html inheritance.png "Inheritance"
 
Inheritance will cause the generator to create new relations in the following cases:
 
<div class="image-table">
| Parent relations | Child relations
|------------------|----------------
\image html inherited-relation1.png "Subclass B becomes parent of A" | \image html inherited-relation3.png "Subclass B becomes child of A"
\image html inherited-relation2.png "Parent class of B becomes parent of A" | \image html inherited-relation4.png "Child class of B becomes child of A"
</div>
 
### Application flow ### {#model_flow}
 
Since a wCMF application is based on the Model-View-Controller pattern, application
flow is defined in terms of _controllers_ and _views_. Controller execution is triggered
by _actions_ which are initiated by the application user.
 
The following __stereotypes__ are used to model user interaction.
 
| Name | UML meta class | Description | Example
|------|----------------|-------------|--------
| _ChiController_ | Class | Controller class, must inherit from the \link wcmf::lib::presentation::Controller `Controller`\endlink | _LoginController_
| _ChiView_ | Class | View assigned to a _ChiController_ | _login_
| _ChiActionKey_ | Association | Associates two _ChiController_ instances (to define a control flow) or a _ChiView_ with a _ChiController_ (to define a view attachment), must be _one directional_ | |
 
\note _ChiActionKey_ realizes the concept of _action keys_ (see \ref arch_actionkey).
Multiple action keys can be defined between controllers or controllers and views
each one used in a different context and/or for a different action.
 
#### ChiController #### {#model_chicontroller}
 
No __tags__ are defined on the _ChiController_ stereotype.
 
#### ChiView #### {#model_chiview}
 
No __tags__ are defined on the _ChiView_ stereotype.
 
#### ChiActionKey #### {#model_chiactionkey}
 
The following __tags__ are defined on the _ChiActionKey_ stereotype.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _action_ |  The action, which is triggered by this association. If empty, any action is valid | _save_ | |
| _context_ | The context, in which this association is valid. If empty, any context is valid | _author_ | |
| _config_ | The configuration, in which this association is defined | _config.ini_ | _config.ini_ |
 
#### Example application flow #### {#model_example_flow}
 
An example for a simple interaction model is given in the diagram below. The
controllers are modeled with the stereotype _ChiController_, the associations with
_ChiActionKey_ stereotype. Each association's tagged values are displayed in an
attached note. Since the association between _AuthorController_ and _author_ view
does not define the tagged values _action_ and _context_, _AuthorController_
displays this view for every action and context. The same applies to _ArticleController_
and the _article_ view. _SaveController_ does not display a view, it only stores
the data passed to it and returns to the next controller.
 
For associations, which link controllers, at least the tagged value _action_ is set.
Since obviously all _save_ actions result in the execution of _SaveController_,
no context is necessary. The context is helpful, when we want to solve the
ambiguousness of the action _ok_ upon termination of _SaveController_.
We define, that the context is _author_ when editing the author and _article_
when editing articles. By this the application always knows to which controller it
should return to after executing _SaveController_.
 
\image html flow.png "Example application flow"
 
\note If the _controller_ value of the action key should be empty, meaning that the
action can be triggered from _any_ controller, the source of the _ChiActionKey_
association must be the \link wcmf::lib::presentation::Controller `Controller`\endlink
base class.
 
#### Controller methods #### {#model_controller_methods}
 
By default the framework calls the method _doExecute_ on the current controller
instance for any _context_ and _action_ value. For this reason an empty implementation
of this method will be added by the generator.
 
To distinguish different actions or contexts it is also possible to model several
operations inside the controller class. To connect an action key to a controller
method, the action key's end that points to the controller must be named like
the method. The following diagram illustrates the concept:
 
\image html controller-methods.png "Controller methods"
 
#### Request parameters #### {#model_controller_parameters}
 
Parameters can be added to controller methods. The generator will create code
that extracts and validates the input parameters from the requests or sets
default values if they are absent. Output parameters will be added to the response.
 
#### Routes #### {#model_controller_routes}
 
If an action should be available in the public API of the application, it must be
mapped to a request uri in the `Routes` configuration section (see \ref pres_routingext).
 
This can be easily achieved by setting a request uri pattern on the action key's
source end. The following diagram illustrates the concept:
 
\image html controller-routes.png "Controller routes"
 
### Configuration ### {#model_config}
 
The following __stereotypes__ are used to model the application configuration.
 
| Name | UML meta class | Description | Example
|------|----------------|-------------|--------
| _ChiSystem_ | Class | A configuration section, class members and their default values become key-value pairs inside the section | _Database_
 
#### ChiSystem #### {#model_chisystem}
 
The following __tags__ are defined on the _ChiSystem_ stereotype.
 
| Tag | Description | Example | Default value
|-----|-------------|---------|--------------
| _platform_ |  The platform to which the configuration settings apply | _wcmf_ | |
| _config_ | The configuration, in which the settings are defined | _config.ini_ | _config.ini_ |
 
#### Example configuration #### {#model_example_config}
 
The following diagram shows the configuration of a database connection. The
connection parameters can be accessed later using the
\link wcmf::lib::config::Configuration::getSection `Configuration::getSection`\endlink
method and passing _database_ as `section` paramter.
 
\image html config.png "Example configuration"
 
### Default model ### {#model_default}
 
The \ref app "default application" includes a demo UML model located in
`model/model.uml`. It is a good starting point for custom applications. For those who
want to start from scratch there are also base models in _model/base/cwm/_ (for
[Chronos Web Modeler](http://sourceforge.net/projects/olympos/)) and
_model/base/papyrus/_ (for [Eclipse Papyrus](http://www.eclipse.org/papyrus/)).
 
The default model has the following package structure:
 
- _model_
  - _wcmf test_
    - _root_
      - _wcmf_ Framework packages with useful (base-)classes
        - _Primitive types_
        - _configuration_ Base configuration
          - _config.ini_
            - `«ChiSystem» Config`
            - ...
          - ...
        - _application_
          - _controller_ Existing controllers
            - `«ChiController» AssociateController`
            - ...
        - _lib_
          - _presentation_
            - `«ChiController» Controller` Base class for all controller classes
          - _model_
            - `«ChiNode» Node` Base class for all domain classes
          - _security_
            - _principal_
              - _impl_
                - `AbstractUser` Base class for custom user class
                - `AbstractRole` Base class for custom role class
      - _app_ Application specific packages
        - __configuration__ Application specific configuration
          - _backend.ini_
          - _server.ini_ Deployment specific configuration
        - _src_
          - __model__ Domain class package
            - _wcmf_ Default framework classes
              - `«ChiNode» DBSequence`
              - ...
            - `«ChiNode» EntityBase` Base class for domain classes with audit info
            - ...
          - __controller__ Controller package
            - `«ChiController» RootController` Main controller of \ref app "default application"
          - __views__ Views package
            - `«ChiView» cms` Main view of \ref app "default application"
 
Application specific model elements will mostly reside in the __emphasized__ packages.
 
## Generator ## {#model_generator}
 
wCMF uses the code generator from the [Olympos](http://sourceforge.net/projects/olympos/)
project which is originally based on _openArchitectureWare_. The generator is
a JAVA application that executes user defined workflows. Workflows are organized in
cartridges one of which is the wCMF cartridge. Cartridges are written in the
_Xtent/Xpand_ language.
 
If you are using [Composer](https://getcomposer.org/), the generator will be installed
as a dependency in the directory _vendor/olympos/chronos-generator_. It is also
available at [SourceForge](https://sourceforge.net/projects/olympos/files/ChronosGenerator-wCMF/).
 
### Configuration ### {#generator_config}
 
The configuration of the generator is stored as key-value pairs in a file called
`workflow.properties` in the _model_ directory. It contains the following __variables__:
 
| Variable | Description | Default value
|----------|-------------|--------------
| _profilename_ | Name of the used UML profile | _Chronos_ |
| _profileUmlFile_ | Path to the profile file | <em>${basePath}/metamodel/chronos.profile.uml</em> |
| _modelUmlFile_ | Model file to generate code from | _model.uml_ |
| _transformedModelUmlFile_ | Location for the model transformed into the generator's internal format (used for debug purposes) | _model-transformed_ |
| _rootPackage_ | Model package containing _libraryPackage_ and _applicationPackage_. It's name will be stripped from paths to classes | _wcmf test::root_ |
| _libraryPackage_ | Model package, in which the wCMF framework is defined. From this package no files will be generated | _wcmf_ |
| _applicationPackage_ | Model package, in which the application is modeled | _app_ |
| _doCheck_ | Indicates whether the generator should run checks on the model | _true_ |
| _preCheckFile_ | Check file, that should be used before the transformation into the internal model format | _cartridge::Wcmf::checks::pre_ |
| _postCheckFile_ | Check file, that should be used after the transformation into the internal model format | _cartridge::Wcmf::checks::post_ |
| _requiredControllerSuperclass_ | Controller base class, from which all controllers must inherit, used in the checks | _model::${rootPackage}::${libraryPackage}::lib::presentation::Controller_ |
| _requiredNodeSuperclass_ | Domain base class, from which all domain classes must inherit, used in the checks | _model::${rootPackage}::${libraryPackage}::lib::model::Node_ |
| _doBackup_ | Indicates whether the generator should do a backup of the application, before generating any files | _false_ |
| _expand_ | Template definition to start the generation from | _cartridge::Wcmf::templates::Root::root_ |
| _outputEncoding_ | Encoding of the generated files | _UTF-8_ |
| _configFileDefault_ | Name of the default configuration file, general properties like type mapping are declared here | _config.ini_ |
| _projectname_ | Name of the application | _wcmf testapp_ |
| _targetDir_ | Directory, in which the application is created | _targetDir_ |
| _prExcludes_ | File patterns to be excluded when searching for protected regions | <em>*.svn-base, .git, vendor</em> |
| _printGenerateDate_ | Indicates whether the generation date should be printed in generated file headers | _false_ |
| _headerText_ | Text to be prepended to generated files | |
 
The variables `${basePath}` (generator location) and `${targetDir}` (generated code
location) must be provided as __command line__ arguments when running the generator
(see \ref generator_run).
 
### Running ### {#generator_run}
 
The generator is started using the __command__
 
<div class="shell">
```
$ java -Djava.library.path=libPath -jar ChronosGenerator.jar workflowFile -basePath=basePath -propertyFile=propertyFile -targetDir=targetDir
```
</div>
 
The __parameters__ are explained in the following table.
 
| Parameter | Description | Default value
|-----------|-------------|--------------
| _libPath_ | Path to the generator libraries | <em>../vendor/olympos/chronos-generator/lib</em> |
| _workflowFile_ | Workflow definition file | <em>../vendor/olympos/chronos-generator/cartridge/Wcmf/workflow/wcmf.oaw</em> |
| _basePath_ | Path to the generator installation | <em>../vendor/olympos/chronos-generator/</em> |
| _propertyFile_ | Workflow configuration file | <em>../model/workflow.properties</em> |
| _targetDir_ | Path to the generated files | <em>../</em> |
 
The __default values__ apply, if the generator is run from the _build_ directory of
the \ref app "default application".
 
Since the code generator is integrated into the __ant deployment script__ of the
application, it's also sufficient to run the following command in the _build_
directory:
 
<pre>
ant generate
</pre>
 
### Artefacts ### {#generator_artefacts}
 
The generator creates the following files:
 
#### Configuration #### {#generator_artefacts_config}
 
- __SQL scripts__ are generated in the _install_ directory. They contain the
  table definitions for [MySQL](http://www.mysql.com) databases (`install/tables_mysql.sql`)
  and [SQLite](https://sqlite.org) databases (`install/tables_sqlite.sql`). For each domain
  class one table is created, inherited attributes are stored in each table
  ([Concrete Table Inheritance] (http://martinfowler.com/eaaCatalog/concreteTableInheritance.html)).
 
- __Configuration files__ in the [INI file](http://en.wikipedia.org/wiki/INI_file)
  format are generated in the _app/config_ directory. Configuration files are
  implicitly defined in the model by the `ChiActionKey.config` and `ChiSystem.config`
  tags. For each name mentioned in these tags, one configuration file will be
  created, containing all definitions related to it. Furthermore, the default
  configuration file (_config.ini_ per default) contains the domain class
  mapping definitions.
 
#### PHP Code #### {#generator_artefacts_php}
 
- __Mapper classes__ are generated in directories corresponding to the
  model packages (_app/src/model_, if the default model packages are used). For
  each `ChiNode`/`ChiManyToMany` class one subclass of
  \link wcmf::lib::model::mapper::NodeUnifiedRDBMapper `NodeUnifiedRDBMapper`\endlink
  is created (e.g. `AuthorRDBMapper`).
 
- __Domain classes__ are generated in the same directories as the mapper classes.
  For each `ChiNode`/`ChiManyToMany` class two classes are created, one base class
  that contains all generated code (e.g. `AuthorBase`) and one empty subclass,
  that is used to add custom code (e.g. `Author`). The base class inherits from
  \link wcmf::lib::model::Node `Node`\endlink or one of it's subclasses. Getter
  methods are generated for transient/computed properties.
 
- __Controller classes__ are generated in directories corresponding to the
  model packages (_app/src/controller_, if the default model packages are used). For
  each `ChiController` class two classes are created, one base class that contains
  all generated code and one subclass that contains the methods to be implemented.
  The base class inherits from
  \link wcmf::lib::presentation::Controller `Controller`\endlink or one of it's
  subclasses.
 
- The __SOAP interface__ is generated in the file _app/public/soap-interface.php_.
  \link wcmf::application::controller::SOAPController `SOAPController`\endlink
  uses this file to configure the \link wcmf::lib::service::SoapServer `SoapServer`\endlink.
 
#### Template Code #### {#generator_artefacts_tpl}
 
- __View templates__ are generated in directories corresponding to the
  model packages (_app/src/views_, if the default model packages are used). For
  each `ChiView` class one empty template file will be created.
 
#### JavaScript Code #### {#generator_artefacts_js}
 
- __Domain classes__ are generated in a subdirectory of _public/js_
  (_app/public/js/app/src/model_, if the default model packages are used).
  For each `ChiNode`/`ChiManyToMany` one subclass of `Entity` is created.
 
- An [AMD](http://en.wikipedia.org/wiki/Asynchronous_module_definition) file
  referencing all domain classes is created in _public/js/model_
  (_app/public/js/model/_TypeList.js_, if the default model packages are used).
 
#### Protected regions #### {#generator_pr}
 
The generator creates functional code, but of course __custom code__ must be added
to implement domain specific functionality. For this reason
the generator adds sections that are enclosed in `PROTECTED REGION` tags,
between which the user is supposed to place custom code. When re-generating
the code later (e.g. because of model changes), this custom code will be preserved.
 
An example of a class file containing protected regions is shown below.
 
<div class="php">
```
<?php
/**
 * This file was generated by ChronosGenerator  from model.uml.
 * Manual modifications should be placed inside the protected regions.
 */
namespace app\src\model;
 
use app\src\model\AuthorBase;
// PROTECTED REGION ID(app/src/model/Author.php/Import) ENABLED START
// PROTECTED REGION END
 
/**
 * Author description:
 *
 * @author
 * @version 1.0
 */
class Author extends AuthorBase {
// PROTECTED REGION ID(app/src/model/Author.php/Body) ENABLED START
// PROTECTED REGION END
}
?>
```
</div>
*/