001 /*
002 * Copyright 2001-2009 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.time;
017
018 /**
019 * Defines an instant in the datetime continuum.
020 * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z.
021 * <p>
022 * The implementation of this interface may be mutable or immutable.
023 * This interface only gives access to retrieve data, never to change it.
024 * <p>
025 * Methods in your application should be defined using <code>ReadableInstant</code>
026 * as a parameter if the method only wants to read the instant without needing to know
027 * the specific datetime fields.
028 * <p>
029 * The {@code compareTo} method is no longer defined in this class in version 2.0.
030 * Instead, the definition is simply inherited from the {@code Comparable} interface.
031 * This approach is necessary to preserve binary compatibility.
032 * The definition of the comparison is ascending order by millisecond instant.
033 * Implementors are recommended to extend {@code AbstractInstant} instead of this interface.
034 *
035 * @author Stephen Colebourne
036 * @since 1.0
037 */
038 public interface ReadableInstant extends Comparable<ReadableInstant> {
039
040 /**
041 * Get the value as the number of milliseconds since
042 * the epoch, 1970-01-01T00:00:00Z.
043 *
044 * @return the value as milliseconds
045 */
046 long getMillis();
047
048 /**
049 * Gets the chronology of the instant.
050 * <p>
051 * The {@link Chronology} provides conversion from the millisecond
052 * value to meaningful fields in a particular calendar system.
053 *
054 * @return the Chronology, never null
055 */
056 Chronology getChronology();
057
058 /**
059 * Gets the time zone of the instant from the chronology.
060 *
061 * @return the DateTimeZone that the instant is using, never null
062 */
063 DateTimeZone getZone();
064
065 /**
066 * Get the value of one of the fields of a datetime.
067 * <p>
068 * This method uses the chronology of the instant to obtain the value.
069 *
070 * @param type a field type, usually obtained from DateTimeFieldType, not null
071 * @return the value of that field
072 * @throws IllegalArgumentException if the field type is null
073 */
074 int get(DateTimeFieldType type);
075
076 /**
077 * Checks whether the field type specified is supported by this implementation.
078 *
079 * @param field the field type to check, may be null which returns false
080 * @return true if the field is supported
081 */
082 boolean isSupported(DateTimeFieldType field);
083
084 //-----------------------------------------------------------------------
085 /**
086 * Get the value as a simple immutable <code>Instant</code> object.
087 * <p>
088 * This can be useful if you don't trust the implementation
089 * of the interface to be well-behaved, or to get a guaranteed
090 * immutable object.
091 *
092 * @return the value as an <code>Instant</code> object
093 */
094 Instant toInstant();
095
096 //-----------------------------------------------------------------------
097 // Method is no longer defined here as that would break generic backwards compatibility
098 // /**
099 // * 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 }