001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.util;
028:
029: import java.io.Serializable;
030: import java.util.Date;
031:
032: /**
033: * An abstraction of an object which starts at a known point
034: * in time and ends before a known point in time.
035: *
036: * Note that the interval is closed with respect to the
037: * start point, open with respect to the end point and start must
038: * be strictly less than end.
039: *
040: * An interval where start==end is illegal, as it would indicate a
041: * negative 1 millisecond duration. A point in time must be represented
042: * with end = start+EPSILON.
043: *
044: * A TimeSpan that does not have well-defined start and end times is
045: * also illegal. For example a set of TimeSpans might also be a
046: * TimeSpan (e.g. Schedule) (with start and end times bounding the
047: * start and end times of all the members of the set). If the set were
048: * empty, there would be no well-defined start and end times. Such a
049: * TimeSpan would be illegal.
050: *
051: * The values are usually interpreted to mean milliseconds in java time,
052: * though there is nothing which actually requires these semantics.
053: *
054: * Note that while the interface is not required to be serializable,
055: * most implementations (including the static inner classes here)
056: * will actually be so.
057: *
058: * @see TimeSpans for a collection of factory methods.
059: **/
060: public interface TimeSpan {
061: /** The minimum Time increment. **/
062: long EPSILON = 1;
063:
064: /** A value to indicate unbounded StartTime.
065: * The actual value was chosen so that (MAX_VALUE-MIN_VALUE) is still a long.
066: **/
067: long MIN_VALUE = -(Long.MAX_VALUE >> 2); //was Long.MIN_VALUE;
068:
069: /** A value to indicate unbounded EndTime.
070: * The actual value was chosen so that (MAX_VALUE-MIN_VALUE) is still a long.
071: **/
072: long MAX_VALUE = (Long.MAX_VALUE >> 2); //was Long.MAX_VALUE;
073:
074: /** The first point in time to be considered part of the
075: * interval.
076: * @return MIN_VALUE IFF unbounded.
077: **/
078: long getStartTime();
079:
080: /** The first point in time after start to be considered
081: * <em> not </em> part of the interval.
082: * @return MAX_VALUE IFF unbounded.
083: **/
084: long getEndTime();
085:
086: /** A representation of a point in time, generally
087: * the smallest time span which contains the specified
088: * time. Strictly speaking, this ought to be represeted
089: * differently than a span.
090: * @see TimeSpans#getPoint(long)
091: **/
092: class Point implements TimeSpan, Serializable {
093: private long t;
094:
095: public Point(long t) {
096: if (t < MIN_VALUE || t >= MAX_VALUE) {
097: throw new IllegalArgumentException(
098: "Bad TimeSpan.Point(" + t + ")");
099: }
100: this .t = t;
101: }
102:
103: public long getStartTime() {
104: return t;
105: }
106:
107: public long getEndTime() {
108: return t + EPSILON;
109: }
110:
111: public String toString() {
112: return "["
113: + (t == MIN_VALUE ? "MIN_VALUE"
114: : t == MAX_VALUE ? "MAX_VALUE" : (new Date(
115: t)).toString()) + "]";
116: }
117: }
118:
119: /** A simple implementation of a two-point specified time span.
120: * @see TimeSpans#getSpan(long, long)
121: **/
122: class Span implements TimeSpan, Serializable {
123: private long t0, t1;
124:
125: public Span(long t0, long t1) {
126: if (t0 >= t1 || t0 < MIN_VALUE || t1 > MAX_VALUE) {
127: throw new IllegalArgumentException("Bad TimeSpan.Span("
128: + t0 + "," + t1 + ")");
129: }
130: this .t0 = t0;
131: this .t1 = t1;
132: }
133:
134: public long getStartTime() {
135: return t0;
136: }
137:
138: public long getEndTime() {
139: return t1;
140: }
141:
142: public String toString() {
143: return "["
144: + (t0 == MIN_VALUE ? "MIN_VALUE" : (new Date(t0))
145: .toString())
146: + "-"
147: + (t1 == MAX_VALUE ? "MAX_VALUE" : (new Date(t1))
148: .toString()) + "]";
149: }
150: }
151:
152: /** a TimeSpan representing all representable time **/
153: TimeSpan FOREVER = new Span(MIN_VALUE, MAX_VALUE) {
154: public String toString() {
155: return "[forever]";
156: }
157: };
158: }
|