org.exolab.castor.types
Class DateTimeBase

java.lang.Object
  org.exolab.castor.types.DateTimeBase

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

Date, DateTime, GDay, GMonth, GMonthDay, GYear, GYearMonth, Time

public abstract class DateTimeBase
extends Object
implements Serializable, Cloneable

The base class for date/time XML Schema types.

The validation of the date/time fields is done in the set methods and follows the ISO8601 Date and Time Format.

Note: the Castor date/time types are mutable, unlike the date/time types of the JDK in Java2. This is needed by the Marshaling framework.

Version:

$Revision: 8516 $

Author:

Arnaud Blandin, Edward Kuns

See Also:

DateTime, Date, Time, Serialized Form

Field Summary

static int	EQUALS Public constant referring to a Date/Time comparison result of "equals".
static int	GREATER_THAN Public constant referring to a Date/Time comparison result of "greater than".
static int	INDETERMINATE Public constant referring to an indeterminate Date/Time comparison.
static int	LESS_THAN Public constant referring to a Date/Time comparison result of "less than".
protected static int	MAX_TIME_ZONE_COMPARISON_OFFSET When comparing a date/time with a time zone to one without, the recommendation says that 14 hours is the time zone offset to use for comparison.
protected static String	WRONGLY_PLACED Convenience String for complaints.

Constructor Summary

DateTimeBase()

Method Summary

void	addDuration(Duration duration) Adds a Duration to this Date/Time type as defined in Adding Duration to dateTimes (W3C XML Schema, part 2 appendix E).
protected void	appendDateString(StringBuffer result)
protected void	appendTimeString(StringBuffer result)
protected void	appendTimeZoneString(StringBuffer result)
DateTimeBase	clone(DateTimeBase dateTime)
int	compareTo(DateTimeBase dateTime) Compares two date/time data types.
protected boolean	equal(DateTimeBase dateTime) Returns true if the present instance of date/time type is equal to the parameter.
boolean	equals(Object object) Overrides the java.lang.Object#equals method.
short	getCentury()
short	getDay()
short	getHour()
short	getMilli()
short	getMinute()
short	getMonth()
short	getSeconds()
abstract short[]	getValues() returns an array of short with all the fields that describe a date/time type.
short	getYear()
short	getZoneHour()
short	getZoneMinute()
boolean	hasCentury()
boolean	hasDay()
int	hashCode() Overrides the java.lang.Object#hashcode method.
boolean	hasHour()
boolean	hasIsNegative()
boolean	hasMilli()
boolean	hasMinute()
boolean	hasMonth()
boolean	hasSeconds()
boolean	hasYear()
boolean	isLeap(int year) Returns true if the given year represents a leap year.
boolean	isNegative()
boolean	isUTC() Returns true if this date/time type is UTC, that is, has a time zone assigned.
boolean	isZoneNegative()
void	normalize() Normalizes a date/time datatype as defined in W3C XML Schema Recommendation document: if a timeZone is present but it is not Z then we convert the date/time datatype to Z using the addition operation defined in Adding Duration to dateTimes (W3C XML Schema, part 2 appendix E).
protected static int	parseDay(String str, DateTimeBase result, char[] chars, int index, String complaint)
protected static int	parseMonth(String str, DateTimeBase result, char[] chars, int index, String complaint)
protected static int	parseTime(String str, DateTimeBase result, char[] chars, int index, String complaint)
protected static int	parseTimeZone(String str, DateTimeBase result, char[] chars, int index, String complaint)
protected static int	parseYear(String str, DateTimeBase result, char[] chars, int index, String complaint)
void	setCentury(short century) Set the century field.
protected void	setDateFormatTimeZone(Calendar calendar) Sets the time zone in the provided Calendar.
protected void	setDateFormatTimeZone(DateFormat df) Sets the time zone in the provided DateFormat.
void	setDay(short day) Sets the Day Field.
void	setHour(short hour) Sets the hour field for this date/time type.
void	setMilliSecond(short millisecond) Sets the millisecond field for this date/time type.
void	setMinute(short minute) set the minute field for this date/time type.
void	setMonth(short month) Sets the Month Field.
void	setNegative() Set the negative field to true.
void	setSecond(short second) Sets the seconds field for this date/time type, not including the fractional seconds.
void	setSecond(short second, short millsecond) Sets the seconds field for this date/time type, including fractional seconds.
void	setUTC() Sets the UTC field.
abstract void	setValues(short[] values) Sets all the fields by reading the values in an array.
void	setYear(short year) Sets the Year field.
void	setZone(short hour, short minute) Sets the time zone fields for this date/time type.
void	setZoneHour(short hour) Sets the time zone hour field for this date/time type.
void	setZoneMinute(short minute) Sets the time zone minute field for this date/time type.
void	setZoneNegative(boolean zoneNegative) Sets the time zone negative field to true.
Calendar	toCalendar() converts this Date/Time into a local java Calendar.
abstract Date	toDate() Returns a java.util.Date that represents the XML Schema Date datatype.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

