Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.fujitsu.iflow.model.workflow
Interface TimerDef

public interface TimerDef

This interface allows you to specify time-based triggers within the Interstage BPM environment. A timer contains two components: the time when the timer expires and the action that the timer triggers when it expires. Timers are for example ideal for monitoring whether project milestones are met, for periodically checking for the status of an activity or process instance, for periodically notifying a project team about mounting time-based overhead (such as equipment rental costs), for updating static HTML files, and other situations requiring up-to-date time-triggered reports.

Interstage BPM timers are very versatile and can be associated with an activity node or a process definition. The timers' behaviour differs for activity nodes and process definitions:

- Activity-Node-Level timers: Activity-Node-Level timers start running when the activity node is activated. They could therefore be used to monitor whether an activity is finished within a set period of time, and if not, the activity could be forwarded to a new group of people, or a `JavaAction` could generate another action (such as changing the priority level). Alternatively, the timer function could generate e-mail reminders to be sent to the assignees. Activity-based timers are automatically cancelled (or disabled) when the activity is completed before the timer expires.
- Process-Level timers: A Process-Level timer starts running when the process instance containing the timer is started. It can trigger actions when the entire process instance is taking too long. Process-Level timers are automatically cancelled (or disabled) when the process instance is completed before the timer expires.

### Controlling Timers

Process definition design controls the specification of Process-Level- and Activity-Node-Level timers. Timers are controlled by time and action parameters.

The parameters are specified as User Defined Attributes (UDA), which can be reset, for example, through the use of `JavaAction`s, by a user using forms or by a user via a GUI.

### Timer Type Specification

The timer type parameters can specify an absolute, specific time, or it can be relative to some other event (such as the start of the activity or process instance). The timer can also be set to trigger actions periodically (repeatedly).

- Absolute timers are set according to the absolute time when the timer will expire, measured in milliseconds since January 1, 1970, 00:00:00. You can convert this long data element into a recognizable representation of the date using methods in `java.util.Date`. This mode is typically used in conjunction with an action that separately calculates the times, and this timer then simply uses the calculated time.
- Relative timers calculate the time when they will expire based upon the time when the activity or process becomes active. They are only activated once.
- Periodic timers are relative timers that operate repeatedly. The first occurrence of the timer is relative to the time when the activity or the process instance becomes active. Subsequent occurrences are relative to the last occurrence.
- Business Relative timers calculate the time that they will expire based upon the time that the activity or a process instance becomes active, and using the 'business calendar' expression methods. They are only activated once.
- Business Periodic timers are business relative timers that operate repeatedly. The first occurrence of the timer is activated relative to the time the activity or a process instance becomes active, and subsequent occurrences are relative to the last occurrence.

### Action Specification

Interstage BPM timers perform `TimerAction`s that consists of a set of `JavaAction`s which can be implemented for the actual necessities.

This interface defines constants and operations for handling timers. All timer operations are controlled through properties with values which can be set at run time through UDAs. During development, you only need to specify the names of the UDA in which data values will later be stored.

### Adding Timers to Objects

Timers must be constructed and added to other objects in a certain order. The standard way of constructing a new `TimerDef` object is to call the method `WFObjectFactory.getTimerDef`.

You must perform the following operations (or otherwise set their associated values) before adding the timer to a process definition, node, process instance, or node instance.

- `setName(java.lang.String)`
- `setDescription(java.lang.String)`
- `setType(int)`
- `setTime(java.lang.String)`

The following `TimerDef` methods are not supported for a timer that has already been added to a process definition, node, process instance, or node instance.

- `addTimerAction(com.fujitsu.iflow.model.workflow.TimerAction)`
- `removeTimerAction(com.fujitsu.iflow.model.workflow.TimerAction)`
- `reorderTimerActions(com.fujitsu.iflow.model.workflow.TimerAction[])`

See Also:
  `WFObjectFactory`, `TimerAction`, `JavaAction`, `Plan.addTimer(TimerDef)`, `Node.addTimer(TimerDef)`, `ProcessInstance.addTimer(TimerDef)`

Field Summary
`static int` | `ABSOLUTE` Indicates that this is an Absolute Timer which fires only once at a specific date and time, no matter when the appropriate process definition or node became active.
`static int` | `BUSINESSPERIODIC` Indicates that this is a Business Periodic Timer which starts timing when the appropriate process definition or node is activated (or after it fires).
`static int` | `BUSINESSRELATIVE` Indicates that this is a Business Relative Timer which starts timing when the process definition or node is activated.
`static int` | `MAX_TIMER_DESCRIPTION_LENGTH` Specifies the maximum length of the timer description; currently 256 characters.
`static int` | `MAX_TIMER_NAME_LENGTH` Specifies the maximum length of the timer name; currently 30 characters.
`static int` | `PERIODIC` Indicates that this is a Periodic Timer which starts timing when the process definition or node is activated (or after it fires).
`static int` | `RELATIVE` Indicates that this is a Relative Timer which starts timing when the process definition or node is activated.

