Package org.silverpeas.core.date

Class Period

  • All Implemented Interfaces:
    Serializable
    @Embeddable
@DateRange(start="startDate",
           end="endDate")
public class Period
extends Object
implements Serializable

    A period is a lapse of time starting at a given date or datetime and ending at another given date or datetime. When the period takes care of the time, it is always set in UTC/Greenwich in order to avoid any bugs by comparing two periods in different time zones or offset zones. A period is indefinite when it spans over a very large of time that cannot be reached; in this case the period is counted in days between LocalDate.MIN and LocalDate.MAX. An indefinite period can be created either by:

    • invoking the indefinite() method,
    • or by invoking one of the between(...,...) method with as arguments the MIN et MAX values of one of the concrete date or datetime of the Java Time API,
    • or by invoking one of the betweenNullable(...,...) method with as arguments either null or the MIN et MAX values of one of the concrete date or datetime of the Java Time API.
    Author:
    mmoquillon
    See Also:
    Serialized Form

    • Constructor Detail

      • Period

        public Period()

    • Method Detail

      • indefinite

        public static Period indefinite()
        Creates an indefinite period of time. An undefined period is a period over an indefinite range of time meaning that whatever any event, it occurs during this period. It is like an infinite period but starting at LocalDate.MIN and ending at LocalDate.MAX.
        Returns:
        an undefined period.

      • between

        public static Period between​(Temporal start,
                             Temporal end)
        Creates a new period of time between the two specified non null date or datetime. It accepts as both Temporal parameters either LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime or Instant instances.
        Parameters:
        start - the start of the period. It defines the inclusive date or datetime at which the period starts.
        end - the end day of the period. It defines the exclusive date or the exclusive datetime at which the period ends. The end date must be the same or after the start date. An end date equal to the start date means the period is spanning all the day; it is equivalent to an end date being one day after the start date.
        Returns:
        the period of days between the two specified dates.
        Throws:
        IllegalArgumentException - if the concrete type of the temporal parameters isn't supported or if they aren't of the same concrete type.

      • between

        public static Period between​(LocalDate startDay,
                             LocalDate endDay)
        Creates a new period of time between the two non null specified dates. The period is spreading over all the day(s) between the specified inclusive start day and the exclusive end day; the period is expressed in days. For example, a period between 2016-12-15 and 2016-12-17 means the period is spreading over two days (2016-12-15 and 2016-12-16).
        Parameters:
        startDay - the start day of the period. It defines the inclusive date at which the period starts.
        endDay - the end day of the period. It defines the exclusive date at which the period ends. The end date must be the same or after the start date. An end date equal to the start date means the period is spanning all the day of the start date; it is equivalent to an end date being one day after the start date.
        Returns:
        the period of days between the two specified dates.

      • between

        public static Period between​(OffsetDateTime startDateTime,
                             OffsetDateTime endDateTime)
        Creates a new period of time between the two non null specified datetime. The period starts at the specified inclusive datetime and it ends at the specified other exclusive datetime. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startDateTime - the start datetime of the period. It defines the inclusive date time at which the period starts.
        endDateTime - the end datetime of the period. It defines the exclusive datetime at which the period ends. The end datetime must be after the start datetime.
        Returns:
        the period of time between the two specified datetimes.

      • between

        public static Period between​(ZonedDateTime startDateTime,
                             ZonedDateTime endDateTime)
        Creates a new period of time between the two non null specified datetime. The period starts at the specified inclusive datetime and it ends at the specified other exclusive datetime. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startDateTime - the start datetime of the period. It defines the inclusive date time at which the period starts.
        endDateTime - the end datetime of the period. It defines the exclusive datetime at which the period ends. The end datetime must be after the start datetime.
        Returns:
        the period of time between the two specified datetimes.

      • between

        public static Period between​(Instant startInstant,
                             Instant endInstant)
        Creates a new period of time between the two non-null specified instant. The period starts at the specified inclusive instant and it ends at the specified other exclusive instant. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startInstant - the start instant of the period. It defines the inclusive epoch date time at which the period starts.
        endInstant - the end instant of the period. It defines the exclusive epoch date time at which the period ends. The end instant must be after the start instant.
        Returns:
        the period of time between the two specified instants.

      • betweenInDays

        public static Period betweenInDays​(Instant startInstant,
                                   Instant endInstant)
        Creates a new period of time between the two days represented by the two non-null specified instant. The period is spreading over all the day(s) between the specified inclusive start day and the exclusive end day; the period is expressed in days. For example, a period between 2016-12-15 and 2016-12-17 means the period is spreading over two days (2016-12-15 and 2016-12-16). If you want the period spreads over a whole day, then the endInstant must after one day the startInstant (as the endInstant is exclusive): a period starting at 2016-12-15 and ending at 2016-12-16 means the period is spreading over the 2016-12-15.

        This method is a convenient one to represent a period in days with Date or Instant object (by using Date.toInstant()). Nevertheless we strongly recommend to prefer the between(LocalDate, LocalDate) instead to avoid unexpected surprise with the date handling.

        Parameters:
        startInstant - the start instant of the period. It defines the inclusive epoch day at which the period starts.
        endInstant - the end instant of the period. It defines the exclusive epoch day at which the period ends. The end instant must be after the start instant.
        Returns:
        the period of time between the two specified instants.

      • betweenNullable

        public static Period betweenNullable​(LocalDate startDay,
                                     LocalDate endDay)
        Creates a new period of time between the two specified dates. The period is spreading over all the day(s) between the specified inclusive start day and the exclusive end day; the period is expressed in days. For example, a period between 2016-12-15 and 2016-12-17 means the period is spreading over two days (2016-12-15 and 2016-12-16).
        Parameters:
        startDay - the start day of the period. It defines the inclusive date at which the period starts. If null, then the minimum supported LocalDate.MIN date is taken.
        endDay - the end day of the period. It defines the exclusive date at which the period ends. The end date must be the same or after the start date. An end date equal to the start date means the period is spanning all the day of the start date; it is equivalent to an end date being one day after the start date. If null, then the maximum supported LocalDate.MAX is taken.
        Returns:
        the period of days between the two specified dates.
        See Also:
        for the minimum supported date., for the maximum supported date.

      • betweenNullable

        public static Period betweenNullable​(OffsetDateTime startDateTime,
                                     OffsetDateTime endDateTime)
        Creates a new period of time between the two specified datetime. The period starts at the specified inclusive datetime and it ends at the specified other exclusive datetime. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startDateTime - the start datetime of the period. It defines the inclusive date time at which the period starts. If null then the minimum supported OffsetDateTime.MIN is taken.
        endDateTime - the end datetime of the period. It defines the exclusive datetime at which the period ends. The end datetime must be after the start datetime. If null, then the maximum supported OffsetDateTime.MAX is taken.
        Returns:
        the period of time between the two specified date times.
        See Also:
        for the minimum supported date., for the maximum supported date.

      • betweenNullable

        public static Period betweenNullable​(ZonedDateTime startDateTime,
                                     ZonedDateTime endDateTime)
        Creates a new period of time between the two specified datetime. The period starts at the specified inclusive datetime and it ends at the specified other exclusive datetime. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startDateTime - the start datetime of the period. It defines the inclusive date time at which the period starts. If null then the minimum supported OffsetDateTime.MIN is taken.
        endDateTime - the end datetime of the period. It defines the exclusive datetime at which the period ends. The end datetime must be after the start datetime. If null, then the maximum supported OffsetDateTime.MAX is taken.
        Returns:
        the period of time between the two specified date times.
        See Also:
        for the minimum supported date., for the maximum supported date.

      • betweenNullable

        public static Period betweenNullable​(Instant startInstant,
                                     Instant endInstant)
        Creates a new period of time between the two specified instants. The period starts at the specified inclusive instant and it ends at the specified other exclusive instant. For example, a period between 2016-12-17T13:30:00Z and 2016-12-17T14:30:00Z means the period is spanning one hour the December 12.
        Parameters:
        startInstant - the start instant of the period. It defines the inclusive epoch date time at which the period starts. If null then the minimum supported OffsetDateTime.MIN is taken.
        endInstant - the end instant of the period. It defines the exclusive epoch date time at which the period ends. The end instant must be after the start instant. If null, then the maximum supported Instant.MAX is taken.
        Returns:
        the period of time between the two specified instants.
        See Also:
        for the minimum supported date., for the maximum supported date.

      • getStartDate

        public Temporal getStartDate()
        Gets the inclusive temporal start date of this period of time.

        If the period is in days, then the returned temporal is a LocalDate which represents the first day of the period.
        Otherwise, the date and the time in UTC/Greenwich at which this period starts on the timeline is returned.

        Returns:
        a temporal instance (LocalDate if all day period or OffsetDateTime) otherwise.

      • getEndDate

        public Temporal getEndDate()
        Gets the exclusive temporal end date of this period of time.

        If the period is in days, then the returned temporal is a LocalDate which represents the last day of the period.
        Otherwise, the date and the time in UTC/Greenwich at which this period ends on the timeline is returned.

        Returns:
        a temporal instance (LocalDate if all day period or OffsetDateTime) otherwise.

      • isInDays

        public boolean isInDays()
        Is this period in days?
        Returns:
        true if the lapse of time defining this period is expressed in days. False otherwise.

      • isIndefinite

        public boolean isIndefinite()
        Is this period an indefinite one? That is to say a period ranging over an indefinite range of time meaning that whatever any event, it occurs during this period. In Silverpeas, an indefinite period starts at LocalDate.MIN and ends at LocalDate.MAX.
        Returns:
        true if this period is an indefinite one. False otherwise.

      • startsAtMinDate

        public boolean startsAtMinDate()
        Is this period starts at the the minimum supported date/datetime in Java?
        Returns:
        true if this period starts at the minimum date/datetime supported by Java. False otherwise.
        See Also:
        for the minimum supported date.

      • endsAtMaxDate

        public boolean endsAtMaxDate()
        Is this period ends at the the maximum supported date/datetime in Java?
        Returns:
        true if this period ends at the minimum date/datetime supported by Java. False otherwise.
        See Also:
        for the maximum supported datetime.

      • includes

        public boolean includes​(Temporal dateTime)
        Is this period including the specified temporal?
        Parameters:
        dateTime - either a date or a date time. Any other temporal type isn't supported.
        Returns:
        true if the specified date is included in this period, false otherwise.

      • endsBefore

        public boolean endsBefore​(Temporal dateTime)
        Is this period ending before the specified temporal?
        Parameters:
        dateTime - either a date or a date time. Any other temporal type isn't supported.
        Returns:
        true if this period's end date is at or before the specified temporal (the period's end date is exclusive).

      • endsAfter

        public boolean endsAfter​(Temporal dateTime)
        Is this period ending after the specified temporal?
        Parameters:
        dateTime - either a date or a date time. Any other temporal type isn't supported.
        Returns:
        true if this period's end date is at or before the specified temporal (the period's end date is exclusive).

      • startsAfter

        public boolean startsAfter​(Temporal dateTime)
        Is this period starting after the specified temporal?
        Parameters:
        dateTime - either a date or a date time. Any other temporal type isn't supported.
        Returns:
        true if this period's start date is after the specified temporal (the period's start date is inclusive).

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object