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 }