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 */
016package 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 */
028public 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}