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 */
016package 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 */
038public 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}