## org.jfree.chart.axis
Class SegmentedTimeline

    java.lang.Object
      org.jfree.chart.axis.SegmentedTimeline

All Implemented Interfaces:
  java.lang.Cloneable, java.io.Serializable, Timeline

public class SegmentedTimeline
extends java.lang.Object
implements Timeline, java.lang.Cloneable, java.io.Serializable

A `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 group

Legend:
<space> = Included segment
EE = Excluded segments in the base timeline

In the example, the following segment attributes are presented:

- segment size: the size of each segment in ms.
- start time: the start of the first segment of the first segment group to consider.
- included segments: the number of segments to include in the group.
- excluded segments: the number of segments to exclude in the group.

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 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.

Author:
  Bill Kelemen
See Also:
  `DateAxis`, Serialized Form

Nested Class Summary
`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.

Field Summary
`static long` `DAY_SEGMENT_SIZE` Defines a day segment size in ms.
`static java.util.TimeZone` `DEFAULT_TIME_ZONE` This is the default time zone where the application is running.
`static long` `FIFTEEN_MINUTE_SEGMENT_SIZE` Defines a 15-minute segment size in ms.
`static long` `FIRST_MONDAY_AFTER_1900` Utility constant that defines the startTime as the first monday after 1/1/1970.
`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` Utility TimeZone object that has no DST and an offset equal to the default TimeZone.

Constructor Summary
`SegmentedTimeline(long segmentSize, int segmentsIncluded, int segmentsExcluded)` Constructs a new segmented timeline, optionaly using another segmented timeline as its base.

Method Summary
`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
`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.
`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.

Methods inherited from class java.lang.Object
`finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DAY_SEGMENT_SIZE

    public static final long DAY_SEGMENT_SIZE

  Defines a day segment size in ms.

  See Also:
    Constant Field Values

### HOUR_SEGMENT_SIZE

    public static final long HOUR_SEGMENT_SIZE

  Defines a one hour segment size in ms.

  See Also:
    Constant Field Values

### FIFTEEN_MINUTE_SEGMENT_SIZE

    public static final long FIFTEEN_MINUTE_SEGMENT_SIZE

  Defines a 15-minute segment size in ms.

  See Also:
    Constant Field Values

### MINUTE_SEGMENT_SIZE

    public static final long MINUTE_SEGMENT_SIZE

  Defines a one-minute segment size in ms.

  See Also:
    Constant Field Values

### FIRST_MONDAY_AFTER_1900

    public static long FIRST_MONDAY_AFTER_1900

  Utility constant that defines the startTime as the first monday after 1/1/1970. This should be used when creating a SegmentedTimeline for Monday through Friday. See static block below for calculation of this constant.

### NO_DST_TIME_ZONE

    public static java.util.TimeZone NO_DST_TIME_ZONE

  Utility TimeZone object that has no DST and an offset equal to the default TimeZone. This allows easy arithmetic between days as each one will have equal size.

### DEFAULT_TIME_ZONE

    public static java.util.TimeZone DEFAULT_TIME_ZONE

  This is the default time zone where the application is running. See getTime() below where we make use of certain transformations between times in the default time zone and the no-dst time zone used for our calculations.

Constructor Detail

### SegmentedTimeline

    public SegmentedTimeline(long segmentSize,
                             int segmentsIncluded,
                             int segmentsExcluded)

  Constructs a new segmented timeline, optionaly using another segmented timeline as its base. This chaining of SegmentedTimelines allows further segmentation into smaller timelines. If a base