INDETERMINATE

public static final int INDETERMINATE

Public constant referring to an indeterminate Date/Time comparison.

See Also:

Constant Field Values

LESS_THAN

public static final int LESS_THAN

Public constant referring to a Date/Time comparison result of "less than".

See Also:

Constant Field Values

EQUALS

public static final int EQUALS

Public constant referring to a Date/Time comparison result of "equals".

See Also:

Constant Field Values

GREATER_THAN

public static final int GREATER_THAN

Public constant referring to a Date/Time comparison result of "greater than".

See Also:

Constant Field Values

MAX_TIME_ZONE_COMPARISON_OFFSET

protected static final int MAX_TIME_ZONE_COMPARISON_OFFSET

When comparing a date/time with a time zone to one without, the recommendation says that 14 hours is the time zone offset to use for comparison.

See Also:

Constant Field Values

WRONGLY_PLACED

protected static final String WRONGLY_PLACED

Convenience String for complaints.

See Also:

Constant Field Values

Constructor Detail

DateTimeBase

public DateTimeBase()

Method Detail

toDate

public abstract Date toDate()

Returns a java.util.Date that represents the XML Schema Date datatype.

Returns:

a java.util.Date that represents the XML Schema Date datatype.

setValues

public abstract void setValues(short[] values)

Sets all the fields by reading the values in an array.

Parameters:

values - an array of shorts with the values.

getValues

public abstract short[] getValues()

returns an array of short with all the fields that describe a date/time type.

Returns:

an array of short with all the fields that describe a date/time type.

isLeap

public final boolean isLeap(int year)

Returns true if the given year represents a leap year. A specific year is a leap year if it is either evenly divisible by 400 OR evenly divisible by 4 and not evenly divisible by 100.

Parameters:

year - the year to test where 0 < year <= 9999

Returns:

true if the given year represents a leap year

setNegative

public void setNegative()
                 throws UnsupportedOperationException

Set the negative field to true.

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the "century+year is negative" field is not allowed.

setCentury

public void setCentury(short century)
                throws UnsupportedOperationException

Set the century field. Note: year 0000 is not allowed.

Parameters:

century - the value to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the century field is not allowed

setYear

public void setYear(short year)
             throws UnsupportedOperationException

Sets the Year field. Note: year 0000 is not allowed.

Parameters:

year - the year to set

Throws:

UnsupportedOperationException - in an overridden method in a derived class if that derived class does not support the year element.

setMonth

public void setMonth(short month)
              throws UnsupportedOperationException

Sets the Month Field. Note 1 <= month <= 12.

Parameters:

month - the value to set up

Throws:

UnsupportedOperationException - in an overridden method in a derived class if that derived class does not support the month element.

setDay

