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, int hours,
125: 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: }
|