Method Summary
`TimerAction` | `addTimerAction(int actionType)` Deprecated. Only the type JAVAACTION of TimerActions is supported
`TimerAction` | `addTimerAction(TimerAction action)` Adds a `TimerAction` that specifies a `JavaActionSet` to this timer definition.
`java.lang.String` | `getDescription()` Returns the description of this timer definition.
`long` | `getId()` Returns this timer's unique identifier.
`java.lang.String` | `getName()` Returns the name of this timer.
`java.lang.String` | `getTime()` Returns the name of the User Defined Attribute (UDA) that will contain the period of time in milliseconds after which this timer expires.
`TimerAction[]` | `getTimerActions()` Returns all `TimerAction` objects that are attached to this timer definition.
`int` | `getType()` Returns the current type of this timer definition as defined in the `TimerDef` interface by constants such as `ABSOLUTE`.
`boolean` | `isPeriodic()` Indicates whether this timer definition is a Periodic timer.
`void` | `removeTimerAction(TimerAction ta)` Removes the specified `TimerAction` object from this timer definition.
`void` | `reorderTimerActions(TimerAction[] tas)` Adds and schedules the `TimerAction` objects to be fired in the user-defined sequence.
`void` | `setDescription(java.lang.String description)` Sets the description of this timer.
`void` | `setName(java.lang.String name)` Sets the name of this timer.
`void` | `setTime(java.lang.String milliSeconds)` Sets the name of User Defined Attribute (UDA) that contains the period of time before this timer expires in milliseconds.
`void` | `setType(int timerType)` Sets the type for this timer definition.

Field Detail

### MAX_TIMER_NAME_LENGTH

    public static final int MAX_TIMER_NAME_LENGTH

  Specifies the maximum length of the timer name; currently 30 characters.

  See Also:
    Constant Field Values

### MAX_TIMER_DESCRIPTION_LENGTH

    public static final int MAX_TIMER_DESCRIPTION_LENGTH

  Specifies the maximum length of the timer description; currently 256 characters.

  See Also:
    Constant Field Values

### RELATIVE

    public static final int RELATIVE

  Indicates that this is a Relative Timer which starts timing when the process definition or node is activated. A Relative Timer fires only once after a set period of time.

  See Also:
    Constant Field Values

### ABSOLUTE

    public static final int ABSOLUTE

  Indicates that this is an Absolute Timer which fires only once at a specific date and time, no matter when the appropriate process definition or node became active.

  See Also:
    Constant Field Values

### PERIODIC

    public static final int PERIODIC

  Indicates that this is a Periodic Timer which starts timing when the process definition or node is activated (or after it fires). A Periodic Timer repeatedly fires after a set period of time.

  See Also:
    Constant Field Values

### BUSINESSPERIODIC

    public static final int BUSINESSPERIODIC

  Indicates that this is a Business Periodic Timer which starts timing when the appropriate process definition or node is activated (or after it fires). A Business Periodic Timer repeatedly fires after a set period of time.

  See Also:
    Constant Field Values

### BUSINESSRELATIVE

    public static final int BUSINESSRELATIVE

  Indicates that this is a Business Relative Timer which starts timing when the process definition or node is activated. A Business Relative Timer fires only once after a set period of time.

  See Also:
    Constant Field Values

Method Detail

### setName

    public void setName(java.lang.String name)
                 throws ModelException

  Sets the name of this timer. It should be a short descriptive name that allows the user to easily identify what the timer does.

  The name is limited to `MAX_TIMER_NAME_LENGTH`.

  It is suggested to set the timer's name before adding a timer to a process definition, process instance, node or node instance.

  Parameters:
    `name` - The timer's name
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance. This exception is also thrown when the supplied name is invalid or `null`.
  See Also:
    `getName()`

### getName

    public java.lang.String getName()
                             throws ModelException

  Returns the name of this timer. If no name is defined, an empty `String` is returned.

  Returns:
    The name of this `TimerDef` object.
  Throws:
    `ModelException`

### setDescription

    public void setDescription(java.lang.String description)
                        throws ModelException

  Sets the description of this timer. The description can be used to document the actions to be performed for the timer.

  The description is limited to `MAX_TIMER_DESCRIPTION_LENGTH`.

  It is suggested to set the timer's description before adding the timer to a process definition, process instance, node or node instance.

  Parameters:
    `description` - The description of this timer.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance. This exception is also thrown when the supplied description is invalid or `null`.
  See Also:
    `getDescription()`

### getDescription

    public java.lang.String getDescription()
                                    throws ModelException

  Returns the description of this timer definition. The description field can contain a description of the actions to be performed by this timer. Returns an empty `String` if no description is defined.

  Returns:
    A `String` containing the description of this timer.
  Throws:
    `ModelException`

