de.aristaflow.adept2.model.processmodel

Interface ChangePrimitives

All Known Subinterfaces:

ChangeableInstance, ChangeableTemplate

public interface ChangePrimitives

The ProcessChangePrimitive interface provides all basic functions for changing a process (template or instance). These primitive functions do not care about the graph being valid and might leave it invalid. Their purpose is to provide all basic needs for a higher level set of change operations.

If the following descriptions refer to a "process", it is either a Template or an Instance. TODO describe change transactions; usage of topo-IDs, branchIDs, splitNodeIDs, correspondingBIDs within a transaction is not allowed / possible. TODO describe the different internal behaviour of the primitives concerning changes on template and instance level. ########## TODO Add a generic description like the following If this method is called in the context of an instance specific change, the changed attribute (including at least the id of the data element) is stored in the delta layer. In the context of a process type change (Template) - in addition to storing the changed attribute in the delta layer - the attribute specified by dataElementProperty is overwritten by the changed attribute value included in the dataElement object, i.e the change is materialised (see TWiki "Flexibilitaet" for further detail). ########### While performing changes it may not be relied on the topological sorting. This applies to internal functions of template as well as functions using the topological sorting. Depending on the implementation of the processmodel the described situation can be pointed out by setting a special "topSortUsable" flag at the beginning of a change transaction which is reset at the end of the transaction by endTransaction() .

Note: TODO This part needs further description concerning pre-conditions and effects of the functions! Furthermore its important to describe the differences between the implementation of the change primitives for templates (direct materialisation and delta layer)and instances (only delta layer).

Method Summary

Modifier and Type	Method and Description
DataEdge	addDataEdge(int node, int dataElement, DataEdge dataEdge) Use this method to connect a data element to a node which does not have an assigned activity yet.
DataEdge	addDataEdge(int node, int connector, int dataElement, DataEdge dataEdge) This method is called when the node has an assigned activity.
DataElement	addDataElement(DataElement dataElement) Adds a new data element to the process, using the values of the given data element object.
void	addDisabledConnector(int nodeID, int connectorID) Adds the information that a connector (respectively its corresponding parameter) is disabled to the template
Edge	addEdge(int srcNodeID, int destNodeID, Edge edge) Add an edge between the given nodes, using the values of the given edge object (e.g. the edge type).
void	addMovedNode(int node) Adds a moved node as meta-information to a process Note: This method is not necessary for a correct process representation but essential for an efficient schema evolution.
Node	addNode(Node node) Creates a new node in the process, using the data of the given object.
void	endTransaction() Signals the end of a change transaction and corrects the topological sorting.
void	reMapDataElement(int dataElementID, int nodeID, ActivityConstants.AccessType type, java.lang.String parameterName) This method remaps a data element to the given parameter of a node.
void	removeDataEdge(int node, int dataElement, ActivityConstants.AccessType dataEdgeType) Removes the data edge between the given node and data element and of the given access type from the process.
void	removeDataElement(int dataElementID) Removes a data element from a process, without caring about existing data accesses from nodes.
void	removeDisabledConnector(int nodeID, int connectorID) Removes the information that a connector (respectively its corresponding parameter) is disabled
void	removeEdge(int srcNodeID, int destNodeID, ProcessConstants.EdgeType edgeType) Removes the edge of the given type between the given nodes.
void	removeNode(int nodeID) Removes the node with the given ID from the template, without caring about any possibly affected edges.
void	removeUserAttribute(UserAttributeContainer container, java.lang.String name) Removes the User defined Attribute identified by name.
void	setBranchID(int startNodeID, int endNodeID, boolean newIDNecessary, int existingID) Sets the branch ID attribute of the nodes between startNodeID and endNodeID.
void	setCorrespondingBlockNode(int split, int join) Sets the corresponding block node attribute for the split node with ID split to the value given by join.
void	setInputParameters(java.util.Set<ProcessModelParameter> inputParameters) Sets the input parameters of the process.
void	setName(java.lang.String name) Set the name of the process.
void	setNodeType(int nodeID, ProcessConstants.NodeType type) Sets the type of the given node.
void	setOutputParameters(java.util.Set<ProcessModelParameter> outputParameters) Sets the output parameters of the process.
void	setSplitNodeID(int startNodeID, int endNodeID, int splitNodeID) Sets the split node ID attribute of the nodes between startNodeID and endNodeID.
void	setSupervisorAgent(QualifiedAgent supervisorAgent) Set the agent ID of the supervisor of the process.
void	startTransaction() Signals the beginning of a change transaction.
DataEdge	updateDataEdge(int nodeID, int dataElementID, ActivityConstants.AccessType accessType, DataEdge dataEdge, ProcessConstants.DataEdgeProperty... dataEdgeProperties) Updates the data edge attribute given by dataEdgeProperty.
DataElement	updateDataElement(DataElement dataElement, ProcessConstants.DataElementProperty... dataElementProperties) Updates the data element attributes given by dataElementProperties.
Edge	updateEdge(int srcNodeID, int destNodeID, Edge edge, ProcessConstants.EdgeProperty... edgeProperty) Updates the edge which is identified by the given source and destination node IDs and the type of the edge (i.e. stored in the Edge object).
void	updateExecutableBusinessProcess(int nodeID, ExecutableBusinessProcess ebp, ProcessConstants.ExecutableBusinessProcessProperty... ebpProperties) Updates the Executable Business Process of the node with the given ID, using the values of the given EBP object.
Node	updateNode(Node node, ProcessConstants.NodeProperty... nodeProperties) Updates a node object using the data in the given node.
void	updatePluginDataContainer(PluginDataContainer pluginContainer, java.lang.String extensionPointID, java.lang.String pluginDataID, PluginData pluginData) Sets the plug in data for the extension point in the plug in data container.
void	updateUserAttribute(UserAttributeContainer container, java.lang.String name, java.lang.String value) Sets the value of the user defined attribute identified by name to value.

