de.aristaflow.adept2.core.datamanager

Interface DataManager

All Superinterfaces:

ADEPT2Service

public interface DataManager
extends ADEPT2Service

The data manager provides access to different interfaces which handle (the values of) data elements and user-defined data types (UDTs) at runtime.

Access to data elements is defined by the ADEPT-metamodel. For every write access the corresponding node (and user) is logged. This allows to provide reading nodes with the valid values. The validity of a data value depends on the position of the reading node relative to the corresponding writing node. For instance, it is only allowed to read a data value written by a successor node and not by a parallel node. For convenient usage a data container is provided which allows access via parameter names.

Since there may also be applications that need to access data elements outside of the process context, there is also an interface for such ProcessUnawareAccess. It is allowed to read the latest values written from inside of the process or the latest value written by another external application. Values written process unaware are stored separately so process aware application are always provided with the data intended by the process modeler.

The DataManager also allows to manage user-defined data types (UDTs) and user-defined functions (UDFs). These are used by the ProcessManager when importing or deleting process templates. The processing of UDFs is done via the interface UDFExecution. This is called by the execution manager or by external components when accessing values of user-defined data type.

The DataManager does not synchronise any access to data elements. This is not necessary since every written value is versioned and only valid for specific readers succeeding the writer. The ADEPT-metamodel ensures that no conflicting access appears, for instance, concurrent reading and writing of the same value is not possible. This also allows for storing temporary and intermediate values by an application. The reader of these values is not started before the writing application has successfully terminated.

To allow for suspending of running applications, the DataManager provides an interface to store and retrieve session/application states via savepoints and to manage these savepoints.

The designated session tokens allow for checking access rights on a coarse level, for instance, to prevent controlling instances at all.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	archiveInstance(SessionToken session, java.util.UUID instanceID) Archives the data of the designated instance to a separate archive.
InstanceDataContainer	createInstanceDataContainer(SessionToken session, Template template) Creates an instance data container for the input (and output) parameters of the designated template.
java.net.URI[]	getDataLogManager(SessionToken session) Gets the log manager responsible for the DataHistory assigned to data manager for logging instance data.
ProcessAwareAccess	getProcessAwareAccess() Gets an instance for accessing values of data elements from a process context, which means, the access (storage and retrieval) is carried out by an entity with valid node id and connector.
ProcessUnawareAccess	getProcessUnawareAccess() Gets an instance for accessing values of data elements from outside a process context, which means, the access (storage and retrieval) is carried out by an entity with no knowledge of a process.
SessionStateManager	getSessionStateManager() Gets an instance for managing session/application states via savepoints.
UDFExecution	getUDFExecution() Gets an instance for executing functions on the values of user-defined data type.
UDTManager	getUDTManagement() Gets a reference to the management functions of user-defined data types (UDTs) (creation, retrieval and removal).
void	instanceChanged(SessionToken session, Instance instance) Notifies the data manager that the designated instance has been changed.
void	instanceChanged(SessionToken session, Instance instance, DataContainer changedDataContainer) Notifies the data manager that the designated instance and also its output parameters have changed.
void	instanceStarted(SessionToken session, ExecutableInstance instance, DataContainer dataContainer) Tells the data manager that an instance has been started with the designated data container (input and output parameters of the instance).
void	instanceTerminated(SessionToken session, ExecutableInstance instance, DataContainer dataContainer) Tells the data manager that an instance has been terminated with the designated data container (input and output parameters of the instance).
DataContainer	retrieveInstanceDataContainer(SessionToken session, Instance instance) Retrieves the instance data container for the designated instance.

Methods inherited from interface de.aristaflow.adept2.base.service.ADEPT2Service

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, init, ping, preShutdown, shutdown, start

Method Detail

instanceStarted

void instanceStarted(SessionToken session,
                     ExecutableInstance instance,
                     DataContainer dataContainer)

Tells the data manager that an instance has been started with the designated data container (input and output parameters of the instance). This allows the data manager on the one hand to create the necessary data structures (type information of data elements), on the other hand it can store the data container of the instance and return it later when the instance has finished. The latter renders an own storage for the execution manager unnecessary.
The instance may not be stored internally! It has to be de-referenced by the data manager (and all its subcomponents) when this method returns.
The provided data container is not checked! The supplier has to ensure that it conforms to the instance. Instances without input and output parameters may provide null as data container.
An instance is only started once, i.e. this method is also only called once for an instance.

Parameters:

session - The session which is used to notify the starting of an instance which is just used for tracking and logging purpose.

instance - The instance that is started. The caller must have an execution lock on this instance.

dataContainer - The data container for the designated instance or null in case the instance does not have input and output parameters.

instanceChanged

void instanceChanged(SessionToken session,
                     Instance instance)

Notifies the data manager that the designated instance has been changed. This is necessary for creating new data elements, removing data elements that have been deleted by the change or incorporating changes to the data elements. The information is retrieved via the InstanceDeltaLayer. This method is usually called by the corresponding ExecutionManager. Be sure to have the change lock on the instance when calling this method!
The instance may not be stored internally! It has to be de-referenced by the data manager (and all its subcomponents) when this method returns.
This method does not support changes in the output parameters of the designated instance (input parameters can never be changed after the instance has been started). Use instanceChanged(SessionToken, Instance, DataContainer) instead.

Parameters:

