001/*
002 *  Copyright 2001-2005 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 *
029 * @author Stephen Colebourne
030 * @since 1.0
031 */
032public interface ReadableInstant extends Comparable {
033
034    /**
035     * Get the value as the number of milliseconds since
036     * the epoch, 1970-01-01T00:00:00Z.
037     *
038     * @return the value as milliseconds
039     */
040    long getMillis();
041
042    /**
043     * Gets the chronology of the instant.
044     * <p>
045     * The {@link Chronology} provides conversion from the millisecond
046     * value to meaningful fields in a particular calendar system.
047     * 
048     * @return the Chronology, never null
049     */
050    Chronology getChronology();
051
052    /**
053     * Gets the time zone of the instant from the chronology.
054     * 
055     * @return the DateTimeZone that the instant is using, never null
056     */
057    DateTimeZone getZone();
058
059    /**
060     * Get the value of one of the fields of a datetime.
061     * <p>
062     * This method uses the chronology of the instant to obtain the value.
063     *
064     * @param type  a field type, usually obtained from DateTimeFieldType, not null
065     * @return the value of that field
066     * @throws IllegalArgumentException if the field type is null
067     */
068    int get(DateTimeFieldType type);
069
070    /**
071     * Checks whether the field type specified is supported by this implementation.
072     *
073     * @param field  the field type to check, may be null which returns false
074     * @return true if the field is supported
075     */
076    boolean isSupported(DateTimeFieldType field);
077
078    //-----------------------------------------------------------------------
079    /**
080     * Get the value as a simple immutable <code>Instant</code> object.
081     * <p>
082     * This can be useful if you don't trust the implementation
083     * of the interface to be well-behaved, or to get a guaranteed
084     * immutable object.
085     *
086     * @return the value as an <code>Instant</code> object
087     */
088    Instant toInstant();
089
090    //-----------------------------------------------------------------------
091    /**
092     * Compares this object with the specified object for ascending
093     * millisecond instant order. This ordering is inconsistent with
094     * equals, as it ignores the Chronology.
095     * <p>
096     * All ReadableInstant instances are accepted.
097     *
098     * @param readableInstant  a readable instant to check against
099     * @return negative value if this is less, 0 if equal, or positive value if greater
100     * @throws NullPointerException if the object is null
101     * @throws ClassCastException if the object type is not supported
102     */
103    int compareTo(Object readableInstant);
104
105    //-----------------------------------------------------------------------
106    /**
107     * Is this instant equal to the instant passed in
108     * comparing solely by millisecond.
109     *
110     * @param instant  an instant to check against, null means now
111     * @return true if the instant is equal to the instant passed in
112     */
113    boolean isEqual(ReadableInstant instant);
114
115    /**
116     * Is this instant after the instant passed in
117     * comparing solely by millisecond.
118     *
119     * @param instant  an instant to check against, null means now
120     * @return true if the instant is after the instant passed in
121     */
122    boolean isAfter(ReadableInstant instant);
123
124    /**
125     * Is this instant before the instant passed in
126     * comparing solely by millisecond.
127     *
128     * @param instant  an instant to check against, null means now
129     * @return true if the instant is before the instant passed in
130     */
131    boolean isBefore(ReadableInstant instant);
132
133    //-----------------------------------------------------------------------
134    /**
135     * Compares this object with the specified object for equality based
136     * on the millisecond instant and the Chronology. All ReadableInstant
137     * instances are accepted.
138     * <p>
139     * To compare two instants for absolute time (ie. UTC milliseconds 
140     * ignoring the chronology), use {@link #isEqual(ReadableInstant)} or
141     * {@link #compareTo(Object)}.
142     *
143     * @param readableInstant  a readable instant to check against
144     * @return true if millisecond and chronology are equal, false if
145     *  not or the instant is null or of an incorrect type
146     */
147    boolean equals(Object readableInstant);
148
149    /**
150     * Gets a hash code for the instant that is compatible with the 
151     * equals method.
152     * <p>
153     * The formula used must be as follows:
154     * <pre>
155     * ((int) (getMillis() ^ (getMillis() >>> 32))) +
156     * (getChronology().hashCode())
157     * </pre>
158     *
159     * @return a hash code as defined above
160     */
161    int hashCode();
162
163    //-----------------------------------------------------------------------
164    /**
165     * Get the value as a String in a recognisable ISO8601 format.
166     * <p>
167     * The string output is in ISO8601 format to enable the String
168     * constructor to correctly parse it.
169     *
170     * @return the value as an ISO8601 string
171     */
172    String toString();
173
174}