View Javadoc

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 }