diff options
Diffstat (limited to 'src/site-docs/adoc/fragments')
108 files changed, 5844 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/apex-intro/configuration-matrix.adoc b/src/site-docs/adoc/fragments/apex-intro/configuration-matrix.adoc new file mode 100644 index 000000000..c82b2aa41 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/configuration-matrix.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) +// + +== APEX Configuration + +An APEX engine can be configured to use various combinations of + event input handlers, + event output handlers, + event protocols, + context handlers, and + logic executors. +The system is build using a plugin architecture. +Each configuration option is realized by a plugin, which can be loaded and configured when the engine is started. +New plugins can be added to the system at any time, though to benefit from a new plugin an engine will need to be restarted. + +.APEX Configuration Matrix +image::apex-intro/ApexEngineConfig.png[APEX Configuration Matrix] + +The APEX distribution already comes with a number of plugins. +The figure above shows the provided plugins. +Any combination of input, output, event protocol, context handlers, and executors is possible. diff --git a/src/site-docs/adoc/fragments/apex-intro/introduction.adoc b/src/site-docs/adoc/fragments/apex-intro/introduction.adoc new file mode 100644 index 000000000..b936ef51b --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/introduction.adoc @@ -0,0 +1,57 @@ +// +// ============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 + +APEX stand for Adaptive Policy EXecution. +It is a lightweight engine for execution of policies. +APEX allows you to specify logic as a policy, logic that you can adapt on the fly as your system executes. +The APEX policies you design can be really simple, with a single snippet of logic, or can be very complex, with many states and tasks. +APEX policies can even be designed to self-adapt at execution time, the choice is yours! + +.Simple APEX Overview +image::apex-intro/ApexSimple.png[Simple APEX Overview] + +The Adaptive Policy Engine in APEX runs your policies. +These policies are triggered by incoming events. +The logic of the policies executes and produces a response event. +The __Incoming Context__ on the incoming event and the __Outgoing Context__ on the outgoing event are simply the fields and attributes of the event. +You design the policies that APEX executes and the trigger and action events that your policies accept and produce. +Events are fed in and sent out as JSON or XML events over Kafka, a Websocket, a file or named pipe, or even standard input. +If you run APEX as a library in your application, you can even feed and receive events over a Java API. + +.APEX States and Context +image::apex-intro/ApexStatesAndContext.png[APEX States and Context] + +You design your policy as a chain of states, with each state being fed by the state before. +The simplest policy can have just one state. +We provide specific support for the four-state link:https://www.researchgate.net/publication/303564082_Apex_An_Engine_for_Dynamic_Adaptive_Policy_Execution[MEDA (Match Establish Decide Act)] policy state model and the three-state link:https://en.wikipedia.org/wiki/Event_condition_action[ECA (Event Condition Action)] policy state model. +APEX is fully distributed. +You can decide how many APEX engine instances to run for your application and on which real or virtual hosts to run them. + +In APEX, you also have control of the __Context__ used by your policies. +Context is simply the state information and data used by your policies. +You define what context your policies use and what the scope of that context is. +__Policy Context__ is private to a particular policy and is accessible only to whatever APEX engines are running that particular policy. +__Global Context__ is available to all policies. +__External Context__ is read-only context such as weather or topology information that is provided by other systems. +APEX keeps context coordinated across all the the instances running a particular policy. +If a policy running in an APEX engine changes the value of a piece of context, that value is is available to all other APEX engines that use that piece of context. +APEX takes care of distribution, locking, writing of context to persistent storage, and monitoring of context. + +.The APEX Eco-System +image::apex-intro/ApexEcosystem.png[The APEX Eco-System] + +The APEX engine (AP-EN) is available as a Java library for inclusion in your application, as a microservice running in a Docker container, or as a stand-alone service available for integration into your system. +APEX also includes a policy editor (AP-AUTH) that allows you to design your policies and a web-based policy management console you use to deploy policies and to keep track of the state of policies and context in policies. +Context handling (AP-CTX) is integrated into the APEX engine and policy deployment (AP-DEP) is provided as a servlet running under a web framework such as link:http://tomcat.apache.org/[Apache Tomcat]. diff --git a/src/site-docs/adoc/fragments/apex-intro/policy-matrix.adoc b/src/site-docs/adoc/fragments/apex-intro/policy-matrix.adoc new file mode 100644 index 000000000..b3c626522 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/policy-matrix.adoc @@ -0,0 +1,90 @@ +// +// ============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) +// + +== APEX Policy Matrix + +APEX offers a lot of flexibility for defining, deploying, and executing policies. +Based on a theoretic model, it supports virtually any policy model and allows to translate legacy policies into the APEX execution format. +However, the most important aspect for using APEX is to decide what policy is needed, what underlying policy concepts should be used, and how the decision logic should be realized. +Once these aspects are decided, APEX can be used to execute the policies. +If the policy evolves, say from a simple decision table to a fully adaptable policy, only the policy definition requires change. +APEX supports all of that. + +The figure below shows a (non-exhaustive) matrix, which will help to decide what policy is required to solve your problem. +Read the matrix from left to right choosing one cell in each column. + +.APEX Policy Matrix +image::apex-intro/ApexPolicyMatrix.png[APEX Policy Matrix] + +The policy can support one of a number of stimuli with an associated purpose/model of the policy, for instance: + +* Configuration, i.e. what should happen. + An example is an event that states an intended network configuration and the policy should provide the detailed actions for it. + The policy can be realized for instance as an obligation policy, a promise or an intent. +* Report, i.e. something did happen. + An example is an event about an error or fault and the policy needs to repair that problem. + The policy would usually be an obligation, utility function, or goal policy. +* Monitoring, i.e. something does happen. + An example is a notification about certain network conditions, to which the policy might (or might not) react. + The policy will mitigate the monitored events or permit (deny) related actions as an obligation or authorization. +* Analysis, i.e. why did something happen. + An example is an analytic component sends insights of a situation requiring a policy to act on it. + The policy can solve the problem, escalate it, or delegate it as a refrain or delegation policy. +* Prediction, i.e. what will happen next. + An example are events that a policy uses to predict a future network condition. + The policy can prevent or enforce the prediction as an adaptive policy, a utility function, or a goal. +* Feedback, i.e. why did something happen or not happen. + Similar to analysis, but here the feedback will be in the input event and the policy needs to something with that information. + Feedback can be related to history or experience, for instance a previous policy execution. + The policy needs to be context-aware or be a meta-policy. + +Once the purpose of the policy is decided, the next step is to look into what context information the policy will require to do its job. +This can range from very simple to a lot of different information, for instance: + +* No context, nothing but a trigger event, e.g. a string or a number, is required +* Event context, the incoming event provides all information (more than a string or number) for the policy +* Policy context (read only), the policy has access to additional information related to its class but cannot change/alter them +* Policy context (read and write), the policy has access to additional information related to its class and can alter this information (for instance to record historic information) +* Global context (read only), the policy has access to additional information of any kind but cannot change/alter them +* Global context (read and write), the policy the policy has access to additional information of any kind and can alter this information (for instance to record historic information) + +The next step is to decide how the policy should do its job, i.e. what flavor it has, how many states are needed, and how many tasks. +There are many possible combinations, for instance: + +* Simple / God: a simple policy with 1 state and 1 task, which is doing everything for the decision-making. + This is the ideal policy for simple situation, e.g. deciding on configuration parameters or simple access control. +* Simple sequence: a simple policy with a number of states each having a single task. + This is a very good policy for simple decision-making with different steps. + For instance, a classic action policy (ECA) would have 3 states (E, C, and A) with some logic (1 task) in each state. +* Simple selective: a policy with 1 state but more than one task. + Here, the appropriate task (and it's logic) will be selected at execution time. + This policy is very good for dealing with similar (or the same) situation in different contexts. + For instance, the tasks can be related to available external software, or to current work load on the compute node, or to time of day. +* Selective: any number of states having any number of tasks (usually more than 1 task). + This is a combination of the two policies above, for instance an ECA policy with more than one task in E, C, and A. +* Classic directed: a policy with more than one state, each having one task, but a non-sequential execution. + This means that the sequence of the states is not pre-defined in the policy (as would be for all cases above) but calculated at runtime. + This can be good to realize decision trees based on contextual information. +* Super Adaptive: using the full potential of the APEX policy model, states and tasks and state execution are fully flexible and calculated at runtime (per policy execution). + This policy is very close to a general programming system (with only a few limitations), but can solve very hard problems. + +The final step is to select a response that the policy creates. +Possible responses have been discussed in the literature for a very long time. +A few examples are: + +* Obligation (deontic for what should happen) +* Authorization (e.g. for rule-based or other access control or security systems) +* Intent (instead of providing detailed actions the response is an intent statement and a further system processes that) +* Delegation (hand the problem over to someone else, possibly with some information or instructions) +* Fail / Error (the policy has encountered a problem, and reports it) +* Feedback (why did the policy make a certain decision) diff --git a/src/site-docs/adoc/fragments/apex-intro/resources.adoc b/src/site-docs/adoc/fragments/apex-intro/resources.adoc new file mode 100644 index 000000000..f4c8b947a --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/resources.adoc @@ -0,0 +1,19 @@ +// +// ============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) +// + +== Resources + +* APEX Documentation hosted on Github: link:https://ericsson.github.io/apex-docs[] +* APEX source code repo hosted on Github: link:https://github.com/Ericsson/apex[] +* Issue Management (source and documentation): link:https://github.com/Ericsson/apex/issues[] +* List of APEX publications: link:https://ericsson.github.io/apex-docs/apex-publications.html[] diff --git a/src/site-docs/adoc/fragments/apex-intro/upee-clustering.adoc b/src/site-docs/adoc/fragments/apex-intro/upee-clustering.adoc new file mode 100644 index 000000000..1ce6142ad --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/upee-clustering.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) +// + +== Flexible Clustering + +APEX can be clustered in various ways. +The following figure shows a few of these clustering options. +Cluster, engine and (policy) executors are named UPec (universal policy cluster), UPe (universal policy engine, APEX engine) and UPx (universal policy executor, the APEX internal state machine executor). + +.APEX Clustering Options +image::apex-intro/UpeeClusterOptions.png[APEX Clustering Options] + +[loweralpha] +. Single source/target, single UPx + * Simple forward +. Multiple sources/targets, single UPx + * Simple forward +. Single source/target, multiple UPx + * Multithreading (MT) in UPe +. Multiple sources/targets, multiple UPx instances + * Simple forward & MT in UPe +. Multiple non-MT UPe in UPec + * Simple event routing +. Multiple MT UPe in UPec + * Simple event routing +. Mixed UPe in UPec + * Simple event routing +. Multiple non-MT UPec in UPec + * Intelligent event routing +. Multiple mixed UPec in UPec + * Intelligent event routing + +["loweralpha", start=11] +. Mix of UPec in multiple UPec + * External intelligent event routing + * Optimized with UPec internal routing diff --git a/src/site-docs/adoc/fragments/apex-intro/upee-deployment.adoc b/src/site-docs/adoc/fragments/apex-intro/upee-deployment.adoc new file mode 100644 index 000000000..63608b836 --- /dev/null +++ b/src/site-docs/adoc/fragments/apex-intro/upee-deployment.adoc @@ -0,0 +1,44 @@ +// +// ============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) +// + +== Flexible Deployment + +APEX can be deployed in various ways. +The following figure shows a few of these deployment options. +Engine and (policy) executors are named UPe (universal policy engine, APEX engine) and UPx (universal policy executor, the APEX internal state machine executor). + +.APEX Deployment Options +image::apex-intro/UpeeDeploymentOptions.png[APEX Deployment Options] + +[loweralpha] +. For an interface or class + * Either UPx or UPe as association +. For an application + * UPx as object for single policies + * UPe as object for multiple policies +. For a component (as service) + * UPe as service for requests + * UPec as service for requests +. As a service (PolaS) + * One or more UPe with service i/f + * One or more Upec/UPec with service i/f + * One or more Upec/UPec with service i/f +. In a control loop + * UPe as decision making part + * UPec as decision making part +. On cloud compute nodes + * Nodes with only UPe or Upec + * Nodes with any combination of UPe, UPec +. A cloud example + * Left: 2 UPec managing several UPe on different cloud nodes + * Right: 2 large UPec with different UPe/UPec deployments 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] + diff --git a/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc new file mode 100644 index 000000000..973564df3 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-model-2-cli.adoc @@ -0,0 +1,62 @@ +// +// ============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) +// + +== Application: Convert a Policy Model to CLI Editor Commands + +**Status: Experimental** + +This application takes a policy model (JSON or XML encoded) and generates commands for the APEX CLI Editor. +This effectively reverses a policy specification realized with the CLI Editor. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh model-2-cli [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat model-2-cli [args] +---- +|==================== + +The option `-h` provides a help screen. + +[source%nowrap,sh] +---- +usage: gen-model2cli + -h,--help prints this help and usage screen + -m,--model <MODEL-FILE> set the input policy model file + -sv,--skip-validation switch of validation of the input file + -v,--version prints the application version +---- + +For instance, running the tool with the __Sample Domain__ policy model as: +[source%nowrap,sh] +---- +apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli +---- + +will produce the following status messages: + +[source%nowrap,sh] +---- +gen-model2cli: starting CLI generator + --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json +---- + +and then run the generator application producing all CLI Editor commands and printing them to standard out. + diff --git a/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc new file mode 100644 index 000000000..bd31bedf9 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-tpl-event-json.adoc @@ -0,0 +1,99 @@ +// +// ============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) +// + +== Application: Create Event Templates + +**Status: Experimental** + +This application takes a policy model (JSON or XML encoded) and generates templates for events in JSON format. +This can help when a policy defines rather complex trigger or action events or complex events between states. +The application can produce events for the types: stimuli (policy trigger events), internal (events between policy states), and response (action events). + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh tpl-event-json [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] +---- +|==================== + +The option `-h` provides a help screen. + +[source%nowrap,sh] +---- +usage: gen-model2event + -h,--help prints this help and usage screen + -m,--model <MODEL-FILE> set the input policy model file + -t,--type <TYPE> set the event type for generation, one of: + stimuli (trigger events), response (action + events), internal (events between states) + -v,--version prints the application version +---- + +The created templates are not valid events, instead they use some markup for values one will need to change to actual values. +For instance, running the tool with the __Sample Domain__ policy model as: +[source%nowrap,sh] +---- +apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli +---- + +will produce the following status messages: + +[source%nowrap,sh] +---- +gen-model2event: starting Event generator + --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json + --> type: stimuli +---- + +and then run the generator application producing two event templates. +The first template is called `Event0000`. + +[source%nowrap,json] +---- +{ + "name" : "Event0000", + "nameSpace" : "org.onap.policy.apex.sample.events", + "version" : "0.0.1", + "source" : "Outside", + "target" : "Match", + "TestTemperature" : ###double: 0.0###, + "TestTimestamp" : ###long: 0###, + "TestMatchCase" : ###integer: 0###, + "TestSlogan" : "###string###" +} +---- +The values for the keys are marked with `###` and the expected type of the value. +To create an actual stimuli event, all these markers need to be change to actual values, for instance: +[source%nowrap,json] +---- +{ + "name" : "Event0000", + "nameSpace" : "org.onap.policy.apex.sample.events", + "version" : "0.0.1", + "source" : "Outside", + "target" : "Match", + "TestTemperature" : 25, + "TestTimestamp" : 123456789123456789, + "TestMatchCase" : 1, + "TestSlogan" : "Testing the Match Case with Temperature 25" +} +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc b/src/site-docs/adoc/fragments/howto-apex/app-ws.adoc new file mode 100644 index 000000000..f11bdf277 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/app-ws.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) +// + +== Application: Websocket Clients (Echo and Console) + +**Status: Production** + +The application launcher also provides a Websocket echo client and a Websocket console client. +The echo client connects to APEX and prints all events it receives from APEX. +The console client connects to APEX, reads input from the command line, and sends this input as events to APEX. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh ws-echo [args] +# $APEX_HOME/bin/apexApps.sh ws-console [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat ws-echo [args] +> %APEX_HOME%\bin\apexApps.bat ws-console [args] +---- +|==================== + +The arguments are the same for both applications: + +- `-p` defines the Websocket port to connect to (defaults to `8887`) +- `-s` defines the host on which a Websocket server is running (defaults to `localhost`) + +A discussion on how to use these two applications to build an APEX system is detailed HowTo-Websockets. + diff --git a/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc new file mode 100644 index 000000000..4222b436a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/application-launcher.adoc @@ -0,0 +1,80 @@ +// +// ============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) +// + +== The APEX Application Launcher +The standard applications (Engine, CLI Editor, REST Editor) come with dedicated start scripts. +For all other APEX applications, we provide an application launcher. + +On UNIX and Cygwin systems use: + +- apexApps.sh` - simply starts the application launcher + +On Windows systems use: + +- `apexApps.bat` - simply starts the application launcher + + +Summary of alternatives to start the APEX application launcher: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexApps.sh [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexApps.bat [args] +---- +|==================== + +The option `-h` provides a help screen with all launcher command line arguments. + +[source%nowrap,sh] +---- +apexApps.sh - runs APEX applications + + Usage: apexApps.sh [options] | [<application> [<application options>]] + + Options + -d <app> - describes an application + -l - lists all applications supported by this script + -h - this help screen +---- + +Using `-l` lists all known application the launcher can start. + +[source%nowrap,sh] +---- +apexApps.sh: supported applications: + --> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console +---- + +Using the `-d <name>` option describes the named application, for instance for the `ws-console`: + +[source%nowrap,sh] +---- +apexApps.sh: application 'ws-console' + --> a simple console sending events to APEX, connect to APEX consumer port +---- + +Launching an application is done by calling the script with only the application name and any CLI arguments for the application. +For instance, starting the `ws-echo` application with port `8888`: +[source%nowrap,sh] +---- +apexApps.sh ws-echo -p 8888 +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc new file mode 100644 index 000000000..e677079f2 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/cli-editor.adoc @@ -0,0 +1,82 @@ +// +// ============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) +// + +== The APEX CLI Editor +The CLI Editor allows to define policies from the command line. +The application uses a simple language and supports all elements of an APEX policy. +It can be used in to different ways: + +- non-interactive, specifying a file with the commands to create a policy +- interactive, using the editors CLI to create a policy + +When a policy is fully specified, the editor will generate the APEX core policy specification in JSON. +This core specification is called the policy model in the APEX engine and can be used directly with the APEX engine. + +On UNIX and Cygwin systems use: + +- `apexCLIEditor.sh` - simply starts the CLI editor, arguments to the script determine the mode of the editor +- `apexApps.sh cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor + +On Windows systems use: + +- `apexCLIEditor.bat` - simply starts the CLI editor, arguments to the script determine the mode of the editor +- `apexApps.bat cli-editor` - simply starts the CLI editor, arguments to the script determine the mode of the editor + + +Summary of alternatives to start the APEX CLI Editor: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexCLIEditor.sh.sh [args] +# $APEX_HOME/bin/apexApps.sh cli-editor [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexCLIEditor.bat [args] +> %APEX_HOME%\bin\apexApps.bat cli-editor [args] +---- +|==================== + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...] +options + + -a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use + -c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor + -h,--help outputs the usage of this command + -i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor + -if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and continue + executing the command file + -l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will log + to standard output if not specified or suppressed with "-nl" flag + -m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use + -nl,--no-log if specified, no logging or output of commands to standard output or log + file is carried out + -nm,--no-model-output if specified, no output of a model to standard output or model output + file is carried out, the user can use the "save" command in a script to + save a model + -o,--output-model-file <OUTPUT_MODEL_FILE> name of a file that will contain the output model for the editor, will + output model to standard output if not specified or suppressed with + "-nm" flag + -wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the + root from which to look for included macro files +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc new file mode 100644 index 000000000..52836a783 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/eng-deployment.adoc @@ -0,0 +1,50 @@ +// +// ============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) +// + +== The APEX Deployment Client +The standard way to use the APEX Deployment Client is via an installation of the __war__ file on a webserver. +However, the Deployment Client can also be started via command line. +This will start a Grizzly webserver with the __war__ deployed. +Access to the Deployment Client is then via the provided URL + +On UNIX and Cygwin systems use: + +- `apexApps.sh eng-deployment` - simply starts the webserver with the Deployment Client + +On Windows systems use: + +- `apexApps.bat eng-deployment` - simply starts the webserver with the Deployment Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.client.deployment.rest.ApexDeploymentRestMain [options...] +-h,--help outputs the usage of this command +-p,--port <PORT> port to use for the Apex Services REST calls +-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating +---- + +If the Deployment Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ +---- + +The last line states the URL on which the Deployment Client can be accessed. +The example above stated `http://localhost:18989/apexservices`. +In a web browser use the URL `http://localhost:18989`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc new file mode 100644 index 000000000..960546d06 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/eng-monitoring.adoc @@ -0,0 +1,50 @@ +// +// ============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) +// + +== The APEX Monitoring Client +The standard way to use the APEX Monitoring Client is via an installation of the __war__ file on a webserver. +However, the Monitoring Client can also be started via command line. +This will start a Grizzly webserver with the __war__ deployed. +Access to the Monitoring Client is then via the provided URL + +On UNIX and Cygwin systems use: + +- `apexApps.sh eng-monitoring` - simply starts the webserver with the Monitoring Client + +On Windows systems use: + +- `apexApps.bat eng-monitoring` - simply starts the webserver with the Monitoring Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.client.monitoring.rest.ApexMonitoringRestMain [options...] +-h,--help outputs the usage of this command +-p,--port <PORT> port to use for the Apex Services REST calls +-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating +---- + +If the Monitoring Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ +---- + +The last line states the URL on which the Monitoring Client can be accessed. +The example above stated `http://localhost:18989/apexservices`. +In a web browser use the URL `http://localhost:18989`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/engine.adoc b/src/site-docs/adoc/fragments/howto-apex/engine.adoc new file mode 100644 index 000000000..819c2ca87 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/engine.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) +// + +== The APEX Engine +The APEX engine can be started in different ways, depending your requirements. +All scripts are located in the APEX __bin__ directory + +On UNIX and Cygwin systems use: + +- `apexEngine.sh` - this script will + ** Test if `$APEX_USER` is set and if the user exists, terminate with an error otherwise + ** Test if `$APEX_HOME` is set. If not set, it will use the default setting as `/opt/ericsson/apex/apex`. + Then the set directory is tested to exist, the script will terminate if not. + ** When all tests are passed successfully, the script will call `apexApps.sh` with arguments to start the APEX engine. +- `apexApps.sh engine` - this is the general APEX application launcher, which will + ** Start the engine with the argument `engine` + ** Test if `$APEX_HOME` is set and points to an existing directory. If not set or directory does not exist, script terminates. + ** Not test for any settings of `$APEX_USER`. + +On Windows systems use `apexEngine.bat` and `apexApps.bat engine` respectively. +Note: none of the windows batch files will test for `%APEX_USER%`. + +Summary of alternatives to start the APEX Engine: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexEngine.sh [args] +# $APEX_HOME/bin/apexApps.sh engine [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexEngine.bat [args] +> %APEX_HOME%\bin\apexApps.bat engine [args] +---- +|==================== + + +The APEX engine comes with a few CLI arguments for setting configuration and policy model. +The configuration file is always required. +The policy model file is only required if no model file is specified in the configuration, or if the specified model file should be over written. +The option `-h` prints a help screen. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] +options + -c,--config-file <CONFIG_FILE> the full path to the configuration file to use, + the configuration file must be a Json + file containing the Apex configuration parameters + -h,--help outputs the usage of this command + -m,--model-file <MODEL_FILE> the full path to the model file to use, + if set it overrides the model file set in the + configuration file + -v,--version outputs the version of Apex +---- + diff --git a/src/site-docs/adoc/fragments/howto-apex/full-client.adoc b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc new file mode 100644 index 000000000..97a18393b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/full-client.adoc @@ -0,0 +1,51 @@ +// +// ============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) +// + +== The APEX Full Client +The APEX Full Client combines the REST Editor, the Monitoring Client, and the Deployment Client into a single application. +The standard way to use the APEX Full Client is via an installation of the __war__ file on a webserver. +However, the Full Client can also be started via command line. +This will start a Grizzly webserver with the __war__ deployed. +Access to the Full Client is then via the provided URL + +On UNIX and Cygwin systems use: + +- `apexApps.sh full-client` - simply starts the webserver with the Full Client + +On Windows systems use: + +- `apexApps.bat full-client` - simply starts the webserver with the Full Client + + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.services.client.full.rest.ApexServicesRestMain [options...] +-h,--help outputs the usage of this command +-p,--port <PORT> port to use for the Apex Services REST calls +-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating +---- + +If the Full Client is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ +---- + +The last line states the URL on which the Monitoring Client can be accessed. +The example above stated `http://localhost:18989/apexservices`. +In a web browser use the URL `http://localhost:18989`. + diff --git a/src/site-docs/adoc/fragments/howto-apex/introduction.adoc b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc new file mode 100644 index 000000000..faa2f4949 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/introduction.adoc @@ -0,0 +1,51 @@ +// +// ============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 Engine and Applications +The core of APEX is the APEX Engine, also known as the APEX Policy Engine. +Beside this engine, an APEX system comes with a few applications intended to help with policy authoring, deployment, and execution. + +The engine itself and most applications are started from the command line with command line arguments. +This is called a Command Line Interface (CLI). +Some applications require an installation on a webserver, as for instance the REST Editor. +Those applications can be accessed via a web browser. + +Starting with APEX version 0.5.6, we also provide plugins for Eclipse realizing a policy development environment. +Those plugins support the main APEX policy language. +Other, higher-level, policy languages will be added in future versions along with their Eclipse plugins. +Furthermore, we are planning to provide a backend supporting the Language Server Protocol (LSP). +This backend, run as a server, will allow to join any editor or IDE that is LSP-enabled to benefit from the APEX policy languages. + +Last not least, one can use the available APEX APIs and applications to develop other applications as required. +This includes policy languages (and associated parsers and compilers / interpreters), GUIs to access APEX or to define policies, clients to connect to APEX, etc. +Separate documentation will be available in APEX releases addressing this type of applications. + +For this documentation, we assume an installation of APEX as a full system (i.e. not minimal) of version 0.5.6 or higher. + +== CLI on Unix, Windows, and Cygwin +A note on APEX CLI applications: all applications and the engine itself have been deployed and tested on different operating systems: Red Hat, Ubuntu, Debian, Mac OSX, Windows, Cygwin. +Each operating system comes with its own way of configuring and executing Java. +The main items here are: + +- For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the provided bash scripts work as expected + with absolute paths (e.g. `/opt/ericsson/apex/apex-{release-version}/examples`), + indirect and linked paths (e.g. `../apex/apex`), + and path substitutions using environment settings (e.g. `$APEX_HOME/bin/`) +- For Windows systems, the provided batch files (`.bat`) work as expected with + with absolute paths (e.g. `C:\apex\apex-{release-version}\examples`), + and path substitutions using environment settings (e.g. `%APEX_HOME%\bin\`) +- For Cygwin system we assume a standard Cygwin installation with standard tools (mainly bash) using a Windows Java installation. + This means that the bash scripts can be used as in UNIX, however any argument pointing to files and directories need to use either a DOS path (e.g. `C:\apex\apex-{release-version}\examples\config\...`) + or the command `cygpath` with a mixed option. + The reason for that is: Cygwin executes Java using UNIX paths but then runs Java as a DOS/WINDOWS process, which requires DOS paths for file access. + diff --git a/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc new file mode 100644 index 000000000..3be6f9f94 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-apex/rest-editor.adoc @@ -0,0 +1,74 @@ +// +// ============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) +// + +== The APEX REST Editor +The standard way to use the APEX REST Editor is via an installation of the __war__ file on a webserver. +However, the REST editor can also be started via command line. +This will start a Grizzly webserver with the __war__ deployed. +Access to the REST Editor is then via the provided URL + +On UNIX and Cygwin systems use: + +- `apexRESTEditor.sh` - simply starts the webserver with the REST editor +- `apexApps.sh rest-editor` - simply starts the webserver with the REST editor + +On Windows systems use: + +- `apexRESTEditor.bat` - simply starts the webserver with the REST editor +- `apexApps.bat rest-editor` - simply starts the webserver with the REST editor + + +Summary of alternatives to start the APEX REST Editor: + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh] +---- +# $APEX_HOME/bin/apexRESTEditor.sh.sh [args] +# $APEX_HOME/bin/apexApps.sh rest-editor [args] +---- +| +[source%nowrap,bat] +---- +> %APEX_HOME%\bin\apexRESTEditor.bat [args] +> %APEX_HOME%\bin\apexApps.bat rest-editor [args] +---- +|==================== + +The option `-h` provides a help screen with all command line arguments. + +[source%nowrap,sh] +---- +usage: org.onap.policy.apex.auth.rest.ApexEditorMain [options...] +-h,--help outputs the usage of this command +-l,--listen <ADDRESS> the IP address to listen on. Default value is 0.0.0.0 to listen on all available + addresses. Use value 'localhost' to restrict access to the local machine only. +-p,--port <PORT> port to use for the Apex RESTful editor REST calls. +-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default + value is -1 to run indefinitely. +---- + +If the REST Editor is started without any arguments the final messages will look similar to this: + +[source%nowrap,sh] +---- +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://0.0.0.0:18988/apex/, TTL=-1sec], State=RUNNING) started at http://0.0.0.0:18988/apex/ +---- + +The last line states the URL on which the REST Editor can be accessed. +The example above stated `http://0.0.0.0:18988/apex/`. +In a web browser use the URL `http://localhost:18988` and the REST Editor will start. + diff --git a/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc b/src/site-docs/adoc/fragments/howto-build/checkstyle.adoc new file mode 100644 index 000000000..f1a8a003f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/checkstyle.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) +// + +== Checkstyle with Maven + +The codestyle for all APEX java projects can be checked automatically. +The checks include empty or non-existing Javadocs. +Any checkstyle run should complete without any errors, some warnings are acceptable. + +To run checkstyle on an APEX Maven project use: + +[source%nowrap,sh] +---- +mvn checkstyle:check +---- + + +To run checkstyle on all modules use: + +[source%nowrap,sh] +---- +mvn checkstyle:checkstyle -DapexAll +---- + diff --git a/src/site-docs/adoc/fragments/howto-build/documentation.adoc b/src/site-docs/adoc/fragments/howto-build/documentation.adoc new file mode 100644 index 000000000..3a42cc78b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/documentation.adoc @@ -0,0 +1,41 @@ +// +// ============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) +// + +== Build the APEX Documentation + +The APEX Maven build also includes stand-alone documentations, such as the HowTo documents, the Installation Guide, and the User Manual. +Use Maven to build the APEX Documentation. +The Maven options `-N` prevents Maven to go through all APEX modules, which is not necessary for the documentation. +The final documents will be in `target/generated-docs` (Windows: `target\generated-docs`). +The __HTML__ documents are in the `html/` folder, the __PDF__ documents are in the `pdf/` folder. +Once the documentation is build, copy the __HTML__ and __PDF__ documents to a folder of choice + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean generate-resources -N -DapexDocs +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean generate-resources -N -DapexDocs +---- +|==================== + + diff --git a/src/site-docs/adoc/fragments/howto-build/introduction.adoc b/src/site-docs/adoc/fragments/howto-build/introduction.adoc new file mode 100644 index 000000000..02ba21fbd --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/introduction.adoc @@ -0,0 +1,56 @@ +// +// ============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 building APEX + +APEX is written 100% in Java and uses link:https://maven.apache.org/[Apache Maven] as the build system. +The requirements for building APEX are: + +- An installed Java development kit for Java version 8 or higher + ** To install a Java SDK please follow these guidelines link:https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html[Oracle Java 8 SDK]. +- Maven 3 + ** To get Maven 3 running please follow the guidelines for link:https://maven.apache.org/download.cgi[Download] and link:https://maven.apache.org/install.html[Install], and link:https://maven.apache.org/run.html[Run] Maven +- A clone of the APEX source repositories + +To get a clone of the APEX source repositories, please see the APEX Installation Guide or the APEX User manual. + +One all requirements are in place, APEX can be build. +There are several different artifacts one can create building APEX, most of them defined in their own __profile__. +APEX can also be build in a standard way with standard tests (`mvn clean install`) or without standard tests (`mvn clean install -DskipTests`). + +The examples in this document assume that the APEX source repositories are cloned to: + +- Unix, Cygwin: `/usr/local/src/apex` +- Windows: `C:\dev\apex` +- Cygwin: `/cygdrive/c/dev/apex` + +[IMPORTANT] +.A Build needs Space +==== +Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for the downloaded dependencies +==== + +[IMPORTANT] +.A Build requires Internet (for first build to download all dependencies and plugins) +==== +During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven repository. +The first standard build (and any first specific build) requires Internet access to download those dependencies. +==== + +[IMPORTANT] +.Building RPM distributions +==== +RPM images are only build if the `rpm` package is installed (Unix). +To install `rpm` run `sudo apt-get install rpm`, then build APEX. +==== + diff --git a/src/site-docs/adoc/fragments/howto-build/site.adoc b/src/site-docs/adoc/fragments/howto-build/site.adoc new file mode 100644 index 000000000..42cbda525 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/site.adoc @@ -0,0 +1,93 @@ +// +// ============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) +// + +== Build APEX Site + +The APEX Maven build comes with full support to build a web site using Maven Site. +Use Maven to build the APEX Site. +Stage the APEX web site. +The target folder for the staged site is + +- Unix: `/usr/local/src/apex/target/gh-pages` +- Windows: `C:\dev\apex\target\gh-pages` +- Cygwin: `/cygdrive/c/dev/apex/target/gh-pages` + +Once the web site is staged, copy the full site to a folder of choice or into a web server. + + +[IMPORTANT] +.Building a Site takes Time +==== +Building and staging the APEX web site can take very long. +The stand-alone documentation will take about 2 minutes. +The sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine +(~10 minutes without generating source and test-source reports, closer to 30 minutes with all reports). +==== + + +Start the build deleting the staging directory that might have been created by a previous site build. +Then go to the APEX packaging directory. + +[width="100%",options="header",cols="5a,5a,5a"] +|==================== +| Unix | Windows | Cygwin +| +[source%nowrap,sh] +---- +cd /usr/local/src/apex +rm -fr target/gh-pages +---- +| +[source%nowrap,bat] +---- +c: +cd \dev\apex +rmdir /s /q target\gh-pages +---- +| +[source%nowrap,sh] +---- +cd /cygdrive/c/dev/apex +rm -fr target/gh-pages +---- +|==================== + +the workflow for building a complete site then is as follows: + +[source%nowrap,sh] +---- +mvn clean -DapexAll #<1> +mvn install -DskipTests #<2> +mvn generate-resources -N -DapexDocs #<3> +mvn initialize site:attach-descriptor site site:stage -DapexSite #<4> +---- +. First clean all modules to remove any site artifacts, use the _apexXtext_ profile to make sure these modules are processed as well +. Next run a simple install without tests +. Now generate the APEX stand -alone documentation, they are in the local package only so we can use the _-N_ switch +. Last build the actual sites and stage (copy to the staging directory) with the profile _apexSite_ (do not forget the initialize goal, otherwise the staging directory will not be correctly set and sites are staged in every model in a directory called `docs`). + +If you want to build the site for a particular project for testing, the Maven command is simpler. +Since only the main project has APEX documentation (stand-alone), you can use Maven as follow. + +[source%nowrap,sh] +---- +mvn clean site -DapexSite +---- + +If you want to stage the tested site, then use + +[source%nowrap,sh] +---- +mvn clean initialize site:attach-descriptor site site:stage -DapexSite +---- + diff --git a/src/site-docs/adoc/fragments/howto-build/standard.adoc b/src/site-docs/adoc/fragments/howto-build/standard.adoc new file mode 100644 index 000000000..76ebfc2bf --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/standard.adoc @@ -0,0 +1,86 @@ +// +// ============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 Build + +Use Maven to for a standard build without any tests. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +The build takes 2-3 minutes on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +The build will have created all artifacts required for an APEX installation. +The following example show how to change to the target directory and how it should look like. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-components.adoc new file mode 100644 index 000000000..4cd08cf0d --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-all-components.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) +// + +== Build with all Components + +A standard APEX build will not build all components. +Some parts are for specific deployments, only. +Use Maven to for a standard build with __all__ components. + +[IMPORTANT] +.Might require specific software +==== +When building all components, some modules require specific software installed on the build machine. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DapexAll +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DapexAll +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc new file mode 100644 index 000000000..6fa654d00 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-all-tests.adoc @@ -0,0 +1,50 @@ +// +// ============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) +// + +== Build with all Tests + +Use Maven to for a standard build with __all__ tests. + +[IMPORTANT] +.Some tests have specific timing Requirements +==== +Some of the tests have very specific timing requirements. +If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well. +If this happens, reduce the load on your build machine and restart the build. +==== + +[IMPORTANT] +.Might require specific software +==== +When running all tests, some modules require specific software installed on the build machine. +For instance, testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan installed on the build machine. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DallTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DallTests +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-build/with-tests.adoc b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc new file mode 100644 index 000000000..f8d300c45 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-build/with-tests.adoc @@ -0,0 +1,57 @@ +// +// ============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) +// + +== Build with standard Tests + +Use Maven to for a standard build with standard tests. + +[IMPORTANT] +.Some tests have specific timing Requirements +==== +Some of the tests have very specific timing requirements. +If run on a low-powered build machine, or if the build machine is on high load, those tests might fail and the whole build might fail as well. +If this happens, reduce the load on your build machine and restart the build. +==== + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install +---- +|==================== + +The build takes about 5-6 minutes with tests on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. +If build with tests (i.e. without `-DskipTests`), there will be error messages and stack trace prints from some tests. +This is normal, as long as the build finishes successful. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, with tests] +---- + +The build will have created all artifacts required for an APEX installation. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc b/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc new file mode 100644 index 000000000..776ad3448 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc @@ -0,0 +1,27 @@ +// +// ============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: APEX Codestyle + +This page describes how to apply a code style to the APEX Java projects. +The provided code templates are guidelines and are provided for references and as examples. +We will not engage in "holy war" on style for coding. +As long as the style of a particular block of code is understandable, consistent, and readable, please feel free to adapt or modify these guides or use other guides as you see fit. + +The JAutoDoc and Checkstyle Eclipse Plugins and tools are useful and remove a lot of the tedium from code documentation. +Use them to check your code and please fix any issues they identify with your code. + +The templates and examples on this page have been tested on a clean installation of Eclipse Oxygen Release (4.7.0) on Ubuntu Linux 16.04 LTS. + +The Apex settings referred to on this page are also available in the apex-model GIT repository in the APEX model repository in apex-model/apex-model.build-tools/src/main/resources/`. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc b/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc new file mode 100644 index 000000000..8b7f122b8 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc @@ -0,0 +1,38 @@ +// +// ============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) +// + +== Java coding Rules + +* APEX is (in large parts) a platform (or middleware), so link:https://en.wikipedia.org/wiki/Software_design_pattern[Software Design Patterns] are a good thing +* The link:https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)[Solid Principles] apply +* Avoid class fields scoped as `protected` + ** They break a lot of good design rules, e.g. most SOLID rules + ** For a discussion see this link:https://softwareengineering.stackexchange.com/questions/162643/why-is-clean-code-suggesting-avoiding-protected-variables[Stackoverflow Question] +* If you absolutely need `protected` class fields they should be `final` +* Avoid `default` scope for class fields and methods + ** For fields: use `public` or `private` (see also above) + ** For methods: use `public` for general use, `protected` for specialization using inheritance (ideally `final`), `private` for everything else +* Method parameters that are not changed in the method should be marked `final` +* Every package must have a `package-info.java` file with an appropriate description, minimum a descriptive one liner +* Every class must have + ** The common header (copyright, file, date) + ** Javadoc header for the class with description of the class and author + ** Javadoc for _all public__ fields + ** If possible, Javadoc for __private__ fields, at least some documentation for private fields + ** Javadoc for __all__ methods +* All project must build with all tests on Unix, Windows, __and__ Cygwin + ** Support all line endings in files, e.g. `\n` and `\r\n` + ** Be aware of potential differences in exception messages, if testing against a message + ** Support all types of paths: Unix with `/`, Windows with an optinal drive `C:\` and `\`, Cygwin with mixed paths + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc b/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc new file mode 100644 index 000000000..c0b6fa31f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc @@ -0,0 +1,25 @@ +// +// ============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) +// + +== Eclipse Plugin: JAutodoc + +This plugin is a helper plugin for writing Javadoc. +It will automatically create standard headers on files, create package-info.java files and will put in remarkably good stub Javadoc comments in your code, using class names and method names as hints. + +Available from the Eclipse Marketplace. +In Eclipse Help->Eclipse Marketplace... and type `JAutodoc`. +Select JAutodoc when the search returns and install it. + +You must configure JAutoDoc in order to get the most out of it. +Ideally JAutoDoc should be configured with templates that cooperate with the inbuilt Eclipse Code Formatter for best results. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc new file mode 100644 index 000000000..a6a93bfa4 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc @@ -0,0 +1,26 @@ +// +// ============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) +// + +== Eclipse Plugin: Checkstyle + +This plugin integrates link:http://checkstyle.sourceforge.net/[Checkstyle] into Eclipse. +It will check your code and flag any checkstyle issues as warnings in the code. + +Available from the Eclipse Marketplace. +In Eclipse Help->Eclipse Marketplace... and type "Checkstyle". +Select "Checkstyle Plug-in" when the search returns and install it. +Note that "Checkstyle Plug-in" may not be the first result in the list of items returned. + +You must configure Checkstyle in order to get the most out of it. +There are two built-in style templates in Checkstyle (from Oracle and Google) but user will almost certainly wish to tweak these. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.adoc b/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.adoc new file mode 100644 index 000000000..9f13e817a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.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) +// + +== Configure Eclipse + +* Set the template for Eclipse code clean up + . menu:Eclipse[Window > Preferences > Java > Code Style > Clean Up] -> kbd:[Import...] + . Select your template file (`ApexCleanUpTemplate.xml`) and apply it +* Set the Eclipse code templates + . menu:Eclipse[Window > Preferences > Java > Code Style > Code Templates] -> kbd:[Import...] + . Select your templates file (`ApexCodeTemplates.xml`) and apply it + ** Make sure to set your email address in generated comments by selecting "Comments->Types" in the "Configure generated code and comments:" pane, then change the email address on the @author tag to be your email address +* Set the Eclipse Formatter profile + . menu:Eclipse[Window > Preferences > Java > Code Style > Formatter] -> kbd:[Import...] + . Select your formatter profile file (`ApexFormatterProfile.xml`) and apply it + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc b/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc new file mode 100644 index 000000000..48c8ee6d7 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc @@ -0,0 +1,25 @@ +// +// ============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) +// + +== Configure JAutodoc (Eclipse) + +Import the settings for JAutodoc: + + . menu:Eclipse[Window > Preferences > Java > JAutodoc] -> kbd:[Import All...] (at bottom of the JAutodoc preferences window) + . Leave all the preferences ticked to import all preferences, browse to the JAutodoc setting file (`ApexJautodocSettings.xml`) and press kbd:[OK] + . Set your email address in the package Javadoc template + * Press kbd:[Edit Template...] in the Package Javadoc area of the JAutodoc preferences window, and change the email address on the `@author` tag to be your email address + . Now, apply the JAutodoc settings + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.adoc b/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.adoc new file mode 100644 index 000000000..2e6698fff --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.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) +// + +== Configure Checkstyle (Maven) + +When using a custom style configuration with Checkstyle, the definition of that style must of course be available to Checkstyle. +In order not to have to distribute style files for checkstyle into all Maven modules, it is recommended that a special Maven module be built that contains the checkstyle style definition. +That module is then used as a dependency in the __POM__ for all other modules that wish to use that checkstyle style. +For a full explanation see link:https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html[the explanation of Checkstyle multi-module configuration]. + +In Apex, the module `apex-model.build-tools` provides the Apex checkstyle style files as resources in `src/main/resources/checkstyle`. +This style is a slightly tweaked version of the standard Google checkstyle style that allows longer lines and has some other checks slightly relaxed. +Therefore, all modules that wish to use the Apex style must put the following build directive into their `pom.xml`. + +[source%nowrap,xml] +---- +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-checkstyle-plugin</artifactId> + <version>2.17</version> + <dependencies> + <dependency> + <groupId>org.onap.policy.apex.model</groupId> + <artifactId>apex-model.build-tools</artifactId> + <version>${project.version}</version> + </dependency> + </dependencies> + <configuration> + <configLocation>checkstyle/apex_style_checks.xml</configLocation> + <headerLocation>checkstyle/apex_header.txt</headerLocation> + </configuration> +</plugin> +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.adoc b/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.adoc new file mode 100644 index 000000000..381153f7b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.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) +// + +== Run Checkstyle (Maven) + +Run Checkstyle using Maven on the command line with the command: + +[source%nowrap,sh] +---- +mvn checkstyle:check +---- + +On the main APEX project, run a full checkstyle check as: + +[source%nowrap,sh] +---- +mvn checkstyle:checkstyle -DapexAll +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc b/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc new file mode 100644 index 000000000..507cbb9bd --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc @@ -0,0 +1,36 @@ +// +// ============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) +// + +== Configure Checkstyle (Eclipse, globally) + +. Set up a module with the Checkstyle style files (see above) +. In menu:Eclipse[Window > Preferences] go to Checkstyle +. Import the settings for Checkstyle + * Press kbd:[New...] to create a new __Global Check Configurations__ entry + * Give the configuration a name such as __Apex Checkstyle Configuration__ and select the __External Configuration File__ form in the __Type__ drop down menu + * Browse to the Checckstyle setting file (`ApexCheckstyleSettings.xml`) and press kbd:[OK] +. Press kbd:[OK] + * You may now get an __Unresolved Properties found__ dialogue + * This is because there is a second Checkstyle configuration file required to check file headers +. Press kbd:[Edit Properties...] and press kbd:[Find unresolved properties] on the next dialogue window +. The plugin will find the `${checkstyle.header.file}` property is unresolved and will ask should it be added to the properties, click kbd:[yes] +. Now, select the row on the dialogue for the `checkstyle.header.file property` and click kbd:[Edit...] +. Set the value of the `checkstyle.header.file property` to `<your-apex-git-location>/apex-model/apex-model.build-tools/src/main/resources/checkstyle/apex_header.txt` + * Of course replacing the tag `<your-apex-git-location>` with the location of your Apex GIT repository +. Press kbd:[OK], kbd:[OK], kbd:[OK] to back out to the main Checkstyle properties window +. Select the __Apex Checkstyle Configuration__ as your default configuration by selecting its line in the __Global Check Configuraitons__ list and clicking kbd:[Set as Default] +. Press kbd:[Apply and Close] to finish Checkstyle global configuration + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc b/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc new file mode 100644 index 000000000..d4cb45914 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc @@ -0,0 +1,35 @@ +// +// ============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) +// + +== Configure Checkstyle Blueprint + +As well as being configured globally, Checkstyle must be configured and activated for each project in Eclipse. +In order to make this process less tedious, set up the first project you apply Checkstye to as a blueprint project and then use this blueprint for all other projects. + +. Select the project you want to use as a blueprint + * For example, `apex-model.basic-model` in `apex` and enter the project properties by right clicking and selecting menu:Properties[] +. Click __Checkstyle__ on the properties to get the Checkstyle project configuration window +. Click the box __Checkstyle active for this project__ and in the __Exclude from checking...__ list check the boxes: + * [*] __files outside source directories__ + * [*] __derived (generated) files__ + * [*] __files from packages:__ +. Now, in order to turn off checking on resource directories and on JUnit tests + * Select the line __files from packages:__ in the __Exclude from checking...__ list and click kbd:[Change...] +. On the __Filter packages__ dialogue + * Check all the boxes except the top box, which is the box for __src/main/java__ + * Ensure that the __recursively exclude sub-packages__ check box is ticked + ** [*] __recursively exclude sub-packages__ + * Press kbd:[OK] +. Press kbd:[Apply and Close] to apply the changes + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc b/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc new file mode 100644 index 000000000..6ead28a7f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc @@ -0,0 +1,48 @@ +// +// ============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========================================================= + +== Use Eclipse Source Operations + +Eclipse Source Operations can be carried out on individual files or on all the files in a package but do not recurse into sub-packages. +They are available as a menu in Eclipse by selecting a file or package and right clicking on __Source__. +Note that running __Clean Up...__ with the Apex clean up profile will run __Format__ and __Organize Imports__. +So if you run a clean up on a file or package, you need not run __Format__ or __Organize Imports__. + +We recommend you use the following Eclipse Source Operations: + +. __Format__ applies the current format definition to the file or all files in a package +. __Organize Imports__ sorts the imports on each file in standard order +. __Clean Up__ runs a number of cleaning operations on each file. The Apex clean up template + ** Remove `this` qualifier for non static field accesses + ** Change non static accesses to static members using declaring type + ** Change indirect accesses to static members to direct accesses (accesses through subtypes) + ** Convert control statement bodies to block + ** Convert `for` loops to enhanced `for` loops + ** Add final modifier to private fields + ** Add final modifier to local variables + ** Remove unused imports + ** Remove unused private methods + ** Remove unused private constructors + ** Remove unused private types + ** Remove unused private fields + ** Remove unused local variables + ** Add missing `@Override` annotations + ** Add missing `@Override` annotations to implementations of interface methods + ** Add missing `@Deprecated` annotations + ** Add missing serial version ID (generated) + ** Remove unnecessary casts + ** Remove unnecessary `$NON-NLS$` tags + ** Organize imports + ** Format source code + ** Remove trailing white spaces on all lines + ** Correct indentation + ** Remove redundant type arguments + ** Add file header (JAutodoc) + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.adoc b/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.adoc new file mode 100644 index 000000000..0c3ab0518 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.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) +// + +== Using JAutodoc + +Similar to Eclipse Source Operations, JAutodoc operations can be carried out on individual files or on all the files in a package but do not recurse into sub-packages. +The JAutodoc operations are available by selecting a file or package and right clicking on __JAutodoc__: + +. To add a `package-info.java` file to a package, select the package and right-click menu:Jautodoc[Add Package Javadoc] +. To add headers to files select on a file (or on the package to do all files) and right click menu:JAutodoc[Add Header] +. To add JAutodoc stubs to a files, select on a file (or on the package to do all files) and right click menu:JAutodoc[Add Javadoc] + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc new file mode 100644 index 000000000..f639868ae --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc @@ -0,0 +1,32 @@ +// +// ============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) +// + +== Using Checkstyle + +In order to use Checkstyle, you must configure it per project and then activate it per project. +The easiest way to do this is to set up one project as a blueprint and use that blueprint for other projects (see above). +Once you have a blueprint project, you can use Checkstyle on other projects as follows + +. Set up Checkstyle on projects by selecting one or more projects + * Right clicking and selecting menu:Checkstyle[Configure project(s)] from __blueprint...__ and then selecting your blueprint project + * (for example `apex-model.basic-model`) from the list of projects and pressing kbd:[OK] +. Activate Checkstyle on projects by selecting one or more projects + * Right clicking and selecting menu:Checkstyle[Activate Checkstyle] + * Now Checkstyle warnings will appear on the selected projects if they have warnings +. You can disable Checkstyle checking on a file or a package (recursively) by selecting a file or package + * Right clicking and selecting menu:Checkstyle[Clear Checkstyle violations] +. You can enable Checkstyle checking on a file or a package (recursively) by selecting a file or package + * Right clicking and selecting menu:Checkstyle[Check Code with Checkstyle] +. On individual files, you can apply fixes that clear some Checkstyle warnings + * Select the file, right click and select menu:Apply Checkstyle fixes[] + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.adoc b/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.adoc new file mode 100644 index 000000000..adf480fb0 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.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) +// + +== Disable Eclipse Formatting (partially) + +Sometimes, the Eclipse code formatting results in correct but untidy indentation, for example when Java Persistence annotations or long sequences of lined-up assignments are formatted. +You can disable formatting for sections of code. + +. Ensure that Off/On Tags are enabled in Eclipse + . In menu:Eclipse[Window > Preferences > Java > Code Style > Formatter] window press kbd:[Edit...] + . Click on the __Off/On Tags__ tab + . Ensure that the __Enable Off/On Tags__ checkbox is checked +. Surround the section of code that you do not want the formatter to act on with comments containing the Off/On tags + + +[source%nowrap,java,numbered] +---- +// @formatter:off +// Plugin Parameters +private DistributorParameters distributorParameters = new DistributorParameters(); +private SchemaParameters schemaParameters = new SchemaParameters(); +private LockManagerParameters lockManagerParameters = new LockManagerParameters(); +private PersistorParameters persistorParameters = new PersistorParameters(); +// @formatter:on +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.adoc new file mode 100644 index 000000000..549df0726 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.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) +// + +== Supress Checkstyle (partially) + +Sometimes Checkstyle checks identify code that does not comply with Checkstyle rules. +In limited cases Checkstyle rules can be suppressed, for example where it is impossible to design the code in a way that complies with Checkstyle or where the Checkstyle rule is impossible to apply. +Checkstyle rules are suppressed as is explained in this link:https://stackoverflow.com/questions/4023185/how-to-disable-a-particular-checkstyle-rule-for-a-particular-line-of-code[Stackoverflow post]. + +The example below illustrates how to suppress a Checkstyle rule that specifies all methods must have seven parameters or less. + +[source%nowrap,java,numbered] +---- +// CHECKSTYLE:OFF: checkstyle:ParameterNumber +public myMethod(final int par1, final int par2, final int par3, final int par4, + final int par5, final int par6, final int par7, final int par8) { +} +// CHECKSTYLE:ON: checkstyle:ParameterNumber +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc new file mode 100644 index 000000000..ce6367ef9 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc @@ -0,0 +1,17 @@ +// +// ============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) +// + +[source%nowrap,text,subs="attributes+"] +---- +include::{apex-main-dir}/checkstyle/apex_header.txt[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc new file mode 100644 index 000000000..f67a01c0a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc @@ -0,0 +1,17 @@ +// +// ============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) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/checkstyle/apex_style_checks.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc new file mode 100644 index 000000000..255855b43 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc @@ -0,0 +1,17 @@ +// +// ============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) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexCheckstyleSettings.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc new file mode 100644 index 000000000..638d33972 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc @@ -0,0 +1,17 @@ +// +// ============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) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexCleanUpTemplate.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc new file mode 100644 index 000000000..dad270110 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc @@ -0,0 +1,17 @@ +// +// ============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) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexFormatterProfile.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-config/introduction.adoc b/src/site-docs/adoc/fragments/howto-config/introduction.adoc new file mode 100644 index 000000000..3f0265796 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-config/introduction.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) +// + +== Introduction to APEX Configuration + +An APEX engine can be configured to use various combinations of + event input handlers, + event output handlers, + event protocols, + context handlers, and + logic executors. +The system is build using a plugin architecture. +Each configuration option is realized by a plugin, which can be loaded and configured when the engine is started. +New plugins can be added to the system at any time, though to benefit from a new plugin an engine will need to be restarted. + +.APEX Configuration Matrix +image::apex-intro/ApexEngineConfig.png[APEX Configuration Matrix] + +The APEX distribution already comes with a number of plugins. +The figure above shows the provided plugins. +Any combination of input, output, event protocol, context handlers, and executors is possible. 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> +---- + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-00.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-00.adoc new file mode 100644 index 000000000..a9f72a80c --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-00.adoc @@ -0,0 +1,24 @@ +// +// ============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) +// + +== Demo with VPN Policy Model + +We assume that you have an APEX installation using the full package, i.e. APEX with all examples, of version `0.5.6` or higher. +We will use the VPN policy from the APEX examples here. + +Now, have the following ready to start the demo: + +- 3 terminals on the host where APEX is running (we need 1 for APEX and 1 for each client) +- the events in the file `$APEX_HOME/examples/events/VPN/SetupEvents.json` open in an editor (we need to send those events to APEX) +- the events in the file `$APEX_HOME/examples/events/VPN/Link09Events.json` open in an editor (we need to send those events to APEX) + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-01-vpn-wsconfig.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-01-vpn-wsconfig.adoc new file mode 100644 index 000000000..f1d4d7327 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-01-vpn-wsconfig.adoc @@ -0,0 +1,69 @@ +// +// ============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) +// + +=== A Websocket Configuration for the VPN Domain + +Create a new APEX configuration using the VPN policy model and configuring APEX as discussed above for Websockets. +Copy the following configuration into `$APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json` (for Windows use `%APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json`): + +[source%nowrap,json,numbered,subs="attributes+"] +---- +{ + "engineServiceParameters" : { + "name" : "VPNApexEngine", + "version" : "0.0.1", + "id" : 45, + "instanceCount" : 1, + "deploymentPort" : 12345, + "policyModelFileName" : "examples/models/VPN/VPNPolicyModelAvro.json", + "engineParameters" : { + "executorParameters" : { + "MVEL" : { + "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters" + } + }, + "contextParameters" : { + "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters", + "schemaParameters":{ + "Avro":{ + "parameterClassName" : "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters" + } + } + } + } + }, + "producerCarrierTechnologyParameters" : { + "carrierTechnology" : "WEBSOCKET", + "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters", + "parameters" : { + "wsClient" : false, + "port" : 42452 + } + }, + "producerEventProtocolParameters" : { + "eventProtocol" : "JSON" + }, + "consumerCarrierTechnologyParameters" : { + "carrierTechnology" : "WEBSOCKET", + "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters", + "parameters" : { + "wsClient" : false, + "port" : 42450 + } + }, + "consumerEventProtocolParameters" : { + "eventProtocol" : "JSON" + } +} +---- + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-02-start-engine.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-02-start-engine.adoc new file mode 100644 index 000000000..58d3e1fe8 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-02-start-engine.adoc @@ -0,0 +1,41 @@ +// +// ============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) +// + +=== Start APEX Engine + +In a new terminal, start APEX with the new configuration for Websocket-Server ingress/egress: + +[source%nowrap,sh,numbered] +---- +#: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json +---- + +[source%nowrap,bat,numbered] +---- +#: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json +---- + +Wait for APEX to start, it takes a while to create all Websocket servers (about 8 seconds on a standard laptop without cached binaries). +depending on your log messages, you will see no (some, a lot) log messages. +If APEX starts correctly, the last few messages you should see are: + +[source%nowrap,sh,numbered] +---- +2017-07-28 13:17:20,834 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model VPNPolicyModelAvro:0.0.1 added to the engine-AxArtifactKey:(name=VPNApexEngine-0,version=0.0.1) +2017-07-28 13:17:21,057 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=VPNApexEngine-0,version=0.0.1) processing ... +2017-07-28 13:17:21,296 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine +Started Apex service +---- + +APEX is running in the new terminal and will produce output when the policy is triggered/executed. + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-03-start-echo-client.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-03-start-echo-client.adoc new file mode 100644 index 000000000..473696d46 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-03-start-echo-client.adoc @@ -0,0 +1,15 @@ +// +// ============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) +// + +include::{adsite-tools-wsclients-dir}/site-docs/adoc/fragments/run-echo.adoc[leveloffset=+1] + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-04-start-console-client.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-04-start-console-client.adoc new file mode 100644 index 000000000..5a501e11b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-04-start-console-client.adoc @@ -0,0 +1,15 @@ +// +// ============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) +// + +include::{adsite-tools-wsclients-dir}/site-docs/adoc/fragments/run-console.adoc[leveloffset=+1] + diff --git a/src/site-docs/adoc/fragments/howto-websockets/demo-05-send-events.adoc b/src/site-docs/adoc/fragments/howto-websockets/demo-05-send-events.adoc new file mode 100644 index 000000000..3f5955869 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/demo-05-send-events.adoc @@ -0,0 +1,58 @@ +// +// ============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) +// + +=== Send Events + +Now you have the full system up and running: + +- Terminal 1: APEX ready and loaded +- Terminal 2: an echo client, printing received messages produced by the VPN policy +- Terminal 2: a console client, waiting for input on the console (standard in) and sending text to APEX + +We started the engine with the VPN policy example. +So all the events we are using now are located in files in the following example directory: + +[source%nowrap,sh,numbered] +---- +#: $APEX_HOME/examples/events/VPN +> %APEX_HOME%\examples\events\VPN +---- + +To sends events, simply copy the content of the event files into Terminal 3 (the console client). +It will read multi-line JSON text and send the events. +So copy the content of `SetupEvents.json` into the client. +APEX will trigger a policy and produce some output, the echo client will also print some events created in the policy. +In Terminal 1 (APEX) you’ll see some status messages from the policy as: + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/howto-websockets/wsc-screens/vpn-setup-events.log[APEX output for VPN Setup Events] +---- + +In Terminal 2 (echo-client) you see the received events, the last two should look like: + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/howto-websockets/wsc-screens/echo-client-received-events.log[Echo Client Received Events] +---- + +Congratulations, you have triggered a policy in APEX using Websockets, the policy did run through, created events, picked up by the echo-client. + +Now you can send the Link 09 and Link 10 events, they will trigger the actual VPN policy and some calculations are made. +Let’s take the Link 09 events from `Link09Events.json`, copy them all into Terminal 3 (the console). +APEX will run the policy (with some status output), and the echo client will receive and print events. + +To terminate the applications, simply press `CTRL+C` in Terminal 1 (APEX). +This will also terminate the echo-client in Terminal 2. +Then type `exit<enter>` in Terminal 3 (or `CTRL+C`) to terminate the console-client. + diff --git a/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/echo-client-received-events.log b/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/echo-client-received-events.log new file mode 100644 index 000000000..b3aeb43dd --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/echo-client-received-events.log @@ -0,0 +1,29 @@ +ws-simple-echo: received +--------------------------------- +{ + "name": "VPNCustomerCtxtActEvent", + "version": "0.0.1", + "nameSpace": "org.onap.policy.apex.domains.vpn.events", + "source": "Source", + "target": "Target", + "CustomerName": "C", + "LinkList": "L09 L10", + "SlaDT": 300, + "YtdDT": 300 +} +================================= + +ws-simple-echo: received +--------------------------------- +{ + "name": "VPNCustomerCtxtActEvent", + "version": "0.0.1", + "nameSpace": "org.onap.policy.apex.domains.vpn.events", + "source": "Source", + "target": "Target", + "CustomerName": "D", + "LinkList": "L09 L10", + "SlaDT": 300, + "YtdDT": 400 +} +================================= diff --git a/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/vpn-setup-events.log b/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/vpn-setup-events.log new file mode 100644 index 000000000..071d43532 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-websockets/wsc-screens/vpn-setup-events.log @@ -0,0 +1,29 @@ +{Link=L09, LinkUp=true} +L09 true +outFields: {Link=L09, LinkUp=true} +{Link=L10, LinkUp=true} +L09 true +L10 true +outFields: {Link=L10, LinkUp=true} +{CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300} +*** Customers *** +C 300 300 [L09, L10] +outFields: {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300} +{CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50} +*** Customers *** +A 300 50 [L09, L10] +C 300 300 [L09, L10] +outFields: {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50} +{CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400} +*** Customers *** +A 300 50 [L09, L10] +C 300 300 [L09, L10] +D 300 400 [L09, L10] +outFields: {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400} +{CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299} +*** Customers *** +A 300 50 [L09, L10] +B 300 299 [L09, L10] +C 300 300 [L09, L10] +D 300 400 [L09, L10] +outFields: {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-write-logic/logic-cheatsheet.adoc b/src/site-docs/adoc/fragments/howto-write-logic/logic-cheatsheet.adoc new file mode 100644 index 000000000..fe3cd0d0d --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-write-logic/logic-cheatsheet.adoc @@ -0,0 +1,269 @@ +// +// ============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) +// + +== Logic Cheatsheet + +Examples given here use Javascript (if not stated otherwise), other execution environments will be similar. + + +=== Add Nashorn + +First line in the logic use this import. + +.JS Nashorn +[source,javascript,options="nowrap"] +---- +load("nashorn:mozilla_compat.js"); +---- + + +=== Finish Logic with Success or Error + +To finish logic, i.e. return to APEX, with success use the following lines close to the end of the logic. + +.JS Success +[source,javascript,options="nowrap"] +---- +var returnValueType = Java.type("java.lang.Boolean"); +var returnValue = new returnValueType(true); +---- + +To notify a problem, finish with an error. + +.JS Fail +[source,javascript,options="nowrap"] +---- +var returnValueType = Java.type("java.lang.Boolean"); +var returnValue = new returnValueType(false); +---- + + +=== Logic Logging + +Logging can be made easy using a local variable for the logger. +Line 1 below does that. +Then we start with a trace log with the task (or task logic) identifier followed by the infields. + +.JS Logging +[source,javascript,options="nowrap"] +---- +var logger = executor.logger; +logger.trace("start: " + executor.subject.id); +logger.trace("-- infields: " + executor.inFields); +---- + +For larger logging blocks you can use the standard logging API to detect log levels, for instance: + +.JS Logging Blocks +[source,javascript,options="nowrap"] +---- +if(logger.isTraceEnabled()){ + // trace logging block here +} +---- + +Note: the shown logger here logs to `org.onap.policy.apex.executionlogging`. +The behavior of the actual logging can be specified in the `$APEX_HOME/etc/logback.xml`. + +If you want to log into the APEX root logger (which is sometimes necessary to report serious logic errors to the top), +then import the required class and use this logger. + +.JS Root Logger +[source,javascript,options="nowrap"] +---- +importClass(org.slf4j.LoggerFactory); +var rootLogger = LoggerFactory.getLogger(logger.ROOT_LOGGER_NAME); + +rootLogger.error("Serious error in logic detected: " + executor.subject.id); +---- + +=== Local Variable for Infields + +It is a good idea to use local variables for `infields`. +This avoids long code lines and policy evolution. +The following example assumes infields named `nodeName` and `nodeAlias`. + +.JS Infields Local Var +[source,javascript,options="nowrap"] +---- +var ifNodeName = executor.inFields["nodeName"]; +var ifNodeAlias = executor.inFields["nodeAlias"]; +---- + + +=== Local Variable for Context Albums + +Similar to the `infields` it is good practice to use local variables for context albums as well. +The following example assumes that a task can access a context album `albumTopoNodes`. +The second line gets a particular node from this context album. + +.JS Infields Local Var +[source,javascript,options="nowrap"] +---- +var albumTopoNodes = executor.getContextAlbum("albumTopoNodes"); +var ctxtNode = albumTopoNodes.get(ifNodeName); +---- + + +=== Set Outfields in Logic + +The task logic needs to set outfields with content generated. +The exception are outfields that are a direct copy from an infield of the same name, APEX does that autmatically. + +.JS Set Outfields +[source,javascript,options="nowrap"] +---- +executor.outFields["report"] = "node ctxt :: added node " + ifNodeName; +---- + + +=== Create a instance of an Outfield using Schemas + +If an outfield is not an atomic type (string, integer, etc.) but uses a complex schema (with a Java or Avro backend), APEX can help to create new instances. +The `executor` provides a field called `subject`, which provides a schem helper with an API for this. +The complete API of the schema helper is documented here: link:https://ericsson.github.io/apex-docs/javadocs/index.html[API Doc: SchemaHelper]. + +If the backend is Avro, then an import of the Avro schema library is required: + +.JS Import Avro +[source,javascript,options="nowrap"] +---- +importClass(org.apache.avro.generic.GenericData.Array); +importClass(org.apache.avro.generic.GenericRecord); +importClass(org.apache.avro.Schema); +---- + +If the backend is Java, then the Java class implementing the schema needs to be imported. + +The following example assumes an outfield `situation`. +The `subject` method `getOutFieldSchemaHelper()` is used to create a new instance. + +.JS Outfield Instance with Schema +[source,javascript,options="nowrap"] +---- +var situation = executor.subject.getOutFieldSchemaHelper("situation").createNewInstance(); +---- + +If the schema backend is Java, the new instance will be as implemented in the Java class. +If the schema backend is Avro, the new instance will have all fields from the Avro schema specification, but set to `null`. +So any entry here needs to be done separately. +For instance, the `situation` schema has a field `problemID` which we set. + +.JS Outfield Instance with Schema, set +[source,javascript,options="nowrap"] +---- +situation.put("problemID", "my-problem"); +---- + + +=== Create a instance of an Context Album entry using Schemas + +Context album instances can be created using very similar to the outfields. +Here, the schema helper comes from the context album directly. +The API of the schema helper is the same as for outfields, see link:https://ericsson.github.io/apex-docs/javadocs/index.html[API Doc: SchemaHelper]. + +If the backend is Avro, then an import of the Avro schema library is required: + +.JS Import Avro +[source,javascript,options="nowrap"] +---- +importClass(org.apache.avro.generic.GenericData.Array); +importClass(org.apache.avro.generic.GenericRecord); +importClass(org.apache.avro.Schema); +---- + +If the backend is Java, then the Java class implementing the schema needs to be imported. + +The following example creates a new instance of a context album instance named `albumProblemMap`. + +.JS Outfield Instance with Schema +[source,javascript,options="nowrap"] +---- +var albumProblemMap = executor.getContextAlbum("albumProblemMap"); +var linkProblem = albumProblemMap.getSchemaHelper().createNewInstance(); +---- + +This can of course be also done in a single call without the local variable for the context album. + +.JS Outfield Instance with Schema, one line +[source,javascript,options="nowrap"] +---- +var linkProblem = executor.getContextAlbum("albumProblemMap").getSchemaHelper().createNewInstance(); +---- + +If the schema backend is Java, the new instance will be as implemented in the Java class. +If the schema backend is Avro, the new instance will have all fields from the Avro schema specification, but set to `null`. +So any entry here needs to be done separately (see above in outfields for an example). + + +=== Enumerates + +When dealing with enumerates (Avro or Java defined), it is sometimes and in some execution environments necessary to convert them to a string. +For example, assume an Avro enumerate schema as: + +.Avro Enumerate Schema +[source,json,options="nowrap"] +---- +{ + "type": "enum", + "name": "Status", + "symbols" : [ + "UP", + "DOWN" + ] +} + +---- + +Using a switch over a field initialized with this enumerate in Javascript will fail. +Instead, use the `toString` method, for example: + +.JS Outfield Instance with Schema, one line +[source,javascript,options="nowrap"] +---- +var switchTest = executor.inFields["status"]; +switch(switchTest.toString()){ + case "UP": ...; break; + case "DOWN": ...; break; + default: ...; +} +---- + + +=== MVEL Initialize Outfields First! + +In MVEL, we observed a problem when accessing (setting) outfields without a prior access to them. +So in any MVEL task logic, before setting any outfield, simply do a get (with any string), to load the outfields into the MVEL cache. + +.MVEL Outfield Initialization +[source,java,options="nowrap"] +---- +outFields.get("initialize outfields"); +---- + + +=== Using Java in Scripting Logic + +Since APEX executes the logic inside a JVM, most scripting languages provide access to all standard Java classes. +Simply add an import for the required class and then use it as in actual Java. + +The following example imports `java.util.arraylist` into a Javascript logic, and then creates a new list. + +.JS Import ArrayList +[source,javascript,options="nowrap"] +---- +importClass(java.util.ArrayList); +var myList = new ArrayList(); +---- + + diff --git a/src/site-docs/adoc/fragments/howto-write-logic/policy-examples.adoc b/src/site-docs/adoc/fragments/howto-write-logic/policy-examples.adoc new file mode 100644 index 000000000..77769dc31 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-write-logic/policy-examples.adoc @@ -0,0 +1,44 @@ +// +// ============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) +// + +== My First Policy + +A good starting point is the `My First Policy` example. +It describes a sales problem, to which policy can be applied. +The example details the policy background, shows how to use the REST Editor to create a policy, and provides details for running the policies. +The documentation can be found: + +* link:https://ericsson.github.io/apex-docs/modules/apex-domains/apex-domains.myfirstpolicy/MyFirstPolicyHowto.html[My-First-Policy on the APEX site] +* link:https://ericsson.github.io/apex-docs/docs-apex/html/HowTo-MyFirstPolicy.html[Stand-alone HTML] +* link:https://ericsson.github.io/apex-docs/docs-apex/pdf/HowTo-MyFirstPolicy.pdf[Stand-alone PDF] + + +== VPN SLA + +The domain Policy-controlled Video Streaming (PCVS) contains a policy for controlling video streams with different strategies. +It also provides details for installing an actual testbed with off-the-shelve software (Mininet, Floodlight, Kafka, Zookeeper). +The policy model here demonstrates virtually all APEX features: local context and policies controlling it, task selection logic and multiple tasks in a single state, AVRO schemas for context, AVOR schemas for events (trigger and local), and a CLI editor specification of the policy. +The documentation can be found: + +* link:https://ericsson.github.io/apex-docs/modules/apex-domains/apex-domains.pcvs/vpnsla/policy.html[VPN SLA Policy on the APEX site] + + +== Decision Maker + +The domain Decision Maker shows a very simple policy for decisions. +Interesting here is that the it creates a Docker image to run the policy and that it uses the APEX REST applications to update the policy on the-fly. +It also has local context to remember past decisions, and shows how to use that to no make the same decision twice in a row. +The documentation can be found: + +* link:https://ericsson.github.io/apex-docs/modules/apex-domains/apex-domains.decisionmaker/index.html[Decision Maker on APEX site] + 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); +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/howto-write-logic/task-selection-logic.adoc b/src/site-docs/adoc/fragments/howto-write-logic/task-selection-logic.adoc new file mode 100644 index 000000000..9225ac310 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-write-logic/task-selection-logic.adoc @@ -0,0 +1,165 @@ +// +// ============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 Selection Logic + +The function of Task Selection Logic is to choose which task should be executed for an Apex State as one of the steps in an Apex Policy. +Since each state must define a default task there is no need for Task Selection Logic unless the state uses more than one 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 Selection 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 Selection 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 Selection Logic types but these are not supported as yet. +This guide will focus on the scripted Task Selection 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 does Task Selection Logic do? +==== +When an Apex state references multiple tasks, there must be a way to dynamically decide which task should be chosen and executed. This can depend on the many factors, e.g. the _incoming event for the state_, _shared state_ or _context_, _external context_, etc.. This is the function of a state's Task Selection Logic. Obviously, if there is only one task then Task Selection Logic is not needed. Each state must also select one of the tasks a the _default state_. If the Task Selection Logic is unable to select an appropriate task, then it should select the _default task_. Once the task has been selected the Apex Engine will then execute that task. +==== + +First lets start with some simple Task Selection Logic, drawn from the "My First Apex Policy" example: +The Task Selection Logic from the "My First Apex Policy" example is specified in JavaScript here: + +.Javascript code for the "My First Policy" Task Selection Logic +[source,javascript,options="nowrap"] +---- +include::{adsite-examples-myfirstpolicy-dir}/main/resources/examples/models/MyFirstPolicy/2/MyFirstPolicy_BoozeAuthDecideTSL.js[] +---- + +The role of the Task Selection Logic in this simple example is to examine the value in one incoming field (`branchid`), then depending on that field's value set the value for the selected task to the appropriate task (`MorningBoozeCheck`, `MorningBoozeCheckAlt1`, or the default task). + +Another thing to notice is that Task Selection 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 Selection 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 not 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). +==== + +Each of the scripting languages used in Apex can import and use standard Java libraries to perform complex tasks. Besides 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> | +All fields in the state's incoming event. This is implemented as a standard Java (unmodifiable) Map. + +2+| 2+<a| +*Example:* +[source,javascript,numbered,options="nowrap"] +---- +executor.logger.info("Input Event: " + +executor.inFields); + +var branchid = executor.inFields.get("branch_ID"); + +if(branchid >=0 && branchid <1000){ ... } +---- + +|selectedTask | ID/key | AxArtifactKey | +The writeable field is used to store the result of the task selection logic. The task selection logic should copy the ID of one of the available tasks into this field. Note: ID/key objects have a helpful `copyTo` functions to assist copying IDs. + +2+| 2+<a| +*Example:* +[source,javascript,numbered,options="nowrap"] +---- +taskorig = executor.subject.getTaskKey("MorningBoozeCheck"); +if(branchid >=0 && branchid <1000){ + taskorig.copyTo(executor.selectedTask); +} +---- + +|logger | Logger | org.slf4j.ext.XLogger | A helpful logger + +2+| 2+<a| +*Example:* +[source,javascript,numbered,options="nowrap"] +---- +executor.logger.info("Executing TSL: " + +executor.subject.id); +---- + +|TRUE/FALSE | boolean | java.lang.Boolean | 2 helpful constants. These are useful to retrieve correct return values for the task selection 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 | State | StateFacade | + +This provides some useful information about the state that hosts this task selection logic. This object has some useful fields and methods : + +[options="compact"] +- *_AxState state_* to get access to the full state definition of the host state +- *_String getStateName()_* to get the name of the host task +- *_String getId()_* to get the ID of the host state +- *_List<String> getTaskNames()_* to get the names of tasks available for selection +- *_AxArtifactKey getTaskKey( String taskName )_* to get the ID of a named task for this state +- *_AxArtifactKey getDefaultTaskKey()_* to get the ID of the default task for this state. As described above, all states must define a default task + +2+| 2+<a| +*Example:* +[source,javascript,numbered,options="nowrap"] +---- +executor.logger.info("State name: " + +executor.subject.getStateName()); +executor.logger.info("State id: " + +executor.subject.getId()); +executor.logger.info("State input event : " + +executor.subject.state.getTrigger()); +executor.logger.info("Available tasks : " + +executor.subject.getTaskNames()); +taskdef = executor.subject.getDefaultTaskKey(); +taskorig = executor.subject.getTaskKey("MorningBoozeCheck"); +---- + +3+l|ContextAlbum getContextAlbum( + String ctxtAlbumName ) | +A utility method to retrieve a `ContextAlbum` for use in the task selection logic. This is how you access the context used in task selection. 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 task selection logic is described in the Apex Programmer's Guide and in the My First Apex Policy guide + +2+| 2+<a| +*Example:* +[source,javascript,numbered,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); +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/install-guide/build-apex.adoc b/src/site-docs/adoc/fragments/install-guide/build-apex.adoc new file mode 100644 index 000000000..b773d97bd --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/build-apex.adoc @@ -0,0 +1,112 @@ +// +// ============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) +// + +== Build APEX + +The examples in this document assume that the APEX source repositories are cloned to: + +- Unix, Cygwin: `/usr/local/src/apex` +- Windows: `C:\dev\apex` +- Cygwin: `/cygdrive/c/dev/apex` + +[IMPORTANT] +.A Build needs Space +==== +Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for the downloaded dependencies +==== + +[IMPORTANT] +.A Build requires Internet (for first build) +==== +During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven repository. +The first standard build (and any first specific build) requires Internet access to download those dependencies. +==== + +[IMPORTANT] +.Building RPM distributions +==== +RPM images are only build if the `rpm` package is installed (Unix). +To install `rpm` run `sudo apt-get install rpm`, then build APEX. +==== + +Use Maven to for a standard build without any tests. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +The build takes 2-3 minutes on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +The build will have created all artifacts required for an APEX installation. +The following example show how to change to the target directory and how it should look like. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + +|==================== + diff --git a/src/site-docs/adoc/fragments/install-guide/configure.adoc b/src/site-docs/adoc/fragments/install-guide/configure.adoc new file mode 100644 index 000000000..77c63a29a --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/configure.adoc @@ -0,0 +1,160 @@ +// +// ============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) +// + +== System Configuration +Once APEX is installed, a few configurations need to be done: + +- Create an APEX user and an APEX group (optional, if not installed using RPM and DPKG) +- Create environment settings for `APEX_HOME` and `APEX_USER`, required by the start scripts +- Change settings of the logging framework (optional) +- Create directories for logging, required (execution might fail if directories do not exist or cannot be created) + +=== APEX User and Group +On smaller installations and test systems, APEX can run as any user or group. + +However, if APEX is installed in production, we strongly recommend you set up a dedicated user for running APEX. +This will isolate the execution of APEX to that user. +We recommend you use the userid `apexuser` but you may use any user you choose. + +The following example, for UNIX, creates a group called `apexuser`, an APEX user called `apexuser`, adds the group to the user, and changes ownership of the APEX installation to the user. +Substitute `<apex-dir>` with the directory where APEX is installed. + +[source%nowrap,sh,numbered] +---- +# sudo groupadd apexuser +# sudo useradd -g apexuser apexuser +# sudo chwon -R apexuser:apexuser <apex-dir> +---- + +For other operating systems please consult your manual or system administrator. + + +=== Environment Settings: APEX_HOME and APEX_USER +The provided start scripts for APEX require two environment variables being set: + +- `APEX_USER` with the user under whos name and permission APEX should be started (Unix only) +- `APEX_HOME` with the directory where APEX is installed (Unix, Windows, Cygwin) + +The first row in the following table shows how to set these environment variables temporary (assuming the user is `apexuser`). +The second row shows how to verify the settings. +The last row explains how to set those variables permanently. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin (bash/tcsh) | Windows +| +[source%nowrap,bash,numbered] +---- +# export APEX_USER=apexuser +# cd /opt/ericsson/apex/apex +# export APEX_HOME=`pwd` +---- + +[source%nowrap,tcsh,numbered] +---- +# setenv APEX_USER apexuser +# cd /opt/ericsson/apex/apex +# setenv APEX_HOME `pwd` +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>set APEX_HOME=C:\apex\apex-full-{release-version} +---- + +| +[source%nowrap,sh,numbered] +---- +# env \| grep APEX +APEX_USER=apexuser +APEX_HOME=/opt/ericsson/apex/apex +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>set APEX_HOME +APEX_HOME=\apex\apex-full-{release-version} +---- + +|==================== + + +==== Making Environment Settings Permanent (Unix, Cygwin) +For a per-user setting, edit the a user's `bash` or `tcsh` settings in `~/.bashrc` or `~/.tcshrc`. +For system-wide settings, edit `/etc/profiles` (requires permissions). + + +==== Making Environment Settings Permanent (Windows) +On Windows 7 do + +- Click on the *Start* Menu +- Right click on *Computer* +- Select *Properties* + +On Windows 8/10 do + +- Click on the *Start* Menu +- Select *System* + +Then do the following + +- Select *Advanced System Settings* +- On the *Advanced* tab, click the *Environment Variables* button +- Edit an existing variable, or create a new System variable: 'Variable name'="APEX_HOME", 'Variable value'="C:\apex\apex-full-{release-version}" + +For the settings to take effect, an application needs to be restarted (e.g. any open `cmd` window). + + + +=== Edit the APEX Logging Settings +Configure the APEX logging settings to your requirements, for instance: + +- change the directory where logs are written to, or +- change the log levels + +Edit the file `$APEX_HOME/etc/logback.xml` for any required changes. +To change the log directory change the line + +`<property name="VAR_LOG" value="/var/log/ericsson/apex/" />` + +to + +`<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />` + +On Windows, it is recommended to change the log directory to: + +`<property name="VAR_LOG" value="C:/apex/apex-full-{release-version}/logs" />` + +Note: Be careful about when to use `\` vs. `/` as the path separator! + + +=== Create Directories for Logging +Make sure that the log directory exists. +This is important when APEX was installed manually or when the log directory was changed in the settings (see above). + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +mkdir -p /var/log/ericsson/apex +chown -R apexuser:apexuser /var/log/ericsson/apex +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>mkdir C:\apex\apex-full-{release-version}\logs +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/install-guide/docker.adoc b/src/site-docs/adoc/fragments/install-guide/docker.adoc new file mode 100644 index 000000000..be5273a48 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/docker.adoc @@ -0,0 +1,260 @@ +// +// ============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) +// + +== Running APEX in Docker + +This section explains how to create a Docker image that contains the base APEX package and shows how to run APEX in Docker. +It also explains how to use the base APEX Docker image to create application docker images that contain both APEX and your application policies. + +We assume you have already installed Docker on your host. +For instructions on how to install Docker, see the link:https://www.docker.com/community-edition[Get Started with Docker] page on the Docker web site. + + +=== Create the APEX Base Docker Image + +You need only perform this task once to create an APEX base image that you can use as a base for your applications from then on. +This task sets up an Ubuntu Docker image and then installs Java and APEX on Ubuntu running in the Docker image. + +. Create an empty directory, here the directory is called `apex`, and change into that directory ++ +[source%nowrap,bash,numbered] +---- +# mkdir apex +# cd apex +---- ++ +. Copy the APEX Debian package from the APEX download site into the directory +. Open a text editor and create a file called `Dockerfile` in your directory +. Paste the following text into the editor that is editing `Dockerfile` ++ +[source%nowrap,bash,numbered,subs="attributes+"] +---- +# +# Docker file to build an image that runs APEX on Java 8 in Ubuntu +# +FROM ubuntu:16.04 +MAINTAINER <YOUR> <NAME> <YOUR>.<NAME>@ericsson.com + +RUN apt-get update && \ + apt-get upgrade -y && \ + apt-get install -y software-properties-common && \ + add-apt-repository ppa:webupd8team/java -y && \ + apt-get update && \ + echo oracle-javax8-installer shared/accepted-oracle-license-v1-1 select true | /usr/bin/debconf-set-selections && \ + apt-get install -y oracle-java8-installer + +RUN mkdir /packages +COPY apex-apps.uservice-packages-{release-version}-full.deb /packages +RUN dpkg -i packages/apex-apps.uservice-packages-{release-version}-full.deb +RUN rm /packages/apex-apps.uservice-packages-{release-version}-full.deb + +ENV PATH /opt/ericsson/apex/apex/bin:$PATH + +RUN apt-get clean + +RUN chown -R apexuser:apexuser /home/apexuser/* +WORKDIR /home/apexuser + +---- ++ +. Replace the fields <YOUR> and <NAME> above with your name and email address +. Save the `Dockerfile` +. An example working base `Dockerfile` appears below ++ +[source%nowrap,bash,numbered,subs="attributes+"] +---- +# +# Docker file to build an image that runs APEX on Java 8 in Ubuntu +# +FROM ubuntu:16.04 +MAINTAINER Sean Citizen sean.citizen@ericsson.com + +RUN apt-get update && \ + apt-get upgrade -y && \ + apt-get install -y software-properties-common && \ + add-apt-repository ppa:webupd8team/java -y && \ + apt-get update && \ + echo oracle-javax8-installer shared/accepted-oracle-license-v1-1 select true | /usr/bin/debconf-set-selections && \ + apt-get install -y oracle-java8-installer + +RUN mkdir /packages +COPY apex-apps.uservice-packages-{release-version}-full.deb /packages +RUN dpkg -i packages/apex-apps.uservice-packages-{release-version}-full.deb +RUN rm /packages/apex-apps.uservice-packages-{release-version}-full.deb + +ENV PATH /opt/ericsson/apex/apex/bin:$PATH + +RUN apt-get clean + +RUN chown -R apexuser:apexuser /home/apexuser/* +WORKDIR /home/apexuser +---- ++ +. Create and tag the base Docker image for APEX using this command ++ +[source%nowrap,bash,numbered] +---- +docker build -t apex/base . +docker tag apex/base apex/base:latest +docker tag apex/base apex/base:{release-version} +---- ++ +. Test the APEX Docker base image with the following command, APEX will start a sample policy: ++ +[source%nowrap,bash,numbered] +---- +docker run --name apex --user=apexuser:apexuser -it --rm -p 12345:12345 apex/base apexEngine.sh -c examples/config/SampleDomain/Stdin2StdoutJsonEventJavascript.json +---- ++ +. Paste the following event into the shell and the APEX Policy will process the event ++ +[source%nowrap,json,numbered] +---- +{ + "nameSpace": "org.onap.policy.apex.sample.events", + "name": "Event0000", + "version": "0.0.1", + "source": "test", + "target": "apex", + "TestSlogan": "Test slogan for External Event0", + "TestMatchCase": 0, + "TestTimestamp": 1469781869269, + "TestTemperature": 9080.866 +} +---- ++ +. APEX returns the following event ++ +[source%nowrap,json,numbered] +---- +{ + "nameSpace" : "org.onap.policy.apex..sample.events", + "name" : "Event0004", + "version" : "0.0.1", + "source" : "", + "target" : "", + "TestActCaseSelected" : 3, + "TestActStateTime" : 1481215910429, + "TestTemperature" : 9080.866, + "TestDecideCaseSelected" : 1, + "TestMatchCaseSelected" : 2, + "TestTimestamp" : 1469781869269, + "TestDecideStateTime" : 1481215910425, + "TestMatchCase" : 0, + "TestSlogan" : "Test slogan for External Event0", + "TestEstablishCaseSelected" : 0, + "TestEstablishStateTime" : 1481215910421, + "TestMatchStateTime" : 1481215910415 +} +---- ++ +. You now have built and tested an APEX base Docker image. + You can connect the APEX Deployment and Monitoring servlet to this APEX engine instance. For example, assuming the APEX Deployment and Monitoring servlet is deploying on the localhost computer on port 8080 you can use the following URL: ++ +---- +http://localhost:8080/apex-services.client-{release-version}/?hostname=0.0.0.0&port=12345 +---- + +=== Create an APEX Application Docker Image using the APEX Base Docker Image + +We assume you have created an APEX application, that you wish to use static deployment, and that you have APEX metadata to add to the base APEX Docker image. + +. 1.Create an empty directory for your application, here the directory is called `myApplication`, and change into that directory ++ +[source%nowrap,bash,numbered] +---- +mkdir myApplication +cd myApplication +---- ++ +. Copy the directories containing your application metadata into that directory, for example, if you have three directories called `myappDirectory0`, `myappDirectory1`, and `myappDirectoryn`, you will have the following directory structure ++ +[source%nowrap,bash,numbered] +---- +ls | cat +myappDirectory0 +myappDirectory1 +myappDirectoryn +---- ++ +. Open a text editor and create a file called `Dockerfile` in your application directory +. Paste the following text into the editor that is editing `Dockerfile` ++ +[source%nowrap,bash,numbered] +---- +# +# Docker file to build an image that runs APEX Applications on Java 8 in Ubuntu +# +FROM apex/base:{release-version} +MAINTAINER <YOUR> <NAME> <YOUR>.<NAME>@ericsson.com + +# Copy your application metadata +COPY <MY_APP_DIRECTORY_0> /home/apexuser/<MY_APP_DIRECTORY_0> +COPY <MY_APP_DIRECTORY_1> /home/apexuser/<MY_APP_DIRECTORY_1> +COPY <MY_APP_DIRECTORY_N> /home/apexuser/<MY_APP_DIRECTORY_N> + +run chown -R apexuser:apexuser /home/apexuser/* +---- ++ +. Edit the template fields + .. Replace the fields <YOUR> and <NAME> with your name and email address + .. Replace the <MY_APP_DIRECTORY_x> fields with the names of your actual application directory names, myappDirectoryx in our example here. Do this for all application directories you have. +. Save the `Dockerfile` +. An example working application `Dockerfile` appears below ++ +[source%nowrap,bash,numbered] +---- +# +# Docker file to build an image that runs APEX Applications on Java 8 in Ubuntu +# +FROM apex/base:{release-version} +MAINTAINER Sean Citizen sean.citizen@ericsson.com + +# Copy your application metadata +COPY myappDirectory0 /home/apexuser/myappDirectory0 +COPY myappDirectory1 /home/apexuser/myappDirectory1 +COPY myappDirectoryn /home/apexuser/myappDirectoryn + +run chown -R apexuser:apexuser /home/apexuser/* +---- ++ +. Create the Docker image for your APEX application using this command ++ +[source%nowrap,bash,numbered] +---- +docker build -t apex/myapplication . +---- ++ +. Test the APEX Docker base image with the following command, APEX will start to a bash shell in the `apexuser` home directory: ++ +[source%nowrap,bash,numbered] +---- +docker run --name myapplication -it --rm -p 12345:12345 apex/myapplication apexBash.sh +---- ++ +. Check that your application directories have been created, the command returns the directory list: ++ +[source%nowrap,bash,numbered] +---- +> pwd +/opt/ericsson +> ls -l +total 16 +drwxr-xr-x 8 apexuser apexuser 4096 Dec 9 13:28 examples +drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectory0 +drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectory1 +drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectoryn +---- ++ +. You now have built an APEX Application docker image and you can use the `apexEngine.sh` command to run your application using the appropriate configuration file for your application. + diff --git a/src/site-docs/adoc/fragments/install-guide/get-source.adoc b/src/site-docs/adoc/fragments/install-guide/get-source.adoc new file mode 100644 index 000000000..11786da4e --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/get-source.adoc @@ -0,0 +1,27 @@ +// +// ============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) +// + +== Get the APEX Source Code +The APEX source code is hosted in as project on Github link:https://github.com/Ericsson/apex[Ericsson:apex]. +The current stable version is in the master branch. +Simply clone the master branch from Github using either HTTPS (first example below) or SSH (second example below). + +[source%nowrap,sh,numbered] +---- +git clone https://github.com/Ericsson/apex.git +---- + +[source%nowrap,sh,numbered] +---- +git clone git@github.com:Ericsson/apex.git +---- diff --git a/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc b/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc new file mode 100644 index 000000000..a8bf3d4f1 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc @@ -0,0 +1,99 @@ +// +// ============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) +// + +== Installing the Web Monitoring Application + +APEX comes with a deployment and monitoring application realized as a servlet. +This requires a _full_ installation of APEX. +This requires a web server that can execute `war` web archives. +We recommend to use link:https://tomcat.apache.org/[Apache Tomcat], however other web servers can be used as well. + +Install Apache Tomcat including the `Manager App`, see link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access[V9.0 Docs] for details. +Start the Tomcat service, or make sure that Tomcat is running. +Locate the APEX monitoring application. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +$APEX_HOME/war/apex-services.client.monitoring-{release-version}.war +---- + +[source%nowrap,bat,numbered,subs="attributes+"] +---- +%APEX_HOME%\war\apex-services.client.monitoring-{release-version}.war +---- + +There are multiple ways to install the APEX monitoring application: + +- copy the `.war` file into the Tomcat `webapps` folder +- use the Tomcat `Manager App` to deploy via the web interface +- deploy using a REST call to Tomcat + +For details on how to install `war` files please consult the link:https://tomcat.apache.org/tomcat-9.0-doc/index.html[Tomcat Documentation] or the link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html[Manager App HOW-TO]. +Once you installed the APEX monitoring application (and wait for sufficient time for Tomcat to finalize the installation), open the `Manager App` in Tomcat. +You should see the APEX monitoring application being installed and running. + +image::install-guide/tomcat-installed.png[Tomcat Application Manager with APEX Monitoring Application] + +In case of errors, examine the log files in the Tomcat log directory. +In a conventional install, those log files are in the logs directory where Tomcat is installed. + +Once the APEX monitoring application is installed, start an APEX engine with the `SampleDomain` configuration as described above. +Wait until the engine is fully started. +Then open a browser (or a new tab) and use the following URL to connect to the APEX monitoring application. +Change the values for the Tomcat port (`10080` in the example), the APEX application version (`{release-version}` in the example), and the APEX management port (`12345` in the example, taken from the example configuration) to your local settings. +If your browser is not opened on the same host as the APEX engine runs, change `localhost` to the host name with the APEX engine. + +[source%nowrap,url,subs="attributes+"] +---- +http://localhost:10080/apex-services.client-{release-version}/?hostname=localhost&port=12345 +---- + +The browser will now show the APEX monitoring application. + +image::install-guide/monitoring-app.png[APEX Monitoring and Deployment Application] + +Now send some events to the APEX engine. +The configuration is for standard input, so simply paste the following event into the APEX engine console. + +[source%nowrap,json,numbered] +---- +{ + "nameSpace": "org.onap.policy.apex.sample.events", + "name": "Event0000", + "version": "0.0.1", + "source": "test", + "target": "apex", + "TestSlogan": "Test slogan for External Event0", + "TestMatchCase": 0, + "TestTimestamp": 1469781869269, + "TestTemperature": 9080.866 +} +---- + +When events are sent to APEX, the monitoring application will show all engine status changes. +The following screen shot show the engine status after passing several events into the engine. + +image::install-guide/monitoring-app-status.png[APEX Monitoring: status] + +To terminate this setting, first use `CTRL+C` in the engine console to terminate the engine. +Within a few seconds, the APEX monitoring application will terminate as well with a connection error: + +---- +Error connecting to Apex Engine Service at localhost:12345 +cound not handshake with server localhost:12345 +See detailed message in log +---- + +Terminate the browser now (or the tab with the application). +Finally, if you do not want to use Tomcat for any other applications, terminate the Tomcat server as well. + diff --git a/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc b/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc new file mode 100644 index 000000000..721ede0a9 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc @@ -0,0 +1,60 @@ +// +// ============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) +// + +== Installing the REST Editor + +APEX comes with a RESR Editor application realized as a servlett. +This requires a _full_ installation of APEX. +This requires a web server that can execute `war` web archives. +We recommend to use link:https://tomcat.apache.org/[Apache Tomcat], however other web servers can be used as well. + +Install Apache Tomcat including the `Manager App`, see link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access[V9.0 Docs] for details. +Start the Tomcat service, or make sure that Tomcat is running. +Locate the APEX monitoring application in your local APEX installation. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +$APEX_HOME/war/apex-services.client-editor-{release-version}.war +---- + +[source%nowrap,bat,numbered,subs="attributes+"] +---- +%APEX_HOME%\war\apex-services.client-editor-{release-version}.war +---- + +There are multiple ways to install the APEX monitoring application: + +- copy the `.war` file into the Tomcat `webapps` folder +- use the Tomcat `Manager App` to deploy via the web interface +- deploy using a REST call to Tomcat + +For details on how to install `war` files please consult the link:https://tomcat.apache.org/tomcat-9.0-doc/index.html[Tomcat Documentation] or the link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html[Manager App HOW-TO]. +Once you installed the APEX monitoring application (and wait for sufficient time for Tomcat to finalize the installation), open the `Manager App` in Tomcat. +You should see the APEX REST Editor application being installed and running. + +In case of errors, examine the log files in the Tomcat log directory. +In a conventional install, those log files are in the logs directory where Tomcat is installed. + +Once the APEX REST Editor is installed, open a browser (or a new tab) and use the following URL to connect to the APEX monitoring application. +Change the values for the Tomcat port (`10080` in the example), the APEX REST EDITOR version (`{release-version}` in the example), and the APEX management port (`12345` in the example, taken from the example configuration) to your local settings. +If your browser is not opened on the same host as the APEX engine runs, change `localhost` to the host name with the APEX engine. + +[source%nowrap,url,subs="attributes+"] +---- +http://localhost:10080/apex%2Dauth.rest%2D{release-version}/ +---- + +The browser will now show the APEX REST Editor. + +Terminate the browser now (or the tab with the application). +Finally, if you do not want to use Tomcat for any other applications, terminate the Tomcat server as well. diff --git a/src/site-docs/adoc/fragments/install-guide/install.adoc b/src/site-docs/adoc/fragments/install-guide/install.adoc new file mode 100644 index 000000000..a1e95347a --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install.adoc @@ -0,0 +1,226 @@ +// +// ============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) +// + +== Install APEX +APEX can be installed in different ways: + +- Unix: automatically using `rpm` or `dpkg` from `.rpm` or `.deb` archive +- Windows, Unix, Cygwin: manually from a `.tar.gz` archive +- Windows, Unix, Cygwin: build from source using Maven, then install manually + + +=== Install with RPM and DPKG +The install distributions of APEX automatically install the system. +The installation directory is `/opt/ericsson/apex`. +Log files are located in `/var/log/ericsson/apex`. +The latest APEX version will be available as `/opt/ericsson/apex/apex`. + +For the installation, a new user `apexuser` and a new group `apexuser` will be created. +This user owns the installation directories and the log file location. +The user is also used by the standard APEX start scripts to run APEX with this user's permissions. + +[width="100%",options="header",cols="a"] +|==================== +| RPM Installation +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# sudo rpm -i apex-apps.uservice-packages-{release-version}-full.rpm +********************preinst******************* +arguments 1 +********************************************** +creating group apexuser . . . +creating user apexuser . . . +********************postinst**************** +arguments 1 +*********************************************** +---- +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| DPKG Installation +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# sudo dpkg -i apex-apps.uservice-packages-{release-version}-full.deb +Selecting previously unselected package apex-uservice. +(Reading database ... 288458 files and directories currently installed.) +Preparing to unpack apex-apps.uservice-packages-{release-version}-full.deb ... +********************preinst******************* +arguments install +********************************************** +creating group apexuser . . . +creating user apexuser . . . +Unpacking apex-uservice ({release-version}) ... +Setting up apex-uservice ({release-version}) ... +********************postinst**************** +arguments configure +*********************************************** +---- +|==================== + +Once the installation is finished, APEX is fully installed and ready to run. + + +=== Install Manually from Archive (Unix, Cygwin) +Download a `tar.gz` archive. +Create a directory where APEX should be installed. +Extract the `tar` archive. +The following example shows how to install APEX in `/opt/apex` and create a link to `/opt/apex/apex` for the most recent installation. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# cd /opt +# mkdir apex +# cd apex +# mkdir apex-full-{release-version} +# tar xvfz ~/Downloads/apex-apps.uservice-packages-{release-version}-full.tar.gz -C apex-full-{release-version} +# ln -s apex apex-apps.uservice-packages-{release-version} +---- + + +=== Install Manually from Archive (Windows, 7Zip, GUI) +Download a `tar.gz` archive and copy the file into the install folder (in this example `C:\apex`). +Assuming you are using 7Zip, right click on the file and extract the `tar` archive. +Note: the screenshots might show an older version than you have. + +image::install-guide/win-extract-tar-gz.png[Extract the TAR archive] + +The right-click on the new created TAR file and extract the actual APEX distribution. + +image::install-guide/win-extract-tar.png[Extract the APEX distribution] + +Inside the new APEX folder you see the main directories: `bin`, `etc`, `examples`, `lib`, and `war` + +image::install-guide/win-extracted.png[Extracted APEX distribution] + +Once extracted, please rename the created folder to `apex-full-{release-version}`. +This will keep the directory name in line with the rest of this documentation. + + +=== Install Manually from Archive (Windows, 7Zip, CMD) +Download a `tar.gz` archive and copy the file into the install folder (in this example `C:\apex`). +Start `cmd`, for instance typing `Windows+R` and then `cmd` in the dialog. +Assuming `7Zip` is installed in the standard folder, simply run the following commands (for APEX version {release-version} full distribution) + +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>c: +>cd \apex +>"\Program Files\7-Zip\7z.exe" x apex-apps.uservice-packages-{release-version}-full.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-{release-version}" +---- + +APEX is now installed in the folder `C:\apex\apex-full-{release-version}`. + + + +== Build from Source + +=== Build and Install Manually (Unix, Windows, Cygwin) +Clone the APEX GIT repositories into a directory. +Go to that directory. +Use Maven to build APEX (all details on building APEX from source can be found in __APEX HowTo: Build__). +Install from the created artifacts (`rpm`, `deb`, `tar.gz`, or copying manually). + +[IMPORTANT] +.Building RPM distributions +==== +RPM images are only build if the `rpm` package is installed (Unix). +To install `rpm` run `sudo apt-get install rpm`, then build APEX. +==== + +The following example shows how to build the APEX system, without tests (`-DskipTests`) to safe some time. +It assumes that the APX GIT repositories are cloned to: + +- Unix, Cygwin: `/usr/local/src/apex` +- Windows: `C:\dev\apex` + + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +The build takes about 2 minutes without test and about 4-5 minutes with tests on a standard development laptop. +It should run through without errors, but with a lot of messages from the build process. +If build with tests (i.e. without `-DskipTests`), there will be error messages and stack trace prints from some tests. +This is normal, as long as the build finishes successful. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +The build will have created all artifacts required for an APEX installation. +The following example show how to change to the target directory and how it should look like. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + + +|==================== + +Now, take the `.deb` or the `.tar.gz` file and install APEX. +Alternatively, copy the content of the folder `install_hierarchy` to your APEX directory. + diff --git a/src/site-docs/adoc/fragments/install-guide/layout.adoc b/src/site-docs/adoc/fragments/install-guide/layout.adoc new file mode 100644 index 000000000..ef3d1cf5b --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/layout.adoc @@ -0,0 +1,47 @@ +// +// ============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) +// + +== Installation Layout + +A full installation of APEX comes with the following layout. + +---- +$APEX_HOME + ├───bin <1> + ├───etc <2> + │ ├───editor + │ ├───hazelcast + │ ├───infinispan + │ └───META-INF + ├───examples <3> + │ ├───config <4> + │ ├───docker <5> + │ ├───events <6> + │ ├───models <7> + │ └───scripts <8> + ├───lib <9> + │ └───applications <10> + └───war <11> +---- +<1> binaries, mainly scripts (bash and bat) to start the APEX engine and applications +<2> configuration files, such as logback (logging) and third party library configurations +<3> example policy models to get started +<4> configurations for the examples (with sub directories for individual examples) +<5> Docker files and additional Docker instructions for the exampples +<6> example events for the examples (with sub directories for individual examples) +<7> the policy models, generated for each example (with sub directories for individual examples) +<8> additional scripts for the examples (with sub directories for individual examples) +<9> the library folder with all Java JAR files +<10> applications, also known as jar with dependencies (or fat jars), individually deployable +<11> WAR files for web applications + diff --git a/src/site-docs/adoc/fragments/install-guide/requirements.adoc b/src/site-docs/adoc/fragments/install-guide/requirements.adoc new file mode 100644 index 000000000..6376a53e6 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/requirements.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) +// + +== Requirements +APEX is 100% written in Java and runs on any platform that supports a JVM, e.g. Windows, Unix, Cygwin. +Some APEX applications (such as the monitoring application) come as web archives, they do require a war-capable web server installed. + + +=== Installation Requirements + +- Downloaded distribution: JAVA runtime environment (JRE, Java 8 or later, APEX is tested with the Oracle Java) +- Building from source: JAVA development kit (JDK, Java 8 or later, APEX is tested with the Oracle Java) +- A web archive capable webserver, for instance for the monitoring application + ** for instance link:https://tomcat.apache.org/[Apache Tomcat] +- Sufficient rights to install APEX on the system +- Installation tools depending on the installation method used: + ** ZIP to extract from a ZIP distribution + *** Windows for instance link:http://www.7-zip.org/[7Zip] + ** TAR and GZ to extract from that TAR.GZ distribution + *** Windows for instance link:http://www.7-zip.org/[7Zip] + ** RPM to install from the RPM distribution + *** Install: `sudo apt-get install rpm` + ** DPKG to install from the DEB distribution + *** Install: `sudo apt-get install dpkg` + + +=== Feature Requirements +APEX supports a number of features that require extra software being installed. + +- link:https://kafka.apache.org/[Apache Kafka] to connect APEX to a Kafka message bus +- link:https://hazelcast.com/[Hazelcast] to use distributed hash maps for context +- link:http://infinispan.org/[Infinispan] for distributed context and persistence +- link:https://www.docker.com/[Docker] to run APEX inside a Docker container + + +=== Build (Install from Source) Requirements +Installation from source requires a few development tools + +- GIT to retrieve the source code +- Java SDK, Java version 8 or later +- Apache Maven 3 (the APEX build environment) + diff --git a/src/site-docs/adoc/fragments/install-guide/verify.adoc b/src/site-docs/adoc/fragments/install-guide/verify.adoc new file mode 100644 index 000000000..782c2723e --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/verify.adoc @@ -0,0 +1,180 @@ +// +// ============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) +// + +== Verify the APEX Installation +When APEX is installed and all settings are realized, the installation can be verified. + +=== Verify a Minimal Installation +The minimal installation does not come with any configuration or policy model. +It is therefore not possible to test all APEX features, or an engine running with policies. + +However, one can verify that the engine starts up to the point where it tries to load a configuration. + +On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`. +The engine will fail to fully start. +However, if the output looks similar to the following line, the APEX installation is realized. + +[source%nowrap,sh,numbered] +---- +Starting Apex service with parameters [] . . . +start of Apex service failed: Apex configuration file was not specified as an argument +2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: +---- + +On Windows start the engine using `%APEX_HOME%\bin\apexEngine.bat`. +The engine will fail to fully start. +However, if the output looks similar to the following line, the APEX installation is realized. + +[source%nowrap,bat,numbered] +---- +Starting Apex service with parameters [] . . . +start of Apex service failed: Apex configuration file was not specified as an argument +2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: +---- + + +=== Verify a Full Installation - run an Example +A full APEX installation comes with several examples. +Here, we can fully verify the installation by running one of the examples. + +We use the example called _SampleDomain_ and configure the engine to use standard in and standard out for events. +Run the engine with the provided configuration. +Note: Cygwin executes scripts as Unix scripts but runs Java as a Windows application, thus the configuration file must be given as a Windows path. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <1> +# $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-{release-version}/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <2> +>%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json @@ <3> +---- +<1> UNIX +<2> Cygwin +<3> Windows + + +The engine should start successfully. +Assuming the logging levels are not change (default level is `info`), the output should look similar to this (last few lines) + +[source%nowrap,sh,numbered] +---- +2017-07-28 13:20:54,673 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model SamplePolicyModelJAVA:0.0.1 added to the engine-AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) +2017-07-28 13:20:54,675 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-0,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:1] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-1,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:2] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-2,version=0.0.1) processing ... +2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:3] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) processing ... +2017-07-28 13:20:54,680 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine +Started Apex service +---- + +Important are the last two line, stating that APEX has added the final action listener to the engine and that the engine is started. + +The engine is configured to read events from standard input and write produced events to standard output. +The policy model is a very simple policy. + +The following table shows an input event in the left column and an output event in the right column. +Past the input event into the console where APEX is running, and the output event should appear in the console. +Pasting the input event multiple times will produce output events with different values. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Input Event | Example Output Event +| +[source%nowrap,json,numbered] +---- +{ + "nameSpace": "org.onap.policy.apex.sample.events", + "name": "Event0000", + "version": "0.0.1", + "source": "test", + "target": "apex", + "TestSlogan": "Test slogan for External Event0", + "TestMatchCase": 0, + "TestTimestamp": 1469781869269, + "TestTemperature": 9080.866 +} +---- +| +[source%nowrap,json,numbered] +---- +{ + "nameSpace" : "org.onap.policy.apex.sample.events", + "name" : "Event0004", + "version" : "0.0.1", + "source" : "Act", + "target" : "Outside", + "TestActCaseSelected" : 1, + "TestActStateTime" : 1499280954832, + "TestTemperature" : 9080.866, + "TestDecideCaseSelected" : 2, + "TestMatchCaseSelected" : 2, + "TestTimestamp" : 1469781869269, + "TestDecideStateTime" : 1499280954831, + "TestMatchCase" : 0, + "TestSlogan" : "Test slogan for External Event0", + "TestEstablishCaseSelected" : 1, + "TestEstablishStateTime" : 1499280954831, + "TestMatchStateTime" : 1499280954828 +} +---- +|==================== + +Terminate APEX by simply using `CTRL+C` in the console. + + +=== Verify a Full Installation - REST Editor +APEX has a REST application for viewing policy models. +The application can also be used to create new policy models close to the engine native policy language. +Start the REST editor as follows. + +[source%nowrap,sh,numbered] +---- +# $APEX_HOME/bin/apexApps.sh rest-editor +---- + +[source%nowrap,bat,numbered] +---- +>%APEX_HOME%\bin\apexApps.bat rest-editor +---- + +The script will start a simple web server (link:https://javaee.github.io/grizzly/[Grizzly]) and deploy a `war` web archive in it. +Once the editor is started, it will be available on `localhost:18988`. +The last few line of the messages should be: + +[source%nowrap,sh,numbered] +---- +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=READY) starting at http://localhost:18988/apex/ . . . +Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.NetworkListener start +INFO: Started listener bound to [localhost:18988] +Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.HttpServer start +INFO: [HttpServer] Started. +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=RUNNING) started at http://localhost:18988/apex/ +---- + +Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`. +This will connect the browser to the started REST editor. +The start screen should be as follows. + +.REST Editor Start Screen +image::install-guide/rest-start.png[REST Editor Start Screen] + +Now load a policy model by clicking the menu `File` and then `Open`. +In the opened dialog, go to the directory where APEX is installed, then `examples`, `models`, `SampleDomain`, and there select the file `SamplePolicyModelJAVA.json`. +This will load the policy model used to verify the policy engine (see above). +Once loaded, the screen should look as follows. + +.REST Editor with loaded SampleDomain Policy Model +image::install-guide/rest-loaded.png[REST Editor with loaded SampleDomain Policy Model] + +Now you can use the REST editor. +To finish this verification, simply terminate your browser (or the tab), and then use `CTRL+C` in the console where you started the REST editor. + diff --git a/src/site-docs/adoc/fragments/reference-publications/5g-2015.adoc b/src/site-docs/adoc/fragments/reference-publications/5g-2015.adoc new file mode 100644 index 000000000..6013e7c98 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/5g-2015.adoc @@ -0,0 +1,47 @@ +// +// ============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) +// + +== 5G & Autonomic Networking (5G Summit 2015) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| 5G & Autonomic Networking - Challenges in closing the Loop + +h| Venue +| 1st IEEE 5G Summit, Princeton, May 25, 2015 + +h| Abstract +| This presentation outlines the problems with existing policy based management systems and why we now need adaptive policy based management systems enabling networks to be self-governed. The talk focuses on the integration of key technologies shaping the future of the ENM Automation Framework, including control theory, predictive analytics, policy-based management context aware computing, knowledge engineering and semantics, modelling of adaptive behavior. + +h| Links +| link:https://www.researchgate.net/publication/277329201_5G_Autonomic_Networking_-_Challenges_in_closing_the_Loop[Research Gate] [accessed Aug 11, 2017] + +link:https://ieeetv.ieee.org/mobile/video/princeton-5g-summit-sven-van-der-meer-keynote-automatic-automation[Recorded Talk at IEEE TV] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@article{VanDerMeer2015b, + Author = {van der Meer, Sven}, + Journal = {IEEE First International 5G Summit}, + Month = {May}, + Title = {{5G \& Autonomic Networking - Challenges in closing the Loop}}, + Url = {https://ieeetv.ieee.org/mobile/video/princeton-5g-summit-sven-van-der-meer-keynote-automatic-automation}, + Year = {2015}, +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/apex.adoc b/src/site-docs/adoc/fragments/reference-publications/apex.adoc new file mode 100644 index 000000000..4f52fe85c --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/apex.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) +// + +== APEX & Policy + +The following publications discuss APEX and policy aspects, such as + +* Adaptive Policies +* SON Use Case with Adaptive Policies +* The APEX Engine, including performance analysis +* Distributed Information Management, also known as the APEX Context management + diff --git a/src/site-docs/adoc/fragments/reference-publications/cnsm-2014.adoc b/src/site-docs/adoc/fragments/reference-publications/cnsm-2014.adoc new file mode 100644 index 000000000..27042a949 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/cnsm-2014.adoc @@ -0,0 +1,55 @@ +// +// ============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) +// + +== Towards NFV (CNSM'14) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Towards Real-time Management of Virtualized Telecommunication Networks + +h| Venue +| IEEE CNSM, Rio de Janeiro, November 2014 + +h| Abstract +| The idea of virtualizing network functions is driven by recent advances in network-focused hardware. In 2012, several large telecommunication operators issued a call to action for Network Function Virtualization (NFV) 1. The underlying idea is that every network service currently delivered on proprietary, application specific hardware should be deliverable using virtual machines. This means that routers, firewalls, load balancers and other network devices run virtualized on commodity hardware. Consequently, ETSI is extending this idea to mobile networks. Here, parts of the core and the radio access network will be virtualized. The immediate advantage is that any Virtual Network Function (VNF) can now be deployed, redeployed and un-deployed in the same way as any traditional virtual machine. Thus, NFV will result in more dynamic and agile networks than seen heretofore. However, this will raise a number of serious issues in managing these future networks. In this paper, we examine issues and challenges in orchestrating these virtualized functions and their interconnections to provide a more agile mobile telecommunication network. + +h| Links +| link:https://www.researchgate.net/publication/272164781_Towards_Real-time_Management_of_Virtualized_Telecommunication_Networks[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/cnsm/KeeneyMF14, + author = {John Keeney and + Sven van der Meer and + Liam Fallon}, + title = {Towards Real-time Management of + Virtualized Telecommunication Networks}, + booktitle = {10th International Conference on Network and Service Management, + {CNSM} 2014, Rio de Janeiro, Brazil, November 17-21, 2014}, + pages = {388--393}, + year = {2014}, + crossref = {DBLP:conf/cnsm/2014}, + url = {https://doi.org/10.1109/CNSM.2014.7014200}, + doi = {10.1109/CNSM.2014.7014200}, + timestamp = {Tue, 23 May 2017 01:11:56 +0200}, + biburl = {http://dblp.org/rec/bib/conf/cnsm/KeeneyMF14}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/cnsm-2015.adoc b/src/site-docs/adoc/fragments/reference-publications/cnsm-2015.adoc new file mode 100644 index 000000000..01bd55d00 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/cnsm-2015.adoc @@ -0,0 +1,55 @@ +// +// ============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) +// + +== Dynamically Adaptive Policies (CNSM'15) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Dynamically Adaptive Policies for Dynamically Adaptive Telecommunications Networks + +h| Venue +| IEEE CNSM, Barcelona, November 2015 + +h| Abstract +| New technologies are changing the world of communication networks and even more so their management. Cloud computing and predictive analytics have removed the need for specialized compute hardware and created products that continuously search for and find insights in management data. Virtualization of networks and network functions, SDN and NFV, are beginning to be mature enough for production networks resulting in much more flexible and dynamic networks. IoT and M2M traffic and new customer demands are driving new thinking and demands for 5G networks. Almost every aspect in the control and management of networks has seen new dimensions of flexibility and dynamicity, with the notable exception of the policies that drive them. This paper discusses the need to add adaptiveness to classic policies, describes a novel approach for adaptive policies, shows how adaptive policies will form part of future network frameworks and architectures, and finally discusses early use cases developed for mobile operators. + +h| Links +| link:https://www.researchgate.net/publication/282576518_Dynamically_Adaptive_Policies_for_Dynamically_Adaptive_Telecommunications_Networks[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/cnsm/MeerKF15, + author = {Sven van der Meer and + John Keeney and + Liam Fallon}, + title = {Dynamically Adaptive Policies for + Dynamically Adaptive Telecommunications Networks}, + booktitle = {11th International Conference on Network and Service Management, + {CNSM} 2015, Barcelona, Spain, November 9-13, 2015}, + pages = {182--186}, + year = {2015}, + crossref = {DBLP:conf/cnsm/2015}, + url = {https://doi.org/10.1109/CNSM.2015.7367357}, + doi = {10.1109/CNSM.2015.7367357}, + timestamp = {Tue, 23 May 2017 01:11:56 +0200}, + biburl = {http://dblp.org/rec/bib/conf/cnsm/MeerKF15}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/im-2013.adoc b/src/site-docs/adoc/fragments/reference-publications/im-2013.adoc new file mode 100644 index 000000000..0c9000a02 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/im-2013.adoc @@ -0,0 +1,55 @@ +// +// ============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) +// + +== Recommender System (IM'13) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| A Recommender-system for Telecommunications Network Management Actions + +h| Venue +| IEEE IM, Ghent, May 2013 + +h| Abstract +| Research and products in telecoms network management have long been focused on the automation of processes to keep complex managed networks in an operational state, while being profitable to operate for the network operator. Due to the ever increasing scale and complexity of the problem domain, coupled with specific constraints (legal, regulatory, technological change), a fully automated management approach is virtually impossible. It remains the responsibility of human Network Operations Centre (NOC) operators to oversee and manage the running of the network, where their main task is to respond to huge numbers of messages, errors, warnings and faults constantly flowing from the managed network. In the past, network operators either employed expert systems or became very dependent on expert knowledge of their operational staff. Considering the current explosion in size and complexity of managed telecoms network, it is widely understood and accepted that current manual and semiautomated approaches cannot scale. In this paper we investigate the applicability of recommender systems as an approach to assist NOC operators to correctly respond to indications of incidents in the network they are actively managing. + +h| Links +| link:https://www.researchgate.net/publication/259785776_A_recommender-system_for_telecommunications_network_management_actions[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/im/KeeneyMH13, + author = {John Keeney and + Sven van der Meer and + Gabriel Hogan}, + title = {A Recommender-system for Telecommunications + Network Management Actions}, + booktitle = {2013 {IFIP/IEEE} International Symposium on Integrated + Network Management + {IM} 2013, Ghent, Belgium, May 27-31, 2013}, + pages = {760--763}, + year = {2013}, + crossref = {DBLP:conf/im/2013}, + url = {http://ieeexplore.ieee.org/document/6573072/}, + timestamp = {Sun, 30 Apr 2017 09:41:39 +0200}, + biburl = {http://dblp.org/rec/bib/conf/im/KeeneyMH13}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/im-2017a.adoc b/src/site-docs/adoc/fragments/reference-publications/im-2017a.adoc new file mode 100644 index 000000000..0daeebbe2 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/im-2017a.adoc @@ -0,0 +1,55 @@ +// +// ============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) +// + +== D-MIM (IM'17) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Distributed Management Information Models + +h| Venue +| IEEE IM, Lisbon, May 2017 + +h| Abstract +| The use of information models to share and allow modification of network element state is one of the best and most widely adopted ideas in network management. The formal structure of information models and the controlled manner of accessing and changing such models brings both flexibility and control when managing network elements. However, keeping information models synchronized and consistent across network elements and management systems is also one of the most challenging tasks in network management system development. Today this problem is exasperated with the advent of ephemeral network functions and elements and also by the need for distributed scalable cooperating management functions running in containerized distributed cloud deployments. In computer science, there have been major advances in systems that allow seamless distribution of data across distributed executing entities, and separately in systems that allow highly granular data access synchronization across distributed entities. However, such systems do not place importance on " information model " concepts, with data usually distributed as largely unmodeled unstructured data maps. In this paper, we describe our novel approach for distributed information models. We describe how information models are distributed to dispersed network elements and management systems, how synchronized access to distributed information models is achieved, how information models are persisted, and how lookups and changes to information models are logged. + +h| Links +| link:https://www.researchgate.net/publication/316629867_Distributed_Management_Information_Models[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/im/FallonKM17, + author = {Liam Fallon and + John Keeney and + Sven van der Meer}, + title = {Distributed Management Information Models}, + booktitle = {2017 {IFIP/IEEE} International Symposium on Integrated + Network Management + {IM} 2017, Lisbon, Portugal, May 8-12, 2017}, + pages = {414--420}, + year = {2017}, + crossref = {DBLP:conf/im/2017}, + url = {https://doi.org/10.23919/INM.2017.7987306}, + doi = {10.23919/INM.2017.7987306}, + timestamp = {Fri, 28 Jul 2017 12:12:57 +0200}, + biburl = {http://dblp.org/rec/bib/conf/im/FallonKM17}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/im-2017b.adoc b/src/site-docs/adoc/fragments/reference-publications/im-2017b.adoc new file mode 100644 index 000000000..92a59bcd1 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/im-2017b.adoc @@ -0,0 +1,58 @@ +// +// ============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) +// + +== COMPA AADM (IM'2017) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Using the COMPA Autonomous Architecture for Mobile Network Security + +h| Venue +| IEEE IM, Lisbon, May, 2017 + +h| Abstract +| The COMPA (Control, Orchestration, Management, Policy, and Analytics) adaptive control loop realizes an automation pattern that can operate recursively at many layers in a carrier network. An overall COMPA autonomic control loop can orchestrate functions, themselves implemented as COMPA autonomic loops. Thus the COMPA automation patter can recurse right down to resource level in a network. One of the most exciting application areas for the COMPA automation pattern is in assuring mobile network security. The recursive nature of the pattern is the ideal mechanism for automating monitoring and root cause analysis of security threats to networks. In this paper we present a Proof of Concept of a COMPA compliant system for a Distributed Denial of Service (DDoS) scenario. The system monitors, performs root cause analysis, and mitigates a DDoS attack. The system was built by integrating a number of existing components that were deployed as VNFs. Our experiences of using the system were that the system could handle a DDoS attack quickly and automatically. In addition, the system was very flexible to build and deploy. + +h| Links +| link:https://www.researchgate.net/publication/317014658_Using_the_COMPA_Autonomous_Architecture_for_Mobile_Network_Security[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/im/FallonKMQM17, + author = {Liam Fallon and + John Keeney and + Mark McFadden and + John Quilty and + Sven van der Meer}, + title = {Using the {COMPA} Autonomous Architecture + for Mobile Network Security}, + booktitle = {2017 {IFIP/IEEE} International Symposium on Integrated + Network Management + {IM} 2017, Lisbon, Portugal, May 8-12, 2017}, + pages = {747--753}, + year = {2017}, + crossref = {DBLP:conf/im/2017}, + url = {https://doi.org/10.23919/INM.2017.7987370}, + doi = {10.23919/INM.2017.7987370}, + timestamp = {Fri, 28 Jul 2017 12:12:57 +0200}, + biburl = {http://dblp.org/rec/bib/conf/im/FallonKMQM17}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/monami-2012.adoc b/src/site-docs/adoc/fragments/reference-publications/monami-2012.adoc new file mode 100644 index 000000000..3ad4fc8cf --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/monami-2012.adoc @@ -0,0 +1,32 @@ +// +// ============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) +// + +== HetNets, Big Data, Cloud, SDN ... (Monami'12) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| HetNets, Big Data, Cloud, SDN...all problems solved and your lunch served, right? + +h| Venue +| Keynote, 4th MONAMI, Hamburg, September, 2012 + +h| Abstract +| What happens when you get a huge increase of devices and cells (i.e.Heterogeneous Networks - HetNets), all of which have to be monitored and managed, and our current OSSs are already overburdened, handling their existing workloads? In other domains, there are many promising techniques, such as smart filtering, complex event processing, and predictive analytics, but they are not as effectively applied to network management. Why is that? Can we do better? Instead of being overloaded with all of the hype (BigData and Cloud and Software-Defined Networking) and hoping that by mixing some combination of these magic ingredients a solution will emerge, a combination of science and engineering might be a better way to solve the problem! This keynote will discuss a number of common misconceptions with regard to technologies, all of which cause us to spend money on useless mechanisms and services. Focusing on the actual problems, which are a combination of current state of business, foreseeable future, and customer demands, we will be able to point to a number of real problems that require a solution. As with many things, there is no silver bullet but a combination of social and behavioral, technical and methodological advances that will facilitate a networked society, and in the process change the nature of OSSs from Operation Support Systems to Opportunity Support Systems. + +h| Links +| link:https://www.researchgate.net/publication/279527537_HetNets_Big_Data_Cloud_SDNall_problems_solved_and_your_lunch_served_right[Research Gate] [accessed Aug 11, 2017] + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/monami-2013.adoc b/src/site-docs/adoc/fragments/reference-publications/monami-2013.adoc new file mode 100644 index 000000000..157ed86dd --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/monami-2013.adoc @@ -0,0 +1,57 @@ +// +// ============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) +// + +== Drools Performance (Monami'13) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Cloudifying Mobile Network Management: Performance Tests of Event Distribution and Rule Processing + +h| Venue +| Monami, Cork, November 2013 + +h| Abstract +| The explosion in consumer devices has resulted in a significant increase in the number of mobile telecommunications nodes. As a result of increased device and node numbers, network operators have experienced a large increase in associated events. In such an environment, scalability and performance of event handling become important aspects for Operation Support Systems (OSS). A traditional approach has been to centralize monitoring and decision functions. The scale of events in a modern mobile telecommunications network means such centralized implementations are performance limited. What is required is a remodeling of Complex Event Processing (monitoring) and Policies (decision making) towards a distributed yet coordinated system. This paper describes an extensible architecture for such a distributed policy-based event processing system. Our approach provides a pluggable mechanism into which various event handling functionality can be integrated. In order to illustrate the applicability of our approach we evaluate the performance of 2 message queuing protocols, Advanced Message Queuing Protocol (AMQP) based RabbitMQ and Java Web Sockets. Our performance evaluation illustrates the ability of our architecture to transparently integrate alternative event processing technologies. + +h| Links +| ### + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/monami/DawarMKFB13, + author = {Sumit Dawar and + Sven van der Meer and + John Keeney and + Enda Fallon and + Tom Bennet}, + title = {Cloudifying Mobile Network Management: Performance Tests + of Event Distribution and Rule Processing}, + booktitle = {Mobile Networks and Management - 5th International Conference, + {MONAMI} 2013, Cork, Ireland, September 23-25, 2013}, + pages = {94--107}, + year = {2013}, + crossref = {DBLP:conf/monami/2013}, + url = {https://doi.org/10.1007/978-3-319-04277-0_8}, + doi = {10.1007/978-3-319-04277-0_8}, + timestamp = {Wed, 24 May 2017 08:27:31 +0200}, + biburl = {http://dblp.org/rec/bib/conf/monami/DawarMKFB13}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/noms-2016.adoc b/src/site-docs/adoc/fragments/reference-publications/noms-2016.adoc new file mode 100644 index 000000000..ee3dceea7 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/noms-2016.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) +// + +== APEX Engine (NOMS'16) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| APEX: An Engine for Dynamic Adaptive Policy Execution + +h| Venue +| IEEE NOMS, Istanbul, April 2016 + +h| Abstract +| The advent of " Soft Networking " , where networks are composed of virtual nodes and links, promises to dramatically ease the definition and deployment of networks whilst allowing network applications that are limited only by the imagination of the developers of those applications. In such a dynamic environment, the Autonomic Management pattern supervised by policies has been recognized as holding more promise for management of Soft Networks than traditional techniques. We have proposed Dynamic Adaptive Policies as an approach to give classic policies the dynamicity and flexibility to manage such networks and whatever applications are running on them. In this paper, we describe our ongoing work on Apex, an engine that executes and administers Dynamic Adaptive Policies in a scalable and distributed manner. + +h| Links +| link:https://www.researchgate.net/publication/303564082_Apex_An_Engine_for_Dynamic_Adaptive_Policy_Execution[Research Gate] [accessed Aug 11, 2017] + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{DBLP:conf/noms/FallonMK16, + author = {Liam Fallon and + Sven van der Meer and + John Keeney}, + title = {Apex: An Engine for Dynamic Adaptive Policy Execution}, + booktitle = {2016 {IEEE/IFIP} Network Operations and Management Symposium, + {NOMS} 2016, Istanbul, Turkey, April 25-29, 2016}, + pages = {699--702}, + year = {2016}, + crossref = {DBLP:conf/noms/2016}, + url = {https://doi.org/10.1109/NOMS.2016.7502880}, + doi = {10.1109/NOMS.2016.7502880}, + timestamp = {Fri, 19 May 2017 01:26:25 +0200}, + biburl = {http://dblp.org/rec/bib/conf/noms/FallonMK16}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/noms-2018a.adoc b/src/site-docs/adoc/fragments/reference-publications/noms-2018a.adoc new file mode 100644 index 000000000..b7558da4e --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/noms-2018a.adoc @@ -0,0 +1,60 @@ +// +// ============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) +// + +== Unifying Policy Theory (the APEX theory) (NOMS'18) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| Taming Policy Complexity: Model to Execution + +h| Venue +| IEEE NOMS, Taipei, April 2018 + +h| Abstract +| Since the 1970’s it has been acknowledged that a +complex system can be broken into (a) its invariant functional +parts (mechanism), and (b) the externalized choices for how the +system should behave (policy). Policy-based management’s main +objective is to separate and externalize the decisions required by a +system from the mechanisms provided by the system, and provide +a way to define and evaluate these decisions. A few decades later, +we have today a plethora of different policy models and even more +policy languages – plus tooling – offering policy-based solutions +for virtually any use case and scenario. However, policy-based +management as a standalone domain has never been evaluated +in terms of which parts are variant / invariant, i.e. which parts +of policy-based management can be domain-, model-, language-, +usecase-independent. In this paper, we introduce and define a +formal universal policy model that does exactly that. The result +is a model that can be used to design, implement, and deploy +immutable policy infrastructure (engine and executor) being able +to execute (virtually) any policy model. + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{noms/MeerMK18a, + author = {Sven van der Meer and + John Keeney and + Liam Fallon}, + title = {Taming Policy Complexity: Model to Execution}, + booktitle = {2018 {IEEE/IFIP} Network Operations and Management Symposium, + {NOMS} 2018, Taipei, Taiwan, April 23-27, 2018}, + year = {2018} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/noms-2018b.adoc b/src/site-docs/adoc/fragments/reference-publications/noms-2018b.adoc new file mode 100644 index 000000000..2500e70b1 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/noms-2018b.adoc @@ -0,0 +1,56 @@ +// +// ============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) +// + +== 5G Management and Policy (NOMS'18) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| 5G Networks Must Be Autonomic! + +h| Venue +| IEEE NOMS, Taipei, April 2018 + +h| Abstract +| 5G networks will be the first real converged networks +supporting a plethora of different services, each with their +own requirements. A static best-effort approach is no longer +sufficient. Extreme flexibility and dynamicity is required, yet costs +must be drastically reduced. The only way that these conflicting +goals can be achieved is with vastly increased automation in the +provision and operation of our future 5G networks. In this paper +we briefly discuss the facilitators, goals and challenges for 5G +networks. We identify some of the places where automation is not +just helpful, but is in fact required for 5G to become a reality. +We go on to present a conceptual approach for modeling and +achieving autonomic operations and management in 5G networks +positioning modern policy-based management as a key enabler +for autonomic 5G network management. + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{noms/MeerMK18b, + author = {Sven van der Meer and + John Keeney and + Liam Fallon}, + title = {5G Networks Must Be Autonomic!}, + booktitle = {2018 {IEEE/IFIP} Network Operations and Management Symposium, + {NOMS} 2018, Taipei, Taiwan, April 23-27, 2018}, + year = {2018} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/noms-2018c.adoc b/src/site-docs/adoc/fragments/reference-publications/noms-2018c.adoc new file mode 100644 index 000000000..96803d828 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/noms-2018c.adoc @@ -0,0 +1,51 @@ +// +// ============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) +// + +== An APEX Testbed (NOMS'18) + +[width="100%",cols="15%,90%"] +|=== + +h| Title +e| A Testbed For Policy Driven Closed Loop Network Management + +h| Venue +| IEEE NOMS, Taipei, April 2018 + +h| Abstract +| Due to the increase in the dynamicity, programmability, scope and complexity of modern networks there is a greatly increased requirement that network management systems control, orchestrate and manage networks in a much more automated and dynamic manner. +This drive towards automation and dynamicity requires autonomic network management that continuously analyses network state and continually steers the network in accordance with changing high level goals and policies. As dynamicity increases, it is proving increasingly difficult to test and validate the analytics routines and policies that drive today\textquoteright s network management systems. With more automation, the potential for unanticipated network incidents increase, for example where multiple automation features interact and conflict. + +There is no substitute for seeing how a network management feature actually performs in a real network, ideally allowing iterative authoring/validation development cycles. However, due to the high stakes involved in degrading or disrupting network performance, this is not usually feasible until the very final testing and deployment stages. The next best option is a testbed that accurately represents a live network scenario to support authoring and validation development cycles in a low-risk environment. + +In this work we present our experiences of building a networking testbed that incorporates an emulated network, a production-grade network controller, an analytics function, and a policy execution environment. This allows users to develop policies for adaptive (closed loop) management of a realistic emulated network. We also present two scenarios where the testbed is used to emulate and mitigate against a temporary and prolonged failure occurring on a network. + +h| BibTeX +a| +[source,bibtex] +---- +@inproceedings{noms/McNamaraMK18, + author = {Joseph McNamara and + John Keeney and + Liam Fallon and + Sven van der Meer and + Enda Fallon}, + title = {A Testbed For Policy Driven Closed Loop Network Management}, + booktitle = {2018 {IEEE/IFIP} Network Operations and Management Symposium, + {NOMS} 2018, Taipei, Taiwan, April 23-27, 2018}, + year = {2018} +} +---- + +|=== + diff --git a/src/site-docs/adoc/fragments/reference-publications/policy-general.adoc b/src/site-docs/adoc/fragments/reference-publications/policy-general.adoc new file mode 100644 index 000000000..c94784650 --- /dev/null +++ b/src/site-docs/adoc/fragments/reference-publications/policy-general.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) +// + +== Policy in General + +The following publications discuss general policy aspects, such as + +* Policy as part of Autonomic Networks +* Policy as part of a closed control loop, mainly COMPA +* Policy and Semantics + diff --git a/src/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt b/src/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt new file mode 100644 index 000000000..eaf1c1351 --- /dev/null +++ b/src/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt @@ -0,0 +1,13 @@ +[INFO] apex-apps.uservice ................................. SUCCESS [ 0.054 s] +[INFO] apex-apps.uservice-packaging ....................... SUCCESS [ 0.058 s] +[INFO] apex-apps.uservice-package-minimal ................. SUCCESS [ 7.138 s] +[INFO] apex-apps.uservice-package-full .................... SUCCESS [ 58.960 s] +[INFO] apex-apps.uservice-packages ........................ SUCCESS [ 1.781 s] +[INFO] apex-apps.servlet .................................. SUCCESS [ 3.465 s] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 02:48 min +[INFO] Finished at: 2018-01-04T12:20:45+00:00 +[INFO] Final Memory: 164M/1648M +[INFO] ------------------------------------------------------------------------
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/screens/mvn-install.txt b/src/site-docs/adoc/fragments/screens/mvn-install.txt new file mode 100644 index 000000000..6e5f9c1e9 --- /dev/null +++ b/src/site-docs/adoc/fragments/screens/mvn-install.txt @@ -0,0 +1,13 @@ +[INFO] apex-apps.uservice ................................. SUCCESS [ 0.027 s] +[INFO] apex-apps.uservice-packaging ....................... SUCCESS [ 0.008 s] +[INFO] apex-apps.uservice-package-minimal ................. SUCCESS [ 6.934 s] +[INFO] apex-apps.uservice-package-full .................... SUCCESS [ 55.667 s] +[INFO] apex-apps.uservice-packages ........................ SUCCESS [ 1.833 s] +[INFO] apex-apps.servlet .................................. SUCCESS [ 2.383 s] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 05:34 min +[INFO] Finished at: 2018-01-04T13:49:16+00:00 +[INFO] Final Memory: 164M/1595M +[INFO] ------------------------------------------------------------------------
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/screens/target-ls-unix.txt b/src/site-docs/adoc/fragments/screens/target-ls-unix.txt new file mode 100644 index 000000000..99973f795 --- /dev/null +++ b/src/site-docs/adoc/fragments/screens/target-ls-unix.txt @@ -0,0 +1,12 @@ +-rwxrwx---+ 1 esvevan Domain Users 706 Jan 4 10:44 apex-apps.uservice-package-full_0.7.0_all.changes +-rwxrwx---+ 1 esvevan Domain Users 32694 Jan 4 10:43 apex-apps.uservice-package-full-0.7.0.jar +-rwxrwx---+ 1 esvevan Domain Users 255629634 Jan 4 10:44 apex-uservice-full-0.7.0.deb +-rwxrwx---+ 1 esvevan Domain Users 255613724 Jan 4 10:43 apex-uservice-full-0.7.0-tarball.tar.gz +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 archive-tmp/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 classes/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 dependency-maven-plugin-markers/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 etc/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 examples/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 install_hierarchy/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 lib/ +drwxrwx---+ 1 esvevan Domain Users 0 Jan 4 10:43 maven-archiver/
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/screens/target-ls-win.txt b/src/site-docs/adoc/fragments/screens/target-ls-win.txt new file mode 100644 index 000000000..7a78d07dd --- /dev/null +++ b/src/site-docs/adoc/fragments/screens/target-ls-win.txt @@ -0,0 +1,16 @@ +04/01/2018 11:51 <DIR> . +04/01/2018 11:51 <DIR> .. +04/01/2018 10:43 32,694 apex-apps.uservice-package-full-0.7.0.jar +04/01/2018 10:44 706 apex-apps.uservice-package-full_0.7.0_all.changes +04/01/2018 10:43 255,613,724 apex-uservice-full-0.7.0-tarball.tar.gz +04/01/2018 10:44 255,629,634 apex-uservice-full-0.7.0.deb +04/01/2018 10:43 <DIR> archive-tmp +04/01/2018 10:43 <DIR> classes +04/01/2018 10:43 <DIR> dependency-maven-plugin-markers +04/01/2018 10:43 <DIR> etc +04/01/2018 10:43 <DIR> examples +04/01/2018 10:43 <DIR> install_hierarchy +04/01/2018 10:43 <DIR> lib +04/01/2018 10:43 <DIR> maven-archiver + 4 File(s) 511,276,758 bytes + 10 Dir(s) 6,230,409,216 bytes free
\ No newline at end of file |