diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-apex')
11 files changed, 715 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc new file mode 100644 index 000000000..973564df3 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc @@ -0,0 +1,62 @@ +// +// ============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) +// + +== Application: Convert a Policy Model to CLI Editor Commands + +**Status: Experimental** + +This application takes a policy model (JSON or XML encoded) and generates commands for the APEX CLI Editor. +This effectively reverses a policy specification realized with the CLI Editor. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh model-2-cli [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat model-2-cli [args] +---- +|==================== + +The option `-h` provides a help screen. + +[source%nowrap,sh] +---- +usage: gen-model2cli + -h,--help prints this help and usage screen + -m,--model <MODEL-FILE> set the input policy model file + -sv,--skip-validation switch of validation of the input file + -v,--version prints the application version +---- + +For instance, running the tool with the __Sample Domain__ policy model as: +[source%nowrap,sh] +---- +apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli +---- + +will produce the following status messages: + +[source%nowrap,sh] +---- +gen-model2cli: starting CLI generator + --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json +---- + +and then run the generator application producing all CLI Editor commands and printing them to standard out. + diff --git a/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc new file mode 100644 index 000000000..bd31bedf9 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc @@ -0,0 +1,99 @@ +// +// ============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) +// + +== Application: Create Event Templates + +**Status: Experimental** + +This application takes a policy model (JSON or XML encoded) and generates templates for events in JSON format. +This can help when a policy defines rather complex trigger or action events or complex events between states. +The application can produce events for the types: stimuli (policy trigger events), internal (events between policy states), and response (action events). + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh tpl-event-json [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] +---- +|==================== + +The option `-h` provides a help screen. + +[source%nowrap,sh] +---- +usage: gen-model2event + -h,--help prints this help and usage screen + -m,--model <MODEL-FILE> set the input policy model file + -t,--type <TYPE> set the event type for generation, one of: + stimuli (trigger events), response (action + events), internal (events between states) + -v,--version prints the application version +---- + +The created templates are not valid events, instead they use some markup for values one will need to change to actual values. +For instance, running the tool with the __Sample Domain__ policy model as: +[source%nowrap,sh] +---- +apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli +---- + +will produce the following status messages: + +[source%nowrap,sh] +---- +gen-model2event: starting Event generator + --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json + --> type: stimuli +---- + +and then run the generator application producing two event templates. +The first template is called `Event0000`. + +[source%nowrap,json] +---- +{ + "name" : "Event0000", + "nameSpace" : "org.onap.policy.apex.sample.events", + "version" : "0.0.1", + "source" : "Outside", + "target" : "Match", + "TestTemperature" : ###double: 0.0###, + "TestTimestamp" : ###long: 0###, + "TestMatchCase" : ###integer: 0###, + "TestSlogan" : "###string###" +} +---- +The values for the keys are marked with `###` and the expected type of the value. +To create an actual stimuli event, all these markers need to be change to actual values, for instance: +[source%nowrap,json] +---- +{ + "name" : "Event0000", + "nameSpace" : "org.onap.policy.apex.sample.events", + "version" : "0.0.1", + "source" : "Outside", + "target" : "Match", + "TestTemperature" : 25, + "TestTimestamp" : 123456789123456789, + "TestMatchCase" : 1, + "TestSlogan" : "Testing the Match Case with Temperature 25" +} +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc b/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc new file mode 100644 index 000000000..f11bdf277 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc @@ -0,0 +1,45 @@ +// +// ============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) +// + +== Application: Websocket Clients (Echo and Console) + +**Status: Production** + +The application launcher also provides a Websocket echo client and a Websocket console client. +The echo client connects to APEX and prints all events it receives from APEX. +The console client connects to APEX, reads input from the command line, and sends this input as events to APEX. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh ws-echo [args] +# $APEX_HOME/bin/apexApps.sh ws-console [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat ws-echo [args] +> %APEX_HOME%\bin\apexApps.bat ws-console [args] +---- +|==================== + +The arguments are the same for both applications: + +- `-p` defines the Websocket port to connect to (defaults to `8887`) +- `-s` defines the host on which a Websocket server is running (defaults to `localhost`) + +A discussion on how to use these two applications to build an APEX system is detailed HowTo-Websockets. + diff --git a/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc new file mode 100644 index 000000000..4222b436a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc @@ -0,0 +1,80 @@ +// +// ============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) +// + +== The APEX Application Launcher +The standard applications (Engine, CLI Editor, REST Editor) come with dedicated start scripts. +For all other APEX applications, we provide an application launcher. + +On UNIX and Cygwin systems use: + +- apexApps.sh` - simply starts the application launcher + +On Windows systems use: + +- `apexApps.bat` - simply starts the application launcher + + +Summary of alternatives to start the APEX application launcher: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat [args] +---- +|==================== + +The option `-h` provides a help screen with all launcher command line arguments. + +[source%nowrap,sh] +---- +apexApps.sh - runs APEX applications + + Usage: apexApps.sh [options] | [<application> [<application options>]] + + Options + -d <app> - describes an application + -l - lists all applications supported by this script + -h - this help screen +---- + +Using `-l` lists all known application the launcher can start. + +[source%nowrap,sh] +---- +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 +---- + +Using the `-d <name>` option describes the named application, for instance for the `ws-console`: + +[source%nowrap,sh] +---- +apexApps.sh: application 'ws-console' + --> a simple console sending events to APEX, connect to APEX consumer port +---- + +Launching an application is done by calling the script with only the application name and any CLI arguments for the application. +For instance, starting the `ws-echo` application with port `8888`: +[source%nowrap,sh] +---- +apexApps.sh ws-echo -p 8888 +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc new file mode 100644 index 000000000..e677079f2 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc @@ -0,0 +1,82 @@ +// +// ============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) +// + +== The APEX CLI Editor +The CLI Editor allows to define policies from the command line. +The application uses a simple language and supports all elements of an APEX policy. +It can be used in to different ways: + +- non-interactive, specifying a file with the commands to create a policy +- interactive, using the editors CLI to create a policy + +When a policy is fully specified, the editor will generate the APEX core policy specification in JSON. +This core specification is called the policy model in the APEX engine and can be used directly with the APEX engine. + +On UNIX and Cygwin systems use: + +- `apexCLIEditor.sh` - simply starts the CLI editor, arguments to the script determine the mode of the editor +- `apexApps.sh cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor + +On Windows systems use: + +- `apexCLIEditor.bat` - simply starts the CLI editor, arguments to the script determine the mode of the editor +- `apexApps.bat cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor + + +Summary of alternatives to start the APEX CLI Editor: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexCLIEditor.sh.sh [args] +# $APEX_HOME/bin/apexApps.sh cli-editor [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexCLIEditor.bat [args] +> %APEX_HOME%\bin\apexApps.bat cli-editor [args] +---- +|==================== + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...] +options + + -a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use + -c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor + -h,--help outputs the usage of this command + -i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor + -if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and continue + executing the command file + -l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will log + to standard output if not specified or suppressed with "-nl" flag + -m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use + -nl,--no-log if specified, no logging or output of commands to standard output or log + file is carried out + -nm,--no-model-output if specified, no output of a model to standard output or model output + file is carried out, the user can use the "save" command in a script to + save a model + -o,--output-model-file <OUTPUT_MODEL_FILE> name of a file that will contain the output model for the editor, will + output model to standard output if not specified or suppressed with + "-nm" flag + -wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the + root from which to look for included macro files +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc new file mode 100644 index 000000000..52836a783 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc @@ -0,0 +1,50 @@ +// +// ============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) +// + +== The APEX Deployment Client +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 + +On UNIX and Cygwin systems use: + +- `apexApps.sh eng-deployment` - simply starts the webserver with the Deployment Client + +On Windows systems use: + +- `apexApps.bat eng-deployment` - simply starts the webserver with the Deployment Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.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 +---- + +If the Deployment Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +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/ +---- + +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`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc new file mode 100644 index 000000000..960546d06 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc @@ -0,0 +1,50 @@ +// +// ============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) +// + +== The APEX Monitoring Client +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 + +On UNIX and Cygwin systems use: + +- `apexApps.sh eng-monitoring` - simply starts the webserver with the Monitoring Client + +On Windows systems use: + +- `apexApps.bat eng-monitoring` - simply starts the webserver with the Monitoring Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.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 +---- + +If the Monitoring Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +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/ +---- + +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`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/engine.adoc b/src/site-docs/adoc/fragments/howto-apex/engine.adoc new file mode 100644 index 000000000..819c2ca87 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/engine.adoc @@ -0,0 +1,71 @@ +// +// ============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) +// + +== The APEX Engine +The APEX engine can be started in different ways, depending your requirements. +All scripts are located in the APEX __bin__ directory + +On UNIX and Cygwin systems use: + +- `apexEngine.sh` - this script will + ** Test if `$APEX_USER` is set and if the user exists, terminate with an error otherwise + ** Test if `$APEX_HOME` is set. If not set, it will use the default setting as `/opt/ericsson/apex/apex`. + Then the set directory is tested to exist, the script will terminate if not. + ** When all tests are passed successfully, the script will call `apexApps.sh` with arguments to start the APEX engine. +- `apexApps.sh engine` - this is the general APEX application launcher, which will + ** Start the engine with the argument `engine` + ** Test if `$APEX_HOME` is set and points to an existing directory. If not set or directory does not exist, script terminates. + ** Not test for any settings of `$APEX_USER`. + +On Windows systems use `apexEngine.bat` and `apexApps.bat engine` respectively. +Note: none of the windows batch files will test for `%APEX_USER%`. + +Summary of alternatives to start the APEX Engine: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexEngine.sh [args] +# $APEX_HOME/bin/apexApps.sh engine [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexEngine.bat [args] +> %APEX_HOME%\bin\apexApps.bat engine [args] +---- +|==================== + + +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. + +[source%nowrap,sh] +---- +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 +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/full-client.adoc b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc new file mode 100644 index 000000000..97a18393b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc @@ -0,0 +1,51 @@ +// +// ============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) +// + +== The APEX Full Client +The APEX Full Client combines the REST 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. +However, the Full Client can also be started via command line. +This will start a Grizzly webserver with the __war__ deployed. +Access to the Full Client is then via the provided URL + +On UNIX and Cygwin systems use: + +- `apexApps.sh full-client` - simply starts the webserver with the Full Client + +On Windows systems use: + +- `apexApps.bat full-client` - simply starts the webserver with the Full Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.client.full.rest.ApexServicesRestMain [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 +---- + +If the Full Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ +---- + +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`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/introduction.adoc b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc new file mode 100644 index 000000000..faa2f4949 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc @@ -0,0 +1,51 @@ +// +// ============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) +// + +== Introduction to APEX Engine and Applications +The core of APEX is the APEX Engine, also known as the APEX Policy Engine. +Beside this engine, an APEX system comes with a few applications intended to help with policy authoring, deployment, and execution. + +The engine itself and most applications are started from the command line with command line arguments. +This is called a Command Line Interface (CLI). +Some applications require an installation on a webserver, as for instance the REST Editor. +Those applications can be accessed via a web browser. + +Starting with APEX version 0.5.6, we also provide plugins for Eclipse realizing a policy development environment. +Those plugins support the main APEX policy language. +Other, higher-level, policy languages will be added in future versions along with their Eclipse plugins. +Furthermore, we are planning to provide a backend supporting the Language Server Protocol (LSP). +This backend, run as a server, will allow to join any editor or IDE that is LSP-enabled to benefit from the APEX policy languages. + +Last not least, one can use the available APEX APIs and applications to develop other applications as required. +This includes policy languages (and associated parsers and compilers / interpreters), GUIs to access APEX or to define policies, clients to connect to APEX, etc. +Separate documentation will be available in APEX releases addressing this type of applications. + +For this documentation, we assume an installation of APEX as a full system (i.e. not minimal) of version 0.5.6 or higher. + +== CLI on Unix, Windows, and Cygwin +A note on APEX CLI applications: all applications and the engine itself have been deployed and tested on different operating systems: Red Hat, Ubuntu, Debian, Mac OSX, Windows, Cygwin. +Each operating system comes with its own way of configuring and executing Java. +The main items here are: + +- For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the provided bash scripts work as expected + with absolute paths (e.g. `/opt/ericsson/apex/apex-{release-version}/examples`), + indirect and linked paths (e.g. `../apex/apex`), + and path substitutions using environment settings (e.g. `$APEX_HOME/bin/`) +- For Windows systems, the provided batch files (`.bat`) work as expected with + with absolute paths (e.g. `C:\apex\apex-{release-version}\examples`), + and path substitutions using environment settings (e.g. `%APEX_HOME%\bin\`) +- For Cygwin system we assume a standard Cygwin installation with standard tools (mainly bash) using a Windows Java installation. + This means that the bash scripts can be used as in UNIX, however any argument pointing to files and directories need to use either a DOS path (e.g. `C:\apex\apex-{release-version}\examples\config\...`) + or the command `cygpath` with a mixed option. + The reason for that is: Cygwin executes Java using UNIX paths but then runs Java as a DOS/WINDOWS process, which requires DOS paths for file access. + diff --git a/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc new file mode 100644 index 000000000..3be6f9f94 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc @@ -0,0 +1,74 @@ +// +// ============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) +// + +== The APEX REST Editor +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 + +On UNIX and Cygwin systems use: + +- `apexRESTEditor.sh` - simply starts the webserver with the REST editor +- `apexApps.sh rest-editor` - simply starts the webserver with the REST editor + +On Windows systems use: + +- `apexRESTEditor.bat` - simply starts the webserver with the REST editor +- `apexApps.bat rest-editor` - simply starts the webserver with the REST editor + + +Summary of alternatives to start the APEX REST Editor: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexRESTEditor.sh.sh [args] +# $APEX_HOME/bin/apexApps.sh rest-editor [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexRESTEditor.bat [args] +> %APEX_HOME%\bin\apexApps.bat rest-editor [args] +---- +|==================== + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.auth.rest.ApexEditorMain [options...] +-h,--help outputs the usage of this command +-l,--listen <ADDRESS> the IP address to listen on. Default value is 0.0.0.0 to listen on all available + addresses. Use value '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. +---- + +If the REST Editor is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://0.0.0.0:18988/apex/, TTL=-1sec], State=RUNNING) started at http://0.0.0.0:18988/apex/ +---- + +The last line states the URL on which the REST Editor can be accessed. +The example above stated `http://0.0.0.0:18988/apex/`. +In a web browser use the URL `http://localhost:18988` and the REST Editor will start. + |