diff options
| -rw-r--r-- | docs/apex/APEX-Developer-Guide.rst | 122 | ||||
| -rw-r--r-- | docs/apex/APEX-Install-Guide.rst | 86 | ||||
| -rw-r--r-- | docs/apex/APEX-Introduction.rst | 12 | ||||
| -rw-r--r-- | docs/apex/APEX-OnapPf-Guide.rst | 4 | ||||
| -rw-r--r-- | docs/apex/APEX-Policy-Guide.rst | 98 | ||||
| -rw-r--r-- | docs/apex/APEX-User-Manual.rst | 444 | ||||
| -rw-r--r-- | docs/distribution/Distribution-User-Manual.rst | 10 |
7 files changed, 388 insertions, 388 deletions
diff --git a/docs/apex/APEX-Developer-Guide.rst b/docs/apex/APEX-Developer-Guide.rst index d5f16d56..b247ab83 100644 --- a/docs/apex/APEX-Developer-Guide.rst +++ b/docs/apex/APEX-Developer-Guide.rst @@ -52,10 +52,10 @@ Introduction to building APEX .. container:: paragraph - One all requirements are in place, APEX can be build. + 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 build in a standard way with + *profile*. APEX can also be built in a standard way with standard tests (``mvn clean install``) or without standard tests (``mvn clean install -DskipTests``). @@ -73,26 +73,26 @@ Introduction to building 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:: + A Build requires ONAP Nexus + APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current + settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__. + + .. important:: + + A Build needs Space + Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full + distribution and 1-2 GB for the downloaded dependencies + + .. important:: + A Build requires Internet (for first build to download all dependencies and plugins) + During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven + repository. The first standard build (and any first specific build) requires Internet access to download those + dependencies. + + .. important:: Building RPM distributions - RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` - run ``sudo apt-get install rpm``, then build APEX. + 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 -------------- @@ -146,7 +146,7 @@ Standard Build 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. + directory and how it should look. +-----------------------------------------------------------------------------------------------------------------------------+ | Unix, Cygwin | @@ -242,7 +242,7 @@ Checkstyle with Maven .. container:: content - .. code:: bash + .. code:: bash mvn checkstyle:checkstyle -DapexAll @@ -251,13 +251,13 @@ Build with standard Tests .. container:: paragraph - Use Maven to for a standard build with standard tests. + Use Maven for a standard build with standard tests. - .. important:: + .. 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. + 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 | @@ -279,10 +279,10 @@ Build with standard Tests The build takes about 10 minutes with tests on a standard development laptop. It should run through without errors, but with a lot of - messages from the build process. If build with tests (i.e. without + 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 - successful. + successfully. Build with all Tests -------------------- @@ -291,17 +291,17 @@ Build with all Tests Use Maven to for a standard build with *all* tests. - .. important:: + .. 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. + 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:: + .. 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. + 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 | @@ -324,12 +324,12 @@ Build with all Components .. container:: paragraph A standard APEX build will not build all components. Some parts - are for specific deployments, only. Use Maven to for a standard + are for specific deployments, only. Use Maven for a standard build with *all* components. - .. important:: + .. important:: Might require specific software. - When building all components, some modules require specific software installed on the build machine. + When building all components, some modules require specific software to be installed on the build machine. +----------------------------------------------+----------------------------------------------+ | Unix, Cygwin | Windows | @@ -352,15 +352,15 @@ Build the APEX Documentation .. container:: paragraph - The APEX Maven build also includes stand-alone documentations, + 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 - options ``-N`` prevents Maven to go through all APEX modules, + 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 build, copy the *HTML* and *PDF* + Once the documentation is built, copy the *HTML* and *PDF* documents to a folder of choice +-------------------------------------------------------+--------------------------------------------------------+ @@ -400,11 +400,11 @@ Build APEX Site Once the web site is staged, copy the full site to a folder of choice or into a web server. - .. important:: + .. 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). + 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 @@ -450,7 +450,7 @@ Build APEX Site #. Next run a simple install without tests - #. Now generate the APEX stand -alone documentation, they are in + #. 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 @@ -577,7 +577,7 @@ Java coding Rules - Javadoc for *all* methods - - All project must build with all tests on Unix, Windows, + - All projects must build with all tests on Unix, Windows, *and* Cygwin .. container:: ulist @@ -651,7 +651,7 @@ Configure Eclipse .. container:: olist arabic - #. Eclipse Window Preferences Java Code Style + #. Eclipse Window Preferences Java Code Style Clean Up → Import… #. Select your template file @@ -661,7 +661,7 @@ Configure Eclipse .. container:: olist arabic - #. Eclipse Window Preferences Java Code Style + #. Eclipse Window Preferences Java Code Style Code Templates → Import… #. Select your templates file @@ -680,7 +680,7 @@ Configure Eclipse .. container:: olist arabic - #. Eclipse Window Preferences Java Code Style + #. Eclipse Window Preferences Java Code Style Formatter → Import… #. Select your formatter profile file @@ -1012,8 +1012,8 @@ Using JAutodoc package to do all files) and right click JAutodoc Add Header - #. To add JAutodoc stubs to a files, select on a file (or on - the package to do all files) and right click JAutodoc + #. 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 @@ -1091,7 +1091,7 @@ Disable Eclipse Formatting (partially) #. Ensure that Off/On Tags are enabled in Eclipse - #. In Eclipse Window Preferences Java Code Style + #. In Eclipse Window Preferences Java Code Style Formatter window press Edit… #. Click on the *Off/On Tags* tab @@ -1180,7 +1180,7 @@ CLI Example .. container:: paragraph - No use the provided ``CliOptions`` and ``CliParser``. + 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): @@ -1383,12 +1383,12 @@ Autoversioning an Application .. container:: paragraph - The APEX utilities project provides means to versioning an - application automatically towards the APEX version it is written - for. This is realized by generating a file called + 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 mthod to + full APEX distribution. The CLI Parser here provides a method to access this version for an application. .. container:: paragraph diff --git a/docs/apex/APEX-Install-Guide.rst b/docs/apex/APEX-Install-Guide.rst index 3ac1eb23..92b96565 100644 --- a/docs/apex/APEX-Install-Guide.rst +++ b/docs/apex/APEX-Install-Guide.rst @@ -158,28 +158,28 @@ Build APEX - 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>`__. + 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 + 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. + 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 build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, - then build APEX. + 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 to for a standard build without any tests. + Use Maven for a standard build without any tests. +-------------------------------------------------------+--------------------------------------------------------+ | Unix, Cygwin | Windows | @@ -232,7 +232,7 @@ Build APEX 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. + directory and how it should look. +----------------------------------------------------------------------------------------------------------------------------+ | Unix, Cygwin | @@ -365,9 +365,9 @@ Install with RPM and DPKG | .. container:: content | | | | .. code:: bash | -| :number-lines: | +| :number-lines: | | | -| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| # 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 ... | @@ -427,7 +427,7 @@ Install Manually from Archive (Windows, 7Zip, GUI) .. container:: content |Extract the TAR archive| - + .. container:: paragraph The right-click on the new created TAR file and extract the actual @@ -490,18 +490,18 @@ Build and Install Manually (Unix, Windows, Cygwin) 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 copying manually). + ``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. + .. 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 safe some time. It - assumes that the APX GIT repositories are cloned to: + without tests (``-DskipTests``) to save some time. It + assumes that the APEX GIT repositories are cloned to: .. container:: ulist @@ -509,7 +509,7 @@ Build and Install Manually (Unix, Windows, Cygwin) - Windows: ``C:\dev\apex`` - +-------------------------------------------------------+--------------------------------------------------------+ + +-------------------------------------------------------+--------------------------------------------------------+ | Unix, Cygwin | Windows | +=======================================================+========================================================+ | .. container:: | .. container:: | @@ -529,9 +529,9 @@ Build and Install Manually (Unix, Windows, Cygwin) 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 - build with tests (i.e. without ``-DskipTests``), there will be error + 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 successful. + long as the build finishes successfully. .. container:: paragraph @@ -782,7 +782,7 @@ Environment Settings: APEX_HOME and APEX_USER .. container:: ulist - - ``APEX_USER`` with the user under whos name and permission APEX + - ``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, @@ -791,7 +791,7 @@ Environment Settings: APEX_HOME and APEX_USER .. container:: paragraph The first row in the following table shows how to set these - environment variables temporary (assuming the user is + 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. @@ -807,7 +807,7 @@ Environment Settings: APEX_HOME and APEX_USER | | | | # 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` | | + | # export APEX_HOME=`pwd` | | | | | +------------------------------------------------+ | | .. container:: | | @@ -819,7 +819,7 @@ Environment Settings: APEX_HOME and APEX_USER | | | | # setenv APEX_USER apexuser | | | # cd /opt/app/policy/apex-pdp | | - | # setenv APEX_HOME `pwd` | | + | # setenv APEX_HOME `pwd` | | | | | +------------------------------------------------+---------------------------------------------------------+ | .. container:: | .. container:: | @@ -831,7 +831,7 @@ Environment Settings: APEX_HOME and APEX_USER | | | | # 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 | | + | # APEX_HOME=/opt/app/policy/apex-pdp | | | | | +------------------------------------------------+---------------------------------------------------------+ @@ -841,7 +841,7 @@ Making Environment Settings Permanent (Unix, Cygwin) .. container:: paragraph - For a per-user setting, edit the a user’s ``bash`` or ``tcsh`` + 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). @@ -941,9 +941,9 @@ Create Directories for Logging .. container:: paragraph Make sure that the log directory exists. This is important when - APEX was installed manually or when the log directory was changed + APEX is installed manually or when the log directory is changed in the settings (see above). - + +------------------------------------------------------------------+-------------------------------------------------------+ | Unix, Cygwin | Windows | +==================================================================+=======================================================+ @@ -1029,9 +1029,9 @@ Verify Installation - run an Example .. 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) + # $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 @@ -1046,7 +1046,7 @@ Verify Installation - run an Example .. container:: paragraph The engine should start successfully. Assuming the logging levels are - not change (default level is ``info``), the output should look + not changed (default level is ``info``), the output should look similar to this (last few lines) .. container:: listingblock @@ -1073,7 +1073,7 @@ Verify Installation - run an Example .. container:: paragraph - Important are the last two line, stating that APEX has added the + 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 @@ -1085,7 +1085,7 @@ Verify Installation - run an Example .. container:: paragraph The following table shows an input event in the left column and an - output event in the right column. Past the input event into the + 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. @@ -1233,7 +1233,7 @@ Installing WAR Applications .. container:: paragraph Installing and using the WAR applications requires a web server - that can execute ``war`` web archives. We recommend to use + that can execute ``war`` web archives. We recommend using `Apache Tomcat <https://tomcat.apache.org/>`__, however other web servers can be used as well. @@ -1264,7 +1264,7 @@ Installing WAR Applications 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 installed an APEX WAR application (and wait for + 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. diff --git a/docs/apex/APEX-Introduction.rst b/docs/apex/APEX-Introduction.rst index 90dd9e74..b13e335e 100644 --- a/docs/apex/APEX-Introduction.rst +++ b/docs/apex/APEX-Introduction.rst @@ -85,7 +85,7 @@ Introduction to APEX information that is provided by other systems. APEX keeps context coordinated across all the the instances running a particular policy. If a policy running in an APEX engine - changes the value of a piece of context, that value is is + changes the value of a piece of context, that value is available to all other APEX engines that use that piece of context. APEX takes care of distribution, locking, writing of context to persistent storage, and monitoring of context. @@ -125,11 +125,11 @@ APEX Configuration An APEX engine can be configured to use various combinations of event input handlers, event output handlers, event protocols, context handlers, and logic executors. The system - is build using a plugin architecture. Each configuration + is built using a plugin architecture. Each configuration option is realized by a plugin, which can be loaded and configured when the engine is started. New plugins can be added to the system at any time, though to benefit from a - new plugin an engine will need to be restarted. + new plugin, an engine will need to be restarted. .. container:: imageblock @@ -157,7 +157,7 @@ APEX Policy Matrix APEX offers a lot of flexibility for defining, deploying, and executing policies. Based on a theoretic model, it - supports virtually any policy model and allows to translate + supports virtually any policy model and supports translation of legacy policies into the APEX execution format. However, the most important aspect for using APEX is to decide what policy is needed, what underlying policy concepts should be @@ -222,7 +222,7 @@ APEX Policy Matrix - Feedback, i.e. why did something happen or not happen. Similar to analysis, but here the feedback will be in the - input event and the policy needs to something with that + input event and the policy needs to do something with that information. Feedback can be related to history or experience, for instance a previous policy execution. The policy needs to be context-aware or be a meta-policy. @@ -255,7 +255,7 @@ APEX Policy Matrix additional information of any kind but cannot change/alter them - - Global context (read and write), the policy the policy + - Global context (read and write), the policy has access to additional information of any kind and can alter this information (for instance to record historic information) diff --git a/docs/apex/APEX-OnapPf-Guide.rst b/docs/apex/APEX-OnapPf-Guide.rst index c9083477..3ff2062a 100644 --- a/docs/apex/APEX-OnapPf-Guide.rst +++ b/docs/apex/APEX-OnapPf-Guide.rst @@ -400,10 +400,10 @@ Format of the configuration file (OnapPfConfig.json) explained | | For e.g. dmaap, noop, ueb | +-----------------------------------+-----------------------------------+ | **10** | List of topics' details to which | - | | messages are sent to. | + | | messages are sent. | +-----------------------------------+-----------------------------------+ | **11** | Topic name of the sink to which | - | | PDP-A sends messages to. | + | | PDP-A sends messages. | +-----------------------------------+-----------------------------------+ | **12** | List of servers for the sink | | | topic. | diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst index 392f31c7..dc4f2bbe 100644 --- a/docs/apex/APEX-Policy-Guide.rst +++ b/docs/apex/APEX-Policy-Guide.rst @@ -18,8 +18,8 @@ APEX Policy Matrix APEX offers a lot of flexibility for defining, deploying, and executing policies. Based on a theoretic model, it - supports virtually any policy model and allows to - translate legacy policies into the APEX execution format. + supports virtually any policy model and supports + translation of legacy policies into the APEX execution format. However, the most important aspect for using APEX is to decide what policy is needed, what underlying policy concepts should be used, and how the decision logic @@ -868,19 +868,19 @@ Writing APEX Task Logic attempt to teach you about the scripting languages themselves … that is up to you! - .. tip:: - JVM-based scripting languages - For more more information on scripting for the Java platform see: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html + .. tip:: + JVM-based scripting languages + For more more information on scripting for the Java platform see: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html - .. note:: - What do Tasks do? - The function of an Apex Task is to provide the logic that can be executed for an Apex State as one of the steps in - an Apex Policy. Each task receives some *incoming fields*, executes some logic (e.g: make a decision based on - *shared state* or *context*, *incoming fields*, *external context*, etc.), perhaps set some *shared state* or - *context* and then emits *outgoing fields*. The state that uses the task is responsible for extracting the - *incoming fields* from the state input event. The state also has an *output mapper* associated with the task, and - this *output mapper* is responsible for mapping the *outgoing fields* from the task into an appropriate - output event for the state. + .. note:: + What do Tasks do? + The function of an Apex Task is to provide the logic that can be executed for an Apex State as one of the steps in + an Apex Policy. Each task receives some *incoming fields*, executes some logic (e.g: make a decision based on + *shared state* or *context*, *incoming fields*, *external context*, etc.), perhaps set some *shared state* or + *context* and then emits *outgoing fields*. The state that uses the task is responsible for extracting the + *incoming fields* from the state input event. The state also has an *output mapper* associated with the task, and + this *output mapper* is responsible for mapping the *outgoing fields* from the task into an appropriate + output event for the state. .. container:: paragraph @@ -988,7 +988,7 @@ Writing APEX Task Logic .. container:: content - .. code:: javascript + .. code:: javascript :number-lines: /* @@ -1094,14 +1094,14 @@ Writing APEX Task Logic and exit. .. note:: - How to return a value from task logic - Some languages explicitly support returning values from the script (e.g. MVEL and JRuby) using an explicit - return statement (e.g. ``return true``), other languages do not (e.g. JavaScript and Jython). For - languages that do not support the ``return`` statement, a special field called ``returnValue`` must be - created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean`` - value to the ``returnValue`` field before completing the task). - Also, in MVEL if there is no explicit return statement then the return value of the last executed statement will return - (e.g. the statement a=(1+2) will return the value 3). + How to return a value from task logic + Some languages explicitly support returning values from the script (e.g. MVEL and JRuby) using an explicit + return statement (e.g. ``return true``), other languages do not (e.g. JavaScript and Jython). For + languages that do not support the ``return`` statement, a special field called ``returnValue`` must be + created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean`` + value to the ``returnValue`` field before completing the task). + Also, in MVEL if there is no explicit return statement then the return value of the last executed statement will return + (e.g. the statement a=(1+2) will return the value 3). .. container:: paragraph @@ -1116,7 +1116,7 @@ Writing APEX Task Logic ``executor`` keyword in MVEL): Table 1. The ``executor`` Fields / Methods - + +------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ | Name | Type | Java type | Description | +============+=============+================================+=====================================================================================+ @@ -1308,21 +1308,21 @@ Writing APEX Task Selection Logic the scripting languages themselves … that is up to you! .. tip:: - JVM-based scripting languages - For more more information on Scripting for the Java platform see: - https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html - - .. note:: - What does Task Selection Logic do? - When an Apex state references multiple tasks, there must be a way to dynamically decide - which task should be chosen and executed. This can depend on the many factors, e.g. the - *incoming event for the state*, *shared state* or *context*, *external context*, - etc.. This is the function of a state’s Task Selection Logic. Obviously, if there is - only one task then Task only one task then Task Selection Logic is not needed. - Each state must also select one of the tasks a the *default state*. If the Task - Selection Logic is unable to select an appropriate task, then it should select the - *default task*. Once the task has been selected the Apex Engine will then execute that - task. + JVM-based scripting languages + For more more information on Scripting for the Java platform see: + https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html + + .. note:: + What does Task Selection Logic do? + When an Apex state references multiple tasks, there must be a way to dynamically decide + which task should be chosen and executed. This can depend on the many factors, e.g. the + *incoming event for the state*, *shared state* or *context*, *external context*, + etc.. This is the function of a state’s Task Selection Logic. Obviously, if there is + only one task then Task only one task then Task Selection Logic is not needed. + Each state must also select one of the tasks a the *default state*. If the Task + Selection Logic is unable to select an appropriate task, then it should select the + *default task*. Once the task has been selected the Apex Engine will then execute that + task. .. container:: paragraph @@ -1406,15 +1406,15 @@ Writing APEX Task Selection Logic be returned, but this will cause the policy invoking this task will fail and exit. - .. note:: + .. note:: How to return a value from Task Selection Logic - Some languages explicitly support returning values from the script (e.g. MVEL and - JRuby) using an explicit return statement (e.g. ``return true``), other languages do not (e.g. - JavaScript and Jython). For languages that do not support the ``return`` statement, a special field called - ``returnValue`` must be created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean`` - value to the ``returnValue`` field before completing the task). - Also, in MVEL if there is not explicit return statement then the return value of the last executed statement will - return (e.g. the statement a=(1+2) will return the value 3). + Some languages explicitly support returning values from the script (e.g. MVEL and + JRuby) using an explicit return statement (e.g. ``return true``), other languages do not (e.g. + JavaScript and Jython). For languages that do not support the ``return`` statement, a special field called + ``returnValue`` must be created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean`` + value to the ``returnValue`` field before completing the task). + Also, in MVEL if there is not explicit return statement then the return value of the last executed statement will + return (e.g. the statement a=(1+2) will return the value 3). .. container:: paragraph @@ -1922,7 +1922,7 @@ Create a instance of an Context Album entry using Schemas .. container:: content - .. code:: javascript + .. code:: javascript var albumProblemMap = executor.getContextAlbum("albumProblemMap"); var linkProblem = albumProblemMap.getSchemaHelper().createNewInstance(); @@ -1940,7 +1940,7 @@ Create a instance of an Context Album entry using Schemas .. container:: content - .. code:: javascript + .. code:: javascript var linkProblem = executor.getContextAlbum("albumProblemMap").getSchemaHelper().createNewInstance(); diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index 01f74fab..97abd095 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -135,7 +135,7 @@ Get the APEX Source Code .. container:: content - .. code:: + .. code:: :number-lines: git clone https://gerrit.onap.org/r/policy/apex-pdp @@ -156,26 +156,26 @@ Build APEX - Cygwin: ``/cygdrive/c/dev/apex-pdp`` - .. important:: + .. 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>`__. + 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 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:: + .. 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. + 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:: + .. 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. + 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 @@ -211,7 +211,7 @@ Build APEX .. container:: content - .. code:: + .. code:: :number-lines: [INFO] tools .............................................. SUCCESS [ 0.248 s] @@ -365,9 +365,9 @@ Install with RPM and DPKG | .. container:: content | | | | .. code:: | -| :number-lines: | +| :number-lines: | | | -| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| # 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 ... | @@ -402,7 +402,7 @@ Install Manually from Archive (Unix, Cygwin) .. container:: content - .. code:: + .. code:: :number-lines: # cd /opt @@ -466,7 +466,7 @@ Install Manually from Archive (Windows, 7Zip, CMD) .. container:: content - .. code:: + .. code:: :number-lines: >c: @@ -492,10 +492,10 @@ Build and Install Manually (Unix, Windows, Cygwin) 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. + .. 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 @@ -509,7 +509,7 @@ Build and Install Manually (Unix, Windows, Cygwin) - Windows: ``C:\dev\apex`` - +-------------------------------------------------------+--------------------------------------------------------+ + +-------------------------------------------------------+--------------------------------------------------------+ | Unix, Cygwin | Windows | +=======================================================+========================================================+ | .. container:: | .. container:: | @@ -542,7 +542,7 @@ Build and Install Manually (Unix, Windows, Cygwin) .. container:: content - .. code:: + .. code:: :number-lines: [INFO] tools .............................................. SUCCESS [ 0.248 s] @@ -760,7 +760,7 @@ APEX User and Group .. container:: content - .. code:: + .. code:: :number-lines: # sudo groupadd apexuser @@ -807,19 +807,19 @@ Environment Settings: APEX_HOME and APEX_USER | | | | # 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` | | + | # export APEX_HOME=`pwd` | | | | | +------------------------------------------------+ | | .. container:: | | | | | | .. container:: content | | | | | - | .. code:: tcsh | | + | .. code::tcsh | | | :number-lines: | | | | | | # setenv APEX_USER apexuser | | | # cd /opt/app/policy/apex-pdp | | - | # setenv APEX_HOME `pwd` | | + | # setenv APEX_HOME `pwd` | | | | | +------------------------------------------------+---------------------------------------------------------+ | .. container:: | .. container:: | @@ -831,7 +831,7 @@ Environment Settings: APEX_HOME and APEX_USER | | | | # 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 | | + | # APEX_HOME=/opt/app/policy/apex-pdp | | | | | +------------------------------------------------+---------------------------------------------------------+ @@ -981,7 +981,7 @@ Verify Installation - run Engine .. container:: content - .. code:: + .. code:: :number-lines: Starting Apex service with parameters [] . . . @@ -1021,12 +1021,12 @@ Verify Installation - run an Example .. container:: content - .. code:: + .. 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/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 @@ -1048,7 +1048,7 @@ Verify Installation - run an Example .. container:: content - .. code:: + .. 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] . . . @@ -1134,7 +1134,7 @@ Verify a Full Installation - REST Editor .. container:: content - .. code:: + .. code:: :number-lines: # $APEX_HOME/bin/apexApps.sh rest-editor @@ -1143,7 +1143,7 @@ Verify a Full Installation - REST Editor .. container:: content - .. code:: + .. code:: :number-lines: >%APEX_HOME%\bin\apexApps.bat rest-editor @@ -1160,7 +1160,7 @@ Verify a Full Installation - REST Editor .. container:: content - .. code:: + .. 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/ . . . @@ -1343,7 +1343,7 @@ Build a Docker Image .. container:: content - .. code:: + .. code:: :number-lines: # @@ -1437,7 +1437,7 @@ General Configuration Format .. container:: content - .. code:: + .. code:: { "engineServiceParameters":{ @@ -1528,7 +1528,7 @@ Engine Service Parameters .. container:: content - .. code:: + .. code:: "engineServiceParameters" : { "name" : "AADMApexEngine", (1) @@ -1684,7 +1684,7 @@ Input and Output Interfaces .. container:: content - .. code:: + .. code:: "eventInputParameters": { (1) "FirstConsumer": { (2) @@ -1796,7 +1796,7 @@ Event Filters .. container:: content - .. code:: + .. code:: "eventInputParameters": { "Input1": { @@ -1866,7 +1866,7 @@ Configure the Javascript Executor .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -1891,7 +1891,7 @@ Configure the Jython Executor .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -1916,7 +1916,7 @@ Configure the JRuby Executor .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -1941,7 +1941,7 @@ Configure the Java Executor .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -1966,7 +1966,7 @@ Configure the MVEL Executor .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -2016,7 +2016,7 @@ Configure AVRO Schema Handler .. container:: content - .. code:: + .. code:: "engineServiceParameters":{ "engineParameters":{ @@ -2193,7 +2193,7 @@ Standard Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "FILE", (1) @@ -2231,7 +2231,7 @@ File Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "FILE", (1) @@ -2260,7 +2260,7 @@ File Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "FILE", (1) @@ -2297,7 +2297,7 @@ Event Requestor Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology": "EVENT_REQUESTOR" (1) @@ -2320,7 +2320,7 @@ Event Requestor Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology": "EVENT_REQUESTOR" (1) @@ -2342,7 +2342,7 @@ Peering Event Requestors .. container:: content - .. code:: + .. code:: "eventInputParameters": { "EventRequestorConsumer": { @@ -2442,7 +2442,7 @@ Kafka Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "KAFKA", (1) @@ -2500,7 +2500,7 @@ Kafka Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "KAFKA", (1) @@ -2570,7 +2570,7 @@ JMS Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "JMS", (1) @@ -2629,7 +2629,7 @@ JMS Output with Text .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "JMS", (1) @@ -2730,7 +2730,7 @@ Websocket Client .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "WEBSOCKET", (1) @@ -2768,7 +2768,7 @@ Websocket Server .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "WEBSOCKET", (1) @@ -2817,7 +2817,7 @@ REST Client Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "RESTCLIENT", (1) @@ -2851,7 +2851,7 @@ REST Client Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters" : { "carrierTechnology" : "RESTCLIENT", (1) @@ -2961,7 +2961,7 @@ REST Server Stand-alone .. container:: content - .. code:: + .. code:: "eventInputParameters": { "MyConsumer": { @@ -3016,7 +3016,7 @@ REST Server Stand-alone .. container:: content - .. code:: + .. code:: "eventOutputParameters": { "MyProducer": { @@ -3066,7 +3066,7 @@ REST Server Stand-alone in Servlet .. container:: content - .. code:: + .. code:: <servlet> ... @@ -3098,7 +3098,7 @@ REST Requestor Input .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters": { "carrierTechnology": "RESTREQUESTOR", (1) @@ -3131,7 +3131,7 @@ REST Requestor Input .. container:: content - .. code:: + .. code:: "eventName": "GuardResponseEvent", (1) "eventNameFilter": "GuardResponseEvent", (2) @@ -3165,7 +3165,7 @@ REST Requestor Output .. container:: content - .. code:: + .. code:: "carrierTechnologyParameters": { "carrierTechnology": "RESTREQUESTOR", (1) @@ -3187,7 +3187,7 @@ REST Requestor Output .. container:: content - .. code:: + .. code:: "eventNameFilter": "GuardRequestEvent", (1) "requestorMode": true, (2) @@ -3287,7 +3287,7 @@ JSON Event .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "JSON" @@ -3310,7 +3310,7 @@ JSON Event .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "JSON", @@ -3366,7 +3366,7 @@ APEX Event .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "APEX" @@ -3400,7 +3400,7 @@ JMS Text .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "JMSTEXT", @@ -3427,7 +3427,7 @@ JMS Object .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "JMSOBJECT", @@ -3462,7 +3462,7 @@ YAML Event .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "XML", @@ -3496,7 +3496,7 @@ XML Event .. container:: content - .. code:: + .. code:: "eventProtocolParameters":{ "eventProtocol" : "XML", @@ -3524,7 +3524,7 @@ A configuration example .. container:: content - .. code:: + .. code:: { "engineServiceParameters" : { @@ -3763,7 +3763,7 @@ The APEX Engine .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] options @@ -3852,7 +3852,7 @@ The APEX CLI Editor .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...] options @@ -3939,7 +3939,7 @@ The APEX REST Editor .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...] -h,--help outputs the usage of this command @@ -3958,7 +3958,7 @@ The APEX REST Editor .. container:: content - .. code:: + .. 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 @@ -4012,7 +4012,7 @@ The APEX Monitoring Client .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...] -h,--help outputs the usage of this command @@ -4028,7 +4028,7 @@ The APEX Monitoring Client .. container:: content - .. code:: + .. 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 @@ -4082,7 +4082,7 @@ The APEX Deployment Client .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...] -h,--help outputs the usage of this command @@ -4098,7 +4098,7 @@ The APEX Deployment Client .. container:: content - .. code:: + .. 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 @@ -4155,7 +4155,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: usage: org.onap.policy.apex.client.full.rest.ApexServicesRestMain [options...] -h,--help outputs the usage of this command @@ -4171,7 +4171,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.NetworkListener start @@ -4240,7 +4240,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: apexApps.sh - runs APEX applications @@ -4260,7 +4260,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: apexApps.sh: supported applications: --> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console @@ -4274,7 +4274,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: apexApps.sh: application 'ws-console' --> a simple console sending events to APEX, connect to APEX consumer port @@ -4290,7 +4290,7 @@ The APEX Full Client .. container:: content - .. code:: + .. code:: apexApps.sh ws-echo -p 8888 @@ -4333,7 +4333,7 @@ Application: Create Event Templates .. container:: content - .. code:: + .. code:: gen-model2event v{release-version} - generates JSON templates for events generated from a policy model usage: gen-model2event @@ -4355,7 +4355,7 @@ Application: Create Event Templates .. container:: content - .. code:: + .. code:: apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli @@ -4367,7 +4367,7 @@ Application: Create Event Templates .. container:: content - .. code:: + .. code:: gen-model2event: starting Event generator --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json @@ -4407,7 +4407,7 @@ Application: Create Event Templates .. container:: content - .. code:: + .. code:: { "name" : "Event0000", @@ -4457,7 +4457,7 @@ Application: Convert a Policy Model to CLI Editor Commands .. container:: content - .. code:: + .. code:: usage: gen-model2cli -h,--help prints this help and usage screen @@ -4474,7 +4474,7 @@ Application: Convert a Policy Model to CLI Editor Commands .. container:: content - .. code:: + .. code:: apexApps.sh model-2-cli -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json @@ -4486,7 +4486,7 @@ Application: Convert a Policy Model to CLI Editor Commands .. container:: content - .. code:: + .. code:: gen-model2cli: starting CLI generator --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json @@ -4942,32 +4942,32 @@ Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH`` parameter fields. .. tip - - .. container:: title - - Field Schema types - - .. container:: paragraph - - APEX natively supports schema definitions in ``Java`` and ``Avro``. - - .. container:: paragraph - - ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions: - - .. container:: ulist - - - the class must be instantiatable, i.e. not an Java interface or abstract class - - - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc. - - - it must be possible to find the class, i.e. the class must be contained in the Java classpath. - - .. container:: paragraph - - ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__ - schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must - contain a value that conforms to the Avro schema. + + .. container:: title + + Field Schema types + + .. container:: paragraph + + APEX natively supports schema definitions in ``Java`` and ``Avro``. + + .. container:: paragraph + + ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions: + + .. container:: ulist + + - the class must be instantiatable, i.e. not an Java interface or abstract class + + - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc. + + - it must be possible to find the class, i.e. the class must be contained in the Java classpath. + + .. container:: paragraph + + ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__ + schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must + contain a value that conforms to the Avro schema. .. container:: paragraph @@ -5004,10 +5004,10 @@ Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH`` the event definition pane. .. tip:: - Optional Fields in APEX Events - Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it - is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set - for an output event then value will be set to ``null``. + Optional Fields in APEX Events + Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it + is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set + for an output event then value will be set to ``null``. .. container:: imageblock @@ -5217,7 +5217,7 @@ Create a new Policy and add the *"No Booze before 11:30"* check .. container:: content - .. code:: + .. code:: /* * ============LICENSE_START======================================================= @@ -5325,7 +5325,7 @@ Create a new Policy and add the *"No Booze before 11:30"* check .. container:: content - .. code:: + .. code:: /* * ============LICENSE_START======================================================= @@ -5494,60 +5494,60 @@ Create a new Policy and add the *"No Booze before 11:30"* check default task is automatically selected and no 'Task Selection Logic' is required. - .. note:: - .. container:: title - - State Output Mappings - - .. container:: paragraph - - In a 'Policy' 'State' a 'State Output Mapping' has 3 roles: - 1) Select which 'State' should be executed next, 2) Select - the type of the state’s 'Outgoing Event', and 3) - Populate the state’s 'Outgoing Event'. This is how states are - chained together to form a (`Directed Acyclic Graph - (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ ) - of states. The final state(s) of a policy are those that do - not select any 'next' state. Since a 'State' can only - accept a single type of event, the type of the event emitted - by a previous 'State' must be match the incoming event type - of the next 'State'. This is also how the last state(s) in - a policy can emit events of different types. The 'State - Output Mapping' is also responsible for taking the - fields that are output by the task executed in the state and - populating the state’s output event before it is emitted. - - .. container:: paragraph - - Each 'Task' referenced in 'State' must have a defined - 'Output Mapping' to take the output of the task, select an - 'Outgoing Event' type for the state, populate the state’s - outgoing event, and then select the next state to be - executed (if any). - - .. container:: paragraph - - There are 2 basic types of output mappings: - - .. container:: olist arabic - - #. **Direct Output Mappings** have a single value for - 'Next State' and a single value for 'State Output - Event'. The outgoing event for the state is - automatically created, any outgoing event parameters - that were present in the incoming event are copied - into the outgoing event, then any task output fields - that have the same name and type as parameters in the - outgoing event are automatically copied into - the outgoing event. - - #. **Logic-based State Output Mappings / Finalizers** - have some logic defined that dynamically selects - and creates the 'State Outgoing Event', manages - the population of the outgoing event parameters - (perhaps changing or adding to the outputs from the - task), and then dynamically selects the next state to - be executed (if any). + .. note:: + .. container:: title + + State Output Mappings + + .. container:: paragraph + + In a 'Policy' 'State' a 'State Output Mapping' has 3 roles: + 1) Select which 'State' should be executed next, 2) Select + the type of the state’s 'Outgoing Event', and 3) + Populate the state’s 'Outgoing Event'. This is how states are + chained together to form a (`Directed Acyclic Graph + (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ ) + of states. The final state(s) of a policy are those that do + not select any 'next' state. Since a 'State' can only + accept a single type of event, the type of the event emitted + by a previous 'State' must be match the incoming event type + of the next 'State'. This is also how the last state(s) in + a policy can emit events of different types. The 'State + Output Mapping' is also responsible for taking the + fields that are output by the task executed in the state and + populating the state’s output event before it is emitted. + + .. container:: paragraph + + Each 'Task' referenced in 'State' must have a defined + 'Output Mapping' to take the output of the task, select an + 'Outgoing Event' type for the state, populate the state’s + outgoing event, and then select the next state to be + executed (if any). + + .. container:: paragraph + + There are 2 basic types of output mappings: + + .. container:: olist arabic + + #. **Direct Output Mappings** have a single value for + 'Next State' and a single value for 'State Output + Event'. The outgoing event for the state is + automatically created, any outgoing event parameters + that were present in the incoming event are copied + into the outgoing event, then any task output fields + that have the same name and type as parameters in the + outgoing event are automatically copied into + the outgoing event. + + #. **Logic-based State Output Mappings / Finalizers** + have some logic defined that dynamically selects + and creates the 'State Outgoing Event', manages + the population of the outgoing event parameters + (perhaps changing or adding to the outputs from the + task), and then dynamically selects the next state to + be executed (if any). .. container:: paragraph @@ -5841,7 +5841,7 @@ Test Policy Step 1 .. container:: content - .. code:: + .. code:: #------------------------------------------------------------------------------- # ============LICENSE_START======================================================= @@ -6143,7 +6143,7 @@ Extend the Policy with the new Scenario .. container:: content - .. code:: + .. code:: /* * ============LICENSE_START======================================================= @@ -6320,7 +6320,7 @@ Extend the Policy with the new Scenario .. container:: content - .. code:: + .. code:: /* * ============LICENSE_START======================================================= @@ -6429,7 +6429,7 @@ Test Policy Step 2 .. container:: content - .. code:: + .. code:: { "engineServiceParameters" : { @@ -6633,7 +6633,7 @@ Policy 2 in CLI Editor .. container:: content - .. code:: + .. code:: #------------------------------------------------------------------------------- # ============LICENSE_START======================================================= @@ -7053,7 +7053,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: <configuration debug="false"> @@ -7075,7 +7075,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> @@ -7093,7 +7093,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: <root level="info"> @@ -7109,7 +7109,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: <appender name="FILE" class="ch.qos.logback.core.FileAppender"> @@ -7128,7 +7128,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: <appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender"> @@ -7151,7 +7151,7 @@ Standard Logging Configuration .. container:: content - .. code:: + .. code:: :number-lines: @@ -7176,7 +7176,7 @@ Adding Logback Status and Debug .. container:: content - .. code:: + .. code:: <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /> @@ -7190,7 +7190,7 @@ Adding Logback Status and Debug .. container:: content - .. code:: + .. code:: <configuration debug="true"> ... @@ -7216,7 +7216,7 @@ Logging External Components .. container:: content - .. code:: + .. code:: <logger name="org.infinispan" level="INFO" additivity="false"> <appender-ref ref="STDOUT" /> @@ -7231,7 +7231,7 @@ Logging External Components .. container:: content - .. code:: + .. code:: <logger name="org.apache.zookeeper.ClientCnxn" level="INFO" additivity="false"> <appender-ref ref="STDOUT" /> @@ -7260,7 +7260,7 @@ Configuring loggers for Policy Logic .. container:: content - .. code:: + .. code:: <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> @@ -7282,7 +7282,7 @@ Configuring loggers for Policy Logic .. container:: content - .. code:: + .. code:: <logger name="org.onap.policy.apex.executionlogging.TaskExecutionLogging" level="TRACE" additivity="false"> <appender-ref ref="POLICY_APPENDER_STDOUT" /> @@ -7309,7 +7309,7 @@ Rolling File Appenders .. container:: content - .. code:: + .. code:: <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${VAR_LOG}/apex.log</file> @@ -7340,7 +7340,7 @@ Rolling File Appenders .. container:: content - .. code:: + .. code:: <appender name="CTXT-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> @@ -7378,7 +7378,7 @@ Example Configuration for Logging Logic .. container:: content - .. code:: + .. code:: <configuration debug="false"> <statusListener class="ch.qos.logback.core.status.NopStatusListener" /> @@ -7437,7 +7437,7 @@ Example Configuration for a Production Server .. container:: content - .. code:: + .. code:: <configuration debug="false"> <statusListener class="ch.qos.logback.core.status.NopStatusListener" /> @@ -7611,7 +7611,7 @@ A Websocket Configuration for the VPN Domain .. container:: content - .. code:: + .. code:: :number-lines: { @@ -7674,7 +7674,7 @@ Start APEX Engine .. container:: content - .. code:: + .. code:: :number-lines: #: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json @@ -7683,7 +7683,7 @@ Start APEX Engine .. container:: content - .. code:: + .. code:: :number-lines: #: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json @@ -7700,7 +7700,7 @@ Start APEX Engine .. container:: content - .. code:: + .. code:: :number-lines: 2017-07-28 13:17:20,834 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model VPNPolicyModelAvro:0.0.1 added to the engine-AxArtifactKey:(name=VPNApexEngine-0,version=0.0.1) @@ -7725,7 +7725,7 @@ Run the Websocket Echo Client .. important:: APEX engine needs to run first - The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first. + The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first. +---------------------------------------------------------+-----------------------------------------------------------+ | Unix, Cygwin | Windows | @@ -7768,7 +7768,7 @@ Run the Websocket Echo Client .. container:: content - .. code:: + .. code:: # $APEX_HOME/bin/apexApps.sh ws-echo -p 42452 (1) > %APEX_HOME%\bin\apexApps.bat ws-echo -p 42452 (2) @@ -7791,7 +7791,7 @@ Run the Websocket Echo Client .. container:: content - .. code:: + .. code:: ws-simple-echo: starting simple event echo --> server: localhost @@ -7815,8 +7815,8 @@ Run the Websocket Console Client .. important:: APEX engine needs to run first - The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event - protocol is executed first. + The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event + protocol is executed first. +------------------------------------------------------------+--------------------------------------------------------------+ | Unix, Cygwin | Windows | @@ -7859,7 +7859,7 @@ Run the Websocket Console Client .. container:: content - .. code:: + .. code:: # $APEX_HOME/bin/apexApps.sh ws-console -p 42450 (1) > %APEX_HOME%\bin\apexApps.sh ws-console -p 42450 (2) @@ -7882,7 +7882,7 @@ Run the Websocket Console Client .. container:: content - .. code:: + .. code:: ws-simple-console: starting simple event console --> server: localhost @@ -7921,7 +7921,7 @@ Send Events .. container:: content - .. code:: + .. code:: :number-lines: #: $APEX_HOME/examples/events/VPN @@ -7940,7 +7940,7 @@ Send Events .. container:: content - .. code:: + .. code:: :number-lines: {Link=L09, LinkUp=true} @@ -7982,7 +7982,7 @@ Send Events .. container:: content - .. code:: + .. code:: :number-lines: ws-simple-echo: received diff --git a/docs/distribution/Distribution-User-Manual.rst b/docs/distribution/Distribution-User-Manual.rst index 12f75b9a..7d3f770e 100644 --- a/docs/distribution/Distribution-User-Manual.rst +++ b/docs/distribution/Distribution-User-Manual.rst @@ -105,7 +105,7 @@ Build Distribution .. important:: A Build needs Space - Building distribution requires approximately 1-2 GB of hard disc space, 100 MB for the actual build with full + Building distribution requires approximately 1-2 GB of hard disc space, 100 MB for the actual build with full distribution and around 1 GB for the downloaded dependencies. .. important:: @@ -175,7 +175,7 @@ Build Distribution The build will have created all artifacts required for distribution installation. The following example show how to change to the target - directory and how it should look like. + directory and how it should look. +----------------------------------------------------------------------------------------------------------------------------+ | Unix, Cygwin | @@ -256,7 +256,7 @@ Install Manually from Archive (Windows, 7Zip, GUI) .. container:: paragraph - The right-click on the new created TAR file and extract the actual + Then right-click on the new created TAR file and extract the actual distribution. | @@ -362,11 +362,11 @@ Introduction to Distribution Configuration A distribution engine can be configured to use various combinations of policy reception handlers, policy decoders and policy forwarders. - The system is build using a plugin architecture. Each configuration + The system is built using a plugin architecture. Each configuration option is realized by a plugin, which can be loaded and configured when the engine is started. New plugins can be added to the system at any time, though to benefit from a - new plugin an engine will need to be restarted. + new plugin, an engine will need to be restarted. | |