Interface INodeHandler<TData>
-
- Type Parameters:
TData
- Type of the properties model for the node. UseJSONObject
if you want to get the raw data and possibly perform serialization / deserialization yourself. SeeIElementHandler.getDataModelClass()
.
- All Superinterfaces:
ICustomParametersUpdateable
,IElementHandler<TData,WorkflowNode>
,IExecutionResultDescriptor
,IRefinedExecutionResultDescriptor<TData>
,IResourceBundleLocator
,IWorkflowElementTypeProviding
,IWorkflowNodeFlowAnalyzer<TData>
,IWorkflowNodeTypeProviding
- All Known Subinterfaces:
IBaseActionClientHandlerNode<TData>
,IBaseActionNode<TData>
,IBaseConditionClientHandlerNode<TData>
,IBaseDoUntilLoopClientHandlerNode<TData>
,IBaseWhileLoopClientHandlerNode<TData>
,IBeanValidatingNode<TData>
,IBuiltinNodeType<TData>
,IDefaultClientHandlerNode<TData>
,IExecutingLikeActionNode<TData>
,IExecutingLikeBinarySelectionNode<TData>
,IExecutingLikeControlTransferNode<TData>
,IExecutingLikeExceptionHandlerNode<TData>
,IExecutingLikeMultiSwitchNode<TData>
,IExecutingLikePostTestLoopNode<TData>
,IExecutingLikePreTestLoopNode<TData>
,IExecutingLikeReturningActionNode<TData>
,IExecutingLikeReturnNode<TData>
,IExecutingLikeSequenceNode<TData>
,IExecutingLikeThrowNode<TData>
,IFileProviding<TData>
,IHierarchyValidatingNode<TData>
,ILoopStatementMustLoopValidating<TData>
,IMultipleCheckPropertiesNode<TData>
,IOfficialHelpPageNode<TData>
,IPluginActionNodeHandler<TData>
,IPluginConditionNodeHandler<TData>
,IPluginDoUntilLoopNodeHandler<TData,TState>
,IPluginWhileLoopNodeHandler<TData,TState>
,IResultlessNode<TData>
,ISemverUpdatingNode<TData>
,ISingleBaseActionBuiltinNodePrototype<TData>
,ISingleBaseActionNodePrototype<TData>
,ISingleBaseConditionNodePrototype<TData>
,ISingleBaseDoUntilLoopNodePrototype<TData>
,ISingleBaseWhileLoopNodePrototype<TData>
,ISingleBuiltinNodePrototype<TData>
,ISingleNodePrototype<TData>
- All Known Implementing Classes:
APluginActionNodeHandler
,APluginConditionNodeHandler
,APluginDoUntilLoopNodeHandler
,APluginWhileLoopNodeHandler
,FcBreakHandler
,FcChangeFormAvailabilityHandler
,FcChangeFormValueHandler
,FcChangeStateHandler
,FcCompressAsZipHandler
,FcContinueHandler
,FcCopyFormRecordHandler
,FcCounterHandler
,FcCreateTextFileHandler
,FcDecodeBase64Handler
,FcDeleteAttachmentHandler
,FcDeleteFormRecordHandler
,FcDoiInitHandler
,FcDoUntilLoopHandler
,FcEmailHandler
,FcEmptyHandler
,FcEncodeBase64Handler
,FcExperimentHandler
,FcExportToPersistenceHandler
,FcExportToXmlHandler
,FcFillPdfHandler
,FcFillWordHandler
,FcForEachLoopHandler
,FcHttpRequestHandler
,FcImportFormValueFromXmlHandler
,FcLdapQueryHandler
,FcLogEntryHandler
,FcMoveFormRecordToInboxHandler
,FcMultipleConditionHandler
,FcProcessHistoryPdfHandler
,FcProcessLogPdfHandler
,FcProvideResourceHandler
,FcQueueTaskHandler
,FcRedirectHandler
,FcRenewProcessIdHandler
,FcReturnFileHandler
,FcReturnHandler
,FcSaveToFileSystemHandler
,FcSaveToWebDavHandler
,FcSendFormRecordMessageHandler
,FcSequenceHandler
,FcSetSavedFlagHandler
,FcShowTemplateHandler
,FcSqlStatementHandler
,FcSwitchCaseHandler
,FcSwitchDefaultHandler
,FcSwitchHandler
,FcThrowExceptionHandler
,FcWhileLoopHandler
,FcWriteFormRecordAttrHandler
public interface INodeHandler<TData> extends IElementHandler<TData,WorkflowNode>, IExecutionResultDescriptor, IRefinedExecutionResultDescriptor<TData>, IWorkflowNodeFlowAnalyzer<TData>, IWorkflowNodeTypeProviding
All node handlers must be thread-safe. Usually you should not have any instance fields in your handler.Interface for registering workflow nodes. Each workflow node is of a given
type
, and a handler needs to be registered for each type. The handler is responsible for processing the node during execution, for displaying the node during editing, and for validating the node.For plugins, it is strongly recommended that you override
IElementHandler.getVersion()
and use the version of the plugin instead. You should also overridegetResourceBundle()
and provide a resource bundle for your plugin.Each action may create data when it is executed, that describe the result of the action. This may include, for example, a status message or a list of values fetched from a network. This interface contains the descriptors that describe the type of data that is created in case the action succeeds and fails, see
IExecutionResultDescriptor
.The workflow engine is generic in the sense that it never checks the type of a node for special types, all logic is implemented in terms of the node handler interface. All built-in workflow nodes are implemented purely in terms of this interface. This ensures that all features usable by built-in nodes can also be used by plugins. On the downside, this requires this interface to have an extensive collection of methods. To ease implementation, several mixins are provided for special types of nodes that implement a particular sub set of methods with sane defaults. You can find available general-purpose mixins in the packages
de.xima.fc.interfaces.workflow.mixin
andde.xima.fc.workflow.mixin
.- Since:
- 7.0.0
- Author:
- XIMA MEDIA GmbH
- See Also:
de.xima.fc.interfaces.workflow.mixin
-
-
Field Summary
-
Fields inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler
CURRENT_HANDLER_VERSION
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description INormalCompletionResult
execute(INodeExecutionParams<TData> params)
Executes the given workflow node.default String
getLocalizedTypeName(Locale locale)
Finds the localized name of this node type.List<INodePrototypeDescriptor<TData>>
getNodePrototypes(IGetNodePrototypesParams params)
Returns a list of all node prototypes for this node type.default Class<? extends INodePropertiesBean<TData>>
getPropertiesBeanClass()
Returns the class of the bean that should be used when editing the properties of a workflow element.default Set<String>
getRelatedNodeTypes()
Complex workflow elements may consist of several related node types.default Set<String>
getSupportedControlTransferTypes()
Returns the set of control transfer types that this node can handle.default boolean
isCreateProtocolEntryAfterExecution(boolean success)
Deprecated.default boolean
isCreateProtocolEntryAfterExecution(ICreateProtocolEntryAfterExecutionParams params)
Controls whether a protocol entry is created after the node was executed.default boolean
isReplacePlaceholderBeforeExecution()
Whether to replace allString
fields annotated with@Placeholder
in the properties model automatically before execution.-
Methods inherited from interface de.xima.fc.interfaces.workflow.ICustomParametersUpdateable
updateCustomParams
-
Methods inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler
extractDescription, extractName, extractSearchTerms, getCascadingStyleSheet, getCascadingStyleSheet, getDataModelClass, getDisplayLabel, getElementSummaryModel, getElementSummaryXhtml, getFastJsonConverter, getFilterCriteriaForEntities, getHelpPageLocation, getJavaScript, getJavaScript, getPropertiesViewXhtml, getResourceBundle, getVersion, isAvailable, isHasUserVisibleName, readEntityReferences, readPlaceholders, validateGlobal, validateLocal, writeEntityReferences, writePlaceholders
-
Methods inherited from interface de.xima.fc.interfaces.workflow.execution.IExecutionResultDescriptor
getAlwaysValueDescriptor, getAttachmentValueDescriptor, getCurrentAttachmentValueDescriptor, getCurrentFileValueDescriptor, getCurrentValueDescriptor, getErrorValueDescriptor, getFileValueDescriptor, getSoftErrorValueDescriptor, getSuccessValueDescriptor
-
Methods inherited from interface de.xima.fc.interfaces.workflow.execution.IRefinedExecutionResultDescriptor
getAlwaysValueDescriptor, getAttachmentValueDescriptor, getCurrentAttachmentValueDescriptor, getCurrentFileValueDescriptor, getCurrentValueDescriptor, getErrorValueDescriptor, getFileValueDescriptor, getSoftErrorValueDescriptor, getSuccessValueDescriptor
-
Methods inherited from interface de.xima.fc.interfaces.workflow.IWorkflowElementTypeProviding
getType
-
Methods inherited from interface de.xima.fc.interfaces.workflow.analysis.IWorkflowNodeFlowAnalyzer
createFlowGraph
-
-
-
-
Method Detail
-
execute
INormalCompletionResult execute(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException, ExecutionAbortedError
Executes the given workflow node. You may perform any action required by this node type, such as creating files, sending HTTP requests etc.If this node has children that need to be executed (such as for control nodes like conditions or switches), you must use
IWorkflowExecutionContext.executor()
to execute the children instead of attempting to call their execute method directly. Note that a node must never attempt to execute any other node that is not in the subtree (= a child, a grand-child, a grand-grand-child etc.) of this node.In case you throw any other exceptions other than the exceptions mentioned in the throws clause, it will be wrapped in a
NodeThrewException
with a general error code.- Parameters:
params
- The node that needs to be executed and the current workflow context.- Returns:
- The result value or values created by the executed node.
- Throws:
ExecutionAbortedError
- When the execution of the task was aborted, such as when certain limits were exceeded. Usually you should not catch this exception and allow it to propagate upwards.AbstractAbruptCompletionException
- When the node's execution did not finish normally, see below for subclasses.NodeThrewException
- If this exception was thrown by the execute method of the given node. Indicates that a node could not be completed successfully. This exception can be caught by control flow nodes with custom error handling, such as a try-catch node.NodeReturnedException
- If this exception was thrown by the execute method of the given node. Indicates that the node wishes to return, i.e. to stop the execution of the current processing chain (="function"). This exception can be caught by control flow nodes with custom finalization handling, such as a try-finally node (which should rethrow this exception afterwards).NodeTransferredControlException
- If this exception was thrown by the execute method of the given node. Indicates that a control transfer should take place. The matching node for thecontrol transfer target
should catch this exception and proceed according to thetype of the control transfer
. For example, loop nodes may catch break and continue control transfers and either stop the loop or skip to the next iteration of the loop.RuntimeException
- A runtime exception may be thrown to indicate an unforeseen error, such as general database errors. For all errors you expect to happen, you should throw an appropriateNodeThrewException
with the details of the exception. When a runtime exception is thrown, it is wrapped in aNodeThrewException
with a generic error code and treated as if that exception had been thrown.
-
getLocalizedTypeName
default String getLocalizedTypeName(Locale locale)
Finds the localized name of this node type. The default implementation uses the keywf.node.[TYPE]
, and looks up the key in theIElementHandler.getResourceBundle(Locale)
. If it cannot be found there, it looks it up in the built-in resource bundles. If it cannot be found there either, returns#getType()
.- Specified by:
getLocalizedTypeName
in interfaceIElementHandler<TData,WorkflowNode>
- Parameters:
locale
- Locale for which the type name should be returned.- Returns:
- A human-readable name of this node type in the given locale.
-
getNodePrototypes
List<INodePrototypeDescriptor<TData>> getNodePrototypes(IGetNodePrototypesParams params)
Returns a list of all node prototypes for this node type. Each prototype appears in the drawer panel of the workflow designer. The user can move a node prototype via drag & drop into the design area in the center to add the node to the current flowchart.You should always return all prototypes, irrespective of whether they are allowed to the current user.
IElementHandler.isAvailable(IIsAvailableParams)
is checked by the engine, and unavailable node types are removed automatically.- Parameters:
params
- Parameters for this method, such as the current locale for localizing the display name of the prototypes.- Returns:
- A list of all available prototypes.
null
is treated as an empty list. - Throws:
RuntimeException
- This method should normally not throw an exception. A runtime exception may be thrown when the node prototypes cannot be created for an unknown reason. When an exception is thrown, no node prototypes are made available for this handler.
-
getPropertiesBeanClass
default Class<? extends INodePropertiesBean<TData>> getPropertiesBeanClass()
Description copied from interface:IElementHandler
Returns the class of the bean that should be used when editing the properties of a workflow element. May benull
if you do not require any bean or custom logic. When you only wish to access the properties of yourIElementHandler.getDataModelClass()
, you do have to use a custom bean - the model is available via the expression language variablemodel
. SeeIElementHandler.getPropertiesViewXhtml()
for further details.The default returns
null
, which uses no extra bean. An extra bean may not be required for simple UIs if you only need to access the properties model of the workflow element - seeIElementHandler.getPropertiesViewXhtml()
.- Specified by:
getPropertiesBeanClass
in interfaceIElementHandler<TData,WorkflowNode>
- Returns:
- The class of the bean to use for editing a workflow node's properties.
- See Also:
IElementHandler.getPropertiesViewXhtml()
-
getRelatedNodeTypes
default Set<String> getRelatedNodeTypes()
Complex workflow elements may consist of several related node types. For example, a switch may consist of a switch node, a default case node, and a switch case node. This method should return such related node types (but not theIWorkflowElementTypeProviding.getType()
itself). This is not a strict requirement, all features will still work even if this method returns an empty set. The result of this method is used e.g. to load the handlers for the related node types when the flowchart is loaded in the designer (otherwise they would be loaded dynamically once required).- Returns:
- A list of related node types.
-
isCreateProtocolEntryAfterExecution
@Deprecated default boolean isCreateProtocolEntryAfterExecution(boolean success)
Deprecated.Controls whether a protocol entry is created after the node was executed.The default implementation returns true iff result was created by the current node.
When some action throws an exception, all parent control flow node such as if-else statements also throw an exception. This would result in multiple protocol entries for a singe error.
- Parameters:
success
- Whether the action was executed successfully.- Returns:
true
to create a protocol entry, orfalse
otherwise.
-
isCreateProtocolEntryAfterExecution
default boolean isCreateProtocolEntryAfterExecution(ICreateProtocolEntryAfterExecutionParams params)
Controls whether a protocol entry is created after the node was executed.The default implementation returns true iff result was created by the current node.
When some action throws an exception, all parent control flow node such as if-else statements also throw an exception. This would result in multiple protocol entries for a single error.
- Parameters:
params
- Parameters with the node that was executed and the result of the node's execution.- Returns:
true
to create a protocol entry, orfalse
otherwise.
-
isReplacePlaceholderBeforeExecution
default boolean isReplacePlaceholderBeforeExecution()
Whether to replace allString
fields annotated with@Placeholder
in the properties model automatically before execution.Specifically: When this returns
true
andTData
is not setJSONObject
,IWorkflowPlaceholderHandler#replaceStringFields
is invoked on the properties model before it is passed to the#execute
viaINodeExecutionParams#getData
. When this returnsfalse
, no such call is made. Defaults totrue
when not overridden.- Returns:
true
to replace placeholders in the properties model automatically before execution, orfalse
otherwise.
-
getSupportedControlTransferTypes
default Set<String> getSupportedControlTransferTypes()
Returns the set of control transfer types that this node can handle. SeeEStandardControlTransferType
for a list of built-in transfer types.If this method returns a non-empty set, the
execute
method should catchNodeTransferredControlException
. If itscontrol transfer type
is one of the supported types, it should handle that control transfer accordingly. Otherwise, it should propagate the exception upwards by rethrowing it.This method is also used by control transfer nodes (e.g. the built-in
FC_BREAK
orFC_CONTINUE
) to decide which nodes are valid targets.- Returns:
- The control transfer types that this node can handle.
- See Also:
for a list of built-in control transfer types.
-
-