Interface INodeHandler<TData>

    • 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 the control transfer target should catch this exception and proceed according to the type 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 appropriate NodeThrewException with the details of the exception. When a runtime exception is thrown, it is wrapped in a NodeThrewException 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 key wf.node.[TYPE], and looks up the key in the IElementHandler.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 interface IElementHandler<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.
      • 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 the IWorkflowElementTypeProviding.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)
        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, or false 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, or false otherwise.
      • isReplacePlaceholderBeforeExecution

        default boolean isReplacePlaceholderBeforeExecution()
        Whether to replace all String fields annotated with @Placeholder in the properties model automatically before execution.

        Specifically: When this returns true and TData is not set JSONObject , IWorkflowPlaceholderHandler#replaceStringFields is invoked on the properties model before it is passed to the #execute via INodeExecutionParams#getData. When this returns false, no such call is made. Defaults to true when not overridden.

        Returns:
        true to replace placeholders in the properties model automatically before execution, or false otherwise.