Package de.xima.fc.interfaces.workflow.triggers

Interface ITriggerHandler<Model>

    • Method Detail

      • getFilterCriteriaForEvent

        @Nullable
de.xima.cmn.criteria.FilterCriterion getFilterCriteriaForEvent​(ITriggerFilterCriteriaForEventParams params)
        Called once with the event data when an event is fired. Each handler may add filter criteria to locate the triggers that match the event data.

        This method must return a non-null value to indicate that the event applies to this type of trigger at all. When this returns null, no triggers of this handler type are considered. The filter criterion returned by this method is used for a query for WorkflowTrigger entities, i.e. all attribute names must be relative to that entity.

        For example, to limit the result to triggers which have a search term with the key customKey set to valueForCustomKey, use: 

         return params.searchTermExists("customKey", valueForCustomKey);
        To create a complex filter, use or / and etc. If you cannot use a database filter to check whether a trigger applies, use always to fetch all triggers for this handler type, and implement isAppliesToEvent to filter the applicable triggers via Java code.

        Basic restrictions such as the trigger type, the form record and project are applied automatically by the system and do not need to be included in the returned filter.

        See the class level documentation ITriggerHandler for more details.

        Parameters:
        params - Parameters with the event data of the event that occurred.
        Returns:
        A filter criterion to restrict the list of matching triggers for this handler type. When null is returned, no triggers of this handler type are considered.
        Throws:
        RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and no triggers of this type are considered.

      • getLocalizedTypeName

        default String getLocalizedTypeName​(Locale locale)
        Finds the localized name of this trigger type. The default implementation uses the key wf.trigger.[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<Model,​WorkflowTrigger>
        Parameters:
        locale - Locale for which the type name should be returned.
        Returns:
        A human-readable name of this trigger type in the given locale.

      • getTriggerPrototypes

        List<ITriggerPrototypeDescriptor<Model>> getTriggerPrototypes​(IGetTriggerPrototypesParams params)
        Returns a list of all trigger prototypes for this node type. Each prototype appears in the drawer panel of the workflow designer. The user can move a trigger prototype via drag & drop into the design area in the center to add the trigger 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 trigger 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.

      • isAppliesToEvent

        default boolean isAppliesToEvent​(ITriggerAppliesToEventParams<Model> params)
        Called once the database query for matching triggers completes successfully. May be used to restrict the list of candidate triggers returned by the database query for matching triggers. This is useful, for example, when the check cannot be expressed as a database query. The tasks of triggers for which this method returns false are not executed.

        See the class level documentation ITriggerHandler for more details.

        Parameters:
        params - The parameters with the event that occurred and a trigger returned by the database query for matching triggers.
        Returns:
        Whether the given trigger applies to the the given event. If not, the task for that trigger is not executed.
        Throws:
        RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and the trigger is considered not to apply to the event.

      • isPreconditionSatisfied

        default boolean isPreconditionSatisfied​(ITriggerPreconditionSatisfiedParams<Model> params)
        Called once the task of a trigger is about to be executed. This method may return false to prevent the task from being executed. When an event triggers multiple tasks, the execution of one task may invalidate the preconditions for a later task, so this method can be used to check whether the precondition is still satisfied.

        See the class level documentation ITriggerHandler for more details.

        Parameters:
        params - The parameters with the task about to be executed.
        Returns:
        true to proceed with the task's execution, false to skip the task's execution.
        Throws:
        RuntimeException - Should not throw under normal circumstances. Any exception throws by this method is caught and logged; and the precondition is considered not be fulfilled.

      • onTaskBegin

        default IOnTaskBeginRetVal onTaskBegin​(ITriggerOnTaskBeginParams<Model> params)
                                throws Exception
        Callback that is invoked just before a task that has a trigger of this type is executed. You may use this callback method to set up the execution context.

        This method should return the data that should be made available via IWorkflowVariableHandler.getTriggerData(String). This data is also available via a placeholder.

        Parameters:
        params - Parameters passed to the callback that contain the trigger data and the execution context.
        Returns:
        Result of the begin callback, see IOnTaskBeginRetVal.
        Throws:
        Exception - Should not throw under normal circumstances. When this method throws an exception, the task is marked as a failure and will cause remaining tasks to be aborted.

      • onTaskFinish

        default void onTaskFinish​(ITriggerOnTaskFinishParams<Model> params)
        Callback that is invoked just after a task that has a trigger of this type was executed. You may use this callback method to clean up the execution context, such as by removing certain variables added by onTaskBegin(ITriggerOnTaskBeginParams).

        In case onTaskBegin(ITriggerOnTaskBeginParams) threw an exception, this is not called.

        Parameters:
        params - Parameters passed to the callback that contain the trigger data and the execution context.
        Throws:
        RuntimeException - Should not throw under normal circumstances. When this method throws an exception, the task is marked as a failure and will cause remaining tasks to be aborted.