de.esoco.process

Class ProcessStep

java.lang.Object

org.obrel.core.RelatedObject

org.obrel.core.SerializableRelatedObject

de.esoco.process.ProcessElement

de.esoco.process.ProcessFragment

de.esoco.process.ProcessStep

All Implemented Interfaces:

java.io.Serializable, org.obrel.core.Relatable

Direct Known Subclasses:

BranchStep, DisposeResource, EntityStep, FunctionStep, PerformStorageQuery, RollbackStep, SubProcessStep, SwitchStep, TransferParam

public abstract class ProcessStep
extends ProcessFragment

Base class for all kinds of process steps. This class is serializable and uses the default serialized form. Subclasses must declare a serialVersionUID field and implement correct serialization of any fields that they define. In general it is recommended that subclasses don't define fields but use relations instead. The types of all relations that shall not be serialized must have the flag RelationTypeModifier.TRANSIENT set. Further information about the serialization of processes can be found in the documentation of class Process.

A process step can be set to be wrapped inside a history group or a transaction by setting one of the flags HistoryManager.HISTORIZED or MetaTypes.TRANSACTIONAL, respectively. The execute() method will then be invoked after a transaction and a history group have been started. History always includes a transaction to combine the writing of the history and persistent changes by the step.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static org.obrel.core.RelationType<java.lang.String>	NEXT_STEP The next step's name

Fields inherited from class de.esoco.process.ProcessElement

MSG_PARAM_NOT_SET

Constructor Summary

Constructors

Constructor and Description
ProcessStep() Default constructor, which must be provided by any subclass.

Method Summary

Modifier and Type	Method and Description
protected void	abort() This method will be invoked on the currently suspended step if the parent process is rolled back.
void	addDisplayParameters(java.util.Collection<? extends org.obrel.core.RelationType<?>> rParams) Overridden to mark structure changes for legacy process interactions.
void	addSubFragment(org.obrel.core.RelationType<java.util.List<org.obrel.core.RelationType<?>>> rFragmentParam, InteractionFragment rSubFragment) Overridden to mark structure changes for legacy process interactions.
protected void	cancel() This method is similar to the rollback() method, but it is invoked if the enclosing interactive process is canceled completely.
protected boolean	canRollback() This method must be overridden by subclasses that support a rollback of their processing.
protected boolean	checkStopProcessExecution() check whether the execution of this process should be stopped.
protected void	cleanup() This method will always be invoked at the end of a process (whether successful or not) for all executed steps.
protected abstract void	execute() Executes the process step.
java.lang.String	getName() Returns the step's name.
protected java.lang.String	getNextStep() Returns the name of the next process step that shall be executed after this one.
Process	getProcess() Returns the process that this fragment is associated with.
ProcessStep	getProcessStep() Implemented to return this instance.
protected void	internalExecute() Internal method to invoke the execute() method.
boolean	isParameterModified(org.obrel.core.RelationType<?> rParam) Checks whether a parameter has been modified by the process during the last interaction cycle.
protected boolean	needsInteraction() Checks whether this step must be interrupted to perform an interaction to query additional data.
protected void	prepareContinuation() This method can be overridden by (interactive) subclasses if an interaction continuation occurs.
protected void	prepareExecution() Prepares the execution of this step in succession of the previous step by invoking prepareParameters() and prepareValues().
protected void	prepareInteraction() Prepares a re-execution of this step during an interaction by invoking the method prepareValues() and resets the interaction parameter.
protected void	prepareNewInteractionParameters(java.util.Collection<? extends org.obrel.core.RelationType<?>> rParams) Prepares new interaction parameters for rendering.
protected void	prepareParameters() This method can be overridden to prepare this step's parameters for execution.
protected void	prepareValues() This method can be overridden to prepare a step's parameter values after their initialization in the method prepareParameters() or to update the values after an interaction occurred.
void	removeParameterModification(ParameterBase<?,?> rParam) Removes the modification markers for a certain process parameter.
void	removeParameterModification(org.obrel.core.RelationType<?> rParamType) Removes the modification markers for a certain parameter relation type.
void	resetParameterModifications() Resets all parameter modification markers for this step.
protected void	resetParameters() Will be invoked by a process on a rollback to reset parameter initializations performed by interactive steps.
protected boolean	resume() This method can be overridden to resume this step after the process had been suspended.
protected void	rollback() Must be implemented by a subclass if it can perform a rollback of a previous execution.
protected void	setNextStep(java.lang.String sNextStepName) Sets the name of the next process step that shall be executed after this one.
protected void	setup() This method must be overridden by subclasses that require initialization.
protected <T> void	throwMissingParameterException(org.obrel.core.RelationType<T> rParamType) Throws a runtime exception that signals a missing process parameter.
java.lang.String	toString()
protected void	validate() Will be invoked to validate the step's parameters after an interaction has occurred.
protected java.util.Map<org.obrel.core.RelationType<?>,java.lang.String>	validateParameters(boolean bOnInteraction) Invokes the validation functions that are stored in the process step relations ProcessRelationTypes.INTERACTION_PARAM_VALIDATIONS and ProcessRelationTypes.PARAM_VALIDATIONS.

