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/**
020 * Chronology provides access to the individual date time fields for a
021 * chronological calendar system.
022 * <p>
023 * Various chronologies are supported by subclasses including ISO
024 * and GregorianJulian. To construct a Chronology you should use the
025 * factory methods on the chronology subclass in the chrono package.
026 * <p>
027 * For example, to obtain the current time in the coptic calendar system:
028 * <pre>
029 * DateTime dt = new DateTime(CopticChronology.getInstance());
030 * </pre>
031 * <p>
032 * The provided chronology implementations are:
033 * <ul>
034 * <li>ISO - Based on the ISO8601 standard and suitable for use after about 1600
035 * <li>GJ - Historically accurate calendar with Julian followed by Gregorian
036 * <li>Gregorian - The Gregorian calendar system used for all time (proleptic)
037 * <li>Julian - The Julian calendar system used for all time (proleptic)
038 * <li>Buddhist - The Buddhist calendar system which is an offset in years from GJ
039 * <li>Coptic - The Coptic calendar system which defines 30 day months
040 * <li>Ethiopic - The Ethiopic calendar system which defines 30 day months
041 * </ul>
042 * Hopefully future releases will contain more chronologies.
043 * <p>
044 * This class defines a number of fields with names from the ISO8601 standard.
045 * It does not 'strongly' define these fields however, thus implementations
046 * are free to interpret the field names as they wish.
047 * For example, a week could be defined as 10 days and a month as 40 days in a
048 * special WeirdChronology implementation. Clearly the GJ and ISO
049 * implementations provided use the field names as you would expect.
050 *
051 * @see org.joda.time.chrono.ISOChronology
052 * @see org.joda.time.chrono.GJChronology
053 * @see org.joda.time.chrono.GregorianChronology
054 * @see org.joda.time.chrono.JulianChronology
055 * @see org.joda.time.chrono.CopticChronology
056 * @see org.joda.time.chrono.BuddhistChronology
057 * @see org.joda.time.chrono.EthiopicChronology
058 *
059 * @author Stephen Colebourne
060 * @author Brian S O'Neill
061 * @since 1.0
062 */
063public abstract class Chronology {
064
065    /**
066     * Returns the DateTimeZone that this Chronology operates in, or null if
067     * unspecified.
068     *
069     * @return the DateTimeZone, null if unspecified
070     */
071    public abstract DateTimeZone getZone();
072
073    /**
074     * Returns an instance of this Chronology that operates in the UTC time
075     * zone. Chronologies that do not operate in a time zone or are already
076     * UTC must return themself.
077     *
078     * @return a version of this chronology that ignores time zones
079     */
080    public abstract Chronology withUTC();
081    
082    /**
083     * Returns an instance of this Chronology that operates in any time zone.
084     *
085     * @return a version of this chronology with a specific time zone
086     * @param zone to use, or default if null
087     * @see org.joda.time.chrono.ZonedChronology
088     */
089    public abstract Chronology withZone(DateTimeZone zone);
090
091    /**
092     * Returns a datetime millisecond instant, formed from the given year,
093     * month, day, and millisecond values. The set of given values must refer
094     * to a valid datetime, or else an IllegalArgumentException is thrown.
095     * <p>
096     * The default implementation calls upon separate DateTimeFields to
097     * determine the result. Subclasses are encouraged to provide a more
098     * efficient implementation.
099     *
100     * @param year year to use
101     * @param monthOfYear month to use
102     * @param dayOfMonth day of month to use
103     * @param millisOfDay millisecond to use
104     * @return millisecond instant from 1970-01-01T00:00:00Z
105     * @throws IllegalArgumentException if the values are invalid
106     */
107    public abstract long getDateTimeMillis(int year, int monthOfYear, int dayOfMonth, int millisOfDay);
108
109    /**
110     * Returns a datetime millisecond instant, formed from the given year,
111     * month, day, hour, minute, second, and millisecond values. The set of
112     * given values must refer to a valid datetime, or else an
113     * IllegalArgumentException is thrown.
114     * <p>
115     * The default implementation calls upon separate DateTimeFields to
116     * determine the result. Subclasses are encouraged to provide a more
117     * efficient implementation.
118     *
119     * @param year year to use
120     * @param monthOfYear month to use
121     * @param dayOfMonth day of month to use
122     * @param hourOfDay hour to use
123     * @param minuteOfHour minute to use
124     * @param secondOfMinute second to use
125     * @param millisOfSecond millisecond to use
126     * @return millisecond instant from 1970-01-01T00:00:00Z
127     * @throws IllegalArgumentException if the values are invalid
128     */
129    public abstract long getDateTimeMillis(int year, int monthOfYear, int dayOfMonth,
130                           int hourOfDay, int minuteOfHour,
131                           int secondOfMinute, int millisOfSecond);
132
133    /**
134     * Returns a datetime millisecond instant, from from the given instant,
135     * hour, minute, second, and millisecond values. The set of given values
136     * must refer to a valid datetime, or else an IllegalArgumentException is
137     * thrown.
138     * <p>
139     * The default implementation calls upon separate DateTimeFields to
140     * determine the result. Subclasses are encouraged to provide a more
141     * efficient implementation.
142     *
143     * @param instant instant to start from
144     * @param hourOfDay hour to use
145     * @param minuteOfHour minute to use
146     * @param secondOfMinute second to use
147     * @param millisOfSecond millisecond to use
148     * @return millisecond instant from 1970-01-01T00:00:00Z
149     * @throws IllegalArgumentException if the values are invalid
150     */
151    public abstract long getDateTimeMillis(long instant,
152                           int hourOfDay, int minuteOfHour,
153                           int secondOfMinute, int millisOfSecond);
154
155    //-----------------------------------------------------------------------
156    /**
157     * Validates whether the values are valid for the fields of a partial instant.
158     *
159     * @param partial  the partial instant to validate
160     * @param values  the values to validate, not null, match fields in partial
161     * @throws IllegalArgumentException if the instant is invalid
162     */
163    public abstract void validate(ReadablePartial partial, int[] values);
164
165    /**
166     * Gets the values of a partial from an instant.
167     *
168     * @param partial  the partial instant to use
169     * @param instant  the instant to query
170     * @return the values of this partial extracted from the instant
171     */
172    public abstract int[] get(ReadablePartial partial, long instant);
173
174    /**
175     * Sets the partial into the instant.
176     *
177     * @param partial  the partial instant to use
178     * @param instant  the instant to update
179     * @return the updated instant
180     */
181    public abstract long set(ReadablePartial partial, long instant);
182
183    //-----------------------------------------------------------------------
184    /**
185     * Gets the values of a period from an interval.
186     *
187     * @param period  the period instant to use
188     * @param startInstant  the start instant of an interval to query
189     * @param endInstant  the start instant of an interval to query
190     * @return the values of the period extracted from the interval
191     */
192    public abstract int[] get(ReadablePeriod period, long startInstant, long endInstant);
193
194    /**
195     * Gets the values of a period from an interval.
196     *
197     * @param period  the period instant to use
198     * @param duration  the duration to query
199     * @return the values of the period extracted from the duration
200     */
201    public abstract int[] get(ReadablePeriod period, long duration);
202
203    /**
204     * Adds the period to the instant, specifying the number of times to add.
205     *
206     * @param period  the period to add, null means add nothing
207     * @param instant  the instant to add to
208     * @param scalar  the number of times to add
209     * @return the updated instant
210     */
211    public abstract long add(ReadablePeriod period, long instant, int scalar);
212
213    //-----------------------------------------------------------------------
214    /**
215     * Adds the duration to the instant, specifying the number of times to add.
216     *
217     * @param instant  the instant to add to
218     * @param duration  the duration to add
219     * @param scalar  the number of times to add
220     * @return the updated instant
221     */
222    public abstract long add(long instant, long duration, int scalar);
223
224    // Millis
225    //-----------------------------------------------------------------------
226    /**
227     * Get the millis duration field for this chronology.
228     * 
229     * @return DurationField or UnsupportedDurationField if unsupported
230     */
231    public abstract DurationField millis();
232
233    /**
234     * Get the millis of second field for this chronology.
235     * 
236     * @return DateTimeField or UnsupportedDateTimeField if unsupported
237     */
238    public abstract DateTimeField millisOfSecond();
239
240    /**
241     * Get the millis of day field for this chronology.
242     * 
243     * @return DateTimeField or UnsupportedDateTimeField if unsupported
244     */
245    public abstract DateTimeField millisOfDay();
246
247    // Second
248    //-----------------------------------------------------------------------
249    /**
250     * Get the seconds duration field for this chronology.
251     * 
252     * @return DurationField or UnsupportedDurationField if unsupported
253     */
254    public abstract DurationField seconds();
255
256    /**
257     * Get the second of minute field for this chronology.
258     * 
259     * @return DateTimeField or UnsupportedDateTimeField if unsupported
260     */
261    public abstract DateTimeField secondOfMinute();
262
263    /**
264     * Get the second of day field for this chronology.
265     * 
266     * @return DateTimeField or UnsupportedDateTimeField if unsupported
267     */
268    public abstract DateTimeField secondOfDay();
269
270    // Minute
271    //-----------------------------------------------------------------------
272    /**
273     * Get the minutes duration field for this chronology.
274     * 
275     * @return DurationField or UnsupportedDurationField if unsupported
276     */
277    public abstract DurationField minutes();
278
279    /**
280     * Get the minute of hour field for this chronology.
281     * 
282     * @return DateTimeField or UnsupportedDateTimeField if unsupported
283     */
284    public abstract DateTimeField minuteOfHour();
285
286    /**
287     * Get the minute of day field for this chronology.
288     * 
289     * @return DateTimeField or UnsupportedDateTimeField if unsupported
290     */
291    public abstract DateTimeField minuteOfDay();
292
293    // Hour
294    //-----------------------------------------------------------------------
295    /**
296     * Get the hours duration field for this chronology.
297     * 
298     * @return DurationField or UnsupportedDurationField if unsupported
299     */
300    public abstract DurationField hours();
301
302    /**
303     * Get the hour of day (0-23) field for this chronology.
304     * 
305     * @return DateTimeField or UnsupportedDateTimeField if unsupported
306     */
307    public abstract DateTimeField hourOfDay();
308
309    /**
310     * Get the hour of day (offset to 1-24) field for this chronology.
311     * 
312     * @return DateTimeField or UnsupportedDateTimeField if unsupported
313     */
314    public abstract DateTimeField clockhourOfDay();
315
316    // Halfday
317    //-----------------------------------------------------------------------
318    /**
319     * Get the halfdays duration field for this chronology.
320     * 
321     * @return DurationField or UnsupportedDurationField if unsupported
322     */
323    public abstract DurationField halfdays();
324
325    /**
326     * Get the hour of am/pm (0-11) field for this chronology.
327     * 
328     * @return DateTimeField or UnsupportedDateTimeField if unsupported
329     */
330    public abstract DateTimeField hourOfHalfday();
331
332    /**
333     * Get the hour of am/pm (offset to 1-12) field for this chronology.
334     * 
335     * @return DateTimeField or UnsupportedDateTimeField if unsupported
336     */
337    public abstract DateTimeField clockhourOfHalfday();
338
339    /**
340     * Get the AM(0) PM(1) field for this chronology.
341     * 
342     * @return DateTimeField or UnsupportedDateTimeField if unsupported
343     */
344    public abstract DateTimeField halfdayOfDay();
345
346    // Day
347    //-----------------------------------------------------------------------
348    /**
349     * Get the days duration field for this chronology.
350     * 
351     * @return DurationField or UnsupportedDurationField if unsupported
352     */
353    public abstract DurationField days();
354
355    /**
356     * Get the day of week field for this chronology.
357     *
358     * <p>DayOfWeek values are defined in {@link DateTimeConstants}.
359     * They use the ISO definitions, where 1 is Monday and 7 is Sunday.
360     * 
361     * @return DateTimeField or UnsupportedDateTimeField if unsupported
362     */
363    public abstract DateTimeField dayOfWeek();
364
365    /**
366     * Get the day of month field for this chronology.
367     * 
368     * @return DateTimeField or UnsupportedDateTimeField if unsupported
369     */
370    public abstract DateTimeField dayOfMonth();
371
372    /**
373     * Get the day of year field for this chronology.
374     * 
375     * @return DateTimeField or UnsupportedDateTimeField if unsupported
376     */
377    public abstract DateTimeField dayOfYear();
378
379    // Week
380    //-----------------------------------------------------------------------
381    /**
382     * Get the weeks duration field for this chronology.
383     * 
384     * @return DurationField or UnsupportedDurationField if unsupported
385     */
386    public abstract DurationField weeks();
387
388    /**
389     * Get the week of a week based year field for this chronology.
390     * 
391     * @return DateTimeField or UnsupportedDateTimeField if unsupported
392     */
393    public abstract DateTimeField weekOfWeekyear();
394
395    // Weekyear
396    //-----------------------------------------------------------------------
397    /**
398     * Get the weekyears duration field for this chronology.
399     * 
400     * @return DurationField or UnsupportedDurationField if unsupported
401     */
402    public abstract DurationField weekyears();
403
404    /**
405     * Get the year of a week based year field for this chronology.
406     * 
407     * @return DateTimeField or UnsupportedDateTimeField if unsupported
408     */
409    public abstract DateTimeField weekyear();
410
411    /**
412     * Get the year of a week based year in a century field for this chronology.
413     * 
414     * @return DateTimeField or UnsupportedDateTimeField if unsupported
415     */
416    public abstract  DateTimeField weekyearOfCentury();
417
418    // Month
419    //-----------------------------------------------------------------------
420    /**
421     * Get the months duration field for this chronology.
422     * 
423     * @return DurationField or UnsupportedDurationField if unsupported
424     */
425    public abstract DurationField months();
426
427    /**
428     * Get the month of year field for this chronology.
429     * 
430     * @return DateTimeField or UnsupportedDateTimeField if unsupported
431     */
432    public abstract DateTimeField monthOfYear();
433
434    // Year
435    //-----------------------------------------------------------------------
436    /**
437     * Get the years duration field for this chronology.
438     * 
439     * @return DurationField or UnsupportedDurationField if unsupported
440     */
441    public abstract DurationField years();
442
443    /**
444     * Get the year field for this chronology.
445     * 
446     * @return DateTimeField or UnsupportedDateTimeField if unsupported
447     */
448    public abstract DateTimeField year();
449
450    /**
451     * Get the year of era field for this chronology.
452     * 
453     * @return DateTimeField or UnsupportedDateTimeField if unsupported
454     */
455    public abstract DateTimeField yearOfEra();
456
457    /**
458     * Get the year of century field for this chronology.
459     * 
460     * @return DateTimeField or UnsupportedDateTimeField if unsupported
461     */
462    public abstract DateTimeField yearOfCentury();
463
464    // Century
465    //-----------------------------------------------------------------------
466    /**
467     * Get the centuries duration field for this chronology.
468     * 
469     * @return DurationField or UnsupportedDurationField if unsupported
470     */
471    public abstract DurationField centuries();
472
473    /**
474     * Get the century of era field for this chronology.
475     * 
476     * @return DateTimeField or UnsupportedDateTimeField if unsupported
477     */
478    public abstract DateTimeField centuryOfEra();
479
480    // Era
481    //-----------------------------------------------------------------------
482    /**
483     * Get the eras duration field for this chronology.
484     * 
485     * @return DurationField or UnsupportedDurationField if unsupported
486     */
487    public abstract DurationField eras();
488
489    /**
490     * Get the era field for this chronology.
491     * 
492     * @return DateTimeField or UnsupportedDateTimeField if unsupported
493     */
494    public abstract DateTimeField era();
495
496    //-----------------------------------------------------------------------
497    /**
498     * Gets a debugging toString.
499     * 
500     * @return a debugging string
501     */
502    public abstract String toString();
503
504}