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 --- .../src/site-docs/adoc/fragments/ct-jms-io.adoc | 93 -------------- .../src/site-docs/adoc/fragments/ct-kafka-io.adoc | 114 ------------------ .../site-docs/adoc/fragments/ct-restclient-io.adoc | 63 ---------- .../adoc/fragments/ct-restrequestor-io.adoc | 86 ------------- .../site-docs/adoc/fragments/ct-restserver-io.adoc | 134 --------------------- .../site-docs/adoc/fragments/ct-websocket-io.adoc | 75 ------------ .../adoc/fragments/engine-config-bcp.adoc | 29 ----- .../src/site-docs/adoc/fragments/ws-foss.adoc | 27 ----- .../src/site-docs/adoc/fragments/ws-intro.adoc | 23 ---- .../src/site-docs/adoc/fragments/ws-java.adoc | 20 --- .../src/site-docs/adoc/fragments/carriertech.adoc | 41 ------- .../adoc/fragments/ct-eventrequestor-io.adoc | 92 -------------- .../src/site-docs/adoc/fragments/ct-file-io.adoc | 53 -------- .../site-docs/adoc/fragments/ct-standard-io.adoc | 52 -------- 14 files changed, 902 deletions(-) delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-jms/src/site-docs/adoc/fragments/ct-jms-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-kafka/src/site-docs/adoc/fragments/ct-kafka-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restclient/src/site-docs/adoc/fragments/ct-restclient-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restrequestor/src/site-docs/adoc/fragments/ct-restrequestor-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restserver/src/site-docs/adoc/fragments/ct-restserver-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ct-websocket-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/engine-config-bcp.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-foss.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-intro.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-java.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc delete mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-standard-io.adoc (limited to 'plugins/plugins-event/plugins-event-carrier') diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-jms/src/site-docs/adoc/fragments/ct-jms-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-jms/src/site-docs/adoc/fragments/ct-jms-io.adoc deleted file mode 100644 index 940857169..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-jms/src/site-docs/adoc/fragments/ct-jms-io.adoc +++ /dev/null @@ -1,93 +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) -// - -== JMS IO - -APEX supports the Java Messaging Service (JMS) as input as well as output. -JMS IO is supported by the APEX JMS plugin. -Input and output support an event encoding as text (JSON string) or object (serialized object). -The input configuration is the same for both encodings, the output configuration differs. - - -=== JMS Input - -APEX will receive events from a JMS messaging system. -The input is uni-directional, an engine will only receive events from the input but not send any event to the input. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "JMS", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters", - "parameters" : { <2> - "initialContextFactory" : - "org.jboss.naming.remote.client.InitialContextFactory", <3> - "connectionFactory" : "ConnectionFactory", <4> - "providerURL" : "remote://localhost:5445", <5> - "securityPrincipal" : "guest", <6> - "securityCredentials" : "IAmAGuest", <7> - "consumerTopic" : "jms/topic/apexIn" <8> - } -} ----- - -<1> set JMS as carrier technology -<2> set all JMS specific parameters -<3> the context factory, in this case from JBOSS (it requires the dependency org.jboss:jboss-remote-naming:2.0.4.Final or a different version to be in the directory `$APEX_HOME/lib` or `%APEX_HOME%\lib` -<4> a connection factory for the JMS connection -<5> URL with host and port of the JMS provider -<6> access credentials, user name -<7> access credentials, user password -<8> the JMS topic to listen to - - -=== JMS Output with Text - -APEX engine send events to a JMS messaging system. -The output is uni-directional, an engine will send events to the output but not receive any event from output. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "JMS", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters", - "parameters" : { <2> - "initialContextFactory" : - "org.jboss.naming.remote.client.InitialContextFactory", <3> - "connectionFactory" : "ConnectionFactory", <4> - "providerURL" : "remote://localhost:5445", <5> - "securityPrincipal" : "guest", <6> - "securityCredentials" : "IAmAGuest", <7> - "producerTopic" : "jms/topic/apexOut", <8> - "objectMessageSending": "false" <9> - } -} ----- - -<1> set JMS as carrier technology -<2> set all JMS specific parameters -<3> the context factory, in this case from JBOSS (it requires the dependency org.jboss:jboss-remote-naming:2.0.4.Final or a different version to be in the directory `$APEX_HOME/lib` or `%APEX_HOME%\lib` -<4> a connection factory for the JMS connection -<5> URL with host and port of the JMS provider -<6> access credentials, user name -<7> access credentials, user password -<8> the JMS topic to write to -<9> set object messaging to `false` means it sends JSON text - - -=== JMS Output with Object - -To configure APEX for JMS objects on the output interface use the same configuration as above (for output). -Simply change the `objectMessageSending` parameter to `true`. diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-kafka/src/site-docs/adoc/fragments/ct-kafka-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-kafka/src/site-docs/adoc/fragments/ct-kafka-io.adoc deleted file mode 100644 index 94586e9bd..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-kafka/src/site-docs/adoc/fragments/ct-kafka-io.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// -// ============LICENSE_START======================================================= -// Copyright (C) 2016-2018 Ericsson. All rights reserved. -// Modifications Copyright (C) 2019 Nordix Foundation. -// ================================================================================ -// 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) -// - -== Kafka IO - -Kafka IO is supported by the APEX Kafka plugin. -The configurations below are examples. -APEX will take any configuration inside the parameter object and forward it to Kafka. -More information on Kafka specific configuration parameters can be found in the Kafka documentation: - -* link:https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html[Kafka Consumer Class] -* link:https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html[Kafka Producer Class] - - - -=== Kafka Input - -APEX will receive events from the Apache Kafka messaging system. -The input is uni-directional, an engine will only receive events from the input but not send any event to the input. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "KAFKA", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters", - "parameters" : { - "bootstrapServers" : "localhost:49092", <2> - "groupId" : "apex-group-id", <3> - "enableAutoCommit" : true, <4> - "autoCommitTime" : 1000, <5> - "sessionTimeout" : 30000, <6> - "consumerPollTime" : 100, <7> - "consumerTopicList" : ["apex-in-0", "apex-in-1"], <8> - "keyDeserializer" : - "org.apache.kafka.common.serialization.StringDeserializer", <9> - "valueDeserializer" : - "org.apache.kafka.common.serialization.StringDeserializer", <10> - "kafkaProperties" : [] <11> - } -} ----- - -<1> set Kafka as carrier technology -<2> bootstrap server and port -<3> a group identifier -<4> flag for auto-commit -<5> auto-commit timeout in milliseconds -<6> session timeout in milliseconds -<7> consumer poll time in milliseconds -<8> consumer topic list -<9> key for the Kafka de-serializer -<10> value for the Kafka de-serializer -<11> an optional list of name value pairs of properties to be passed transparently to Kafka. -This field need not be specified, can be set to null, or to an empty list as here. - - -=== Kafka Output - -APEX will send events to the Apache Kafka messaging system. -The output is uni-directional, an engine will send events to the output but not receive any event from the output. - - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "KAFKA", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters", - "parameters" : { - "bootstrapServers" : "localhost:49092", <2> - "acks" : "all", <3> - "retries" : 0, <4> - "batchSize" : 16384, <5> - "lingerTime" : 1, <6> - "bufferMemory" : 33554432, <7> - "producerTopic" : "apex-out", <8> - "keySerializer" : - "org.apache.kafka.common.serialization.StringSerializer", <9> - "valueSerializer" : - "org.apache.kafka.common.serialization.StringSerializer", <10> - "kafkaProperties": [ <11> - ["message.max.bytes", 1000000], - ["compression.codec", "none"] - ] - } -} ----- - -<1> set Kafka as carrier technology -<2> bootstrap server and port -<3> acknowledgement strategy -<4> number of retries -<5> batch size -<6> time to linger in milliseconds -<7> buffer memory in byte -<8> producer topic -<9> key for the Kafka serializer -<10> value for the Kafka serializer -<11> an optional list of name value pairs of properties to be passed transparently to Kafka. If a property appears in -the _kafkaProperties_ field and is also explicitly specified to a non-default value (such as _lingerTime_ -and _linger.ms_) the explictly specified value of the property is used rather than the value specified in the -_kafkaProperties_ list. diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restclient/src/site-docs/adoc/fragments/ct-restclient-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restclient/src/site-docs/adoc/fragments/ct-restclient-io.adoc deleted file mode 100644 index 64782a8bc..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restclient/src/site-docs/adoc/fragments/ct-restclient-io.adoc +++ /dev/null @@ -1,63 +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) -// - -== REST Client IO - -APEX can act as REST client on the input as well as on the output interface. -The media type is `application/json`, so this plugin does only work with the JSON Event protocol. - -=== REST Client Input - -APEX will connect to a given URL to receive events, but not send any events. -The server is polled, i.e. APEX will do an HTTP GET, take the result, and then do the next GET. -Any required timing needs to be handled by the server configured via the URL. -For instance, the server could support a wait timeout via the URL as `?timeout=100ms`. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "RESTCLIENT", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters", - "parameters" : { - "url" : "http://example.org:8080/triggers/events", <2> - } -} ----- - -<1> set REST client as carrier technology -<2> the URL of the HTTP server for events - - -=== REST Client Output - -APEX will connect to a given URL to send events, but not receive any events. -The default HTTP operation is POST (no configuration required). -To change it to PUT simply add the configuration parameter (as shown in the example below). - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "RESTCLIENT", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters", - "parameters" : { - "url" : "http://example.com:8888/actions/events", <2> - "httpMethod" : "PUT" <3> - } -} ----- - -<1> set REST client as carrier technology -<2> the URL of the HTTP server for events -<3> use HTTP PUT (remove this line to use HTTP POST) diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restrequestor/src/site-docs/adoc/fragments/ct-restrequestor-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restrequestor/src/site-docs/adoc/fragments/ct-restrequestor-io.adoc deleted file mode 100644 index 320c99880..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restrequestor/src/site-docs/adoc/fragments/ct-restrequestor-io.adoc +++ /dev/null @@ -1,86 +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) -// - -== REST Requestor IO - -APEX can act as REST requestor on the input as well as on the output interface. -The media type is `application/json`, so this plugin does only work with the JSON Event protocol. - -=== REST Requestor Input - -APEX will connect to a given URL to request an input. - -[source%nowrap,json] ----- -"carrierTechnologyParameters": { - "carrierTechnology": "RESTREQUESTOR", <1> - "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters", - "parameters": { - "url": "http://localhost:54321/some/path/to/rest/resource", <2> - "httpMethod": "POST", <3> - "restRequestTimeout": 2000 <4> - } -}, ----- - -<1> set REST requestor as carrier technology -<2> the URL of the HTTP server for events -<3> use HTTP PUT (remove this line to use HTTP POST) -<4> request timeout in milliseconds - -Further settings are required on the consumer to define the event that is requested, for example: - -[source%nowrap,json] ----- -"eventName": "GuardResponseEvent", <1> -"eventNameFilter": "GuardResponseEvent", <2> -"requestorMode": true, <3> -"requestorPeer": "GuardRequestorProducer", <4> -"requestorTimeout": 500 <5> ----- - -<1> the event name -<2> a filter on the event -<3> the mode of the requestor -<4> a peer for the requestor -<5> a general request timeout - - -=== REST Requestor Output - -APEX will connect to a given URL to send events, but not receive any events. - -[source%nowrap,json] ----- -"carrierTechnologyParameters": { - "carrierTechnology": "RESTREQUESTOR", <1> - "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters" -}, ----- - -<1> set REST requestor as carrier technology - -Further settings are required on the consumer to define the event that is requested, for example: - -[source%nowrap,json] ----- -"eventNameFilter": "GuardRequestEvent", <1> -"requestorMode": true, <2> -"requestorPeer": "GuardRequestorConsumer", <3> -"requestorTimeout": 500 <4> ----- - -<1> a filter on the event -<2> the mode of the requestor -<3> a peer for the requestor -<4> a general request timeout diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restserver/src/site-docs/adoc/fragments/ct-restserver-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restserver/src/site-docs/adoc/fragments/ct-restserver-io.adoc deleted file mode 100644 index c6c9a0865..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-restserver/src/site-docs/adoc/fragments/ct-restserver-io.adoc +++ /dev/null @@ -1,134 +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) -// - -== REST Server IO - -APEX supports a REST server for input and output. - -The REST server plugin always uses a synchronous mode. -A client does a HTTP GET on the APEX REST server with the input event and receives the generated output event in the server reply. -This means that for the REST server there has to always to be an input with an associated output. -Input or output only are not permitted. - -The plugin will start a Grizzly server as REST server for a normal APEX engine. -If the APEX engine is executed as a servlet, for instance inside Tomcat, then Tomcat will be used as REST server (this case requires configuration on Tomcat as well). - -Some configuration restrictions apply for all scenarios: - -- Minimum port: 1024 -- Maximum port: 65535 -- The media type is `application/json`, so this plugin does only work with the JSON Event protocol. - -The URL the client calls is created using - -- the configured host and port, e.g. `http://localhost:12345` -- the standard path, e.g. `/apex/` -- the name of the input/output, e.g. `FirstConsumer/` -- the input or output name, e.g. `EventIn`. - -The examples above lead to the URL `http://localhost:12345/apex/FirstConsumer/EventIn`. - -A client can also get status information of the REST server using `/Status`, e.g. `http://localhost:12345/apex/FirstConsumer/Status`. - - -=== REST Server Stand-alone - -We need to configure a REST server input and a REST server output. -Input and output are associated with each other via there name. - -Timeouts for REST calls need to be set carefully. -If they are too short, the call might timeout before a policy finished creating an event. - -The following example configures the input named as `MyConsumer` and associates an output named `MyProducer` with it. - -[source%nowrap,json] ----- -"eventInputParameters": { - "MyConsumer": { - "carrierTechnologyParameters" : { - "carrierTechnology" : "RESTSERVER", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters", - "parameters" : { - "standalone" : true, <2> - "host" : "localhost", <3> - "port" : 12345 <4> - } - }, - "eventProtocolParameters":{ - "eventProtocol" : "JSON" <5> - }, - "synchronousMode" : true, <6> - "synchronousPeer" : "MyProducer", <7> - "synchronousTimeout" : 500 <8> - } -} ----- -<1> set REST server as carrier technology -<2> set the server as stand-alone -<3> set the server host -<4> set the server listen port -<5> use JSON event protocol -<6> activate synchronous mode -<7> associate an output `MyProducer` -<8> set a timeout of 500 milliseconds - - -The following example configures the output named as `MyProducer` and associates the input `MyConsumer` with it. -Note that for the output there are no more paramters (such as host or port), since they are already configured in the associated input - -[source%nowrap,json] ----- -"eventOutputParameters": { - "MyProducer": { - "carrierTechnologyParameters":{ - "carrierTechnology" : "RESTSERVER", - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters" - }, - "eventProtocolParameters":{ - "eventProtocol" : "JSON" - }, - "synchronousMode" : true, - "synchronousPeer" : "MyConsumer", - "synchronousTimeout" : 500 - } -} ----- - - -=== REST Server Stand-alone, multi input - -Any number of input/output pairs for REST servers can be configured. -For instance, we can configure an input `FirstConsumer` with output `FirstProducer` and an input `SecondConsumer` with output `SecondProducer`. -Important is that there is always one pair of input/output. - - -=== REST Server Stand-alone in Servlet - -If APEX is executed as a servlet, e.g. inside Tomcat, the configuration becomes easier since the plugin can now use Tomcat as the REST server. -In this scenario, there are not parameters (port, host, etc.) and the key `standalone` must not be used (or set to false). - -For the Tomcat configuration, we need to add the REST server plugin, e.g. - -[source%nowrap,xml] ----- - - ... - - ... - org.onap.policy.apex.plugins.event.carrier.restserver - - ... - ----- diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ct-websocket-io.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ct-websocket-io.adoc deleted file mode 100644 index 8a19cdd32..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ct-websocket-io.adoc +++ /dev/null @@ -1,75 +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) -// - -== Websocket (WS) IO - -APEX supports the Websockets as input as well as output. -WS IO is supported by the APEX Websocket plugin. -This carrier technology does only support uni-directional communication. -APEX will not send events to a Websocket input and any event sent to a Websocket output will result in an error log. - -The input can be configured as client (APEX connects to an existing Websocket server) or server (APEX starts a Websocket server). -The same applies to the output. -Input and output can both use a client or a server configuration, or separate configurations (input as client and output as server, input as server and output as client). -Each configuration should use its own dedicated port to avoid any communication loops. -The configuration of a Websocket client is the same for input and output. -The configuration of a Websocket server is the same for input and output. - - -=== Websocket Client - -APEX will connect to a given Websocket server. -As input, it will receive events from the server but not send any events. -As output, it will send events to the server and any event received from the server will result in an error log. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "WEBSOCKET", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters", - "parameters" : { - "host" : "localhost", <2> - "port" : 42451 <3> - } -} ----- - -<1> set Websocket as carrier technology -<2> the host name on which a Websocket server is running -<3> the port of that Websocket server - - - -=== Websocket Server - -APEX will start a Websocket server, which will accept any Websocket clients to connect. -As input, it will receive events from the server but not send any events. -As output, it will send events to the server and any event received from the server will result in an error log. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "WEBSOCKET", <1> - "parameterClassName" : - "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters", - "parameters" : { - "wsClient" : false, <2> - "port" : 42450 <3> - } -} ----- - -<1> set Websocket as carrier technology -<2> disable client, so that APEX will start a Websocket server -<3> the port for the Websocket server APEX will start diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/engine-config-bcp.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/engine-config-bcp.adoc deleted file mode 100644 index 227cc45bb..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/engine-config-bcp.adoc +++ /dev/null @@ -1,29 +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) -// - -== BCP: Websocket Configuration - -The probably best is to configure APEX for Websocket servers for input (ingress, consume) and output (egress, produce) interfaces. -This means that APEX will start Websocket servers on named ports and wait for clients to connect. -Advantage: once APEX is running all connectivity infrastructure is running as well. -Consequence: if APEX is not running, everyone else is in the dark, too. - -The best protocol to be used is JSON string. -Each event on any interface is then a string with a JSON encoding. -JSON string is a little bit slower than byte code, but we doubt that this will be noticeable. -A further advantage of JSON strings over Websockets with APEX starting the servers: it is very easy to connect web browsers to such a system. -Simple connect the web browser to the APEX sockets and send/read JSON strings. - -Once APEX is started you simply connect Websocket clients to it, and send/receive event. -When APEX is terminated, the Websocket servers go down, and the clients will be disconnected. -APEX does not (yet) support auto-client reconnect nor WAMP, so clients might need to be restarted or reconnected manually after an APEX boot. diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-foss.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-foss.adoc deleted file mode 100644 index 43c6f247e..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-foss.adoc +++ /dev/null @@ -1,27 +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) -// - -== Websocket Example Code for Websocket clients (FOSS) - -There are a lot of implementations and examples available on Github for Websocket clients. -If one is using Java EE 7, then one can also use the native Websocket implementation. -Good examples for clients using simply Java SE are here: - -- link:https://github.com/TooTallNate/Java-WebSocket[Websocket implementation] -- link:https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ChatClient.java[Websocket sending client example, using AWT] -- link:https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ExampleClient.java[Websocket receiving client example (simple echo client)] - -For Java EE, the native Websocket API is explained here: - -- link:http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html[Oracle docs] -- link: http://www.programmingforliving.com/2013/08/jsr-356-java-api-for-websocket-client-api.html[An example] diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-intro.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-intro.adoc deleted file mode 100644 index cbecbbe7f..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-intro.adoc +++ /dev/null @@ -1,23 +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) -// - -== Websockets - -Websocket is a protocol to run sockets of HTTP. -Since it in essence a socket, the connection is realized between a server (waiting for connections) and a client (connecting to a server). -Server/client separation is only important for connection establishment, once connected, everyone can send/receive on the same socket (as any standard socket would allow). - -Standard Websocket implementations are simple, no publish/subscribe and no special event handling. -Most servers simply send all incoming messages to all connections. -There is a PubSub definition on top of Websocket called link:http://wamp-proto.org/[WAMP]. -APEX does not support WAMP at the moment. diff --git a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-java.adoc b/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-java.adoc deleted file mode 100644 index e6c2c0163..000000000 --- a/plugins/plugins-event/plugins-event-carrier/plugins-event-carrier-websocket/src/site-docs/adoc/fragments/ws-java.adoc +++ /dev/null @@ -1,20 +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) -// - -== Websocket in Java - -In Java, link:http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html[JSR 356] defines the standard Websocket API. -This JSR is part of Jave EE 7 standard. -For Java SE, several implementations exist in open source. -Since Websockets are a stable standard and simple, most implementations are stable and ready to use. -A lot of products support Websockets, like Spring, JBoss, Netty, … there are also Kafka extensions for Websockets. diff --git a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc deleted file mode 100644 index 8ec83ab9a..000000000 --- a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc +++ /dev/null @@ -1,41 +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) -// - -== Carrier Technologies - -Carrier technologies define how APEX receives (input) and sends (output) events. -They can be used in any combination, using asynchronous or synchronous mode. -There can also be any number of carrier technologies for the input (consume) and the output (produce) interface. - -Supported _input_ technologies are: - -- Standard input, read events from the standard input (console), not suitable for APEX background servers -- File input, read events from a file -- Kafka, read events from a Kafka system -- Websockets, read events from a Websocket -- JMS, -- REST (synchronous and asynchronous), additionally as client or server -- Event Requestor, allows reading of events that have been looped back into APEX - - -Supported _output_ technologies are: - -- Standard output, write events to the standard output (console), not suitable for APEX background servers -- File output, write events to a file -- Kafka, write events to a Kafka system -- Websockets, write events to a Websocket -- JMS -- REST (synchronous and asynchronous), additionally as client or server -- Event Requestor, allows events to be looped back into APEX - -New carrier technologies can be added as plugins to APEX or developed outside APEX and added to an APEX deployment. diff --git a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc deleted file mode 100644 index d8756bfcb..000000000 --- a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc +++ /dev/null @@ -1,92 +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) -// - -== Event Requestor IO - -Event Requestor IO does not require a specific plugin, it is supported be default. -It should only be used with the APEX event protocol. - -=== Event Requestor Input - -APEX will take events from APEX. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology": "EVENT_REQUESTOR" // <1> -} ----- -<1> set event requestor input - - -=== Event Requestor Output - -APEX will write events to APEX. - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology": "EVENT_REQUESTOR" // <1> -} ----- - -=== Peering Event Requestors - -When using event requestors, they need to be peered. -This means an event requestor output needs to be peered (associated) with an event requestor input. -The following example shows the use of an event requestor with the APEX event protocol and the peering of output and input. - -[source%nowrap,json] ----- -"eventInputParameters": { - "EventRequestorConsumer": { - "carrierTechnologyParameters": { - "carrierTechnology": "EVENT_REQUESTOR" // <1> - }, - "eventProtocolParameters": { - "eventProtocol": "APEX" // <2> - }, - "eventNameFilter": "InputEvent", // <3> - "requestorMode": true, // <4> - "requestorPeer": "EventRequestorProducer", // <5> - "requestorTimeout": 500 // <6> - } -}, -"eventOutputParameters": { - "EventRequestorProducer": { - "carrierTechnologyParameters": { - "carrierTechnology": "EVENT_REQUESTOR" <7> - }, - "eventProtocolParameters": { - "eventProtocol": "APEX" <8> - }, - "eventNameFilter": "EventListEvent", // <9> - "requestorMode": true, // <10> - "requestorPeer": "EventRequestorConsumer", // <11> - "requestorTimeout": 500 // <12> - } -} ----- - -<1> event requestor on a consumer -<2> with APEX event protocol -<3> optional filter (best to use a filter to prevent unwanted events on the consumer side) -<4> activate requestor mode -<5> the peer to the output (must match the output carrier) -<6> an optional timeout in milliseconds -<7> event requestor on a producer -<8> with APEX event protocol -<9> optional filter (best to use a filter to prevent unwanted events on the consumer side) -<10> activate requestor mode -<11> the peer to the output (must match the input carrier) -<12> an optional timeout in milliseconds diff --git a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc deleted file mode 100644 index bdde9e982..000000000 --- a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc +++ /dev/null @@ -1,53 +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) -// - -== File IO - -File IO does not require a specific plugin, it is supported be default. - -=== File Input - -APEX will take events from a file. -The same file should not be used as an output. -The configuration is as follows: - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", // <1> - "parameters" : { - "fileName" : "examples/events/SampleDomain/EventsIn.xmlfile" // <2> - } -} ----- -<1> set file input -<2> the name of the file to read events from - - -=== File Output - -APEX will write events to a file. -The same file should not be used as an input. -The configuration is as follows: - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", // <1> - "parameters" : { - "fileName" : "examples/events/SampleDomain/EventsOut.xmlfile" // <2> - } -} ----- -<1> set file output -<2> the name of the file to write events to diff --git a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-standard-io.adoc b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-standard-io.adoc deleted file mode 100644 index 43b7bddbb..000000000 --- a/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-standard-io.adoc +++ /dev/null @@ -1,52 +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) -// - -== Standard IO - -Standard IO does not require a specific plugin, it is supported be default. - -=== Standard Input - -APEX will take events from its standard input. -This carrier is good for testing, but certainly not for a use case where APEX runs as a server. -The configuration is as follows: - ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", // <1> - "parameters" : { - "standardIO" : true <2> - } -} ----- -<1> standard input is considered a file -<2> file descriptor set to standard input - - -=== Standard Output - -APEX will send events to its standard output. -This carrier is good for testing, but certainly not for a use case where APEX runs as a server. -The configuration is as follows: - -[source%nowrap,json] ----- -"carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", // <1> - "parameters" : { - "standardIO" : true <2> - } -} ----- -<1> standard output is considered a file -<2> file descriptor set to standard output -- cgit 1.2.3-korg