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    }