Parameters:
  `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.

Method Detail

### newMondayThroughFridayTimeline

    public static SegmentedTimeline newMondayThroughFridayTimeline()

  Factory method to create a Monday through Friday SegmentedTimeline.

  The `startTime` of the resulting timeline will be midnight of the firt Monday after 1/1/1900.

  Returns:
    A fully initialized SegmentedTimeline.

### newFifteenMinuteTimeline

    public static SegmentedTimeline newFifteenMinuteTimeline()

  Factory method to create a 15-min, 9:00 AM thought 4:00 PM, Monday through Friday SegmentedTimeline.

  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 firt Monday after 1/1/1900.

  Returns:
    A fully initialized SegmentedTimeline.

### getAdjustForDaylightSaving

    public boolean getAdjustForDaylightSaving()

  Returns the flag that controls whether or not the daylight saving adjustment is applied.

  Returns:
    A boolean.

### setAdjustForDaylightSaving

    public void setAdjustForDaylightSaving(boolean adjust)

  Sets the flag that controls whether or not the daylight saving adjustment is applied.

  Parameters:
    `adjust` - the flag.

### setStartTime

    public void setStartTime(long millisecond)

  Sets the start time for the timeline. This is the beginning of segment zero.

  Parameters:
    `millisecond` - the start time (encoded as in java.util.Date).

### getStartTime

    public long getStartTime()

  Returns the start time for the timeline. This is the beginning of segment zero.

  Returns:
    The start time.

### getSegmentsExcluded

    public int getSegmentsExcluded()

  Returns the number of segments excluded per segment group.

  Returns:
    The number of segments excluded.

### getSegmentsExcludedSize

    public long getSegmentsExcludedSize()

  Returns the size in milliseconds of the segments excluded per segment group.

  Returns:
    The size in milliseconds.

### getGroupSegmentCount

    public int getGroupSegmentCount()

  Returns the number of segments in a segment group. This will be equal to segments included plus segments excluded.

  Returns:
    The number of segments.

### getSegmentsGroupSize

    public long getSegmentsGroupSize()

  Returns the size in milliseconds of a segment group. This will be equal to size of the segments included plus the size of the segments excluded.

  Returns:
    The segment group size in milliseconds.

### getSegmentsIncluded

    public int getSegmentsIncluded()

  Returns the number of segments included per segment group.

  Returns:
    The number of segments.

### getSegmentsIncludedSize

    public long getSegmentsIncludedSize()

  Returns the size in ms of the segments included per segment group.

  Returns:
    The segment size in milliseconds.

### getSegmentSize

    public long getSegmentSize()

  Returns the size of one segment in ms.

  Returns:
    The segment size in milliseconds.

### getExceptionSegments

    public java.util.List getExceptionSegments()

  Returns a list of all the exception segments. This list is not modifiable.

  Returns:
    The exception segments.

### setExceptionSegments

    public void setExceptionSegments(java.util.List exceptionSegments)

  Sets the exception segments list.

  Parameters:
    `exceptionSegments` - the exception segments.

### getBaseTimeline

    public SegmentedTimeline getBaseTimeline()

  Returns our baseTimeline, or `null` if none.

  Returns:
    The base timeline.

### setBaseTimeline

    public void setBaseTimeline(SegmentedTimeline baseTimeline)

  Sets the base timeline.

  Parameters:
    `baseTimeline` - the timeline.

### toTimelineValue

    public long toTimelineValue(long millisecond)

  Translates a value relative to the domain value (all Dates) into a value relative to the segmented timeline. The values relative to the segmented timeline are all consecutives starting at zero at the startTime.

  Specified by:
    `toTimelineValue` in interface `Timeline`
  Parameters:
    `millisecond` - the millisecond (as encoded by java.util.Date).
  Returns:
    The timeline value.

### toTimelineValue

    public long toTimelineValue(java.util.Date date)

  Translates a date into a value relative to the segmented timeline. The values relative to the segmented timeline are all consecutives starting at zero at the startTime.

  Specified by:
    `toTimelineValue` in interface `Timeline`
  Parameters:
    `date` - date relative to the domain.
  Returns:
    The timeline value (in milliseconds).

### toMillisecond

    public long toMillisecond(long timelineValue)

  Translates a value relative to the timeline into a millisecond.

  Specified by:
    `toMillisecond` in interface `Timeline`
  Parameters:
    `timelineValue` - the timeline value (in milliseconds).
  Returns:
    The domain value (in milliseconds).
  See Also:
    `SegmentedTimeline`

### getTimeFromLong

    public long getTimeFromLong(long date)

  Converts a date/time value to take account of daylight savings time.

  Parameters:
    `date` - the milliseconds.
  Returns:
    The milliseconds.

### containsDomainValue

    public boolean containsDomainValue(long millisecond)

  Returns `true` if a value is contained in the timeline.

  Specified by:
    `containsDomainValue` in interface `Timeline`
  Parameters:
    `millisecond` - the value to verify.
  Returns:
    `true` if value is contained in the timeline.

### containsDomainValue

    public boolean containsDomainValue(java.util.Date date)

  Returns true if a value is contained in the timeline.

  Specified by:
    `containsDomainValue` in interface `Timeline`
  Parameters:
    `date` - date to verify
  Returns:
    true if value is contained in the timeline

### containsDomainRange

    public boolean containsDomainRange(long domainValueStart,
                                       long domainValueEnd)

  Returns true if a range of values are contained in the timeline. This is implemented verifying that all segments are in the range.

  Specified by:
    `containsDomainRange` in interface `Timeline`
  Parameters:
    `domainValueStart` - start of the range to verify
    `domainValueEnd` - end of the range to verify
  Returns:
    true if the range is contained in the timeline

### containsDomainRange

    public boolean containsDomainRange(java.util.Date dateDomainValueStart,
                                       java.util.Date dateDomainValueEnd)

  Returns true if a range of values are contained in the timeline. This is implemented verifying that all segments are in the range.

  Specified by:
    `containsDomainRange` in interface `Timeline`
  Parameters:
    `dateDomainValueStart` - start of the range to verify
    `dateDomainValueEnd` - end of the range to verify
  Returns:
    true if the range is contained in the timeline

### addException

    public void addException(long millisecond)

  Adds a segment as an exception. 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 segment. Therefore the segmentStart <= domainValue <= segmentEnd.

  Parameters:
    `millisecond` - domain value to treat as an exception

### addException

    public void addException(long fromDomainValue,
                             long toDomainValue)

  Adds a segment range as an exception. 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 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.

  Parameters:
    `fromDomainValue` - start of domain range to treat as an exception
    `toDomainValue` - end of domain range to treat as an exception

### addException

    public void addException(java.util.Date exceptionDate)

  Adds a segment as an exception. 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 Date into any part of the segment.

  Parameters:
    `exceptionDate` - Date into the segment to exclude.

### addExceptions

    public void addExceptions(java.util.List exceptionList)

  Adds a list of dates as segment exceptions. Each 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 Date into any part of the segment.

  Parameters:
    `exceptionList` - List of Date objects that identify the segments to exclude.

### addBaseTimelineException

    public void addBaseTimelineException(long domainValue)

  Adds a segment relative to the baseTimeline as an exception. Because a base segment is normally larger than our segments, this may add one or more segment ranges to the exception list.

  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.

  Parameters:
    `domainValue` - domain value to teat as a baseTimeline exception.

### addBaseTimelineException

    public void addBaseTimelineException(java.util.Date date)

  Adds a segment relative to the baseTimeline as an exception. 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 occure (the proposed exception segment will be discarted).

  The segment is identified by a domainValue into any part of the segment. Therefore the segmentStart <= domainValue <= segmentEnd.

  Parameters:
    `date` - date domain value to treat as a baseTimeline exception

### addBaseTimelineExclusions

    public void addBaseTimelineExclusions(long fromBaseDomainValue,
                                          long toBaseDomainValue)

  Adds all excluded segments from the BaseTimeline as exceptions to our timeline. This allows us to combine two timelines for more complex calculations.

  Parameters:
    `fromBaseDomainValue` - Start of the range where exclusions will be extracted.
    `toBaseDomainValue` - End of the range to process.

### getExceptionSegmentCount

    public long getExceptionSegmentCount(long fromMillisecond,
                                         long toMillisecond)

  Returns the number of exception segments wholly contained in the (fromDomainValue, toDomainValue) interval.

  Parameters:
    `fromMillisecond` - the beginning of the interval.
    `toMillisecond` - the end of the interval.
  Returns:
    Number of exception segments contained in the interval.

### getSegment

    public SegmentedTimeline.Segment getSegment(long millisecond)

  Returns a segment that contains a domainValue. If the domainValue is not contained in the timeline (because it is not contained in the baseTimeline), a Segment that contains `index + segmentSize*m` will be returned for the smallest `m` possible.

  Parameters:
    `millisecond` - index into the segment
  Returns:
    a Segment that contains index, or the next possible Segment.

### getSegment

    public SegmentedTimeline.Segment getSegment(java.util.Date date)

  Returns a segment that contains a date. For accurate calculations, the calendar should use TIME_ZONE for its calculation (or any other similar time zone). If the date is not contained in the timeline (because it is not contained in the baseTimeline), a Segment that contains `date + segmentSize*m` will be returned for the smallest `m` possible.

  Parameters:
    `date` - date into the segment
  Returns:
    a Segment that contains date, or the next possible Segment.

### equals

    public boolean equals(java.lang.Object o)

  Returns true if we are equal to the parameter

  Parameters:
    `o` - Object to verify with us
  Returns:
    true or false

### getTime

    public long getTime(java.util.Date date)

  Special method that handles conversion between the Default Time Zone and a UTC time zone with no DST. This is needed so all days have the same size. This method is the prefered way of converting a Data into milliseconds for usage in this class.

  Parameters:
    `date` - Date to convert to long.
  Returns:
    The milliseconds.

### getDate

    public java.util.Date getDate(long value)

  Converts a millisecond value into a `Date` object.

  Parameters:
    `value` - the millisecond value.
  Returns:
    The date.

### clone

    public java.lang.Object clone()
                           throws java.lang.CloneNotSupportedException

  Returns a clone of the timeline.

  Returns:
    A clone.
  Throws:
    `java.lang.CloneNotSupportedException` - ??.