session - The session which is used to notify changes to a running instance which is just used for tracking and logging purpose.

instance - The instance that has been changed. The caller has to have an appropriate lock.

instanceChanged

void instanceChanged(SessionToken session,
                     Instance instance,
                     DataContainer changedDataContainer)

Notifies the data manager that the designated instance and also its output parameters have changed. This is necessary for creating new data elements, removing data elements that have been deleted by the change or incorporating changes to the data elements. The information is retrieved via the InstanceDeltaLayer. This method is usually called by the corresponding ExecutionManager. Be sure to have the change lock on the instance when calling this method!
The instance may not be stored internally! It has to be de-referenced by the data manager (and all its subcomponents) when this method returns.
The supplied data container needs to reflect the changes made to the output parameters of the designated instance. If the modification of the instance has removed all parameters, null is provided as changedDataContainer just like instanceStarted(SessionToken, ExecutableInstance, DataContainer).

Parameters:

session - The session which is used to notify changes to a running instance which is just used for tracking and logging purpose.

instance - The instance that has been changed. The caller has to have an appropriate lock.

changedDataContainer - The data container for the designated instance in case the container has also changed or null in case the instance does not have input and output parameters any more.

instanceTerminated

void instanceTerminated(SessionToken session,
                        ExecutableInstance instance,
                        DataContainer dataContainer)

Tells the data manager that an instance has been terminated with the designated data container (input and output parameters of the instance). This allows to track the values of the instance parameters as well as to access the output parameter values of the instance at a later time.
The instance may not be stored internally! It has to be de-referenced by the data manager (and all its subcomponents) when this method returns.
The provided data container is not checked! The supplier has to ensure that it conforms to the instance. Instances without input and output parameters may provide null as data container.
An instance is only terminated once, i.e. this method is also only called once for an instance.

Parameters:

session - The session which is used to notify the termination of an instance which is just used for tracking and logging purpose.

instance - The instance that has terminated. The caller must have an execution lock on this instance.

dataContainer - The data container for the designated instance or null in case the instance does not have input and output parameters.

createInstanceDataContainer

InstanceDataContainer createInstanceDataContainer(SessionToken session,
                                                  Template template)

Creates an instance data container for the input (and output) parameters of the designated template. The values of the input parameters can be set and provided to the start of an instance based on the designated template.

Parameters:

session - The session which is used to check for access rights on this method.

template - The template for which to create a data container having the corresponding input and output parameters.

Returns:

An InstanceDataContainer having all input and output parameters of the designated template which allows to set input parameters and retrieve the values of the output parameters.

retrieveInstanceDataContainer

DataContainer retrieveInstanceDataContainer(SessionToken session,
                                            Instance instance)

Retrieves the instance data container for the designated instance.
The instance may not be stored internally! It has to be de-referenced by the data manager (and all its subcomponents) when this method returns.

Parameters:

session - The session which is used to check for access rights on this method.

instance - The instance of which to retrieve the data container. The caller must have an execution lock on this instance.

Returns:

The data container for the designated instance or null if there is no data container for the designated instance. The latter will also apply if the corresponding instance has not been started.

getProcessAwareAccess

ProcessAwareAccess getProcessAwareAccess()

Gets an instance for accessing values of data elements from a process context, which means, the access (storage and retrieval) is carried out by an entity with valid node id and connector.

Returns:

A reference for accessing values of data elements from a process context (valid node id and connector available).

getProcessUnawareAccess

ProcessUnawareAccess getProcessUnawareAccess()

Gets an instance for accessing values of data elements from outside a process context, which means, the access (storage and retrieval) is carried out by an entity with no knowledge of a process. The instance and data element id are evidently needed to specify the data to access.

Returns:

A reference for accessing values of data elements from outside a process context (only instance and data element id available).

getUDTManagement

UDTManager getUDTManagement()

Gets a reference to the management functions of user-defined data types (UDTs) (creation, retrieval and removal).

Returns:

A reference to the manager of user-defined data types this data manager.

getUDFExecution

UDFExecution getUDFExecution()

Gets an instance for executing functions on the values of user-defined data type. A proxy for the value is needed for processing these functions.

Returns:

A reference for execution user-defined functions.

getSessionStateManager

SessionStateManager getSessionStateManager()

Gets an instance for managing session/application states via savepoints. The executing functions on the values of user-defined data type. A proxy for the value is needed for processing these functions.

Returns:

A reference for storing and retrieving application states as well as managing savepoints.

getDataLogManager

java.net.URI[] getDataLogManager(SessionToken session)

Gets the log manager responsible for the DataHistory assigned to data manager for logging instance data.

Parameters:

session - The session which is used to access the data log manager. This is just used as a coarse check for the necessary access rights.

Returns:

The communication protocol dependent URIs identifying the data log manager for the instance data of this DataManager.

archiveInstance

void archiveInstance(SessionToken session,
                     java.util.UUID instanceID)

Archives the data of the designated instance to a separate archive. After this, the corresponding data will be deleted from this data manager. So no more access to any data concerning this instance is allowed after archiving.
Note that this method must only be called for terminated or finally failed instances! This cannot be checked here and therefore has to be ensured by the caller by using the archive methods of the process manager appropriately. Also only the data of the designated instance will be archived, child or parent instances of the designated instance are not considered.

Parameters:

session - The session which is used to check for access rights on this method.

instanceID - The (logical) ID of the instance to archive all data.