Add docs for tools package & update main apex-pdp

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

3 files changed, 178 insertions, 0 deletions

diff --git a/tools/simple-wsclient/src/site-docs/adoc/fragments/clients.adoc b/tools/simple-wsclient/src/site-docs/adoc/fragments/clients.adoc
new file mode 100644
index 000000000..e1531bf79
--- /dev/null
+++ b/tools/simple-wsclient/src/site-docs/adoc/fragments/clients.adoc
@@ -0,0 +1,22 @@
+//
+// ============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)
+//
+
+== Simple Websocket Clients
+
+In a full installation, the APEX applications provide two demo Websocket clients: echo and console.
+The __echo__ client connects to a Websocket server and prints all events it receives (reading text/string from Websocket).
+The __console__ client connects to a Websocket server, takes strings from the console (multi-line JSON encoded string starting with ‘{‘ and ending with ‘}’) and sends them as text via a Websocket.
+
+Both demo clients use `Java-WebSocket` and have no further dependency on APEX:
+
+- link:https://search.maven.org/#artifactdetails%7Corg.java-websocket%7CJava-WebSocket%7C1.3.4%7Cjar[Websocket implementation]
diff --git a/tools/simple-wsclient/src/site-docs/adoc/fragments/run-console.adoc b/tools/simple-wsclient/src/site-docs/adoc/fragments/run-console.adoc
new file mode 100644
index 000000000..04d37613a
--- /dev/null
+++ b/tools/simple-wsclient/src/site-docs/adoc/fragments/run-console.adoc
@@ -0,0 +1,77 @@
+//
+// ============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)
+//
+
+== Run the Websocket Console Client
+
+The console client is included in an APEX full installation.
+To run the client, open a new shell (Unix, Cygwin) or command prompt (`cmd` on Windows).
+Then use the APEX application launcher to start the client.
+
+[IMPORTANT]
+.APEX engine needs to run first
+====
+The example assumes that an APEX engine configured for __consume__ carrier technology Websocket and __JSON__ event protocol is executed first.
+====
+
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh ws-console [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat ws-console [args]
+----
+|====================
+
+Use the following command line arguments for server and port of the Websocket server.
+The port should be the same as configured in the APEX engine.
+The server host should be the host on which the APEX engine is running
+
+- `-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`)
+
+Let's assume that there is an APEX engine running, configured for consume Websocket carrier technology, as server, for port 42450, with consume event protocol JSON,.
+If we start the console client on the same host, we can omit the `-s` options.
+We start the console client as:
+
+[source%nowrap,bat]
+----
+# $APEX_HOME/bin/apexApps.sh ws-console -p 42450 <1>
+> %APEX_HOME%\bin\apexApps.sh ws-console -p 42450 <2>
+----
+<1> Start client on Unix or Cygwin
+<2> Start client on Windows
+
+Once started successfully, the client will produce the following messages (assuming we used `-p 42450` and an APEX engine is running on `localhost` with the same port:
+
+[source%nowrap,bat]
+----
+
+ws-simple-console: starting simple event console
+ --> server: localhost
+ --> port: 42450
+
+ - terminate the application typing 'exit<enter>' or using 'CTRL+C'
+ - events are created by a non-blank starting line and terminated by a blank line
+
+
+ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake)
+
+----
+
diff --git a/tools/simple-wsclient/src/site-docs/adoc/fragments/run-echo.adoc b/tools/simple-wsclient/src/site-docs/adoc/fragments/run-echo.adoc
new file mode 100644
index 000000000..213b4acbc
--- /dev/null
+++ b/tools/simple-wsclient/src/site-docs/adoc/fragments/run-echo.adoc
@@ -0,0 +1,79 @@
+//
+// ============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)
+//
+
+== Run the Websocket Echo Client
+
+The echo client is included in an APEX full installation.
+To run the client, open a new shell (Unix, Cygwin) or command prompt (`cmd` on Windows).
+Then use the APEX application launcher to start the client.
+
+[IMPORTANT]
+.APEX engine needs to run first
+====
+The example assumes that an APEX engine configured for __produce__ carrier technology Websocket and __JSON__ event protocol is executed first.
+====
+
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh]
+----
+# $APEX_HOME/bin/apexApps.sh ws-echo [args]
+----
+|
+[source%nowrap,bat]
+----
+> %APEX_HOME%\bin\apexApps.bat ws-echo [args]
+----
+|====================
+
+Use the following command line arguments for server and port of the Websocket server.
+The port should be the same as configured in the APEX engine.
+The server host should be the host on which the APEX engine is running
+
+- `-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`)
+
+Let's assume that there is an APEX engine running, configured for produce Websocket carrier technology, as server, for port 42452, with produce event protocol JSON,.
+If we start the console client on the same host, we can omit the `-s` options.
+We start the console client as:
+
+[source%nowrap,bat]
+----
+# $APEX_HOME/bin/apexApps.sh ws-echo -p 42452 <1>
+> %APEX_HOME%\bin\apexApps.bat ws-echo -p 42452 <2>
+----
+<1> Start client on Unix or Cygwin
+<2> Start client on Windows
+
+Once started successfully, the client will produce the following messages (assuming we used `-p 42452` and an APEX engine is running on `localhost` with the same port:
+
+[source%nowrap,bat]
+----
+
+
+ws-simple-echo: starting simple event echo
+ --> server: localhost
+ --> port: 42452
+
+Once started, the application will simply print out all received events to standard out.
+Each received event will be prefixed by '---' and suffixed by '===='
+
+
+ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake)
+
+
+----
+