8. void deprime(UUID compositionId) throws PfModelException;
9. void handleRestartComposition(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList, AcTypeState state) throws PfModelException;
10. void handleRestartInstance(UUID automationCompositionId, 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;
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.
1. void updateAutomationCompositionElementState(UUID automationCompositionId, UUID elementId, DeployState deployState, LockState lockState, StateChangeResult stateChangeResult, String message);
2. Map<UUID, AutomationComposition> getAutomationCompositions();
- 3. void sendAcElementInfo(UUID automationCompositionId, UUID elementId, String useState, String operationalState, Map<String, Object> outProperties);
- 4. void updateCompositionState(UUID compositionId, AcTypeState state, StateChangeResult stateChangeResult, String message);
+ 3. AutomationComposition getAutomationComposition(UUID automationCompositionId);
+ 4. AutomationCompositionElement getAutomationCompositionElement(UUID automationCompositionId, UUID elementId);
+ 5. Map<UUID, Map<ToscaConceptIdentifier, AutomationCompositionElementDefinition>> getAcElementsDefinitions();
+ 6. Map<ToscaConceptIdentifier, AutomationCompositionElementDefinition> getAcElementsDefinitions(UUID compositionId);
+ 7. AutomationCompositionElementDefinition getAcElementDefinition(UUID compositionId, ToscaConceptIdentifier elementId);
+ 8. void sendAcDefinitionInfo(UUID compositionId, ToscaConceptIdentifier elementId, Map<String, Object> outProperties);
+ 9. void updateCompositionState(UUID compositionId, AcTypeState state, StateChangeResult stateChangeResult, String message);
+ 10. void sendAcElementInfo(UUID automationCompositionId, UUID elementId, String useState, String operationalState, Map<String, Object> outProperties);
+
+In/Out composition Properties
+-----------------------------
+The 'Common Properties' could be created or updated by ACM-runtime.
+Participants will receive that Properties during priming events.
+
+.. code-block:: java
+
+ @Override
+ public void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException {
+ for (var acElementDefinition : elementDefinitionList) {
+ var inProperties = acElementDefinition.getAutomationCompositionElementToscaNodeTemplate().getProperties();
+ .......
+ }
+ .......
+ }
+
+The 'Common Properties' could be fetched during depriming events.
+
+.. code-block:: java
+
+ @Override
+ public void deprime(UUID compositionId) throws PfModelException {
+ var elementDefinitionList = intermediaryApi.getAcElementsDefinitions(compositionId);
+ for (var acElementDefinition : elementDefinitionList.values()) {
+ var inProperties = acElementDefinition.getAutomationCompositionElementToscaNodeTemplate().getProperties();
+ .......
+ }
+ .......
+ }
+
+The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
+The participant can trigger this event using the method sendAcDefinitionInfo.
+
+Is allowed to the participant to read all In/Out Properties of all compositions handled by the participant using the method getAcElementsDefinitions.
+The following code is an example how to update the property 'myProperty' and send to ACM-runtime:
+
+.. code-block:: java
+
+ var acElement = intermediaryApi.getAcElementDefinition(compositionId, elementId);
+ var outProperties = acElement.getOutProperties();
+ outProperties.put("myProperty", myProperty);
+ intermediaryApi.sendAcDefinitionInfo(compositionId, elementId, outProperties);
+
+In/Out instance Properties
+--------------------------
+ The 'In/Out Properties' are stored into the instance elements, so each element has its own In/Out Properties.
-In/Out Properties
------------------
The 'In Properties' could be created or updated by ACM-runtime. Participants will receive that Properties during deploy and update events.
The 'Out Properties' could be created or updated by participants. ACM-runtime will receive that Properties during ParticipantStatus event.
- The participant can trigger this event using the method sendAcElementInfo.
- The 'useState' and 'operationalState' can be used as well.
+ The participant can trigger this event using the method sendAcElementInfo. The 'useState' and 'operationalState' can be used as well.
+ The 'Out Properties' could be **cleaned**:
+
+ * by the participant using the method sendAcElementInfo
+ * by intermediary automatically during deleting of the instance
+ * by an update when the instance is in UNDEPLOYED state (changing the elementId)
+
+ 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 LOCKING/UNLOCKING
+ * during UPDATING/MIGRATING
Is allowed to the participant to read all In/Out Properties and state of all instances handled by the participant using the method getAutomationCompositions.
The following code is an example how to update the property 'myProperty' and send to ACM-runtime:
.. code-block:: java
- var automationCompositions = intermediaryApi.getAutomationCompositions();
- var automationComposition = automationCompositions.get(automationCompositionId);
- var acElement = automationComposition.getElements().get(elementId);
+ var acElement = intermediaryApi.getAutomationCompositionElement(automationCompositionId, elementId);
var outProperties = acElement.getOutProperties();
outProperties.put("myProperty", myProperty);
intermediaryApi.sendAcElementInfo(automationCompositionId, elementId, acElement.getUseState(), acElement.getOperationalState(), outProperties);
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.
}
}
+ @Override
+ public void migrate(UUID automationCompositionId, AcElementDeploy element, UUID compositionTargetId,
+ Map<String, Object> properties) throws PfModelException {
+
+ // TODO migrate process
+
+ if (isMigrateSuccess()) {
+ intermediaryApi.updateAutomationCompositionElementState(automationCompositionId, element.getId(),
+ DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated");
+ } else {
+ intermediaryApi.updateAutomationCompositionElementState(automationCompositionId, element.getId(),
+ DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Migrate failed!");
+ }
+ }
+
@Override
public void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList)
throws PfModelException {
}
+AC Element states in failure scenarios
+--------------------------------------
+
+During the execution of any state change order, there is always a possibility of failures or exceptions that can occur in the participant.
+This can be tackled by the followed approaches.
+
+The participant implementation can handle the exception and revert back the appropriate AC element state, by invoking the
+'updateAutomationCompositionElementState' api from the participant intermediary.
+
+Alternatively, the participant can simply throw a PfModelException from its implementation which will be handled by the participant intermediary.
+The intermediary handles this exception and rolls back the AC element to its previous state with the appropriate stateChange Result.
+Please refer the following table for the state change reversion that happens in the participant intermediary for the AC elements.
+
+================== ==================
+**Error Scenario** **State Reverted**
+================== ==================
+Prime fails Commissoned
+
+Deprime fails Primed
+
+Deploy fails Undeployed
+
+Undeploy fails Deployed
+
+Update fails Deployed
+
+Delete fails Undeployed
+
+Lock fails Unlocked
+
+Unlock fails Locked
+================== ==================
+
+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
Code Review / policy / parent.git / blobdiff