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 an instant in 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 * <p>
024 * Methods in your application should be defined using <code>ReadWritableDateTime</code>
025 * as a parameter if the method wants to manipulate and change a date in simple ways.
026 *
027 * @author Stephen Colebourne
028 * @author Brian S O'Neill
029 * @since 1.0
030 */
031public interface ReadWritableDateTime extends ReadableDateTime, ReadWritableInstant {
032    
033    //-----------------------------------------------------------------------
034    /**
035     * Set the year to the specified value.
036     *
037     * @param year  the year
038     * @throws IllegalArgumentException if the value is invalid
039     */
040    void setYear(int year);
041
042    /**
043     * Add a number of years to the date.
044     *
045     * @param years  the years to add
046     * @throws IllegalArgumentException if the value is invalid
047     */
048    void addYears(int years);
049
050    //-----------------------------------------------------------------------
051    /**
052     * Set the weekyear to the specified value.
053     *
054     * @param weekyear  the weekyear
055     * @throws IllegalArgumentException if the value is invalid
056     */
057    void setWeekyear(int weekyear);
058
059    /**
060     * Add a number of weekyears to the date.
061     *
062     * @param weekyears  the weekyears to add
063     * @throws IllegalArgumentException if the value is invalid
064     */
065    void addWeekyears(int weekyears);
066
067    //-----------------------------------------------------------------------
068    /**
069     * Set the month of the year to the specified value.
070     *
071     * @param monthOfYear  the month of the year
072     * @throws IllegalArgumentException if the value is invalid
073     */
074    void setMonthOfYear(int monthOfYear);
075
076    /**
077     * Add a number of months to the date.
078     *
079     * @param months  the months to add
080     * @throws IllegalArgumentException if the value is invalid
081     */
082    void addMonths(int months);
083
084    //-----------------------------------------------------------------------
085    /**
086     * Set the week of weekyear to the specified value.
087     *
088     * @param weekOfWeekyear the week of the weekyear
089     * @throws IllegalArgumentException if the value is invalid
090     */
091    void setWeekOfWeekyear(int weekOfWeekyear);
092
093    /**
094     * Add a number of weeks to the date.
095     *
096     * @param weeks  the weeks to add
097     * @throws IllegalArgumentException if the value is invalid
098     */
099    void addWeeks(int weeks);
100
101    //-----------------------------------------------------------------------
102    /**
103     * Set the day of year to the specified value.
104     *
105     * @param dayOfYear the day of the year
106     * @throws IllegalArgumentException if the value is invalid
107     */
108    void setDayOfYear(int dayOfYear);
109
110    /**
111     * Set the day of the month to the specified value.
112     *
113     * @param dayOfMonth  the day of the month
114     * @throws IllegalArgumentException if the value is invalid
115     */
116    void setDayOfMonth(int dayOfMonth);
117
118    /**
119     * Set the day of week to the specified value.
120     *
121     * @param dayOfWeek  the day of the week
122     * @throws IllegalArgumentException if the value is invalid
123     */
124    void setDayOfWeek(int dayOfWeek);
125
126    /**
127     * Add a number of days to the date.
128     *
129     * @param days  the days to add
130     * @throws IllegalArgumentException if the value is invalid
131     */
132    void addDays(int days);
133
134    //-----------------------------------------------------------------------
135    /**
136     * Set the hour of the day to the specified value.
137     *
138     * @param hourOfDay  the hour of day
139     * @throws IllegalArgumentException if the value is invalid
140     */
141    void setHourOfDay(int hourOfDay);
142
143    /**
144     * Add a number of hours to the date.
145     *
146     * @param hours  the hours to add
147     * @throws IllegalArgumentException if the value is invalid
148     */
149    void addHours(int hours);
150    
151    //-----------------------------------------------------------------------
152    /**
153     * Set the minute of the day to the specified value.
154     *
155     * @param minuteOfDay  the minute of day
156     * @throws IllegalArgumentException if the value is invalid
157     */
158    void setMinuteOfDay(int minuteOfDay);
159
160    /**
161     * Set the minute of the hour to the specified value.
162     *
163     * @param minuteOfHour  the minute of hour
164     * @throws IllegalArgumentException if the value is invalid
165     */
166    void setMinuteOfHour(int minuteOfHour);
167
168    /**
169     * Add a number of minutes to the date.
170     *
171     * @param minutes  the minutes to add
172     * @throws IllegalArgumentException if the value is invalid
173     */
174    void addMinutes(int minutes);
175
176    //-----------------------------------------------------------------------
177    /**
178     * Set the second of the day to the specified value.
179     *
180     * @param secondOfDay  the second of day
181     * @throws IllegalArgumentException if the value is invalid
182     */
183    void setSecondOfDay(int secondOfDay);
184
185    /**
186     * Set the second of the minute to the specified value.
187     *
188     * @param secondOfMinute  the second of minute
189     * @throws IllegalArgumentException if the value is invalid
190     */
191    void setSecondOfMinute(int secondOfMinute);
192
193    /**
194     * Add a number of seconds to the date.
195     *
196     * @param seconds  the seconds to add
197     * @throws IllegalArgumentException if the value is invalid
198     */
199    void addSeconds(int seconds);
200
201    //-----------------------------------------------------------------------
202    /**
203     * Set the millis of the day to the specified value.
204     *
205     * @param millisOfDay  the millis of day
206     * @throws IllegalArgumentException if the value is invalid
207     */
208    void setMillisOfDay(int millisOfDay);
209
210    /**
211     * Set the millis of the second to the specified value.
212     *
213     * @param millisOfSecond  the millis of second
214     * @throws IllegalArgumentException if the value is invalid
215     */
216    void setMillisOfSecond(int millisOfSecond);
217
218    /**
219     * Add a number of milliseconds to the date. The implementation of this
220     * method differs from the {@link #add(long)} method in that a
221     * DateTimeField performs the addition.
222     *
223     * @param millis  the milliseconds to add
224     * @throws IllegalArgumentException if the value is invalid
225     */
226    void addMillis(int millis);
227
228    /**
229     * Set the date from fields.
230     * The time part of this object will be unaffected.
231     *
232     * @param year  the year
233     * @param monthOfYear  the month of the year
234     * @param dayOfMonth  the day of the month
235     * @throws IllegalArgumentException if any value is invalid
236     */
237    void setDate(int year, int monthOfYear, int dayOfMonth);
238
239    /**
240     * Set the time from fields.
241     * The date part of this object will be unaffected.
242     *
243     * @param hour  the hour
244     * @param minuteOfHour  the minute of the hour
245     * @param secondOfMinute  the second of the minute
246     * @param millisOfSecond  the millisecond of the second
247     * @throws IllegalArgumentException if any value is invalid
248     */
249    void setTime(int hour, int minuteOfHour, int secondOfMinute, int millisOfSecond);
250
251    /**
252     * Set the date and time from fields.
253     *
254     * @param year  the year
255     * @param monthOfYear  the month of the year
256     * @param dayOfMonth  the day of the month
257     * @param hourOfDay  the hour of the day
258     * @param minuteOfHour  the minute of the hour
259     * @param secondOfMinute  the second of the minute
260     * @param millisOfSecond  the millisecond of the second
261     * @throws IllegalArgumentException if any value is invalid
262     */
263    void setDateTime(
264        int year, int monthOfYear, int dayOfMonth,
265        int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond);
266
267}