diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/install-guide/verify.adoc')
| -rw-r--r-- | src/site-docs/adoc/fragments/install-guide/verify.adoc | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/install-guide/verify.adoc b/src/site-docs/adoc/fragments/install-guide/verify.adoc new file mode 100644 index 000000000..782c2723e --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/verify.adoc @@ -0,0 +1,180 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Verify the APEX Installation +When APEX is installed and all settings are realized, the installation can be verified. + +=== Verify a Minimal Installation +The minimal installation does not come with any configuration or policy model. +It is therefore not possible to test all APEX features, or an engine running with policies. + +However, one can verify that the engine starts up to the point where it tries to load a configuration. + +On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`. +The engine will fail to fully start. +However, if the output looks similar to the following line, the APEX installation is realized. + +[source%nowrap,sh,numbered] +---- +Starting Apex service with parameters [] . . . +start of Apex service failed: Apex configuration file was not specified as an argument +2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: +---- + +On Windows start the engine using `%APEX_HOME%\bin\apexEngine.bat`. +The engine will fail to fully start. +However, if the output looks similar to the following line, the APEX installation is realized. + +[source%nowrap,bat,numbered] +---- +Starting Apex service with parameters [] . . . +start of Apex service failed: Apex configuration file was not specified as an argument +2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: +---- + + +=== Verify a Full Installation - run an Example +A full APEX installation comes with several examples. +Here, we can fully verify the installation by running one of the examples. + +We use the example called _SampleDomain_ and configure the engine to use standard in and standard out for events. +Run the engine with the provided configuration. +Note: Cygwin executes scripts as Unix scripts but runs Java as a Windows application, thus the configuration file must be given as a Windows path. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <1> +# $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-{release-version}/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <2> +>%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json @@ <3> +---- +<1> UNIX +<2> Cygwin +<3> Windows + + +The engine should start successfully. +Assuming the logging levels are not change (default level is `info`), the output should look similar to this (last few lines) + +[source%nowrap,sh,numbered] +---- +2017-07-28 13:20:54,673 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model SamplePolicyModelJAVA:0.0.1 added to the engine-AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) +2017-07-28 13:20:54,675 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-0,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:1] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-1,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:2] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-2,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:3] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) processing ... +2017-07-28 13:20:54,680 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine +Started Apex service +---- + +Important are the last two line, stating that APEX has added the final action listener to the engine and that the engine is started. + +The engine is configured to read events from standard input and write produced events to standard output. +The policy model is a very simple policy. + +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 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. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Input Event | Example Output Event +| +[source%nowrap,json,numbered] +---- +{ + "nameSpace": "org.onap.policy.apex.sample.events", + "name": "Event0000", + "version": "0.0.1", + "source": "test", + "target": "apex", + "TestSlogan": "Test slogan for External Event0", + "TestMatchCase": 0, + "TestTimestamp": 1469781869269, + "TestTemperature": 9080.866 +} +---- +| +[source%nowrap,json,numbered] +---- +{ + "nameSpace" : "org.onap.policy.apex.sample.events", + "name" : "Event0004", + "version" : "0.0.1", + "source" : "Act", + "target" : "Outside", + "TestActCaseSelected" : 1, + "TestActStateTime" : 1499280954832, + "TestTemperature" : 9080.866, + "TestDecideCaseSelected" : 2, + "TestMatchCaseSelected" : 2, + "TestTimestamp" : 1469781869269, + "TestDecideStateTime" : 1499280954831, + "TestMatchCase" : 0, + "TestSlogan" : "Test slogan for External Event0", + "TestEstablishCaseSelected" : 1, + "TestEstablishStateTime" : 1499280954831, + "TestMatchStateTime" : 1499280954828 +} +---- +|==================== + +Terminate APEX by simply using `CTRL+C` in the console. + + +=== Verify a Full Installation - REST Editor +APEX has a REST application for viewing policy models. +The application can also be used to create new policy models close to the engine native policy language. +Start the REST editor as follows. + +[source%nowrap,sh,numbered] +---- +# $APEX_HOME/bin/apexApps.sh rest-editor +---- + +[source%nowrap,bat,numbered] +---- +>%APEX_HOME%\bin\apexApps.bat rest-editor +---- + +The script will start a simple web server (link:https://javaee.github.io/grizzly/[Grizzly]) and deploy a `war` web archive in it. +Once the editor is started, it will be available on `localhost:18988`. +The last few line of the messages should be: + +[source%nowrap,sh,numbered] +---- +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=READY) starting at http://localhost:18988/apex/ . . . +Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.NetworkListener start +INFO: Started listener bound to [localhost:18988] +Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.HttpServer start +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=RUNNING) started at http://localhost:18988/apex/ +---- + +Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`. +This will connect the browser to the started REST editor. +The start screen should be as follows. + +.REST Editor Start Screen +image::install-guide/rest-start.png[REST Editor Start Screen] + +Now load a policy model by clicking the menu `File` and then `Open`. +In the opened dialog, go to the directory where APEX is installed, then `examples`, `models`, `SampleDomain`, and there select the file `SamplePolicyModelJAVA.json`. +This will load the policy model used to verify the policy engine (see above). +Once loaded, the screen should look as follows. + +.REST Editor with loaded SampleDomain Policy Model +image::install-guide/rest-loaded.png[REST Editor with loaded SampleDomain Policy Model] + +Now you can use the REST editor. +To finish this verification, simply terminate your browser (or the tab), and then use `CTRL+C` in the console where you started the REST editor. + |