Method Detail

startTransaction

void startTransaction()

Signals the beginning of a change transaction. See ChangePrimitives for further information.

endTransaction

void endTransaction()

Signals the end of a change transaction and corrects the topological sorting.
After calling this method, the topological sorting, the split node IDs, the corresponding block node IDs and the branch IDs must be valid again.
The topological sorting is corrected within this method; the other IDs (branchID etc) have to be set by the change operations. See ChangePrimitives for further information.

setName

void setName(java.lang.String name)

Set the name of the process.

Parameters:

name - The name of the process.

setSupervisorAgent

void setSupervisorAgent(QualifiedAgent supervisorAgent)

Set the agent ID of the supervisor of the process.

Parameters:

supervisorAgent - The supervisor agent of the process.

setInputParameters

void setInputParameters(java.util.Set<ProcessModelParameter> inputParameters)

Sets the input parameters of the process.

Parameters:

inputParameters - the input parameters

setOutputParameters

void setOutputParameters(java.util.Set<ProcessModelParameter> outputParameters)

Sets the output parameters of the process.

Parameters:

outputParameters - the output parameters

addNode

Node addNode(Node node)

Creates a new node in the process, using the data of the given object. The parameter is just a container of the node data. The object itself will be thrown away after copying its data to the new Node. The newly created node object, including its system generated ID will be returned. The following node properties will be copied from the given object:

• NAME
• EXECUTABLE_BUSINESS_PROCESS
• USER_ATTRIBUTE
• DESCRIPTION
• STAFF_ASSIGNMENT_RULE

Other attributes will be discarded, since they either must be set using other change primitives, or are set implicitly. The property EXECUTABLE_BUSINESS_PROCESS may be null. If it is set, addNode will implicitly create connectors and map them to parameter names. The values for the property NAME must not be null. If the value of the property USER_ATTRIBUTE is null, it is assumed that no user attributes exist. TODO describe required steps which will be done by addNode to keep the delta layer automatically purged.

Parameters:

node - The data for the new node.

Returns:

The newly created node as object.

updateNode

Node updateNode(Node node,
                ProcessConstants.NodeProperty... nodeProperties)

Updates a node object using the data in the given node. The given node is just used as a temporary container for the new values. The properties specify which attributes of the node will be updated. The following properties may be updated from the given object:

• NAME
• DESCRIPTION
• STAFF_ASSIGNMENT_RULE
• EXECUTABLE_BUSINESS_PROCESS (and implicitly CONNECTOR_PARAMETER_MAPPING)
• SYSTEM_READ_PARAMS
• SYSTEM_WRITE_PARAMS