Methods inherited from class de.esoco.process.ProcessFragment

addCleanupAction, addLayoutFiller, addPanel, addPanel, addPanelParameters, addProcessStepMessage, addSelectionDependency, addSelectionDependency, addStackPanel, addTabPanel, annotateForEntityQuery, annotateForEntityQuery, annotateParameter, applyDerivedParameter, applyDerivedParameters, applyExtraAttribute, changeDate, checkParameter, clearUIFlag, clearUIFlag, collectDerivedParameter, collectDerivedParameters, deleteParameters, disableElements, disableElements, disableElements, disableMultiSelectionElements, displayHistoryValue, enableAllElements, executeCleanupActions, getAbsoluteFilePath, getAllowedElements, getAllowedValues, getCurrentQuery, getDerivedParameterValue, getFragmentId, getInputMode, getInteractiveInputParameter, getNamedTmpListType, getNamedTmpParameterType, getParameter, getParameterAnnotation, getParameterRelation, getProcessUser, getSelectionIndex, getSubFragment, getSubFragments, getTemporaryListType, getTemporaryListType, getTemporaryParameterId, getTemporaryParameterName, getTemporaryParameterPackage, getTemporaryParameterType, getTemporaryParameterType, getTemporaryParameterType, getTemporarySetType, getUIProperties, getUIProperties, getUIProperty, getUserSetting, getUserSettings, hasFlagParameter, hasParameter, hasUIFlag, hasUserSetting, initChartParameter, initCountChartParameter, initProgressParameter, isInteractiveInput, isPanelParameter, lockEntity, markParameterAsModified, performParameterValidations, prepareDateInput, prepareDownload, prepareDownload, removeAllSubFragments, removeAllUIProperties, removeAllUIProperties, removeCleanupAction, removePanel, removeParameterAnnotation, removeSubFragment, removeSubFragment, removeTemporaryParameterType, removeUIProperties, setAllowedElements, setAllowedValues, setAllowedValues, setDatePeriod, setEnabled, setEnabled, setHtmlSize, setImmediateAction, setImmediateAction, setImmediateAction, setInteractive, setInteractive, setInteractive, setInteractive, setInteractive, setLayout, setParameter, setParameter, setParameterBounds, setProcessStepInfo, setProcessStepMessage, setProgressIndicator, setSelectionDependency, setSelectionDependency, setUIFlag, setUIFlag, setUIProperty, setUIProperty, setUIProperty, setUIProperty, setVisible, setVisible, spawnProcess, storeEntity, unlockEntity

Methods inherited from class de.esoco.process.ProcessElement

