/* * Joda Software License, Version 1.0 * * * Copyright (c) 2001-2004 Stephen Colebourne. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * 3. The end-user documentation included with the redistribution, * if any, must include the following acknowledgment: * "This product includes software developed by the * Joda project (http://www.joda.org/)." * Alternately, this acknowledgment may appear in the software itself, * if and wherever such third-party acknowledgments normally appear. * * 4. The name "Joda" must not be used to endorse or promote products * derived from this software without prior written permission. For * written permission, please contact licence@joda.org. * * 5. Products derived from this software may not be called "Joda", * nor may "Joda" appear in their name, without prior written * permission of the Joda project. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE JODA AUTHORS OR THE PROJECT * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Joda project and was originally * created by Stephen Colebourne . For more * information on the Joda project, please see . */ package org.joda.time; /** * Defines an exact duration of time in milliseconds. *

* The implementation of this interface may be mutable or immutable. This * interface only gives access to retrieve data, never to change it. *

* Methods that are passed a duration as a parameter will treat null * as a zero length duration. * * @see ReadableInterval * @see ReadablePeriod * @author Brian S O'Neill * @author Stephen Colebourne * @since 1.0 */ public interface ReadableDuration extends Comparable { /** * Gets the total length of this duration in milliseconds. * * @return the total length of the time duration in milliseconds. */ long getMillis(); //----------------------------------------------------------------------- /** * Get this duration as an immutable Duration object. *

* This will either typecast this instance, or create a new Duration. * * @return a Duration created using the millisecond duration from this instance */ Duration toDuration(); //----------------------------------------------------------------------- /** * Converts this duration to a Period instance using the standard period type * and the ISO chronology. *

* Only precise fields in the period type will be used. Thus, only the hour, * minute, second and millisecond fields on the period will be used. * The year, month, week and day fields will not be populated. *

* If the duration is small, less than one day, then this method will perform * as you might expect and split the fields evenly. * If the duration is larger than one day then all the remaining duration will * be stored in the largest available field, hours in this case. *

* For example, a duration effectively equal to (365 + 60 + 5) days will be * converted to ((365 + 60 + 5) * 24) hours by this constructor. *

* For more control over the conversion process, you must pair the duration with * an instant, see {@link Period#Period(ReadableInstant,ReadableDuration)}. * * @return a Period created using the millisecond duration from this instance */ Period toPeriod(); //----------------------------------------------------------------------- /** * Compares this duration with the specified duration based on length. * * @param obj a duration 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 given object is not supported */ int compareTo(Object obj); /** * Is the length of this duration equal to the duration passed in. * * @param duration another duration to compare to, null means zero milliseconds * @return true if this duration is equal to than the duration passed in */ boolean isEqual(ReadableDuration duration); /** * Is the length of this duration longer than the duration passed in. * * @param duration another duration to compare to, null means zero milliseconds * @return true if this duration is equal to than the duration passed in */ boolean isLongerThan(ReadableDuration duration); /** * Is the length of this duration shorter than the duration passed in. * * @param duration another duration to compare to, null means zero milliseconds * @return true if this duration is equal to than the duration passed in */ boolean isShorterThan(ReadableDuration duration); //----------------------------------------------------------------------- /** * Compares this object with the specified object for equality based * on the millisecond length. All ReadableDuration instances are accepted. * * @param readableDuration a readable duration to check against * @return true if the length of the duration is equal */ boolean equals(Object readableDuration); /** * Gets a hash code for the duration that is compatable with the * equals method. * The following formula must be used: * 

     *  long len = getMillis();
     *  return (int) (len ^ (len >>> 32));
     *
* * @return a hash code */ int hashCode(); //----------------------------------------------------------------------- /** * Gets the value as a String in the ISO8601 duration format using hours, * minutes and seconds (including fractional milliseconds). *

* For example, "PT6H3M7S" represents 6 hours, 3 minutes, 7 seconds. * * @return the value as an ISO8601 string */ String toString(); }