Add TOSCA policy status header field to APEX event create CLI

In order to expose the processing status of a TOSCA policy
to APEX-PDP, a new header field for APEX concept "event"
has been introduced to track this within an APEX policy
implementation. This field will be leveraged to extract
the TOSCA policy execution metrics. Note, that the field is
marked as optional for backward compatibility.
Unit tests have been augmented to test for the field wherever
applicable and the default empty value is retained for the others.

"example-grpc" module has been updated to include this field.
Exposing the TOSCA policy execution metrics is outside the
scope of this patch since the current changes are already
very large owing to the atomic nature of the change introduced.

Issue-ID: POLICY-3845
Signed-off-by: Rashmi Pujar <rashmi.pujar1@bell.ca>
Change-Id: Ief6d70f9abcfc8414e10aa51a27815ee9028e4c8

5 files changed, 72 insertions, 23 deletions

diff --git a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexEvent.java b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexEvent.java
index 76a1c03a2..a8f13bbf6 100644
--- a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexEvent.java
+++ b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexEvent.java
@@ -2,6 +2,7 @@
  * ============LICENSE_START=======================================================
  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
  *  Modifications Copyright (C) 2021 AT&T Intellectual Property. All rights reserved.
+ *  Modifications Copyright (C) 2022 Bell Canada. All rights reserved.
  * ================================================================================
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,7 +22,9 @@
 
 package org.onap.policy.apex.service.engine.event;
 
+import com.google.common.base.Strings;
 import java.io.Serializable;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Properties;
@@ -30,7 +33,9 @@ import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
 import lombok.ToString;
+import org.apache.commons.lang3.EnumUtils;
 import org.onap.policy.apex.model.basicmodel.concepts.AxReferenceKey;
