Adding Apex docs for Plugins module

Change-Id: Icf68473b472a5896972de5b07b275682a77a1c9f
Signed-off-by: Dinh Danh Le <dinh.danh.le@ericsson.com>
Issue-ID: POLICY-867

4 files changed, 238 insertions, 0 deletions

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
new file mode 100644
index 000000000..8ec83ab9a
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc
@@ -0,0 +1,41 @@
+//
+// ============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
new file mode 100644
index 000000000..d8756bfcb
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc
@@ -0,0 +1,92 @@
+//
+// ============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
new file mode 100644
index 000000000..bdde9e982
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc
@@ -0,0 +1,53 @@
+//
+// ============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
new file mode 100644
index 000000000..43b7bddbb
--- /dev/null
+++ b/plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-standard-io.adoc
@@ -0,0 +1,52 @@
+//
+// ============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