From 0cf967c0239a8ab9c8b8831b700b72d9a08f7b03 Mon Sep 17 00:00:00 2001 From: liamfallon Date: Fri, 16 Oct 2020 13:09:11 +0100 Subject: Remove apex asciidoc documents Apex documentation has now all been ported to use the ONAP recommended rst format. This review removes the old asciidoc documents. Issue-ID: POLICY-2824 Change-Id: I562bd344cb7d6ff36e7d54bdb8f95e3b656468f8 Signed-off-by: liamfallon --- .../site-docs/adoc/fragments/config-example.adoc | 103 ----------------- .../adoc/fragments/config-general-format.adoc | 65 ----------- .../adoc/fragments/config-interfaces-general.adoc | 124 --------------------- .../adoc/fragments/config-service-parameters.adoc | 47 -------- 4 files changed, 339 deletions(-) delete mode 100644 services/services-engine/src/site-docs/adoc/fragments/config-example.adoc delete mode 100644 services/services-engine/src/site-docs/adoc/fragments/config-general-format.adoc delete mode 100644 services/services-engine/src/site-docs/adoc/fragments/config-interfaces-general.adoc delete mode 100644 services/services-engine/src/site-docs/adoc/fragments/config-service-parameters.adoc (limited to 'services/services-engine/src/site-docs/adoc/fragments') diff --git a/services/services-engine/src/site-docs/adoc/fragments/config-example.adoc b/services/services-engine/src/site-docs/adoc/fragments/config-example.adoc deleted file mode 100644 index dfbc397e9..000000000 --- a/services/services-engine/src/site-docs/adoc/fragments/config-example.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// -// ============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) -// - -== A configuration example - -The following example loads all available plug-ins. - -Events are consumed from a Websocket, APEX as client. -Consumed event format is JSON. - -Events are produced to Kafka. -Produced event format is XML. - -[source%nowrap,json] ----- -{ - "engineServiceParameters" : { - "name" : "MyApexEngine", - "version" : "0.0.1", - "id" : 45, - "instanceCount" : 4, - "deploymentPort" : 12345, - "policyModelFileName" : "examples/models/some-model.json", - "engineParameters" : { - "executorParameters" : { - "JAVASCRIPT" : { - "parameterClassName" : - "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters" - }, - "JYTHON" : { - "parameterClassName" : - "org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters" - }, - "JRUBY" : { - "parameterClassName" : - "org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters" - }, - "JAVA" : { - "parameterClassName" : - "org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters" - }, - "MVEL" : { - "parameterClassName" : - "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters" - } - }, - "contextParameters" : { - "parameterClassName" : - "org.onap.policy.apex.context.parameters.ContextParameters", - "schemaParameters" : { - "Avro":{ - "parameterClassName" : - "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters" - } - } - } - } - }, - "producerCarrierTechnologyParameters" : { - "carrierTechnology" : "KAFKA", - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters", - "parameters" : { - "bootstrapServers" : "localhost:49092", - "acks" : "all", - "retries" : 0, - "batchSize" : 16384, - "lingerTime" : 1, - "bufferMemory" : 33554432, - "producerTopic" : "apex-out", - "keySerializer" : "org.apache.kafka.common.serialization.StringSerializer", - "valueSerializer" : "org.apache.kafka.common.serialization.StringSerializer" - } - }, - "producerEventProtocolParameters" : { - "eventProtocol" : "XML", - "parameterClassName" : - "org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters" - }, - "consumerCarrierTechnologyParameters" : { - "carrierTechnology" : "WEBSOCKET", - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters", - "parameters" : { - "host" : "localhost", - "port" : 88888 - } - }, - "consumerEventProtocolParameters" : { - "eventProtocol" : "JSON" - } -} ----- diff --git a/services/services-engine/src/site-docs/adoc/fragments/config-general-format.adoc b/services/services-engine/src/site-docs/adoc/fragments/config-general-format.adoc deleted file mode 100644 index 27e076701..000000000 --- a/services/services-engine/src/site-docs/adoc/fragments/config-general-format.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// -// ============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) -// - -== General Configuration Format - -The APEX configuration file is a JSON file containing a few main blocks for different parts of the configuration. -Each block then holds the configuration details. -The following code shows the main blocks: - -[source%nowrap,json] ----- -{ - "engineServiceParameters":{ - ... // <1> - "engineParameters":{ <2> - "engineParameters":{...}, <3> - "contextParameters":{...} <4> - } - }, - "eventInputParameters":{ <5> - "input1":{ <6> - "carrierTechnologyParameters":{...}, - "eventProtocolParameters":{...} - }, - "input2":{...}, <7> - "carrierTechnologyParameters":{...}, - "eventProtocolParameters":{...} - }, - ... // <8> - }, - "eventOutputParameters":{ <9> - "output1":{ <10> - "carrierTechnologyParameters":{...}, - "eventProtocolParameters":{...} - }, - "output2":{ <11> - "carrierTechnologyParameters":{...}, - "eventProtocolParameters":{...} - }, - ... // <12> - } -} ----- -<1> main engine configuration -<2> engine parameters for plugin configurations (execution environments and context handling) -<3> engine specific parameters, mainly for executor plugins -<4> context specific parameters, e.g. for context schemas, persistence, etc. -<5> configuration of the input interface -<6> an example input called `input1` with carrier technology and event protocol -<7> an example input called `input2` with carrier technology and event protocol -<8> any further input configuration -<9> configuration of the output interface -<10> an example output called `output1` with carrier technology and event protocol -<11> an example output called `output2` with carrier technology and event protocol -<12> any further output configuration diff --git a/services/services-engine/src/site-docs/adoc/fragments/config-interfaces-general.adoc b/services/services-engine/src/site-docs/adoc/fragments/config-interfaces-general.adoc deleted file mode 100644 index 54ffcca1a..000000000 --- a/services/services-engine/src/site-docs/adoc/fragments/config-interfaces-general.adoc +++ /dev/null @@ -1,124 +0,0 @@ -// -// ============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) -// - -== Input and Output Interfaces - -An APEX engine has two main interfaces: - -- An _input_ interface to receive events: also known as ingress interface or consumer, receiving (consuming) events commonly named triggers, and -- An _output_ interface to publish produced events: also known as egress interface or producer, sending (publishing) events commonly named actions or action events. - -The input and output interface is configured in terms of inputs and outputs, respectively. -Each input and output is a combination of a carrier technology and an event protocol. -Carrier technologies and event protocols are provided by plugins, each with its own specific configuration. -Most carrier technologies can be configured for input as well as output. -Most event protocols can be used for all carrier technologies. -One exception is the JMS object event protocol, which can only be used for the JMS carrier technology. -Some further restrictions apply (for instance for carrier technologies using bi- or uni-directional modes). - -Input and output interface can be configured separately, in isolation, with any number of carrier technologies. -The resulting general configuration options are: - -- Input interface with one or more inputs - ** each input with a carrier technology and an event protocol - ** some inputs with optional synchronous mode - ** some event protocols with additional parameters -- Output interface with one or more outputs - ** each output with a carrier technology and an event encoding - ** some outputs with optional synchronous mode - ** some event protocols with additional parameters - -The configuration for input and output is contained in `eventInputParameters` and `eventOutputParameters`, respectively. -Inside here, one can configure any number of inputs and outputs. -Each of them needs to have a unique identifier (name), the content of the name is free form. -The example below shows a configuration for two inputs and two outputs. - -[source%nowrap,json] ----- -"eventInputParameters": { <1> - "FirstConsumer": { <2> - "carrierTechnologyParameters" : {...}, <3> - "eventProtocolParameters":{...}, <4> - ... <5> - }, - "SecondConsumer": { <6> - "carrierTechnologyParameters" : {...}, <7> - "eventProtocolParameters":{...}, <8> - ... <9> - }, -}, -"eventOutputParameters": { <10> - "FirstProducer": { <11> - "carrierTechnologyParameters":{...}, <12> - "eventProtocolParameters":{...}, <13> - ... <14> - }, - "SecondProducer": { <15> - "carrierTechnologyParameters":{...}, <16> - "eventProtocolParameters":{...}, <17> - ... <18> - } -} ----- -<1> input interface configuration, APEX input plugins -<2> first input called `FirstConsumer` -<3> carrier technology for plugin -<4> event protocol for plugin -<5> any other input configuration (e.g. event name filter, see below) -<6> second input called `SecondConsumer` -<7> carrier technology for plugin -<8> event protocol for plugin -<9> any other plugin configuration -<10> output interface configuration, APEX output plugins -<11> first output called `FirstProducer` -<12> carrier technology for plugin -<13> event protocol for plugin -<14> any other plugin configuration -<15> second output called `SecondProducer` -<16> carrier technology for plugin -<17> event protocol for plugin -<18> any other output configuration (e.g. event name filter, see below) - -=== Event Filters - -APEX will always send an event after a policy execution is finished. -For a successful execution, the event sent is the output event created by the policy. -In case the policy does not create an output event, APEX will create a new event with all input event fields plus an additional field `exceptionMessage` with an exception message. - -There are situations in which this auto-generated error event might not be required or wanted: - -* when a policy failing should not result in an event send out via an output interface -* when the auto-generated event goes back in an APEX engine (or the same APEX engine), this can create endless loops -* the auto-generated event should go to a special output interface or channel - -All of these situations are supported by a filter option using a wildecard (regular expression) configuration on APEX I/O interfaces. -The parameter is called `eventNameFilter` and the value are link:https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java regular expressions] (a link:http://www.vogella.com/tutorials/JavaRegularExpressions/article.html[tutorial]). -The following code shows some examples: - -[source%nowrap,json] ----- -"eventInputParameters": { - "Input1": { - "carrierTechnologyParameters" : {...}, - "eventProtocolParameters":{...}, - "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]004$" <1> - } -}, -"eventOutputParameters": { - "Output1": { - "carrierTechnologyParameters":{...}, - "eventProtocolParameters":{...}, - "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]104$" <2> - } -} ----- diff --git a/services/services-engine/src/site-docs/adoc/fragments/config-service-parameters.adoc b/services/services-engine/src/site-docs/adoc/fragments/config-service-parameters.adoc deleted file mode 100644 index d1b3fa3b9..000000000 --- a/services/services-engine/src/site-docs/adoc/fragments/config-service-parameters.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// -// ============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) -// - -== Engine Service Parameters - -The configuration provides a number of parameters to configure the engine. -An example configuration with explanations of all options is shown below. - -[source%nowrap,json] ----- -"engineServiceParameters" : { - "name" : "AADMApexEngine", // <1> - "version" : "0.0.1", // <2> - "id" : 45, // <3> - "instanceCount" : 4, // <4> - "deploymentPort" : 12345, // <5> - "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", // <6> - "periodicEventPeriod": 1000, <7> - "engineParameters":{ <8> - "engineParameters":{...}, <9> - "contextParameters":{...} <10> - } -} ----- -<1> a name for the engine. The engine name is used to create a key in a runtime engine. An name matching the following regular expression can be used here: `[A-Za-z0-9\\-_\\.]+` -<2> a version of the engine, use semantic versioning as explained here: link:http://semver.org/[Semantic Versioning]. This version is used in a runtime engine to create a version of the engine. For that reason, the version must match the following regular expression `[A-Z0-9.]+` -<3> a numeric identifier for the engine -<4> the number of threads (policy instances executed in parallel) the engine should use, use `1` for single threaded engines -<5> the port for the deployment Websocket connection to the engine -<6> the model file to load into the engine on startup (optional) -<7> an optional timer for periodic policies, in milliseconds (a defined periodic policy will be executed every `X` milliseconds), not used of not set or `0` -<8> engine parameters for plugin configurations (execution environments and context handling) -<9> engine specific parameters, mainly for executor plugins -<10> context specific parameters, e.g. for context schemas, persistence, etc. - -The model file is optional, it can also be specified via command line. -In any case, make sure all execution and other required plug-ins for the loaded model are loaded as required. -- cgit 1.2.3-korg