### getId

    public long getId()
               throws ModelException

  Returns this timer's unique identifier. Each timer in a process definition in Interstage BPM is identified by a unique ID. The ID is allocated automatically by the server when the `TimerDef` is added to a process definition. If timer is not added to a process definition, this method returns -1. The sequencing of ID numbers does not necessarily correlate with the order the timers are started and fired.

  Returns:
    The ID of the timer.
  Throws:
    `ModelException`

### setType

    public void setType(int timerType)
                 throws ModelException

  Sets the type for this timer definition. The parameter must be one of the constants defined in the `TimerDef` interface such as `ABSOLUTE`.

  It is suggested to set the timer's type before adding the timer to a process definition, process instance, node or node instance.

  Parameters:
    `timerType` - The new type for the timer definition.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance.
  See Also:
    `getType()`

### getType

    public int getType()
                throws ModelException

  Returns the current type of this timer definition as defined in the `TimerDef` interface by constants such as `ABSOLUTE`.

  See the class documentation of this interface for details on timer types.

  Returns:
    The integer constant specifying the type of this timer or -1 if no type is defined.
  Throws:
    `ModelException`

### setTime

    public void setTime(java.lang.String milliSeconds)
                 throws ModelException

  Sets the name of User Defined Attribute (UDA) that contains the period of time before this timer expires in milliseconds. The milliseconds specified by the supplied UDA must be defined as `long` value.

  If the type of this timer definition is `ABSOLUTE`, the time is measured in milliseconds since January 1, 1970, 00:00:00. You can convert this long data element into a recognizable representation of the date using methods in `java.util.Date`.

  The name of UDA must not be longer than specified in `DataItemRef.MAX_DATA_REF_NAME_LENGTH`.

  It is suggested to set the timer's UDA before adding the timer to a process definition, process instance, node or node instance.

  Parameters:
    `milliSeconds` - The UDA's name that contains the time period in milliseconds before the timer expires.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance. This exception is also thrown when the supplied UDA name is invalid or `null`.
  See Also:
    `getTime()`

### getTime

    public java.lang.String getTime()
                             throws ModelException

  Returns the name of the User Defined Attribute (UDA) that will contain the period of time in milliseconds after which this timer expires. If no time is defined, an empty `String` is returned.

  Returns:
    Returns The UDA's name that contains the period of time after which the timer expires.
  Throws:
    `ModelException`

### addTimerAction

    public TimerAction addTimerAction(TimerAction action)
                               throws ModelException

  Adds a `TimerAction` that specifies a `JavaActionSet` to this timer definition. The defined `JavaActionSet` of this action is executed when this timer expires.

  This method is not supported if the timer is still added to a process definition, process instance, node or node instance.

  Parameters:
    `action` - The `TimerAction` to be added.
  Returns:
    The `TimerAction` object that has been added to this timer definition.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance.
  See Also:
    `getTimerActions()`, `JavaActionSet`

### addTimerAction

    public TimerAction addTimerAction(int actionType)
                               throws ModelException

  Deprecated. Only the type JAVAACTION of TimerActions is supported

  Adds a new `TimerAction` object of the specified type to this `TimerDef`. The possible types are defined in the `TimerAction` interface such as `SENDMAIL`. The returned object can be used for further specifications.

  Parameters:
    `actionType` - The integer constant specifying the type of the `TimerAction` to be created.
  Returns:
    The newly created `TimerAction` object.
  Throws:
    `ModelException`

### getTimerActions

    public TimerAction[] getTimerActions()
                                  throws ModelException

  Returns all `TimerAction` objects that are attached to this timer definition. If there are none, an empty array is returned.

  Returns:
    All `TimerAction` objects associated with this timer definition.
  Throws:
    `ModelException`

### removeTimerAction

    public void removeTimerAction(TimerAction ta)
                           throws ModelException

  Removes the specified `TimerAction` object from this timer definition.

  This method is not supported if the timer is still added to a process definition, process instance, node or node instance.

  Parameters:
    `ta` - The `TimerAction` object to be removed.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance.
  See Also:
    `addTimerAction(TimerAction)`

### reorderTimerActions

    public void reorderTimerActions(TimerAction[] tas)
                             throws ModelException

  Adds and schedules the `TimerAction` objects to be fired in the user-defined sequence.

  This method is not supported if the timer is still added to a process definition, process instance, node or node instance.

  Parameters:
    `tas` - An array of `TimerAction` objects to be added, passed in the specified firing sequence.
  Throws:
    `ModelException` - Thrown when this timer definition is still associated with a process definition, process instance, node or node instance.

### isPeriodic

    public boolean isPeriodic()
                       throws ModelException

  Indicates whether this timer definition is a Periodic timer.

  Returns:
    `true` if the timer type is periodic; `false` otherwise.
  Throws:
    `ModelException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD