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, 438 insertions, 0 deletions

diff --git a/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc b/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc
new file mode 100644
index 000000000..788894572
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/example-logic.adoc
@@ -0,0 +1,64 @@
+//
+// ============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)
+//
+
+== Example Configuration for Logging Logic
+
+The following example shows a configuration that logs policy logic to standard out (__info__) and a file (__debug__)
+All other APEX components are logging to a file (__debug__) and standard out (__error__).
+This configuration an be used in a pre-production phase with the APEX engine still running in a separate terminal to monitor policy execution.
+This logback configuration is in the APEX installation as `etc/logback-logic.xml`
+
+[source%nowrap,xml]
+----
+<configuration debug="false">
+  <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
+
+  <contextName>Apex</contextName>
+  <property name="VAR_LOG" value="/var/log/ericsson/apex/" />
+
+  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+    <encoder>
+      <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
+    </encoder>
+  </appender>
+
+  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
+    <file>${VAR_LOG}/apex.log</file>
+    <encoder>
+      <pattern>
+        %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
+      </pattern>
+    </encoder>
+  </appender>
+
+  <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+    <encoder>
+      <pattern>policy: %msg\n</pattern>
+    </encoder>
+  </appender>
+
+  <root level="error">
+    <appender-ref ref="STDOUT" />
+  </root>
+
+<logger name="org.onap.policy.apex" level="debug" additivity="false">
+  <appender-ref ref="FILE" />
+</logger>
+
+  <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false">
+    <appender-ref ref="POLICY_APPENDER_STDOUT" />
+    <appender-ref ref="FILE" />
+  </logger>
+</configuration>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/example-server.adoc b/src/site-docs/adoc/fragments/howto-logging/example-server.adoc
new file mode 100644
index 000000000..b438bd4a7
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/example-server.adoc
@@ -0,0 +1,46 @@
+//
+// ============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)
+//
+
+== Example Configuration for a Production Server
+
+The following example shows a configuration that logs all APEX components, including policy logic, to a file (__debug__).
+This configuration an be used in a production phase with the APEX engine being executed as a service on a system without console output.
+This logback configuration is in the APEX installation as `logback-server.xml`
+
+[source%nowrap,xml]
+----
+<configuration debug="false">
+  <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
+
+  <contextName>Apex</contextName>
+  <property name="VAR_LOG" value="/var/log/ericsson/apex/" />
+
+  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
+    <file>${VAR_LOG}/apex.log</file>
+    <encoder>
+      <pattern>
+        %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
+      </pattern>
+    </encoder>
+  </appender>
+
+  <root level="debug">
+    <appender-ref ref="FILE" />
+  </root>
+
+  <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false">
+    <appender-ref ref="FILE" />
+  </logger>
+</configuration>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/introduction.adoc b/src/site-docs/adoc/fragments/howto-logging/introduction.adoc
new file mode 100644
index 000000000..0bc37c58d
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/introduction.adoc
@@ -0,0 +1,39 @@
+//
+// ============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 APEX Logging
+
+All APEX components make extensive use of logging using the logging façade link:https://www.slf4j.org/[SLF4J] with the backend link:https://logback.qos.ch/[Logback].
+Both are used off-the-shelve, so the standard documentation and configuration apply to APEX logging.
+For details on how to work with logback please see the link:https://logback.qos.ch/manual/index.html[logback manual].
+
+The APEX applications is the logback configuration file `$APEX_HOME/etc/logback.xml` (Windows: `%APEX_HOME%\etc\logback.xml`).
+The logging backend is set to no debug, i.e. logs from the logging framework should be hidden at runtime.
+
+The configurable log levels work as expected:
+
+- __error__ (or __ERROR__) is used for serious errors in the APEX runtime engine
+- __warn__ (or __WARN__) is used for warnings, which in general can be ignored but might indicate some deeper problems
+- __info__ (or __INFO__) is used to provide generally interesting messages for startup and policy execution
+- __debug__ (or __DEBUG__) provides more details on startup and policy execution
+- __trace__ (or __TRACE__) gives full details on every aspect of the APEX engine from start to end
+
+The loggers can also be configured as expected.
+The standard configuration (after installing APEX) uses log level __info__ on all APEX classes (components).
+
+The applications and scripts in `$APEX_HOME/bin` (Windows: `%APEX_HOME\bin`) are configured to use the logback configuration `$APEX_HOME/etc/logback.xml` (Windows: `%APEX_HOME\etc\logback.xml`).
+There are multiple ways to use different logback configurations, for instance:
+
+- Maintain multiple configurations in `etc`, for instance a `logback-debug.xml` for deep debugging and a `logback-production.xml` for APEX in production mode, then copy the required configuration file to the used `logback.xml` prior starting APEX
+- Edit the scripts in `bin` to use a different logback configuration file (only recommended if you are familiar with editing bash scripts or windows batch files)
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc b/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc
new file mode 100644
index 000000000..985fa6dac
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/logback-status.adoc
@@ -0,0 +1,31 @@
+//
+// ============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)
+//
+
+== Adding Logback Status and Debug
+
+To activate logback status messages change the status listener from 'NOP' to for instance console.
+
+[source%nowrap,xml]
+----
+<statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />
+----
+
+To activate all logback debugging, for instance to debug a new logback configuration, activate the debug attribute in the configuration.
+
+[source%nowrap,xml]
+----
+<configuration debug="true">
+...
+</configuration>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc b/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc
new file mode 100644
index 000000000..be2b9af38
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/logging-3pps.adoc
@@ -0,0 +1,37 @@
+//
+// ============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)
+//
+
+== Logging External Components
+
+Logback can also be configured to log any other, external components APEX is using, if they are using the common logging framework.
+
+For instance, the context component of APEX is using __Infinispan__ and one can add a logger for this external component.
+The following example adds a logger for __Infinispan__ using the standard output appender.
+
+[source%nowrap,xml]
+----
+<logger name="org.infinispan" level="INFO" additivity="false">
+  <appender-ref ref="STDOUT" />
+</logger>
+----
+
+Another example is Apache Zookeeper.
+The following example adds a logger for Zookeeper using the standard outout appender.
+
+[source%nowrap,xml]
+----
+<logger name="org.apache.zookeeper.ClientCnxn" level="INFO" additivity="false">
+  <appender-ref ref="STDOUT" />
+</logger>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc b/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc
new file mode 100644
index 000000000..779e45458
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/logging-policy-logic.adoc
@@ -0,0 +1,54 @@
+//
+// ============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)
+//
+
+== Configuring loggers for Policy Logic
+
+The logging for the logic inside a policy (task logic, task selection logic, state finalizer logic) can be configured separate from standard logging.
+The logger for policy logic is `org.onap.policy.apex.executionlogging`.
+The following example defines
+
+- a new appender for policy logic logging to standard out using a very simple pattern (simply the actual message)
+- a logger for policy logic to standard out using the new appender
+- a logger for policy logic to the standard `FILE` appender
+
+[source%nowrap,xml]
+----
+<appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+  <encoder>
+    <pattern>policy: %msg\n</pattern>
+  </encoder>
+</appender>
+
+<appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+  <encoder>
+    <pattern>policy: %msg\n</pattern>
+  </encoder>
+</appender>
+
+<logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false">
+  <appender-ref ref="POLICY_APPENDER_STDOUT" />
+  <appender-ref ref="FILE" />
+</logger>
+
+----
+
+It is also possible to use specific logging for parts of policy logic.
+The following example defines a logger for task logic.
+
+[source%nowrap,xml]
+----
+<logger name="org.onap.policy.apex.executionlogging.TaskExecutionLogging" level="TRACE" additivity="false">
+  <appender-ref ref="STDOUT" />
+</logger>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc b/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc
new file mode 100644
index 000000000..68a6d1cba
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/rolling-file-appenders.adoc
@@ -0,0 +1,71 @@
+//
+// ============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)
+//
+
+== Rolling File Appenders
+
+Rolling file appenders are a good option for more complex logging of a production or complex testing APEX installation.
+The standard logback configuration can be used for these use cases.
+This section gives two examples for the standard logging and for context logging.
+
+First the standard logging.
+The following example defines a rolling file appender.
+The appender rolls over on a daily basis.
+It allows for a file size of 100 MB.
+
+[source%nowrap,xml]
+----
+<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+  <file>${VAR_LOG}/apex.log</file>
+  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+    <!-- rollover daily -->
+    <!-- <fileNamePattern>xstream-%d{yyyy-MM-dd}.%i.txt</fileNamePattern> -->
+    <fileNamePattern>${VAR_LOG}/apex_%d{yyyy-MM-dd}.%i.log.gz
+    </fileNamePattern>
+    <maxHistory>4</maxHistory>
+    <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
+      <!-- or whenever the file size reaches 100MB -->
+      <maxFileSize>100MB</maxFileSize>
+    </timeBasedFileNamingAndTriggeringPolicy>
+  </rollingPolicy>
+  <encoder>
+    <pattern>
+      %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
+    </pattern>
+  </encoder>
+</appender>
+----
+
+A very similar configuration can be used for a rolling file appender logging APEX context.
+
+[source%nowrap,xml]
+----
+<appender name="CTXT-FILE"
+      class="ch.qos.logback.core.rolling.RollingFileAppender">
+  <file>${VAR_LOG}/apex_ctxt.log</file>
+  <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+    <fileNamePattern>${VAR_LOG}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz
+    </fileNamePattern>
+    <maxHistory>4</maxHistory>
+    <timeBasedFileNamingAndTriggeringPolicy
+        class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
+      <maxFileSize>100MB</maxFileSize>
+    </timeBasedFileNamingAndTriggeringPolicy>
+  </rollingPolicy>
+  <encoder>
+    <pattern>
+      %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
+    </pattern>
+  </encoder>
+</appender>
+----
+
diff --git a/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc b/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc
new file mode 100644
index 000000000..a09b3d27e
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-logging/standard-configuration.adoc
@@ -0,0 +1,96 @@
+//
+// ============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 Logging Configuration
+
+The standard logging configuration defines a context __APEX__, which is used in the standard output pattern.
+The location for log files is defined in the property `VAR_LOG` and set to `/var/log/apex`.
+The standard status listener is set to __NOP__ and the overall logback configuration is set to no debug.
+
+[source%nowrap,xml,numbered]
+----
+<configuration debug="false">
+  <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
+
+  <contextName>Apex</contextName>
+  <property name="VAR_LOG" value="/var/log/ericsson/apex/" />
+
+  ...appenders
+  ...loggers
+</configuration>
+----
+
+The first appender defined is called `STDOUT` for logs to standard out.
+
+[source%nowrap,xml,numbered]
+----
+<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+  <encoder>
+    <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
+  </encoder>
+</appender>
+----
+
+The root level logger then is set to the level __info__ using the standard out appender.
+[source%nowrap,xml,numbered]
+----
+<root level="info">
+  <appender-ref ref="STDOUT" />
+</root>
+----
+
+The first appender is called `FILE`.
+It writes logs to a file `apex.log`.
+[source%nowrap,xml,numbered]
+----
+<appender name="FILE" class="ch.qos.logback.core.FileAppender">
+  <file>${VAR_LOG}/apex.log</file>
+  <encoder>
+    <pattern>
+      %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
+    </pattern>
+  </encoder>
+</appender>
+----
+
+The first appender is called `CTXT_FILE`.
+It writes logs to a file `apex_ctxt.log`.
+[source%nowrap,xml,numbered]
+----
+<appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender">
+  <file>${VAR_LOG}/apex_ctxt.log</file>
+  <encoder>
+    <pattern>
+      %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
+    </pattern>
+  </encoder>
+</appender>
+----
+
+The last definitions are for specific loggers.
+The first logger captures all standard APEX classes, appends logs to `STDOUT` with the log level __info__.
+The second logger capture all standard APEX classes, appends logs to `FILE` with log level __info__.
+The third logger captures context monitoring classes, appends logs to `CTXT_FILE` with log level __trace__.
+
+[source%nowrap,xml,numbered]
+----
+<logger name="org.onap.policy.apex" level="info" additivity="false">
+  <appender-ref ref="STDOUT" />
+  <appender-ref ref="FILE" />
+</logger>
+
+<logger name="org.onap.policy.apex.core.context.monitoring" level="TRACE" additivity="false">
+  <appender-ref ref="CTXT_FILE" />
+</logger>
+----
+