Source code: jtemporal/Instant.java
1 /*
2 Copyright (C) 2002 Thomas A Beck (http://thomas.beck.name)
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public
15 License along with this library; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
17
18
19 package jtemporal;
20 /**
21 * You must implement this interface (basically a Comparable) to
22 * represent time. The implementing object must be immutable. <BR>
23 * If you are in nuclear particle research you won't use the same class
24 * as if you are a geologist. <BR>
25 * You can write a little adapter wrapping java.util.Date. Most users rether use
26 * "pure" dates, to avoid issues with timezones. There are many opensource
27 * implementations of Julian date and of Gregorian date.
28 * Many companies have their own date/calendar framework.
29 * For example, in my unit test classes, I have simply adapted an int. <BR>
30 * <B>Any object implementing this interface is required to be immutable. This
31 * is part of the contract.</B><BR>
32 * Do not forget to implement equals and hashCode properly, as defined in the
33 * java.lang.Object documentation.
34 * Also, the equals method must be consistent with the compareTo method.
35 * @stereotype immutable
36 * @version $Id$
37 * @author Thomas Beck
38 */
39 public interface Instant extends Comparable
40 {
41 /**
42 * Compares this object with the specified object for order. Returns a
43 * negative integer, zero, or a positive integer as this object is less
44 * than, equal to, or greater than the specified object.<p>
45 *
46 * The implementor must ensure <tt>sgn(x.compareTo(y)) ==
47 * -sgn(y.compareTo(x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This
48 * implies that <tt>x.compareTo(y)</tt> must throw an exception iff
49 * <tt>y.compareTo(x)</tt> throws an exception.)<p>
50 *
51 * The implementor must also ensure that the relation is transitive:
52 * <tt>(x.compareTo(y)>0 && y.compareTo(z)>0)</tt> implies
53 * <tt>x.compareTo(z)>0</tt>.<p>
54 *
55 * Finally, the implementer must ensure that <tt>x.compareTo(y)==0</tt>
56 * implies that <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>, for
57 * all <tt>z</tt>.<p>
58 *
59 * <B>It is required that <tt>(x.compareTo(y)==0) == (x.equals(y))</tt>.</B>
60 *
61 * @param o the Object to be compared.
62 * @return a negative integer, zero, or a positive integer as this object
63 * is less than, equal to, or greater than the specified object.
64 *
65 * @throws ClassCastException if the specified object's type prevents it
66 * from being compared to this Object.
67 */
68 public int compareTo(Object o);
69
70 /**
71 * Returns the biggest existing Instant. <BR>
72 * The implementation of this method is not mandatory. <BR>
73 * It could become mandatory in a future version.
74 * @throws UnsupportedOperationException if this method is not implemented
75 * @return the instant which is greater than any other instant
76 */
77 Instant positiveInfinity();
78
79 /**
80 * Returns the lowest existing Instant. <BR>
81 * The implementation of this method is not mandatory. <BR>
82 * It could become mandatory in a future version.
83 * @throws UnsupportedOperationException if this method is not implemented
84 * @return the instant which is lower than any other instant
85 */
86 Instant negativeInfinity();
87
88 }