Added documentation for readthedocs

Issue-ID: POLICY-1161
Change-Id: I8a3ac2b8fbfccacd04cfd5cb3bc649d9674ec59b
Signed-off-by: mmis <michael.morris@ericsson.com>

1 files changed, 1471 insertions, 0 deletions

diff --git a/docs/APEX-Developer-Guide.rst b/docs/APEX-Developer-Guide.rst
new file mode 100644
index 000000000..d5f16d56c
--- /dev/null
+++ b/docs/APEX-Developer-Guide.rst
@@ -0,0 +1,1471 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+APEX Developer Guide
+********************
+
+.. contents::
+    :depth: 3
+
+Build APEX from Source
+^^^^^^^^^^^^^^^^^^^^^^
+
+Introduction to building APEX
+-----------------------------
+
+            .. container:: paragraph
+
+               APEX is written 100% in Java and uses `Apache
+               Maven <https://maven.apache.org/>`__ as the build system.
+               The requirements for building APEX are:
+
+            .. container:: ulist
+
+               -  An installed Java development kit for Java version 8
+                  or higher
+
+                  .. container:: ulist
+
+                     -  To install a Java SDK please follow these
+                        guidelines `Oracle Java 8
+                        SDK <https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html>`__.
+
+               -  Maven 3
+
+                  .. container:: ulist
+
+                     -  To get Maven 3 running please follow the
+                        guidelines for
+                        `Download <https://maven.apache.org/download.cgi>`__
+                        and
+                        `Install <https://maven.apache.org/install.html>`__,
+                        and `Run <https://maven.apache.org/run.html>`__
+                        Maven
+
+               -  A clone of the APEX source repositories
+
+            .. container:: paragraph
+
+               To get a clone of the APEX source repositories, please
+               see the APEX Installation Guide or the APEX User manual.
+
+            .. container:: paragraph
+
+               One all requirements are in place, APEX can be build.
+               There are several different artifacts one can create
+               building APEX, most of them defined in their own
+               *profile*. APEX can also be build in a standard way with
+               standard tests (``mvn clean install``) or without
+               standard tests (``mvn clean install -DskipTests``).
+
+            .. container:: paragraph
+
+               The examples in this document assume that the APEX source
+               repositories are cloned to:
+
+            .. container:: ulist
+
+               -  Unix, Cygwin: ``/usr/local/src/apex``
+
+               -  Windows: ``C:\dev\apex``
+
+               -  Cygwin: ``/cygdrive/c/dev/apex``
+
+            .. important::
+			   A Build requires ONAP Nexus
+			   APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
+			   settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
+
+            .. important:: 
+			
+			   A Build needs Space
+			   Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full
+			   distribution and 1-2 GB for the downloaded dependencies
+
+            .. important:: 
+			   A Build requires Internet (for first build to download all dependencies and plugins)
+			   During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven 
+			   repository. The first standard build (and any first specific build) requires Internet access to download those
+			   dependencies.
+
+            .. important:: 
+               Building RPM distributions
+               RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` 
+               run ``sudo apt-get install rpm``, then build APEX. 
+
+Standard Build
+--------------
+
+            .. container:: paragraph
+
+               Use Maven to for a standard build without any tests.
+
+            +-----------------------------------+------------------------------------+
+            | Unix, Cygwin                      | Windows                            |
+            +===================================+====================================+
+            | ::                                | ::                                 |
+            |                                   |                                    |
+            |    >c:                            |    # cd /usr/local/src/apex        |
+            |    >cd \dev\apex                  |    # mvn clean install -DskipTests |
+            |    >mvn clean install -DskipTests |                                    |
+            |                                   |                                    |
+            +-----------------------------------+------------------------------------+
+
+.. container:: paragraph
+
+   The build takes about 6 minutes on a standard development laptop. It
+   should run through without errors, but with a lot of messages from
+   the build process.
+
+.. container:: paragraph
+
+   When Maven is finished with the build, the final screen should look
+   similar to this (omitting some ``success`` lines):
+
+.. container:: listingblock
+
+   .. code:: bash
+     :number-lines:
+
+     [INFO] tools .............................................. SUCCESS [  0.248 s]
+     [INFO] tools-common ....................................... SUCCESS [  0.784 s]
+     [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
+     [INFO] model-generator .................................... SUCCESS [  0.644 s]
+     [INFO] packages ........................................... SUCCESS [  0.336 s]
+     [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
+     [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
+     [INFO] ------------------------------------------------------------------------
+     [INFO] BUILD SUCCESS
+     [INFO] ------------------------------------------------------------------------
+     [INFO] Total time: 03:43 min
+     [INFO] Finished at: 2018-09-03T11:56:01+01:00
+     [INFO] ------------------------------------------------------------------------
+
+.. container:: paragraph
+
+   The build will have created all artifacts required for an APEX
+   installation. The following example show how to change to the target
+   directory and how it should look like.
+
++-----------------------------------------------------------------------------------------------------------------------------+
+| Unix, Cygwin                                                                                                                |
++=============================================================================================================================+
+| .. container::                                                                                                              |
+|                                                                                                                             |
+|    .. container:: listingblock                                                                                              |
+|                                                                                                                             |
+|          .. code:: bash                                                                                                     |
+|            :number-lines:                                                                                                   |
+|                                                                                                                             |
+|            # cd packages/apex-pdp-package-full/target                                                                       |
+|            # ls -l                                                                                                          |
+|            -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*      |
+|            -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*              |
+|            -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*              |
+|            -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz*   |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                           |
+|            -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                  |
+|            -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                                |
+|            -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                                 |
+|            -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                                 |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                               |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                       |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                   |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                              |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                     |
+|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                        |
++-----------------------------------------------------------------------------------------------------------------------------+
+
++-----------------------------------------------------------------------------------------------------------------------------+
+| Windows                                                                                                                     |
++=============================================================================================================================+
+| .. container::                                                                                                              |
+|                                                                                                                             |
+|    .. container:: listingblock                                                                                              |
+|                                                                                                                             |
+|          .. code:: bash                                                                                                     |
+|            :number-lines:                                                                                                   |
+|                                                                                                                             |
+|            >cd packages\apex-pdp-package-full\target                                                                        |
+|            >dir                                                                                                             |
+|                                                                                                                             |
+|            03/09/2018  11:55    <DIR>          .                                                                            |
+|            03/09/2018  11:55    <DIR>          ..                                                                           |
+|            03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz                          |
+|            03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb                                     |
+|            03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar                                     |
+|            03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes                             |
+|            03/09/2018  11:54    <DIR>          archive-tmp                                                                  |
+|            03/09/2018  11:54                89 checkstyle-cachefile                                                         |
+|            03/09/2018  11:54            10,621 checkstyle-checker.xml                                                       |
+|            03/09/2018  11:54               584 checkstyle-header.txt                                                        |
+|            03/09/2018  11:54                86 checkstyle-result.xml                                                        |
+|            03/09/2018  11:54    <DIR>          classes                                                                      |
+|            03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                                              |
+|            03/09/2018  11:54    <DIR>          etc                                                                          |
+|            03/09/2018  11:54    <DIR>          examples                                                                     |
+|            03/09/2018  11:55    <DIR>          install_hierarchy                                                            |
+|            03/09/2018  11:54    <DIR>          maven-archiver                                                               |
+|                           8 File(s)    292,652,686 bytes                                                                    |
+|                           9 Dir(s)  14,138,720,256 bytes free                                                               |
++-----------------------------------------------------------------------------------------------------------------------------+
+
+
+Checkstyle with Maven
+---------------------
+
+   .. container:: paragraph
+
+      The codestyle for all APEX java projects can be checked
+      automatically. The checks include empty or non-existing Javadocs.
+      Any checkstyle run should complete without any errors, some
+      warnings are acceptable.
+
+   .. container:: paragraph
+
+      To run checkstyle on an APEX Maven project use:
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: bash
+
+            mvn checkstyle:check
+
+   .. container:: paragraph
+
+      To run checkstyle on all modules use:
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: bash 
+
+            mvn checkstyle:checkstyle -DapexAll
+
+Build with standard Tests
+-------------------------
+
+   .. container:: paragraph
+
+      Use Maven to for a standard build with standard tests.
+
+   .. important::  
+      Some tests have specific timing Requirements
+	  Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
+	  machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
+	  on your build machine and restart the build.
+
+   +-----------------------------------+-----------------------------------+
+   | Unix, Cygwin                      | Windows                           |
+   +===================================+===================================+
+   | .. container::                    | .. container::                    |
+   |                                   |                                   |
+   |    .. container:: content         |    .. container:: content         |
+   |                                   |                                   |
+   |       .. code:: bash              |       .. code:: bash              |
+   |         :number-lines:            |         :number-lines:            |
+   |                                   |                                   |
+   |         >c:                       |         # cd /usr/local/src/apex  |
+   |         >cd \dev\apex             |         # mvn clean install       |
+   |         >mvn clean install        |                                   |
+   +-----------------------------------+-----------------------------------+
+
+
+.. container:: paragraph
+
+   The build takes about 10 minutes with tests on a standard development
+   laptop. It should run through without errors, but with a lot of
+   messages from the build process. If build with tests (i.e. without
+   ``-DskipTests``), there will be error messages and stack trace prints
+   from some tests. This is normal, as long as the build finishes
+   successful.
+
+Build with all Tests
+--------------------
+
+   .. container:: paragraph
+
+      Use Maven to for a standard build with *all* tests.
+
+   .. important::  
+      Some tests have specific timing Requirements.
+	  Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
+	  machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
+	  on your build machine and restart the build.
+
+   .. important::  
+      Might require specific software.
+	  When running all tests, some modules require specific software installed on the build machine. For instance,
+	  testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan
+	  installed on the build machine.
+
+   +----------------------------------------------+----------------------------------------------+
+   | Unix, Cygwin                                 | Windows                                      |
+   +==============================================+==============================================+
+   | .. container::                               | .. container::                               |
+   |                                              |                                              |
+   |    .. container:: content                    |    .. container:: content                    |
+   |                                              |                                              |
+   |       .. code:: bash                         |       .. code:: bash                         |
+   |         :number-lines:                       |         :number-lines:                       |
+   |                                              |                                              |
+   |         >c:                                  |         # cd /usr/local/src/apex             |
+   |         >cd \dev\apex                        |         # mvn clean install -DallTests       |
+   |         >mvn clean install -DallTests        |                                              |
+   +----------------------------------------------+----------------------------------------------+
+
+Build with all Components
+-------------------------
+
+   .. container:: paragraph
+
+      A standard APEX build will not build all components. Some parts
+      are for specific deployments, only. Use Maven to for a standard
+      build with *all* components.
+
+   .. important:: 
+      Might require specific software.
+	  When building all components, some modules require specific software installed on the build machine.
+
+   +----------------------------------------------+----------------------------------------------+
+   | Unix, Cygwin                                 | Windows                                      |
+   +==============================================+==============================================+
+   | .. container::                               | .. container::                               |
+   |                                              |                                              |
+   |    .. container:: content                    |    .. container:: content                    |
+   |                                              |                                              |
+   |       .. code:: bash                         |       .. code:: bash                         |
+   |         :number-lines:                       |         :number-lines:                       |
+   |                                              |                                              |
+   |         >c:                                  |         # cd /usr/local/src/apex             |
+   |         >cd \dev\apex                        |         # mvn clean install -DapexAll        |
+   |         >mvn clean install -DapexAll         |                                              |
+   +----------------------------------------------+----------------------------------------------+
+
+
+Build the APEX Documentation
+----------------------------
+
+   .. container:: paragraph
+
+      The APEX Maven build also includes stand-alone documentations,
+      such as the HowTo documents, the Installation Guide, and the User
+      Manual. Use Maven to build the APEX Documentation. The Maven
+      options ``-N`` prevents Maven to go through all APEX modules,
+      which is not necessary for the documentation. The final documents
+      will be in ``target/generated-docs`` (Windows:
+      ``target\generated-docs``). The *HTML* documents are in the
+      ``html/`` folder, the *PDF* documents are in the ``pdf/`` folder.
+      Once the documentation is build, copy the *HTML* and *PDF*
+      documents to a folder of choice
+
+   +-------------------------------------------------------+--------------------------------------------------------+
+   | Unix, Cygwin                                          | Windows                                                |
+   +=======================================================+========================================================+
+   | .. container::                                        | .. container::                                         |
+   |                                                       |                                                        |
+   |    .. container:: content                             |    .. container:: content                              |
+   |                                                       |                                                        |
+   |       .. code:: bash                                  |       .. code:: bash                                   |
+   |         :number-lines:                                |         :number-lines:                                 |
+   |                                                       |                                                        |
+   |         >c:                                           |         # cd /usr/local/src/apex                       |
+   |         >cd \dev\apex                                 |         # mvn clean generate-resources -N -DapexDocs   |
+   |         >mvn clean generate-resources -N -DapexDocs   |                                                        |
+   +-------------------------------------------------------+--------------------------------------------------------+
+
+Build APEX Site
+---------------
+
+   .. container:: paragraph
+
+      The APEX Maven build comes with full support to build a web site
+      using Maven Site. Use Maven to build the APEX Site. Stage the APEX
+      web site. The target folder for the staged site is
+
+   .. container:: ulist
+
+      -  Unix: ``/usr/local/src/apex/target/ad-site``
+
+      -  Windows: ``C:\dev\apex\target\ad-site``
+
+      -  Cygwin: ``/cygdrive/c/dev/apex/target/ad-site``
+
+   .. container:: paragraph
+
+      Once the web site is staged, copy the full site to a folder of
+      choice or into a web server.
+
+   .. important::  
+      Building a Site takes Time.
+	  Building and staging the APEX web site can take very long. The stand-alone documentation will take about 2 minutes. The
+	  sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine (~10 minutes
+	  without generating source and test-source reports, closer to 30 minutes with all reports).
+
+   .. container:: paragraph
+
+      Start the build deleting the staging directory that might have
+      been created by a previous site build. Then go to the APEX
+      packaging directory.
+
+   +--------------------------------+-----------------------------------+----------------------------------+
+   | Unix                           | Windows                           | Cygwin                           |
+   +================================+===================================+==================================+
+   | .. container::                 | .. container::                    | .. container::                   |
+   |                                |                                   |                                  |
+   |    .. container:: content      |    .. container:: content         |    .. container:: content        |
+   |                                |                                   |                                  |
+   |       .. code:: bash           |       .. code:: bash              |       .. code:: bash             |
+   |         :number-lines:         |         :number-lines:            |         :number-lines:           |
+   |                                |                                   |                                  |
+   |         cd /usr/local/src/apex |         c:                        |         cd /cygdrive/c/dev/apex  |
+   |         rm -fr target/ad-site  |         cd \dev\apex              |         rm -fr target/ad-site    |
+   |                                |         rmdir /s/q target\ad-site |                                  |
+   +--------------------------------+-----------------------------------+----------------------------------+
+
+   .. container:: paragraph
+
+      the workflow for building a complete site then is as follows:
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: bash
+
+            mvn clean -DapexAll (1)
+            mvn install -DskipTests (2)
+            mvn generate-resources -N -DapexDocs (3)
+            mvn initialize site:attach-descriptor site site:stage -DapexSite (4)
+
+   .. container:: olist arabic
+
+      #. First clean all modules to remove any site artifacts, use the
+         *apexXtext* profile to make sure these modules are processed as
+         well
+
+      #. Next run a simple install without tests
+
+      #. Now generate the APEX stand -alone documentation, they are in
+         the local package only so we can use the *-N* switch
+
+      #. Last build the actual sites and stage (copy to the staging
+         directory) with the profile *apexSite* (do not forget the
+         initialize goal, otherwise the staging directory will not be
+         correctly set and sites are staged in every model in a
+         directory called ``docs``).
+
+   .. container:: paragraph
+
+      If you want to build the site for a particular project for
+      testing, the Maven command is simpler. Since only the main project
+      has APEX documentation (stand-alone), you can use Maven as follow.
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: bash
+
+            mvn clean site -DapexSite
+
+   .. container:: paragraph
+
+      If you want to stage the tested site, then use
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: bash
+
+            mvn clean initialize site:attach-descriptor site site:stage -DapexSite
+
+APEX Codestyle
+^^^^^^^^^^^^^^
+
+Introduction: APEX Codestyle
+----------------------------
+
+         .. container:: paragraph
+
+            This page describes how to apply a code style to the APEX
+            Java projects. The provided code templates are guidelines
+            and are provided for references and as examples. We will not
+            engage in "holy war" on style for coding. As long as the
+            style of a particular block of code is understandable,
+            consistent, and readable, please feel free to adapt or
+            modify these guides or use other guides as you see fit.
+
+         .. container:: paragraph
+
+            The JAutoDoc and Checkstyle Eclipse Plugins and tools are
+            useful and remove a lot of the tedium from code
+            documentation. Use them to check your code and please fix
+            any issues they identify with your code.
+
+         .. container:: paragraph
+
+            Since APEX is part of ONAP, the general ONAP rules and
+            guideliness for development do apply. Please see `ONAP
+            Wiki <https://wiki.onap.org/display/DW/Developing+ONAP>`__
+            for details.
+
+Java coding Rules
+-----------------
+
+         .. container:: ulist
+
+            -  APEX is (in large parts) a platform (or middleware), so
+               `Software Design
+               Patterns <https://en.wikipedia.org/wiki/Software_design_pattern>`__
+               are a good thing
+
+            -  The `Solid
+               Principles <https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)>`__
+               apply
+
+            -  Avoid class fields scoped as ``protected``
+
+               .. container:: ulist
+
+                  -  They break a lot of good design rules, e.g. most
+                     SOLID rules
+
+                  -  For a discussion see this `Stackoverflow
+                     Question <https://softwareengineering.stackexchange.com/questions/162643/why-is-clean-code-suggesting-avoiding-protected-variables>`__
+
+            -  If you absolutely need ``protected`` class fields they
+               should be ``final``
+
+            -  Avoid ``default`` scope for class fields and methods
+
+               .. container:: ulist
+
+                  -  For fields: use ``public`` or ``private`` (see also
+                     above)
+
+                  -  For methods: use ``public`` for general use,
+                     ``protected`` for specialization using inheritance
+                     (ideally ``final``), ``private`` for everything
+                     else
+
+            -  Method parameters that are not changed in the method
+               should be marked ``final``
+
+            -  Every package must have a ``package-info.java`` file with
+               an appropriate description, minimum a descriptive one
+               liner
+
+            -  Every class must have
+
+               .. container:: ulist
+
+                  -  The common header (copyright, file, date)
+
+                  -  Javadoc header for the class with description of
+                     the class and author
+
+                  -  Javadoc for *all public\_* fields
+
+                  -  If possible, Javadoc for *private* fields, at least
+                     some documentation for private fields
+
+                  -  Javadoc for *all* methods
+
+            -  All project must build with all tests on Unix, Windows,
+               *and* Cygwin
+
+               .. container:: ulist
+
+                  -  Support all line endings in files, e.g. ``\n`` and
+                     ``\r\n``
+
+                  -  Be aware of potential differences in exception
+                     messages, if testing against a message
+
+                  -  Support all types of paths: Unix with ``/``,
+                     Windows with an optinal drive ``C:\`` and ``\``,
+                     Cygwin with mixed paths
+
+Eclipse Plugin: JAutodoc
+------------------------
+
+         .. container:: paragraph
+
+            This plugin is a helper plugin for writing Javadoc. It will
+            automatically create standard headers on files, create
+            package-info.java files and will put in remarkably good stub
+            Javadoc comments in your code, using class names and method
+            names as hints.
+
+         .. container:: paragraph
+
+            Available from the Eclipse Marketplace. In Eclipse
+            Help→Eclipse Marketplace…​ and type ``JAutodoc``. Select
+            JAutodoc when the search returns and install it.
+
+         .. container:: paragraph
+
+            You must configure JAutoDoc in order to get the most out of
+            it. Ideally JAutoDoc should be configured with templates
+            that cooperate with the inbuilt Eclipse Code Formatter for
+            best results.
+
+Eclipse Plugin: Checkstyle
+--------------------------
+
+         .. container:: paragraph
+
+            This plugin integrates
+            `Checkstyle <http://checkstyle.sourceforge.net/>`__ into
+            Eclipse. It will check your code and flag any checkstyle
+            issues as warnings in the code.
+
+         .. container:: paragraph
+
+            Available from the Eclipse Marketplace. In Eclipse
+            Help→Eclipse Marketplace…​ and type "Checkstyle". Select
+            "Checkstyle Plug-in" when the search returns and install it.
+            Note that "Checkstyle Plug-in" may not be the first result
+            in the list of items returned.
+
+         .. container:: paragraph
+
+            For APEX, the ONAP checkstyle rules do apply. The
+            configuration is part of the ONAP parent. See `ONAP
+            Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
+            for details and updates. All settings for checkstyle are
+            already part of the code (POM files).
+
+Configure Eclipse
+-----------------
+
+         .. container:: ulist
+
+            -  Set the template for Eclipse code clean up
+
+               .. container:: olist arabic
+
+                  #. Eclipse  Window  Preferences  Java  Code Style 
+                     Clean Up → Import…​
+
+                  #. Select your template file
+                     (``ApexCleanUpTemplate.xml``) and apply it
+
+            -  Set the Eclipse code templates
+
+               .. container:: olist arabic
+
+                  #. Eclipse  Window  Preferences  Java  Code Style 
+                     Code Templates → Import…​
+
+                  #. Select your templates file
+                     (``ApexCodeTemplates.xml``) and apply it
+
+                     .. container:: ulist
+
+                        -  Make sure to set your email address in
+                           generated comments by selecting
+                           "Comments→Types" in the "Configure generated
+                           code and comments:" pane, then change the
+                           email address on the @author tag to be your
+                           email address
+
+            -  Set the Eclipse Formatter profile
+
+               .. container:: olist arabic
+
+                  #. Eclipse  Window  Preferences  Java  Code Style 
+                     Formatter → Import…​
+
+                  #. Select your formatter profile file
+                     (``ApexFormatterProfile.xml``) and apply it
+
+         .. container:: paragraph
+
+            The templates mentioned above can be found in
+            ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+Configure JAutodoc (Eclipse)
+----------------------------
+
+         .. container:: paragraph
+
+            Import the settings for JAutodoc:
+
+         .. container:: olist arabic
+
+            #. Eclipse  Window  Preferences  Java  JAutodoc → Import
+               All…​ (at bottom of the JAutodoc preferences window)
+
+            #. Leave all the preferences ticked to import all
+               preferences, browse to the JAutodoc setting file
+               (``ApexJautodocSettings.xml``) and press OK
+
+            #. Set your email address in the package Javadoc template
+
+               .. container:: ulist
+
+                  -  Press Edit Template…​ in the Package Javadoc area
+                     of the JAutodoc preferences window, and change the
+                     email address on the ``@author`` tag to be your
+                     email address
+
+            #. Now, apply the JAutodoc settings
+
+         .. container:: paragraph
+
+            The templates mentioned above can be found in
+            ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+Configure Checkstyle (Maven)
+----------------------------
+
+         .. container:: paragraph
+
+            When using a custom style configuration with Checkstyle, the
+            definition of that style must of course be available to
+            Checkstyle. In order not to have to distribute style files
+            for checkstyle into all Maven modules, it is recommended
+            that a special Maven module be built that contains the
+            checkstyle style definition. That module is then used as a
+            dependency in the *POM* for all other modules that wish to
+            use that checkstyle style. For a full explanation see `the
+            explanation of Checkstyle multi-module
+            configuration <https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html>`__.
+
+         .. container:: paragraph
+
+            For APEX, the ONAP checkstyle rules do apply. The
+            configuration is part of the ONAP parent. See `ONAP
+            Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
+            for details and updates.
+
+Run Checkstyle (Maven)
+----------------------
+
+         .. container:: paragraph
+
+            Run Checkstyle using Maven on the command line with the
+            command:
+
+         .. container:: listingblock
+
+            .. container:: content
+
+               .. code:: bash
+
+                  mvn checkstyle:check
+
+         .. container:: paragraph
+
+            On the main APEX project, run a full checkstyle check as:
+
+         .. container:: listingblock
+
+            .. container:: content
+
+               .. code:: bash
+
+                  mvn checkstyle:checkstyle -DapexAll
+
+Configure Checkstyle (Eclipse, globally)
+----------------------------------------
+
+         .. container:: olist arabic
+
+            #. Set up a module with the Checkstyle style files (see
+               above)
+
+            #. In Eclipse  Window  Preferences go to Checkstyle
+
+            #. Import the settings for Checkstyle
+
+               .. container:: ulist
+
+                  -  Press New…​ to create a new *Global Check
+                     Configurations* entry
+
+                  -  Give the configuration a name such as *Apex
+                     Checkstyle Configuration* and select the *External
+                     Configuration File* form in the *Type* drop down
+                     menu
+
+                  -  Browse to the Checckstyle setting file
+                     (``ApexCheckstyleSettings.xml``) and press OK
+
+            #. Press OK
+
+               .. container:: ulist
+
+                  -  You may now get an *Unresolved Properties found*
+                     dialogue
+
+                  -  This is because there is a second Checkstyle
+                     configuration file required to check file headers
+
+            #. Press Edit Properties…​ and press Find unresolved
+               properties on the next dialogue window
+
+            #. The plugin will find the ``${checkstyle.header.file}``
+               property is unresolved and will ask should it be added to
+               the properties, click yes
+
+            #. Now, select the row on the dialogue for the
+               ``checkstyle.header.file property`` and click Edit…​
+
+            #. Set the value of the ``checkstyle.header.file property``
+               to
+               ``<your-apex-git-location>/apex-model/apex-model.build-tools/src/main/resources/checkstyle/apex_header.txt``
+
+               .. container:: ulist
+
+                  -  Of course replacing the tag
+                     ``<your-apex-git-location>`` with the location of
+                     your Apex GIT repository
+
+            #. Press OK, OK, OK to back out to the main Checkstyle
+               properties window
+
+            #. Select the *Apex Checkstyle Configuration* as your
+               default configuration by selecting its line in the
+               *Global Check Configuraitons* list and clicking Set as
+               Default
+
+            #. Press Apply and Close to finish Checkstyle global
+               configuration
+
+         .. container:: paragraph
+
+            The templates mentioned above can be found in
+            ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+2.10. Configure Checkstyle Blueprint
+------------------------------------
+
+         .. container:: paragraph
+
+            As well as being configured globally, Checkstyle must be
+            configured and activated for each project in Eclipse. In
+            order to make this process less tedious, set up the first
+            project you apply Checkstye to as a blueprint project and
+            then use this blueprint for all other projects.
+
+         .. container:: olist arabic
+
+            #. Select the project you want to use as a blueprint
+
+               .. container:: ulist
+
+                  -  For example, ``apex-model.basic-model`` in ``apex``
+                     and enter the project properties by right clicking
+                     and selecting **Properties**
+
+            #. Click *Checkstyle* on the properties to get the
+               Checkstyle project configuration window
+
+            #. Click the box *Checkstyle active for this project* and in
+               the *Exclude from checking…​* list check the boxes:
+
+               .. container:: ulist checklist
+
+                  -   *files outside source directories*
+
+                  -   *derived (generated) files*
+
+                  -   *files from packages:*
+
+            #. Now, in order to turn off checking on resource
+               directories and on JUnit tests
+
+               .. container:: ulist
+
+                  -  Select the line *files from packages:* in the
+                     *Exclude from checking…​* list and click Change…​
+
+            #. On the *Filter packages* dialogue
+
+               .. container:: ulist
+
+                  -  Check all the boxes except the top box, which is
+                     the box for *src/main/java*
+
+                  -  Ensure that the *recursively exclude sub-packages*
+                     check box is ticked
+
+                     .. container:: ulist checklist
+
+                        -   *recursively exclude sub-packages*
+
+                  -  Press OK
+
+            #. Press Apply and Close to apply the changes
+
+Use Eclipse Source Operations
+-----------------------------
+
+         .. container:: paragraph
+
+            Eclipse Source Operations can be carried out on individual
+            files or on all the files in a package but do not recurse
+            into sub-packages. They are available as a menu in Eclipse
+            by selecting a file or package and right clicking on
+            *Source*. Note that running *Clean Up…​* with the Apex clean
+            up profile will run *Format* and *Organize Imports*. So if
+            you run a clean up on a file or package, you need not run
+            *Format* or *Organize Imports*.
+
+         .. container:: paragraph
+
+            We recommend you use the following Eclipse Source
+            Operations:
+
+         .. container:: olist arabic
+
+            #. *Format* applies the current format definition to the
+               file or all files in a package
+
+            #. *Organize Imports* sorts the imports on each file in
+               standard order
+
+            #. *Clean Up* runs a number of cleaning operations on each
+               file. The Apex clean up template
+
+               .. container:: ulist
+
+                  -  Remove ``this`` qualifier for non static field
+                     accesses
+
+                  -  Change non static accesses to static members using
+                     declaring type
+
+                  -  Change indirect accesses to static members to
+                     direct accesses (accesses through subtypes)
+
+                  -  Convert control statement bodies to block
+
+                  -  Convert ``for`` loops to enhanced ``for`` loops
+
+                  -  Add final modifier to private fields
+
+                  -  Add final modifier to local variables
+
+                  -  Remove unused imports
+
+                  -  Remove unused private methods
+
+                  -  Remove unused private constructors
+
+                  -  Remove unused private types
+
+                  -  Remove unused private fields
+
+                  -  Remove unused local variables
+
+                  -  Add missing ``@Override`` annotations
+
+                  -  Add missing ``@Override`` annotations to
+                     implementations of interface methods
+
+                  -  Add missing ``@Deprecated`` annotations
+
+                  -  Add missing serial version ID (generated)
+
+                  -  Remove unnecessary casts
+
+                  -  Remove unnecessary ``$NON-NLS$`` tags
+
+                  -  Organize imports
+
+                  -  Format source code
+
+                  -  Remove trailing white spaces on all lines
+
+                  -  Correct indentation
+
+                  -  Remove redundant type arguments
+
+                  -  Add file header (JAutodoc)
+
+Using JAutodoc
+--------------
+
+         .. container:: paragraph
+
+            Similar to Eclipse Source Operations, JAutodoc operations
+            can be carried out on individual files or on all the files
+            in a package but do not recurse into sub-packages. The
+            JAutodoc operations are available by selecting a file or
+            package and right clicking on *JAutodoc*:
+
+         .. container:: olist arabic
+
+            #. To add a ``package-info.java`` file to a package, select
+               the package and right-click Jautodoc  Add Package Javadoc
+
+            #. To add headers to files select on a file (or on the
+               package to do all files) and right click JAutodoc  Add
+               Header
+
+            #. To add JAutodoc stubs to a files, select on a file (or on
+               the package to do all files) and right click JAutodoc 
+               Add Javadoc
+
+Using Checkstyle
+----------------
+
+         .. container:: paragraph
+
+            In order to use Checkstyle, you must configure it per
+            project and then activate it per project. The easiest way to
+            do this is to set up one project as a blueprint and use that
+            blueprint for other projects (see above). Once you have a
+            blueprint project, you can use Checkstyle on other projects
+            as follows
+
+         .. container:: olist arabic
+
+            #. Set up Checkstyle on projects by selecting one or more
+               projects
+
+               .. container:: ulist
+
+                  -  Right clicking and selecting Checkstyle  Configure
+                     project(s) from *blueprint…​* and then selecting
+                     your blueprint project
+
+                  -  (for example ``apex-model.basic-model``) from the
+                     list of projects and pressing OK
+
+            #. Activate Checkstyle on projects by selecting one or more
+               projects
+
+               .. container:: ulist
+
+                  -  Right clicking and selecting Checkstyle  Activate
+                     Checkstyle
+
+                  -  Now Checkstyle warnings will appear on the selected
+                     projects if they have warnings
+
+            #. You can disable Checkstyle checking on a file or a
+               package (recursively) by selecting a file or package
+
+               .. container:: ulist
+
+                  -  Right clicking and selecting Checkstyle  Clear
+                     Checkstyle violations
+
+            #. You can enable Checkstyle checking on a file or a package
+               (recursively) by selecting a file or package
+
+               .. container:: ulist
+
+                  -  Right clicking and selecting Checkstyle  Check Code
+                     with Checkstyle
+
+            #. On individual files, you can apply fixes that clear some
+               Checkstyle warnings
+
+               .. container:: ulist
+
+                  -  Select the file, right click and select **Apply
+                     Checkstyle fixes**
+
+Disable Eclipse Formatting (partially)
+--------------------------------------
+
+         .. container:: paragraph
+
+            Sometimes, the Eclipse code formatting results in correct
+            but untidy indentation, for example when Java Persistence
+            annotations or long sequences of lined-up assignments are
+            formatted. You can disable formatting for sections of code.
+
+         .. container:: olist arabic
+
+            #. Ensure that Off/On Tags are enabled in Eclipse
+
+            #. In Eclipse  Window  Preferences  Java  Code Style 
+               Formatter window press Edit…​
+
+            #. Click on the *Off/On Tags* tab
+
+            #. Ensure that the *Enable Off/On Tags* checkbox is checked
+
+            #. Surround the section of code that you do not want the
+               formatter to act on with comments containing the Off/On
+               tags
+
+         .. container:: listingblock
+
+            .. container:: content
+
+               .. code:: java
+                 :number-lines:
+
+                 // @formatter:off
+                 // Plugin Parameters
+                 private DistributorParameters distributorParameters = new DistributorParameters();
+                 private SchemaParameters      schemaParameters      = new SchemaParameters();
+                 private LockManagerParameters lockManagerParameters = new LockManagerParameters();
+                 private PersistorParameters   persistorParameters   = new PersistorParameters();
+                 // @formatter:on
+
+Supress Checkstyle (partially)
+------------------------------
+
+   .. container:: paragraph
+
+      Sometimes Checkstyle checks identify code that does not comply
+      with Checkstyle rules. In limited cases Checkstyle rules can be
+      suppressed, for example where it is impossible to design the code
+      in a way that complies with Checkstyle or where the Checkstyle
+      rule is impossible to apply. Checkstyle rules are suppressed as is
+      explained in this `Stackoverflow
+      post <https://stackoverflow.com/questions/4023185/how-to-disable-a-particular-checkstyle-rule-for-a-particular-line-of-code>`__.
+
+   .. container:: paragraph
+
+      The example below illustrates how to suppress a Checkstyle rule
+      that specifies all methods must have seven parameters or less.
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: java
+            :number-lines:
+
+            // CHECKSTYLE:OFF: checkstyle:ParameterNumber
+            public myMethod(final int par1, final int par2, final int par3, final int par4,
+              final int par5, final int par6, final int par7, final int par8) {
+            }
+            // CHECKSTYLE:ON: checkstyle:ParameterNumber
+
+apex-apps.utilities
+^^^^^^^^^^^^^^^^^^^
+
+CLI Example
+-----------
+
+         .. container:: paragraph
+
+            Using the APEX CLI utilities can be done as follows. First,
+            add the dependency of the utility project to your POM file.
+
+         .. container:: listingblock
+
+            .. container:: content
+
+               .. code:: bash
+
+                  <dependency>
+                    <groupId>org.onap.policy.apex-pdp.tools</groupId>
+                    <artifactId>tools-common</artifactId>
+                    <version>2.0.0-SNAPSHOT</version>
+                  </dependency>
+
+         .. container:: paragraph
+
+            Now, create a new application project, for instance
+            ``MyApp``. In this project, create a new main application
+            class as ``Application.java``. In this class, create a new
+            main method as ``public static void main(String[] args)``.
+
+         .. container:: paragraph
+
+            No use the provided ``CliOptions`` and ``CliParser``.
+            Manually importing means to add the following lines to the
+            start of your application (in Eclipse this import will be
+            done automatically):
+
+         .. container:: listingblock
+
+            .. container:: content
+
+               .. code:: java
+                  :number-lines:
+
+                  import org.onap.policy.apex.tools.common.CliOptions;
+                  import org.onap.policy.apex.tools.common.CliParser;
+
+.. container:: paragraph
+
+   Now, inside your ``main()`` method, start setting some general
+   application properties. Important are the application name and some
+   description of your application. For instance:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         String appName = "test-app";
+         final String appDescription = "a test app for documenting how to use the CLI utilities";
+
+.. container:: paragraph
+
+   Next, create a new CLI Parser and add a few CLI options from the
+   standard ``CliOptions``. The following example adds options for help,
+   version, and a model file:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         final CliParser cli = new CliParser();
+         cli.addOption(CliOptions.HELP);
+         cli.addOption(CliOptions.VERSION);
+         cli.addOption(CliOptions.MODELFILE);
+
+.. container:: paragraph
+
+   Next, parse the given CLI arguments:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         final CommandLine cmd = cli.parseCli(args);
+
+.. container:: paragraph
+
+   Once the command line is parsed, we can look into the individual
+   options, check if they are set, and then act accordingly. We start
+   with the option for *help*. If the option is present, we print a help
+   screen and return:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         // help is an exit option, print usage and exit
+         if (cmd.hasOption('h') || cmd.hasOption("help")) {
+             final HelpFormatter formatter = new HelpFormatter();
+             LOGGER.info(appName + " v" + cli.getAppVersion() + " - " + appDescription);
+             formatter.printHelp(appName, cli.getOptions());
+             return;
+         }
+
+.. container:: paragraph
+
+   Next, we process the option for *version*. Here, we want to print a
+   version for our application and return. The CLI Parser already
+   provides a method to obtain the correct version for an APEX build, so
+   we use that:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         // version is an exit option, print version and exit
+         if (cmd.hasOption('v') || cmd.hasOption("version")) {
+             LOGGER.info(appName + " " + cli.getAppVersion());
+             return;
+         }
+
+.. container:: paragraph
+
+   Once help and version arguments are processed, we can proceed to look
+   at all other options. We have added an option for a model file, so
+   check this option and test if we can actually load a model file with
+   the given argument. If we can load a model, everything is ok. If we
+   cannot load a model, we print an error and return.
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         String modelFile = cmd.getOptionValue('m');
+         if (modelFile == null) {
+             modelFile = cmd.getOptionValue("model");
+         }
+         if (modelFile == null) {
+             LOGGER.error(appName + ": no model file given, cannot proceed (try -h for help)");
+             return;
+         }
+
+.. container:: paragraph
+
+   With a model file being loadable, we finish parsing command line
+   arguments. We also print some status messages to note that the
+   application now is ready to start:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         LOGGER.info(appName + ": starting");
+         LOGGER.info(" --> model file: " + modelFile);
+
+.. container:: paragraph
+
+   The last action now is to run the actual application. The example
+   below is taken from a version of the ``Model2Cli`` application, which
+   creates a new object and runs it in a ``try`` block, since exceptions
+   might be thrown by the object:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         // your code for the application here
+         // e.g.
+         // try {
+         // Model2Cli app = new Model2Cli(modelFile, !cmd.hasOption("sv"), appName);
+         // app.runApp();
+         // }
+         // catch(ApexException aex) {
+         // LOGGER.error(appName + ": caught APEX exception with message: " + aex.getMessage());
+         // }
+
+.. container:: paragraph
+
+   If this new application is now called with the command line ``-h`` or
+   ``--help`` it will print the following help screen:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: bash
+
+         test-app v2.0.0-SNAPSHOT - a test app for documenting how to use the CLI utilities
+         usage: test-app
+          -h,--help                 prints this help and usage screen
+          -m,--model <MODEL-FILE>   set the input policy model file
+          -v,--version              prints the application version
+
+.. container:: paragraph
+
+   If this new application is called with the option ``-v`` or
+   ``--version`` it will print its version information as:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: bash
+
+         test-app 2.0.0-SNAPSHOT
+
+Autoversioning an Application
+-----------------------------
+
+   .. container:: paragraph
+
+      The APEX utilities project provides means to versioning an
+      application automatically towards the APEX version it is written
+      for. This is realized by generating a file called
+      ``app-version.txt`` that includes the Maven project version. This
+      file is then automatically deployed in the folder ``etc`` of a
+      full APEX distribution. The CLI Parser here provides a mthod to
+      access this version for an application.
+
+   .. container:: paragraph
+
+      First, create a new CLI Parser object, add some options (in the
+      example an option for version, but any options will do), then
+      parse the command line:
+
+   .. container:: listingblock
+
+      .. container:: content
+
+         .. code:: java
+            :number-lines:
+
+            final CliParser cli = new CliParser();
+            cli.addOption(CliOptions.VERSION);
+            final CommandLine cmd = cli.parseCli(args);
+
+.. container:: paragraph
+
+   Next, we check if the version option was used in the command line and
+   print application name and version if it was used:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         // version is an exit option, print version and exit
+         if (cmd.hasOption('v') || cmd.hasOption("version")) {
+             LOGGER.info("myApp" + " " + cli.getAppVersion());
+             return;
+         }
+
+.. container:: paragraph
+
+   The output will be:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: bash
+
+         myApp 2.0.0-SNAPSHOT
+
+.. container:: paragraph
+
+   The auto-version information comes from the method call
+   ``cli.getAppVersion()`` in line 2 in the example above. The method is
+   defined in the ``CliParser`` class as:
+
+.. container:: listingblock
+
+   .. container:: content
+
+      .. code:: java
+         :number-lines:
+
+         public String getAppVersion() {
+             return new Scanner(CliParser.class.getResourceAsStream("/app-version.txt"), "UTF-8").useDelimiter("\\A").next();
+         }
+
+.. container:: paragraph
+
+   The file ``app-version.txt`` is automatically added to an APEX full
+   distribution, as described above (for details on this see the POM
+   files in the APEX application packaging projects).
+
+.. container::
+   :name: footer
+
+   .. container::
+      :name: footer-text
+
+      2.0.0-SNAPSHOT
+      Last updated 2018-09-04 16:04:24 IST