Package org.joda.time.format

Class DateTimeParserBucket

  • public class DateTimeParserBucket
extends java.lang.Object
    DateTimeParserBucket is an advanced class, intended mainly for parser implementations. It can also be used during normal parsing operations to capture more information about the parse.

    This class allows fields to be saved in any order, but be physically set in a consistent order. This is useful for parsing against formats that allow field values to contradict each other.

    Field values are applied in an order where the "larger" fields are set first, making their value less likely to stick. A field is larger than another when it's range duration is longer. If both ranges are the same, then the larger field has the longer duration. If it cannot be determined which field is larger, then the fields are set in the order they were saved.

    For example, these fields were saved in this order: dayOfWeek, monthOfYear, dayOfMonth, dayOfYear. When computeMillis is called, the fields are set in this order: monthOfYear, dayOfYear, dayOfMonth, dayOfWeek.

    DateTimeParserBucket is mutable and not thread-safe.

    Since:
    1.0

    • Constructor Summary

      Constructors 
      Constructor Description
      DateTimeParserBucket​(long instantLocal, Chronology chrono, java.util.Locale locale)
      Deprecated.
      Use longer constructor
      DateTimeParserBucket​(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear)
      Deprecated.
      Use longer constructor
      DateTimeParserBucket​(long instantLocal, Chronology chrono, java.util.Locale locale, java.lang.Integer pivotYear, int defaultYear)
      Constructs a bucket, with the option of specifying the pivot year for two-digit year parsing.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      long computeMillis()
      Computes the parsed datetime by setting the saved fields.
      long computeMillis​(boolean resetFields)
      Computes the parsed datetime by setting the saved fields.
      long computeMillis​(boolean resetFields, java.lang.CharSequence text)
      Computes the parsed datetime by setting the saved fields.
      long computeMillis​(boolean resetFields, java.lang.String text)
      Computes the parsed datetime by setting the saved fields.
      Chronology getChronology()
      Gets the chronology of the bucket, which will be a local (UTC) chronology.
      java.util.Locale getLocale()
      Returns the locale to be used during parsing.
      int getOffset()
      Deprecated.
      use Integer version
      java.lang.Integer getOffsetInteger()
      Returns the time zone offset in milliseconds used by computeMillis.
      java.lang.Integer getPivotYear()
      Returns the default year used when information is incomplete.
      DateTimeZone getZone()
      Returns the time zone used by computeMillis.
      long parseMillis​(DateTimeParser parser, java.lang.CharSequence text)
      Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.
      void reset()
      Resets the state back to that when the object was constructed.
      boolean restoreState​(java.lang.Object savedState)
      Restores the state of this bucket from a previously saved state.
      void saveField​(DateTimeField field, int value)
      Saves a datetime field value.
      void saveField​(DateTimeFieldType fieldType, int value)
      Saves a datetime field value.
      void saveField​(DateTimeFieldType fieldType, java.lang.String text, java.util.Locale locale)
      Saves a datetime field text value.
      java.lang.Object saveState()
      Saves the state of this bucket, returning it in an opaque object.
      void setOffset​(int offset)
      Deprecated.
      use Integer version
      void setOffset​(java.lang.Integer offset)
      Set a time zone offset to be used when computeMillis is called.
      void setPivotYear​(java.lang.Integer pivotYear)
      Deprecated.
      this method should never have been public
      void setZone​(DateTimeZone zone)
      Set a time zone to be used when computeMillis is called.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • DateTimeParserBucket

        @Deprecated
public DateTimeParserBucket​(long instantLocal,
                            Chronology chrono,
                            java.util.Locale locale)
        Deprecated.
        Use longer constructor
        Constructs a bucket.
        Parameters:
        instantLocal - the initial millis from 1970-01-01T00:00:00, local time
        chrono - the chronology to use
        locale - the locale to use

      • DateTimeParserBucket

        @Deprecated
public DateTimeParserBucket​(long instantLocal,
                            Chronology chrono,
                            java.util.Locale locale,
                            java.lang.Integer pivotYear)
        Deprecated.
        Use longer constructor
        Constructs a bucket, with the option of specifying the pivot year for two-digit year parsing.
        Parameters:
        instantLocal - the initial millis from 1970-01-01T00:00:00, local time
        chrono - the chronology to use
        locale - the locale to use
        pivotYear - the pivot year to use when parsing two-digit years
        Since:
        1.1

      • DateTimeParserBucket

        public DateTimeParserBucket​(long instantLocal,
                            Chronology chrono,
                            java.util.Locale locale,
                            java.lang.Integer pivotYear,
                            int defaultYear)
        Constructs a bucket, with the option of specifying the pivot year for two-digit year parsing.
        Parameters:
        instantLocal - the initial millis from 1970-01-01T00:00:00, local time
        chrono - the chronology to use
        locale - the locale to use
        pivotYear - the pivot year to use when parsing two-digit years
        defaultYear - the default year to use when parsing month-day
        Since:
        2.0

    • Method Detail

      • reset

        public void reset()
        Resets the state back to that when the object was constructed.

        This resets the state of the bucket, allowing a single bucket to be re-used for many parses. The bucket must not be shared between threads.

        Since:
        2.4

      • parseMillis

        public long parseMillis​(DateTimeParser parser,
                        java.lang.CharSequence text)
        Parses a datetime from the given text, returning the number of milliseconds since the epoch, 1970-01-01T00:00:00Z.

        This parses the text using the parser into this bucket. The bucket is reset before parsing begins, allowing the bucket to be re-used. The bucket must not be shared between threads.

        Parameters:
        parser - the parser to use, see DateTimeFormatter.getParser(), not null
        text - text to parse, not null
        Returns:
        parsed value expressed in milliseconds since the epoch
        Throws:
        java.lang.UnsupportedOperationException - if parsing is not supported
        java.lang.IllegalArgumentException - if the text to parse is invalid
        Since:
        2.4

      • getChronology

        public Chronology getChronology()
        Gets the chronology of the bucket, which will be a local (UTC) chronology.

      • getLocale

        public java.util.Locale getLocale()
        Returns the locale to be used during parsing.
        Returns:
        the locale to use

      • getZone

        public DateTimeZone getZone()
        Returns the time zone used by computeMillis.

      • setZone

        public void setZone​(DateTimeZone zone)
        Set a time zone to be used when computeMillis is called.

      • getOffset

        @Deprecated
