org.eclipse.stardust.engine.api.runtime

Interface AdministrationService

All Superinterfaces:

org.eclipse.stardust.engine.api.runtime.Service

public interface AdministrationService
extends org.eclipse.stardust.engine.api.runtime.Service

Provides administration services for the CARNOT runtime environment.

The functionality includes the following tasks:

• manage the workflow models (deploy, modify or delete)
• recover the runtime environment or single workflow objects
• terminate running process instances
• manage the life cycle management of CARNOT daemons

An administration service always operates against an audit trail database.

The administration service requires that the user performing tasks has been assigned to the predefined role Administrator.

Version:

$Revision$

Author:

ubirkemeyer

Field Summary

Fields

Modifier and Type	Field and Description
static String	BENCHMARK_DAEMON The predefined benchmark daemon type-
static String	CRITICALITY_DAEMON The predefined criticality daemon type.
static String	EVENT_DAEMON The predefined event daemon type.
static String	SYSTEM_DAEMON The predefined notification daemon type.

Method Summary

Methods

Modifier and Type	Method and Description
ProcessInstance	abortProcessInstance(long oid) Aborts a process instance disregarding any activities which were or are performed by the process instance.
void	cleanupRuntime(boolean keepUsers) Removes all records from the runtime environment making up the audit trail database.
void	cleanupRuntime(boolean keepUsers, boolean keepBO) Removes all records from the runtime environment making up the audit trail database.
void	cleanupRuntimeAndModels() Removes all records from the runtime environment making up the audit trail database.
Department	createDepartment(String id, String name, String description, DepartmentInfo parent, OrganizationInfo organization) Creates a new department.
ProcessInstanceLinkType	createProcessInstanceLinkType(String id, String description) Creates a new type of link between process instances.
DeploymentInfo	deleteModel(long modelOID) Deletes the specified model.
void	deleteProcesses(List<Long> piOids) Deletes process instances from the audit trail.
void	deleteRuntimeArtifact(long oid) Deleted a deployed artifact by oid.
List<DeploymentInfo>	deployModel(List<DeploymentElement> deploymentElements, DeploymentOptions options) Deploys a group of models.
DeploymentInfo	deployModel(String model, int predecessorOID) Deprecated. since 6.0, predecessorOID is ignored.
DeploymentInfo	deployModel(String model, String configuration, int predecessorOID, Date validFrom, Date validTo, String comment, boolean disabled, boolean ignoreWarnings) Deprecated. since 6.0, configuration, validTo and disabled are ignored.
DeployedRuntimeArtifact	deployRuntimeArtifact(RuntimeArtifact runtimeArtifact) Deploys a new artifact with a new oid.
void	flushCaches() Flushes all internal caches, effectively returning the engine to a state just like after it has started.
ActivityInstance	forceCompletion(long activityInstanceOID, Map<String,?> accessPoints) Forces the completion of a non-interactive activity instance.
ActivityInstance	forceSuspendToDefaultPerformer(long activityInstanceOID) Forces an activity instance to be suspended.
List<Daemon>	getAllDaemons(boolean acknowledge) Retrieves a list of all the available daemons.
AuditTrailHealthReport	getAuditTrailHealthReport() Determines key indicators of audit trail health.
AuditTrailHealthReport	getAuditTrailHealthReport(boolean countOnly) Determines key indicators of audit trail health.
ConfigurationVariables	getConfigurationVariables(byte[] model) Retrieves configuration variables from the given model (without Password type).
List<ConfigurationVariables>	getConfigurationVariables(List<String> modelIds) Retrieves merged configuration variables from all models matching the specified modelIds (without Password type).
ConfigurationVariables	getConfigurationVariables(String modelId) Retrieves merged configuration variables from all models matching the specified modelId (without Password type).
ConfigurationVariables	getConfigurationVariables(String modelId, boolean all) Retrieves merged configuration variables from all models matching the specified modelId.
Daemon	getDaemon(String daemonType, boolean acknowledge) Retrieves the specified daemon.
Department	getDepartment(long oid) Retrieves the department with the given oid.
RuntimePermissions	getGlobalPermissions() Retrieves permissions that are globally set.
PasswordRules	getPasswordRules() Returns the password rules.
List<Permission>	getPermissions() Retrieves all permissions the current user has on this service plus the global permissions.
Preferences	getPreferences(PreferenceScope scope, String moduleId, String preferencesId) Retrieves preferences from the given scope.
Map<String,?>	getProfile(ProfileScope scope) Retrieves the profile for the specified scope.
RuntimeArtifact	getRuntimeArtifact(long oid) Retrieves the artifact by the unique oid.
List<ArtifactType>	getSupportedRuntimeArtifactTypes() Returns a list of supported artifact types.
User	getUser() Retrieves information on the current user.
Department	modifyDepartment(long oid, String name, String description) Change the description of a department.
DeploymentInfo	overwriteModel(DeploymentElement deploymentElement, int modelOID, DeploymentOptions options) Overwrites the specified model.
DeploymentInfo	overwriteModel(String model, int modelOID) Deprecated. since 6.0
DeploymentInfo	overwriteModel(String model, String configuration, int modelOID, Date validFrom, Date validTo, String comment, boolean disabled, boolean ignoreWarnings) Deprecated. since 6.0, configuration, validFrom, validTo and disabled are ignored.
DeployedRuntimeArtifact	overwriteRuntimeArtifact(long oid, RuntimeArtifact runtimeArtifact) Overwrites only content of a specified already deployed artifact.
ProcessInstance	recoverProcessInstance(long oid) Recovers the process instance identified by the given OID and all of its subprocess instances, executed in a separate transaction.
void	recoverProcessInstances(List<Long> oids) Recovers the process instances identified by the given list of OIDs and all associated subprocess instances.Executed in a separate transaction.
void	recoverRuntimeEnvironment() Recovers the complete CARNOT runtime environment.Executed in a separate transaction.
void	removeDepartment(long oid) Removes the department having the specified oid, all his children and all user grants associated with the department.
List<ModelReconfigurationInfo>	saveConfigurationVariables(ConfigurationVariables configurationVariables, boolean force) Saves changes to configuration variables values.
void	savePreferences(List<Preferences> preferences) Saves a complete list of preferences to the preference store.
void	savePreferences(Preferences preferences) Saves the changed preferences to the preference store.
void	setGlobalPermissions(RuntimePermissions permissions) Saves the changed Permissions.
void	setPasswordRules(PasswordRules rules) Set password rule.
DeploymentInfo	setPrimaryImplementation(long interfaceModelOid, String processId, String implementationModelId, org.eclipse.stardust.engine.api.runtime.LinkingOptions options) Specifies which implementation alternative (identified by implementationModelId) will be considered the primary implementation of the process interface declared by a specific process definition (identified by interfaceModelOid and processId).
ProcessInstance	setProcessInstancePriority(long oid, int priority) Changes the process instance priority.
ProcessInstance	setProcessInstancePriority(long oid, int priority, boolean propagateToSubProcesses) Changes the process instance priority.
void	setProfile(ProfileScope scope, Map<String,?> profile) Sets the profile for the specified scope.
Daemon	startDaemon(String daemonType, boolean acknowledge) Starts the specified daemon.
ProcessInstance	startProcess(long modelOID, String id, Map<String,?> data, boolean synchronously) Starts a process from a specified model.The startProcess method is executed asynchronously if the synchronously parameter is set to false.However, even if the synchronously parameter is true, the execution of activities is performed in the calling thread only up to the first transition marked with "Fork on Traversal", from that point on execution is asynchronous.
Daemon	stopDaemon(String daemonType, boolean acknowledge) Stops the specified daemon.
void	writeLogEntry(LogType logType, ContextKind contextType, long contextOid, String message, Throwable throwable) Logs an audit trail event of type LogCode.ADMINISTRATION.

