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 exact duration of time in milliseconds. 20 * <p> 21 * The implementation of this interface may be mutable or immutable. This 22 * interface only gives access to retrieve data, never to change it. 23 * <p> 24 * Methods that are passed a duration as a parameter will treat <code>null</code> 25 * as a zero length duration. 26 * <p> 27 * The {@code compareTo} method is no longer defined in this class in version 2.0. 28 * Instead, the definition is simply inherited from the {@code Comparable} interface. 29 * This approach is necessary to preserve binary compatibility. 30 * The definition of the comparison is ascending order by millisecond duration. 31 * Implementors are recommended to extend {@code AbstractInstant} instead of this interface. 32 * 33 * @see ReadableInterval 34 * @see ReadablePeriod 35 * @author Brian S O'Neill 36 * @author Stephen Colebourne 37 * @since 1.0 38 */ 39 public interface ReadableDuration extends Comparable<ReadableDuration> { 40 41 /** 42 * Gets the total length of this duration in milliseconds. 43 * 44 * @return the total length of the time duration in milliseconds. 45 */ 46 long getMillis(); 47 48 //----------------------------------------------------------------------- 49 /** 50 * Get this duration as an immutable <code>Duration</code> object. 51 * <p> 52 * This will either typecast this instance, or create a new <code>Duration</code>. 53 * 54 * @return a Duration created using the millisecond duration from this instance 55 */ 56 Duration toDuration(); 57 58 //----------------------------------------------------------------------- 59 /** 60 * Converts this duration to a Period instance using the standard period type 61 * and the ISO chronology. 62 * <p> 63 * Only precise fields in the period type will be used. Thus, only the hour, 64 * minute, second and millisecond fields on the period will be used. 65 * The year, month, week and day fields will not be populated. 66 * <p> 67 * If the duration is small, less than one day, then this method will perform 68 * as you might expect and split the fields evenly. 69 * If the duration is larger than one day then all the remaining duration will 70 * be stored in the largest available field, hours in this case. 71 * <p> 72 * For example, a duration effectively equal to (365 + 60 + 5) days will be 73 * converted to ((365 + 60 + 5) * 24) hours by this constructor. 74 * <p> 75 * For more control over the conversion process, you must pair the duration with 76 * an instant, see {@link Period#Period(ReadableInstant,ReadableDuration)}. 77 * 78 * @return a Period created using the millisecond duration from this instance 79 */ 80 Period toPeriod(); 81 82 //----------------------------------------------------------------------- 83 // Method is no longer defined here as that would break generic backwards compatibility 84 // /** 85 // * Compares this duration with the specified duration based on length. 86 // * 87 // * @param obj a duration to check against 88 // * @return negative value if this is less, 0 if equal, or positive value if greater 89 // * @throws NullPointerException if the object is null 90 // * @throws ClassCastException if the given object is not supported 91 // */ 92 // int compareTo(ReadableDuration obj); 93 94 /** 95 * Is the length of this duration equal to the duration passed in. 96 * 97 * @param duration another duration to compare to, null means zero milliseconds 98 * @return true if this duration is equal to than the duration passed in 99 */ 100 boolean isEqual(ReadableDuration duration); 101 102 /** 103 * Is the length of this duration longer than the duration passed in. 104 * 105 * @param duration another duration to compare to, null means zero milliseconds 106 * @return true if this duration is equal to than the duration passed in 107 */ 108 boolean isLongerThan(ReadableDuration duration); 109 110 /** 111 * Is the length of this duration shorter than the duration passed in. 112 * 113 * @param duration another duration to compare to, null means zero milliseconds 114 * @return true if this duration is equal to than the duration passed in 115 */ 116 boolean isShorterThan(ReadableDuration duration); 117 118 //----------------------------------------------------------------------- 119 /** 120 * Compares this object with the specified object for equality based 121 * on the millisecond length. All ReadableDuration instances are accepted. 122 * 123 * @param readableDuration a readable duration to check against 124 * @return true if the length of the duration is equal 125 */ 126 boolean equals(Object readableDuration); 127 128 /** 129 * Gets a hash code for the duration that is compatable with the 130 * equals method. 131 * The following formula must be used: 132 * <pre> 133 * long len = getMillis(); 134 * return (int) (len ^ (len >>> 32)); 135 * </pre> 136 * 137 * @return a hash code 138 */ 139 int hashCode(); 140 141 //----------------------------------------------------------------------- 142 /** 143 * Gets the value as a String in the ISO8601 duration format using hours, 144 * minutes and seconds (including fractional milliseconds). 145 * <p> 146 * For example, "PT6H3M7S" represents 6 hours, 3 minutes, 7 seconds. 147 * 148 * @return the value as an ISO8601 string 149 */ 150 String toString(); 151 152 }