Class DateTimeBase

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    Direct Known Subclasses:
    Date, DateTime, GDay, GMonth, GMonthDay, GYear, GYearMonth, Time

    public abstract class DateTimeBase
    extends java.lang.Object
    implements java.io.Serializable, java.lang.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

      Fields 
      Modifier and Type Field Description
      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 java.lang.String WRONGLY_PLACED
      Convenience String for complaints.
    • Constructor Summary

      Constructors 
      Constructor Description
      DateTimeBase()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      protected void appendDateString​(java.lang.StringBuffer result)  
      protected void appendTimeString​(java.lang.StringBuffer result)  
      protected void appendTimeZoneString​(java.lang.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​(java.lang.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​(java.lang.String str, DateTimeBase result, char[] chars, int index, java.lang.String complaint)  
      protected static int parseMonth​(java.lang.String str, DateTimeBase result, char[] chars, int index, java.lang.String complaint)  
      protected static int parseTime​(java.lang.String str, DateTimeBase result, char[] chars, int index, java.lang.String complaint)  
      protected static int parseTimeZone​(java.lang.String str, DateTimeBase result, char[] chars, int index, java.lang.String complaint)  
      protected static int parseYear​(java.lang.String str, DateTimeBase result, char[] chars, int index, java.lang.String complaint)  
      void setCentury​(short century)
      Set the century field.
      protected void setDateFormatTimeZone​(java.text.DateFormat df)
      Sets the time zone in the provided DateFormat.
      protected void setDateFormatTimeZone​(java.util.Calendar calendar)
      Sets the time zone in the provided Calendar.
      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.
      java.util.Calendar toCalendar()
      converts this Date/Time into a local java Calendar.
      abstract java.util.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 java.lang.String WRONGLY_PLACED
        Convenience String for complaints.
        See Also:
        Constant Field Values
    • Constructor Detail

      • DateTimeBase

        public DateTimeBase()
    • Method Detail

      • toDate

        public abstract java.util.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 java.lang.UnsupportedOperationException
        Set the negative field to true.
        Throws:
        java.lang.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 java.lang.UnsupportedOperationException
        Set the century field. Note: year 0000 is not allowed.
        Parameters:
        century - the value to set
        Throws:
        java.lang.UnsupportedOperationException - this exception is thrown when changing the value of the century field is not allowed
      • setYear

        public void setYear​(short year)
                     throws java.lang.UnsupportedOperationException
        Sets the Year field. Note: year 0000 is not allowed.
        Parameters:
        year - the year to set
        Throws:
        java.lang.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 java.lang.UnsupportedOperationException
        Sets the Month Field. Note 1 <= month <= 12.
        Parameters:
        month - the value to set up
        Throws:
        java.lang.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 java.lang.UnsupportedOperationException
        Sets the Day Field. Note: This field is validated before the assignment is done.
        Parameters:
        day - the value to set up
        Throws:
        java.lang.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 java.lang.UnsupportedOperationException
        Sets the hour field for this date/time type.
        Parameters:
        hour - the hour to set
        Throws:
        java.lang.UnsupportedOperationException - this exception is thrown when changing the value of the hour field is not allowed
      • setMinute

        public void setMinute​(short minute)
                       throws java.lang.UnsupportedOperationException
        set the minute field for this date/time type.
        Parameters:
        minute - the minute to set.
        Throws:
        java.lang.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 java.lang.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:
        java.lang.UnsupportedOperationException - this exception is thrown when changing the value of the second field is not allowed
      • setSecond

        public void setSecond​(short second)
                       throws java.lang.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:
        java.lang.UnsupportedOperationException - this exception is thrown when changing the value of the second field is not allowed
      • setMilliSecond

        public void setMilliSecond​(short millisecond)
                            throws java.lang.UnsupportedOperationException
        Sets the millisecond field for this date/time type.
        Parameters:
        millisecond - the millisecond to set
        Throws:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.UnsupportedOperationException - this exception is thrown when changing the value of the time zone fields is not allowed
      • isNegative

        public boolean isNegative()
                           throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getCentury

        public short getCentury()
                         throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getYear

        public short getYear()
                      throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getMonth

        public short getMonth()
                       throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getDay

        public short getDay()
                     throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getHour

        public short getHour()
                      throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getMinute

        public short getMinute()
                        throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getSeconds

        public short getSeconds()
                         throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.UnsupportedOperationException
      • getMilli

        public short getMilli()
                       throws java.lang.UnsupportedOperationException
        Throws:
        java.lang.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
      • 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 java.lang.CloneNotSupportedException
        Throws:
        java.lang.CloneNotSupportedException
      • hashCode

        public int hashCode()
        Overrides the java.lang.Object#hashcode method.
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object object)
        Overrides the java.lang.Object#equals method.
        Overrides:
        equals in class java.lang.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 java.util.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​(java.lang.String str,
                                       DateTimeBase result,
                                       char[] chars,
                                       int index,
                                       java.lang.String complaint)
                                throws java.text.ParseException
        Throws:
        java.text.ParseException
      • parseMonth

        protected static int parseMonth​(java.lang.String str,
                                        DateTimeBase result,
                                        char[] chars,
                                        int index,
                                        java.lang.String complaint)
                                 throws java.text.ParseException
        Throws:
        java.text.ParseException
      • parseDay

        protected static int parseDay​(java.lang.String str,
                                      DateTimeBase result,
                                      char[] chars,
                                      int index,
                                      java.lang.String complaint)
                               throws java.text.ParseException
        Throws:
        java.text.ParseException
      • parseTime

        protected static int parseTime​(java.lang.String str,
                                       DateTimeBase result,
                                       char[] chars,
                                       int index,
                                       java.lang.String complaint)
                                throws java.text.ParseException
        Throws:
        java.text.ParseException
      • parseTimeZone

        protected static int parseTimeZone​(java.lang.String str,
                                           DateTimeBase result,
                                           char[] chars,
                                           int index,
                                           java.lang.String complaint)
                                    throws java.text.ParseException
        Throws:
        java.text.ParseException
      • setDateFormatTimeZone

        protected void setDateFormatTimeZone​(java.text.DateFormat df)
        Sets the time zone in the provided DateFormat.
        Parameters:
        df -
      • setDateFormatTimeZone

        protected void setDateFormatTimeZone​(java.util.Calendar calendar)
        Sets the time zone in the provided Calendar.
        Parameters:
        calendar -
      • appendDateString

        protected void appendDateString​(java.lang.StringBuffer result)
      • appendTimeString

        protected void appendTimeString​(java.lang.StringBuffer result)
      • appendTimeZoneString

        protected void appendTimeZoneString​(java.lang.StringBuffer result)