This class is an abstract base class for Calendars, which can be
used to convert between
Date objects and a set of
integer fields which represent
YEAR,
MONTH,
DAY, etc. The
Date
object represents a time in milliseconds since the Epoch.
This class is locale sensitive. To get the Object matching the
current locale you can use
getInstance. You can even provide
a locale or a timezone.
getInstance returns currently
a
GregorianCalendar for the current date.
If you want to convert a date from the Year, Month, Day, DayOfWeek,
etc. Representation to a
Date-Object, you can create
a new Calendar with
getInstance(),
clear() all fields,
set(int,int) the
fields you need and convert it with
getTime().
If you want to convert a
Date-object to the Calendar
representation, create a new Calendar, assign the
Date-Object with
setTime(), and read the
fields with
get(int).
When computing the date from time fields, it may happen, that there
are either two few fields set, or some fields are inconsistent. This
cases will handled in a calendar specific way. Missing fields are
replaced by the fields of the epoch: 1970 January 1 00:00.
To understand, how the day of year is computed out of the fields
look at the following table. It is traversed from top to bottom,
and for the first line all fields are set, that line is used to
compute the day.
month + day_of_month
month + week_of_month + day_of_week
month + day_of_week_of_month + day_of_week
day_of_year
day_of_week + week_of_year
The hour_of_day-field takes precedence over the ampm and
hour_of_ampm fields.
Note: This can differ for non-Gregorian calendar.
To convert a calendar to a human readable form and vice versa, use
the
java.text.DateFormat class.
Other useful things you can do with an calendar, is
rolling fields (that means increase/decrease a
specific field by one, propagating overflows), or
adding/substracting a fixed amount to a field.
add
public abstract void add(int field,
int amount) Adds the specified amount of time to the given time field. The
amount may be negative to subtract the time. If the field overflows
it does what you expect: Jan, 25 + 10 Days is Feb, 4.
field - the time field. One of the time field constants.amount - the amount of time.
after
public boolean after(Object o)
Compares the given calendar with this.
o - the object to that we should compare.
- true, if the given object is a calendar, and this calendar
represents a bigger time than the calendar o.
- JDK1.2 you don't need to override this method
before
public boolean before(Object o)
Compares the given calendar with this.
o - the object to that we should compare.
- true, if the given object is a calendar, and this calendar
represents a smaller time than the calendar o.
- JDK1.2 you don't need to override this method
clear
public final void clear(int field)
Clears the values of the specified time field.
field - the time field. One of the time field constants.
compareTo
public int compareTo(Calendar cal)
Compares the time of two calendar instances.
cal - the calendar to which the time should be compared.
- 0 if the two calendars are set to the same time,
less than 0 if the time of this calendar is before that of
cal, or more than 0 if the time of this calendar is after
that of cal.
equals
public boolean equals(Object o)
Compares the given calendar with this.
- equals in interface Object
o - the object to that we should compare.
- true, if the given object is a calendar, that represents
the same time (but doesn't necessary have the same fields).
get
public int get(int field)
Gets the value of the specified field. They are recomputed
if they are invalid.
field - the time field. One of the time field constants.
- the value of the specified field
getActualMaximum
public int getActualMaximum(int field)
Gets the actual maximum value that is allowed for the specified field.
This value is dependent on the values of the other fields.
field - the time field. One of the time field constants.
- the actual maximum value.
getActualMinimum
public int getActualMinimum(int field)
Gets the actual minimum value that is allowed for the specified field.
This value is dependent on the values of the other fields.
field - the time field. One of the time field constants.
- the actual minimum value.
getDisplayName
public String getDisplayName(int field,
int style,
Locale locale) Returns a localised textual representation of the current value
of the given field using the specified style. If there is no
applicable textual representation (e.g. the field has a numeric
value), then
null is returned. If one does exist,
then the value is obtained from
get(int) and converted
appropriately. For example, if the
MONTH field is
requested, then
get(MONTH) is called. This is then
converted to a textual representation based on its value and
the style requested; if the
LONG style is requested
and the returned value is
11 from a
GregorianCalendar implementation, then
"December"
is returned. By default, a textual representation is available
for all fields which have an applicable value obtainable from
DateFormatSymbols.
field - the calendar field whose textual representation should
be obtained.style - the style to use; either LONG or SHORT.locale - the locale to use for translation.
- the textual representation of the given field in the specified
style, or
null if none is applicable.
getDisplayNames
public Map getDisplayNames(int field,
int style,
Locale locale)
Returns a map linking all specified textual representations
of the given field to their numerical values. The textual
representations included are determined by the specified
style and locale. For example, if the style
LONG
is specified and the German locale, then the map will
contain "Montag" to
MONDAY, "Dienstag" to
TUESDAY, "Mittwoch" to
WEDNESDAY and
so on. The default implementation uses the values returned
by
DateFormatSymbols so, for example, the style
ALL_STYLES and the field
MONTH will return
a map filled with the values returned from
DateFormatSymbols.getMonths() and
DateFormatSymbols.getShortMonths(). If there are
no textual representations for a given field (usually because
it is purely numeric, such as the year in the
GregorianCalendar),
null is returned.
field - the calendar field whose textual representation should
be obtained.style - the style to use; either LONG, SHORT
or ALL_STYLES.locale - the locale to use for translation.
- a map of the textual representations of the given field in the
specified style to their numeric values, or
null
if none is applicable.
internalGet
protected final int internalGet(int field)
Gets the value of the specified field. This method doesn't
recompute the fields, if they are invalid.
field - the time field. One of the time field constants.
- the value of the specified field, undefined if
areFieldsSet or isSet[field] is false.
isLenient
public boolean isLenient()
Tells if the date/time interpretation is lenient.
- true, if the date should be interpreted linient,
false if it should be interpreted strict.
roll
public abstract void roll(int field,
boolean up) Rolls the specified time field up or down. This means add one
to the specified field, but don't change the other fields. If
the maximum for this field is reached, start over with the
minimum value.
Note: There may be situation, where the other
fields must be changed, e.g rolling the month on May, 31.
The date June, 31 is automatically converted to July, 1.
field - the time field. One of the time field constants.up - the direction, true for up, false for down.
roll
public void roll(int field,
int amount) Rolls up or down the specified time field by the given amount.
A negative amount rolls down. The default implementation is
call roll(int, boolean) for the specified amount.
Subclasses should override this method to do more intuitiv things.
field - the time field. One of the time field constants.amount - the amount to roll by, positive for rolling up,
negative for rolling down.
set
public void set(int field,
int value) Sets the time field with the given value. This does invalidate
the time in milliseconds.
field - the time field. One of the time field constantsvalue - the value to be set.
set
public final void set(int year,
int month,
int date) Sets the fields for year, month, and date
year - the year.month - the month, one of the constants JANUARY..UNDICEMBER.date - the day of the month
set
public final void set(int year,
int month,
int date,
int hour,
int minute) Sets the fields for year, month, date, hour, and minute
year - the year.month - the month, one of the constants JANUARY..UNDICEMBER.date - the day of the monthhour - the hour of day.minute - the minute.
set
public final void set(int year,
int month,
int date,
int hour,
int minute,
int second) Sets the fields for year, month, date, hour, and minute
year - the year.month - the month, one of the constants JANUARY..UNDICEMBER.date - the day of the monthhour - the hour of day.minute - the minute.second - the second.
setLenient
public void setLenient(boolean lenient)
Specifies if the date/time interpretation should be lenient.
If the flag is set, a date such as "February 30, 1996" will be
treated as the 29th day after the February 1. If this flag
is false, such dates will cause an exception.
lenient - true, if the date should be interpreted linient,
false if it should be interpreted strict.
setMinimalDaysInFirstWeek
public void setMinimalDaysInFirstWeek(int value)
Sets how many days are required in the first week of the year.
If the first day of the year should be the first week you should
set this value to 1. If the first week must be a full week, set
it to 7.
value - the minimal days required in the first week.
Calendar.java --
Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2005, 2006,
Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.