Class Period
- java.lang.Object
-
- org.silverpeas.core.date.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
andLocalDate.MAX
. An indefinite period can be created either by:- invoking the
indefinite()
method, - or by invoking one of the
between(...,...)
method with as arguments theMIN
etMAX
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 theMIN
etMAX
values of one of the concrete date or datetime of the Java Time API.
- Author:
- mmoquillon
- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description Period()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Period
between(Instant startInstant, Instant endInstant)
Creates a new period of time between the two non-null specified instant.static Period
between(LocalDate startDay, LocalDate endDay)
Creates a new period of time between the two non null specified dates.static Period
between(OffsetDateTime startDateTime, OffsetDateTime endDateTime)
Creates a new period of time between the two non null specified datetime.static Period
between(Temporal start, Temporal end)
Creates a new period of time between the two specified non null date or datetime.static Period
between(ZonedDateTime startDateTime, ZonedDateTime endDateTime)
Creates a new period of time between the two non null specified datetime.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.static Period
betweenNullable(Instant startInstant, Instant endInstant)
Creates a new period of time between the two specified instants.static Period
betweenNullable(LocalDate startDay, LocalDate endDay)
Creates a new period of time between the two specified dates.static Period
betweenNullable(OffsetDateTime startDateTime, OffsetDateTime endDateTime)
Creates a new period of time between the two specified datetime.static Period
betweenNullable(Temporal start, Temporal end)
Creates a new period of time between the two specified date or datetime.static Period
betweenNullable(ZonedDateTime startDateTime, ZonedDateTime endDateTime)
Creates a new period of time between the two specified datetime.Period
copy()
boolean
endsAfter(Temporal dateTime)
Is this period ending after the specified temporal?boolean
endsAtMaxDate()
Is this period ends at the the maximum supported date/datetime in Java?boolean
endsBefore(Temporal dateTime)
Is this period ending before the specified temporal?boolean
equals(Object o)
Temporal
getEndDate()
Gets the exclusive temporal end date of this period of time.Temporal
getStartDate()
Gets the inclusive temporal start date of this period of time.int
hashCode()
boolean
includes(Temporal dateTime)
Is this period including the specified temporal?static Period
indefinite()
Creates an indefinite period of time.boolean
isInDays()
Is this period in days?boolean
isIndefinite()
Is this period an indefinite one?boolean
startsAfter(Temporal dateTime)
Is this period starting after the specified temporal?boolean
startsAtMinDate()
Is this period starts at the the minimum supported date/datetime in Java?
-
-
-
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 atLocalDate.MIN
and ending atLocalDate.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 bothTemporal
parameters eitherLocalDate
,LocalDateTime
,OffsetDateTime
,ZonedDateTime
orInstant
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
orInstant
object (by usingDate.toInstant()
). Nevertheless we strongly recommend to prefer thebetween(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(Temporal start, Temporal end)
Creates a new period of time between the two specified date or datetime. If date parameters are instances ofLocalDate
, take a look at the methodbetweenNullable(LocalDate, LocalDate)
. If date parameters are instances ofOffsetDateTime
, take a look at the methodbetweenNullable(OffsetDateTime, OffsetDateTime)
. If both date parameters are null, then a period betweenLocalDate.MIN
andLocalDate.MAX
is returned unless those parameters are explicitly typed; for example:Period.betweenNullable((OffsetDateTime) null, null)
- Parameters:
start
- the start of the period. It defines the inclusive date or datetime at which the period starts. If it is null then the minimum temporal (date or datetime) is taken.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. If It is null then the maximum temporal (date or datetime) is taken.- Returns:
- the period of days between the two specified dates.
- Throws:
IllegalArgumentException
- if date parameters are not bothLocalDate
orOffsetDateTime
instances.- See Also:
for the minimum supported date.
,for the maximum supported date.
,for the maximum supported datetime.
,for the maximum supported datetime.
-
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 supportedLocalDate.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 supportedLocalDate.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 supportedOffsetDateTime.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 supportedOffsetDateTime.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 supportedOffsetDateTime.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 supportedOffsetDateTime.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 supportedOffsetDateTime.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 supportedInstant.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 orOffsetDateTime
) 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 orOffsetDateTime
) 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 atLocalDate.MIN
and ends atLocalDate.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).
-
copy
public Period copy()
-
-