Field Detail

EVENT_DAEMON

static final String EVENT_DAEMON

The predefined event daemon type.

See Also:

Constant Field Values

SYSTEM_DAEMON

static final String SYSTEM_DAEMON

The predefined notification daemon type.

See Also:

Constant Field Values

CRITICALITY_DAEMON

static final String CRITICALITY_DAEMON

The predefined criticality daemon type.

See Also:

Constant Field Values

BENCHMARK_DAEMON

static final String BENCHMARK_DAEMON

The predefined benchmark daemon type-

See Also:

Constant Field Values

Method Detail

setPasswordRules

@ExecutionPermission(id=modifyAuditTrail)
void setPasswordRules(PasswordRules rules)

Set password rule.

Parameters:

rules - The rules or null.

getPasswordRules

@ExecutionPermission
PasswordRules getPasswordRules()

Returns the password rules.

Returns:

The password rules or null.

deployModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo deployModel(String model,
                                                                 int predecessorOID)
                           throws DeploymentException

Deprecated. since 6.0, predecessorOID is ignored.

Deploys a new model.

Parameters:

model - the XML representation of the model to deploy.

predecessorOID - the predecessor of the model in the priority list. A value of 0 indicates an absent predecessor.

Returns:

deployment information, including possible errors or warnings.

Throws:

DeploymentException

overwriteModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo overwriteModel(String model,
                                                                    int modelOID)
                              throws DeploymentException

Deprecated. since 6.0

Overwrites the specified model.

Parameters:

model - the XML representation of the model to deploy.

modelOID - the model to be overwritten.

Returns:

deployment information, including possible errors or warnings.

Throws:

DeploymentException

deployModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo deployModel(String model,
                                                                 String configuration,
                                                                 int predecessorOID,
                                                                 Date validFrom,
                                                                 Date validTo,
                                                                 String comment,
                                                                 boolean disabled,
                                                                 boolean ignoreWarnings)
                           throws DeploymentException

Deprecated. since 6.0, configuration, validTo and disabled are ignored.

Deploys a new model.

Parameters:

model - the XML representation of the model to deploy.

