flux
Interface TimerTrigger
- All Superinterfaces:
- Action, java.lang.Cloneable, RuntimeDataMap, java.io.Serializable, Trigger
public interface TimerTrigger
- extends Trigger
Fires triggers at scheduled dates and times. Unlike some other triggers, a
timer trigger can be expedited. When being expedited, a timer trigger does
not update its internal state, such as decrementing the running count. When
being expedited, a timer trigger simply fires without decrementing the
running count or updating any other state.
The rationale for not updating the timer trigger state is as follows. Suppose
a timer trigger fires at the beginning of every month for 10 months. Further
suppose that a user wants to expedite this timer trigger mid-month. If the
running count were decremented when the timer trigger was expedited, the job
would finish one month early, which would be unexpected behavior.
At a minimum, either a Time Expression or a scheduled trigger date must be
set when initializing a timer trigger.
When a Timer Trigger executes, it throws an EngineException if its Time
Expression, if any, does not guarantee that newly scheduled trigger dates are
strictly in the future. Cron-style Time Expressions make this guarantee;
however, it is possible for Relative Time Expressions to generate newly
scheduled trigger dates that are older than the last scheduled trigger date.
This behavior is needed to guarantee Timer Trigger firings always move
forward in time.
The Timer Trigger returns its result in the flow context variable "RESULT". The
following table contains more information on accessing and using the result.
| Flow Context Variable |
Field |
Java Type |
Description |
| RESULT | result | boolean | A boolean value indicating whether the timer trigger has expired. The trigger can expire if its maximum count is reached, or it reaches the end date or the end time expression is satisfied. If this value is true, the timer trigger has not expired. If the value is false, the timer trigger has expired. |
- Author:
- Copyright 2014 Flux Corporation. All rights reserved.
|
Field Summary |
static int |
INFINITY
Use this constant in the setCount() method to allow the timer trigger to
run forever or until the end date. |
|
Method Summary |
Flow |
addFlow(Action action)
The flow that is followed when this Timer Trigger fires successfully. |
void |
expire()
Resets the state of this timer trigger as though it had expired and control
had flowed down the expiration path. |
AllowableBusinessInterval |
getBusinessInterval()
Deprecated. Use TimerTrigger.getBusinessIntervalNamespace. Deprecated in
Flux 8.0. Will be removed in a future release. |
java.lang.String |
getBusinessIntervalNamespace()
Returns the optional repository namespace to the business interval associated with this
trigger. |
long |
getCount()
Returns the total number of times this timer trigger is scheduled to fire. |
java.util.Date |
getEndDate()
Returns the date when this timer trigger expires. |
java.lang.String |
getEndTimeExpression()
Returns a time expression, when applied to the date when this timer trigger
is created, that determines when this timer trigger expires. |
java.util.Date |
getLastTriggerDate()
Returns the date when this trigger was last scheduled to fire. |
java.lang.String |
getLateTimeWindow()
Returns a time expression that indicates the latest a timer trigger may
fire past its scheduled firing time without being skipped. |
boolean |
getMakeupFiring()
Indicates whether makeup firings are enabled. |
long |
getRemainingCount()
Returns the number of remaining scheduled firings for this timer trigger. |
java.util.Date |
getScheduledTriggerDate()
Returns the date when this timer trigger is scheduled to fire. |
java.lang.String |
getTimeExpression()
Returns the time expression that governs how frequently this timer trigger
fires. |
java.util.TimeZone |
getTimeZone()
Returns the time zone associated with this timer trigger. |
void |
setBusinessInterval(AllowableBusinessInterval businessInterval)
Deprecated. Use TimerTrigger.setBusinessIntervalNamespace. Deprecated in
Flux 8.0. Will be removed in a future version. |
void |
setBusinessIntervalNamespace(java.lang.String businessIntervalNamespace)
Sets a repository namespace to a business interval, which is
consulted when time expressions are evaluated. |
void |
setCount(long count)
Sets the total number of times this timer trigger is scheduled to fire. |
void |
setEndDate(java.util.Date endDate)
Sets the date such that the timer trigger expires on or after the given end
date. |
void |
setEndTimeExpression(java.lang.String timeExpression)
Applies the specified time expression to the current date to determine when
this timer trigger expires. |
void |
setExpirationFlow(Action action)
The flow that is followed when this timer trigger expires. |
void |
setLateTimeWindow(java.lang.String timeExpression)
Sets a time expression that indicates the latest a timer trigger may fire
past its scheduled firing time without being skipped. |
void |
setLateTimeWindow(java.lang.String timeExpression,
boolean enableMakeupFiring)
Sets a time expression that indicates the latest a timer trigger may fire
past its scheduled firing time without being skipped. |
void |
setScheduledTriggerDate(java.util.Date scheduledTriggerDate)
Sets the date when this timer trigger is next scheduled to fire. |
void |
setTimeExpression(java.lang.String timeExpression)
Sets the time expression that governs how frequently this timer trigger
fires. |
void |
setTimeZone(java.util.TimeZone timeZone)
Sets the time zone associated with this timer trigger. |
| Methods inherited from interface flux.Action |
addFlow, addSignalFlow, clone, execute, getDescription, getFlows, getHiddenVariableNames, getJoinExpression, getName, getPostscript, getPostscriptLanguage, getPrescript, getPrescriptLanguage, getResultInfo, getSignalsToMonitor, getTimeoutBusinessInterval, getTimeoutBusinessIntervalNamespace, getTimeoutExpression, getVariableManager, isEndOfRun, isJoinPoint, isSkippable, isStartAction, isStartOfRun, isTransactionBreak, removeFlow, reset, setDescription, setElseFlow, setEndOfRun, setErrorFlow, setErrorFlowWithoutRollback, setErrorFlowWithRollback, setJoinExpression, setJoinPoint, setName, setPostscript, setPostscriptLanguage, setPrescript, setPrescriptLanguage, setSignalsToMonitor, setSkippable, setStartAction, setStartOfRun, setTimeoutBusinessInterval, setTimeoutBusinessIntervalNamespace, setTimeoutExpression, setTimeoutFlow, setTransactionBreak, verify, verifyOnClient |
INFINITY
static final int INFINITY
- Use this constant in the setCount() method to allow the timer trigger to
run forever or until the end date.
- See Also:
setCount(long),
Constant Field Values
addFlow
Flow addFlow(Action action)
- The flow that is followed when this Timer Trigger fires successfully.
Delegates to addFlow(Action, EngineHelper.useLastResult("result")).
To add a flow that is followed under different conditions with this Timer
Trigger, use a different flow condition by calling addFlow(Action action,
String condition). For example, to unconditionally follow a flow to a
certain action, call TimerTrigger.addFlow(action, "true"). Alternately, to
follow a flow after an unsuccessful firing of this Timer Trigger, call
TimerTrigger.setElseFlow(action).
Note that with actions other than Timer Trigger, addFlow(Action) may not
delegate to addFlow(Action, EngineHelper.useLastResult("result")). Most
actions do not delegate in this manner. When using these other actions, use
caution to ensure the flow condition is as intended.
- Specified by:
addFlow in interface Action
- Parameters:
action - The flow that is followed when this timer trigger fires.
- Returns:
- The newly created flow.
- See Also:
Action.addFlow(Action, String),
EngineHelper.useLastResult(String)
expire
void expire()
- Resets the state of this timer trigger as though it had expired and control
had flowed down the expiration path. Useful for flow charts that use timer
triggers in such a way that timer trigger expirations must be performed at
points in the flow chart away from the timer trigger itself.
getBusinessInterval
@Deprecated
AllowableBusinessInterval getBusinessInterval()
- Deprecated. Use TimerTrigger.getBusinessIntervalNamespace. Deprecated in
Flux 8.0. Will be removed in a future release.
- Returns the optional business interval associated with this trigger.
- Returns:
- The optional business interval.
getBusinessIntervalNamespace
java.lang.String getBusinessIntervalNamespace()
- Returns the optional repository namespace to the business interval associated with this
trigger.
- Returns:
- The optional business interval namespace.
getCount
long getCount()
- Returns the total number of times this timer trigger is scheduled to fire.
Returns -1 if it is scheduled to fire indefinitely.
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Returns:
- The total number of times this timer trigger is scheduled to fire.
- See Also:
getRemainingCount(),
TimerTrigger.Timer_Result.result
getEndDate
java.util.Date getEndDate()
- Returns the date when this timer trigger expires. Timer triggers scheduled
to fire on or after this date are expired. Returns null if there is no
expiration date. However, although an expiration date may not exist, this
timer trigger may expire when its count is exhausted.
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Returns:
- The date when this timer trigger expires.
- See Also:
TimerTrigger.Timer_Result.result
getEndTimeExpression
java.lang.String getEndTimeExpression()
- Returns a time expression, when applied to the date when this timer trigger
is created, that determines when this timer trigger expires.
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Returns:
- The time expression that determines when this timer trigger
expires.
- See Also:
TimerTrigger.Timer_Result.result
getLastTriggerDate
java.util.Date getLastTriggerDate()
- Returns the date when this trigger was last scheduled to fire.
- Returns:
- The date when this trigger was last scheduled to fire.
getLateTimeWindow
java.lang.String getLateTimeWindow()
- Returns a time expression that indicates the latest a timer trigger may
fire past its scheduled firing time without being skipped. For example, a
late time window of "+5m" means that a timer trigger may fire up to five
minutes late. If the scheduled firing is more than five minutes late, that
firing is skipped.
By default, there is a late time window of +3m, three minutes. Also enabled
by default is the makeup firing setting. With these two default settings
enabled, the default behavior is to skip all scheduled firings that are
more than three minutes late except for the very last
firing, which will be executed.
If the late time window is set to null, then all scheduled firings are
executed, regardless of how late they are.
Fore more information on how the makeup firing setting interacts with the
late time window setting, see setLateTimeWindow().
- Returns:
- A time expression that indicates the latest a timer trigger may
fire past its scheduled firing time without being skipped. Defaults
to "+3m", three minutes. If null or empty, the timer trigger may
fire arbitrarily late.
- See Also:
setLateTimeWindow(String, boolean)
getMakeupFiring
boolean getMakeupFiring()
- Indicates whether makeup firings are enabled. See setLateTimeWindow() for
further information.
- Returns:
- Whether makeup firings are enabled.
- See Also:
setLateTimeWindow(String, boolean)
getRemainingCount
long getRemainingCount()
- Returns the number of remaining scheduled firings for this timer trigger.
Returns -1 if it is scheduled to fire indefinitely. For example, if the
total number of scheduled firings is 3 and this trigger has fired once,
then getRemainingCount() returns 2.
- Returns:
- The number of remaining scheduled firings.
- See Also:
getCount(),
setCount(long)
getScheduledTriggerDate
java.util.Date getScheduledTriggerDate()
- Returns the date when this timer trigger is scheduled to fire. After this
timer trigger fires at the scheduled trigger date, the next scheduled
trigger date is calculated by applying the time expression to it, if a time
expression has been set.
If the scheduled trigger date is not set explicitly, returns null if this
method is called after the job has been added to the engine but before the
engine has had a chance to start running the job, reach this timer trigger,
and set the scheduled trigger date.
- Returns:
- The date when this timer trigger is scheduled to fire.
getTimeExpression
java.lang.String getTimeExpression()
- Returns the time expression that governs how frequently this timer trigger
fires.
- Returns:
- the time expression that governs how frequently this timer trigger
fires.
getTimeZone
java.util.TimeZone getTimeZone()
- Returns the time zone associated with this timer trigger. If no time zone
is explicitly set, the default time zone from the client side is used. Note
that if the client side is in a different time zone than the server side,
this timer trigger fires according to the time zone where the job
originates (the client side).
If the computer, operating system, or JVM is misconfigured, the local time
zone may be returned in a generic format, such as "GMT+05:30", instead of
the proper form, such as "Asia/Calcutta". In this case, the time zone is
saved in the generic format, such as "GMT+05:30". When this generic format
is used, any daylight savings information is lost. However, in areas of the
world such as India where daylight savings is never observed, then no
information is lost.
Finally, if a custom time zone is created and used, its ID must match the
generic time zone format, such as "GMT+05:30", in order for the Flux engine
to store the custom time zone. Note, however, that any daylight savings
information in the custom time zone cannot be stored, due to limitations in
the JDK time zone API.
- Returns:
- The time zone associated with this timer trigger.
- See Also:
TimeZone
setBusinessInterval
@Deprecated
void setBusinessInterval(AllowableBusinessInterval businessInterval)
- Deprecated. Use TimerTrigger.setBusinessIntervalNamespace. Deprecated in
Flux 8.0. Will be removed in a future version.
- Registers a business interval with this timer trigger, which is consulted
when Time Expressions are evaluated.
- Parameters:
businessInterval - The business interval to use.
setBusinessIntervalNamespace
void setBusinessIntervalNamespace(java.lang.String businessIntervalNamespace)
- Sets a repository namespace to a business interval, which is
consulted when time expressions are evaluated.
- Parameters:
businessIntervalNamespace - A repository namespace to a business interval, which is
consulted when time expressions are evaluated.
setCount
void setCount(long count)
- Sets the total number of times this timer trigger is scheduled to fire.
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Parameters:
count - The total number of times this timer trigger is scheduled to
fire.- See Also:
getRemainingCount(),
TimerTrigger.Timer_Result.result
setEndDate
void setEndDate(java.util.Date endDate)
- Sets the date such that the timer trigger expires on or after the given end
date. A null end date indicates that there is no expiration date. However,
although an expiration date may not exist, this timer trigger may expire
when its count is exhausted.
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Parameters:
endDate - The date such that the timer trigger expires on or after the
given end date.- See Also:
TimerTrigger.Timer_Result.result
setEndTimeExpression
void setEndTimeExpression(java.lang.String timeExpression)
throws EngineException
- Applies the specified time expression to the current date to determine when
this timer trigger expires. The specified time expression may not contain a
"for loop".
Note that when a timer trigger expires, it fires and the result object's
"result" field is set to false. This kind of expiration firing does not
occur before the count expires, the end date occurs, or the end time
expression is reached.
- Parameters:
timeExpression - Indicates when this timer trigger expires.
- Throws:
EngineException - If a system error occurs.- See Also:
TimerTrigger.Timer_Result.result
setExpirationFlow
void setExpirationFlow(Action action)
- The flow that is followed when this timer trigger expires. Delegates to
setElseFlow().
- Parameters:
action - The flow that is followed when this timer trigger expires.
setLateTimeWindow
void setLateTimeWindow(java.lang.String timeExpression)
throws EngineException
- Sets a time expression that indicates the latest a timer trigger may fire
past its scheduled firing time without being skipped. For example, a late
time window of "+5m" means that a job may fire up to five minutes late. If
the job is more than five minutes late, that job firing is skipped. By
default, the timer trigger always fires late jobs, regardless of how late
they may be.
The specified time expression may not contain a "for loop".
- Parameters:
timeExpression - A time expression. If null or empty, the timer
trigger may fire arbitrarily late.
- Throws:
EngineException - If a system error occurs.
setLateTimeWindow
void setLateTimeWindow(java.lang.String timeExpression,
boolean enableMakeupFiring)
throws EngineException
- Sets a time expression that indicates the latest a timer trigger may fire
past its scheduled firing time without being skipped. For example, a late
time window of "+5m" means that a timer trigger may fire up to five minutes
late. If the scheduled firing is more than five minutes late, that firing
is skipped.
By default, there is a late time window of +3m, three minutes. Also enabled
by default is the makeup firing setting. With these two default settings
enabled, the default behavior is to skip all scheduled firings that are
more than three minutes late except for the very last
firing, which will be executed.
The enableMakeupFiring parameter allows the timer trigger to make up a
single firing even if the late time window has elapsed. If the late time
window is not empty, makeup firing is enabled, and the timer trigger's late
time window has elapsed, the timer trigger will fire a single makeup
firing. The enableMakeupFiring ensures that one (and only one) makeup
firing occurs after the timer trigger has passed its late time window.
For example, suppose a timer trigger is scheduled to fire once a day. If
the engine goes down for a month and the late time window is set to "+1d"
(one day), there will be several missed firings when the engine begins
running again. If makeup firing is not enabled, none of these missed
firings will execute. On the other hand, if makeup firing is enabled, the
last late firing will indeed execute.
The enableMakeupFiring parameter is useful if the engine is down for an
extended period of time and multiple firings are missed, but only the last
missed firing should still be executed.
The specified time expression may not contain a "for loop".
- Parameters:
timeExpression - A time expression. If null or empty, the timer
trigger may fire arbitrarily late.enableMakeupFiring - Allows a "make up" firing to occur.
- Throws:
EngineException - If a system error occurs.
setScheduledTriggerDate
void setScheduledTriggerDate(java.util.Date scheduledTriggerDate)
- Sets the date when this timer trigger is next scheduled to fire. After this
timer trigger fires at the scheduled trigger date, the next scheduled
trigger date is calculated by applying the time expression to it, if a time
expression has been set.
- Parameters:
scheduledTriggerDate - The date when this timer trigger is next
scheduled to fire.
setTimeExpression
void setTimeExpression(java.lang.String timeExpression)
throws EngineException
- Sets the time expression that governs how frequently this timer trigger
fires.
- Parameters:
timeExpression - The time expression that governs how frequently this
timer trigger fires.
- Throws:
EngineException - If a system error occurs.
setTimeZone
void setTimeZone(java.util.TimeZone timeZone)
- Sets the time zone associated with this timer trigger. If no time zone is
explicitly set, the default time zone from the client side is used. Note
that if the client side is in a different time zone than the server side,
this timer trigger fires according to the time zone where the job
originates (the client side).
If the computer, operating system, or JVM is misconfigured, the local time
zone may be returned in a generic format, such as "GMT+05:30", instead of
the proper form, such as "Asia/Calcutta". In this case, the time zone is
saved in the generic format, such as "GMT+05:30". When this generic format
is used, any daylight savings information is lost. However, in areas of the
world such as India where daylight savings is never observed, then no
information is lost.
Finally, if a custom time zone is created and used, its ID must match the
generic time zone format, such as "GMT+05:30", in order for the Flux engine
to store the custom time zone. Note, however, that any daylight savings
information in the custom time zone cannot be stored, due to limitations in
the JDK time zone API.
- Parameters:
timeZone - The time zone associated with this timer trigger.- See Also:
TimeZone
© 2014 Flux Corporation. All rights reserved.