1 /*
2 * Copyright 2001-2009 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.time;
17
18 /**
19 * Defines an instant in the datetime continuum.
20 * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.
21 * <p>
22 * The implementation of this interface may be mutable or immutable.
23 * This interface only gives access to retrieve data, never to change it.
24 * <p>
25 * Methods in your application should be defined using <code>ReadableInstant</code>
26 * as a parameter if the method only wants to read the instant without needing to know
27 * the specific datetime fields.
28 * <p>
29 * The {@code compareTo} method is no longer defined in this class in version 2.0.
30 * Instead, the definition is simply inherited from the {@code Comparable} interface.
31 * This approach is necessary to preserve binary compatibility.
32 * The definition of the comparison is ascending order by millisecond instant.
33 * Implementors are recommended to extend {@code AbstractInstant} instead of this interface.
34 *
35 * @author Stephen Colebourne
36 * @since 1.0
37 */
38 public interface ReadableInstant extends Comparable<ReadableInstant> {
39
40 /**
41 * Get the value as the number of milliseconds since
42 * the epoch, 1970-01-01T00:00:00Z.
43 *
44 * @return the value as milliseconds
45 */
46 long getMillis();
47
48 /**
49 * Gets the chronology of the instant.
50 * <p>
51 * The {@link Chronology} provides conversion from the millisecond
52 * value to meaningful fields in a particular calendar system.
53 *
54 * @return the Chronology, never null
55 */
56 Chronology getChronology();
57
58 /**
59 * Gets the time zone of the instant from the chronology.
60 *
61 * @return the DateTimeZone that the instant is using, never null
62 */
63 DateTimeZone getZone();
64
65 /**
66 * Get the value of one of the fields of a datetime.
67 * <p>
68 * This method uses the chronology of the instant to obtain the value.
69 *
70 * @param type a field type, usually obtained from DateTimeFieldType, not null
71 * @return the value of that field
72 * @throws IllegalArgumentException if the field type is null
73 */
74 int get(DateTimeFieldType type);
75
76 /**
77 * Checks whether the field type specified is supported by this implementation.
78 *
79 * @param field the field type to check, may be null which returns false
80 * @return true if the field is supported
81 */
82 boolean isSupported(DateTimeFieldType field);
83
84 //-----------------------------------------------------------------------
85 /**
86 * Get the value as a simple immutable <code>Instant</code> object.
87 * <p>
88 * This can be useful if you don't trust the implementation
89 * of the interface to be well-behaved, or to get a guaranteed
90 * immutable object.
91 *
92 * @return the value as an <code>Instant</code> object
93 */
94 Instant toInstant();
95
96 //-----------------------------------------------------------------------
97 // Method is no longer defined here as that would break generic backwards compatibility
98 // /**
99 // * Compares this object with the specified object for ascending
100 // * millisecond instant order. This ordering is inconsistent with
101 // * equals, as it ignores the Chronology.
102 // * <p>
103 // * All ReadableInstant instances are accepted.
104 // *
105 // * @param readableInstant a readable instant to check against
106 // * @return negative value if this is less, 0 if equal, or positive value if greater
107 // * @throws NullPointerException if the object is null
108 // * @throws ClassCastException if the object type is not supported
109 // */
110 // int compareTo(ReadableInstant readableInstant);
111
112 //-----------------------------------------------------------------------
113 /**
114 * Is this instant equal to the instant passed in
115 * comparing solely by millisecond.
116 *
117 * @param instant an instant to check against, null means now
118 * @return true if the instant is equal to the instant passed in
119 */
120 boolean isEqual(ReadableInstant instant);
121
122 /**
123 * Is this instant after the instant passed in
124 * comparing solely by millisecond.
125 *
126 * @param instant an instant to check against, null means now
127 * @return true if the instant is after the instant passed in
128 */
129 boolean isAfter(ReadableInstant instant);
130
131 /**
132 * Is this instant before the instant passed in
133 * comparing solely by millisecond.
134 *
135 * @param instant an instant to check against, null means now
136 * @return true if the instant is before the instant passed in
137 */
138 boolean isBefore(ReadableInstant instant);
139
140 //-----------------------------------------------------------------------
141 /**
142 * Compares this object with the specified object for equality based
143 * on the millisecond instant and the Chronology. All ReadableInstant
144 * instances are accepted.
145 * <p>
146 * To compare two instants for absolute time (ie. UTC milliseconds
147 * ignoring the chronology), use {@link #isEqual(ReadableInstant)} or
148 * {@link #compareTo(Object)}.
149 *
150 * @param readableInstant a readable instant to check against
151 * @return true if millisecond and chronology are equal, false if
152 * not or the instant is null or of an incorrect type
153 */
154 boolean equals(Object readableInstant);
155
156 /**
157 * Gets a hash code for the instant that is compatible with the
158 * equals method.
159 * <p>
160 * The formula used must be as follows:
161 * <pre>
162 * ((int) (getMillis() ^ (getMillis() >>> 32))) +
163 * (getChronology().hashCode())
164 * </pre>
165 *
166 * @return a hash code as defined above
167 */
168 int hashCode();
169
170 //-----------------------------------------------------------------------
171 /**
172 * Get the value as a String in a recognisable ISO8601 format.
173 * <p>
174 * The string output is in ISO8601 format to enable the String
175 * constructor to correctly parse it.
176 *
177 * @return the value as an ISO8601 string
178 */
179 String toString();
180
181 }