configuration - reserved for internal use (can be null).

predecessorOID - the predecessor of the model in the priority list. A value of 0 indicates an absent predecessor.

validFrom - validity start time for the model or null if unlimited.

validTo - validity end time for the model or null if unlimited.

comment - deployment comment.

disabled - specifies if the model should disabled after deployment.

ignoreWarnings - specifies that the deployment should continue if only warnings were issued.

Returns:

deployment information, including possible errors or warnings.

Throws:

DeploymentException

overwriteModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo overwriteModel(String model,
                                                                    String configuration,
                                                                    int modelOID,
                                                                    Date validFrom,
                                                                    Date validTo,
                                                                    String comment,
                                                                    boolean disabled,
                                                                    boolean ignoreWarnings)
                              throws DeploymentException

Deprecated. since 6.0, configuration, validFrom, validTo and disabled are ignored.

Overwrites the specified model.

Parameters:

model - the XML representation of the model to deploy.

configuration - reserved for internal use (can be null).

modelOID - the model to be overwritten.

validFrom - validity start time for the model or null if unlimited.

validTo - validity end time for the model or null if unlimited.

comment - deployment comment.

disabled - specifies if the model should disabled after deployment.

ignoreWarnings - specifies that the deployment should continue if only warnings were issued.

Returns:

deployment information, including possible errors or warnings.

Throws:

DeploymentException

overwriteModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo overwriteModel(DeploymentElement deploymentElement,
                                                                    int modelOID,
                                                                    DeploymentOptions options)
                              throws DeploymentException

Overwrites the specified model.

Parameters:

deploymentElement - The model to be overwritten.

modelOID - The modelOID of the model to be overwritten.

options - The deployment options. Can be null, in which case default deployment options will be used.

Returns:

depoymentInfo Deployment information information, including possible errors or warning

Throws:

DeploymentException - Exception if the overwrite operation could not be performed.

deployModel

@ExecutionPermission(id=deployProcessModel)
List<DeploymentInfo> deployModel(List<DeploymentElement> deploymentElements,
                                                                       DeploymentOptions options)
                                 throws DeploymentException,
                                        org.eclipse.stardust.common.error.ConcurrencyException

Deploys a group of models. The deployment operation is transactional, that means either all models in the group are deployed or none of them. Model references will be resolved first within the group, and only if there is no corresponding model in the group the already deployed models will be considered. Note: It is possible to deploy an empty set of models. This will not necessarily mean that audit trail is not being changed. If the PredefinedModel is not already present in audit trail this means it will be deployed in any case.

Parameters:

deploymentElements - The models to be deployed. Each model in the set must have a unique ID.

options - The deployment options. Can be null, in which case default deployment options will be used.

Returns:

Deployment information, including possible errors or warnings, one DeploymentInfo per DeploymentElement.

Throws:

DeploymentException - if the deployment operation could not be performed.

org.eclipse.stardust.common.error.InvalidArgumentException - if the deploymentElements argument is null.

org.eclipse.stardust.common.error.ConcurrencyException - if the multiple transactions trying to deploy models at the same time.

setPrimaryImplementation

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo setPrimaryImplementation(long interfaceModelOid,
                                                                              String processId,
                                                                              String implementationModelId,
                                                                              org.eclipse.stardust.engine.api.runtime.LinkingOptions options)
                                        throws DeploymentException

Specifies which implementation alternative (identified by implementationModelId) will be considered the primary implementation of the process interface declared by a specific process definition (identified by interfaceModelOid and processId).

Precondition:

• There needs to be at least one model having the ID implementingModelId that contains a process definition which implements the specified process interface.

If implementationModelId is null the default implementation will be reset to the process definition declaring the process interface (the default implementation).

Parameters:

interfaceModelOid - The OID of the model defining the process interface.

processId - The ID of the process definition declaring the process interface.

implementationModelId - The ID of the model providing the implementation.

options - The linking comments.

Returns:

Deployment information, including possible errors or warnings.

Throws:

DeploymentException - if the linking operation could not be performed.

deleteModel

@ExecutionPermission(id=deployProcessModel)
DeploymentInfo deleteModel(long modelOID)
                           throws DeploymentException

Deletes the specified model.

Parameters:

modelOID - the model to be deleted.

Returns:

deployment information, including possible errors or warnings.

Throws:

DeploymentException

deleteProcesses

@ExecutionPermission(id=modifyAuditTrail,
                     changeable=false)
void deleteProcesses(List<Long> piOids)
                     throws IllegalOperationException

Deletes process instances from the audit trail.

Only terminated root process instance can be deleted. All subprocess instances started by one of the root process instances to be deleted will be deleted transitively, too.

Parameters:

piOids - A list with OIDs of the root process instance to be deleted.

Throws:

IllegalOperationException - Raised if non-root or non-terminated process instances are to be deleted.

cleanupRuntime

@ExecutionPermission(id=modifyAuditTrail)
void cleanupRuntime(boolean keepUsers,
                                                        boolean keepBO)