addDisplayParameters, addInputParameters, addInputParameters, clearInteractionParameters, continueOnInteraction, getParameterValidations, hasInteractionParameter, markInputParams, markInputParams, params, removeAllParameterValidations, removeInteractionParameters, removeInteractionParameters, removeParameterValidations, removeParameterValidations, setContinueOnInteraction, setMandatory, setParameterNotEmptyValidations, setParameterNotEmptyValidations, setParameterNotNullValidations, setParameterNotNullValidations, setParameterValidation, setParameterValidation, staticParams

Methods inherited from class org.obrel.core.RelatedObject

deleteRelation, get, getRelation, getRelations, notifyRelationListeners, readRelations, relationsEqual, relationsHashCode, relationsString, set, set, transform, writeRelations

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.obrel.core.Relatable

deleteRelation, deleteRelations, getAll, getOption, getRelationCount, getRelations, hasFlag, hasRelation, hasRelations, init, set, set, set, setOption, streamRelations

Field Detail

NEXT_STEP

public static final org.obrel.core.RelationType<java.lang.String> NEXT_STEP

The next step's name

Constructor Detail

ProcessStep

public ProcessStep()

Default constructor, which must be provided by any subclass.

Method Detail

addDisplayParameters

public void addDisplayParameters(java.util.Collection<? extends org.obrel.core.RelationType<?>> rParams)

Overridden to mark structure changes for legacy process interactions.

Overrides:

addDisplayParameters in class ProcessElement

Parameters:

rParams - The parameter types to be displayed

See Also:

ProcessElement.addDisplayParameters(Collection)

addSubFragment

public void addSubFragment(org.obrel.core.RelationType<java.util.List<org.obrel.core.RelationType<?>>> rFragmentParam,
                           InteractionFragment rSubFragment)

Overridden to mark structure changes for legacy process interactions.

Overrides:

addSubFragment in class ProcessFragment

Parameters:

rFragmentParam - The interactive process parameter in which the fragment will be displayed

rSubFragment - The fragment to add

See Also:

ProcessFragment.addSubFragment(RelationType, InteractionFragment)

getName

public final java.lang.String getName()

Returns the step's name.

Returns:

The step's name

getProcess

public final Process getProcess()

Description copied from class: ProcessFragment

Returns the process that this fragment is associated with.

Specified by:

getProcess in class ProcessFragment

Returns:

The process of this fragment

See Also:

ProcessFragment.getProcess()

getProcessStep

public ProcessStep getProcessStep()

Implemented to return this instance.

Specified by:

getProcessStep in class ProcessFragment

Returns:

The process step of this fragment

See Also:

ProcessFragment.getProcessStep()

isParameterModified

public boolean isParameterModified(org.obrel.core.RelationType<?> rParam)

Checks whether a parameter has been modified by the process during the last interaction cycle.

Parameters:

rParam - The parameter to check

Returns:

TRUE if the parameter has been modified

removeParameterModification

public void removeParameterModification(ParameterBase<?,?> rParam)

Removes the modification markers for a certain process parameter.

Parameters:

rParam - The process parameter

removeParameterModification

public void removeParameterModification(org.obrel.core.RelationType<?> rParamType)

Removes the modification markers for a certain parameter relation type.

Parameters:

rParamType - The parameter relation type

resetParameterModifications

public void resetParameterModifications()

Resets all parameter modification markers for this step.

toString

public java.lang.String toString()

Overrides:

toString in class org.obrel.core.RelatedObject

See Also:

Object.toString()

execute

protected abstract void execute()
                         throws java.lang.Exception

Executes the process step. This method must be implemented by subclasses to provide the functionality of the process step. in case of errors The implementation may throw any kind of exception. The Process class will catch any Throwable that is thrown from this method.

Throws:

java.lang.Exception - Any kind of exception may be thrown if executing the step fails

abort

protected void abort()
              throws java.lang.Exception

This method will be invoked on the currently suspended step if the parent process is rolled back. Most step implementations won't need to override this method. It is intended only for special steps that perform complex tasks like the execution of sub-processes. The default implementation does nothing.

Throws:

java.lang.Exception - Any kind of exception can be thrown

cancel

