001 /* 002 * Copyright 2001-2005 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 a duration of time that can be queried and modified using datetime fields. 020 * <p> 021 * The implementation of this interface will be mutable. 022 * It may provide more advanced methods than those in the interface. 023 * 024 * @author Brian S O'Neill 025 * @author Stephen Colebourne 026 * @since 1.0 027 */ 028 public interface ReadWritablePeriod extends ReadablePeriod { 029 030 /** 031 * Clears the period, setting all values back to zero. 032 */ 033 void clear(); 034 035 /** 036 * Sets the value of one of the fields by index. 037 * 038 * @param index the field index 039 * @param value the new value for the field 040 * @throws IndexOutOfBoundsException if the index is invalid 041 */ 042 void setValue(int index, int value); 043 044 /** 045 * Sets the value of one of the fields. 046 * <p> 047 * The field type specified must be one of those that is supported by the period. 048 * 049 * @param field a DurationFieldType instance that is supported by this period 050 * @param value the new value for the field 051 * @throws IllegalArgumentException if the field is null or not supported 052 */ 053 void set(DurationFieldType field, int value); 054 055 /** 056 * Sets all the fields in one go from another ReadablePeriod. 057 * 058 * @param period the period to set, null means zero length period 059 * @throws IllegalArgumentException if an unsupported field's value is non-zero 060 */ 061 void setPeriod(ReadablePeriod period); 062 063 /** 064 * Sets all the fields in one go. 065 * 066 * @param years amount of years in this period, which must be zero if unsupported 067 * @param months amount of months in this period, which must be zero if unsupported 068 * @param weeks amount of weeks in this period, which must be zero if unsupported 069 * @param days amount of days in this period, which must be zero if unsupported 070 * @param hours amount of hours in this period, which must be zero if unsupported 071 * @param minutes amount of minutes in this period, which must be zero if unsupported 072 * @param seconds amount of seconds in this period, which must be zero if unsupported 073 * @param millis amount of milliseconds in this period, which must be zero if unsupported 074 * @throws IllegalArgumentException if an unsupported field's value is non-zero 075 */ 076 void setPeriod(int years, int months, int weeks, int days, 077 int hours, int minutes, int seconds, int millis); 078 079 /** 080 * Sets all the fields in one go from an interval dividing the 081 * fields using the period type. 082 * 083 * @param interval the interval to set, null means zero length 084 */ 085 void setPeriod(ReadableInterval interval); 086 087 //----------------------------------------------------------------------- 088 /** 089 * Adds to the value of one of the fields. 090 * <p> 091 * The field type specified must be one of those that is supported by the period. 092 * 093 * @param field a DurationFieldType instance that is supported by this period 094 * @param value the value to add to the field 095 * @throws IllegalArgumentException if the field is null or not supported 096 */ 097 void add(DurationFieldType field, int value); 098 099 /** 100 * Adds a period to this one by adding each field in turn. 101 * 102 * @param period the period to add, null means add nothing 103 * @throws IllegalArgumentException if the period being added contains a field 104 * not supported by this period 105 * @throws ArithmeticException if the addition exceeds the capacity of the period 106 */ 107 void add(ReadablePeriod period); 108 109 /** 110 * Adds to each field of this period. 111 * 112 * @param years amount of years to add to this period, which must be zero if unsupported 113 * @param months amount of months to add to this period, which must be zero if unsupported 114 * @param weeks amount of weeks to add to this period, which must be zero if unsupported 115 * @param days amount of days to add to this period, which must be zero if unsupported 116 * @param hours amount of hours to add to this period, which must be zero if unsupported 117 * @param minutes amount of minutes to add to this period, which must be zero if unsupported 118 * @param seconds amount of seconds to add to this period, which must be zero if unsupported 119 * @param millis amount of milliseconds to add to this period, which must be zero if unsupported 120 * @throws IllegalArgumentException if the period being added contains a field 121 * not supported by this period 122 * @throws ArithmeticException if the addition exceeds the capacity of the period 123 */ 124 void add(int years, int months, int weeks, int days, 125 int hours, int minutes, int seconds, int millis); 126 127 /** 128 * Adds an interval to this one by dividing the interval into 129 * fields and then adding each field in turn. 130 * 131 * @param interval the interval to add, null means add nothing 132 * @throws ArithmeticException if the addition exceeds the capacity of the period 133 */ 134 void add(ReadableInterval interval); 135 136 //----------------------------------------------------------------------- 137 /** 138 * Sets the number of years of the period. 139 * 140 * @param years the number of years 141 * @throws IllegalArgumentException if field is not supported and the value is non-zero 142 */ 143 void setYears(int years); 144 145 /** 146 * Adds the specified years to the number of years in the period. 147 * 148 * @param years the number of years 149 * @throws IllegalArgumentException if field is not supported and the value is non-zero 150 * @throws ArithmeticException if the addition exceeds the capacity of the period 151 */ 152 void addYears(int years); 153 154 //----------------------------------------------------------------------- 155 /** 156 * Sets the number of months of the period. 157 * 158 * @param months the number of months 159 * @throws IllegalArgumentException if field is not supported and the value is non-zero 160 */ 161 void setMonths(int months); 162 163 /** 164 * Adds the specified months to the number of months in the period. 165 * 166 * @param months the number of months 167 * @throws IllegalArgumentException if field is not supported and the value is non-zero 168 * @throws ArithmeticException if the addition exceeds the capacity of the period 169 */ 170 void addMonths(int months); 171 172 //----------------------------------------------------------------------- 173 /** 174 * Sets the number of weeks of the period. 175 * 176 * @param weeks the number of weeks 177 * @throws IllegalArgumentException if field is not supported and the value is non-zero 178 */ 179 void setWeeks(int weeks); 180 181 /** 182 * Adds the specified weeks to the number of weeks in the period. 183 * 184 * @param weeks the number of weeks 185 * @throws IllegalArgumentException if field is not supported and the value is non-zero 186 * @throws ArithmeticException if the addition exceeds the capacity of the period 187 */ 188 void addWeeks(int weeks); 189 190 //----------------------------------------------------------------------- 191 /** 192 * Sets the number of days of the period. 193 * 194 * @param days the number of days 195 * @throws IllegalArgumentException if field is not supported and the value is non-zero 196 */ 197 void setDays(int days); 198 199 /** 200 * Adds the specified days to the number of days in the period. 201 * 202 * @param days the number of days 203 * @throws IllegalArgumentException if field is not supported and the value is non-zero 204 * @throws ArithmeticException if the addition exceeds the capacity of the period 205 */ 206 void addDays(int days); 207 208 //----------------------------------------------------------------------- 209 /** 210 * Sets the number of hours of the period. 211 * 212 * @param hours the number of hours 213 * @throws IllegalArgumentException if field is not supported and the value is non-zero 214 */ 215 void setHours(int hours); 216 217 /** 218 * Adds the specified hours to the number of hours in the period. 219 * 220 * @param hours the number of hours 221 * @throws IllegalArgumentException if field is not supported and the value is non-zero 222 * @throws ArithmeticException if the addition exceeds the capacity of the period 223 */ 224 void addHours(int hours); 225 226 //----------------------------------------------------------------------- 227 /** 228 * Sets the number of minutes of the period. 229 * 230 * @param minutes the number of minutes 231 * @throws IllegalArgumentException if field is not supported and the value is non-zero 232 */ 233 void setMinutes(int minutes); 234 235 /** 236 * Adds the specified minutes to the number of minutes in the period. 237 * 238 * @param minutes the number of minutes 239 * @throws IllegalArgumentException if field is not supported and the value is non-zero 240 * @throws ArithmeticException if the addition exceeds the capacity of the period 241 */ 242 void addMinutes(int minutes); 243 244 //----------------------------------------------------------------------- 245 /** 246 * Sets the number of seconds of the period. 247 * 248 * @param seconds the number of seconds 249 * @throws IllegalArgumentException if field is not supported and the value is non-zero 250 */ 251 void setSeconds(int seconds); 252 253 /** 254 * Adds the specified seconds to the number of seconds in the period. 255 * 256 * @param seconds the number of seconds 257 * @throws IllegalArgumentException if field is not supported and the value is non-zero 258 * @throws ArithmeticException if the addition exceeds the capacity of the period 259 */ 260 void addSeconds(int seconds); 261 262 //----------------------------------------------------------------------- 263 /** 264 * Sets the number of millis of the period. 265 * 266 * @param millis the number of millis 267 * @throws IllegalArgumentException if field is not supported and the value is non-zero 268 */ 269 void setMillis(int millis); 270 271 /** 272 * Adds the specified millis to the number of millis in the period. 273 * 274 * @param millis the number of millis 275 * @throws IllegalArgumentException if field is not supported and the value is non-zero 276 * @throws ArithmeticException if the addition exceeds the capacity of the period 277 */ 278 void addMillis(int millis); 279 280 }