Class BasePeriod

  • All Implemented Interfaces:
    java.io.Serializable, ReadablePeriod
    Direct Known Subclasses:
    MutablePeriod, Period

    public abstract class BasePeriod
    extends AbstractPeriod
    implements ReadablePeriod, java.io.Serializable
    BasePeriod is an abstract implementation of ReadablePeriod that stores data in a PeriodType and an int[].

    This class should generally not be used directly by API users. The ReadablePeriod interface should be used when different kinds of period objects are to be referenced.

    BasePeriod subclasses may be mutable and not thread-safe.

    Since:
    1.0
    See Also:
    Serialized Form
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serialization version
        See Also:
        Constant Field Values
      • DUMMY_PERIOD

        private static final ReadablePeriod DUMMY_PERIOD
        Serialization version
      • iType

        private final PeriodType iType
        The type of period
      • iValues

        private final int[] iValues
        The values
    • Constructor Detail

      • BasePeriod

        protected BasePeriod​(int years,
                             int months,
                             int weeks,
                             int days,
                             int hours,
                             int minutes,
                             int seconds,
                             int millis,
                             PeriodType type)
        Creates a period from a set of field values.
        Parameters:
        years - amount of years in this period, which must be zero if unsupported
        months - amount of months in this period, which must be zero if unsupported
        weeks - amount of weeks in this period, which must be zero if unsupported
        days - amount of days in this period, which must be zero if unsupported
        hours - amount of hours in this period, which must be zero if unsupported
        minutes - amount of minutes in this period, which must be zero if unsupported
        seconds - amount of seconds in this period, which must be zero if unsupported
        millis - amount of milliseconds in this period, which must be zero if unsupported
        type - which set of fields this period supports
        Throws:
        java.lang.IllegalArgumentException - if period type is invalid
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • BasePeriod

        protected BasePeriod​(long startInstant,
                             long endInstant,
                             PeriodType type,
                             Chronology chrono)
        Creates a period from the given interval endpoints.
        Parameters:
        startInstant - interval start, in milliseconds
        endInstant - interval end, in milliseconds
        type - which set of fields this period supports, null means standard
        chrono - the chronology to use, null means ISO default
        Throws:
        java.lang.IllegalArgumentException - if period type is invalid
      • BasePeriod

        protected BasePeriod​(ReadableInstant startInstant,
                             ReadableInstant endInstant,
                             PeriodType type)
        Creates a period from the given interval endpoints.
        Parameters:
        startInstant - interval start, null means now
        endInstant - interval end, null means now
        type - which set of fields this period supports, null means standard
        Throws:
        java.lang.IllegalArgumentException - if period type is invalid
      • BasePeriod

        protected BasePeriod​(ReadablePartial start,
                             ReadablePartial end,
                             PeriodType type)
        Creates a period from the given duration and end point.

        The two partials must contain the same fields, thus you can specify two LocalDate objects, or two LocalTime objects, but not one of each. As these are Partial objects, time zones have no effect on the result.

        The two partials must also both be contiguous - see DateTimeUtils.isContiguous(ReadablePartial) for a definition. Both LocalDate and LocalTime are contiguous.

        Parameters:
        start - the start of the period, must not be null
        end - the end of the period, must not be null
        type - which set of fields this period supports, null means standard
        Throws:
        java.lang.IllegalArgumentException - if the partials are null or invalid
        Since:
        1.1
      • BasePeriod

        protected BasePeriod​(ReadableInstant startInstant,
                             ReadableDuration duration,
                             PeriodType type)
        Creates a period from the given start point and duration.
        Parameters:
        startInstant - the interval start, null means now
        duration - the duration of the interval, null means zero-length
        type - which set of fields this period supports, null means standard
      • BasePeriod

        protected BasePeriod​(ReadableDuration duration,
                             ReadableInstant endInstant,
                             PeriodType type)
        Creates a period from the given duration and end point.
        Parameters:
        duration - the duration of the interval, null means zero-length
        endInstant - the interval end, null means now
        type - which set of fields this period supports, null means standard
      • BasePeriod

        protected BasePeriod​(long duration)
        Creates a period from the given millisecond duration with the standard period type and ISO rules, ensuring that the calculation is performed with the time-only period type.

        The calculation uses the hour, minute, second and millisecond fields.

        Parameters:
        duration - the duration, in milliseconds
      • BasePeriod

        protected BasePeriod​(long duration,
                             PeriodType type,
                             Chronology chrono)
        Creates a period from the given millisecond duration, which is only really suitable for durations less than one day.

        Only fields that are precise will be used. Thus the largest precise field may have a large value.

        Parameters:
        duration - the duration, in milliseconds
        type - which set of fields this period supports, null means standard
        chrono - the chronology to use, null means ISO default
        Throws:
        java.lang.IllegalArgumentException - if period type is invalid
      • BasePeriod

        protected BasePeriod​(java.lang.Object period,
                             PeriodType type,
                             Chronology chrono)
        Creates a new period based on another using the ConverterManager.
        Parameters:
        period - the period to convert
        type - which set of fields this period supports, null means use type from object
        chrono - the chronology to use, null means ISO default
        Throws:
        java.lang.IllegalArgumentException - if period is invalid
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • BasePeriod

        protected BasePeriod​(int[] values,
                             PeriodType type)
        Constructor used when we trust ourselves. Do not expose publicly.
        Parameters:
        values - the values to use, not null, not cloned
        type - which set of fields this period supports, not null
    • Method Detail

      • checkPeriodType

        protected PeriodType checkPeriodType​(PeriodType type)
        Validates a period type, converting nulls to a default value and checking the type is suitable for this instance.
        Parameters:
        type - the type to check, may be null
        Returns:
        the validated type to use, not null
        Throws:
        java.lang.IllegalArgumentException - if the period type is invalid
      • getValue

        public int getValue​(int index)
        Gets the value at the specified index.
        Specified by:
        getValue in interface ReadablePeriod
        Parameters:
        index - the index to retrieve
        Returns:
        the value of the field at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is invalid
      • toDurationFrom

        public Duration toDurationFrom​(ReadableInstant startInstant)
        Gets the total millisecond duration of this period relative to a start instant.

        This method adds the period to the specified instant in order to calculate the duration.

        An instant must be supplied as the duration of a period varies. For example, a period of 1 month could vary between the equivalent of 28 and 31 days in milliseconds due to different length months. Similarly, a day can vary at Daylight Savings cutover, typically between 23 and 25 hours.

        Parameters:
        startInstant - the instant to add the period to, thus obtaining the duration
        Returns:
        the total length of the period as a duration relative to the start instant
        Throws:
        java.lang.ArithmeticException - if the millis exceeds the capacity of the duration
      • toDurationTo

        public Duration toDurationTo​(ReadableInstant endInstant)
        Gets the total millisecond duration of this period relative to an end instant.

        This method subtracts the period from the specified instant in order to calculate the duration.

        An instant must be supplied as the duration of a period varies. For example, a period of 1 month could vary between the equivalent of 28 and 31 days in milliseconds due to different length months. Similarly, a day can vary at Daylight Savings cutover, typically between 23 and 25 hours.

        Parameters:
        endInstant - the instant to subtract the period from, thus obtaining the duration
        Returns:
        the total length of the period as a duration relative to the end instant
        Throws:
        java.lang.ArithmeticException - if the millis exceeds the capacity of the duration
      • checkAndUpdate

        private void checkAndUpdate​(DurationFieldType type,
                                    int[] values,
                                    int newValue)
        Checks whether a field type is supported, and if so adds the new value to the relevant index in the specified array.
        Parameters:
        type - the field type
        values - the array to update
        newValue - the new value to store if successful
      • setPeriod

        protected void setPeriod​(ReadablePeriod period)
        Sets all the fields of this period from another.
        Parameters:
        period - the period to copy from, not null
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • setPeriodInternal

        private void setPeriodInternal​(ReadablePeriod period)
        Private method called from constructor.
      • setPeriod

        protected void setPeriod​(int years,
                                 int months,
                                 int weeks,
                                 int days,
                                 int hours,
                                 int minutes,
                                 int seconds,
                                 int millis)
        Sets the eight standard the fields in one go.
        Parameters:
        years - amount of years in this period, which must be zero if unsupported
        months - amount of months in this period, which must be zero if unsupported
        weeks - amount of weeks in this period, which must be zero if unsupported
        days - amount of days in this period, which must be zero if unsupported
        hours - amount of hours in this period, which must be zero if unsupported
        minutes - amount of minutes in this period, which must be zero if unsupported
        seconds - amount of seconds in this period, which must be zero if unsupported
        millis - amount of milliseconds in this period, which must be zero if unsupported
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • setPeriodInternal

        private int[] setPeriodInternal​(int years,
                                        int months,
                                        int weeks,
                                        int days,
                                        int hours,
                                        int minutes,
                                        int seconds,
                                        int millis)
        Private method called from constructor.
      • setField

        protected void setField​(DurationFieldType field,
                                int value)
        Sets the value of a field in this period.
        Parameters:
        field - the field to set
        value - the value to set
        Throws:
        java.lang.IllegalArgumentException - if field is is null or not supported.
      • setFieldInto

        protected void setFieldInto​(int[] values,
                                    DurationFieldType field,
                                    int value)
        Sets the value of a field in this period.
        Parameters:
        values - the array of values to update
        field - the field to set
        value - the value to set
        Throws:
        java.lang.IllegalArgumentException - if field is null or not supported.
      • addField

        protected void addField​(DurationFieldType field,
                                int value)
        Adds the value of a field in this period.
        Parameters:
        field - the field to set
        value - the value to set
        Throws:
        java.lang.IllegalArgumentException - if field is is null or not supported.
      • addFieldInto

        protected void addFieldInto​(int[] values,
                                    DurationFieldType field,
                                    int value)
        Adds the value of a field in this period.
        Parameters:
        values - the array of values to update
        field - the field to set
        value - the value to set
        Throws:
        java.lang.IllegalArgumentException - if field is is null or not supported.
      • mergePeriod

        protected void mergePeriod​(ReadablePeriod period)
        Merges the fields from another period.
        Parameters:
        period - the period to add from, not null
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • mergePeriodInto

        protected int[] mergePeriodInto​(int[] values,
                                        ReadablePeriod period)
        Merges the fields from another period.
        Parameters:
        values - the array of values to update
        period - the period to add from, not null
        Returns:
        the updated values
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • addPeriod

        protected void addPeriod​(ReadablePeriod period)
        Adds the fields from another period.
        Parameters:
        period - the period to add from, not null
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • addPeriodInto

        protected int[] addPeriodInto​(int[] values,
                                      ReadablePeriod period)
        Adds the fields from another period.
        Parameters:
        values - the array of values to update
        period - the period to add from, not null
        Returns:
        the updated values
        Throws:
        java.lang.IllegalArgumentException - if an unsupported field's value is non-zero
      • setValue

        protected void setValue​(int index,
                                int value)
        Sets the value of the field at the specified index.
        Parameters:
        index - the index
        value - the value to set
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is invalid
      • setValues

        protected void setValues​(int[] values)
        Sets the values of all fields.

        In version 2.0 and later, this method copies the array into the original. This is because the instance variable has been changed to be final to satisfy the Java Memory Model. This only impacts subclasses that are mutable.

        Parameters:
        values - the array of values