ReadableInstant


1   /*
2    *  Copyright 2001-2005 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   *
29   * @author Stephen Colebourne
30   * @since 1.0
31   */
32  public interface ReadableInstant extends Comparable   {
33  
34      /**
35       * Get the value as the number of milliseconds since
36       * the epoch, 1970-01-01T00:00:00Z.
37       *
38       * @return the value as milliseconds
39       */
40      long getMillis();
41  
42      /**
43       * Gets the chronology of the instant.
44       * <p>
45       * The {@link Chronology} provides conversion from the millisecond
46       * value to meaningful fields in a particular calendar system.
47       * 
48       * @return the Chronology, never null
49       */
50      Chronology getChronology();
51  
52      /**
53       * Gets the time zone of the instant from the chronology.
54       * 
55       * @return the DateTimeZone that the instant is using, never null
56       */
57      DateTimeZone getZone();
58  
59      /**
60       * Get the value of one of the fields of a datetime.
61       * <p>
62       * This method uses the chronology of the instant to obtain the value.
63       *
64       * @param type  a field type, usually obtained from DateTimeFieldType, not null
65       * @return the value of that field
66       * @throws IllegalArgumentException if the field type is null
67       */
68      int get(DateTimeFieldType type);
69  
70      /**
71       * Checks whether the field type specified is supported by this implementation.
72       *
73       * @param field  the field type to check, may be null which returns false
74       * @return true if the field is supported
75       */
76      boolean isSupported(DateTimeFieldType field);
77  
78      //-----------------------------------------------------------------------
79      /**
80       * Get the value as a simple immutable <code>Instant</code> object.
81       * <p>
82       * This can be useful if you don't trust the implementation
83       * of the interface to be well-behaved, or to get a guaranteed
84       * immutable object.
85       *
86       * @return the value as an <code>Instant</code> object
87       */
88      Instant toInstant();
89  
90      //-----------------------------------------------------------------------
91      /**
92       * Compares this object with the specified object for ascending
93       * millisecond instant order. This ordering is inconsistent with
94       * equals, as it ignores the Chronology.
95       * <p>
96       * All ReadableInstant instances are accepted.
97       *
98       * @param readableInstant  a readable instant to check against
99       * @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 }
175
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags