From 669915c559fb9bcd4a8f8d5239f0b9b6ab33436b Mon Sep 17 00:00:00 2001 From: Dinh Danh Le Date: Sun, 5 Aug 2018 09:54:13 +0100 Subject: Adding Apex docs for Plugins module Change-Id: Icf68473b472a5896972de5b07b275682a77a1c9f Signed-off-by: Dinh Danh Le Issue-ID: POLICY-867 --- .../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 ++++++++++++ 4 files changed, 238 insertions(+) create mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/carriertech.adoc create mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-eventrequestor-io.adoc create mode 100644 plugins/plugins-event/plugins-event-carrier/src/site-docs/adoc/fragments/ct-file-io.adoc create 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/src/site-docs') 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 -- cgit 1.2.3-korg