diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/apex-policy-model')
14 files changed, 452 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitem.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitem.adoc new file mode 100644 index 000000000..27922026b --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitem.adoc @@ -0,0 +1,21 @@ +// +// ============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) +// + +== Concept: ContextItem + +Each piece of context in a __ContextMap__ is represented by an instance of the __ContextItem__ concept. +Each __ContextItem__ concept instance in a context map keyed with a `ReferenceKey` key, which references the context map of the context item. +The __LocalName__ field of the `ReferenceKey` holds the name of the context item in the context map +A reference to a __DataType__ concept defines the data type that values of this context item have at run time. +The __WritableFlag__ indicates if the context item is read only or read-write at run time. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitemtemplate.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitemtemplate.adoc new file mode 100644 index 000000000..6ebeb840c --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextitemtemplate.adoc @@ -0,0 +1,22 @@ +// +// ============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) +// + +== Concept: ContextItemTemplate + +In a __SAMETYPE__ __ContextMap__, the __ContextItemTemplate__ definition provides a template for the __ContextItem__ instances that will be created on the context map at run time. +Each __ContextItem__ concept instance in the context map is created using the __ContextItemTemplate__ template. +It is keyed with a `ReferenceKey` key, which references the context map of the context item. +The __LocalName__ field of the `ReferenceKey`, supplied by the creator of the context item at run time, holds the name of the context item in the context map. +A reference to a __DataType__ concept defines the data type that values of this context item have at run time. +The __WritableFlag__ indicates if the context item is read only or read-write at run time. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-contextmap.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextmap.adoc new file mode 100644 index 000000000..d3276590c --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-contextmap.adoc @@ -0,0 +1,52 @@ +// +// ============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) +// + +== Concept: ContextMap + +The set of context that is available for use by the policies of a __PolicyModel__ is defined as __ContextMap__ concept instances. +The __PolicyModel__ holds a map of all the __ContextMap__ definitions. +A __ContextMap__ is itself a container for a group of related context items, each of which is represented by a __ContextItem__ concept instance. +__ContextMap__ concepts are keyed with an `ArtifactKey` key. +A developer can use the APEX Policy Editor to create context maps for their application domain. + +A __ContextMap__ uses a map to hold the context items. +The ContextItem concept instances in the map are indexed by the __LocalName__ of their `ReferenceKey`. + +The __ContextMapType__ field of a __ContextMap__ defines the type of a context map. +The type can have either of two values: + +* A __BAG__ context map is a context map with fixed content. + Each possible context item in the context map is defined at design time and is held in the __ContextMap__ context instance as __ContextItem__ concept definitions and only the values of the context items in the context map can be changed at run time. + The context items in a __BAG__ context map have mixed types and distinct __ContextItem__ concept instances of the same type can be defined. + A __BAG__ context map is convenient for defining a group of context items that are diverse but are related by domain, such as the characteristics of a device. + A fully defined __BAG__ context map has a fully populated __ContextItem__ map but its __ContextItemTemplate__ reference is not defined. ++ +* A __SAMETYPE__ context map is used to represent a group of __ContextItem__ instances of the same type. + Unlike a __BAG__ context map, the __ContextItem__ concept instances of a __SAMETYPE__ context map can be added, modified, and deleted at runtime. + All __ContextItem__ concept instances in a __SAMETYPE__ context map must be of the same type, and that context item is defined as a single __ContextItemTemplate__ concept instances at design time. + At run time, the __ContextItemTemplate__ definition is used to create new __ContextItem__ concept instances for the context map on demand. + A fully defined _SAMETYPE__ context map has an empty __ContextItem__ map and its __ContextItemTemplate__ reference is defined. + + +The __Scope__ of a __ContextMap__ defines the range of applicability of a context map in APEX. +The following scopes of applicability are defined: + +* __EPHEMERAL__ scope means that the context map is owned, used, and modified by a single application, but the context map only exists while that application is running +* __APPLICATION__ scope specifies that the context map is owned, used, and modified by a single application, the context map is persistent +* __GLOBAL__ scope specifies that the context map is globally owned and is used and modified by any application, the context map is persistent +* __EXTERNAL__ scope specifies that the context map is owned by an external system and may be used in a read-only manner by any application, the context map is persistent + +A much more sophisticated scoping mechanism for context maps is envisaged for +Apex in future work. In such a mechanism, the scope of a context map would work +somewhat like the way roles work in security authentication systems. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-datatype.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-datatype.adoc new file mode 100644 index 000000000..f0062e2aa --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-datatype.adoc @@ -0,0 +1,21 @@ +// +// ============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) +// + +== Concept: DataType + +Data types are tightly controlled in APEX in order to provide a very high degree of consistency in policies and to facilitate tracking of changes to context as policies execute. +All context is modeled as a __DataType__ concept. +Each DataType concept instance is keyed with an `ArtifactKey` key. +The DataType field identifies the Java class of objects that is used to represent concept instances that use this data type. +All context has a __DataType__; incoming and outgoing context is represented by __EventField__ concepts and all other context is represented by __ContextItem__ concepts. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-event.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-event.adoc new file mode 100644 index 000000000..fdd8d7f5b --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-event.adoc @@ -0,0 +1,28 @@ +// +// ============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) +// + +== Concept: Event + +An __Event__ defines the structure of a message that passes into or out of an APEX engine or that passes between two states in an APEX engine. +APEX supports message reception and sending in many formats and all messages are translated into an __Event__ prior to processing by an APEX engine. +Event concepts are keyed with an `ArtifactKey` key. +The parameters of an event are held as a map of __EventField__ concept instances with each parameter indexed by the __LocalName__ of its `ReferenceKey`. +An __Event__ has three fields: + +* The __NameSpace__ identifies the domain of application of the event +* The __Source__ of the event identifies the system that emitted the event +* The __Target__ of the event identifies the system that the event was sent to + +A __PolicyModel__ contains a map of all the events known to a given policy model. +Although an empty model may have no events in its event map, any sane policy model must have at least one __Event__ defined. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-eventfield.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-eventfield.adoc new file mode 100644 index 000000000..b5646332a --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-eventfield.adoc @@ -0,0 +1,22 @@ +// +// ============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) +// + +== Concept: EventField + +The incoming context and outgoing context of an event are the fields of the event. +Each field representing a single piece of incoming or outgoing context. +Each field of an __Event__ is represented by an instance of the __EventField__ concept. +Each __EventField__ concept instance in an event is keyed with a `ReferenceKey` key, which references the event. +The __LocalName__ field of the `ReferenceKey` holds the name of the field +A reference to a __DataType__ concept defines the data type that values of this parameter have at run time. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-logic.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-logic.adoc new file mode 100644 index 000000000..250f8accf --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-logic.adoc @@ -0,0 +1,30 @@ +// +// ============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) +// + +== Concept: Logic + +The __Logic__ concept instance holds the actual programmed task logic for a task defined in a __Task__ concept or the programmed task selection logic for a state defined in a __State__ concept. +It is keyed with a `ReferenceKey` key, which references the task or state that owns the logic. +The __LocalName__ field of the Logic concept is the name of the logic. + +The __LogicCode__ field of a Logic concept definition is a string that holds the program code that is to be executed at run time. +The __LogicType__ field defines the language of the code. +The standard values are the logic languages supported by APEX: + link:https://en.wikipedia.org/wiki/JavaScript[JAVASCRIPT], + link:https://java.com/en/[JAVA], + link:http://www.jython.org/[JYTHON], + link:http://jruby.org/[JRUBY], or + link:https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide[MVEL]. + +The APEX engine uses the __LogicType__ field value to decide which language interpreter to use for a task and then sends the logic defined in the __LogicCode__ field to that interpreter. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-policy.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-policy.adoc new file mode 100644 index 000000000..3e48915d9 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-policy.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) +// + +== Concept: Policy + +The __Policy__ concept defines a policy in APEX. +The definition is rather straightforward. +A policy is made up of a set of states with the flavor of the policy determining the structure of the policy states and the first state defining what state in the policy executes first. +__Policy__ concepts are keyed with an `ArtifactKey` key. + +The __PolicyFlavour__ of a __Policy__ concept specifies the structure that will be used for the states in the policy. +A number of commonly used policy patterns are supported as APEX policy flavors. +The standard policy flavors are: + +* The __MEDA__ flavor supports policies written to the link:https://www.researchgate.net/publication/282576518_Dynamically_Adaptive_Policies_for_Dynamically_Adaptive_Telecommunications_Networks[MEDA policy pattern] and require a sequence of four states: namely __Match__, __Establish__, __Decide__ and __Act__. +* The __OODA__ flavor supports policies written to the link:https://en.wikipedia.org/wiki/OODA_loop[OODA loop pattern] and require a sequence of four states: namely __Observe__, __Orient__, __Decide__ and __Act__. +* The __ECA__ flavor supports policies written to the link:https://en.wikipedia.org/wiki/Event_condition_action[ECA active rule pattern] and require a sequence of three states: namely __Event__, __Condition__ and __Action__ +* The __XACML__ flavor supports policies written in link:https://en.wikipedia.org/wiki/XACML[XACML] and require a single state: namely __XACML__ +* The __FREEFORM__ flavor supports policies written in an arbitrary style. + A user can define a __FREEFORM__ policy as an arbitrarily long chain of states. + +The __FirstState__ field of a __Policy__ definition is the starting point for execution of a policy. +Therefore, the trigger event of the state referenced in the __FirstState__ field is also the trigger event for the entire policy. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-policymodel.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-policymodel.adoc new file mode 100644 index 000000000..385f7310d --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-policymodel.adoc @@ -0,0 +1,23 @@ +// +// ============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) +// + +== Concept: PolicyModel + +The __PolicyModel__ concept is a container that holds the definition of a set of policies and their associated events, context maps, and tasks. +A __PolicyModel__ is implemented as four maps for policies, events, context maps, and tasks. +Each map is indexed by the key of the policy, event, context map, or task. +Any non-empty policy model must have at least one entry in its policy, event, and task map because all policies must have at least one input and output event and must execute at least one task. + +A __PolicyModel__ concept is keyed with an `ArtifactKey key`. +Because a __PolicyModel__ is an `AxConcept`, calling the `validate()` method on a policy model validates the concepts, structure, and relationships of the entire policy model. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-state.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-state.adoc new file mode 100644 index 000000000..acab55235 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-state.adoc @@ -0,0 +1,45 @@ +// +// ============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) +// + +== Concept: State + +The __State__ concept represents a phase or a stage in a policy, with a policy being composed of a series of states. +Each state has at least one but may have many tasks and, on each run of execution, a state executes one and only one of its tasks. +If a state has more than one task, then its task selection logic is used to select which task to execute. +Task selection logic is programmable logic provided by the state designer. +That logic can use incoming, policy, global, and external context to select which task best accomplishes the purpose of the state in a give situation if more than one task has been specified on a state. +A state calls one and only one task when it is executed. + +Each state is triggered by an event, which means that all tasks of a state must also be triggered by that same event. +The set of output events for a state is the union of all output events from all tasks for that task. +In practice at the moment, because a state can only have a single input event, a state that is not the final state of a policy +may only output a single event and all tasks of that state may also only output that single event. +In future work, the concept of having a less restrictive trigger pattern will be examined. + +A __State__ concept is keyed with a `ReferenceKey` key, which references the __Policy__ concept that owns the state. +The __LocalName__ field of the `ReferenceKey` holds the name of the state. +As a state is part of a chain of states, the __NextState__ field of a state holds the `ReferenceKey` key of the state in the policy to execute after this state. + +The __Trigger__ field of a state holds the `ArtifactKey` of the event that triggers this state. +The __OutgoingEvents__ field holds the `ArtifactKey` references of all possible events that may be output from the state. +This is a set that is the union of all output events of all tasks of the state. + +The __Task__ concepts that hold the definitions of the task for the state are held as a set of `ArtifactKey` references in the state. +The __DefaultTask__ field holds a reference to the default task for the state, a task that is executed if no task selection logic is +specified. +If the state has only one task, that task is the default task. + +The __Logic__ concept referenced by a state holds the task selection logic for a state. +The task selection logic uses the incoming context (parameters of the incoming event) and other context to determine the best task to use to execute its goals. +The state holds a set of references to __ContextItem__ and __ContextItemTemplate__ definitions for the context used by its task selection logic. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-task.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-task.adoc new file mode 100644 index 000000000..78f5defbb --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-task.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) +// + +== Concept: Task + +The smallest unit of logic in a policy is a __Task__. +A task encapsulates a single atomic unit of logic, and is designed to be a single indivisible unit of execution. +A task may be invoked by a single policy or by many policies. +A task has a single trigger event, which is sent to the task when it is invoked. +Tasks emit one or more outgoing events, which carry the result of the task execution. +Tasks may use or modify context as they execute. + +The Task concept definition captures the definition of an APEX task. +Task concepts are keyed with an `ArtifactKey` key. +The Trigger of the task is a reference to the __Event__ concept that triggers the task. +The __OutgoingEvents__ of a task are a set of references to __Event__ concepts that may be emitted by the task. + +All tasks have logic, some code that is programmed to execute the work of the task. +The __Logic__ concept of the task holds the definition of that logic. + +The __Task__ definition holds a set of __ContextItem__ and __ContextItemTemplate__ context items that the task is allow to access, as defined by the task developer at design time. +The type of access (read-only or read write) that a task has is determined by the __WritableFlag__ flag on the individual context item definitions. +At run time, a task may only access the context items specified in its context item set, the APEX engine makes only the context items in the task context item set is available to the task. + +A task can be configured with startup parameters. +The set of parameters that can be configured on a task are defined as a set of __TaskParameter__ concept definitions. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concept-taskparameter.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concept-taskparameter.adoc new file mode 100644 index 000000000..97eedaa96 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concept-taskparameter.adoc @@ -0,0 +1,20 @@ +// +// ============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) +// + +== Concept: TaskParameter + +Each configuration parameter of a task are represented as a __Taskparameter__ concept keyed with a `ReferenceKey` key, which references the task. +The __LocalName__ field of the `ReferenceKey` holds the name of the parameter. +The __DefaultValue__ field defines the default value that the task parameter is set to. +The value of __TaskParameter__ instances can be overridden at deployment time by specifying their values in the configuration information passed to APEX engines. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/concepts-keys.adoc b/src/site-docs/adoc/fragments/apex-policy-model/concepts-keys.adoc new file mode 100644 index 000000000..d15152b01 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/concepts-keys.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) +// + +== Concepts and Keys + +Each element of the policy model is called a __concept__. +Each __concept__ is a subclass of the abstract __Concept__ class, as shown in the next figure. +Every concept implements the following abstract methods: + +.Concepts and Keys +image::apex-policy-model/ConceptsKeys.png[Concepts and Keys] + +* `getKey()` - gets the unique key for this concept instance in the system +* `validate()` - validates the structure of this concept, its sub-concepts and its relationships +* `clean()` - carries out housekeeping on the concept such as trimming strings, remove any hanging references +* `clone()` - creates a deep copy of an instance of this concept +* `equals()` - checks if two instances of this concept are equal +* `toString()` - returns a string representation of the concept +* `hashCode()` - returns a hash code for the concept +* `copyTo()` - carries out a deep copy of one instance of the concept to another instance, overwriting the target fields. + +All concepts must have a __key__, which uniquely identifies a concept instance. +The __key__ of a subclass of an __Concept__ must either be an `ArtifactKey` or an `ReferenceKey`. +Concepts that have a stand-alone independent existence such as __Policy__, __Task__, and __Event__ must have an `ArtifctKey` key. +Concepts that are contained in other concepts, that do not exist as stand-alone concepts must have an `ReferenceKey` key. +Examples of such concepts are __State__ and __EventParameter__. + +An `ArticactKey` has two fields; the __Name__ of the concept it is the key for and the concept's __Version__. +A concept's name must be unique in a given PolicyModel. +A concept version is represented using the well known __major.minor.path__ scheme as used in semantic versioning. + +A `ReferenceKey` has three fields. +The __UserKeyName__ and __UserKeyVersion__ fields identify the `ArtifactKey` of the concept in which the concept keyed by the `ReferenceKey` is contained. +The __LocalName__ field identifies the contained concept instance. +The __LocalName__ must be unique in the concepts of a given type contained by a parent. + +For example, a policy called `_SalesPolicy_` with a Version of `_1.12.4_` has a state called `_Decide_`. +The `_Decide_` state is linked to the `_SalesPolicy_` with a `ReferenceKey` with fields __UserKeyName__ of `_SalesPolicy_`, __UserKeyVersion__ of `_1.12.4_`, and __LocalName__ of `_Decide_`. +There must not be another state called `_Decide_` in the policy `_SalesPolicy_`. +However, there may well be a state called `_Decide_` in some other policy called `_PurchasingPolicy_`. + +Each concept in the model is also a JPA (link:https://en.wikipedia.org/wiki/Java_Persistence_API[Java Persistence API]) Entity. +This means that every concept can be individually persisted or the entire model can be persisted en-bloc to any persistence mechanism using an JPA framework such as link:http://hibernate.org/[Hibernate] or link:http://www.eclipse.org/eclipselink/[EclipseLink]. + diff --git a/src/site-docs/adoc/fragments/apex-policy-model/introduction.adoc b/src/site-docs/adoc/fragments/apex-policy-model/introduction.adoc new file mode 100644 index 000000000..906f51cce --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-policy-model/introduction.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) +// + +== Introduction + +The APEX policy model is shown in UML notation in the figure below. +A policy model can be stored in JSON or XML format in a file or can be held in a database. +The APEX editor creates and modifies APEX policy models. +APEX deployment deploys policy models, and a policy model is loaded into APEX engines so that the engines can run the policies in the policy model. + +The figure shows four different views of the policy model: + +* The general model view shows the main parts of a policy: state, state output, event, and task. + A task can also have parameters. + Data types can be defined on a per-model basis using either standard atomic types (such as character, string, numbers) or complex types from a policy domain. +* The logic model view emphasizes how decision-making logic is injected into a policy. + There are essentially three different types of logic: + task logic (for decision making in a task), + task selection logic (to select a task if more than one is defined in a state), and + state finalizer logic (to compute the final output event of a state and select an appropriate next state from the policy model). +* The context model view shows how context is injected into a policy. + States collect all context from their tasks. + A task can define what context it requires for the decision making, i.e. what context the task logic will process. + Context itself is a collection of items (individual context information) with data types. + Context can be templated. +* The event and field model view shows the events in the policy model. + Tasks define what information they consume (input) and produce (output). + This information is modeled as fields, essentially a key/type tuple in the model and a key/type/value triple at execution. + Events then are collection of fields. + +.APEX Policy Model for Execution +image::apex-policy-model/UmlPolicyModels.png[APEX Policy Model for Execution] + |