protected void cancel()
               throws java.lang.Exception

This method is similar to the rollback() method, but it is invoked if the enclosing interactive process is canceled completely. Therefore it is not necessary to restore the process parameters in this method. It only needs to be implemented if the process step needs to undo a modification that has been performed on execution and which must not be persistent if the process is canceled. This is an infrequent case because in most cases this will be implemented differently, e.g. by making persistent changes in the final, non-interactive steps of the process.

The default implementation does nothing.

Throws:

java.lang.Exception - Any kind of exception may be thrown if canceling fails

canRollback

protected boolean canRollback()

This method must be overridden by subclasses that support a rollback of their processing. If it returns TRUE the step must also implement the method rollback() with the rollback functionality.

This default implementation always returns FALSE.

Returns:

TRUE if the step implementation support a rollback

checkStopProcessExecution

protected boolean checkStopProcessExecution()

check whether the execution of this process should be stopped.

Returns:

TRUE if the process should be stopped, FALSE otherwise.

cleanup

protected void cleanup()

This method will always be invoked at the end of a process (whether successful or not) for all executed steps. Process steps that allocate resources should override this method to free such resources if that hasn't already be done in a regular way. Multiple invocations of this method can occur and should be handled correctly by implementations. The default implementation does nothing.

getNextStep

protected java.lang.String getNextStep()

Returns the name of the next process step that shall be executed after this one.

Returns:

The name of the next process step

internalExecute

protected void internalExecute()
                        throws java.lang.Exception

Internal method to invoke the execute() method. Should only be invoked by framework classes.

Throws:

java.lang.Exception - Any exception may be thrown by subclasses

needsInteraction

protected boolean needsInteraction()
                            throws java.lang.Exception

Checks whether this step must be interrupted to perform an interaction to query additional data. The default implementation returns TRUE if the flag MetaTypes.INTERACTIVE is set to TRUE and at least one interaction parameter is present.

Returns:

TRUE if an interaction is needed

Throws:

java.lang.Exception - Any exception may be thrown by subclasses

prepareContinuation

protected void prepareContinuation()
                            throws java.lang.Exception

This method can be overridden by (interactive) subclasses if an interaction continuation occurs. That is the case if the parameter that caused the interaction is an element of the continuation parameter list that is stored in ProcessRelationTypes.CONTINUATION_PARAMS. The framework stores the corresponding parameter into ProcessRelationTypes.CONTINUATION_PARAM before this method will be invoked.

The default implementation does nothing.

Throws:

java.lang.Exception - Any exception may be thrown

prepareExecution

protected void prepareExecution()
                         throws java.lang.Exception

Prepares the execution of this step in succession of the previous step by invoking prepareParameters() and prepareValues(). This method should only be overridden by framework classes.

Throws:

java.lang.Exception - Any exception may be thrown

prepareInteraction

protected void prepareInteraction()
                           throws java.lang.Exception

Prepares a re-execution of this step during an interaction by invoking the method prepareValues() and resets the interaction parameter. This method should only be overridden by framework classes.

Throws:

java.lang.Exception - Any exception may be thrown

prepareNewInteractionParameters

protected void prepareNewInteractionParameters(java.util.Collection<? extends org.obrel.core.RelationType<?>> rParams)

Prepares new interaction parameters for rendering.

Parameters:

rParams -

prepareParameters

protected void prepareParameters()
                          throws java.lang.Exception

This method can be overridden to prepare this step's parameters for execution. The main use of this method is for steps that are interactive to prepare the interaction parameters. This method will not be invoked if this step is re-executed because of the modification of an interactive input parameter. In that case only prepareValues() will be invoked.

Throws:

java.lang.Exception - Any exception may be thrown if the preparation fails

prepareValues

protected void prepareValues()
                      throws java.lang.Exception

This method can be overridden to prepare a step's parameter values after their initialization in the method prepareParameters() or to update the values after an interaction occurred.

Throws:

java.lang.Exception - Any exception may be thrown if the preparation fails

resetParameters

