public class SegmentedTimeline extends java.lang.Object implements Timeline, java.lang.Cloneable, java.io.Serializable
Timeline
that implements a "segmented" timeline with included,
excluded and exception segments.
A Timeline will present a series of values to be used for an axis. Each Timeline must provide transformation methods between domain values and timeline values.
A timeline can be used as parameter to a
DateAxis
to define the values that this axis
supports. This class implements a timeline formed by segments of equal
length (ex. days, hours, minutes) where some segments can be included in the
timeline and others excluded. Therefore timelines like "working days" or
"working hours" can be created where non-working days or non-working hours
respectively can be removed from the timeline, and therefore from the axis.
This creates a smooth plot with equal separation between all included
segments.
Because Timelines were created mainly for Date related axis, values are
represented as longs instead of doubles. In this case, the domain value is
just the number of milliseconds since January 1, 1970, 00:00:00 GMT as
defined by the getTime() method of Date
.
In this class, a segment is defined as a unit of time of fixed length. Examples of segments are: days, hours, minutes, etc. The size of a segment is defined as the number of milliseconds in the segment. Some useful segment sizes are defined as constants in this class: DAY_SEGMENT_SIZE, HOUR_SEGMENT_SIZE, FIFTEEN_MINUTE_SEGMENT_SIZE and MINUTE_SEGMENT_SIZE.
Segments are group together to form a Segment Group. Each Segment Group will contain a number of Segments included and a number of Segments excluded. This Segment Group structure will repeat for the whole timeline.
For example, a working days SegmentedTimeline would be formed by a group of 7 daily segments, where there are 5 included (Monday through Friday) and 2 excluded (Saturday and Sunday) segments.
Following is a diagram that explains the major attributes that define a segment. Each box is one segment and must be of fixed length (ms, second, hour, day, etc).
start time | v 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 ... +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+... | | | | | |EE|EE| | | | | |EE|EE| | | | | |EE|EE| +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+... \____________/ \___/ \_/ \/ | | included excluded segment segments segments size \_________ _______/ \/ segment groupLegend:
In the example, the following segment attributes are presented:
Exception Segments are allowed. These exception segments are defined as segments that would have been in the included segments of the Segment Group, but should be excluded for special reasons. In the previous working days SegmentedTimeline example, holidays would be considered exceptions.
Additionally the startTime
, or start of the first Segment of
the smallest segment group needs to be defined. This startTime could be
relative to January 1, 1970, 00:00:00 GMT or any other date. This creates a
point of reference to start counting Segment Groups. For example, for the
working days SegmentedTimeline, the startTime
could be
00:00:00 GMT of the first Monday after January 1, 1970. In this class, the
constant FIRST_MONDAY_AFTER_1900 refers to a reference point of the first
Monday of the last century.
A SegmentedTimeline can include a baseTimeline. This combination of timelines allows the creation of more complex timelines. For example, in order to implement a SegmentedTimeline for an intraday stock trading application, where the trading period is defined as 9:00 AM through 4:00 PM Monday through Friday, two SegmentedTimelines are used. The first one (the baseTimeline) would be a working day SegmentedTimeline (daily timeline Monday through Friday). On top of this baseTimeline, a second one is defined that maps the 9:00 AM to 4:00 PM period. Because the baseTimeline defines a timeline of Monday through Friday, the resulting (combined) timeline will expose the period 9:00 AM through 4:00 PM only on Monday through Friday, and will remove all other intermediate intervals.
Two factory methods newMondayThroughFridayTimeline() and newFifteenMinuteTimeline() are provided as examples to create special SegmentedTimelines.
DateAxis
,
Serialized FormModifier and Type | Class and Description |
---|---|
protected class |
SegmentedTimeline.BaseTimelineSegmentRange
Special
SegmentRange that came from the BaseTimeline. |
class |
SegmentedTimeline.Segment
Internal class to represent a valid segment for this timeline.
|
protected class |
SegmentedTimeline.SegmentRange
Private internal class to represent a range of segments.
|
Modifier and Type | Field and Description |
---|---|
static long |
DAY_SEGMENT_SIZE
Defines a day segment size in ms.
|
static java.util.TimeZone |
DEFAULT_TIME_ZONE
Deprecated.
As of 1.0.7. When the default time zone is required,
just call
TimeZone.getDefault() . |
static long |
FIFTEEN_MINUTE_SEGMENT_SIZE
Defines a 15-minute segment size in ms.
|
static long |
FIRST_MONDAY_AFTER_1900
Deprecated.
As of 1.0.7. This field doesn't take into account changes
to the default time zone.
|
static long |
HOUR_SEGMENT_SIZE
Defines a one hour segment size in ms.
|
static long |
MINUTE_SEGMENT_SIZE
Defines a one-minute segment size in ms.
|
static java.util.TimeZone |
NO_DST_TIME_ZONE
Deprecated.
As of 1.0.7. This field is initialised based on the
default time zone, and doesn't take into account subsequent
changes to the default.
|
Constructor and Description |
---|
SegmentedTimeline(long segmentSize,
int segmentsIncluded,
int segmentsExcluded)
Constructs a new segmented timeline, optionaly using another segmented
timeline as its base.
|
Modifier and Type | Method and Description |
---|---|
void |
addBaseTimelineException(java.util.Date date)
Adds a segment relative to the baseTimeline as an exception.
|
void |
addBaseTimelineException(long domainValue)
Adds a segment relative to the baseTimeline as an exception.
|
void |
addBaseTimelineExclusions(long fromBaseDomainValue,
long toBaseDomainValue)
Adds all excluded segments from the BaseTimeline as exceptions to our
timeline.
|
void |
addException(java.util.Date exceptionDate)
Adds a segment as an exception.
|
void |
addException(long millisecond)
Adds a segment as an exception.
|
void |
addException(long fromDomainValue,
long toDomainValue)
Adds a segment range as an exception.
|
void |
addExceptions(java.util.List exceptionList)
Adds a list of dates as segment exceptions.
|
java.lang.Object |
clone()
Returns a clone of the timeline.
|
boolean |
containsDomainRange(java.util.Date dateDomainValueStart,
java.util.Date dateDomainValueEnd)
Returns
true if a range of values are contained in the
timeline. |
boolean |
containsDomainRange(long domainValueStart,
long domainValueEnd)
Returns
true if a range of values are contained in the
timeline. |
boolean |
containsDomainValue(java.util.Date date)
Returns
true if a value is contained in the timeline. |
boolean |
containsDomainValue(long millisecond)
Returns
true if a value is contained in the timeline. |
boolean |
equals(java.lang.Object o)
Returns true if we are equal to the parameter
|
static long |
firstMondayAfter1900()
Returns the milliseconds for midnight of the first Monday after
1-Jan-1900, ignoring daylight savings.
|
boolean |
getAdjustForDaylightSaving()
Returns the flag that controls whether or not the daylight saving
adjustment is applied.
|
SegmentedTimeline |
getBaseTimeline()
Returns our baseTimeline, or
null if none. |
java.util.Date |
getDate(long value)
Converts a millisecond value into a
Date object. |
long |
getExceptionSegmentCount(long fromMillisecond,
long toMillisecond)
Returns the number of exception segments wholly contained in the
(fromDomainValue, toDomainValue) interval.
|
java.util.List |
getExceptionSegments()
Returns a list of all the exception segments.
|
int |
getGroupSegmentCount()
Returns the number of segments in a segment group.
|
SegmentedTimeline.Segment |
getSegment(java.util.Date date)
Returns a segment that contains a date.
|
SegmentedTimeline.Segment |
getSegment(long millisecond)
Returns a segment that contains a domainValue.
|
int |
getSegmentsExcluded()
Returns the number of segments excluded per segment group.
|
long |
getSegmentsExcludedSize()
Returns the size in milliseconds of the segments excluded per segment
group.
|
long |
getSegmentsGroupSize()
Returns the size in milliseconds of a segment group.
|
int |
getSegmentsIncluded()
Returns the number of segments included per segment group.
|
long |
getSegmentsIncludedSize()
Returns the size in ms of the segments included per segment group.
|
long |
getSegmentSize()
Returns the size of one segment in ms.
|
long |
getStartTime()
Returns the start time for the timeline.
|
long |
getTime(java.util.Date date)
Special method that handles conversion between the Default Time Zone and
a UTC time zone with no DST.
|
long |
getTimeFromLong(long date)
Converts a date/time value to take account of daylight savings time.
|
int |
hashCode()
Returns a hash code for this object.
|
static SegmentedTimeline |
newFifteenMinuteTimeline()
Factory method to create a 15-min, 9:00 AM thought 4:00 PM, Monday
through Friday SegmentedTimeline.
|
static SegmentedTimeline |
newMondayThroughFridayTimeline()
Factory method to create a Monday through Friday SegmentedTimeline.
|
void |
setAdjustForDaylightSaving(boolean adjust)
Sets the flag that controls whether or not the daylight saving adjustment
is applied.
|
void |
setBaseTimeline(SegmentedTimeline baseTimeline)
Sets the base timeline.
|
void |
setExceptionSegments(java.util.List exceptionSegments)
Sets the exception segments list.
|
void |
setStartTime(long millisecond)
Sets the start time for the timeline.
|
long |
toMillisecond(long timelineValue)
Translates a value relative to the timeline into a millisecond.
|
long |
toTimelineValue(java.util.Date date)
Translates a date into a value relative to the segmented timeline.
|
long |
toTimelineValue(long millisecond)
Translates a value relative to the domain value (all Dates) into a value
relative to the segmented timeline.
|
public static final long DAY_SEGMENT_SIZE
public static final long HOUR_SEGMENT_SIZE
public static final long FIFTEEN_MINUTE_SEGMENT_SIZE
public static final long MINUTE_SEGMENT_SIZE
public static long FIRST_MONDAY_AFTER_1900
public static java.util.TimeZone NO_DST_TIME_ZONE
public static java.util.TimeZone DEFAULT_TIME_ZONE
TimeZone.getDefault()
.public SegmentedTimeline(long segmentSize, int segmentsIncluded, int segmentsExcluded)
segmentSize
- the size of a segment in ms. This time unit will be
used to compute the included and excluded segments of the
timeline.segmentsIncluded
- Number of consecutive segments to include.segmentsExcluded
- Number of consecutive segments to exclude.public static long firstMondayAfter1900()
public static SegmentedTimeline newMondayThroughFridayTimeline()
The startTime
of the resulting timeline will be midnight
of the first Monday after 1/1/1900.
public static SegmentedTimeline newFifteenMinuteTimeline()
This timeline uses a segmentSize of FIFTEEN_MIN_SEGMENT_SIZE. The segment group is defined as 28 included segments (9:00 AM through 4:00 PM) and 68 excluded segments (4:00 PM through 9:00 AM the next day).
In order to exclude Saturdays and Sundays it uses a baseTimeline that only includes Monday through Friday days.
The startTime
of the resulting timeline will be 9:00 AM
after the startTime of the baseTimeline. This will correspond to 9:00 AM
of the first Monday after 1/1/1900.
public boolean getAdjustForDaylightSaving()
public void setAdjustForDaylightSaving(boolean adjust)
adjust
- the flag.public void setStartTime(long millisecond)
millisecond
- the start time (encoded as in java.util.Date).public long getStartTime()
public int getSegmentsExcluded()
public long getSegmentsExcludedSize()
public int getGroupSegmentCount()
public long getSegmentsGroupSize()
public int getSegmentsIncluded()
public long getSegmentsIncludedSize()
public long getSegmentSize()
public java.util.List getExceptionSegments()
public void setExceptionSegments(java.util.List exceptionSegments)
exceptionSegments
- the exception segments.public SegmentedTimeline getBaseTimeline()
null
if none.public void setBaseTimeline(SegmentedTimeline baseTimeline)
baseTimeline
- the timeline.public long toTimelineValue(long millisecond)
toTimelineValue
in interface Timeline
millisecond
- the millisecond (as encoded by java.util.Date).public long toTimelineValue(java.util.Date date)
toTimelineValue
in interface Timeline
date
- date relative to the domain.public long toMillisecond(long timelineValue)
toMillisecond
in interface Timeline
timelineValue
- the timeline value (in milliseconds).SegmentedTimeline
public long getTimeFromLong(long date)
date
- the milliseconds.public boolean containsDomainValue(long millisecond)
true
if a value is contained in the timeline.containsDomainValue
in interface Timeline
millisecond
- the value to verify.true
if value is contained in the timeline.public boolean containsDomainValue(java.util.Date date)
true
if a value is contained in the timeline.containsDomainValue
in interface Timeline
date
- date to verifytrue
if value is contained in the timelinepublic boolean containsDomainRange(long domainValueStart, long domainValueEnd)
true
if a range of values are contained in the
timeline. This is implemented verifying that all segments are in the
range.containsDomainRange
in interface Timeline
domainValueStart
- start of the range to verifydomainValueEnd
- end of the range to verifytrue
if the range is contained in the timelinepublic boolean containsDomainRange(java.util.Date dateDomainValueStart, java.util.Date dateDomainValueEnd)
true
if a range of values are contained in the
timeline. This is implemented verifying that all segments are in the
range.containsDomainRange
in interface Timeline
dateDomainValueStart
- start of the range to verifydateDomainValueEnd
- end of the range to verifytrue
if the range is contained in the timelinepublic void addException(long millisecond)
The segment is identified by a domainValue into any part of the segment. Therefore the segmentStart <= domainValue <= segmentEnd.
millisecond
- domain value to treat as an exceptionpublic void addException(long fromDomainValue, long toDomainValue)
The segment range is identified by a domainValue that begins a valid segment and ends with a domainValue that ends a valid segment. Therefore the range will contain all segments whose segmentStart <= domainValue and segmentEnd <= toDomainValue.
fromDomainValue
- start of domain range to treat as an exceptiontoDomainValue
- end of domain range to treat as an exceptionpublic void addException(java.util.Date exceptionDate)
The segment is identified by a Date into any part of the segment.
exceptionDate
- Date into the segment to exclude.public void addExceptions(java.util.List exceptionList)
The segment is identified by a Date into any part of the segment.
exceptionList
- List of Date objects that identify the segments to
exclude.public void addBaseTimelineException(long domainValue)
An exception segment is defined as a segment to exclude from what would otherwise be considered a valid segment of the timeline. An exception segment can not be contained inside an already excluded segment. If so, no action will occur (the proposed exception segment will be discarded).
The segment is identified by a domainValue into any part of the baseTimeline segment.
domainValue
- domain value to teat as a baseTimeline exception.public void addBaseTimelineException(java.util.Date date)
The segment is identified by a domainValue into any part of the segment. Therefore the segmentStart <= domainValue <= segmentEnd.
date
- date domain value to treat as a baseTimeline exceptionpublic void addBaseTimelineExclusions(long fromBaseDomainValue, long toBaseDomainValue)
fromBaseDomainValue
- Start of the range where exclusions will be
extracted.toBaseDomainValue
- End of the range to process.public long getExceptionSegmentCount(long fromMillisecond, long toMillisecond)
fromMillisecond
- the beginning of the interval.toMillisecond
- the end of the interval.public SegmentedTimeline.Segment getSegment(long millisecond)
index + segmentSize*m
will be returned for the smallest
m
possible.millisecond
- index into the segmentpublic SegmentedTimeline.Segment getSegment(java.util.Date date)
date + segmentSize*m
will be returned for the smallest
m
possible.date
- date into the segmentpublic boolean equals(java.lang.Object o)
equals
in class java.lang.Object
o
- Object to verify with ustrue
or false
public int hashCode()
hashCode
in class java.lang.Object
public long getTime(java.util.Date date)
date
- Date to convert to long.public java.util.Date getDate(long value)
Date
object.value
- the millisecond value.public java.lang.Object clone() throws java.lang.CloneNotSupportedException
clone
in class java.lang.Object
java.lang.CloneNotSupportedException
- ??.