Removes all records from the runtime environment making up the audit trail database. The tables will still remain in the database.

Parameters:

keepUsers - a flag to specify if the users should be deleted or not.

keepBO - a flag to specify if the BO should be deleted or not.

cleanupRuntime

@ExecutionPermission(id=modifyAuditTrail)
void cleanupRuntime(boolean keepUsers)

Removes all records from the runtime environment making up the audit trail database. The tables will still remain in the database.

Parameters:

keepUsers - a flag to specify if the users should be deleted or not.

cleanupRuntimeAndModels

@ExecutionPermission(id=modifyAuditTrail)
void cleanupRuntimeAndModels()

Removes all records from the runtime environment making up the audit trail database. Additionally empties the model table. The tables will still remain in the database.

setProcessInstancePriority

@ExecutionPermission(id=modifyProcessInstances,
                     scope=processDefinition)
ProcessInstance setProcessInstancePriority(long oid,
                                                                                                           int priority)
                                           throws org.eclipse.stardust.common.error.ObjectNotFoundException

Changes the process instance priority. Equivalent with setProcessInstancePriority(oid, priority, false).

Parameters:

oid - the OID of the process instance the priority should be changed of.

priority - the new priority of the process instance.

Returns:

the process instance that was changed.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process instance with the specified oid.

setProcessInstancePriority

@ExecutionPermission(id=modifyProcessInstances,
                     scope=processDefinition)
ProcessInstance setProcessInstancePriority(long oid,
                                                                                                           int priority,
                                                                                                           boolean propagateToSubProcesses)
                                           throws org.eclipse.stardust.common.error.ObjectNotFoundException

Changes the process instance priority.

Parameters:

oid - the OID of the process instance the priority should be changed of.

priority - the new priority of the process instance.

propagateToSubProcesses - if true, the priority will be propagated to all subprocesses.

Returns:

the process instance that was changed.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process instance with the specified oid.

abortProcessInstance

@ExecutionPermission(id=abortProcessInstances,
                     scope=processDefinition)
ProcessInstance abortProcessInstance(long oid)
                                     throws org.eclipse.stardust.common.error.ObjectNotFoundException,
                                            IllegalOperationException

Aborts a process instance disregarding any activities which were or are performed by the process instance. Regularly the process instance to be aborted will be set to the state ABORTING synchronously. The returned ProcessInstance object will already be in that state. Before returning the ProcessInstance object, a asynchronous abortion task is scheduled for it. If the process instance is not yet inserted in the database but needs to be aborted for some reason ( e.g. by abort process event) then the abort operation is optimized to happen completely synchronously. In that case the returned ProcessInstance will already be in state ABORTED. This method also aborts all super process instances.

State changes:

• Process state before: active, interrupted
• State after: The state of root process, all sub-processes and activities that are not yet completed changes to aborted.

Parameters:

oid - the OID of the process instance to be aborted.

Returns:

the process instance that was aborted.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process instance with the specified oid.

IllegalOperationException - if the oid references a case process instance.

See Also:

WorkflowService.abortActivityInstance(long)

recoverProcessInstance

@ExecutionPermission(id=runRecovery)
ProcessInstance recoverProcessInstance(long oid)
                                       throws org.eclipse.stardust.common.error.ObjectNotFoundException

Recovers the process instance identified by the given OID and all of its subprocess instances, executed in a separate transaction. By default the execution is synchronous. An asynchronous successor attempt to recover the process instance is scheduled only if there is a non fatal error (e.g. locking conflicts) during the first attempt.

This includes crashes during non-interactive application execution and crashes of the CARNOT runtime engine itself.

Parameters:

oid - the OID of the process instance to be recovered.

Returns:

the process instance that was recovered.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process instance with the specified oid.

recoverProcessInstances

@ExecutionPermission(id=runRecovery)
void recoverProcessInstances(List<Long> oids)
                             throws org.eclipse.stardust.common.error.ObjectNotFoundException

Recovers the process instances identified by the given list of OIDs and all associated subprocess instances.Executed in a separate transaction. By default the execution is synchronous. Asynchronous successor attempts to recover the affected process instances are only scheduled if there are non fatal errors (e.g. locking conflicts) during the first attempts.

This includes crashes during non-interactive application execution and crashes of the CARNOT runtime engine itself.

Parameters:

oids - the list of OID of the process instance to be recovered.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process instance for one of the specified oids.

getDaemon

@ExecutionPermission(id=manageDaemons)
Daemon getDaemon(String daemonType,
                                                  boolean acknowledge)
                 throws org.eclipse.stardust.common.error.ObjectNotFoundException

Retrieves the specified daemon. The following daemon types exist:

• mail.trigger for the mail trigger daemon
• timer.trigger for the timer trigger daemon
• event.daemon for the event daemon
• system.daemon for the notification daemon.
• criticality.daemon for the prioritization daemon.
• benchmark.daemon for the benchmark daemon.
• reporting.daemon for the reporting daemon.
• business_calendar.daemon for the business calendar daemon.

