001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/util/tags/sakai_2-4-1/util-api/api/src/java/org/sakaiproject/time/api/TimeRange.java $
003: * $Id: TimeRange.java 6835 2006-03-21 21:06:44Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.time.api;
021:
022: /**
023: * <p>
024: * TimeRange ...
025: * </p>
026: */
027: public interface TimeRange extends Cloneable {
028: /**
029: * Check if this Time in my range.
030: *
031: * @param time
032: * The time to check for inclusion.
033: * @return true if the time is in the range, false if not.
034: */
035: boolean contains(Time time);
036:
037: /**
038: * Check if this TimeRange overlap this other TimeRange at all.
039: *
040: * @param range
041: * The time range to check for overlap.
042: * @return true if any time in the other range is in this range, false if not.
043: */
044: boolean overlaps(TimeRange range);
045:
046: /**
047: * Check if this TimeRange completely contains the other range.
048: *
049: * @param range
050: * The time range to check for containment.
051: * @return true if the other TimeRange is within this TimeRange, false if not.
052: */
053: boolean contains(TimeRange range);
054:
055: /**
056: * Access the first Time of the range.
057: *
058: * @return the first Time actually in the range.
059: */
060: Time firstTime();
061:
062: /**
063: * Access the last Time in the range.
064: *
065: * @return the last Time actually in the range.
066: */
067: Time lastTime();
068:
069: /**
070: * Access the first Time of the range (fudged).
071: *
072: * @param fudge
073: * How many ms to increase if the first is not included.
074: * @return the first Time actually in the range (fudged).
075: */
076: Time firstTime(long fudge);
077:
078: /**
079: * Access the last Time of the range (fudged).
080: *
081: * @param fudge
082: * How many ms to decrease if the last is not included.
083: * @return the first Time actually in the range (fudged).
084: */
085: Time lastTime(long fudge);
086:
087: /**
088: * Format the TimeRange - human readable.
089: *
090: * @return The TimeRange in string format.
091: */
092: String toStringHR();
093:
094: /**
095: * Access the duration of the TimeRange, in milliseconds.
096: *
097: * @return The duration.
098: */
099: long duration();
100:
101: /**
102: * Shift the time range back an interval
103: *
104: * @param i
105: * time intervel in ms
106: */
107: void shiftBackward(long i);
108:
109: /**
110: * Shift the time range forward an interval
111: *
112: * @param i
113: * time intervel in ms
114: */
115: void shiftForward(long i);
116:
117: /**
118: * Enlarge or shrink the time range by multiplying a zooming factor.
119: *
120: * @param f
121: * zooming factor
122: */
123: void zoom(double f);
124:
125: /**
126: * Adjust this time range based on the difference between the origRange and the modRange, if any.
127: *
128: * @param original
129: * the original time range.
130: * @param modified
131: * the modified time range.
132: */
133: void adjust(TimeRange original, TimeRange modified);
134:
135: /**
136: * Clone the TimeRange
137: *
138: * @return A cloned TimeRange.
139: */
140: Object clone();
141:
142: /**
143: * Check if the TimeRange is really just a single Time.
144: *
145: * @return true if the tiTimeRange is a single Time, false if it is not.
146: */
147: boolean isSingleTime();
148: }
|