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>

1 files changed, 177 insertions, 0 deletions

diff --git a/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc b/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc
new file mode 100644
index 000000000..23a05024d
--- /dev/null
+++ b/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc
@@ -0,0 +1,177 @@
+//
+// ============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)
+//
+
+== Writing APEX Task Logic
+
+Task logic specifies the behavior of an Apex Task.
+This logic can be specified in a number of ways, exploiting Apex's plug-in architecture to support a range of logic executors.
+In Apex scripted Task Logic can be written in any of these languages: 
+
+* https://en.wikipedia.org/wiki/MVEL[`MVEL`],
+* https://en.wikipedia.org/wiki/JavaScript[`JavaScript`],
+* https://en.wikipedia.org/wiki/JRuby[`JRuby`] or
+* https://en.wikipedia.org/wiki/Jython[`Jython`].
+
+These languages were chosen because the scripts can be compiled into Java bytecode at runtime and then efficiently executed natively in the JVM.
+Task Logic an also be written directly in Java but needs to be compiled, with the resulting classes added to the classpath.
+There are also a number of other Task Logic types (e.g. Fuzzy Logic), but these are not supported as yet.
+This guide will focus on the scripted Task Logic approaches, with MVEL and JavaScript being our favorite languages.
+In particular this guide will focus on the Apex aspects of the scripts.
+However, this guide does not attempt to teach you about the scripting languages themselves ... that is up to you!
+
+[TIP]
+.JVM-based scripting languages
+====
+For more more information on Scripting for the Java platform see: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html
+====
+
+[NOTE]
+.What do Tasks do? 
+====
+The function of an Apex Task is to provide the logic that can be executed for an Apex State as one of the steps in an Apex Policy.
+Each task receives some _incoming fields_, executes some logic (e.g: make a decision based on _shared state_ or _context_, _incoming fields_,  _external context_, etc.), perhaps set some _shared state_ or _context_ and then emits _outgoing fields_.
+The state that uses the task is responsible for extracting the _incoming fields_ from the state input event.
+The state also has an _output mapper_ associated with the task, and this _output mapper_ is responsible for mapping the _outgoing fields_ from the task into an appropriate output event for the state.
+==== 
+
+First lets start with a sample task, drawn from the "My First Apex Policy" example:
+The task "MorningBoozeCheck" from the "My First Apex Policy" example is available in both MVEL and JavaScript:
+ 
+.Javascript code for the `MorningBoozeCheck` task
+[source,javascript,options="nowrap"]
+----
+include::{adsite-examples-myfirstpolicy-dir}/main/resources/examples/models/MyFirstPolicy/1/MorningBoozeCheck.js[]
+----
+
+.MVEL code for the `MorningBoozeCheck` task
+[source,java,options="nowrap"]
+----
+include::{adsite-examples-myfirstpolicy-dir}/main/resources/examples/models/MyFirstPolicy/1/MorningBoozeCheck.mvel[]
+----
+
+The role of the task in this simple example is to copy the values in the incoming fields into the outgoing fields, then examine the values in some incoming fields (`item_id` and `time`), then set the values in some other outgoing fields (`authorised` and `message`). 
+
+Both MVEL and JavaScript like most JVM-based scripting languages can use standard Java libraries to perform complex tasks.
+Towards the top of the scripts you will see how to import Java classes and packages to be used directly in the logic. 
+Another thing to notice is that Task Logic should return a `java.lang.Boolean` value `true` if the logic executed correctly.
+If the logic fails for some reason then `false` can be returned, but this will cause the policy invoking this task will fail and exit. 
+
+[NOTE]
+.How to return a value from task logic
+====
+Some languages explicitly support returning values from the script (e.g. MVEL and JRuby) using an explicit return statement (e.g. `return true`), other languages do not (e.g. JavaScript and Jython).
+For languages that do not support the `return` statement, a special field called `returnValue` must be created to hold the result of the task logic operation (i.e. assign a `java.lang.Boolean` value to the `returnValue` field before completing the task).
+
+Also, in MVEL if there is no explicit return statement then the return value of the last executed statement will return (e.g.  the statement a=(1+2) will return the value 3).
+====
+
+Besides these imported classes and normal language features Apex provides some natively available parameters and functions that can be used directly.
+At run-time these parameters are populated by the Apex execution environment and made natively available to logic scripts each time the logic script is invoked.
+(These can be accessed using the `executor` keyword for most languages, or can be accessed directly without the `executor` keyword in MVEL):
+
+.The `executor` Fields / Methods
+[width="100%",cols="10l,10d,30m,40a",options="header"]
+|====================
+|Name | Type | Java type | Description  
+
+|inFields | Fields | java.util.Map <String,Object> | 
+The incoming task fields. This is implemented as a standard Java (unmodifiable) Map. 
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+executor.logger.debug("Incoming fields: "
+   +executor.inFields.entrySet());
+var item_id = executor.incomingFields["item_ID"];
+if (item_id >=1000) { ... }
+----
+
+|outFields | Fields | java.util.Map <String,Object> | 
+The outgoing task fields. This is implemented as a standard initially empty Java (modifiable) Map.
+To create a new schema-compliant instance of a field object see the utility method `subject.getOutFieldSchemaHelper()` below 
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+executor.outFields["authorised"] = false;
+----
+
+|logger | Logger | org.slf4j.ext.XLogger | A helpful logger 
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+executor.logger.info("Executing task: "
+   +executor.subject.id);
+----
+
+|TRUE/FALSE | boolean | java.land.Boolean | 2 helpful constants. These are useful to retrieve correct return values for the task logic
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+var returnValue = executor.TRUE;
+// functionally equivalent to: 
+var returnValueType = Java.type("java.lang.Boolean");
+var returnValue = new returnValueType(true);
+----
+
+|subject | Task | TaskFacade | 
+
+This provides some useful information about the task that contains this task logic.
+This object has some useful fields and methods : 
+
+[options="compact"]
+- *_AxTask task_* to get access to the full task definition of the host task
+- *_String getTaskName()_* to get the name of the host task
+- *_String getId()_* to get the ID of the host task 
+- *_SchemaHelper getInFieldSchemaHelper( String fieldName )_* to get a `SchemaHelper` helper object to manipulate incoming task fields in a schema-aware manner
+- *_SchemaHelper getOutFieldSchemaHelper( String fieldName )_* to get a `SchemaHelper` helper object to manipulate outgoing task fields in a schema-aware manner, e.g. to instantiate new schema-compliant field objects to populate the `executor.outFields` outgoing fields map 
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+executor.logger.info("Task name: "
+   +executor.subject.getTaskName());
+executor.logger.info("Task id: "
+   +executor.subject.getId());
+executor.logger.info("Task inputs definitions: "
+   +"executor.subject.task.getInputFieldSet());
+executor.logger.info("Task outputs definitions: "
+   +"executor.subject.task.getOutputFieldSet());
+executor.outFields["authorised"] = executor.subject
+      .getOutFieldSchemaHelper("authorised")
+      .createNewInstance("false");
+----
+
+3+l|ContextAlbum getContextAlbum(
+       String ctxtAlbumName ) |
+A utility method to retrieve a `ContextAlbum` for use in the task. This is how you access the context used by the task. The returned `ContextAlbum` implements the `java.util.Map <String,Object>` interface to get and set context as appropriate. The returned `ContextAlbum` also has methods to lock context albums, get information about the schema of the items to be stored in a context album, and get a `SchemaHelper` to manipulate context album items. How to define and use context in a task is described in the Apex Programmer's Guide and in the My First Apex Policy guide.
+
+2+| 2+<a|
+*Example:*
+[source,javascript,options="nowrap"]
+----
+var bkey = executor.inFields.get("branch_ID");
+var cnts = executor.getContextMap("BranchCounts");
+cnts.lockForWriting(bkey);
+cnts.put(bkey, cnts.get(bkey) + 1);
+cnts.unlockForWriting(bkey);
+----
+|====================
+