001 /* 002 * Copyright 2001-2009 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 exact duration of time in milliseconds. 020 * <p> 021 * The implementation of this interface may be mutable or immutable. This 022 * interface only gives access to retrieve data, never to change it. 023 * <p> 024 * Methods that are passed a duration as a parameter will treat <code>null</code> 025 * as a zero length duration. 026 * <p> 027 * The {@code compareTo} method is no longer defined in this class in version 2.0. 028 * Instead, the definition is simply inherited from the {@code Comparable} interface. 029 * This approach is necessary to preserve binary compatibility. 030 * The definition of the comparison is ascending order by millisecond duration. 031 * Implementors are recommended to extend {@code AbstractInstant} instead of this interface. 032 * 033 * @see ReadableInterval 034 * @see ReadablePeriod 035 * @author Brian S O'Neill 036 * @author Stephen Colebourne 037 * @since 1.0 038 */ 039 public interface ReadableDuration extends Comparable<ReadableDuration> { 040 041 /** 042 * Gets the total length of this duration in milliseconds. 043 * 044 * @return the total length of the time duration in milliseconds. 045 */ 046 long getMillis(); 047 048 //----------------------------------------------------------------------- 049 /** 050 * Get this duration as an immutable <code>Duration</code> object. 051 * <p> 052 * This will either typecast this instance, or create a new <code>Duration</code>. 053 * 054 * @return a Duration created using the millisecond duration from this instance 055 */ 056 Duration toDuration(); 057 058 //----------------------------------------------------------------------- 059 /** 060 * Converts this duration to a Period instance using the standard period type 061 * and the ISO chronology. 062 * <p> 063 * Only precise fields in the period type will be used. Thus, only the hour, 064 * minute, second and millisecond fields on the period will be used. 065 * The year, month, week and day fields will not be populated. 066 * <p> 067 * If the duration is small, less than one day, then this method will perform 068 * as you might expect and split the fields evenly. 069 * If the duration is larger than one day then all the remaining duration will 070 * be stored in the largest available field, hours in this case. 071 * <p> 072 * For example, a duration effectively equal to (365 + 60 + 5) days will be 073 * converted to ((365 + 60 + 5) * 24) hours by this constructor. 074 * <p> 075 * For more control over the conversion process, you must pair the duration with 076 * an instant, see {@link Period#Period(ReadableInstant,ReadableDuration)}. 077 * 078 * @return a Period created using the millisecond duration from this instance 079 */ 080 Period toPeriod(); 081 082 //----------------------------------------------------------------------- 083 // Method is no longer defined here as that would break generic backwards compatibility 084 // /** 085 // * Compares this duration with the specified duration based on length. 086 // * 087 // * @param obj a duration to check against 088 // * @return negative value if this is less, 0 if equal, or positive value if greater 089 // * @throws NullPointerException if the object is null 090 // * @throws ClassCastException if the given object is not supported 091 // */ 092 // int compareTo(ReadableDuration obj); 093 094 /** 095 * Is the length of this duration equal to the duration passed in. 096 * 097 * @param duration another duration to compare to, null means zero milliseconds 098 * @return true if this duration is equal to than the duration passed in 099 */ 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 }