Package de.xima.fc.workflow.mixin

Interface IPluginTriggerHandler<TData extends BaseTriggerProps>

Type Parameters:

TData - Type of the trigger's properties model, which must extend BaseTriggerProps. The properties themselves are stored as JSON and serialized to / deserialized from this type automatically. You should make sure this type can be serialized / deserialized via JSON. This means you should only basic field types such as number, booleans, or strings, or nested types. Furthermore, If you wish, you can also use the type JSONObject to skip serialization / deserialization and work with the raw JSON data.

All Superinterfaces:

IBaseTrigger<TData>, IBeanValidatingElement<TData,WorkflowTrigger>, IBeanValidatingTrigger<TData>, ICustomParametersUpdateable, IDefaultClientHandlerTrigger<TData>, IElementHandler<TData,WorkflowTrigger>, IFCPlugin, INamedUiElement, INameProviding, IPluginGenericCustomGUI<IPluginWorkflowTriggerBean>, IPluginWorkflowTrigger, IRefinedTriggerDataDescriptor<TData>, IResourceBundleLocator, ISingleBaseTriggerPrototype<TData>, ISingleElementPrototype<TData,WorkflowTrigger>, ISingleTriggerPrototype<TData>, ITransferable, ITriggerDataDescriptor, ITriggerHandler<TData>, IWorkflowElementTypeProviding, IWorkflowTriggerTypeProviding, Serializable

All Known Implementing Classes:

APluginTriggerHandler

public interface IPluginTriggerHandler<TData extends BaseTriggerProps>
extends IPluginWorkflowTrigger, ITriggerHandler<TData>, IBaseTrigger<TData>, IDefaultClientHandlerTrigger<TData>, ISingleBaseTriggerPrototype<TData>

Mixin meant for IPluginWorkflowTrigger plugins that only wish to provide a workflow trigger that executes some business logic. The ITriggerHandler offers many methods that are irrelevant for this use case - this mixin implements most methods with the appropriate defaults.

Since:

7.0.0

Author:

XIMA MEDIA GmbH

Field Summary

Fields inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler

CURRENT_HANDLER_VERSION

Fields inherited from interface de.xima.fc.plugin.interfaces.IFCPlugin

CONFIG_FILENAME

Fields inherited from interface de.xima.fc.interfaces.INamedUiElement

ATTR_DISPLAY_NAME

Fields inherited from interface de.xima.fc.entities.interfaces.INameProviding

ATTR_NAME, COL_NAME

Method Summary

