summaryrefslogtreecommitdiffstats
path: root/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc
diff options
context:
space:
mode:
authorliamfallon <liam.fallon@est.tech>2020-10-16 13:09:11 +0100
committerliamfallon <liam.fallon@est.tech>2020-10-16 13:09:16 +0100
commit0cf967c0239a8ab9c8b8831b700b72d9a08f7b03 (patch)
treea4fbcd97008769d55ac443bc22abf517308bf6a7 /src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc
parent9833876720ff14517ee78bda557e6021df723800 (diff)
Remove apex asciidoc documents
Apex documentation has now all been ported to use the ONAP recommended rst format. This review removes the old asciidoc documents. Issue-ID: POLICY-2824 Change-Id: I562bd344cb7d6ff36e7d54bdb8f95e3b656468f8 Signed-off-by: liamfallon <liam.fallon@est.tech>
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc')
-rw-r--r--src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc177
1 files changed, 0 insertions, 177 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
deleted file mode 100644
index e014a9e9c..000000000
--- a/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc
+++ /dev/null
@@ -1,177 +0,0 @@
-//
-// ============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.isTrue;
-// 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);
-----
-|====================
-