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 /**
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 */
063 public 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 }