diff options
| author |   liamfallon <liam.fallon@est.tech> | 2020-07-13 16:37:56 +0100 |
|---|---|---|
| committer | liamfallon <liam.fallon@est.tech> | 2020-07-13 16:38:06 +0100 |
| commit | ab5be046f229fcb23a9b4dfb3746a1c0fabcce9d (patch) | |
| tree | 13672ff36c41475c4d3eaa7a970e2074a44340c8 /docs | |
| parent | f398107e1423eb77a30f5fcc5402cf557a077170 (diff) | |
Remove redundant apex-pdp documentation
The developer guide and installation guide are amalgamated into the apex
policy guide. The informaiton in those documents is redundant.
Issue-ID: POLICY-2686
Change-Id: Ib6426aa508bad3206808ff2fb2f3d8b1d3c2bd5f
Signed-off-by: liamfallon <liam.fallon@est.tech>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/apex/APEX-Developer-Guide.rst | 1471 | ||||
| -rw-r--r-- | docs/apex/APEX-Install-Guide.rst | 1418 | ||||
| -rw-r--r-- | docs/apex/APEX-Policy-Guide.rst | 2 | ||||
| -rw-r--r-- | docs/apex/apex.rst | 4 |
4 files changed, 2 insertions, 2893 deletions
diff --git a/docs/apex/APEX-Developer-Guide.rst b/docs/apex/APEX-Developer-Guide.rst deleted file mode 100644 index b247ab83..00000000 --- a/docs/apex/APEX-Developer-Guide.rst +++ /dev/null @@ -1,1471 +0,0 @@ -.. 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 - - Once 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 built 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 built 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. - -+-----------------------------------------------------------------------------------------------------------------------------+ -| 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 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 built 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 - successfully. - -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 for a standard - build with *all* components. - - .. important:: - Might require specific software. - When building all components, some modules require specific software to be 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 documentation, - such as the HowTo documents, the Installation Guide, and the User - Manual. Use Maven to build the APEX Documentation. The Maven - option ``-N`` prevents Maven from going 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 built, 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 projects 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 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 - - Now 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 a means to version an - application automatically towards the APEX version for which it is - written. 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 method 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 diff --git a/docs/apex/APEX-Install-Guide.rst b/docs/apex/APEX-Install-Guide.rst deleted file mode 100644 index 0cff1317..00000000 --- a/docs/apex/APEX-Install-Guide.rst +++ /dev/null @@ -1,1418 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - - -APEX Installation Guide -*********************** - -.. contents:: - :depth: 3 - -Requirements -^^^^^^^^^^^^ - - .. container:: sectionbody - - .. container:: paragraph - - APEX is 100% written in Java and runs on any platform that - supports a JVM, e.g. Windows, Unix, Cygwin. Some APEX - applications (such as the monitoring application) come as - web archives, they do require a war-capable web server - installed. - -Installation Requirements -------------------------- - - .. container:: ulist - - - Downloaded distribution: JAVA runtime environment - (JRE, Java 8 or later, APEX is tested with the Oracle - Java) - - - Building from source: JAVA development kit (JDK, Java - 8 or later, APEX is tested with the Oracle Java) - - - A web archive capable webserver, for instance for the - monitoring application - - .. container:: ulist - - - for instance `Apache - Tomcat <https://tomcat.apache.org/>`__ - - - Sufficient rights to install APEX on the system - - - Installation tools depending on the installation - method used: - - .. container:: ulist - - - ZIP to extract from a ZIP distribution - - .. container:: ulist - - - Windows for instance - `7Zip <http://www.7-zip.org/>`__ - - - TAR and GZ to extract from that TAR.GZ - distribution - - .. container:: ulist - - - Windows for instance - `7Zip <http://www.7-zip.org/>`__ - - - RPM to install from the RPM distribution - - .. container:: ulist - - - Install: ``sudo apt-get install rpm`` - - - DPKG to install from the DEB distribution - - .. container:: ulist - - - Install: ``sudo apt-get install dpkg`` - -Feature Requirements --------------------- - - .. container:: paragraph - - APEX supports a number of features that require extra - software being installed. - - .. container:: ulist - - - `Apache Kafka <https://kafka.apache.org/>`__ to - connect APEX to a Kafka message bus - - - `Hazelcast <https://hazelcast.com/>`__ to use - distributed hash maps for context - - - `Infinispan <http://infinispan.org/>`__ for - distributed context and persistence - - - `Docker <https://www.docker.com/>`__ to run APEX - inside a Docker container - -Build (Install from Source) Requirements ----------------------------------------- - - .. container:: paragraph - - Installation from source requires a few development tools - - .. container:: ulist - - - GIT to retrieve the source code - - - Java SDK, Java version 8 or later - - - Apache Maven 3 (the APEX build environment) - -Get the APEX Source Code -^^^^^^^^^^^^^^^^^^^^^^^^ - - .. container:: sectionbody - - .. container:: paragraph - - The first APEX source code was hosted on Github in January - 2018. By the end of 2018, APEX was added as a project in the - ONAP Policy Framework, released later in the ONAP Casablanca - release. - - .. container:: paragraph - - The APEX source code is hosted in ONAP as project APEX. The - current stable version is in the master branch. Simply clone - the master branch from ONAP using HTTPS. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - git clone https://gerrit.onap.org/r/policy/apex-pdp - -Build APEX -^^^^^^^^^^ - - .. container:: sectionbody - - .. container:: paragraph - - The examples in this document assume that the APEX source - repositories are cloned to: - - .. container:: ulist - - - Unix, Cygwin: ``/usr/local/src/apex-pdp`` - - - Windows: ``C:\dev\apex-pdp`` - - - Cygwin: ``/cygdrive/c/dev/apex-pdp`` - - .. 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) - 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 built if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, - then build APEX. - - .. container:: paragraph - - Use Maven for a standard build without any tests. - - +-------------------------------------------------------+--------------------------------------------------------+ - | Unix, Cygwin | Windows | - +=======================================================+========================================================+ - | .. container:: | .. container:: | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: bash | .. code:: bash | - | :number-lines: | :number-lines: | - | | | - | >c: | # cd /usr/local/src/apex-pdp | - | >cd \dev\apex | # mvn clean install -Pdocker -DskipTests | - | >mvn clean install -Pdocker -DskipTests | | - +-------------------------------------------------------+--------------------------------------------------------+ - -.. container:: paragraph - - The build takes 2-3 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 - - .. container:: content - - .. 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. - -+----------------------------------------------------------------------------------------------------------------------------+ -| Unix, Cygwin | -+============================================================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. container:: content | -| | -| .. code:: bash | -| :number-lines: | -| | -| -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 | -| | -| .. container:: content | -| | -| .. code:: bash | -| :number-lines: | -| | -| 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 | -+--------------------------------------------------------------------------------------------------------+ - -Install APEX -^^^^^^^^^^^^ - - .. container:: paragraph - - APEX can be installed in different ways: - - .. container:: ulist - - - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` - or ``.deb`` archive - - - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive - - - Windows, Unix, Cygwin: build from source using Maven, then - install manually - -Install with RPM and DPKG -------------------------- - - .. container:: paragraph - - The install distributions of APEX automatically install the - system. The installation directory is - ``/opt/app/policy/apex-pdp``. Log files are located in - ``/var/log/onap/policy/apex-pdp``. The latest APEX version - will be available as ``/opt/app/policy/apex-pdp/apex-pdp``. - - .. container:: paragraph - - For the installation, a new user ``apexuser`` and a new - group ``apexuser`` will be created. This user owns the - installation directories and the log file location. The user - is also used by the standard APEX start scripts to run APEX - with this user’s permissions. - - +-----------------------------------------------------------------------+ - | RPM Installation | - +=======================================================================+ - | .. container:: | - | | - | .. container:: listingblock | - | | - | .. container:: content | - | | - | .. code:: bash | - | :number-lines: | - | | - | # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm | - | ********************preinst******************* | - | arguments 1 | - | ********************************************** | - | creating group apexuser . . . | - | creating user apexuser . . . | - | ********************postinst**************** | - | arguments 1 | - | *********************************************** | - +-----------------------------------------------------------------------+ - -+--------------------------------------------------------------------------------------+ -| DPKG Installation | -+======================================================================================+ -| .. container:: | -| | -| .. container:: listingblock | -| | -| .. container:: content | -| | -| .. code:: bash | -| :number-lines: | -| | -| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb | -| Selecting previously unselected package apex-uservice. | -| (Reading database ... 288458 files and directories currently installed.) | -| Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ... | -| ********************preinst******************* | -| arguments install | -| ********************************************** | -| creating group apexuser . . . | -| creating user apexuser . . . | -| Unpacking apex-uservice (2.0.0-SNAPSHOT) ... | -| Setting up apex-uservice (2.0.0-SNAPSHOT) ... | -| ********************postinst**************** | -| arguments configure | -| *********************************************** | -+--------------------------------------------------------------------------------------+ - -.. container:: paragraph - - Once the installation is finished, APEX is fully installed and ready - to run. - -Install Manually from Archive (Unix, Cygwin) --------------------------------------------- - - .. container:: paragraph - - Download a ``tar.gz`` archive. Create a directory where APEX - should be installed. Extract the ``tar`` archive. The following - example shows how to install APEX in ``/opt/apex`` and create a - link to ``/opt/apex/apex`` for the most recent installation. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - # cd /opt - # mkdir apex - # cd apex - # mkdir apex-full-2.0.0-SNAPSHOT - # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT - # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT - -Install Manually from Archive (Windows, 7Zip, GUI) --------------------------------------------------- - - .. container:: paragraph - - Download a ``tar.gz`` archive and copy the file into the install - folder (in this example ``C:\apex``). Assuming you are using 7Zip, - right click on the file and extract the ``tar`` archive. Note: the - screenshots might show an older version than you have. - - .. container:: imageblock - - .. container:: content - - |Extract the TAR archive| - - .. container:: paragraph - - The right-click on the new created TAR file and extract the actual - APEX distribution. - - .. container:: imageblock - - .. container:: content - - |Extract the APEX distribution| - - .. container:: paragraph - - Inside the new APEX folder you see the main directories: ``bin``, - ``etc``, ``examples``, ``lib``, and ``war`` - - .. container:: paragraph - - Once extracted, please rename the created folder to - ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in - line with the rest of this documentation. - -Install Manually from Archive (Windows, 7Zip, CMD) --------------------------------------------------- - - .. container:: paragraph - - Download a ``tar.gz`` archive and copy the file into the install - folder (in this example ``C:\apex``). Start ``cmd``, for instance - typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming - ``7Zip`` is installed in the standard folder, simply run the - following commands (for APEX version 2.0.0-SNAPSHOT full - distribution) - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - >c: - >cd \apex - >"\Program Files\7-Zip\7z.exe" x apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-2.0.0-SNAPSHOT" - -.. container:: paragraph - - APEX is now installed in the folder - ``C:\apex\apex-full-2.0.0-SNAPSHOT``. - -Build from Source -^^^^^^^^^^^^^^^^^ - -Build and Install Manually (Unix, Windows, Cygwin) --------------------------------------------------- - - .. container:: paragraph - - Clone the APEX GIT repositories into a directory. Go to that - directory. Use Maven to build APEX (all details on building - APEX from source can be found in *APEX HowTo: Build*). - Install from the created artifacts (``rpm``, ``deb``, - ``tar.gz``, or copy manually). - - .. 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. - - .. container:: paragraph - - The following example shows how to build the APEX system, - without tests (``-DskipTests``) to save some time. It - assumes that the APEX GIT repositories are cloned to: - - .. container:: ulist - - - Unix, Cygwin: ``/usr/local/src/apex`` - - - Windows: ``C:\dev\apex`` - - +-------------------------------------------------------+--------------------------------------------------------+ - | 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 -Pdocker -DskipTests | - | >mvn clean install -Pdocker -DskipTests | | - +-------------------------------------------------------+--------------------------------------------------------+ - -.. container:: paragraph - - The build takes about 2 minutes without test and about 4-5 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 - built 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 successfully. - -.. container:: paragraph - - When Maven is finished with the build, the final screen should look - similar to this (omitting some ``success`` lines): - -.. container:: listingblock - - .. container:: content - - .. 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 | -+-----------------------------------------------------------------------------------------------------------------------------+ - -.. container:: paragraph - - Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX. - Alternatively, copy the content of the folder ``install_hierarchy`` - to your APEX directory. - -Installation Layout -^^^^^^^^^^^^^^^^^^^ - - .. container:: paragraph - - A full installation of APEX comes with the following layout. - - .. container:: listingblock - - .. container:: content - - :: - - $APEX_HOME - ├───bin (1) - ├───etc (2) - │ ├───editor - │ ├───hazelcast - │ ├───infinispan - │ └───META-INF - ├───examples (3) - │ ├───config (4) - │ ├───docker (5) - │ ├───events (6) - │ ├───html (7) - │ ├───models (8) - │ └───scripts (9) - ├───lib (10) - │ └───applications (11) - └───war (12) - - .. container:: colist arabic - - +-----------------------------------+-----------------------------------+ - | **1** | binaries, mainly scripts (bash | - | | and bat) to start the APEX engine | - | | and applications | - +-----------------------------------+-----------------------------------+ - | **2** | configuration files, such as | - | | logback (logging) and third party | - | | library configurations | - +-----------------------------------+-----------------------------------+ - | **3** | example policy models to get | - | | started | - +-----------------------------------+-----------------------------------+ - | **4** | configurations for the examples | - | | (with sub directories for | - | | individual examples) | - +-----------------------------------+-----------------------------------+ - | **5** | Docker files and additional | - | | Docker instructions for the | - | | exampples | - +-----------------------------------+-----------------------------------+ - | **6** | example events for the examples | - | | (with sub directories for | - | | individual examples) | - +-----------------------------------+-----------------------------------+ - | **7** | HTML files for some examples, | - | | e.g. the Decisionmaker example | - +-----------------------------------+-----------------------------------+ - | **8** | the policy models, generated for | - | | each example (with sub | - | | directories for individual | - | | examples) | - +-----------------------------------+-----------------------------------+ - | **9** | additional scripts for the | - | | examples (with sub directories | - | | for individual examples) | - +-----------------------------------+-----------------------------------+ - | **10** | the library folder with all Java | - | | JAR files | - +-----------------------------------+-----------------------------------+ - | **11** | applications, also known as jar | - | | with dependencies (or fat jars), | - | | individually deployable | - +-----------------------------------+-----------------------------------+ - | **12** | WAR files for web applications | - +-----------------------------------+-----------------------------------+ - -System Configuration -^^^^^^^^^^^^^^^^^^^^ - - .. container:: paragraph - - Once APEX is installed, a few configurations need to be done: - - .. container:: ulist - - - Create an APEX user and an APEX group (optional, if not - installed using RPM and DPKG) - - - Create environment settings for ``APEX_HOME`` and - ``APEX_USER``, required by the start scripts - - - Change settings of the logging framework (optional) - - - Create directories for logging, required (execution might - fail if directories do not exist or cannot be created) - -APEX User and Group -------------------- - - .. container:: paragraph - - On smaller installations and test systems, APEX can run as - any user or group. - - .. container:: paragraph - - However, if APEX is installed in production, we strongly - recommend you set up a dedicated user for running APEX. This - will isolate the execution of APEX to that user. We - recommend you use the userid ``apexuser`` but you may use - any user you choose. - - .. container:: paragraph - - The following example, for UNIX, creates a group called - ``apexuser``, an APEX user called ``apexuser``, adds the - group to the user, and changes ownership of the APEX - installation to the user. Substitute ``<apex-dir>`` with the - directory where APEX is installed. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - # sudo groupadd apexuser - # sudo useradd -g apexuser apexuser - # sudo chown -R apexuser:apexuser <apex-dir> - -.. container:: paragraph - - For other operating systems please consult your manual or system - administrator. - -Environment Settings: APEX_HOME and APEX_USER ---------------------------------------------- - - .. container:: paragraph - - The provided start scripts for APEX require two environment - variables being set: - - .. container:: ulist - - - ``APEX_USER`` with the user under whose name and permission APEX - should be started (Unix only) - - - ``APEX_HOME`` with the directory where APEX is installed (Unix, - Windows, Cygwin) - - .. container:: paragraph - - The first row in the following table shows how to set these - environment variables temporarily (assuming the user is - ``apexuser``). The second row shows how to verify the settings. - The last row explains how to set those variables permanently. - - +------------------------------------------------+---------------------------------------------------------+ - | Unix, Cygwin (bash/tcsh) | Windows | - +================================================+=========================================================+ - | .. container:: | .. container:: | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: bash | .. code:: bash | - | :number-lines: | :number-lines: | - | | | - | # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT | - | # cd /opt/app/policy/apex-pdp | | - | # export APEX_HOME=`pwd` | | - | | | - +------------------------------------------------+ | - | .. container:: | | - | | | - | .. container:: content | | - | | | - | .. code:: tcsh | | - | :number-lines: | | - | | | - | # setenv APEX_USER apexuser | | - | # cd /opt/app/policy/apex-pdp | | - | # setenv APEX_HOME `pwd` | | - | | | - +------------------------------------------------+---------------------------------------------------------+ - | .. container:: | .. container:: | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: bash | .. code:: bash | - | :number-lines: | :number-lines: | - | | | - | # env | grep APEX | >set APEX_HOME | - | # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT | - | # APEX_HOME=/opt/app/policy/apex-pdp | | - | | | - +------------------------------------------------+---------------------------------------------------------+ - - -Making Environment Settings Permanent (Unix, Cygwin) -#################################################### - - .. container:: paragraph - - For a per-user setting, edit the user’s ``bash`` or ``tcsh`` - settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide - settings, edit ``/etc/profiles`` (requires permissions). - - -Making Environment Settings Permanent (Windows) -############################################### - - .. container:: paragraph - - On Windows 7 do - - .. container:: ulist - - - Click on the **Start** Menu - - - Right click on **Computer** - - - Select **Properties** - - .. container:: paragraph - - On Windows 8/10 do - - .. container:: ulist - - - Click on the **Start** Menu - - - Select **System** - - .. container:: paragraph - - Then do the following - - .. container:: ulist - - - Select **Advanced System Settings** - - - On the **Advanced** tab, click the **Environment Variables** - button - - - Edit an existing variable, or create a new System variable: - 'Variable name'="APEX_HOME", 'Variable - value'="C:\apex\apex-full-2.0.0-SNAPSHOT" - - .. container:: paragraph - - For the settings to take effect, an application needs to be - restarted (e.g. any open ``cmd`` window). - -Edit the APEX Logging Settings ------------------------------- - - .. container:: paragraph - - Configure the APEX logging settings to your requirements, for - instance: - - .. container:: ulist - - - change the directory where logs are written to, or - - - change the log levels - - .. container:: paragraph - - Edit the file ``$APEX_HOME/etc/logback.xml`` for any required - changes. To change the log directory change the line - - .. container:: paragraph - - ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />`` - - .. container:: paragraph - - to - - .. container:: paragraph - - ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />`` - - .. container:: paragraph - - On Windows, it is recommended to change the log directory to: - - .. container:: paragraph - - ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />`` - - .. container:: paragraph - - Note: Be careful about when to use ``\`` vs. ``/`` as the path - separator! - -Create Directories for Logging ------------------------------- - - .. container:: paragraph - - Make sure that the log directory exists. This is important when - APEX is installed manually or when the log directory is changed - in the settings (see above). - - +------------------------------------------------------------------+-------------------------------------------------------+ - | Unix, Cygwin | Windows | - +==================================================================+=======================================================+ - | .. container:: | .. container:: | - | | | - | .. container:: content | .. container:: content | - | | | - | .. code:: bash | .. code:: bash | - | :number-lines: | :number-lines: | - | | | - | mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs | - | chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | | - +------------------------------------------------------------------+-------------------------------------------------------+ - -Verify the APEX Installation -############################ - - .. container:: sectionbody - - .. container:: paragraph - - When APEX is installed and all settings are realized, the - installation can be verified. - -Verify Installation - run Engine --------------------------------- - - .. container:: paragraph - - A simple verification of an APEX installation can be done by - simply starting the APEX engine without any configuration. - On Unix (or Cygwin) start the engine using - ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the - engine using ``%APEX_HOME%\bin\apexEngine.bat``. The engine - will fail to fully start. However, if the output looks - similar to the following line, the APEX installation is - realized. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - Starting Apex service with parameters [] . . . - start of Apex service failed: Apex configuration file was not specified as an argument - 2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed - org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267) - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161) - at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68) - at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165) - usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] - options - -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file - containing the Apex configuration parameters - -h,--help outputs the usage of this command - -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the - configuration file - -v,--version outputs the version of Apex - -Verify Installation - run an Example ------------------------------------- - - .. container:: paragraph - - A full APEX installation comes with several examples. Here, we can - fully verify the installation by running one of the examples. - - .. container:: paragraph - - We use the example called *SampleDomain* and configure the engine - to use standard in and standard out for events. Run the engine - with the provided configuration. Note: Cygwin executes scripts as - Unix scripts but runs Java as a Windows application, thus the - configuration file must be given as a Windows path. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1) - # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2) - >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3) - -.. container:: colist arabic - - +-------+---------+ - | **1** | UNIX | - +-------+---------+ - | **2** | Cygwin | - +-------+---------+ - | **3** | Windows | - +-------+---------+ - -.. container:: paragraph - - The engine should start successfully. Assuming the logging levels are - not changed (default level is ``info``), the output should look - similar to this (last few lines) - -.. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . . - 2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 . - 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 . - 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 . - 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 . - 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created. - 2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . . - 2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started - 2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1 - 2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1 - 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1 - 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1 - 2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine - Started Apex service - -.. container:: paragraph - - Important are the last two lines, stating that APEX has added the - final action listener to the engine and that the engine is started. - -.. container:: paragraph - - The engine is configured to read events from standard input and write - produced events to standard output. The policy model is a very simple - policy. - -.. container:: paragraph - - The following table shows an input event in the left column and an - output event in the right column. Paste the input event into the - console where APEX is running, and the output event should appear in - the console. Pasting the input event multiple times will produce - output events with different values. - -+-------------------------------------------------------------+-------------------------------------------------------------+ -| Input Event | Example Output Event | -+=============================================================+=============================================================+ -| .. container:: | .. container:: | -| | | -| .. container:: content | .. container:: content | -| | | -| .. code:: bash | .. code:: bash | -| :number-lines: | :number-lines: | -| | | -| { | { | -| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", | -| "name": "Event0000", | "version": "0.0.1", | -| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", | -| "source": "test", | "source": "Act", | -| "target": "apex", | "target": "Outside", | -| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, | -| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, | -| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, | -| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, | -| } | "TestEstablishCaseSelected": 0, | -| | "TestEstablishStateTime": 1536157104623, | -| | "TestMatchCase": 0, | -| | "TestMatchCaseSelected": 1, | -| | "TestMatchStateTime": 1536157104620, | -| | "TestSlogan": "Test slogan for External Event0", | -| | "TestTemperature": 9080.866, | -| | "TestTimestamp": 1469781869269 | -| | } | -+-------------------------------------------------------------+-------------------------------------------------------------+ - -.. container:: paragraph - - Terminate APEX by simply using ``CTRL+C`` in the console. - -Verify a Full Installation - REST Editor ----------------------------------------- - - .. container:: paragraph - - APEX has a REST application for viewing policy models. The - application can also be used to create new policy models close to - the engine native policy language. Start the REST editor as - follows. - - .. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - # $APEX_HOME/bin/apexApps.sh rest-editor - -.. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - >%APEX_HOME%\bin\apexApps.bat rest-editor - -.. container:: paragraph - - The script will start a simple web server - (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a - ``war`` web archive in it. Once the editor is started, it will be - available on ``localhost:18989``. The last few line of the messages - should be: - -.. container:: listingblock - - .. container:: content - - .. code:: bash - :number-lines: - - Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . - Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start - INFO: Started listener bound to [localhost:18989] - Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start - INFO: [HttpServer] Started. - Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ - -.. container:: paragraph - - Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and - use the URL ``http://localhost:18989/``. This will connect the - browser to the started REST editor. The start screen should be as - follows. - -.. container:: imageblock - - .. container:: content - - |REST Editor Start Screen| - - .. container:: title - - Figure 1. REST Editor Start Screen - -.. container:: paragraph - - Now load a policy model by clicking the menu ``File`` and then - ``Open``. In the opened dialog, go to the directory where APEX is - installed, then ``examples``, ``models``, ``SampleDomain``, and there - select the file ``SamplePolicyModelJAVA.json``. This will load the - policy model used to verify the policy engine (see above). Once - loaded, the screen should look as follows. - -.. container:: imageblock - - .. container:: content - - |REST Editor with loaded SampleDomain Policy Model| - - .. container:: title - - Figure 2. REST Editor with loaded SampleDomain Policy Model - -.. container:: paragraph - - Now you can use the REST editor. To finish this verification, simply - terminate your browser (or the tab), and then use ``CTRL+C`` in the - console where you started the REST editor. - -Installing WAR Applications -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. container:: sectionbody - - .. container:: paragraph - - APEX comes with a set of WAR files. These are complete - applications that can be installed and run in an application - server. All of these applications are realized as servlets. You - can find the WAR applications in ``$APEX_HOME/war`` (UNIX, - Cygwin) or ``%APEX_HOME%\war`` (Windows). - - .. container:: paragraph - - Installing and using the WAR applications requires a web server - that can execute ``war`` web archives. We recommend using - `Apache Tomcat <https://tomcat.apache.org/>`__, however other - web servers can be used as well. - - .. container:: paragraph - - Install Apache Tomcat including the ``Manager App``, see `V9.0 - Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__ - for details. Start the Tomcat service, or make sure that Tomcat - is running. - - .. container:: paragraph - - There are multiple ways to install the APEX WAR applications: - - .. container:: ulist - - - copy the ``.war`` file into the Tomcat ``webapps`` folder - - - use the Tomcat ``Manager App`` to deploy via the web - interface - - - deploy using a REST call to Tomcat - - .. container:: paragraph - - For details on how to install ``war`` files please consult the - `Tomcat - Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__ - or the `Manager App - HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__. - Once you have installed an APEX WAR application (and wait for - sufficient time for Tomcat to finalize the installation), open - the ``Manager App`` in Tomcat. You should see the APEX WAR - application being installed and running. - - .. container:: paragraph - - In case of errors, examine the log files in the Tomcat log - directory. In a conventional install, those log files are in - the logs directory where Tomcat is installed. - - .. container:: paragraph - - The current APEX version provides the following WAR - applications: - - .. container:: ulist - - - client-deployment-2.0.0-SNAPSHOT.war - a client to deploy - new policy models to a running engine - - - client-editor-2.0.0-SNAPSHOT.war - the standard policy REST - editor GUI - - - client-monitoring-2.0.0-SNAPSHOT.war - a client for - monitoring a running APEX engine - - - client-full-2.0.0-SNAPSHOT.war - a full client with a - one-stop-access to deployment, monitoring, and REST editor - - - examples-servlet-2.0.0-SNAPSHOT.war - an example APEX - servlet - -Running APEX in Docker -^^^^^^^^^^^^^^^^^^^^^^ - - .. container:: sectionbody - - .. container:: paragraph - - Since APEX is in ONAP, we provide a full virtualization - environment for the engine. - -Run in ONAP ------------ - - .. container:: paragraph - - Running APEX from the ONAP docker repository only requires 2 - commands: - - .. container:: olist arabic - - #. Log into the ONAP docker repo - - .. container:: listingblock - - .. container:: content - - :: - - docker login -u docker -p docker nexus3.onap.org:10003 - - .. container:: olist arabic - - #. Run the APEX docker image - - .. container:: listingblock - - .. container:: content - - :: - - docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest - - -Build a Docker Image --------------------- - - .. container:: paragraph - - Alternatively, one can use the Dockerfile defined in the - Docker package to build an image. - - .. container:: listingblock - - .. container:: title - - APEX Dockerfile - - .. container:: content - - .. code:: bash - :number-lines: - - # - # Docker file to build an image that runs APEX on Java 8 in Ubuntu - # - FROM ubuntu:16.04 - - RUN apt-get update && \ - apt-get upgrade -y && \ - apt-get install -y software-properties-common && \ - add-apt-repository ppa:openjdk-r/ppa -y && \ - apt-get update && \ - apt-get install -y openjdk-8-jdk - - # Create apex user and group - RUN groupadd apexuser - RUN useradd --create-home -g apexuser apexuser - - # Add Apex-specific directories and set ownership as the Apex admin user - RUN mkdir -p /opt/app/policy/apex-pdp - RUN mkdir -p /var/log/onap/policy/apex-pdp - RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp - - # Unpack the tarball - RUN mkdir /packages - COPY apex-pdp-package-full.tar.gz /packages - RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp - RUN rm /packages/apex-pdp-package-full.tar.gz - - # Ensure everything has the correct permissions - RUN find /opt/app -type d -perm 755 - RUN find /opt/app -type f -perm 644 - RUN chmod a+x /opt/app/policy/apex-pdp/bin/* - - # Copy examples to Apex user area - RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser - - RUN apt-get clean - - RUN chown -R apexuser:apexuser /home/apexuser/* - - USER apexuser - ENV PATH /opt/app/policy/apex-pdp/bin:$PATH - WORKDIR /home/apexuser - -.. container:: - :name: footer - - .. container:: - :name: footer-text - - 2.0.0-SNAPSHOT - Last updated 2018-09-10 15:38:16 IST - -.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png -.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png -.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png -.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png - diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst index cb4ae729..4b11413f 100644 --- a/docs/apex/APEX-Policy-Guide.rst +++ b/docs/apex/APEX-Policy-Guide.rst @@ -7,7 +7,7 @@ APEX Policy Guide .. contents:: - :depth: 3 + :depth: 5 ****************** APEX Policy Matrix diff --git a/docs/apex/apex.rst b/docs/apex/apex.rst index 8023e6d7..862bcfaf 100644 --- a/docs/apex/apex.rst +++ b/docs/apex/apex.rst @@ -3,14 +3,12 @@ .. _apex-doc: Policy APEX PDP Engine ------------------------------------------------- +---------------------- .. toctree:: :maxdepth: 1 APEX-Introduction.rst APEX-User-Manual.rst APEX-Policy-Guide.rst - APEX-Developer-Guide.rst - APEX-Install-Guide.rst APEX-OnapPf-Guide.rst APEX-Policy-Examples.rst |