protected void resetParameters()
                        throws java.lang.Exception

Will be invoked by a process on a rollback to reset parameter initializations performed by interactive steps. This method will be invoked on the currently suspended step as well as on any step on which the rollback() method is invoked.

Throws:

java.lang.Exception - Any exception may be thrown if the reset fails

resume

protected boolean resume()
                  throws java.lang.Exception

This method can be overridden to resume this step after the process had been suspended. It will be invoked before the execute() method is called when the process had been suspended by this step after a previous call to the prepareParameters() method. A possible application would be to collect the user input from the parameters for an interactive step.

If the method is invoked after an interactive input occurred the interaction parameter will still be set. It will be reset automatically before the process continues the execution.

Returns:

TRUE if the process can continue with the execution of this step, FALSE if this step requires another interaction first

Throws:

java.lang.Exception - Any exception may be thrown if resuming the step fails

rollback

protected void rollback()
                 throws java.lang.Exception

Must be implemented by a subclass if it can perform a rollback of a previous execution. It is guaranteed by the framework that this method will only be invoked after the step has been executed already. It is intended mainly for interactive processes that stop execution at certain (interactive) steps and can be rolled back to previous such steps. A step implementation that supports rollback must return TRUE from it's overridden canRollback() method.

A successful rollback must leave this step in a state that allows it and the following steps in the enclosing process to be executed again. On re-execution, the method prepareParameters() will be invoked again too before execution. Basically, after a rollback the parameters of the enclosing process should be in the same state as they had been before the execution of this step.

This default implementation always throws a ProcessException stating that a rollback is not supported.

Throws:

java.lang.Exception - Any exception may be thrown if the rollback fails

setNextStep

protected void setNextStep(java.lang.String sNextStepName)

Sets the name of the next process step that shall be executed after this one.

Parameters:

sNextStepName - The name of the next process step

setup

protected void setup()
              throws ProcessException

This method must be overridden by subclasses that require initialization. It will be invoked automatically after a step instance has been created and added to it's process. Overriding classes should invoke the super method.

Throws:

ProcessException - Can be thrown by subclasses if the initialization fails

throwMissingParameterException

protected <T> void throwMissingParameterException(org.obrel.core.RelationType<T> rParamType)

Throws a runtime exception that signals a missing process parameter.

Overrides:

throwMissingParameterException in class ProcessFragment

Parameters:

rParamType - The relation type of the missing parameter

validate

protected void validate()
                 throws java.lang.Exception

Will be invoked to validate the step's parameters after an interaction has occurred. This method processes all validation functions that are stored in ProcessRelationTypes.PARAM_VALIDATIONS and throws an InvalidParametersException if at least one validation fails. Subclasses can override this method to implement their own validations but should in most cases also invoke the superclass method.

The validation will not occur if an interactive input parameter exists and the method ProcessElement.continueOnInteraction(RelationType...) returns FALSE because then this step will be prepared and executed again to continue with the current interaction. Validation only occurs on the transition to the next step.

Throws:

InvalidParametersException - If a preset parameter validation fails

java.lang.Exception - Any exception may be thrown if the validation fails

validateParameters

protected java.util.Map<org.obrel.core.RelationType<?>,java.lang.String> validateParameters(boolean bOnInteraction)

Invokes the validation functions that are stored in the process step relations ProcessRelationTypes.INTERACTION_PARAM_VALIDATIONS and ProcessRelationTypes.PARAM_VALIDATIONS. It can be overridden by subclasses to perform more complex parameter validations that cannot be described by a single validation function. It returns a mapping from invalid parameters to the corresponding error messages if at least one parameter validation fails. If no error occurs the returned map will be empty.

Subclasses should normally invoke the superclass method and add their own error message to the returned map if necessary. That allows the user interface of interactive steps to display all failures at once.

Parameters:

bOnInteraction - TRUE if the validation occurs during an interaction and FALSE if it occurs when the process progresses to the next step

Returns:

The mapping from invalid parameters to the corresponding error messages