From af74a6270d6ab6badf04a97495a6ef8ccded9b4b Mon Sep 17 00:00:00 2001 From: ramverma Date: Tue, 31 Jul 2018 18:25:39 +0100 Subject: 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 --- .../fragments/howto-write-logic/task-logic.adoc | 177 +++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc (limited to 'src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc') 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 | +The incoming task fields. This is implemented as a standard Java (unmodifiable) Map. + +2+| 2+=1000) { ... } +---- + +|outFields | Fields | java.util.Map | +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+` 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+