Removing the ExecutableBusinessProcsess from a node:
If EXECUTABLE_BUSINESS_PROCESS is set in the parameter nodeProperties and getExecutableBusinessProcess() of the given node returns null, the EBP and the parameter/data-connector mapping is removed from the node as well as all data-connectors which are not connected (i.e marked as disabled or connect later) with a data edge.
Setting a new ExecutableBusinessProcsess to a node:
If the property EXECUTABLE_BUSINESS_PROCESS is set, and the attribute returns a value, the returned ExecutableBusinessProcess will be used as a new EBP. This means that the old EBP is removed (like described above), and afterwards added. Changing attributes of the ExecutableBusinessProcsess of a node:
Please use #updateExecutableBusinessProcess(int, ExecutableBusinessProcess, ExecutableBusinessProcessProperty[]).
Note: The declaration of CONNECTOR_PARAMETER_MAPPING in nodeProperties is senseless because the data parameter mapping is always changed if the ebp is changed. Therefore calling the method with the argument CONNECTOR_PARAMETER_MAPPING will produce an exception. In turn to that calling the method with EXECUTABLE_BUSINESS_PROCESS forces the user to store a correct connector mapping in the given node object.

Parameters:

node - A temporary node object, containing the new values.

nodeProperties - Possible values of NodeProperty are described above.

Returns:

The updated node object from the process.

removeNode

void removeNode(int nodeID)

Removes the node with the given ID from the template, without caring about any possibly affected edges. Ensures that all node attributes (including corresponding block node, connectors, etc.) are deleted.

Parameters:

nodeID - The ID of the node to be removed.

setNodeType

void setNodeType(int nodeID,
                 ProcessConstants.NodeType type)

Sets the type of the given node. The type characterises the functionality of a node. It can be one of NT_NORMAL, NT_STARTFLOW, NT_ENDFLOW, NT_AND_SPLIT, NT_AND_JOIN, NT_XOR_SPLIT, NT_XOR_JOIN, NT_STARTLOOP or NT_ENDLOOP. If the node with the given nodeId does not exists an IllegalArgumentException is thrown.

Parameters:

nodeID - The ID of the node to be changed.

type - the type the node is to be set

Throws:

java.lang.IllegalArgumentException - if nodeID does not exist

See Also:

Template.getNodeType(int)

setCorrespondingBlockNode

void setCorrespondingBlockNode(int split,
                               int join)

Sets the corresponding block node attribute for the split node with ID split to the value given by join.

Parameters:

split - ID of the split node.

join - ID of the corresponding join node.

setBranchID

void setBranchID(int startNodeID,
                 int endNodeID,
                 boolean newIDNecessary,
                 int existingID)

Sets the branch ID attribute of the nodes between startNodeID and endNodeID. startNodeID and endNodeID have to be on the same branch, nodes which are inside of blocks on that branch, are not considered. Preconditions: - To be able to navigate through the graph, all edges within the given range must be set. - For efficient navigation, all split-nodes between startNodeID and endNodeID must have their corresponding join-node attribute set. If the parameter newIDNecessary is set to true, a new branch ID will be created and set (in this case, the value of existingID will be ignored). If the parameter newIDNecessary is set to false, the branchID in the parameter existingID will be set. Note: The given branchID must already exist!

Parameters:

startNodeID - The ID of the node which marks the beginning of the sequence.

endNodeID - The ID of the node which marks the end of the sequence.

newIDNecessary - If set to true, a new branch ID will be generated and used.

existingID - If newIDNecessary is false, this ID will be used.

setSplitNodeID

void setSplitNodeID(int startNodeID,
                    int endNodeID,
                    int splitNodeID)

Sets the split node ID attribute of the nodes between startNodeID and endNodeID. startNodeID and endNodeID have to be on the same branch, nodes which are inside of blocks on that branch, are not considered. Preconditions: - To be able to navigate through the graph, all edges within the given range must be set. - For efficient navigation, all split-nodes between startNodeID and endNodeID must have their corresponding join-node attribute set. The ID of the parameter splitNodeID will be set to all of the described nodes. Note: The node of the given ID must exist in the process.

Parameters:

startNodeID - The ID of the node which marks the beginning of the sequence.

endNodeID - The ID of the node which marks the end of the sequence.

splitNodeID - The ID of the split node.

reMapDataElement

void reMapDataElement(int dataElementID,
                      int nodeID,
                      ActivityConstants.AccessType type,
                      java.lang.String parameterName)

This method remaps a data element to the given parameter of a node. Thereby the data edge between the data element and the node with the given data access type must already exist and the parameter must not be marked as disabled (otherwise exceptions are thrown; Note: the initial mapping is created with addDataEdge). Furthermore node must have an assigned ebp at all. The intended task of this method is to change the already existent logical mapping between a data element and a parameter of an ebp. Example of intended usage: Activity a1 assigned to node n1 has to input parameters (ip1, ip2) with the same type. ip1 is connected to connector c1, ip2 is connected to c2. Furthermore data edges between n1 and data element d1 and n1 and data element d2 exists. Now data element d2 should be mapped to ip1 and d1 to ip2. To achieve this the connectorID where d2 is connected with (c2) must be changed from c2 to c1 (d1 analogous). Thereby the "inner" mapping between ip1 and c1 and ip2 and c2 can remain unchanged. Similar scenario if ip2 is unconnected.