Parameters:

daemonType - the type of the daemon.

acknowledge - whether to acknowledge the daemon information

Returns:

daemon information.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no daemon with the specified type.

stopDaemon

@ExecutionPermission(id=manageDaemons)
Daemon stopDaemon(String daemonType,
                                                   boolean acknowledge)
                  throws org.eclipse.stardust.common.error.ObjectNotFoundException

Stops the specified daemon. See getDaemon(String, boolean) for a list of daemon types.The stop daemon operation is inherently asynchronous, regardless of the acknowledge flag. The stop operation only marks the daemon for stopping. The daemon will stop asynchronously at the first opportunity. If the acknowledge parameter is set to true then the method will wait for a predetermined (configurable) amount of time for the asynchronous daemon to confirm the execution of the operation. If acknowledge is false then the method will return immediately, without status updates to the returned object. Otherwise it will wait for the executor thread to confirm the action. The acknowledge flag allows to wait for the executor to confirm the actual stop of the daemon. The status object is not influenced by this flag.

Parameters:

daemonType - the type of the daemon to be stopped.

acknowledge - whether to acknowledge the stop operation.

Returns:

daemon information.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no daemon with the specified type.

startDaemon

@ExecutionPermission(id=manageDaemons)
Daemon startDaemon(String daemonType,
                                                    boolean acknowledge)
                   throws org.eclipse.stardust.common.error.ObjectNotFoundException

Starts the specified daemon. See getDaemon(String, boolean) for a list of daemon types. The start daemon operation is inherently asynchronous, regardless of the acknowledge flag. The start operation schedules a timer for the daemon execution which will be performed asynchronously. If the acknowledge parameter is set to true then the method will wait for a predetermined (configurable) amount of time for the asynchronous daemon to confirm the execution of the operation. If acknowledge is false then the method will return immediately, without status updates to the returned object. Otherwise it will wait for the executor thread to confirm the action. The acknowledge flag allows to wait for the executor to confirm the actual start of the daemon. The status object is not influenced by this flag.

Parameters:

daemonType - the type of the daemon to be started.

acknowledge - whether to acknowledge the start operation

Returns:

daemon information.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no daemon with the specified type.

getAllDaemons

@ExecutionPermission(id=manageDaemons)
List<Daemon> getAllDaemons(boolean acknowledge)
                           throws org.eclipse.stardust.common.error.AccessForbiddenException

Retrieves a list of all the available daemons.

Parameters:

acknowledge - whether to acknowledge the daemon information

Returns:

a list containing Daemon objects.

Throws:

org.eclipse.stardust.common.error.AccessForbiddenException

getAuditTrailHealthReport

@ExecutionPermission(id=readAuditTrailStatistics)
AuditTrailHealthReport getAuditTrailHealthReport()

Determines key indicators of audit trail health.

Returns:

A status report indicating some important indicators of audit trail health.

getAuditTrailHealthReport

@ExecutionPermission(id=readAuditTrailStatistics)
AuditTrailHealthReport getAuditTrailHealthReport(boolean countOnly)

Determines key indicators of audit trail health.

Parameters:

countOnly - Determines if report should include the process instances oids or just the total count of oids. If countOnly is set to true the total count of process instances will be included in report. If countOnly is set to false a list containing the process instances oids will be included in report.

Returns:

A status report indicating some important indicators of audit trail health.

recoverRuntimeEnvironment

@ExecutionPermission(id=runRecovery)
void recoverRuntimeEnvironment()

Recovers the complete CARNOT runtime environment.Executed in a separate transaction. By default the execution is synchronous. Only if there are non fatal errors (e.g. locking conflicts), for the affected process instances, a successor asynchronous attempt to recover is scheduled.

This reanimates dead activity threads from an application server crash. Additionally previously interrupted processes are reanimated.

It is equivalent with recovering all the process instances which are in the states active or interrupted.

startProcess

@ExecutionPermission(id=modifyAuditTrail,
                     changeable=false)
ProcessInstance startProcess(long modelOID,
                                                                           String id,
                                                                           Map<String,?> data,
                                                                           boolean synchronously)
                             throws org.eclipse.stardust.common.error.ObjectNotFoundException

Starts a process from a specified model.The startProcess method is executed asynchronously if the synchronously parameter is set to false.However, even if the synchronously parameter is true, the execution of activities is performed in the calling thread only up to the first transition marked with "Fork on Traversal", from that point on execution is asynchronous.

State changes:

• Process state after: active

Parameters:

modelOID - the model where the process is defined.

id - the ID of the process to start.

data - contains data IDs as keyset and corresponding data values to be set as values.

synchronously - determines whether the process will be started synchronously or asynchronously.

Returns:

the ProcessInstance that was started.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no process with the specified ID in the specified model or if the model does not exist.

forceCompletion

@ExecutionPermission(id=performActivity,
                     changeable=false)