public void setDay(short day)
            throws UnsupportedOperationException

Sets the Day Field. Note: This field is validated before the assignment is done.

Parameters:

day - the value to set up

Throws:

UnsupportedOperationException - in an overridden method in a derived class if that derived class does not support the day element.

setHour

public void setHour(short hour)
             throws UnsupportedOperationException

Sets the hour field for this date/time type.

Parameters:

hour - the hour to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the hour field is not allowed

setMinute

public void setMinute(short minute)
               throws UnsupportedOperationException

set the minute field for this date/time type.

Parameters:

minute - the minute to set.

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the minute field is not allowed

setSecond

public void setSecond(short second,
                      short millsecond)
               throws UnsupportedOperationException

Sets the seconds field for this date/time type, including fractional seconds. (In this implementation, fractional seconds are limited to milliseconds and are truncated at millseconds if more precision is provided.)

Parameters:

second - the second to set

millsecond - the millisecond to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the second field is not allowed

setSecond

public void setSecond(short second)
               throws UnsupportedOperationException

Sets the seconds field for this date/time type, not including the fractional seconds. Any fractional seconds previously set is unmodified.

Parameters:

second - the second to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the second field is not allowed

setMilliSecond

public void setMilliSecond(short millisecond)
                    throws UnsupportedOperationException

Sets the millisecond field for this date/time type.

Parameters:

millisecond - the millisecond to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the millisecond field is not allowed

setUTC

public void setUTC()

Sets the UTC field.

setZoneNegative

public void setZoneNegative(boolean zoneNegative)

Sets the time zone negative field to true.

Parameters:

zoneNegative - indicates whether or not the time zone is negative.

Throws:

UnsupportedOperationException - this exception is thrown when changing the time zone fields is not allowed

setZone

public void setZone(short hour,
                    short minute)

Sets the time zone fields for this date/time type. A call to this method means that the date/time type used is UTC.

For a negative time zone, you first assign the absolute value of the time zone using this method and then you call setZoneNegative(boolean).

Parameters:

hour - The time zone hour to set. Must be positive.

minute - The time zone minute to set.

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the time zone fields is not allowed

setZoneHour

public void setZoneHour(short hour)

Sets the time zone hour field for this date/time type. A call to this method means that the date/time type used is UTC.

For a negative time zone, you first assign the absolute value of the time zone using this method and then you call setZoneNegative(boolean).

Parameters:

hour - the time zone hour to set. Must be positive.

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the time zone fields is not allowed

setZoneMinute

public void setZoneMinute(short minute)

Sets the time zone minute field for this date/time type. A call to this method means that the date/time type used is UTC.

Parameters:

minute - the time zone minute to set

Throws:

UnsupportedOperationException - this exception is thrown when changing the value of the time zone fields is not allowed

isNegative

public boolean isNegative()
                   throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getCentury

public short getCentury()
                 throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getYear

public short getYear()
              throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getMonth

public short getMonth()
               throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getDay

public short getDay()
             throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getHour

public short getHour()
              throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getMinute

public short getMinute()
                throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getSeconds

public short getSeconds()
                 throws UnsupportedOperationException

Throws:

UnsupportedOperationException

getMilli

public short getMilli()
               throws UnsupportedOperationException

Throws:

UnsupportedOperationException

isUTC

public boolean isUTC()

Returns true if this date/time type is UTC, that is, has a time zone assigned. A date/time type is UTC if a 'Z' appears at the end of the lexical representation type or if it contains a time zone.

Returns:

true if this type has a time zone assigned, else false.

isZoneNegative

public boolean isZoneNegative()

getZoneHour

public short getZoneHour()

getZoneMinute

public short getZoneMinute()

hasIsNegative

public boolean hasIsNegative()

hasCentury

public boolean hasCentury()

hasYear

public boolean hasYear()

hasMonth

public boolean hasMonth()

hasDay

public boolean hasDay()

