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: */
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: *
029: * @author Stephen Colebourne
030: * @since 1.0
031: */
032: public 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: }
|