ActivityInstance forceCompletion(long activityInstanceOID,
                                                                              Map<String,?> accessPoints)
                                 throws org.eclipse.stardust.common.error.ConcurrencyException,
                                        org.eclipse.stardust.common.error.ObjectNotFoundException,
                                        IllegalStateChangeException,
                                        org.eclipse.stardust.common.error.InvalidValueException,
                                        org.eclipse.stardust.common.error.AccessForbiddenException,
                                        IllegalOperationException

Forces the completion of a non-interactive activity instance. A map of access points maybe provided. This way this method can mimic precisely the behavior of a normal completion of the activity.

State changes:

• Activity state before: application, suspended, hibernated
• Process state before: active, interrupted
• Activity state after: completed
• Process state after: State does not change.

If the process hierarchy is halted:

• Activity state before: halted
• Process state before: halted
• Activity state after: completed
• Process state after: State does not change.
• Next activity will not be created since process hierarchy is halted.

Parameters:

activityInstanceOID - - the OID of the non-interactive activity to be completed.

accessPoints - - an optional map with access points to perform data mappings, can be null

Returns:

the completed ActivityInstance.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no activity with the specified OID.

org.eclipse.stardust.common.error.ConcurrencyException - if the activity instance is exclusively locked by another thread.

IllegalStateChangeException - if the activity is already completed or aborted.

org.eclipse.stardust.common.error.InvalidValueException - if one of the outData values to be written is invalid, most probably as of a type conflict in case of statically typed data.

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user is not an administrator.

IllegalOperationException - if the activity instance is interactive.

See Also:

forceSuspendToDefaultPerformer(long)

forceSuspendToDefaultPerformer

@ExecutionPermission(id=forceSuspend)
ActivityInstance forceSuspendToDefaultPerformer(long activityInstanceOID)
                                                throws org.eclipse.stardust.common.error.ObjectNotFoundException,
                                                       org.eclipse.stardust.common.error.ConcurrencyException,
                                                       IllegalStateChangeException,
                                                       org.eclipse.stardust.common.error.AccessForbiddenException

Forces an activity instance to be suspended. It will be added to the worklist of the default performer declared for the corresponding activity, and the specified activity instance will be set to SUSPENDED state.

State changes:

• Activity state before: application, suspended, hibernated
• Process state before: active, interrupted
• Activity state after: suspended
• Process state after: State does not change.

If the process hierarchy is halted:

• Activity state before: halted, application
• Process state before: halted
• Activity state after: halted
• Process state after: State does not change.

Parameters:

activityInstanceOID - the OID of the activity to be suspended.

Returns:

the ActivityInstance that was suspended.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no activity instance with the specified OID.

org.eclipse.stardust.common.error.ConcurrencyException - if the activity instance is exclusively locked by another thread.

IllegalStateChangeException - if the activity is already completed or aborted.

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user does not have the required privilege.

See Also:

forceCompletion(long, java.util.Map)

getUser

@ExecutionPermission
User getUser()

Retrieves information on the current user.

Returns:

the current user.

flushCaches

@ExecutionPermission(id=controlProcessEngine)
void flushCaches()

Flushes all internal caches, effectively returning the engine to a state just like after it has started.

getPermissions

@ExecutionPermission
List<Permission> getPermissions()

Retrieves all permissions the current user has on this service plus the global permissions.

Returns:

a list of permission ids.

getProfile

@ExecutionPermission
Map<String,?> getProfile(ProfileScope scope)

Retrieves the profile for the specified scope.

Parameters:

scope -

Returns:

the profile.

setProfile

@ExecutionPermission
void setProfile(ProfileScope scope,
                                  Map<String,?> profile)

Sets the profile for the specified scope.

Parameters:

scope - the scope.

profile - the profile.

writeLogEntry

@ExecutionPermission(id=modifyAuditTrailStatistics)
void writeLogEntry(LogType logType,
                                                                 ContextKind contextType,
                                                                 long contextOid,
                                                                 String message,
                                                                 Throwable throwable)
                   throws org.eclipse.stardust.common.error.ObjectNotFoundException

Logs an audit trail event of type LogCode.ADMINISTRATION.

Parameters:

logType - Set the type of log (info, warn, error etc.). Whereas the Unknown type is mapped to a warning.

contextType - Set the context scope of the event

contextOid - Oid of the runtime object (only used if context type is set to ProcessInstance or ActivityInstance)

message - any message that should be logged

throwable - any exception (or null) that should be appended to the message

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no runtime object with the specified OID

createDepartment

@ExecutionPermission(id=modifyDepartments)
Department createDepartment(String id,
                                                                 String name,
                                                                 String description,
                                                                 DepartmentInfo parent,
                                                                 OrganizationInfo organization)
                            throws DepartmentExistsException,
                                   org.eclipse.stardust.common.error.ObjectNotFoundException,
                                   org.eclipse.stardust.common.error.InvalidArgumentException,
                                   IllegalOperationException

Creates a new department.

Parameters:

id - the id of the department. Must not be null or empty and it must be unique in the parent scope.

name - the name of the department. Must not be null or empty.

description - the description of the department.

