+++ /dev/null
-.. 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
+++ /dev/null
-.. 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
-
Code Review / policy / parent.git / commitdiff