XmlCalendar Class
- public class XmlCalendar
extends GregorianCalendar
An XML Schema compatible subclass of GregorianCalendar
.
XmlCalendar modifies several key details in the behavior of
GregorianCalendar to make it more useful when dealing with XML dates.
It is easy to convert between XmlCalendar and GDate
, or to
parse or emit an XmlCalendar using a standard XML Schema
lexical representation.
-
To match XML Schema dates, this XmlCalendar is a fully proleptic
Gregorian calendar by default, which means that Gregorian calendar
rules are applied backwards in time as if they had always been in
effect, actual historical circumstances concerning the observance
of the 1582 decree of Pope Gregory XIII notwithstanding.
-
In order to better support partially-specified dates for XML Schema,
this implementation provides a stable get(field) method
that does not modify the instance if you are acessing a field right
after it was explicitly set: a set followed by a get will always
return the same thing and will not fill in any other fields. However,
if you get a field that was not explicitly set, then all the fields
are still automatically filled and normalized for you, just like a
regular GregorianCalendar. If you wish to force the completion and
defaulting of all the fields (without hunting to get one that happens
to be unset), you can always do so by calling getTime().
-
When a year is unspecified and needs to be filled in automatically
(for example when using a .get or .getTime method as discussed above),
the year is defaulted to year 0 (also known as 1 BC). This is different
from
GregorianCalendar
, which chooses 1970. The reason 0 is preferable
is that it is a leap year and so it permits the date --2-29 to be specified
stably. A different default year can be chosen via the static method
XmlCalendar.setDefaultYear()
, or by setting the
system property "user.defaultyear". If you do change this value, you should
pick another leap year such as 2000 and avoid non-leap years such as 1900.
-
When constructing an XmlCalendar from an XML Schema
formatted date or time string or GDate object, the timezone
for the calendar is taken from the string if it is present, or
taken to be
TimeZone.getDefault()
if not.
For example, the XML timezone "Z" is translated to "GMT";
the XML timezone "+05:00" is translated to "GMT+05:00".
-
Finally, this implementation provides a String constructor and a
toString() method that comply with the XML Schema conventions
for formatting a date. If only a subset of fields have been
explicitly set, toString() produces a string with the proper subset
of information.
-
Hierarchy
-
Object
Calendar
GregorianCalendar
XmlCalendar
-
All Implemented Interfaces
-
Cloneable
, Serializable
Fields from java.util.Calendar |
AM, AM_PM, APRIL, areFieldsSet, AUGUST, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DST_OFFSET, ERA, FEBRUARY, FIELD_COUNT, fields, FRIDAY, HOUR, HOUR_OF_DAY, isSet, isTimeSet, JANUARY, JULY, JUNE, MARCH, MAY, MILLISECOND, MINUTE, MONDAY, MONTH, NOVEMBER, OCTOBER, PM, SATURDAY, SECOND, SEPTEMBER, SUNDAY, THURSDAY, time, TUESDAY, UNDECIMBER, WEDNESDAY, WEEK_OF_MONTH, WEEK_OF_YEAR, YEAR, ZONE_OFFSET |
-
XmlCalendar()
- Constructs an empty instance with no fields set.
|
-
XmlCalendar(
GDateSpecification date)
- Constructs an XmlCalendar from a GDate.
|
-
XmlCalendar(int year, int month, int day, int hour, int minute, int second,
BigDecimal fraction, int tzSign, int tzHour, int tzMinute)
- Constructs an XmlCalendar with the specified year, month, day,
hours, minutes, seconds, and optional fractional seconds, in
the specified timezone.
|
-
XmlCalendar(int year, int month, int day, int hour, int minute, int second,
BigDecimal fraction)
- Constructs an XmlCalendar with the specified year, month, day,
hours, minutes, seconds, and optional fractional seconds, in
the default timezone.
|
-
XmlCalendar(
String xmlSchemaDateString)
- Constructs an XmlCalendar for a standard XML
schema formatted date string.
|
-
XmlCalendar(
Date date)
- Constructs an XmlCalendar from a Date.
|
protected void |
-
computeTime ()
- Overrides GregorianCalendar.computeTime to apply a different
default year.
|
public int |
-
get (int field)
- Gets the value for a given time field.
|
public static int |
-
getDefaultYear ()
- Returns the default year that is used when no year is specified.
|
public static void |
-
setDefaultYear (int year)
- Sets the default year to be used when no year is specified.
|
public String |
-
toString ()
- Prints the XmlCalendar using a standard XML Schema
format, as described in XmlCalendar(String s).
|
Methods from java.util.GregorianCalendar |
add, computeFields, equals, getActualMaximum, getActualMinimum, getGreatestMinimum, getGregorianChange, getLeastMaximum, getMaximum, getMinimum, hashCode, isLeapYear, roll, roll, setGregorianChange |
Methods from java.util.Calendar |
add, after, before, clear, clear, clone, complete, computeFields, computeTime, equals, getActualMaximum, getActualMinimum, getAvailableLocales, getFirstDayOfWeek, getGreatestMinimum, getInstance, getInstance, getInstance, getInstance, getLeastMaximum, getMaximum, getMinimalDaysInFirstWeek, getMinimum, getTime, getTimeInMillis, getTimeZone, hashCode, internalGet, isLenient, isSet, roll, roll, set, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setTime, setTimeInMillis, setTimeZone, |
Methods from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
XmlCalendar
public XmlCalendar()
- Constructs an empty instance with no fields set.
XmlCalendar
public XmlCalendar(GDateSpecification
date)
- Constructs an XmlCalendar from a GDate.
If the instance is not completed, you can round-trip to an
equivalent GDate by writing "new GDate(new XmlCalendar(gdate))".
However, if you access any of the unset fields of the calendar, all
the fields will be automatically filled in, so partial dates
without timezones or other fields will not round-trip after access.
XmlCalendar
public XmlCalendar(int year,
int month,
int day,
int hour,
int minute,
int second,
BigDecimal
fraction,
int tzSign,
int tzHour,
int tzMinute)
- Constructs an XmlCalendar with the specified year, month, day,
hours, minutes, seconds, and optional fractional seconds, in
the specified timezone.
XmlCalendar
public XmlCalendar(int year,
int month,
int day,
int hour,
int minute,
int second,
BigDecimal
fraction)
- Constructs an XmlCalendar with the specified year, month, day,
hours, minutes, seconds, and optional fractional seconds, in
the default timezone.
XmlCalendar
public XmlCalendar(String
xmlSchemaDateString)
- Constructs an XmlCalendar for a standard XML
schema formatted date string.
The parser accepts any of the following formats:
YYYY-MM-DDThh:mm:ss - dateTime
YYYY-MM-DD - date
hh:mm:ss - time
YYYY - gYear
--MM - gMonth
---DD - gDay
The parser actually accepts all 16 combinations of subsets of
fields (Y, M, D, T) using the same scheme, even for combinations
that are not defined as types in the schema spec, such as
year, day, and time:
YYYY--DDThh:mm:ss - [everything but month specified]
In the string, each field must be padded to its full width, for
example, January must be --01, not just --1.
In particular, a year must be padded to at least four digits, so
"98" is not a valid year, although "1998" and "0098" are both valid
years, unambiguously 19 centuries separated from each other. A year
may also be preceded by a minus symbol: 0000 is 1 BC and -0001 is
2 BC.
Finally a timezone is always allowed (yet optional) at the end.
Timezones must be either "Z" (UTC, which we translate to GMT),
or simple offsets from UTC in the range "-14:00" to "+14:00",
for example: "14:30:00-05:00" specifies 2:30 PM in the
afternoon at UTC-05:00, which is the same as EST.
If a timezone is not specified, the default TimeZone is used.
XmlCalendar
public XmlCalendar(Date
date)
- Constructs an XmlCalendar from a Date.
The default TimeZone is used for computing the various fields.
computeTime() Method
protected void computeTime()
Overrides GregorianCalendar.computeTime to apply a different
default year. (It must be a leap year.)
-
Overrides
-
GregorianCalendar.computeTime()
get(int) Method
public int get(int field)
Gets the value for a given time field.
Unlike the GregorianCalendar implementation, the get() does not
force a complete of all fields. If you wish to force a completion
of all the fields, call getTime() first.
-
Overrides
-
Calendar.get(int)
getDefaultYear() Method
public static int getDefaultYear()
Returns the default year that is used when no year is specified.
setDefaultYear(int) Method
public static void setDefaultYear(int year)
Sets the default year to be used when no year is specified.
toString() Method
public String
toString()
Prints the XmlCalendar using a standard XML Schema
format, as described in XmlCalendar(String s).
-
Overrides
-
Calendar.toString()