parent - the parent scope. Can be null if the department will be a top level department.

organization - the organization to which this department is assigned. Must not be null.

Returns:

the created department.

Throws:

DepartmentExistsException - if a department with the same id already exists in the parent scope.

org.eclipse.stardust.common.error.ObjectNotFoundException - if either the parent or the organization could not be resolved.

org.eclipse.stardust.common.error.InvalidArgumentException -
- if either the id or the name is null or an empty string or
- if the organization is null or
- if the organization does not resolve to an actual organization in the model (i.e. resolves to a role or conditional performer) or
- if the organization is not directly part of the organization to which the parent department is assigned (invalid hierarchy).

IllegalOperationException - - if the user was external authentified

getDepartment

@ExecutionPermission(id=readDepartments,
                     defaults=ALL)
Department getDepartment(long oid)
                         throws org.eclipse.stardust.common.error.ObjectNotFoundException

Retrieves the department with the given oid.

Parameters:

oid - the unique identifier of the department.

Returns:

the modified department.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no department with the specified oid.

modifyDepartment

@ExecutionPermission(id=modifyDepartments)
Department modifyDepartment(long oid,
                                                                 String name,
                                                                 String description)
                            throws org.eclipse.stardust.common.error.ObjectNotFoundException,
                                   org.eclipse.stardust.common.error.InvalidArgumentException,
                                   IllegalOperationException

Change the description of a department.

Parameters:

oid - the unique identifier of the department.

name - the new name of the department.

description - the new description.

Returns:

the modified department.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no department with the specified oid.

org.eclipse.stardust.common.error.InvalidArgumentException - if the name is null or an empty string

IllegalOperationException - - if the user was external authentified

removeDepartment

@ExecutionPermission(id=modifyDepartments)
void removeDepartment(long oid)
                      throws org.eclipse.stardust.common.error.ObjectNotFoundException,
                             org.eclipse.stardust.common.error.InvalidArgumentException,
                             IllegalOperationException

Removes the department having the specified oid, all his children and all user grants associated with the department.

Parameters:

oid - the unique identifier of the department.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no department with the specified oid.

org.eclipse.stardust.common.error.InvalidArgumentException - if there are work items currently associated with the department or any child of the department.

IllegalOperationException - - if the user was external authentified

getPreferences

@ExecutionPermission
Preferences getPreferences(PreferenceScope scope,
                                             String moduleId,
                                             String preferencesId)

Retrieves preferences from the given scope.

Parameters:

scope - the scope from which the preferences are to be retrieved from

moduleId - the moduleId of the preferences

preferencesId - the id of the preferences

Returns:

a preferences object.

Throws:

org.eclipse.stardust.common.error.PublicException - if scope is null.

savePreferences

@ExecutionPermission(id=saveOwnUserScopePreferences,
                     defaults=ALL)
void savePreferences(Preferences preferences)
                     throws org.eclipse.stardust.common.error.AccessForbiddenException

Saves the changed preferences to the preference store.

Parameters:

preferences - an preferences object to be saved.

Throws:

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user does not have the required privilege.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences is null.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences property preferences is null.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences property moduleId is null or empty.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences property preferencesId is null or empty.

savePreferences

@ExecutionPermission(id=saveOwnUserScopePreferences,
                     defaults=ALL)
void savePreferences(List<Preferences> preferences)
                     throws org.eclipse.stardust.common.error.AccessForbiddenException

Saves a complete list of preferences to the preference store.

Parameters:

preferences - a list of preferences to be saved.

Throws:

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user does not have the required privilege.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences is null.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences property moduleId is null or empty.

org.eclipse.stardust.common.error.InvalidArgumentException - if preferences property preferencesId is null or empty.

getConfigurationVariables

@ExecutionPermission
ConfigurationVariables getConfigurationVariables(String modelId)

Retrieves merged configuration variables from all models matching the specified modelId (without Password type). The contained descriptions and default values are taken from the newest model version the configuration variable exists in.

Parameters:

modelId - The modelId of the model(s) to retrieve the configuration variables from.

Returns:

A ConfigurationVariables object containing the merged configuration variables from all model versions.

Throws:

org.eclipse.stardust.common.error.InvalidArgumentException - if modelId is null or empty.

getConfigurationVariables

@ExecutionPermission
ConfigurationVariables getConfigurationVariables(String modelId,
                                                                   boolean all)

Retrieves merged configuration variables from all models matching the specified modelId. The contained descriptions and default values are taken from the newest model version the configuration variable exists in.

Parameters:

modelId - The modelId of the model(s) to retrieve the configuration variables from.

all - Indicates if to fetch all configuration variables, including Password type.

Returns:

A ConfigurationVariables object containing the merged configuration variables from all model versions.

Throws:

org.eclipse.stardust.common.error.InvalidArgumentException - if modelId is null or empty.

getConfigurationVariables

@ExecutionPermission
List<ConfigurationVariables> getConfigurationVariables(List<String> modelIds)

