Package org.threeten.bp.chrono

Class ChronoDateImpl<D extends ChronoLocalDate>

  • Type Parameters:
    D - the date type
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<ChronoLocalDate>, Temporal, TemporalAccessor, TemporalAdjuster
    Direct Known Subclasses:
    HijrahDate, JapaneseDate, MinguoDate, ThaiBuddhistDate
    abstract class ChronoDateImpl<D extends ChronoLocalDate>
extends ChronoLocalDate
implements Temporal, TemporalAdjuster, java.io.Serializable
    A date expressed in terms of a standard year-month-day calendar system.

    This class is used by applications seeking to handle dates in non-ISO calendar systems. For example, the Japanese, Minguo, Thai Buddhist and others.

    ChronoLocalDate is built on the generic concepts of year, month and day. The calendar system, represented by a Chronology, expresses the relationship between the fields and this class allows the resulting date to be manipulated.

    Note that not all calendar systems are suitable for use with this class. For example, the Mayan calendar uses a system that bears no relation to years, months and days.

    The API design encourages the use of LocalDate for the majority of the application. This includes code to read and write from a persistent data store, such as a database, and to send dates and times across a network. The ChronoLocalDate instance is then used at the user interface level to deal with localized input/output.

    Example: 

            System.out.printf("Example()%n");
        // Enumerate the list of available calendars and print today for each
        Set<Chrono> chronos = Chrono.getAvailableChronologies();
        for (Chrono chrono : chronos) {
            ChronoLocalDate date = chrono.dateNow();
            System.out.printf("   %20s: %s%n", chrono.getID(), date.toString());
        }

        // Print the Hijrah date and calendar
        ChronoLocalDate date = Chrono.of("Hijrah").dateNow();
        int day = date.get(ChronoField.DAY_OF_MONTH);
        int dow = date.get(ChronoField.DAY_OF_WEEK);
        int month = date.get(ChronoField.MONTH_OF_YEAR);
        int year = date.get(ChronoField.YEAR);
        System.out.printf("  Today is %s %s %d-%s-%d%n", date.getChrono().getID(),
                dow, day, month, year);

        // Print today's date and the last day of the year
        ChronoLocalDate now1 = Chrono.of("Hijrah").dateNow();
        ChronoLocalDate first = now1.with(ChronoField.DAY_OF_MONTH, 1)
                .with(ChronoField.MONTH_OF_YEAR, 1);
        ChronoLocalDate last = first.plus(1, ChronoUnit.YEARS)
                .minus(1, ChronoUnit.DAYS);
        System.out.printf("  Today is %s: start: %s; end: %s%n", last.getChrono().getID(),
                first, last);

    Adding Calendars

    The set of calendars is extensible by defining a subclass of ChronoLocalDate to represent a date instance and an implementation of Chronology to be the factory for the ChronoLocalDate subclass.

    To permit the discovery of the additional calendar types the implementation of Chronology must be registered as a Service implementing the Chronology interface in the META-INF/Services file as per the specification of ServiceLoader. The subclass must function according to the Chronology class description and must provide its calendar name and calendar type.

    Specification for implementors

    This abstract class must be implemented with care to ensure other classes operate correctly. All implementations that can be instantiated must be final, immutable and thread-safe. Subclasses should be Serializable wherever possible.

    • Field Detail

      • serialVersionUID

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

    • Constructor Detail

      • ChronoDateImpl

        ChronoDateImpl()
        Creates an instance.

    • Method Detail

      • plus

        public ChronoDateImpl<D> plus​(long amountToAdd,
                              TemporalUnit unit)
        Description copied from interface: Temporal
        Returns an object of the same type as this object with the specified period added.

        This method returns a new object based on this one with the specified period added. For example, on a LocalDate, this could be used to add a number of years, months or days. The returned object will have the same observable type as this object.

        In some cases, changing a field is not fully defined. For example, if the target object is a date representing the 31st January, then adding one month would be unclear. In cases like this, the field is responsible for resolving the result. Typically it will choose the previous valid date, which would be the last valid day of February in this example.

        If the implementation represents a date-time that has boundaries, such as LocalTime, then the permitted units must include the boundary unit, but no multiples of the boundary unit. For example, LocalTime must accept DAYS but not WEEKS or MONTHS.

        Specification for implementors

        Implementations must check and handle all units defined in ChronoUnit. If the unit is supported, then the addition must be performed. If unsupported, then a DateTimeException must be thrown.

        If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.addTo(Temporal, long) passing this as the first argument.

        Implementations must not alter either this object or the specified temporal object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.

        Specified by:
        plus in interface Temporal
        Specified by:
        plus in class ChronoLocalDate
        Parameters:
        amountToAdd - the amount of the specified unit to add, may be negative
        unit - the unit of the period to add, not null
        Returns:
        an object of the same type with the specified period added, not null

      • plusYears

        abstract ChronoDateImpl<D> plusYears​(long yearsToAdd)
        Returns a copy of this date with the specified period in years added.

        This adds the specified period in years to the date. In some cases, adding years can cause the resulting date to become invalid. If this occurs, then other fields, typically the day-of-month, will be adjusted to ensure that the result is valid. Typically this will select the last valid day of the month.

        This instance is immutable and unaffected by this method call.

        Parameters:
        yearsToAdd - the years to add, may be negative
        Returns:
        a date based on this one with the years added, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • plusMonths

        abstract ChronoDateImpl<D> plusMonths​(long monthsToAdd)
        Returns a copy of this date with the specified period in months added.

        This adds the specified period in months to the date. In some cases, adding months can cause the resulting date to become invalid. If this occurs, then other fields, typically the day-of-month, will be adjusted to ensure that the result is valid. Typically this will select the last valid day of the month.

        This instance is immutable and unaffected by this method call.

        Parameters:
        monthsToAdd - the months to add, may be negative
        Returns:
        a date based on this one with the months added, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • plusWeeks

        ChronoDateImpl<D> plusWeeks​(long weeksToAdd)
        Returns a copy of this date with the specified period in weeks added.

        This adds the specified period in weeks to the date. In some cases, adding weeks can cause the resulting date to become invalid. If this occurs, then other fields will be adjusted to ensure that the result is valid.

        The default implementation uses plusDays(long) using a 7 day week.

        This instance is immutable and unaffected by this method call.

        Parameters:
        weeksToAdd - the weeks to add, may be negative
        Returns:
        a date based on this one with the weeks added, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • plusDays

        abstract ChronoDateImpl<D> plusDays​(long daysToAdd)
        Returns a copy of this date with the specified number of days added.

        This adds the specified period in days to the date.

        This instance is immutable and unaffected by this method call.

        Parameters:
        daysToAdd - the days to add, may be negative
        Returns:
        a date based on this one with the days added, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • minusYears

        ChronoDateImpl<D> minusYears​(long yearsToSubtract)
        Returns a copy of this date with the specified period in years subtracted.

        This subtracts the specified period in years to the date. In some cases, subtracting years can cause the resulting date to become invalid. If this occurs, then other fields, typically the day-of-month, will be adjusted to ensure that the result is valid. Typically this will select the last valid day of the month.

        The default implementation uses plusYears(long).

        This instance is immutable and unaffected by this method call.

        Parameters:
        yearsToSubtract - the years to subtract, may be negative
        Returns:
        a date based on this one with the years subtracted, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • minusMonths

        ChronoDateImpl<D> minusMonths​(long monthsToSubtract)
        Returns a copy of this date with the specified period in months subtracted.

        This subtracts the specified period in months to the date. In some cases, subtracting months can cause the resulting date to become invalid. If this occurs, then other fields, typically the day-of-month, will be adjusted to ensure that the result is valid. Typically this will select the last valid day of the month.

        The default implementation uses plusMonths(long).

        This instance is immutable and unaffected by this method call.

        Parameters:
        monthsToSubtract - the months to subtract, may be negative
        Returns:
        a date based on this one with the months subtracted, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • minusWeeks

        ChronoDateImpl<D> minusWeeks​(long weeksToSubtract)
        Returns a copy of this date with the specified period in weeks subtracted.

        This subtracts the specified period in weeks to the date. In some cases, subtracting weeks can cause the resulting date to become invalid. If this occurs, then other fields will be adjusted to ensure that the result is valid.

        The default implementation uses plusWeeks(long).

        This instance is immutable and unaffected by this method call.

        Parameters:
        weeksToSubtract - the weeks to subtract, may be negative
        Returns:
        a date based on this one with the weeks subtracted, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • minusDays

        ChronoDateImpl<D> minusDays​(long daysToSubtract)
        Returns a copy of this date with the specified number of days subtracted.

        This subtracts the specified period in days to the date.

        The default implementation uses plusDays(long).

        This instance is immutable and unaffected by this method call.

        Parameters:
        daysToSubtract - the days to subtract, may be negative
        Returns:
        a date based on this one with the days subtracted, not null
        Throws:
        DateTimeException - if the result exceeds the supported date range

      • atTime

        public ChronoLocalDateTime<?> atTime​(LocalTime localTime)
        Description copied from class: ChronoLocalDate
        Combines this date with a time to create a ChronoLocalDateTime.

        This returns a ChronoLocalDateTime formed from this date at the specified time. All possible combinations of date and time are valid.

        Overrides:
        atTime in class ChronoLocalDate
        Parameters:
        localTime - the local time to use, not null
        Returns:
        the local date-time formed from this date and the specified time, not null

      • until

        public long until​(Temporal endExclusive,
                  TemporalUnit unit)
        Description copied from interface: Temporal
        Calculates the period between this temporal and another temporal in terms of the specified unit.

        This calculates the period between two temporals in terms of a single unit. The start and end points are this and the specified temporal. The result will be negative if the end is before the start. For example, the period in hours between two temporal objects can be calculated using startTime.until(endTime, HOURS).

        The calculation returns a whole number, representing the number of complete units between the two temporals. For example, the period in hours between the times 11:30 and 13:29 will only be one hour as it is one minute short of two hours.

        There are two equivalent ways of using this method. The first is to invoke this method directly. The second is to use TemporalUnit.between(Temporal, Temporal): 

           // these two lines are equivalent
   between = thisUnit.between(start, end);
   between = start.until(end, thisUnit);
        The choice should be made based on which makes the code more readable.

        For example, this method allows the number of days between two dates to be calculated: 

           long daysBetween = DAYS.between(start, end);
   // or alternatively
   long daysBetween = start.until(end, DAYS);

        Specification for implementors

        Implementations must begin by checking to ensure that the input temporal object is of the same observable type as the implementation. They must then perform the calculation for all instances of ChronoUnit. A DateTimeException must be thrown for ChronoUnit instances that are unsupported.

        If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.between(Temporal, Temporal) passing this as the first argument and the input temporal as the second argument.

        In summary, implementations must behave in a manner equivalent to this code: 

          // check input temporal is the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw DateTimeException for unsupported units
  }
  return unit.between(this, endTemporal);

        The target object must not be altered by this method.

        Specified by:
        until in interface Temporal
        Parameters:
        endExclusive - the end temporal, of the same type as this object, not null
        unit - the unit to measure the period in, not null
        Returns:
        the amount of the period between this and the end

      • until

        public ChronoPeriod until​(ChronoLocalDate endDate)
        Description copied from class: ChronoLocalDate
        Calculates the period between this date and another date as a ChronoPeriod.

        This calculates the period between two dates. All supplied chronologies calculate the period using years, months and days, however the ChronoPeriod API allows the period to be represented using other units.

        The start and end points are this and the specified date. The result will be negative if the end is before the start. The negative sign will be the same in each of year, month and day.

        The calculation is performed using the chronology of this date. If necessary, the input date will be converted to match.

        This instance is immutable and unaffected by this method call.

        Specified by:
        until in class ChronoLocalDate
        Parameters:
        endDate - the end date, exclusive, which may be in any chronology, not null
        Returns:
        the period between this date and the end date, not null