Each segment will know its segment number, segmentStart, segmentEnd and index inside the segment. 

 public SegmentedTimeline(long segmentSize,
    int segmentsIncluded,
    int segmentsExcluded) 
{
    ////////////////////////////////////////////////////////////////////////////
    // static block
    ////////////////////////////////////////////////////////////////////////////
        // make a time zone with no DST for our Calendar calculations
        int offset = TimeZone.getDefault().getRawOffset();
        NO_DST_TIME_ZONE = new SimpleTimeZone(offset, "UTC-" + offset);
        // calculate midnight of first monday after 1/1/1900 relative to
        // current locale
        Calendar cal = new GregorianCalendar(NO_DST_TIME_ZONE);
        cal.set(1900, 0, 1, 0, 0, 0);
        cal.set(Calendar.MILLISECOND, 0);
        while (cal.get(Calendar.DAY_OF_WEEK) != Calendar.MONDAY) {
            cal.add(Calendar.DATE, 1);
        }
        // FIRST_MONDAY_AFTER_1900 = cal.getTime().getTime();
        // preceding code won't work with JDK 1.3
        FIRST_MONDAY_AFTER_1900 = cal.getTime().getTime();
        this.segmentSize = segmentSize;
        this.segmentsIncluded = segmentsIncluded;
        this.segmentsExcluded = segmentsExcluded;
        this.groupSegmentCount = this.segmentsIncluded + this.segmentsExcluded;
        this.segmentsIncludedSize = this.segmentsIncluded * this.segmentSize;
        this.segmentsExcludedSize = this.segmentsExcluded * this.segmentSize;
        this.segmentsGroupSize = this.segmentsIncludedSize
                                 + this.segmentsExcludedSize;
        int offset = TimeZone.getDefault().getRawOffset();
        TimeZone z = new SimpleTimeZone(offset, "UTC-" + offset);
        this.workingCalendarNoDST = new GregorianCalendar(z,
                Locale.getDefault());
}

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.

 public  void addBaseTimelineException(long domainValue) 
{
        Segment baseSegment = this.baseTimeline.getSegment(domainValue);
        if (baseSegment.inIncludeSegments()) {
            // cycle through all the segments contained in the BaseTimeline
            // exception segment
            Segment segment = getSegment(baseSegment.getSegmentStart());
            while (segment.getSegmentStart() < = baseSegment.getSegmentEnd()) {
                if (segment.inIncludeSegments()) {
                    // find all consecutive included segments
                    long fromDomainValue = segment.getSegmentStart();
                    long toDomainValue;
                    do {
                        toDomainValue = segment.getSegmentEnd();
                        segment.inc();
                    }
                    while (segment.inIncludeSegments());
                    // add the interval as an exception
                    addException(fromDomainValue, toDomainValue);
                }
                else {
                    // this is not one of our included segment, skip it
                    segment.inc();
                }
            }
        }
}

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.

 public  void addBaseTimelineException(Date date) 
{
        addBaseTimelineException(getTime(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 discarded).

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

 public  void addBaseTimelineExclusions(long fromBaseDomainValue,
    long toBaseDomainValue) 
{
        // find first excluded base segment starting fromDomainValue
        Segment baseSegment = this.baseTimeline.getSegment(fromBaseDomainValue);
        while (baseSegment.getSegmentStart() < = toBaseDomainValue
               && !baseSegment.inExcludeSegments()) {
            baseSegment.inc();
        }
        // cycle over all the base segments groups in the range
        while (baseSegment.getSegmentStart() < = toBaseDomainValue) {
            long baseExclusionRangeEnd = baseSegment.getSegmentStart()
                     + this.baseTimeline.getSegmentsExcluded()
                     * this.baseTimeline.getSegmentSize() - 1;
            // cycle through all the segments contained in the base exclusion
            // area
            Segment segment = getSegment(baseSegment.getSegmentStart());
            while (segment.getSegmentStart() < = baseExclusionRangeEnd) {
                if (segment.inIncludeSegments()) {
                    // find all consecutive included segments
                    long fromDomainValue = segment.getSegmentStart();
                    long toDomainValue;
                    do {
                        toDomainValue = segment.getSegmentEnd();
                        segment.inc();
                    }
                    while (segment.inIncludeSegments());
                    // add the interval as an exception
                    addException(new BaseTimelineSegmentRange(
                            fromDomainValue, toDomainValue));
                }
                else {
                    // this is not one of our included segment, skip it
                    segment.inc();
                }
            }
            // go to next base segment group
            baseSegment.inc(this.baseTimeline.getGroupSegmentCount());
        }
}

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

 public  void addException(long millisecond) 
{
        addException(new Segment(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.

 public  void addException(Date exceptionDate) 
{
        addException(getTime(exceptionDate));
        //addException(exceptionDate.getTime());
}

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.

 public  void addException(long fromDomainValue,
    long toDomainValue) 
{
        addException(new SegmentRange(fromDomainValue, 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.

 public  void addExceptions(List exceptionList) 
{
        for (Iterator iter = exceptionList.iterator(); iter.hasNext();) {
            addException((Date) iter.next());
        }
}

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.

 public Object clone() throws CloneNotSupportedException 
{
        SegmentedTimeline clone = (SegmentedTimeline) super.clone();
        return clone;
}

Returns a clone of the timeline.

 public boolean containsDomainRange(long domainValueStart,
    long domainValueEnd) 
{
        if (domainValueEnd <  domainValueStart) {
            throw new IllegalArgumentException(
                    "domainValueEnd (" + domainValueEnd
                    + ") <  domainValueStart (" + domainValueStart + ")");
        }
        Segment segment = getSegment(domainValueStart);
        boolean contains = true;
        do {
            contains = (segment.inIncludeSegments());
            if (segment.contains(domainValueEnd)) {
                break;
            }
            else {
                segment.inc();
            }
        }
        while (contains);
        return (contains);
}

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

 public boolean containsDomainRange(Date dateDomainValueStart,
    Date dateDomainValueEnd) 
{
        return containsDomainRange(getTime(dateDomainValueStart),
        		getTime(dateDomainValueEnd));
}

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

 public boolean containsDomainValue(long millisecond) 
{
        Segment segment = getSegment(millisecond);
        return segment.inIncludeSegments();
}

Returns true if a value is contained in the timeline.

 public boolean containsDomainValue(Date date) 
{
        return containsDomainValue(getTime(date));
}

Returns true if a value is contained in the timeline.

 public boolean equals(Object o) 
{
        if (o instanceof SegmentedTimeline) {
            SegmentedTimeline other = (SegmentedTimeline) o;
            boolean b0 = (this.segmentSize == other.getSegmentSize());
            boolean b1 = (this.segmentsIncluded == other.getSegmentsIncluded());
            boolean b2 = (this.segmentsExcluded == other.getSegmentsExcluded());
            boolean b3 = (this.startTime == other.getStartTime());
            boolean b4 = equals(this.exceptionSegments,
            		other.getExceptionSegments());
            return b0 && b1 && b2 && b3 && b4;
        }
        else {
            return (false);
        }
}

Returns true if we are equal to the parameter

 public static long firstMondayAfter1900() 
{
        int offset = TimeZone.getDefault().getRawOffset();
        TimeZone z = new SimpleTimeZone(offset, "UTC-" + offset);
        // calculate midnight of first monday after 1/1/1900 relative to
        // current locale
        Calendar cal = new GregorianCalendar(z);
        cal.set(1900, 0, 1, 0, 0, 0);
        cal.set(Calendar.MILLISECOND, 0);
        while (cal.get(Calendar.DAY_OF_WEEK) != Calendar.MONDAY) {
            cal.add(Calendar.DATE, 1);
        }
        //return cal.getTimeInMillis();
        // preceding code won't work with JDK 1.3
        return cal.getTime().getTime();
}

Returns the milliseconds for midnight of the first Monday after 1-Jan-1900, ignoring daylight savings.

 public boolean getAdjustForDaylightSaving() 
{
        return this.adjustForDaylightSaving;
}

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

 public SegmentedTimeline getBaseTimeline() 
{
        return this.baseTimeline;
}

Returns our baseTimeline, or null if none.

 public Date getDate(long value) 
{
        this.workingCalendarNoDST.setTime(new Date(value));
        return (this.workingCalendarNoDST.getTime());
}

Converts a millisecond value into a Date object.

 public long getExceptionSegmentCount(long fromMillisecond,
    long toMillisecond) 
{
        if (toMillisecond <  fromMillisecond) {
            return (0);
        }
        int n = 0;
        for (Iterator iter = this.exceptionSegments.iterator();
             iter.hasNext();) {
            Segment segment = (Segment) iter.next();
            Segment intersection = segment.intersect(fromMillisecond,
            		toMillisecond);
            if (intersection != null) {
                n += intersection.getSegmentCount();
            }
        }
        return (n);
}

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

 public List getExceptionSegments() 
{
        return Collections.unmodifiableList(this.exceptionSegments);
}

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

 public int getGroupSegmentCount() 
{
        return this.groupSegmentCount;
}

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

 public SegmentedTimeline.Segment getSegment(long millisecond) 
{
        return new Segment(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.

 public SegmentedTimeline.Segment getSegment(Date date) 
{
        return (getSegment(getTime(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.

 public long getSegmentSize() 
{
        return this.segmentSize;
}

Returns the size of one segment in ms.

 public int getSegmentsExcluded() 
{
        return this.segmentsExcluded;
}

Returns the number of segments excluded per segment group.

 public long getSegmentsExcludedSize() 
{
        return this.segmentsExcludedSize;
}

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

 public long getSegmentsGroupSize() 
{
        return this.segmentsGroupSize;
}

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.

 public int getSegmentsIncluded() 
{
        return this.segmentsIncluded;
}

Returns the number of segments included per segment group.

 public long getSegmentsIncludedSize() 
{
        return this.segmentsIncludedSize;
}

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

 public long getStartTime() 
{
        return this.startTime;
}

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

 public long getTime(Date date) 
{
        long result = date.getTime();
        if (this.adjustForDaylightSaving) {
            this.workingCalendar.setTime(date);
            this.workingCalendarNoDST.set(
                    this.workingCalendar.get(Calendar.YEAR),
                    this.workingCalendar.get(Calendar.MONTH),
                    this.workingCalendar.get(Calendar.DATE),
                    this.workingCalendar.get(Calendar.HOUR_OF_DAY),
                    this.workingCalendar.get(Calendar.MINUTE),
                    this.workingCalendar.get(Calendar.SECOND));
            this.workingCalendarNoDST.set(Calendar.MILLISECOND,
                    this.workingCalendar.get(Calendar.MILLISECOND));
            Date revisedDate = this.workingCalendarNoDST.getTime();
            result = revisedDate.getTime();
        }
        return result;
}

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.

 public long getTimeFromLong(long date) 
{
        long result = date;
        if (this.adjustForDaylightSaving) {
            this.workingCalendarNoDST.setTime(new Date(date));
            this.workingCalendar.set(
                this.workingCalendarNoDST.get(Calendar.YEAR),
                this.workingCalendarNoDST.get(Calendar.MONTH),
                this.workingCalendarNoDST.get(Calendar.DATE),
                this.workingCalendarNoDST.get(Calendar.HOUR_OF_DAY),
                this.workingCalendarNoDST.get(Calendar.MINUTE),
                this.workingCalendarNoDST.get(Calendar.SECOND)
            );
            this.workingCalendar.set(Calendar.MILLISECOND,
                    this.workingCalendarNoDST.get(Calendar.MILLISECOND));
            // result = this.workingCalendar.getTimeInMillis();
            // preceding code won't work with JDK 1.3
            result = this.workingCalendar.getTime().getTime();
        }
        return result;
}

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

 public int hashCode() 
{
        int result = 19;
        result = 37 * result
                 + (int) (this.segmentSize ^ (this.segmentSize  > > > 32));
        result = 37 * result + (int) (this.startTime ^ (this.startTime  > > > 32));
        return result;
}

Returns a hash code for this object.

 public static SegmentedTimeline newFifteenMinuteTimeline() 
{
        SegmentedTimeline timeline = new SegmentedTimeline(
                FIFTEEN_MINUTE_SEGMENT_SIZE, 28, 68);
        timeline.setStartTime(firstMondayAfter1900() + 36
                * timeline.getSegmentSize());
        timeline.setBaseTimeline(newMondayThroughFridayTimeline());
        return timeline;
}

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

 public static SegmentedTimeline newMondayThroughFridayTimeline() 
{
        SegmentedTimeline timeline
            = new SegmentedTimeline(DAY_SEGMENT_SIZE, 5, 2);
        timeline.setStartTime(firstMondayAfter1900());
        return timeline;
}

Factory method to create a Monday through Friday SegmentedTimeline.

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

 public  void setAdjustForDaylightSaving(boolean adjust) 
{
        this.adjustForDaylightSaving = adjust;
}

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

 public  void setBaseTimeline(SegmentedTimeline baseTimeline) 
{
        // verify that baseTimeline is compatible with us
        if (baseTimeline != null) {
            if (baseTimeline.getSegmentSize() <  this.segmentSize) {
                throw new IllegalArgumentException(
                		"baseTimeline.getSegmentSize() "
                		+ "is smaller than segmentSize");
            }
            else if (baseTimeline.getStartTime()  > this.startTime) {
                throw new IllegalArgumentException(
                        "baseTimeline.getStartTime() is after startTime");
            }
            else if ((baseTimeline.getSegmentSize() % this.segmentSize) != 0) {
                throw new IllegalArgumentException(
                        "baseTimeline.getSegmentSize() is not multiple of "
                        + "segmentSize");
            }
            else if (((this.startTime
                    - baseTimeline.getStartTime()) % this.segmentSize) != 0) {
                throw new IllegalArgumentException(
                		"baseTimeline is not aligned");
            }
        }
        this.baseTimeline = baseTimeline;
}

Sets the base timeline.

 public  void setExceptionSegments(List exceptionSegments) 
{
        this.exceptionSegments = exceptionSegments;
}

Sets the exception segments list.

 public  void setStartTime(long millisecond) 
{
        this.startTime = millisecond;
}

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

 public long toMillisecond(long timelineValue) 
{
        // calculate the result as if no exceptions
        Segment result = new Segment(this.startTime + timelineValue
                + (timelineValue / this.segmentsIncludedSize)
                * this.segmentsExcludedSize);
        long lastIndex = this.startTime;
        // adjust result for any exceptions in the result calculated
        while (lastIndex < = result.segmentStart) {
            // skip all whole exception segments in the range
            long exceptionSegmentCount;
            while ((exceptionSegmentCount = getExceptionSegmentCount(
                 lastIndex, (result.millisecond / this.segmentSize)
                 * this.segmentSize - 1))  > 0
            ) {
                lastIndex = result.segmentStart;
                // move forward exceptionSegmentCount segments skipping
                // excluded segments
                for (int i = 0; i <  exceptionSegmentCount; i++) {
                    do {
                        result.inc();
                    }
                    while (result.inExcludeSegments());
                }
            }
            lastIndex = result.segmentStart;
            // skip exception or excluded segments we may fall on
            while (result.inExceptionSegments() || result.inExcludeSegments()) {
                result.inc();
                lastIndex += this.segmentSize;
            }
            lastIndex++;
        }
        return getTimeFromLong(result.millisecond);
}

Translates a value relative to the timeline into a millisecond.

 public long toTimelineValue(long millisecond) 
{
        long result;
        long rawMilliseconds = millisecond - this.startTime;
        long groupMilliseconds = rawMilliseconds % this.segmentsGroupSize;
        long groupIndex = rawMilliseconds / this.segmentsGroupSize;
        if (groupMilliseconds  >= this.segmentsIncludedSize) {
            result = toTimelineValue(this.startTime + this.segmentsGroupSize
            		* (groupIndex + 1));
        }
        else {
            Segment segment = getSegment(millisecond);
            if (segment.inExceptionSegments()) {
            	int p;
                while ((p = binarySearchExceptionSegments(segment))  >= 0) {
                    segment = getSegment(millisecond = ((Segment)
                    		this.exceptionSegments.get(p)).getSegmentEnd() + 1);
                }
                result = toTimelineValue(millisecond);
            }
            else {
                long shiftedSegmentedValue = millisecond - this.startTime;
                long x = shiftedSegmentedValue % this.segmentsGroupSize;
                long y = shiftedSegmentedValue / this.segmentsGroupSize;
                long wholeExceptionsBeforeDomainValue =
                    getExceptionSegmentCount(this.startTime, millisecond - 1);
//                long partialTimeInException = 0;
//                Segment ss = getSegment(millisecond);
//                if (ss.inExceptionSegments()) {
//                    partialTimeInException = millisecond
                //     - ss.getSegmentStart();
//                }
                if (x <  this.segmentsIncludedSize) {
                    result = this.segmentsIncludedSize * y
                             + x - wholeExceptionsBeforeDomainValue
                             * this.segmentSize;
                             // - partialTimeInException;
                }
                else {
                    result = this.segmentsIncludedSize * (y + 1)
                             - wholeExceptionsBeforeDomainValue
                             * this.segmentSize;
                             // - partialTimeInException;
                }
            }
        }
        return result;
}

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.

 public long toTimelineValue(Date date) 
{
        return toTimelineValue(getTime(date));
        //return toTimelineValue(dateDomainValue.getTime());
}

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.