aboutsummaryrefslogtreecommitdiffstats
path: root/src/site-docs/adoc/fragments/install-guide/verify.adoc
blob: 6774a848939ad59e014df314e8ec74b4d529f787 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
//
// ============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 Installation - run Engine
A simple verification of an APEX installation can be done by simply starting the APEX engine without any configuration.
On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`.
On Windows start the engine using `%APEX_HOME%\bin\apexEngine.bat`.
The engine will fail to fully start.
However, if the output looks similar to the following line, the APEX installation is realized.

[source%nowrap,sh,numbered]
----
Starting Apex service with parameters [] . . .
start of Apex service failed: Apex configuration file was not specified as an argument
2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed
org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument
        at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)
        at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)
        at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)
        at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)
usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
options
-c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file
                              containing the Apex configuration parameters
-h,--help                     outputs the usage of this command
-m,--model-file <MODEL_FILE>  the full path to the model file to use, if set it overrides the model file set in the
                              configuration file
-v,--version                  outputs the version of Apex

----



=== Verify Installation - run an Example
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]
----
Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . .
2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 .
2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 .
2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 .
2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 .
2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.
2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .
2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started
2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1
2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1
2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1
2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1
2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
Started Apex service
----

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]
----
{
  "name": "Event0004",
  "version": "0.0.1",
  "nameSpace": "org.onap.policy.apex.sample.events",
  "source": "Act",
  "target": "Outside",
  "TestActCaseSelected": 2,
  "TestActStateTime": 1536157104627,
  "TestDecideCaseSelected": 0,
  "TestDecideStateTime": 1536157104625,
  "TestEstablishCaseSelected": 0,
  "TestEstablishStateTime": 1536157104623,
  "TestMatchCase": 0,
  "TestMatchCaseSelected": 1,
  "TestMatchStateTime": 1536157104620,
  "TestSlogan": "Test slogan for External Event0",
  "TestTemperature": 9080.866,
  "TestTimestamp": 1469781869269
}
----
|====================

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:18989`.
The last few line of the messages should be:

[source%nowrap,sh,numbered]
----
Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [localhost:18989]
Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
----

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.

.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.