hasHour

public boolean hasHour()

hasMinute

public boolean hasMinute()

hasSeconds

public boolean hasSeconds()

hasMilli

public boolean hasMilli()

addDuration

public void addDuration(Duration duration)

Adds a Duration to this Date/Time type as defined in Adding Duration to dateTimes (W3C XML Schema, part 2 appendix E). This version uses the algorithm defined in the document from W3C. A later version may optimize it.

The modified Date/Time instance will keep the same time zone it started with, if any.

Don't use getter methods but use direct field access for dateTime in order to have the behaviour defined in the Recommendation document.

Parameters:

duration - the duration to add

normalize

public void normalize()

Normalizes a date/time datatype as defined in W3C XML Schema Recommendation document: if a timeZone is present but it is not Z then we convert the date/time datatype to Z using the addition operation defined in Adding Duration to dateTimes (W3C XML Schema, part 2 appendix E).

See Also:

addDuration(org.exolab.castor.types.Duration)

compareTo

public int compareTo(DateTimeBase dateTime)

Compares two date/time data types. The algorithm of comparison is defined in W3C XML Schema Recommendation (section 3.2.7.3)

The returned value will be one of:

• INDETERMINATE (-1): this ? dateTime
• LESS_THAN (0): this < dateTime
• EQUALS (1): this == dateTime
• GREATER_THAN (2): this > dateTime

FIXME: This code does not compare time zones properly for date/time types that do not contain a time.

Parameters:

dateTime - the dateTime to compare with the current instance.

Returns:

the status of the comparison.

clone

public DateTimeBase clone(DateTimeBase dateTime)
                   throws CloneNotSupportedException

Throws:

CloneNotSupportedException

hashCode

public int hashCode()

Overrides the java.lang.Object#hashcode method.

Overrides:

hashCode in class Object

equals

public boolean equals(Object object)

Overrides the java.lang.Object#equals method.

Overrides:

equals in class Object

See Also:

equals(Object)

equal

protected boolean equal(DateTimeBase dateTime)

Returns true if the present instance of date/time type is equal to the parameter.

The equals relation is as defined in the W3C XML Schema Recommendation, part2.

Parameters:

dateTime - the date/time type to compare with the present instance

Returns:

true if the present instance is equal to the parameter false if not

toCalendar

public Calendar toCalendar()

converts this Date/Time into a local java Calendar.

Returns:

a local calendar representing this Date or Time

parseYear

protected static int parseYear(String str,
                               DateTimeBase result,
                               char[] chars,
                               int index,
                               String complaint)
                        throws ParseException

Throws:

ParseException

parseMonth

protected static int parseMonth(String str,
                                DateTimeBase result,
                                char[] chars,
                                int index,
                                String complaint)
                         throws ParseException

Throws:

ParseException

parseDay

protected static int parseDay(String str,
                              DateTimeBase result,
                              char[] chars,
                              int index,
                              String complaint)
                       throws ParseException

Throws:

ParseException

parseTime

protected static int parseTime(String str,
                               DateTimeBase result,
                               char[] chars,
                               int index,
                               String complaint)
                        throws ParseException

Throws:

ParseException

parseTimeZone

protected static int parseTimeZone(String str,
                                   DateTimeBase result,
                                   char[] chars,
                                   int index,
                                   String complaint)
                            throws ParseException

Throws:

ParseException

setDateFormatTimeZone

protected void setDateFormatTimeZone(DateFormat df)

Sets the time zone in the provided DateFormat.

Parameters:

df -

setDateFormatTimeZone

protected void setDateFormatTimeZone(Calendar calendar)

Sets the time zone in the provided Calendar.

Parameters:

calendar -

appendDateString

protected void appendDateString(StringBuffer result)

appendTimeString

protected void appendTimeString(StringBuffer result)

appendTimeZoneString

protected void appendTimeZoneString(StringBuffer result)