Retrieves merged configuration variables from all models matching the specified modelIds (without Password type). The contained descriptions and default values are taken from the newest model version the configuration variable exists in.

Parameters:

modelIds - The modelId of the model(s) to retrieve the configuration variables from.

Returns:

A List of ConfigurationVariables objects containing the merged configuration variables from all model versions.

Throws:

org.eclipse.stardust.common.error.InvalidArgumentException - if modelIds is null or contains an modelId which is null or empty.

getConfigurationVariables

@ExecutionPermission
ConfigurationVariables getConfigurationVariables(byte[] model)

Retrieves configuration variables from the given model (without Password type).

Parameters:

model - The model xml representation in byte array form.

Returns:

A ConfigurationVariables object containing only the configuration variables from the given model.

Throws:

org.eclipse.stardust.common.error.InvalidArgumentException - if model is null.

saveConfigurationVariables

@ExecutionPermission(id=saveOwnPartitionScopePreferences)
List<ModelReconfigurationInfo> saveConfigurationVariables(ConfigurationVariables configurationVariables,
                                                                                                              boolean force)
                                                          throws org.eclipse.stardust.common.error.AccessForbiddenException

Saves changes to configuration variables values.

Parameters:

configurationVariables - The configuration variables containing changed values.

force - Option to ignore validation warnings.

Returns:

model reconfiguration information, including possible errors or warnings.

Throws:

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user does not have the required privilege.

org.eclipse.stardust.common.error.InvalidArgumentException - if configurationVariables is null.

getGlobalPermissions

@ExecutionPermission
RuntimePermissions getGlobalPermissions()

Retrieves permissions that are globally set. For example permissions concerning model deployment, preference saving, modifying AuditTrail, managing deamons ect.

Returns:

the currently set Permissions

setGlobalPermissions

@ExecutionPermission(id=saveOwnPartitionScopePreferences)
void setGlobalPermissions(RuntimePermissions permissions)
                          throws org.eclipse.stardust.common.error.AccessForbiddenException

Saves the changed Permissions. Use getGlobalPermissions to retrieve currently valid global permissions first. Permissions with null or empty lists set as grants will be reset to their internal default. Changed grants are validated against the currently active model for existing model participants.

Parameters:

permissions - the modified permissions

Throws:

org.eclipse.stardust.common.error.AccessForbiddenException - if the current user does not have the required privilege.

org.eclipse.stardust.common.error.InvalidArgumentException - if permissions is null.

org.eclipse.stardust.common.error.ValidationException - if changed grants are not valid in the active model.

deployRuntimeArtifact

@ExecutionPermission(id=deployRuntimeArtifact)
DeployedRuntimeArtifact deployRuntimeArtifact(RuntimeArtifact runtimeArtifact)

Deploys a new artifact with a new oid.

If an artifact with the same validFrom date already exists, the newly deployed artifact takes priority when querying for active artifacts.

Parameters:

runtimeArtifact - The new artifact.

Returns:

The deployed artifact including an assigned oid.

overwriteRuntimeArtifact

@ExecutionPermission(id=deployRuntimeArtifact)
DeployedRuntimeArtifact overwriteRuntimeArtifact(long oid,
                                                                                          RuntimeArtifact runtimeArtifact)
                                                 throws org.eclipse.stardust.common.error.ObjectNotFoundException

Overwrites only content of a specified already deployed artifact. Other fields cannot be changed.

Parameters:

oid - The oid of the artifact.

runtimeArtifact - The new artifact.

Returns:

The updated artifact.

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no runtime artifact with the specified oid.

deleteRuntimeArtifact

@ExecutionPermission(id=deployRuntimeArtifact)
void deleteRuntimeArtifact(long oid)
                           throws org.eclipse.stardust.common.error.ObjectNotFoundException

Deleted a deployed artifact by oid.

Parameters:

oid - The oid of the artifact

Throws:

org.eclipse.stardust.common.error.ObjectNotFoundException - if there is no runtime artifact with the specified oid.

getRuntimeArtifact

@ExecutionPermission(id=readRuntimeArtifact,
                     defaults=ALL)
RuntimeArtifact getRuntimeArtifact(long oid)

Retrieves the artifact by the unique oid.

Parameters:

oid - The oid of the artifact.

Returns:

The artifact or null if it does not exist.

getSupportedRuntimeArtifactTypes

@ExecutionPermission(id=readRuntimeArtifact)
List<ArtifactType> getSupportedRuntimeArtifactTypes()

Returns a list of supported artifact types.

The ArtifactType.getId() is used to identify the ArtifactType for a RuntimeArtifact.

Returns:

The supported artifact types.

createProcessInstanceLinkType

@ExecutionPermission(id=modifyAuditTrail)
ProcessInstanceLinkType createProcessInstanceLinkType(String id,
                                                                                          String description)

Creates a new type of link between process instances.

Parameters:

id - the id of the link type.

description - the description of the link type.

Returns:

the newly created process instance link type.

Throws:

org.eclipse.stardust.common.error.ObjectExistsException - if another link type with the same id already exists.