.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
+.. _apex-user-manual-label:
APEX User Manual
****************
.. contents::
:depth: 3
-Installation
-^^^^^^^^^^^^
+Installation of Apex
+^^^^^^^^^^^^^^^^^^^^
Requirements
------------
.. container:: ulist
- Downloaded distribution: JAVA runtime environment
- (JRE, Java 8 or later, APEX is tested with the
- Oracle Java)
+ (JRE, Java 11 or later, APEX is tested with the
+ OpenJDK Java)
- Building from source: JAVA development kit (JDK,
- Java 8 or later, APEX is tested with the Oracle
+ Java 11 or later, APEX is tested with the OpenJDK
Java)
- A web archive capable webserver, for instance for
- 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
repository. The first standard build (and any first specific build) requires Internet access to download those
dependencies.
- .. important::
- Building RPM distributions
- RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``,
- then build APEX.
-
.. container:: paragraph
Use Maven to for a standard build without any tests.
installation. The following example show how to change to the target
directory and how it should look like.
-+----------------------------------------------------------------------------------------------------------------------------+
-| Unix, Cygwin |
-+============================================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. container:: content |
-| |
-| .. code:: |
-| :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:: |
-| :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 |
-+--------------------------------------------------------------------------------------------------------+
++---------------------------------------------------------------------------------------------------------------------+
+| Unix, Cygwin |
++=====================================================================================================================+
+| .. container:: content |
+| |
+| .. container:: listingblock |
+| |
+| .. container:: content |
+| |
+| .. code:: |
+| :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:: |
+| :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:: ulist
- - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` or
+ - Unix: automatically using ``dpkg`` from
``.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
-#########################
+Install with DPKG
+#################
.. container:: paragraph
+ You can get the APEX debian package from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
The install distributions of APEX automatically install the
system. The installation directory is
``/opt/app/policy/apex-pdp``. Log files are located in
the standard APEX start scripts to run APEX with this user’s
permissions.
- +-----------------------------------------------------------------------+
- | RPM Installation |
- +=======================================================================+
- | .. container:: |
- | |
- | .. container:: listingblock |
- | |
- | .. container:: content |
- | |
- | .. code:: |
- | :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:: |
-| :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 |
-| *********************************************** |
-+--------------------------------------------------------------------------------------+
++-------------------------------------------------------------------------------+
+| DPKG Installation |
++===============================================================================+
+| .. container:: |
+| |
+| .. container:: listingblock |
+| |
+| .. container:: content |
+| |
+| .. code:: |
+| :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
.. container:: paragraph
- Download a ``tar.gz`` archive. Create a directory where APEX
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ 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:: paragraph
- Download a ``tar.gz`` archive and copy the file into the install
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ Copy the ``tar.gz`` 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``,
+ Now, right-click on the new created TAR file and extract the actual
+ APEX distribution. Inside the new APEX folder you will see the main directories: ``bin``,
``etc``, ``examples``, ``lib``, and ``war``
.. container:: paragraph
.. container:: paragraph
- Download a ``tar.gz`` archive and copy the file into the install
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ Copy the ``tar.gz`` 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
from the created artifacts (``rpm``, ``deb``, ``tar.gz``, or
copying 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,
installation. The following example show how to change to the target
directory and how it should look like.
-+-----------------------------------------------------------------------------------------------------------------------------+
-| Unix, Cygwin |
-+=============================================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. code:: |
-| :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:: |
-| :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 |
-+-----------------------------------------------------------------------------------------------------------------------------+
++--------------------------------------------------------------------------------------------------------------------+
+| Unix, Cygwin |
++====================================================================================================================+
+| .. container:: |
+| |
+| .. container:: listingblock |
+| |
+| .. code:: |
+| :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:: |
+| :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
.. container:: content
- ::
+ ::
$APEX_HOME
├───bin (1)
.. container:: paragraph
A simple verification of an APEX installation can be done by
- simply starting the APEX engine without any configuration. On
+ simply starting the APEX engine without specifying a tosca policy. 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
+ ``$APEX_HOME/bin/apexApps.sh engine``. On Windows start the engine
+ using ``%APEX_HOME%\bin\apexApps.bat engine``. The engine will fail
to fully start. However, if the output looks similar to the
following line, the APEX installation is realized.
: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
+ start of Apex service failed.
+ org.onap.policy.apex.model.basicmodel.concepts.ApexException: Arguments validation failed.
+ at org.onap.policy.apex.service.engine.main.ApexMain.populateApexParameters(ApexMain.java:238)
+ at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:86)
+ at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:351)
+ Caused by: org.onap.policy.apex.model.basicmodel.concepts.ApexException: Tosca Policy file was not specified as an argument
+ at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:242)
+ at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:172)
+ at org.onap.policy.apex.service.engine.main.ApexMain.populateApexParameters(ApexMain.java:235)
+ ... 2 common frames omitted
Verify Installation - run an Example
####################################
.. container:: paragraph
- You can now try to run apex.
+ Create a Tosca Policy for the SampleDomain example using ApexCliToscaEditor
+ as explained in the section "The APEX CLI Tosca Editor". Assume the tosca policy name is SampleDomain_tosca.json.
+ You can then try to run apex using the ToscaPolicy.
.. container:: listingblock
.. code::
: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)
+ # $APEX_HOME/bin/apexApps.sh engine -p $APEX_HOME/examples/SampleDomain_tosca.json (1)
+ >%APEX_HOME%\bin\apexApps.bat engine -p %APEX_HOME%\examples\SampleDomain_tosca.json(2)
.. container:: colist arabic
+-------+---------+
| **1** | UNIX |
+-------+---------+
- | **2** | Cygwin |
- +-------+---------+
- | **3** | Windows |
+ | **2** | Windows |
+-------+---------+
.. container:: paragraph
.. code::
: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] . . .
+ Starting Apex service with parameters [-p, /home/ubuntu/apex/SampleDomain_tosca.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 .
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:: | .. code:: |
-| :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 |
-| | } |
-+-------------------------------------------------------------+-------------------------------------------------------------+
++----------------------------------------------------------+----------------------------------------------------------+
+| Input Event | Example Output Event |
++==========================================================+==========================================================+
+| .. container:: | .. container:: |
+| | |
+| .. container:: content | .. container:: content |
+| | |
+| .. code:: | .. code:: |
+| :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
+Verify a Full Installation - REST Client
########################################
.. container:: paragraph
- APEX has a REST application for viewing policy models. The
+ APEX has a REST application for deploying, monitoring, and 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
+ the engine native policy language. Start the REST client as
follows.
.. container:: listingblock
.. code::
:number-lines:
- # $APEX_HOME/bin/apexApps.sh rest-editor
+ # $APEX_HOME/bin/apexApps.sh full-client
.. container:: listingblock
.. code::
:number-lines:
- >%APEX_HOME%\bin\apexApps.bat rest-editor
+ >%APEX_HOME%\bin\apexApps.bat full-client
.. 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
+ ``war`` web archive in it. Once the client is started, it will be
available on ``localhost:18989``. The last few line of the messages
should be:
.. code::
: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
+ Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
+ Jul 02, 2020 2:57:39 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
+ Jul 02, 2020 2:57:39 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/
+ Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: 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
+ browser to the started REST client. Click on the "Policy Editor" button and the Policy Editor start screen should appear.
.. container:: paragraph
``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
+ policy model used to verify the policy engine (see above).
.. container:: paragraph
- Now you can use the REST editor. To finish this verification, simply
+ Now you can use the Policy 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.
+ console where you started the Policy editor.
-Installing WAR Applications
----------------------------
+Installing the WAR Application
+------------------------------
.. 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).
+ The three APEX clients are packaged in a WAR file. This is a complete
+ application that can be installed and run in an application
+ server. The application is realized as a servlet. You
+ can find the WAR application in the `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/client/apex-client-full/>`__.
+
.. container:: paragraph
- Installing and using the WAR applications requires a web server
+ Installing and using the WAR application requires a web server
that can execute ``war`` web archives. We recommend to use `Apache
Tomcat <https://tomcat.apache.org/>`__, however other web servers
can be used as well.
.. container:: paragraph
- There are multiple ways to install the APEX WAR applications:
+ There are multiple ways to install the APEX WAR application:
.. container:: ulist
.. 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
+ The WAR application file has a name similar to *apex-client-full-<VERSION>.war*.
Running APEX in Docker
----------------------
Running APEX from the ONAP docker repository only requires 2
commands:
- .. container:: olist arabic
-
- #. Log into the ONAP docker repo
+ 1. Log into the ONAP docker repo
- .. container:: listingblock
+ .. container:: listingblock
- .. container:: content
+ .. container:: content
::
docker login -u docker -p docker nexus3.onap.org:10003
- .. container:: olist arabic
+ 2. Run the APEX docker image
- #. Run the APEX docker image
+ .. container:: listingblock
- .. container:: listingblock
-
- .. container:: content
+ .. container:: content
::
ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
WORKDIR /home/apexuser
+Running APEX in Standalone mode
+-------------------------------
+
+ .. container:: paragraph
+
+ APEX Engine can run in standalone mode by taking in a ToscaPolicy
+ as an argument and executing it.
+ Assume there is a tosca policy named ToscaPolicy.json in APEX_HOME directory
+ This policy can be executed in standalone mode using any of the below methods.
+
+Run in an APEX installation
+###########################
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+ :number-lines:
+
+ # $APEX_HOME/bin/apexApps.sh engine -p $APEX_HOME/ToscaPolicy.json(1)
+ >%APEX_HOME%\bin\apexApps.bat engine -p %APEX_HOME%\ToscaPolicy.json(2)
+
+.. container:: colist arabic
+
+ +-------+---------+
+ | **1** | UNIX |
+ +-------+---------+
+ | **2** | Windows |
+ +-------+---------+
+
+Run in a docker container
+#########################
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+ :number-lines:
+
+ # docker run -p 6969:6969 -v $APEX_HOME/ToscaPolicy.json:/tmp/policy/ToscaPolicy.json \
+ --name apex -it nexus3.onap.org:10001/onap/policy-apex-pdp:latest \
+ -c "/opt/app/policy/apex-pdp/bin/apexEngine.sh -p /tmp/policy/ToscaPolicy.json"
+
APEX Configurations Explained
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. container:: content
- |APEX Configuration Matrix|
+ .. image:: images/apex-intro/ApexEngineConfig.png
.. container:: title
"id" : 45, (3)
"instanceCount" : 4, (4)
"deploymentPort" : 12345, (5)
- "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)
+ "policy_type_impl" : {...}, (6)
"periodicEventPeriod": 1000, (7)
"engineParameters":{ (8)
"executorParameters":{...}, (9)
| | Websocket connection to the |
| | engine |
+-----------------------------------+-----------------------------------+
- | **6** | the model file to load into the |
- | | engine on startup (optional) |
+ | **6** | the APEX policy model as a JSON |
+ | | or YAML block to load into the |
+ | | engine on startup when |
+ | | APEX is running a policy that has |
+ | | its logic and parameters |
+ | | specified in TOSCA |
+ | | (optional) |
+-----------------------------------+-----------------------------------+
| **7** | an optional timer for periodic |
| | policies, in milliseconds (a |
| **18** | any other output configuration (e.g. event name filter, see below) |
+--------+--------------------------------------------------------------------+
+Event Name
+##########
+
+ .. container:: paragraph
+
+ Any event defined in APEX has to be unique. The "name" of
+ of an event is used as an identifier for an ApexEvent. Every
+ event has to be tagged to an eventName. This can be done in different
+ ways. Either the actual event can have a field called "name". Or, the
+ event has some other field that can act as the identifier, which can be
+ specified using "nameAlias". But in other cases, where a "name" or "nameAlias"
+ cannot be specified, the incoming event coming over an endpoint can be
+ manually tagged to an "eventName" before consuming it.
+
+ .. container:: paragraph
+
+ The "eventName" can have a single event's name if the event coming
+ over the endpoint has to be always mapped to the specified eventName's
+ definition. Otherwise, if different events can come over the endpoint,
+ then "eventName" field can consist of multiple event names separated by
+ "|" symbol. In this case, based on the received event's structure, it is
+ mapped to any one of the event name specified in the "eventName" field.
+
+ .. container:: paragraph
+
+ The following code shows some examples on how to specify the eventName field:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "eventInputParameters": {
+ "Input1": {
+ "carrierTechnologyParameters" : {...},
+ "eventProtocolParameters":{...},
+ "eventName" : "VesEvent" (1)
+ },
+ "Input2": {
+ "carrierTechnologyParameters" : {...},
+ "eventProtocolParameters":{...},
+ "eventName" : "AAISuccessResponseEvent|AAIFailureResponseEvent" (2)
+ }
+ }
+
Event Filters
#############
APEX provides plugins for each of the main areas.
-Configure AVRO Schema Handler
-#############################
+Configure Context Schema Handler
+################################
.. container:: paragraph
+ There are 2 choices available for defining schema: JSON & AVRO.
+ JSON based schemas are recommended because of the flexibility, better tooling & easier integration.
+
+ The JSON schema handler is added to the configuration as
+ follows:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "engineServiceParameters":{
+ "engineParameters":{
+ "contextParameters":{
+ "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
+ "schemaParameters":{
+ "Json":{
+ "parameterClassName" :
+ "org.onap.policy.apex.plugins.context.schema.json.JsonSchemaHelperParameters"
+ }
+ }
+ }
+ }
+ }
+
The AVRO schema handler is added to the configuration as
follows:
.. container:: content
- ::
+ ::
"carrierTechnologyParameters" : {
"carrierTechnology" : "FILE", (1)
"org.apache.kafka.common.serialization.StringDeserializer", (9)
"valueDeserializer" :
"org.apache.kafka.common.serialization.StringDeserializer" (10)
+ "kafkaProperties": [ (11)
+ [
+ "security.protocol",
+ "SASL_SSL"
+ ],
+ [
+ "ssl.truststore.type",
+ "JKS"
+ ],
+ [
+ "ssl.truststore.location",
+ "/opt/app/policy/apex-pdp/etc/ssl/test.jks"
+ ],
+ [
+ "ssl.truststore.password",
+ "policy0nap"
+ ],
+ [
+ "sasl.mechanism",
+ "SCRAM-SHA-512"
+ ],
+ [
+ "sasl.jaas.config",
+ "org.apache.kafka.common.security.scram.ScramLoginModule required username=\"policy\" password=\"policy\";"
+ ],
+ [
+ "ssl.endpoint.identification.algorithm",
+ ""
+ ]
+ ]
}
}
+--------+-------------------------------------+
| **10** | value for the Kafka de-serializer |
+--------+-------------------------------------+
+ | **11** | properties for Kafka connectivity |
+ +--------+-------------------------------------+
+
+ .. container:: paragraph
+
+ Kindly note that the above Kafka properties is just a reference,
+ and the actual properties required depends on the Kafka server installation.
Kafka Output
============
"org.apache.kafka.common.serialization.StringSerializer", (9)
"valueSerializer" :
"org.apache.kafka.common.serialization.StringSerializer" (10)
+ "kafkaProperties": [ (11)
+ [
+ "security.protocol",
+ "SASL_SSL"
+ ],
+ [
+ "ssl.truststore.type",
+ "JKS"
+ ],
+ [
+ "ssl.truststore.location",
+ "/opt/app/policy/apex-pdp/etc/ssl/test.jks"
+ ],
+ [
+ "ssl.truststore.password",
+ "policy0nap"
+ ],
+ [
+ "sasl.mechanism",
+ "SCRAM-SHA-512"
+ ],
+ [
+ "sasl.jaas.config",
+ "org.apache.kafka.common.security.scram.ScramLoginModule required username=\"policy\" password=\"policy\";"
+ ],
+ [
+ "ssl.endpoint.identification.algorithm",
+ ""
+ ]
+ ]
}
}
.. container:: colist arabic
- +--------+---------------------------------+
- | **1** | set Kafka as carrier technology |
- +--------+---------------------------------+
- | **2** | bootstrap server and port |
- +--------+---------------------------------+
- | **3** | acknowledgement strategy |
- +--------+---------------------------------+
- | **4** | number of retries |
- +--------+---------------------------------+
- | **5** | batch size |
- +--------+---------------------------------+
- | **6** | time to linger in milliseconds |
- +--------+---------------------------------+
- | **7** | buffer memory in byte |
- +--------+---------------------------------+
- | **8** | producer topic |
- +--------+---------------------------------+
- | **9** | key for the Kafka serializer |
- +--------+---------------------------------+
- | **10** | value for the Kafka serializer |
- +--------+---------------------------------+
+ +--------+-----------------------------------+
+ | **1** | set Kafka as carrier technology |
+ +--------+-----------------------------------+
+ | **2** | bootstrap server and port |
+ +--------+-----------------------------------+
+ | **3** | acknowledgement strategy |
+ +--------+-----------------------------------+
+ | **4** | number of retries |
+ +--------+-----------------------------------+
+ | **5** | batch size |
+ +--------+-----------------------------------+
+ | **6** | time to linger in milliseconds |
+ +--------+-----------------------------------+
+ | **7** | buffer memory in byte |
+ +--------+-----------------------------------+
+ | **8** | producer topic |
+ +--------+-----------------------------------+
+ | **9** | key for the Kafka serializer |
+ +--------+-----------------------------------+
+ | **10** | value for the Kafka serializer |
+ +--------+-----------------------------------+
+ | **11** | properties for Kafka connectivity |
+ +--------+-----------------------------------+
+
+ .. container:: paragraph
+
+ Kindly note that the above Kafka properties is just a reference,
+ and the actual properties required depends on the Kafka server installation.
JMS IO
-#######
+######
.. container:: paragraph
parameter to ``true``.
Websocket (WS) IO
-########################
+#################
.. container:: paragraph
"org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",
"parameters" : {
"url" : "http://example.org:8080/triggers/events", (2)
- "httpCodeFilter" : "[2][0-9][0-9]" (3)
+ "httpMethod": "GET", (3)
+ "httpCodeFilter" : "[2][0-9][0-9]", (4)
+ "httpHeaders" : [ (5)
+ ["Keep-Alive", "300"],
+ ["Cache-Control", "no-cache"]
+ ]
}
}
+-------+--------------------------------------------------+
| **2** | the URL of the HTTP server for events |
+-------+--------------------------------------------------+
- | **3** | use HTTP CODE FILTER for filtering status code |
+ | **3** | the HTTP method to use (GET/PUT/POST/DELETE), |
+ | | optional, defaults to GET |
+ +-------+--------------------------------------------------+
+ | **4** | use HTTP CODE FILTER for filtering status code, |
+ | | optional, defaults to [2][0-9][0-9] |
+ +-------+--------------------------------------------------+
+ | **5** | HTTP headers to use on the REST request, |
+ | | optional |
+-------+--------------------------------------------------+
REST Client Output
"parameters" : {
"url" : "http://example.com:8888/actions/events", (2)
"url" : "http://example.{site}.com:8888/{trig}/events", (2')
- "httpMethod" : "PUT" (3)
- }
+ "httpMethod" : "PUT". (3)
+ "httpHeaders" : [ (4)
+ ["Keep-Alive", "300"],
+ ["Cache-Control", "no-cache"]
+ ] }
}
.. container:: colist arabic
+-------+--------------------------------------------------+
| **2'**| the tagged URL of the HTTP server for events |
+-------+--------------------------------------------------+
- | **3** | use HTTP PUT (remove this line to use HTTP POST) |
+ | **3** | the HTTP method to use (GET/PUT/POST/DELETE), |
+ | | optional, defaults to POST |
+ +-------+--------------------------------------------------+
+ | **4** | HTTP headers to use on the REST request, |
+ | | optional |
+-------+--------------------------------------------------+
REST Server IO
</servlet>
REST Requestor IO
-##################
+#################
.. container:: paragraph
APEX can act as REST requestor on the input as well as on
the output interface. The media type is
``application/json``, so this plugin only works with
- the JSON Event protocol.
+ the JSON Event protocol. This plugin allows APEX to send REST requests
+ and to receive the reply of that request without tying up APEX resources
+ while the request is being processed. The REST Requestor pairs a REST
+ requestor producer and consumer together to handle the REST request
+ and response. The REST request is created from an APEX output event
+ and the REST response is input into APEX as a new input event.
-REST Requestor Input
-====================
+REST Requestor Output (REST Request Producer)
+=============================================
+
+ .. container:: paragraph
+
+ APEX sends a REST request when events are output by APEX, the REST
+ request configuration is specified on the REST Request Consumer (see
+ below).
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "carrierTechnologyParameters": {
+ "carrierTechnology": "RESTREQUESTOR", (1)
+ "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters"
+ },
+
+ .. container:: colist arabic
+
+ +-------+------------------------------------------+
+ | **1** | set REST requestor as carrier technology |
+ +-------+------------------------------------------+
+
+ .. container:: paragraph
+
+ The settings below are required on the producer to
+ define the event that triggers the REST request and
+ to specify the peered consumer configuration for the
+ REST request, for example:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code::
+
+ "eventNameFilter": "GuardRequestEvent", (1)
+ "requestorMode": true, (2)
+ "requestorPeer": "GuardRequestorConsumer", (3)
+ "requestorTimeout": 500 (4)
+
+ .. container:: colist arabic
+
+ +-------+-------------------------------------------+
+ | **1** | a filter on the event |
+ +-------+-------------------------------------------+
+ | **2** | requestor mode must be set to *true* |
+ +-------+-------------------------------------------+
+ | **3** | the peered consumer for REST requests, |
+ | | that consumer specifies the full |
+ | | configuration for REST requests |
+ +-------+-------------------------------------------+
+ | **4** | the request timeout in milliseconds, |
+ | | overridden by timeout on consumer if that |
+ | | is set, optional defaults to 500 |
+ | | millisconds |
+ +-------+-------------------------------------------+
+
+REST Requestor Input (REST Request Consumer)
+============================================
.. container:: paragraph
- APEX will connect to a given URL to request an input.
+ APEX will connect to a given URL to issue a REST request and
+ wait for a REST response.
The URL can be configured statically or tagged
as ``?example.{site}.org:8080/{trig}/events``,
all tags such as ``site`` and ``trig`` in the URL
"url": "http://localhost:54321/some/path/to/rest/resource", (2)
"url": "http://localhost:54321/{site}/path/to/rest/{resValue}", (2')
"httpMethod": "POST", (3)
- "restRequestTimeout": 2000, (4)
- "httpCodeFilter" : "[2][0-9][0-9]" (5)
- }
+ "requestorMode": true, (4)
+ "requestorPeer": "GuardRequestorProducer", (5)
+ "restRequestTimeout": 2000, (6)
+ "httpCodeFilter" : "[2][0-9][0-9]" (7)
+ "httpHeaders" : [ (8)
+ ["Keep-Alive", "300"],
+ ["Cache-Control", "no-cache"]
+ ] }
},
.. container:: colist arabic
+-------+--------------------------------------------------+
| **2'**| the tagged URL of the HTTP server for events |
+-------+--------------------------------------------------+
- | **3** | use HTTP PUT (remove this line to use HTTP POST) |
+ | **3** | the HTTP method to use (GET/PUT/POST/DELETE), |
+ | | optional, defaults to GET |
+ +-------+--------------------------------------------------+
+ | **4** | requestor mode must be set to *true* |
+-------+--------------------------------------------------+
- | **4** | request timeout in milliseconds |
+ | **5** | the peered producer for REST requests, that |
+ | | producer specifies the APEX output event that |
+ | | triggers the REST request |
+-------+--------------------------------------------------+
- | **5** | use HTTP CODE FILTER for filtering status code |
+ | **6** | request timeout in milliseconds, overrides any |
+ | | value set in the REST Requestor Producer, |
+ | | optional, defaults to 500 millisconds |
+ +-------+--------------------------------------------------+
+ | **7** | use HTTP CODE FILTER for filtering status code |
+ | | optional, defaults to [2][0-9][0-9] |
+ +-------+--------------------------------------------------+
+ | **8** | HTTP headers to use on the REST request, |
+ | | optional |
+-------+--------------------------------------------------+
.. container:: paragraph
- Further settings are required on the consumer to
- define the event that is requested, for example:
+ Further settings may be required on the consumer to
+ define the input event that is produced and forwarded into
+ APEX, for example:
.. container:: listingblock
.. code::
"eventName": "GuardResponseEvent", (1)
- "eventNameFilter": "GuardResponseEvent", (2)
- "requestorMode": true, (3)
- "requestorPeer": "GuardRequestorProducer", (4)
- "requestorTimeout": 500 (5)
+ "eventNameFilter": "GuardResponseEvent" (2)
.. container:: colist arabic
+-------+---------------------------+
| **2** | a filter on the event |
+-------+---------------------------+
- | **3** | the mode of the requestor |
- +-------+---------------------------+
- | **4** | a peer for the requestor |
- +-------+---------------------------+
- | **5** | a general request timeout |
- +-------+---------------------------+
-
-REST Requestor Output
-=====================
-
- .. container:: paragraph
-
- APEX will connect to a given URL to send events, but
- not receive any events.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters": {
- "carrierTechnology": "RESTREQUESTOR", (1)
- "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters"
- },
-
- .. container:: colist arabic
-
- +-------+------------------------------------------+
- | **1** | set REST requestor as carrier technology |
- +-------+------------------------------------------+
-
- .. container:: paragraph
-
- Further settings are required on the consumer to
- define the event that is requested, for example:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventNameFilter": "GuardRequestEvent", (1)
- "requestorMode": true, (2)
- "requestorPeer": "GuardRequestorConsumer", (3)
- "requestorTimeout": 500 (4)
-
- .. container:: colist arabic
-
- +-------+---------------------------+
- | **1** | a filter on the event |
- +-------+---------------------------+
- | **2** | the mode of the requestor |
- +-------+---------------------------+
- | **3** | a peer for the requestor |
- +-------+---------------------------+
- | **4** | a general request timeout |
- +-------+---------------------------+
gRPC IO
#######
"id" : 45,
"instanceCount" : 4,
"deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/some-model.json",
"engineParameters" : {
"executorParameters" : {
"JAVASCRIPT" : {
.. container:: paragraph
- The APEX engine comes with a few CLI arguments for setting
- configuration and policy model. The configuration file is
- always required. The policy model file is only required if
- no model file is specified in the configuration, or if the
- specified model file should be over written. The option
- ``-h`` prints a help screen.
+ The APEX engine comes with a few CLI arguments, the main one is for setting
+ the tosca policy file for execution. The tosca policy file is
+ always required. The option ``-h`` prints a help screen.
.. container:: listingblock
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
+ -p,--tosca-policy-file <TOSCA_POLICY_FILE> the full path to the ToscaPolicy file to use.
+ -h,--help outputs the usage of this command
+ -v,--version outputs the version of Apex
The APEX CLI Editor
-------------------
%APEX_HOME%/\bin/\apexCLIToscaEditor.bat -c %APEX_HOME%\examples\PolicyModel.apex -ot %APEX_HOME%\examples\test.json -l %APEX_HOME%\examples\test.log -ac %APEX_HOME%\examples\RESTServerStandaloneJsonEvent.json -t %APEX_HOME%\examples\ToscaTemplate.json
-The APEX REST Editor
---------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX REST Editor is via an
- installation of the *war* file on a webserver. However, the
- REST editor can also be started via command line. This will
- start a Grizzly webserver with the *war* deployed. Access to
- the REST Editor is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexRESTEditor.sh`` - simply starts the webserver with
- the REST editor
-
- - ``apexApps.sh rest-editor`` - simply starts the webserver
- with the REST editor
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexRESTEditor.bat`` - simply starts the webserver with
- the REST editor
-
- - ``apexApps.bat rest-editor`` - simply starts the
- webserver with the REST editor
-
- .. container:: paragraph
-
- Summary of alternatives to start the APEX REST Editor:
-
- +-------------------------------------------------------------+---------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=============================================================+===============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexRESTEditor.sh.sh [args] | > %APEX_HOME%\bin\apexRESTEditor.bat [args] |
- | # $APEX_HOME/bin/apexApps.sh rest-editor [args] | > %APEX_HOME%\bin\apexApps.bat rest-editor [args] |
- +-------------------------------------------------------------+---------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...]
- -h,--help outputs the usage of this command
- -l,--listen <ADDRESS> the IP address to listen on. Default value is localhost to restrict access to the
- local machine only.
- -p,--port <PORT> port to use for the Apex RESTful editor REST calls.
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default
- value is -1 to run indefinitely.
-
- .. container:: paragraph
-
- If the REST Editor is started without any arguments the
- final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- 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 11:24:30 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:24:30 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
-
- The last line states the URL on which the REST Editor can be
- accessed. The example above stated
- ``http://0.0.0.0:18989/apex/``. In a web browser use the URL
- ``http://localhost:18989`` and the REST Editor will start.
-
-The APEX Monitoring Client
---------------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX Monitoring Client is via an
- installation of the *war* file on a webserver. However, the
- Monitoring Client can also be started via command line. This
- will start a Grizzly webserver with the *war* deployed.
- Access to the Monitoring Client is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexApps.sh eng-monitoring`` - simply starts the
- webserver with the Monitoring Client
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat eng-monitoring`` - simply starts the
- webserver with the Monitoring Client
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...]
- -h,--help outputs the usage of this command
- -p,--port <PORT> port to use for the Apex Services REST calls
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
-
- .. container:: paragraph
-
- If the Monitoring Client is started without any arguments
- the final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
-
- The last line states the URL on which the Monitoring Client
- can be accessed. The example above stated
- ``http://localhost:18989/apexservices``. In a web browser
- use the URL ``http://localhost:18989``.
-
-The APEX Deployment Client
---------------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX Deployment Client is via an
- installation of the *war* file on a webserver. However, the
- Deployment Client can also be started via command line. This
- will start a Grizzly webserver with the *war* deployed.
- Access to the Deployment Client is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexApps.sh eng-deployment`` - simply starts the
- webserver with the Deployment Client
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat eng-deployment`` - simply starts the
- webserver with the Deployment Client
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...]
- -h,--help outputs the usage of this command
- -p,--port <PORT> port to use for the Apex Services REST calls
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
-
- .. container:: paragraph
-
- If the Deployment Client is started without any arguments
- the final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
- The last line states the URL on which the Deployment Client
- can be accessed. The example above stated
- ``http://localhost:18989/apexservices``. In a web browser
- use the URL ``http://localhost:18989``.
-
-The APEX Full Client
---------------------
+The APEX Client
+---------------
.. container:: paragraph
- The APEX Full Client combines the REST Editor, the
+ The APEX Client combines the Policy Editor, the
Monitoring Client, and the Deployment Client into a single
application. The standard way to use the APEX Full Client is
via an installation of the *war* file on a webserver.
.. container:: paragraph
- The standard applications (Engine, CLI Editor, REST Editor)
+ The standard applications (Engine and CLI Editor)
come with dedicated start scripts. For all other APEX
applications, we provide an application launcher.
</logger>
</configuration>
+Unsupported Features
+^^^^^^^^^^^^^^^^^^^^
+
+ .. container:: paragraph
+
+ This section documents some legacy and unsupported features
+ in apex-pdp. The documentation here has not been updated for
+ recent versions of apex-pdp. For example, the apex-pdp models
+ specified in this example should now be in TOSCA format.
+
Building a System with Websocket Backend
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------
Websockets
-----------
+##########
.. container:: paragraph
does not support WAMP at the moment.
Websocket in Java
------------------
+#################
.. container:: paragraph
Netty, … there are also Kafka extensions for Websockets.
Websocket Example Code for Websocket clients (FOSS)
----------------------------------------------------
+###################################################
.. container:: paragraph
example <http://www.programmingforliving.com/2013/08/jsr-356-java-api-for-websocket-client-api.html>`__
BCP: Websocket Configuration
-----------------------------
+############################
.. container:: paragraph
reconnected manually after an APEX boot.
Demo with VPN Policy Model
---------------------------
+##########################
.. container:: paragraph
in an editor (we need to send those events to APEX)
A Websocket Configuration for the VPN Domain
-############################################
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. container:: paragraph
}
Start APEX Engine
-#################
+^^^^^^^^^^^^^^^^^
.. container:: paragraph
.. code::
:number-lines:
- #: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json
+ #: $APEX_HOME/bin/apexApps.sh engine -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json
.. container:: listingblock
.. code::
:number-lines:
- #: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json
+ #: %APEX_HOME%\bin\apexApps.bat engine -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json
.. container:: paragraph
policy is triggered/executed.
Run the Websocket Echo Client
-#############################
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. container:: paragraph
ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake)
Run the Websocket Console Client
-################################
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. container:: paragraph
ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake)
Send Events
-###########
+^^^^^^^^^^^
.. container:: paragraph
(APEX). This will also terminate the echo-client in Terminal 2. Then
type ``exit<enter>`` in Terminal 3 (or ``CTRL+C``) to terminate the
console-client.
-
-.. 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
-.. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
-
-