Adding first set of apex-pdp document changes

Adding document changes for auth, context, core, model, services & the
main apex-pdp module.

Change-Id: Id0d026baa258f1dc6998978f9911f3c4a73b5b3b
Issue-ID: POLICY-867
Signed-off-by: ramverma <ram.krishna.verma@ericsson.com>

8 files changed, 460 insertions, 0 deletions

diff --git a/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc
new file mode 100644
index 000000000..f1a8a003f
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc
@@ -0,0 +1,34 @@
+//
+// ============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)
+//
+
+== Checkstyle with Maven
+
+The codestyle for all APEX java projects can be checked automatically.
+The checks include empty or non-existing Javadocs.
+Any checkstyle run should complete without any errors, some warnings are acceptable.
+
+To run checkstyle on an APEX Maven project use:
+
+[source%nowrap,sh]
+----
+mvn checkstyle:check
+----
+
+
+To run checkstyle on all modules use:
+
+[source%nowrap,sh]
+----
+mvn checkstyle:checkstyle -DapexAll
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-build/documentation.adoc b/src/site-docs/adoc/fragments/howto-build/documentation.adoc
new file mode 100644
index 000000000..3a42cc78b
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/documentation.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)
+//
+
+== Build the APEX Documentation
+
+The APEX Maven build also includes stand-alone documentations, such as the HowTo documents, the Installation Guide, and the User Manual.
+Use Maven to build the APEX Documentation.
+The Maven options `-N` prevents Maven to go through all APEX modules, which is not necessary for the documentation.
+The final documents will be in `target/generated-docs` (Windows: `target\generated-docs`).
+The __HTML__ documents are in the `html/` folder, the __PDF__ documents are in the `pdf/` folder.
+Once the documentation is build, copy the __HTML__ and __PDF__ documents to a folder of choice
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh,numbered]
+----
+# cd /usr/local/src/apex
+# mvn clean generate-resources -N -DapexDocs
+----
+|
+[source%nowrap,bat,numbered]
+----
+>c:
+>cd \dev\apex
+>mvn clean generate-resources -N -DapexDocs
+----
+|====================
+
+
diff --git a/src/site-docs/adoc/fragments/howto-build/introduction.adoc b/src/site-docs/adoc/fragments/howto-build/introduction.adoc
new file mode 100644
index 000000000..02ba21fbd
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/introduction.adoc
@@ -0,0 +1,56 @@
+//
+// ============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)
+//
+
+== Introduction to building APEX
+
+APEX is written 100% in Java and uses link:https://maven.apache.org/[Apache Maven] as the build system.
+The requirements for building APEX are:
+
+- An installed Java development kit for Java version 8 or higher
+  ** To install a Java SDK please follow these guidelines link:https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html[Oracle Java 8 SDK].
+- Maven 3
+  ** To get Maven 3 running please follow the guidelines for link:https://maven.apache.org/download.cgi[Download] and link:https://maven.apache.org/install.html[Install], and link:https://maven.apache.org/run.html[Run] Maven
+- A clone of the APEX source repositories
+
+To get a clone of the APEX source repositories, please see the APEX Installation Guide or the APEX User manual.
+
+One all requirements are in place, APEX can be build.
+There are several different artifacts one can create building APEX, most of them defined in their own __profile__.
+APEX can also be build in a standard way with standard tests (`mvn clean install`) or without standard tests (`mvn clean install -DskipTests`).
+
+The examples in this document assume that the APEX source repositories are cloned to:
+
+- Unix, Cygwin: `/usr/local/src/apex`
+- Windows: `C:\dev\apex`
+- Cygwin: `/cygdrive/c/dev/apex`
+
+[IMPORTANT]
+.A Build needs Space
+====
+Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for the downloaded dependencies
+====
+
+[IMPORTANT]
+.A Build requires Internet (for first build to download all dependencies and plugins)
+====
+During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven repository.
+The first standard build (and any first specific build) requires Internet access to download those dependencies.
+====
+
+[IMPORTANT]
+.Building RPM distributions
+====
+RPM images are only build if the `rpm` package is installed (Unix).
+To install `rpm` run `sudo apt-get install rpm`, then build APEX.
+====
+
diff --git a/src/site-docs/adoc/fragments/howto-build/site.adoc b/src/site-docs/adoc/fragments/howto-build/site.adoc
new file mode 100644
index 000000000..42cbda525
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/site.adoc
@@ -0,0 +1,93 @@
+//
+// ============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)
+//
+
+== Build APEX Site
+
+The APEX Maven build comes with full support to build a web site using Maven Site.
+Use Maven to build the APEX Site.
+Stage the APEX web site.
+The target folder for the staged site is
+
+- Unix: `/usr/local/src/apex/target/gh-pages`
+- Windows: `C:\dev\apex\target\gh-pages`
+- Cygwin: `/cygdrive/c/dev/apex/target/gh-pages`
+
+Once the web site is staged, copy the full site to a folder of choice or into a web server.
+
+
+[IMPORTANT]
+.Building a Site takes Time
+====
+Building and staging the APEX web site can take very long.
+The stand-alone documentation will take about 2 minutes.
+The sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine
+(~10 minutes without generating source and test-source reports, closer to 30 minutes with all reports).
+====
+
+
+Start the build deleting the staging directory that might have been created by a previous site build.
+Then go to the APEX packaging directory.
+
+[width="100%",options="header",cols="5a,5a,5a"]
+|====================
+| Unix | Windows | Cygwin
+|
+[source%nowrap,sh]
+----
+cd /usr/local/src/apex
+rm -fr target/gh-pages
+----
+|
+[source%nowrap,bat]
+----
+c:
+cd \dev\apex
+rmdir /s /q target\gh-pages
+----
+|
+[source%nowrap,sh]
+----
+cd /cygdrive/c/dev/apex
+rm -fr target/gh-pages
+----
+|====================
+
+the workflow for building a complete site then is as follows:
+
+[source%nowrap,sh]
+----
+mvn clean -DapexAll #<1>
+mvn install -DskipTests #<2>
+mvn generate-resources -N -DapexDocs #<3>
+mvn initialize site:attach-descriptor site site:stage -DapexSite #<4>
+----
+. First clean all modules to remove any site artifacts, use the _apexXtext_ profile to make sure these modules are processed as well
+. Next run a simple install without tests
+. Now generate the APEX stand -alone documentation, they are in the local package only so we can use the _-N_ switch
+. Last build the actual sites and stage (copy to the staging directory) with the profile _apexSite_ (do not forget the initialize goal, otherwise the staging directory will not be correctly set and sites are staged in every model in a directory called `docs`).
+
+If you want to build the site for a particular project for testing, the Maven command is simpler.
+Since only the main project has APEX documentation (stand-alone), you can use Maven as follow.
+
+[source%nowrap,sh]
+----
+mvn clean site -DapexSite
+----
+
+If you want to stage the tested site, then use
+
+[source%nowrap,sh]
+----
+mvn clean initialize site:attach-descriptor site site:stage -DapexSite
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-build/standard.adoc b/src/site-docs/adoc/fragments/howto-build/standard.adoc
new file mode 100644
index 000000000..76ebfc2bf
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/standard.adoc
@@ -0,0 +1,86 @@
+//
+// ============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 Build
+
+Use Maven to for a standard build without any tests.
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh,numbered]
+----
+# cd /usr/local/src/apex
+# mvn clean install -DskipTests
+----
+|
+[source%nowrap,bat,numbered]
+----
+>c:
+>cd \dev\apex
+>mvn clean install -DskipTests
+----
+|====================
+
+The build takes 2-3 minutes on a standard development laptop.
+It should run through without errors, but with a lot of messages from the build process.
+
+When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines):
+
+[source%nowrap,sh,numbered,subs="attributes+"]
+----
+include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests]
+----
+
+
+The build will have created all artifacts required for an APEX installation.
+The following example show how to change to the target directory and how it should look like.
+
+[width="100%",options="header",cols="a"]
+|====================
+| Unix, Cygwin
+|
+[source%nowrap,sh,numbered]
+----
+# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target
+# ls -l
+----
+
+|
+[source%nowrap,sh,numbered,subs="attributes+"]
+----
+include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix]
+----
+
+|====================
+
+
+[width="100%",options="header",cols="a"]
+|====================
+| Windows
+|
+[source%nowrap,bat,numbered]
+----
+>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target
+>dir
+----
+
+|
+[source%nowrap,sh,numbered,subs="attributes+"]
+----
+include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows]
+----
+
+|====================
+
diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc
new file mode 100644
index 000000000..4cd08cf0d
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc
@@ -0,0 +1,43 @@
+//
+// ============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)
+//
+
+== Build with all Components
+
+A standard APEX build will not build all components.
+Some parts are for specific deployments, only.
+Use Maven to for a standard build with __all__ components.
+
+[IMPORTANT]
+.Might require specific software
+====
+When building all components, some modules require specific software installed on the build machine.
+====
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh,numbered]
+----
+# cd /usr/local/src/apex
+# mvn clean install -DapexAll
+----
+|
+[source%nowrap,bat,numbered]
+----
+>c:
+>cd \dev\apex
+>mvn clean install -DapexAll
+----
+|====================
+
diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc
new file mode 100644
index 000000000..6fa654d00
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc
@@ -0,0 +1,50 @@
+//
+// ============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)
+//
+
+== Build with all Tests
+
+Use Maven to for a standard build with __all__ tests.
+
+[IMPORTANT]
+.Some tests have specific timing Requirements
+====
+Some of the tests have very specific timing requirements.
+If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well.
+If this happens, reduce the load on your build machine and restart the build.
+====
+
+[IMPORTANT]
+.Might require specific software
+====
+When running all tests, some modules require specific software installed on the build machine.
+For instance, testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan installed on the build machine.
+====
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh,numbered]
+----
+# cd /usr/local/src/apex
+# mvn clean install -DallTests
+----
+|
+[source%nowrap,bat,numbered]
+----
+>c:
+>cd \dev\apex
+>mvn clean install -DallTests
+----
+|====================
+
diff --git a/src/site-docs/adoc/fragments/howto-build/with-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc
new file mode 100644
index 000000000..f8d300c45
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc
@@ -0,0 +1,57 @@
+//
+// ============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)
+//
+
+== Build with standard Tests
+
+Use Maven to for a standard build with standard tests.
+
+[IMPORTANT]
+.Some tests have specific timing Requirements
+====
+Some of the tests have very specific timing requirements.
+If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well.
+If this happens, reduce the load on your build machine and restart the build.
+====
+
+[width="100%",options="header",cols="5a,5a"]
+|====================
+| Unix, Cygwin | Windows
+|
+[source%nowrap,sh,numbered]
+----
+# cd /usr/local/src/apex
+# mvn clean install
+----
+|
+[source%nowrap,bat,numbered]
+----
+>c:
+>cd \dev\apex
+>mvn clean install
+----
+|====================
+
+The build takes about 5-6 minutes with tests on a standard development laptop.
+It should run through without errors, but with a lot of messages from the build process.
+If build with tests (i.e. without `-DskipTests`), there will be error messages and stack trace prints from some tests.
+This is normal, as long as the build finishes successful.
+
+When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines):
+
+[source%nowrap,sh,numbered,subs="attributes+"]
+----
+include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, with tests]
+----
+
+The build will have created all artifacts required for an APEX installation.
+