+import org.onap.policy.apex.model.basicmodel.concepts.AxToscaPolicyProcessingStatus;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -92,6 +97,14 @@ public class ApexEvent extends HashMap<String, Object> implements Serializable {
     public static final String TARGET_HEADER_FIELD = "target";
 
     /**
+     * The toscaPolicyState of Apex event, an optional field. It specifies the TOSCA Policy processing status
+     * on an Apex event, with possible values as enumerated in
+     * {@link org.onap.policy.apex.model.basicmodel.concepts.AxToscaPolicyProcessingStatus}.
+     * If no toscaPolicyState is specified, it indicates that the TOSCA Policy is under process.
+     */
+    public static final String TOSCA_POLICY_STATE_HEADER_FIELD = "toscaPolicyState";
+
+    /**
      * The exception message field of an Apex event is an exception message indicating that an event
      * failed.
      */
@@ -118,6 +131,7 @@ public class ApexEvent extends HashMap<String, Object> implements Serializable {
     private final String nameSpace;
     private final String source;
     private final String target;
+    private final String toscaPolicyState;
 
     // An identifier for the current event execution. The default value here will always be unique
     // in a single JVM
@@ -143,14 +157,13 @@ public class ApexEvent extends HashMap<String, Object> implements Serializable {
      * @throws ApexEventException thrown on validation errors on event names and versions
      */
     public ApexEvent(final String name, final String version, final String nameSpace, final String source,
-            final String target) throws ApexEventException {
-        // @formatter:off
-        this.name      = validateField(NAME_HEADER_FIELD,      name,      NAME_REGEXP);
-        this.version   = validateField(VERSION_HEADER_FIELD,   version,   VERSION_REGEXP);
+            final String target, final String toscaPolicyState) throws ApexEventException {
+        this.name = validateField(NAME_HEADER_FIELD, name, NAME_REGEXP);
+        this.version = validateField(VERSION_HEADER_FIELD, version, VERSION_REGEXP);
         this.nameSpace = validateField(NAMESPACE_HEADER_FIELD, nameSpace, NAMESPACE_REGEXP);
-        this.source    = validateField(SOURCE_HEADER_FIELD,    source,    SOURCE_REGEXP);
-        this.target    = validateField(TARGET_HEADER_FIELD,    target,    TARGET_REGEXP);
-        // @formatter:on
+        this.source = validateField(SOURCE_HEADER_FIELD, source, SOURCE_REGEXP);
+        this.target = validateField(TARGET_HEADER_FIELD, target, TARGET_REGEXP);
+        this.toscaPolicyState = validateField(TOSCA_POLICY_STATE_HEADER_FIELD, toscaPolicyState, "");
     }
 
     /**
@@ -174,6 +187,17 @@ public class ApexEvent extends HashMap<String, Object> implements Serializable {
      */
     private String validateField(final String fieldName, final String fieldValue, final String fieldRegexp)
             throws ApexEventException {
+        if (fieldName.equals(TOSCA_POLICY_STATE_HEADER_FIELD) && !Strings.isNullOrEmpty(fieldValue)) {
+            if (EnumUtils.isValidEnum(AxToscaPolicyProcessingStatus.class, fieldValue)) {
+                return fieldValue;
+            } else {
+                String message = EVENT_PREAMBLE + name + ": field \"" + fieldName + "=" + fieldValue
+                        + "\"  is illegal. It doesn't match supported values '"
+                        + Arrays.asList(AxToscaPolicyProcessingStatus.values()) + "'";
+                LOGGER.warn(message);
+                throw new ApexEventException(message);
+            }
+        }
         if (fieldValue.matches(fieldRegexp)) {
             return fieldValue;
         } else {
@@ -243,4 +267,4 @@ public class ApexEvent extends HashMap<String, Object> implements Serializable {
         // Go ahead and put everything
         super.putAll(incomingMap);
     }
-}
+}
\ No newline at end of file
diff --git a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexPeriodicEventGenerator.java b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexPeriodicEventGenerator.java
index 1300f2176..ea3cb4b29 100644
--- a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexPeriodicEventGenerator.java
+++ b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/ApexPeriodicEventGenerator.java
@@ -2,6 +2,7 @@
  * ============LICENSE_START=======================================================
  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
  *  Modifications Copyright (C) 2021 Nordix Foundation.
+ *  Modifications Copyright (C) 2022 Bell Canada. All rights reserved.
  * ================================================================================
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,6 +54,9 @@ public class ApexPeriodicEventGenerator extends TimerTask {
     /** The target of the periodic event. */
     public static final String PERIODIC_EVENT_TARGET = PERIODIC_EVENT_SOURCE;
 
+    /** The status of the periodic event. */
+    public static final String PERIODIC_EVENT_STATUS = "";
+
     /**
      * The field name in the periodic event for the delay between occurrences of the periodic event.
      */
@@ -137,7 +141,7 @@ public class ApexPeriodicEventGenerator extends TimerTask {
         // Send the periodic event
         try {
             final var periodicEvent = new ApexEvent(PERIODIC_EVENT_NAME, PERIODIC_EVENT_VERSION,
-                    PERIODIC_EVENT_NAMESPACE, PERIODIC_EVENT_SOURCE, PERIODIC_EVENT_TARGET);
+                    PERIODIC_EVENT_NAMESPACE, PERIODIC_EVENT_SOURCE, PERIODIC_EVENT_TARGET, PERIODIC_EVENT_STATUS);
             periodicEvent.putAll(periodicEventMap);
             engineServiceEventInterface.sendEvent(periodicEvent);
         } catch (final ApexEventException e) {
@@ -171,4 +175,4 @@ public class ApexPeriodicEventGenerator extends TimerTask {
         return "ApexPeriodicEventGenerator [period=" + eventGeneratorPeriod + ", firstEventTime=" + firstEventTime
                 + ", lastEventTime=" + lastEventTime + ", eventCount=" + eventCount + "]";
     }
-}
+}
\ No newline at end of file
diff --git a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/enevent/ApexEvent2EnEventConverter.java b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/enevent/ApexEvent2EnEventConverter.java
index 27fa50988..3bbd3ab4f 100644
--- a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/enevent/ApexEvent2EnEventConverter.java
+++ b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/enevent/ApexEvent2EnEventConverter.java
@@ -1,7 +1,7 @@
 /*-
  * ============LICENSE_START=======================================================
  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
- *  Modifications Copyright (C) 2021 Bell Canada. All rights reserved.
+ *  Modifications Copyright (C) 2021-2022 Bell Canada. All rights reserved.
  *  Modifications Copyright (C) 2021 Nordix Foundation.
  *  Modifications Copyright (C) 2021 AT&T Intellectual Property. All rights reserved.
  * ================================================================================
@@ -72,12 +72,12 @@ public final class ApexEvent2EnEventConverter implements ApexEventConverter {
         // Create the Apex event
         final var axEvent = enEvent.getAxEvent();
         final var apexEvent = new ApexEvent(axEvent.getKey().getName(), axEvent.getKey().getVersion(),
-                axEvent.getNameSpace(), axEvent.getSource(), axEvent.getTarget());
+                axEvent.getNameSpace(), axEvent.getSource(), axEvent.getTarget(), axEvent.getToscaPolicyState());
 
         apexEvent.setExecutionId(enEvent.getExecutionId());
         apexEvent.setExecutionProperties(enEvent.getExecutionProperties());
 
-        // Copy he exception message to the Apex event if it is set
+        // Copy the exception message to the Apex event if it is set
         if (enEvent.getExceptionMessage() != null) {
             apexEvent.setExceptionMessage(enEvent.getExceptionMessage());
         }
@@ -119,4 +119,4 @@ public final class ApexEvent2EnEventConverter implements ApexEventConverter {
 
         return enEvent;
     }
-}
+}
\ No newline at end of file
diff --git a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/Apex2JsonEventConverter.java b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/Apex2JsonEventConverter.java
index 56f0d6ba8..976a3ae3d 100644
--- a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/Apex2JsonEventConverter.java
+++ b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/Apex2JsonEventConverter.java
@@ -2,7 +2,7 @@
  * ============LICENSE_START=======================================================
  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
  *  Modifications Copyright (C) 2019-2021 Nordix Foundation.
- *  Modifications Copyright (C) 2021 Bell Canada. All rights reserved.
+ *  Modifications Copyright (C) 2021-2022 Bell Canada. All rights reserved.
  * ================================================================================
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -188,6 +188,7 @@ public class Apex2JsonEventConverter implements ApexEventProtocolConverter {
         jsonObject.addProperty(ApexEvent.NAMESPACE_HEADER_FIELD, apexEvent.getNameSpace());
         jsonObject.addProperty(ApexEvent.SOURCE_HEADER_FIELD, apexEvent.getSource());
         jsonObject.addProperty(ApexEvent.TARGET_HEADER_FIELD, apexEvent.getTarget());
+        jsonObject.addProperty(ApexEvent.TOSCA_POLICY_STATE_HEADER_FIELD, apexEvent.getToscaPolicyState());
 
         if (apexEvent.getExceptionMessage() != null) {
             jsonObject.addProperty(ApexEvent.EXCEPTION_MESSAGE_HEADER_FIELD, apexEvent.getExceptionMessage());
@@ -416,8 +417,9 @@ public class Apex2JsonEventConverter implements ApexEventProtocolConverter {
         final String eventNamespace = getHeaderNamespace(jsonObject, eventName, eventDefinition);
         final String eventSource = getHeaderSource(jsonObject, eventDefinition);
         final String eventTarget = getHeaderTarget(jsonObject, eventDefinition);
+        final String eventStatus = getHeaderToscaPolicyState(jsonObject, eventDefinition);
 
-        return new ApexEvent(eventName, eventVersion, eventNamespace, eventSource, eventTarget);
+        return new ApexEvent(eventName, eventVersion, eventNamespace, eventSource, eventTarget, eventStatus);
     }
 
     /**
@@ -521,6 +523,23 @@ public class Apex2JsonEventConverter implements ApexEventProtocolConverter {
     }
 
     /**
+     * Determine the status field of the event header.
+     *
+     * @param jsonObject the event in JSON format
+     * @param eventDefinition the definition of the event structure
+     * @return the event toscaPolicyState
+     */
+    private String getHeaderToscaPolicyState(final JsonObject jsonObject, final AxEvent eventDefinition) {
+        // For toscaPolicyState, use defined value from model only if value is not found on the incoming event
+        var toscaPolicyState = getJsonStringField(jsonObject, ApexEvent.TOSCA_POLICY_STATE_HEADER_FIELD,
+                jsonPars.getToscaPolicyStateAlias(), null, false);
+        if (toscaPolicyState == null) {
+            toscaPolicyState = eventDefinition.getToscaPolicyState();
+        }
+        return toscaPolicyState;
+    }
+
+    /**
      * This method gets an event string field from a JSON object.
      *
      * @param jsonObject the JSON object containing the JSON representation of the incoming event
@@ -609,4 +628,4 @@ public class Apex2JsonEventConverter implements ApexEventProtocolConverter {
         // check for the field
         return jsonObject.has(fieldName);
     }
-}
+}
\ No newline at end of file
diff --git a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/JsonEventProtocolParameters.java b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/JsonEventProtocolParameters.java
index 51e9b6d40..397a56e78 100644
--- a/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/JsonEventProtocolParameters.java
+++ b/services/services-engine/src/main/java/org/onap/policy/apex/service/engine/event/impl/jsonprotocolplugin/JsonEventProtocolParameters.java
@@ -2,6 +2,7 @@
  * ============LICENSE_START=======================================================
  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
  *  Modifications Copyright (C) 2021 AT&T Intellectual Property. All rights reserved.
+ *  Modifications Copyright (C) 2022 Bell Canada. All rights reserved.
  * ================================================================================
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,11 +62,12 @@ public class JsonEventProtocolParameters extends EventProtocolTextCharDelimitedP
 
     // Aliases for Apex event header fields
     // @formatter:off
-    private String nameAlias      = null;
-    private String versionAlias   = null;
-    private String nameSpaceAlias = null;
-    private String sourceAlias    = null;
-    private String targetAlias    = null;
+    private String nameAlias             = null;
+    private String versionAlias          = null;
+    private String nameSpaceAlias        = null;
+    private String sourceAlias           = null;
+    private String targetAlias           = null;
+    private String toscaPolicyStateAlias = null;
     // @formatter:on
 
     // Flag indicating POJO decoding and encoding and parameter indicating the name of the Pojo field
@@ -104,4 +106,4 @@ public class JsonEventProtocolParameters extends EventProtocolTextCharDelimitedP
     public String getName() {
         return this.getLabel();
     }
-}
+}
\ No newline at end of file