public int getOffset()
        Deprecated.
        use Integer version
        Returns the time zone offset in milliseconds used by computeMillis.

      • getOffsetInteger

        public java.lang.Integer getOffsetInteger()
        Returns the time zone offset in milliseconds used by computeMillis.

      • setOffset

        @Deprecated
public void setOffset​(int offset)
        Deprecated.
        use Integer version
        Set a time zone offset to be used when computeMillis is called.

      • setOffset

        public void setOffset​(java.lang.Integer offset)
        Set a time zone offset to be used when computeMillis is called.

      • getPivotYear

        public java.lang.Integer getPivotYear()
        Returns the default year used when information is incomplete.

        This is used for two-digit years and when the largest parsed field is months or days.

        A null value for two-digit years means to use the value from DateTimeFormatterBuilder. A null value for month/day only parsing will cause the default of 2000 to be used.

        Returns:
        Integer value of the pivot year, null if not set
        Since:
        1.1

      • setPivotYear

        @Deprecated
public void setPivotYear​(java.lang.Integer pivotYear)
        Deprecated.
        this method should never have been public
        Sets the pivot year to use when parsing two digit years.

        If the value is set to null, this will indicate that default behaviour should be used.

        Parameters:
        pivotYear - the pivot year to use
        Since:
        1.1

      • saveField

        public void saveField​(DateTimeField field,
                      int value)
        Saves a datetime field value.
        Parameters:
        field - the field, whose chronology must match that of this bucket
        value - the value

      • saveField

        public void saveField​(DateTimeFieldType fieldType,
                      int value)
        Saves a datetime field value.
        Parameters:
        fieldType - the field type
        value - the value

      • saveField

        public void saveField​(DateTimeFieldType fieldType,
                      java.lang.String text,
                      java.util.Locale locale)
        Saves a datetime field text value.
        Parameters:
        fieldType - the field type
        text - the text value
        locale - the locale to use

      • saveState

        public java.lang.Object saveState()
        Saves the state of this bucket, returning it in an opaque object. Call restoreState to undo any changes that were made since the state was saved. Calls to saveState may be nested.
        Returns:
        opaque saved state, which may be passed to restoreState

      • restoreState

        public boolean restoreState​(java.lang.Object savedState)
        Restores the state of this bucket from a previously saved state. The state object passed into this method is not consumed, and it can be used later to restore to that state again.
        Parameters:
        savedState - opaque saved state, returned from saveState
        Returns:
        true state object is valid and state restored

      • computeMillis

        public long computeMillis()
        Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.
        Returns:
        milliseconds since 1970-01-01T00:00:00Z
        Throws:
        java.lang.IllegalArgumentException - if any field is out of range

      • computeMillis

        public long computeMillis​(boolean resetFields)
        Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.
        Parameters:
        resetFields - false by default, but when true, unsaved field values are cleared
        Returns:
        milliseconds since 1970-01-01T00:00:00Z
        Throws:
        java.lang.IllegalArgumentException - if any field is out of range

      • computeMillis

        public long computeMillis​(boolean resetFields,
                          java.lang.String text)
        Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.
        Parameters:
        resetFields - false by default, but when true, unsaved field values are cleared
        text - optional text being parsed, to be included in any error message
        Returns:
        milliseconds since 1970-01-01T00:00:00Z
        Throws:
        java.lang.IllegalArgumentException - if any field is out of range
        Since:
        1.3

      • computeMillis

        public long computeMillis​(boolean resetFields,
                          java.lang.CharSequence text)
        Computes the parsed datetime by setting the saved fields. This method is idempotent, but it is not thread-safe.
        Parameters:
        resetFields - false by default, but when true, unsaved field values are cleared
        text - optional text being parsed, to be included in any error message
        Returns:
        milliseconds since 1970-01-01T00:00:00Z
        Throws:
        java.lang.IllegalArgumentException - if any field is out of range
        Since:
        2.4