Time sequences and time interval sequences can be defined using time units and/or time entity names. For example
[MON..FRI]
is equivalent to [MON..FRI/DAY#DAY] and defines a sequence of days Monday through Friday inclusively (see about
usage of # and inclusivity below).
Sequence compile is able to recognize this as a time sequence due to use of time entity names like MON or FRI. In most cases compiler also
can infer proper time units (e.g. in this case since MON and FRI are days of the week the step and span are inferred as DAY). Time entities of different size, in most cases, can be considered nested. For example a year [generally] consist of 12 months a month consist of four weeks, a week consist of seven days, a day consist of 24 hours etc. This allows for nested time sequences to be defined. For example (in delimited form):
[2014..2015/yr]:[APR..JUN]:[10/day]:[11..12/hour]
results in the following sequence
<Result Trigger="1:1=Thu Apr 10 11:00:00 PDT 2014"/>
<Result Trigger="2:2=Thu Apr 10 12:00:00 PDT 2014"/>
<Result Trigger="3:3=Sat May 10 11:00:00 PDT 2014"/>
<Result Trigger="4:4=Sat May 10 12:00:00 PDT 2014"/>
<Result Trigger="5:5=Tue Jun 10 11:00:00 PDT 2014"/>
<Result Trigger="6:6=Tue Jun 10 12:00:00 PDT 2014"/>
<Result Trigger="7:7=Fri Apr 10 11:00:00 PDT 2015"/>
<Result Trigger="8:8=Fri Apr 10 12:00:00 PDT 2015"/>
<Result Trigger="9:9=Sun May 10 11:00:00 PDT 2015"/>
<Result Trigger="10:10=Sun May 10 12:00:00 PDT 2015"/>
<Result Trigger="11:11=Wed Jun 10 11:00:00 PDT 2015"/>
<Result Trigger="12:12=Wed Jun 10 12:00:00 PDT 2015"/>
or in other words it selects
- 11th and 12th hours of each enclosing day which is
- 10th day of the enclosing month which is
- sequence of APR, MAY and JUN of enclosing year which is
- sequence of year 2014 and year 2015
The same sequence can be defined in structural form as
<year in="[2014..2015]">
<month in="[APR..JUN]">
<day eq="10">
<hour in="[11..12]"/>
</day>
</month>
</year>
or
<year from="2014" till="2015">
<month from="APR" till="JUN">
<day eq="10">
<hour from="11" till="12"/>
</day>
</month>
</year>
Note that outermost enclosing time interval is always based on the current time unless explicitly specified
(not yet implemented) or the time interval is absolute (e.g. year 2014 is an absolute interval while, month
MAY which is relative to the enclosing year). Thus unlimited sequence
[30../10sec]
run on Sep 15 19:01 will result in the following sequence of 10-seconds intervals (show first 10 values)
<Execute Warning="Stopped at 10:10">
<Result Trigger="1:1=Mon Sep 15 19:01:30 PDT 2014"/>
<Result Trigger="2:2=Mon Sep 15 19:01:40 PDT 2014"/>
<Result Trigger="3:3=Mon Sep 15 19:01:50 PDT 2014"/>
<Result Trigger="4:4=Mon Sep 15 19:02:00 PDT 2014"/>
<Result Trigger="5:5=Mon Sep 15 19:02:10 PDT 2014"/>
<Result Trigger="6:6=Mon Sep 15 19:02:20 PDT 2014"/>
<Result Trigger="7:7=Mon Sep 15 19:02:30 PDT 2014"/>
<Result Trigger="8:8=Mon Sep 15 19:02:40 PDT 2014"/>
<Result Trigger="9:9=Mon Sep 15 19:02:50 PDT 2014"/>
<Result Trigger="10:10=Mon Sep 15 19:03:00 PDT 2014"/>
</Execute>
it uses current time as a base point and selects time intervals relative to it.
About interval "sharpening":
As mentioned before, time intervals use current time as the base reference point. There is a choice in behaviour
of how this base point in time will be used. When time iterator sets enclosing interval boundaries as per sequence
definition, it may or may not align nested sub-intervals.
For example, a compact definition [SUN..SAT/DAY*HOUR] will generate a sequence of one hour long
intervals, one for each day of the week. It does not say however how these one hour intervals will be positioned
within each day. One solution is to preserve as much information as possible so if sequence iterator was
created let's say at 1:00 pm then each consequent interval will also start at 1:00 pm on each day. While it preserves
some information about point of origin, it is not necessarily the expected behaviour. When defining schedules, for
example, people don't expect it to behave differently depending on when schedule was started to execute.
Hence another solution is to always align generated nested intervals boundaries with correspondent enclosing
intervals. This is called interval "sharpening". That is, when sharp mode is engaged, the generated hourly
intervals will start on the correspondent day boundaries (i.e. at 00:00 each day) irrespective of the time when
sequence iterator was started. Note that sharpening occurs only within the base and all subordinate time units
(e.g. if sequence generates hourly intervals then hour, minute, second and millisecond of each interval will be
aligned with the enclosing time unit, correspondent daily interval in our example)
To engage sharp mode:
In compact style definitions an alternative separator '#' (sharp) can be used instead of '*' (soft) span delimiter.
In canonical form Sharp="true" attribute can be specified.
Note that compact mode delimiters can be used without their parameters (e.g. [SUN..SAT/DAY#] will generate a sequence
of sharp daily intervals for each day of the week)
Also different sequence types may have different default behaviour. For time intervals sharp mode is enabled by default.
About inclusive interval boundaries:
When working with numeric sequences the upper (i.e. "Till") sequence boundary is normally exclusive. That is
a definition [1..3] will generate the following values [1, 2]. Note that the upper limit is not a part of the sequence.
This is familiar and [hopefully] expected behaviour which is useful, for example for sequence concatenation (e.g.
a concatenation of [1..3] and [3..5] will result in expected [1,2,3,4]).
However, when working with time intervals (e.g. [MON..FRI]) the expected behaviour is inclusive (i.e. Friday should
be included in the sequence). Therefore the default behaviour of time interval sequences is set to be inclusive.
At this point there is no explicit control over this behaviour.
About time zones:
Time zone can be specified using '@' separator ("TimeZone" tag in extended form).
For example: [2014..2015/yr@UTC]:[APR..JUN]:[10/day]:[11..12/hour]
Time zone is parsed by java.util.TimeZone.getTimeZone(String id) where id is the string found after '@' separator.
Nested time interval iterators inherit time zone automatically so it can be set only on the first one (see example above)
In case of different time zones defined on different sub-sequences the result is undefined and may vary with implementation.