Parameters:

dataElementID -

nodeID -

type -

parameterName -

addDisabledConnector

void addDisabledConnector(int nodeID,
                          int connectorID)

Adds the information that a connector (respectively its corresponding parameter) is disabled to the template

Parameters:

nodeID - the id of the node where the connector is to be marked as disabled

connectorID - the connector id

removeDisabledConnector

void removeDisabledConnector(int nodeID,
                             int connectorID)

Removes the information that a connector (respectively its corresponding parameter) is disabled

Parameters:

nodeID - the id of the node where the disabled connector is to be removed

connectorID - the connector id

updateExecutableBusinessProcess

void updateExecutableBusinessProcess(int nodeID,
                                     ExecutableBusinessProcess ebp,
                                     ProcessConstants.ExecutableBusinessProcessProperty... ebpProperties)

Updates the Executable Business Process of the node with the given ID, using the values of the given EBP object. The EBP object is used as an container only. The following attributes / properties of the EBP may be updated (depending on the type of the EBP, i.e. an Activity or an LWP):

• NAME
• STAFF_ASSIGNMENT_RULE (Activity)
• EXECUTABLE_COMPONENT_NAME (Activity)
• CONFIGURATION (Activity)
• TEST_CONFIGURATION (Activity)

The EBP will not be replaced by the given EBP object (use updateNode with property EXECUTABLE_BUSINESS_PROCESS). Updating user attributes is done using updateUserAttribute.

Parameters:

nodeID - The ID of the node, the given EBP belongs to.

ebp - The executable business process.

ebpProperties - The properties of the EBP which should be updated.

See Also:

ExecutableBusinessProcess

addEdge

Edge addEdge(int srcNodeID,
             int destNodeID,
             Edge edge)

Add an edge between the given nodes, using the values of the given edge object (e.g. the edge type). The given edge object is used as a container only and will be thrown away. The implementation of the primitive adds the structural information and the element information. The following attributes / properties of the given edge will be used:

• TYPE
• EDGE_CODE
• USER_ATTRIBUTE

If the value of the USER_ATTRIBUTE property is null, it will be assumed that the edge does not have any user attribute. The value of TYPE must not be null.

Parameters:

srcNodeID - The source node.

destNodeID - The destination node.

edge - The object containing the values for the new edge.

Returns:

The new edge object.

See Also:

ProcessConstants.EdgeType

updateEdge

Edge updateEdge(int srcNodeID,
                int destNodeID,
                Edge edge,
                ProcessConstants.EdgeProperty... edgeProperty)

Updates the edge which is identified by the given source and destination node IDs and the type of the edge (i.e. stored in the Edge object). The edge object is used as a container only and will not be used afterwards. The following properties may be updated:

• EDGE_CODE

Parameters:

srcNodeID - The ID of the node the Edge starts at.

destNodeID - The ID of the node the Edge ends at.

edge - The temporary Edge object conatining the new values.

edgeProperty - The values to be updated.

Returns:

The updated edge object.

removeEdge

void removeEdge(int srcNodeID,
                int destNodeID,
                ProcessConstants.EdgeType edgeType)

Removes the edge of the given type between the given nodes.

Parameters:

srcNodeID - The ID of the source node.

destNodeID - The ID of the destination node.

edgeType - The type of the edge.

addDataElement

DataElement addDataElement(DataElement dataElement)

Adds a new data element to the process, using the values of the given data element object. The given data element will be used as a container only. The following attributes / properties will be used from the given object:

• NAME
• TYPE
• USER_DEFINED_TYPE
• IDENTIFIER
• VIRTUAL
• USER_ATTRIBUTE

The property USER_DEFINED_TYPE will only be used, if the TYPE of the data element is ProcessConstants.AdeptDataType.USERDEFINED. If the value of the USER_ATTRIBUTE property is null, it will be assumed that the data element does not have any user attribute. All other attributes must be set.

Parameters:

dataElement -

Returns:

The newly created data element.

updateDataElement

DataElement updateDataElement(DataElement dataElement,
                              ProcessConstants.DataElementProperty... dataElementProperties)

Updates the data element attributes given by dataElementProperties. The values of the changed attributes are contained in the given dataElement itself. The given data element is used as a container only. The following attributes / properties may be updated:

