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:
  • Field Details

    • INDETERMINATE

      public static final int INDETERMINATE
      Public constant referring to an indeterminate Date/Time comparison.
      See Also:
    • LESS_THAN

      public static final int LESS_THAN
      Public constant referring to a Date/Time comparison result of "less than".
      See Also:
    • EQUALS

      public static final int EQUALS
      Public constant referring to a Date/Time comparison result of "equals".
      See Also:
    • GREATER_THAN

      public static final int GREATER_THAN
      Public constant referring to a Date/Time comparison result of "greater than".
      See Also:
    • 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:
    • WRONGLY_PLACED

      protected static final String WRONGLY_PLACED
      Convenience String for complaints.
      See Also:
  • Constructor Details

    • DateTimeBase

      public DateTimeBase()
  • Method Details

    • 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:
    • 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:
    • 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)