and the same is configured for the 'ParticipantIntermediaryParameters' object in the code.
1. participantId - A unique participant UUID that is used by the runtime to identify the participant.
-2. ReportingTimeIntervalMs - Time inertval the participant should report the status/heartbeat to the runtime.
-3. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
- These values should be provided for both source and sink configs. The following example shows the topic parameters set for using DMaap.
+2. ReportingTimeIntervalMs - Time interval the participant should report the status/heartbeat to the runtime.
+3. threadPoolSize - This property defines the size of the ThreadPoll used to execute operations by the participant.
+ The default number is 10, if this property is not defined.
+4. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
+ These values should be provided for both source and sink configs.
+ (**Note**: In order to avoid a connection to Kafka when Unit Tests are running, set topicCommInfrastructure: NOOP in properties file for tests).
+ The following example shows the topic parameters set for using Kafka.
.. code-block:: bash
+ intermediaryParameters:
+ topics:
+ operationTopic: policy-acruntime-participant
+ syncTopic: acm-ppnt-sync
clampAutomationCompositionTopics:
topicSources:
-
- topic: POLICY-ACRUNTIME-PARTICIPANT
+ topic: ${participant.intermediaryParameters.topics.operationTopic}
servers:
- - ${topicServer:localhost}
- topicCommInfrastructure: dmaap
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
+ fetchTimeout: 15000
+ additionalProps:
+ group.id: policy-clamp-ac-name
+ -
+ topic: ${participant.intermediaryParameters.topics.syncTopic}
+ servers:
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
fetchTimeout: 15000
topicSinks:
-
- topic: POLICY-ACRUNTIME-PARTICIPANT
+ topic: ${participant.intermediaryParameters.topics.operationTopic}
servers:
- - ${topicServer:localhost}
- topicCommInfrastructure: dmaap
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
-4. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
+5. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
These are user defined name and version and the same should be defined for the AC elements that are included in the TOSCA based AC definitions.
.. code-block:: bash
typeName: org.onap.policy.clamp.acm.PolicyAutomationCompositionElement
typeVersion: 1.0.0
+Kafka Healthcheck
+-----------------
+
+Optionally is possible to add a Kafka Healthcheck by configuration. That feature is responsible of starting the Kafka configuration.
+If Kafka is not up and Kafka Healthcheck is not enable, Kafka messages configuration will fail.
+This feature check Kafka by an admin connection and if Kafka is up, it will start the Kafka messages configuration,
+but if Kafka is not up yet, it will retry this check later.
+
+Kafka Healthcheck supports the topics check and it could be enabled by configuration (using topicValidation parameter).
+Usually topics are getting created when first message happen, so in that scenario, topicValidation should be set as false.
+In different environment, the two topics will be defined into the Kubernetes chart with specific permissions. So Kafka could be up,
+but the Kafka messages configuration could be fail because the two topics are not get created yet.
+So in that scenario, topicValidation should be set as true, and if topics are not created yet, Healthcheck will retry that check later.
+
+For backward compatibility if Kafka Healthcheck is not configured, it will be disabled and Kafka messages configuration will start as normal.
+
+The following example shows the Kafka Healthcheck configuration.
+
+.. code-block:: bash
+
+ intermediaryParameters:
+ topicValidation: true
+ clampAdminTopics:
+ servers:
+ - ${topicServer:kafka:9092}
+ topicCommInfrastructure: kafka
+ fetchTimeout: 15000
+ topics:
+ operationTopic: policy-acruntime-participant
+ syncTopic: acm-ppnt-sync
+ ........
+
+
Interfaces to Implement
-----------------------
AutomationCompositionElementListener:
Every participant should implement a handler class that implements the AutomationCompositionElementListener interface
from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime
and invoke the handler class implementations for various operations. This class implements the methods for deploying,
- undeploying, locking, unlocking , deleting, updating, migrating, priming, depriming requests that are coming from the ACM-runtime.
+ undeploying, locking, unlocking, deleting, updating, preparing, reviewing, migrating, migrationPrechecking, priming, depriming requests that are coming from the ACM-runtime.
The methods are as follows.
.. code-block:: java
6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
7. void prime(CompositionDto composition) throws PfModelException;
8. void deprime(CompositionDto composition) throws PfModelException;
- 9. void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException;
- 10. void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement, DeployState deployState, LockState lockState) throws PfModelException;
- 11. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+ 9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage) throws PfModelException;
+ 10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+ 11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement, int stage) throws PfModelException;
These method from the interface are implemented independently as per the user requirement. These methods after handling the
appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events.
ParticipantIntermediaryParameters getIntermediaryParameters()
-Abstract class AcElementListenerV1
+
+Abstract class AcElementListenerV4
+----------------------------------
+This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases.
+Any new functionality in the future will be wrapped by this class.
+
+**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
+
+
+Methods: deploy, undeploy, lock, unlock, delete, review
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ===========================
+ **field** **description**
+ ============================== ===========================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment policies and policy types
+ inProperties instance in-properties
+ outProperties instance out-properties
+ ============================== ===========================
+
+Method: update
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ================================================
+ **field** **description**
+ ============================== ================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the update)**
+ outProperties instance out-properties
+ ============================== ================================================
+ instanceElementUpdated:
+ ============================== ======================================
+ **field** **description**
+ ============================== ======================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ ============================== ======================================
+
+Methods: prime, deprime
+ composition:
+ ====================== ===================================================================
+ **field** **description**
+ ====================== ===================================================================
+ compositionId composition definition Id
+ inProperties composition definition in-properties for each definition element
+ outProperties composition definition out-properties for each definition element
+ ====================== ===================================================================
+
+Method: migratePrecheck
+ compositionElement:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ compositionElementTarget:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition target Id
+ elementDefinitionId composition definition target element Id
+ inProperties composition definition target in-properties
+ outProperties composition definition target out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ instanceElement:
+ ============================== ===================================================
+ **field** **description**
+ ============================== ===================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the migration)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ===================================================
+ instanceElementMigrate:
+ ============================== ====================================================
+ **field** **description**
+ ============================== ====================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ====================================================
+
+Method: migrate
+ compositionElement:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ compositionElementTarget:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition target Id
+ elementDefinitionId composition definition target element Id
+ inProperties composition definition target in-properties
+ outProperties composition definition target out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ instanceElement:
+ ============================== ===================================================
+ **field** **description**
+ ============================== ===================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the migration)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ===================================================
+ instanceElementMigrate:
+ ============================== ====================================================
+ **field** **description**
+ ============================== ====================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ====================================================
+ stage:
+ the stage of the migration that the participant has to execute
+
+Method: prepare
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ===========================
+ **field** **description**
+ ============================== ===========================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment policies and policy types
+ inProperties instance in-properties
+ outProperties instance out-properties
+ ============================== ===========================
+ stage:
+ the stage of the prepare that the participant has to execute
+
+
+Abstract class AcElementListenerV3
----------------------------------
-This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version.
+This abstract class is introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 8.0.1 version.
So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class.
+The Abstract class AcElementListenerV3 supports the follow methods.
+
+.. code-block:: java
+
+ 1. void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 2. void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 3. void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 4. void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 5. void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
+ 7. void prime(CompositionDto composition) throws PfModelException;
+ 8. void deprime(CompositionDto composition) throws PfModelException;
+ 9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage) throws PfModelException;
+ 10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+ 11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+
+
+Methods: deploy, undeploy, lock, unlock, delete, review and prepare
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ===========================
+ **field** **description**
+ ============================== ===========================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment policies and policy types
+ inProperties instance in-properties
+ outProperties instance out-properties
+ ============================== ===========================
+
+Method: update
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ================================================
+ **field** **description**
+ ============================== ================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the update)**
+ outProperties instance out-properties
+ ============================== ================================================
+ instanceElementUpdated:
+ ============================== ======================================
+ **field** **description**
+ ============================== ======================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ ============================== ======================================
+
+Methods: prime, deprime
+ composition:
+ ====================== ===================================================================
+ **field** **description**
+ ====================== ===================================================================
+ compositionId composition definition Id
+ inProperties composition definition in-properties for each definition element
+ outProperties composition definition out-properties for each definition element
+ ====================== ===================================================================
+
+Method: migratePrecheck
+ compositionElement:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ compositionElementTarget:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition target Id
+ elementDefinitionId composition definition target element Id
+ inProperties composition definition target in-properties
+ outProperties composition definition target out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ instanceElement:
+ ============================== ===================================================
+ **field** **description**
+ ============================== ===================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the migration)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ===================================================
+ instanceElementMigrate:
+ ============================== ====================================================
+ **field** **description**
+ ============================== ====================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ====================================================
+
+Method: migrate
+ compositionElement:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ compositionElementTarget:
+ ====================== =====================================================
+ **field** **description**
+ ====================== =====================================================
+ compositionId composition definition target Id
+ elementDefinitionId composition definition target element Id
+ inProperties composition definition target in-properties
+ outProperties composition definition target out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ====================== =====================================================
+ instanceElement:
+ ============================== ===================================================
+ **field** **description**
+ ============================== ===================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the migration)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ===================================================
+ instanceElementMigrate:
+ ============================== ====================================================
+ **field** **description**
+ ============================== ====================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ state element state: PRESENT, NOT_PRESENT, REMOVED, NEW
+ ============================== ====================================================
+ stage:
+ the stage of the migration that the participant has to execute
+
+
+Abstract class AcElementListenerV2
+----------------------------------
+This abstract class is deprecated and it will be removed in the next release.
+It was introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 8.0.0 version.
+
+The Abstract class AcElementListenerV2 supports the follow methods.
+
+.. code-block:: java
+
+ 1. void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 2. void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 3. void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 4. void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 5. void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException;
+ 7. void prime(CompositionDto composition) throws PfModelException;
+ 8. void deprime(CompositionDto composition) throws PfModelException;
+ 9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+ 10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException;
+ 11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+ 12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException;
+
+**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
+
+
+Methods: deploy, undeploy, lock, unlock, delete, review and prepare
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ===========================
+ **field** **description**
+ ============================== ===========================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment policies and policy types
+ inProperties instance in-properties
+ outProperties instance out-properties
+ ============================== ===========================
+
+Method: update
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ instanceElement:
+ ============================== ================================================
+ **field** **description**
+ ============================== ================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the update)**
+ outProperties instance out-properties
+ ============================== ================================================
+ instanceElementUpdated:
+ ============================== ======================================
+ **field** **description**
+ ============================== ======================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ ============================== ======================================
+
+Methods: prime, deprime
+ composition:
+ ====================== ===================================================================
+ **field** **description**
+ ====================== ===================================================================
+ compositionId composition definition Id
+ inProperties composition definition in-properties for each definition element
+ outProperties composition definition out-properties for each definition element
+ ====================== ===================================================================
+
+Method: migrate and migratePrecheck
+ compositionElement:
+ ====================== =======================================
+ **field** **description**
+ ====================== =======================================
+ compositionId composition definition Id
+ elementDefinitionId composition definition element Id
+ inProperties composition definition in-properties
+ outProperties composition definition out-properties
+ ====================== =======================================
+ compositionElementTarget:
+ ====================== ==============================================
+ **field** **description**
+ ====================== ==============================================
+ compositionId composition definition target Id
+ elementDefinitionId composition definition target element Id
+ inProperties composition definition target in-properties
+ outProperties composition definition target out-properties
+ ====================== ==============================================
+ instanceElement:
+ ============================== ===================================================
+ **field** **description**
+ ============================== ===================================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(before the migration)**
+ outProperties instance out-properties
+ ============================== ===================================================
+ instanceElementMigrate:
+ ============================== ======================================
+ **field** **description**
+ ============================== ======================================
+ instanceId instance id
+ elementId instance element id
+ toscaServiceTemplateFragment
+ inProperties instance in-properties **(updated)**
+ outProperties instance out-properties
+ ============================== ======================================
+
+
+Abstract class AcElementListenerV1
+----------------------------------
+This abstract class is deprecated and it will be removed in the next release.
+It was introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version.
+
The Abstract class AcElementListenerV1 supports the follow methods.
.. code-block:: java
6. void update(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException;
7. void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException;
8. void deprime(UUID compositionId) throws PfModelException;
- 9. void handleRestartComposition(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList, AcTypeState state) throws PfModelException;
- 10. void handleRestartInstance(UUID instanceId, AcElementDeploy element, Map<String, Object> properties, DeployState deployState, LockState lockState) throws PfModelException;
- 11. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;
+ 9. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException;
**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
-Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance.
+Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare.
Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class:
..............................
}
-Abstract class AcElementListenerV2
-----------------------------------
-This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases.
-Any new functionality in the future will be wrapped by this class.
-
-**Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used.
-Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance.
-
APIs to invoke
--------------
1. void updateAutomationCompositionElementState(UUID instanceId, UUID elementId, DeployState deployState, LockState lockState, StateChangeResult stateChangeResult, String message);
2. void updateCompositionState(UUID compositionId, AcTypeState state, StateChangeResult stateChangeResult, String message);
+ 3. void updateAutomationCompositionElementStage(UUID instance, UUID elementId, StateChangeResult stateChangeResult, int stage, String message);
In/Out composition Properties
-----------------------------
The 'Out Properties' will be **not cleaned** by intermediary:
- * during DEPLOIYNG (Out Properties will be take from last changes matching by elementId)
- * during UNDEPLOING
+ * during DEPLOYING (Out Properties will be take from last changes matching by elementId)
+ * during UNDEPLOYING
* during LOCKING/UNLOCKING
- * during UPDATING/MIGRATING
+ * during UPDATING/MIGRATING/PREPARE/REVIEW/MIGRATION_PRECHECKING
Participants will receive the in/out instance Properties related to the element by InstanceElementDto class.
**Note**: In update and migrate Participants will receive the instance Properties before the merge (instanceElement) and the instance Properties merged (instanceElementUpdated / instanceElementMigrate).
-Restart scenario
-----------------
- Restart methods handle the scenario when participant shut down and restart.
- During RESTARTING, compositions and instances will be stored in participant memory with In/Out Properties, 'useState' and 'operationalState'.
- The method handleRestartComposition will be called for each composition and will be present the 'state' at the time the participant shut down.
- The method handleRestartInstance will be called for each instance element and will be present the 'deployState' and the 'lockState' at the time the participant shut down.
-
In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules
can be referred here:
participant:
myparameter: my parameter
intermediaryParameters:
+ topics:
+ operationTopic: policy-acruntime-participant
+ syncTopic: acm-ppnt-sync
reportingTimeIntervalMs: 120000
description: Participant Description
participantId: 101c62b3-8918-41b9-a747-d21eb79c6c90
+ threadPoolSize: 10
clampAutomationCompositionTopics:
topicSources:
- - topic: POLICY-ACRUNTIME-PARTICIPANT
+ - topic: ${participant.intermediaryParameters.topics.operationTopic}
+ servers:
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
+ fetchTimeout: 15000
+ additionalProps:
+ group.id: policy-clamp-my-first-ptn
+ - topic: ${participant.intermediaryParameters.topics.syncTopic}
servers:
- - ${topicServer:localhost}
- topicCommInfrastructure: dmaap
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
fetchTimeout: 15000
topicSinks:
- - topic: POLICY-ACRUNTIME-PARTICIPANT
+ - topic: ${participant.intermediaryParameters.topics.operationTopic}
servers:
- - ${topicServer:localhost}
- topicCommInfrastructure: dmaap
+ - ${topicServer:localhost}:9092
+ topicCommInfrastructure: kafka
participantSupportedElementTypes:
-
typeName: org.onap.policy.clamp.acm.MyFirstAutomationCompositionElement
.. code-block:: java
@Component
- public class AutomationCompositionElementHandler extends AcElementListenerV2 {
+ public class AutomationCompositionElementHandler extends AcElementListenerV3 {
@Override
public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
@Override
public void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement,
- InstanceElementDto instanceElementUpdated) throws PfModelException {
+ InstanceElementDto instanceElementUpdated) throws PfModelException {
// TODO update process
@Override
public void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget,
- InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate)
- throws PfModelException
+ InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage)
+ throws PfModelException
- // TODO migrate process
+ switch (instanceElementMigrate.state()) {
+ case NEW -> // TODO new element scenario
+ case REMOVED -> // TODO element remove scenario
+ default -> // TODO migration process
+ }
if (isMigrateSuccess()) {
- intermediaryApi.updateAutomationCompositionElementState(
- instanceElement.instanceId(), instanceElement.elementId(),
- DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+ if (isStageCompleted()) {
+ intermediaryApi.updateAutomationCompositionElementState(
+ instanceElement.instanceId(), instanceElement.elementId(),
+ DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+ } else {
+ intermediaryApi.updateAutomationCompositionElementStage(
+ instanceElement.instanceId(), instanceElement.elementId(),
+ StateChangeResult.NO_ERROR, nextStage, "stage " + stage + " Migrated");
+ }
} else {
intermediaryApi.updateAutomationCompositionElementState(
instanceElement.instanceId(), instanceElement.elementId(),
}
}
+ @Override
+ public void migratePrecheck(UUID instanceId, UUID elementId) throws PfModelException {
+
+ // TODO migration Precheck process
+
+ intermediaryApi.updateAutomationCompositionElementState(
+ instanceElement.instanceId(), instanceElement.elementId(),
+ DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migration precheck completed");
+ }
+
+ @Override
+ public void prepare(UUID instanceId, UUID elementId) throws PfModelException {
+
+ // TODO prepare process
+
+ intermediaryApi.updateAutomationCompositionElementState(
+ instanceElement.instanceId(), instanceElement.elementId(),
+ DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Prepare completed");
+ }
+
+ @Override
+ public void review(UUID instanceId, UUID elementId) throws PfModelException {
+
+ // TODO review process
+
+ intermediaryApi.updateAutomationCompositionElementState(
+ instanceElement.instanceId(), instanceElement.elementId(),
+ DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Review completed");
+ }
+
@Override
public void prime(CompositionDto composition) throws PfModelException {
}
- @Override
- public void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException {
-
- // TODO restart process
-
- switch (state) {
- case PRIMING -> prime(composition);
- case DEPRIMING -> deprime(composition);
- default -> intermediaryApi
- .updateCompositionState(composition.compositionId(), state, StateChangeResult.NO_ERROR, "Restarted");
- }
- }
-
- @Override
- public void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement,
- DeployState deployState, LockState lockState) throws PfModelException {
-
- // TODO restart process
-
- if (DeployState.DEPLOYING.equals(deployState)) {
- deploy(compositionElement, instanceElement);
- return;
- }
- if (DeployState.UNDEPLOYING.equals(deployState)) {
- undeploy(compositionElement, instanceElement);
- return;
- }
- if (DeployState.UPDATING.equals(deployState)) {
- update(compositionElement, instanceElement, instanceElement);
- return;
- }
- if (DeployState.DELETING.equals(deployState)) {
- delete(compositionElement, instanceElement);
- return;
- }
- if (LockState.LOCKING.equals(lockState)) {
- lock(compositionElement, instanceElement);
- return;
- }
- if (LockState.UNLOCKING.equals(lockState)) {
- unlock(compositionElement, instanceElement);
- return;
- }
- intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
- instanceElement.elementId(), deployState, lockState, StateChangeResult.NO_ERROR, "Restarted");
- }
+Allowed state from the participant perspective
+----------------------------------------------
+
++------------+--------------+---------------------+-------------------------+
+| **Action** | **state** | **stChResult** | **Description** |
++------------+--------------+---------------------+-------------------------+
+| | PRIMED | NO_ERROR | Prime is completed |
++ Prime +--------------+---------------------+-------------------------+
+| | COMMISSIONED | FAILED | Prime is failed |
++------------+--------------+---------------------+-------------------------+
+| | COMMISSIONED | NO_ERROR | Deprime is completed |
++ Deprime +--------------+---------------------+-------------------------+
+| | PRIMED | FAILED | Deprime is failed |
++------------+--------------+---------------------+-------------------------+
+
++------------------+-----------------+---------------+----------------+----------------------------------+
+| **Action** | **deployState** | **lockState** | **stChResult** | **Description** |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | NO_ERROR | Deploy is completed |
++ Deploy +-----------------+---------------+----------------+----------------------------------+
+| | UNDEPLOYED | | FAILED | Deploy is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | UNDEPLOYED | | NO_ERROR | Undeploy is completed |
+| Undeploy +-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | FAILED | Undeploy is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | | LOCKED | NO_ERROR | Lock is completed |
++ Lock +-----------------+---------------+----------------+----------------------------------+
+| | | UNLOCKED | FAILED | Lock is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | | UNLOCKED | NO_ERROR | Unlock is completed |
++ Unlock +-----------------+---------------+----------------+----------------------------------+
+| | | LOCKED | FAILED | Unlock is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | NO_ERROR | Update is completed |
+| Update +-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | FAILED | Update is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | NO_ERROR | Migration is completed |
++ Migrate +-----------------+---------------+----------------+----------------------------------+
+| | DEPLOYED | | FAILED | Migration is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Migrate Precheck | DEPLOYED | | NO_ERROR | Migration-precheck is completed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Prepare | UNDEPLOYED | | NO_ERROR | Prepare is completed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| Review | DEPLOYED | | NO_ERROR | Review is completed |
++------------------+-----------------+---------------+----------------+----------------------------------+
+| | DELETED | | NO_ERROR | Delete is completed |
+| Delete +-----------------+---------------+----------------+----------------------------------+
+| | UNDEPLOYED | | FAILED | Delete is failed |
++------------------+-----------------+---------------+----------------+----------------------------------+
AC Element states in failure scenarios
================== ==================
**Error Scenario** **State Reverted**
================== ==================
-Prime fails Commissoned
+Prime fails Commissioned
Deprime fails Primed
Considering the above mentioned behavior of the participant Intermediary, it is the responsibility of the developer to tackle the
error scenarios in the participant with the suitable approach.
-Tips:
-If the participant tries to undeploy an element which doesn’t exist in the system any more (due to various other external factors),
-it could update the element state to ‘undeployed’ using the Intermediary api.
\ No newline at end of file
+Handle states and failure scenarios from the participant perspective
+--------------------------------------------------------------------
+
+It is important to make distinction between the state of the instance/element flow, and the state of the application/configuration involved.
+A deployed element means that a participant has completed a deploy action, and should not be confused with a deployed application.
+Example with two elements:
+
+1. an instance is deployed, so the two elements are DEPLOYED
+2. user calls undeploy command (ACM-R sets all element as DEPLOYING)
+3. participant executes the first instance element with success and sends UNDEPLOYED state
+4. participant executes the second instance element with fail and sends DEPLOYED state
+5. user calls undeploy command again (ACM-R sets all element as DEPLOYING)
+6. participant does not know that the application related to the first element is already UNDEPLOYED when the flow state is UNDEPLOYING
+
+There are some contexts in a failure scenario that the participant need to know the state of the deployed application.
+From participant side, using "outProperties" it could be possible to handle custom states that better suit whit the context.
+
+Example of a participant that deploy/undeploy applications.
+The following Java code shows how to implement deploy and undeploy that avoid to repeat the action already executed.
+
+.. code-block:: java
+
+ @Override
+ public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
+ throws PfModelException {
+
+ if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) {
+ // deploy process already done
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR,
+ "Already Deployed");
+ return;
+ }
+
+ // deployment process
+ .......................................
+ .......................................
+ // end of the deployment process
+
+ if (isDeploySuccess()) {
+ instanceElement.outProperties().put("state", "DEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed");
+ } else {
+ instanceElement.outProperties().put("state", "UNDEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!");
+ }
+ }
+
+ @Override
+ public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
+ throws PfModelException {
+
+ if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) {
+ // undeploy process already done
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR,
+ "Already Undeployed");
+ return;
+ }
+
+ // undeployment process
+ .......................................
+ .......................................
+ // end of the undeployment process
+
+ if (isUndeploySuccess()) {
+ instanceElement.outProperties().put("state", "UNDEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed");
+ } else {
+ instanceElement.outProperties().put("state", "DEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!");
+ }
+ }
+
+
+Example of a participant that make configurations.
+The following Java code shows how to implement deploy and undeploy that needs a clean up and repeat the action.
+The state of the configuration will saved in outProperties.
+
+.. code-block:: java
+
+ @Override
+ public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException {
+
+ if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) {
+ // clean up deployment
+
+ } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) {
+ // check and clean up
+
+ }
+
+ // deployment process
+ instanceElement.outProperties().put("state", "DEPLOYING");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ .......................................
+ .......................................
+ // end of the deployment process
+
+ if (isDeploySuccess()) {
+ instanceElement.outProperties().put("state", "DEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed");
+ } else {
+ instanceElement.outProperties().put("state", "UNDEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!");
+ }
+ }
+
+ @Override
+ public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement)
+ throws PfModelException {
+
+ if ("UNDEPLOYED".equals(instanceElement.outProperties().get("state"))) {
+ // clean up undeployment
+
+ } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) {
+ // check and clean up
+
+ }
+
+ // undeployment process
+ instanceElement.outProperties().put("state", "UNDEPLOYING");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ .......................................
+ .......................................
+ // end of the undeployment process
+
+ if (isUndeploySuccess()) {
+ instanceElement.outProperties().put("state", "UNDEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed");
+ } else {
+ instanceElement.outProperties().put("state", "DEPLOYED");
+ intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(),
+ null, null, instanceElement.outProperties());
+
+ intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(),
+ instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!");
+ }
+ }
+
+
+*In all suggestions shown before we have used labels as "DEPLOY", "UNDEPLOY", "DEPLOYING", "UNDEPLOYING" but the developer can change them as better suit with the context of the participant.*
+
Code Review / policy / parent.git / blobdiff