• NAME
• DESCRIPTION
• TYPE
• USER_DEFINED_TYPE
• IDENTIFIER
• VIRTUAL

Parameters:

dataElement - The name of the data element.

dataElementProperties - A constant describing the changed data element attribute

Returns:

The updated data element object.

removeDataElement

void removeDataElement(int dataElementID)

Removes a data element from a process, without caring about existing data accesses from nodes.

Parameters:

dataElementID - The ID of the data element to remove.

addDataEdge

DataEdge addDataEdge(int node,
                     int connector,
                     int dataElement,
                     DataEdge dataEdge)

This method is called when the node has an assigned activity. The caller has to specify an existing connector. Furthermore the connector must not be marked as disabled, otherwise an IllegalArgumentException is thrown. Note: If a data element should be connected to a connector which is marked as disabled call removeDisabledConnector(node, connector) first to mark the connector as unconnected

Parameters:

node - The node which is accessing the data element.

connector - the connector where the data edge is connected to

dataElement - The data element which will be accessed

dataEdge -

Returns:

the new DataEdge

addDataEdge

DataEdge addDataEdge(int node,
                     int dataElement,
                     DataEdge dataEdge)

Use this method to connect a data element to a node which does not have an assigned activity yet. If it is called for a node which already has an assigned activity, a runtime exception will be thrown. This is due to the fact that there may not be any connectors not connected to a parameter when there is already an activity assigned. To take care about the connector concept, this method implicitly creates a new connector.

Parameters:

node - The node which is accessing the data element.

dataElement - The data element which will be accessed

dataEdge - a temporary data edge object which contains the data edge attributes

Returns:

a data edge object

updateDataEdge

DataEdge updateDataEdge(int nodeID,
                        int dataElementID,
                        ActivityConstants.AccessType accessType,
                        DataEdge dataEdge,
                        ProcessConstants.DataEdgeProperty... dataEdgeProperties)

Updates the data edge attribute given by dataEdgeProperty. The values of the changed attributes are contained in the given dataEdge itself. The following attributes / properties are changeable:

• OPTIONAL
• VIRTUAL

Parameters:

nodeID - The ID of the node which is accessing the dataElement.

dataElementID - The ID of the DataElement which is accessed.

accessType - Whether the DataElement is read or written.

dataEdge - The data edge values which are updated, in a container object.

dataEdgeProperties - The properties which are updated.

Returns:

The updated data edge object.

removeDataEdge

void removeDataEdge(int node,
                    int dataElement,
                    ActivityConstants.AccessType dataEdgeType)

Removes the data edge between the given node and data element and of the given access type from the process. This method implicitly removes a connector, as long as there is no assigned activity, which means, the connector is linked to a parameter.

Parameters:

node - The node which is accessing the data element.

dataElement - The data element which has been accessed

dataEdgeType - the type of access (read or write)

updateUserAttribute

void updateUserAttribute(UserAttributeContainer container,
                         java.lang.String name,
                         java.lang.String value)

Sets the value of the user defined attribute identified by name to value. User attribute containers are e.g. Node, Edge, DataElement, ...

Parameters:

container - The attribute container.

name - The name of the user defined attribute to be modified.

value - The new value.

removeUserAttribute

void removeUserAttribute(UserAttributeContainer container,
                         java.lang.String name)

Removes the User defined Attribute identified by name.

Parameters:

container - The user attribute container.

name - the Name of the User defined attribute to be removed

updatePluginDataContainer

void updatePluginDataContainer(PluginDataContainer pluginContainer,
                               java.lang.String extensionPointID,
                               java.lang.String pluginDataID,
                               PluginData pluginData)

Sets the plug in data for the extension point in the plug in data container. A value of null for pluginData signals that the plug in with the given plug in ID should be removed (remove). If the container already contains the given plug in for the given extension point, the already existent pluginData is replaced with the given pluginData (update). If it does not exist the pluginData is added to the given extension point (add). Plug in data containers are e.g. Node, ...

Parameters:

pluginContainer - the plug in container object where the method is performed on

extensionPointID - the extension point ID where the plug in data should be updated (added/removed) name

pluginDataID - the ID of the plug in data

pluginData - the object which holds the pluginData or null to remove from the extension point.

addMovedNode

void addMovedNode(int node)

Adds a moved node as meta-information to a process Note: This method is not necessary for a correct process representation but essential for an efficient schema evolution. (By storing moved nodes a comparison between two changes becomes much easier). Therefore it has to be called for every node being moved by a changeoperation like moveNodes .

Parameters:

node - The name of the moved node