Java tutorial
/* * Copyright 2001-2009 Stephen Colebourne * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.joda.time; /** * Defines an instant in the datetime continuum. * This interface expresses the datetime as milliseconds from 1970-01-01T00:00:00Z. * <p> * The implementation of this interface may be mutable or immutable. * This interface only gives access to retrieve data, never to change it. * <p> * Methods in your application should be defined using <code>ReadableInstant</code> * as a parameter if the method only wants to read the instant without needing to know * the specific datetime fields. * <p> * The {@code compareTo} method is no longer defined in this class in version 2.0. * Instead, the definition is simply inherited from the {@code Comparable} interface. * This approach is necessary to preserve binary compatibility. * The definition of the comparison is ascending order by millisecond instant. * Implementors are recommended to extend {@code AbstractInstant} instead of this interface. * * @author Stephen Colebourne * @since 1.0 */ public interface ReadableInstant extends Comparable<ReadableInstant> { /** * Get the value as the number of milliseconds since * the epoch, 1970-01-01T00:00:00Z. * * @return the value as milliseconds */ long getMillis(); /** * Gets the chronology of the instant. * <p> * The {@link Chronology} provides conversion from the millisecond * value to meaningful fields in a particular calendar system. * * @return the Chronology, never null */ Chronology getChronology(); /** * Gets the time zone of the instant from the chronology. * * @return the DateTimeZone that the instant is using, never null */ DateTimeZone getZone(); /** * Get the value of one of the fields of a datetime. * <p> * This method uses the chronology of the instant to obtain the value. * * @param type a field type, usually obtained from DateTimeFieldType, not null * @return the value of that field * @throws IllegalArgumentException if the field type is null */ int get(DateTimeFieldType type); /** * Checks whether the field type specified is supported by this implementation. * * @param field the field type to check, may be null which returns false * @return true if the field is supported */ boolean isSupported(DateTimeFieldType field); //----------------------------------------------------------------------- /** * Get the value as a simple immutable <code>Instant</code> object. * <p> * This can be useful if you don't trust the implementation * of the interface to be well-behaved, or to get a guaranteed * immutable object. * * @return the value as an <code>Instant</code> object */ Instant toInstant(); //----------------------------------------------------------------------- // Method is no longer defined here as that would break generic backwards compatibility // /** // * Compares this object with the specified object for ascending // * millisecond instant order. This ordering is inconsistent with // * equals, as it ignores the Chronology. // * <p> // * All ReadableInstant instances are accepted. // * // * @param readableInstant a readable instant to check against // * @return negative value if this is less, 0 if equal, or positive value if greater // * @throws NullPointerException if the object is null // * @throws ClassCastException if the object type is not supported // */ // int compareTo(ReadableInstant readableInstant); //----------------------------------------------------------------------- /** * Is this instant equal to the instant passed in * comparing solely by millisecond. * * @param instant an instant to check against, null means now * @return true if the instant is equal to the instant passed in */ boolean isEqual(ReadableInstant instant); /** * Is this instant after the instant passed in * comparing solely by millisecond. * * @param instant an instant to check against, null means now * @return true if the instant is after the instant passed in */ boolean isAfter(ReadableInstant instant); /** * Is this instant before the instant passed in * comparing solely by millisecond. * * @param instant an instant to check against, null means now * @return true if the instant is before the instant passed in */ boolean isBefore(ReadableInstant instant); //----------------------------------------------------------------------- /** * Compares this object with the specified object for equality based * on the millisecond instant and the Chronology. All ReadableInstant * instances are accepted. * <p> * To compare two instants for absolute time (ie. UTC milliseconds * ignoring the chronology), use {@link #isEqual(ReadableInstant)} or * {@link #compareTo(Object)}. * * @param readableInstant a readable instant to check against * @return true if millisecond and chronology are equal, false if * not or the instant is null or of an incorrect type */ boolean equals(Object readableInstant); /** * Gets a hash code for the instant that is compatible with the * equals method. * <p> * The formula used must be as follows: * <pre> * ((int) (getMillis() ^ (getMillis() >>> 32))) + * (getChronology().hashCode()) * </pre> * * @return a hash code as defined above */ int hashCode(); //----------------------------------------------------------------------- /** * Get the value as a String in a recognisable ISO8601 format. * <p> * The string output is in ISO8601 format to enable the String * constructor to correctly parse it. * * @return the value as an ISO8601 string */ String toString(); }