Modifier and Type	Method	Description
default String	extractDescription(TData data)	Retrieves the name that will be stored as AWorkflowElement.getDescription().
default String	extractName(TData data)	Retrieves the name that will be stored as AWorkflowElement.getName().
default Class<? extends TData>	getDataModelClass()	This default implementation attempts to read the type of the TData parameter via reflection.
default String	getDescription(Locale locale)	The default implementation returns the localized value of the getI18nKeyDescription() in the getResourceBundle(Locale).
default String	getDisplayName(Locale locale)	The default implementation returns the localized value of the getI18nKeyDisplayName() in the getResourceBundle(Locale).
default String	getI18nKeyActionSearchText()
default String	getI18nKeyActionSubLabel()
default String	getI18nKeyActionTitle()
default String	getI18nKeyDescription()
default String	getI18nKeyDisplayName()
default String	getI18nKeyTriggerLabel()
default IElementCategory	getMainCategory(IGetElementPrototypesParams params)
default Class<? extends ITriggerPropertyPluginBean<TData>>	getMainPluginBeanClass()
String	getName()	Getter for the name of this plugin.
IPluginInitializeData	getPluginInitializeData()
default Class<? extends ITriggerPropertiesBean<TData>>	getPropertiesBeanClass()	Returns the class of the bean that should be used when editing the properties of a workflow element.
default URL	getPropertiesViewXhtml()	This default implementation returns the XHTML page located at getPropertiesViewXhtmlPath()/getPropertiesViewXhtmlName().
String	getPropertiesViewXhtmlName()
default String	getPropertiesViewXhtmlPath()
default IGuiIcon	getPrototypeIcon(IGetElementPrototypesParams params)	This default implementation returns an icon resembling a jigsaw puzzle piece, which is the default icon for an trigger plugin.
default String	getPrototypeLabel(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyTriggerLabel() in the getResourceBundle(Locale).
default String	getPrototypeSearchText(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionSearchText() in the getResourceBundle(Locale).
default String	getPrototypeSubLabel(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionSubLabel() in the getResourceBundle(Locale).
default String	getPrototypeTitle(IGetElementPrototypesParams params)	This default implementation returns the localized value of the getI18nKeyActionTitle() in the getResourceBundle(Locale).
default ResourceBundle	getResourceBundle(Locale locale)	This default implementation attempts to read the resource bundle from the getResourceBundlePath().
default String	getResourceBundlePath()
default IValueDescriptor<?,? extends IValueBuilder<?>>	getTriggerDataDescriptor(IValueDescriptorFactory factory)	When a trigger reacts to an events and a workflow task is started, the trigger can make data available to the workflow task.
default ITriggerHandler<TData>	getTriggerHandler()
default String	getType()	This default implementation simply returns the getName() of the plugin as the type.
default Iterable<Class<? extends IPluginWorkflowTriggerBean>>	getUnmanagedBeans()	This must return a list of backing bean classes that control the user interface and are required by the XHTML Facelet view.
default String	getVersion()	Instead of the formcycle version, this default implementation returns the current version of this plugin.

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.IBeanValidatingElement

getValidationGroups, validateLocal

Methods inherited from interface de.xima.fc.interfaces.workflow.ICustomParametersUpdateable

updateCustomParams

Methods inherited from interface de.xima.fc.workflow.mixin.IDefaultClientHandlerTrigger

getCascadingStyleSheet, getJavaScript

Methods inherited from interface de.xima.fc.interfaces.workflow.elements.IElementHandler

extractSearchTerms, getCascadingStyleSheet, getDisplayLabel, getElementSummaryModel, getElementSummaryXhtml, getFastJsonConverter, getFilterCriteriaForEntities, getHelpPageLocation, getJavaScript, isAvailable, isHasUserVisibleName, readEntityReferences, readPlaceholders, validateGlobal, writeEntityReferences, writePlaceholders

Methods inherited from interface de.xima.fc.plugin.interfaces.IFCPlugin

getDescription, initialize, initPlugin, install, shutdown, shutdown, uninstall, validateConfigurationData

Methods inherited from interface de.xima.fc.plugin.interfaces.workflow.IPluginWorkflowTrigger

getXhtmlView

Methods inherited from interface de.xima.fc.interfaces.workflow.execution.IRefinedTriggerDataDescriptor

getTriggerDataDescriptor, getTriggerFilesDescriptor

Methods inherited from interface de.xima.fc.workflow.mixin.ISingleBaseTriggerPrototype

getPrototypeModelData, getThemeColor

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.ISingleElementPrototype

getPrototypeSortKey, getPrototypeTags, getSubCategory

Methods inherited from interface de.xima.fc.interfaces.workflow.mixin.ISingleTriggerPrototype

getPrototypeElement, getTriggerPrototypes

Methods inherited from interface de.xima.fc.interfaces.workflow.execution.ITriggerDataDescriptor

getTriggerFilesDescriptor

Methods inherited from interface de.xima.fc.interfaces.workflow.triggers.ITriggerHandler

getFilterCriteriaForEvent, getLocalizedTypeName, isAppliesToEvent, isPreconditionSatisfied, onTaskBegin, onTaskFinish

Method Detail

extractDescription

default String extractDescription(TData data)

Description copied from interface: IElementHandler

Retrieves the name that will be stored as AWorkflowElement.getDescription(). For example, actions may let the user enter a description for the action, which would be returned by this method. A condition node may an explanation of the test condition as the description.

The default implementation checks whether the IElementHandler.getDataModelClass() implements IDescriptionProviding and if it does, returns IDescriptionProviding.getDescription(). Otherwise returns an empty string.

Specified by:

extractDescription in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

data - The data of the workflow element for which to retrieve the description.

Returns:

The description of the workflow element with the given data.

extractName

default String extractName(TData data)

Description copied from interface: IElementHandler

Retrieves the name that will be stored as AWorkflowElement.getName(). For example, actions may let the user enter the name of the action, which would be returned by this method. A condition node may use a summary of the test condition as the name. A button trigger event may use the name of the button.

The default implementation checks whether the IElementHandler.getDataModelClass() implements INameProviding and if it does, returns INameProviding.getName().

Specified by:

extractName in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

data - The data of the workflow element for which to retrieve the name.

Returns:

The name of the workflow element with the given data.

getDataModelClass

default Class<? extends TData> getDataModelClass()

This default implementation attempts to read the type of the TData parameter via reflection. If that does not work, or you need to optimize, override this method and return the type directly.

Specified by:

getDataModelClass in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Returns:

The class corresponding to the type parameter TData.

See Also:

IElementHandler.getDataModelClass()

getDescription

default String getDescription(Locale locale)

The default implementation returns the localized value of the getI18nKeyDescription() in the getResourceBundle(Locale). When no value exists for that key, returns an empty string (= no description).

Specified by:

getDescription in interface IFCPlugin

Parameters:

locale - The locale for which to get the description.

Returns:

An HTML markup string with the description for this plugin, or null if no description is available.

See Also:

IFCPlugin.getDescription()

getDisplayName

default String getDisplayName(Locale locale)

The default implementation returns the localized value of the getI18nKeyDisplayName() in the getResourceBundle(Locale). When no value exists for that key, returns the getName() of this plugin.

Specified by:

getDisplayName in interface IFCPlugin

Specified by:

getDisplayName in interface INamedUiElement

Parameters:

locale - The locale to get the display name for.

Returns:

The display name of this element in the given locale.

See Also:

IFCPlugin.getDisplayName(Locale)

getI18nKeyActionSearchText

default String getI18nKeyActionSearchText()

Returns:

The i18n key for the search text of the action, not shown in the UI but used for filtering. Defaults to "getName().searchtext".

getI18nKeyActionSubLabel

default String getI18nKeyActionSubLabel()

Returns:

The i18n key for the sub label of the action, as shown in the workflow designer below the name of the item. Defaults to "getName().sublabel".

getI18nKeyActionTitle

default String getI18nKeyActionTitle()

Returns:

The i18n key for the title of the action, as shown in the workflow designer when hovering over the item with the mouse. Defaults to "getName().title".

getI18nKeyDescription

default String getI18nKeyDescription()

Returns:

The i18n key for the description of this trigger. Defaults to "getName().desc".

getI18nKeyDisplayName

default String getI18nKeyDisplayName()

Returns:

The i18n key for the display name of this trigger, as shown in the plugin configuration backend menu. Defaults to "getName().desc".

getI18nKeyTriggerLabel

default String getI18nKeyTriggerLabel()

Returns:

The i18n key for the name of the trigger, as shown in the workflow designer. Default to the getI18nKeyDisplayName().

getMainCategory

default IElementCategory getMainCategory(IGetElementPrototypesParams params)

Specified by:

getMainCategory in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

IElementCategory element's main category, which is used for grouping the elements.

getMainPluginBeanClass

default Class<? extends ITriggerPropertyPluginBean<TData>> getMainPluginBeanClass()

Returns:

The class of the bean that should be made available in the getPropertiesViewXhtml() page. When this returns null, no bean is made available This is usually sufficient for most simple use cases, see IElementHandler.getPropertiesViewXhtml() for further details.

getName

String getName()

Description copied from interface: IFCPlugin

Getter for the name of this plugin. This is a technical name that should not appear on the user interface. Implement IFCPlugin.getDisplayName(Locale) for the name that should be shown to the user.

Specified by:

getName in interface IFCPlugin

Specified by:

getName in interface INameProviding

Returns:

String The name of this plugin.

getPluginInitializeData

IPluginInitializeData getPluginInitializeData()

Returns:

The IPluginInitializeData, as they were passed to IFCPlugin.initialize(IPluginInitializeData). Implementation should usually just store the data in a private volatile field and return it in this method.

getPropertiesBeanClass

default Class<? extends ITriggerPropertiesBean<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 be null if you do not require any bean or custom logic. When you only wish to access the properties of your IElementHandler.getDataModelClass(), you do have to use a custom bean - the model is available via the expression language variable model. See IElementHandler.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 - see IElementHandler.getPropertiesViewXhtml().

Specified by:

getPropertiesBeanClass in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Specified by:

getPropertiesBeanClass in interface ITriggerHandler<TData extends BaseTriggerProps>

Returns:

The class of the bean to use for editing a workflow node's properties.

See Also:

IElementHandler.getPropertiesViewXhtml()

getPropertiesViewXhtml

default URL getPropertiesViewXhtml()
                            throws MalformedURLException

This default implementation returns the XHTML page located at getPropertiesViewXhtmlPath()/getPropertiesViewXhtmlName().

Specified by:

getPropertiesViewXhtml in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Returns:

Path to the XHTML view. If the action can be configured, this must not return null. If you do return null, it will be treated as an error and an appropriate message is displayed to the user informing them that the properties panel could not be loaded. If the action cannot be configured (i.e. when the action is not selectable), this should return null.

Throws:

MalformedURLException - This exception is declared for convenience - normally you would use new URL(String) with a constant URL string that should not throw. In case an exception is thrown, it is treated the same as if this returned null.

See Also:

IElementHandler.getPropertiesViewXhtml()

getPropertiesViewXhtmlName

String getPropertiesViewXhtmlName()

Returns:

The file name (without the path) to the XHTML page with the custom UI. The file extension .xhtml is added automatically if the returned name does not contain it already.

See Also:

getPropertiesViewXhtmlPath()

getPropertiesViewXhtmlPath

default String getPropertiesViewXhtmlPath()

Returns:

The path (without the file name) to the XHTML page with the custom UI. Defaults to WEB-INF/ui. That is, you should put the file in src/main/resources/WEB-INF/ui.

See Also:

getPropertiesViewXhtmlName()

getPrototypeIcon

default IGuiIcon getPrototypeIcon(IGetElementPrototypesParams params)

This default implementation returns an icon resembling a jigsaw puzzle piece, which is the default icon for an trigger plugin.

Specified by:

getPrototypeIcon in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The icon for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getIcon().

See Also:

ISingleElementPrototype.getPrototypeIcon(IGetElementPrototypesParams)

getPrototypeLabel

default String getPrototypeLabel(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyTriggerLabel() in the getResourceBundle(Locale). If no localized value exists for that key, defaults the getName() of this plugin.

Specified by:

getPrototypeLabel in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The icon for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeLabel(IGetElementPrototypesParams)

getPrototypeSearchText

default String getPrototypeSearchText(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionSearchText() in the getResourceBundle(Locale). If no localized value exists for that key, no title is used.

Specified by:

getPrototypeSearchText in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The search text for the element prototype, never shown to the user but used for filtering. See IElementPrototypeDescriptor.getSearchText().

See Also:

ISingleElementPrototype.getPrototypeSearchText(IGetElementPrototypesParams)

getPrototypeSubLabel

default String getPrototypeSubLabel(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionSubLabel() in the getResourceBundle(Locale). If no localized value exists for that key, no sub label is used.

Specified by:

getPrototypeSubLabel in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The sub label for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeSubLabel(IGetElementPrototypesParams)

getPrototypeTitle

default String getPrototypeTitle(IGetElementPrototypesParams params)

This default implementation returns the localized value of the getI18nKeyActionTitle() in the getResourceBundle(Locale). If no localized value exists for that key, no title is used.

Specified by:

getPrototypeTitle in interface ISingleElementPrototype<TData extends BaseTriggerProps,WorkflowTrigger>

Parameters:

params - Parameters with the current client, locale, entity context etc.

Returns:

The title for the element prototype, shown in the element drawer panel to the left of the workflow designer. See IElementPrototypeDescriptor.getLabel().

See Also:

ISingleElementPrototype.getPrototypeTitle(IGetElementPrototypesParams)

getResourceBundle

default ResourceBundle getResourceBundle(Locale locale)

This default implementation attempts to read the resource bundle from the getResourceBundlePath(). In most cases this is fine and does not have to be overridden, although you may want to override the getResourceBundlePath().

Specified by:

getResourceBundle in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Specified by:

getResourceBundle in interface IResourceBundleLocator

Parameters:

locale - A locale, for which a resource bundle shall be retrieved. Must not be null.

Returns:

The resource bundle to use for localized messages.

See Also:

IElementHandler.getResourceBundle(Locale)

getResourceBundlePath

default String getResourceBundlePath()

Returns:

The path to the resource bundle with the localized message for this plugin trigger. Defaults to WEB-INF/properties/i18n. That is, you should create the properties files src/main/resources/WEB-INF/properties/i18n_en.properties (for English), src/main/resources/WEB-INF/properties/i18n_de.properties (for German), etc.

getTriggerDataDescriptor

default IValueDescriptor<?,? extends IValueBuilder<?>> getTriggerDataDescriptor(IValueDescriptorFactory factory)

When a trigger reacts to an events and a workflow task is started, the trigger can make data available to the workflow task. This is the descriptor for that data. You should also override ITriggerHandler.onTaskBegin(de.xima.fc.interfaces.workflow.params.ITriggerOnTaskBeginParams) and provide the data you promised to provider. The default implementation promises no additional data.

Specified by:

getTriggerDataDescriptor in interface ITriggerDataDescriptor

Parameters:

factory - Factory that may be used for creating the descriptor. Instead of the factory passed in to this method, you may also use ValueDescriptorFactory.getInstance() if you wish to cache the descriptor in a static or instance field.

Returns:

The value descriptor for the data that is made available to the workflow when a task with this trigger is executed.

See Also:

ITriggerDataDescriptor.getTriggerDataDescriptor(IValueDescriptorFactory)

getTriggerHandler

default ITriggerHandler<TData> getTriggerHandler()

Specified by:

getTriggerHandler in interface IPluginWorkflowTrigger

Returns:

The trigger handler that implements all the logic required by the workflow trigger. This lets you customize all features available to built-in workflow triggers.

getType

default String getType()

This default implementation simply returns the getName() of the plugin as the type. Make sure that the name is unique. It is recommended you hardcode the name / type, as any change will result in broken backwards compatibility. In particular we advice against using Class.getCanonicalName() etc., as a refactoring would then break your plugin.

Specified by:

getType in interface IWorkflowElementTypeProviding

Returns:

The type of the workflow element that determines how the workflow element behaves. Usually there is a registered handler for each type.

getUnmanagedBeans

default Iterable<Class<? extends IPluginWorkflowTriggerBean>> getUnmanagedBeans()

Description copied from interface: IPluginGenericCustomGUI

This must return a list of backing bean classes that control the user interface and are required by the XHTML Facelet view. A new instance of the bean will be created automatically when the view is opened. Make sure each bean has got a no-argument constructor or instantiation will fail.

Each bean should be annotated with Named. If this annotation is not present or no name is specified, the name defaults to the simple name of the bean class, with the first character changed to lower case.

Also, each bean needs to be annotated one of the following scopes: @RequestScoped, @ViewScoped, @SessionScoped, or @ApplicationScoped. Note that it depends on the type of plugin which scopes are actually supported (most plugins expect @ViewScoped beans). In case you do not specify a scope, an appropriate scope will be determined automatically.

Please note that the beans are fundamentally unmanaged - functionality specific to managed CDI beans may not be supported, depending on the type of plugin. Certain features of CDI managed beans may be supported partially, depending on the type of plugin, but may work slightly differently. This includes, but is not limited to:

• The exact timing at which PostConstruct and PreDestroy are called may differ.
• A field marked with Inject may not work with all values allowed by the CDI specification, and may not perform certain validation passes such as the check for circular dependencies. Also, no new bean instances will be created when those beans have not yet been created as part of the current page.

Specified by:

getUnmanagedBeans in interface IPluginGenericCustomGUI<TData extends BaseTriggerProps>

Returns:

A list of unmanaged bean classes required by the Facelet page.

getVersion

default String getVersion()

Instead of the formcycle version, this default implementation returns the current version of this plugin. The version is read from the MANIFEST.MF file in the plugin JAR file. Make sure that the manifest contains an appropriate version entry, e.g.:

 Implementation-Version = 3.1.4
 

We recommend that you use version numbers that conform to the format and semantics as laid out by SemVer (semantic version).

Specified by:

getVersion in interface IElementHandler<TData extends BaseTriggerProps,WorkflowTrigger>

Returns:

The version of this plugin.

See Also:

IElementHandler.getVersion()