Top Description Fields Constructors Methods
net.fortuna.ical4j.model

public Class Period<T extends Temporal>

extends Object
implements Comparable<Period<T extends Temporal>>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Comparable
Imports
net.fortuna.ical4j.util.TimeZones, org.threeten.extra.Interval, java.io.Serializable, java.time.Instant, .LocalDate, .LocalDateTime, .ZoneId, java.time.format.DateTimeParseException, java.time.temporal.Temporal, .TemporalAmount, java.util.*, .Date
$Id$ [Apr 14, 2004] Defines a period of time. A period may be specified as either a start date and end date, or a start date and duration. This class enforces a consistent string representation of start date and (where specified) end date via a common CalendarDateFormat.

Note

End dates and durations are implicitly derived when not explicitly specified. This means that you cannot rely on the returned values from the getters to deduce whether a period has an explicit end date or duration. 

    3.3.9.  Period of Time

   Value Name:  PERIOD

   Purpose:  This value type is used to identify values that contain a
      precise period of time.

   Format Definition:  This value type is defined by the following
      notation:

       period     = period-explicit / period-start

       period-explicit = date-time "/" date-time
       ; [ISO.8601.2004] complete representation basic format for a
       ; period of time consisting of a start and end.  The start MUST
       ; be before the end.

       period-start = date-time "/" dur-value
       ; [ISO.8601.2004] complete representation basic format for a
       ; period of time consisting of a start and positive duration
       ; of time.


   Description:  If the property permits, multiple "period" values are
      specified by a COMMA-separated list of values.  There are two
      forms of a period of time.  First, a period of time is identified
      by its start and its end.  This format is based on the
      [ISO.8601.2004] complete representation, basic format for "DATE-
      TIME" start of the period, followed by a SOLIDUS character
      followed by the "DATE-TIME" of the end of the period.  The start
      of the period MUST be before the end of the period.  Second, a
      period of time can also be defined by a start and a positive
      duration of time.  The format is based on the [ISO.8601.2004]
      complete representation, basic format for the "DATE-TIME" start of
      the period, followed by a SOLIDUS character, followed by the
      [ISO.8601.2004] basic format for "DURATION" of the period.

   Example:  The period starting at 18:00:00 UTC, on January 1, 1997 and
      ending at 07:00:00 UTC on January 2, 1997 would be:

       19970101T180000Z/19970102T070000Z

      The period start at 18:00:00 on January 1, 1997 and lasting 5
      hours and 30 minutes would be:

       19970101T180000Z/PT5H30M

      No additional content value encoding (i.e., BACKSLASH character
      encoding, see Section 3.3.11) is defined for this value type.
Author
Ben Fortuna

Field Summary

Modifier and TypeField and Description
private Component
component

private static final TemporalComparator
DATE_RANGE_COMPARATOR

private final transient CalendarDateFormat
dateFormat

private final TemporalAmountAdapter
duration

private final T
end

private final T
start

Constructor Summary

AccessConstructor and Description
public
Period(final T
the start date of the period
start, final T
the end date of the period
end)

Constructs a new period with the specified start and end date.

public
Period(final T
the start date of the period
start, final T
the end date of the period
end, CalendarDateFormat
the format used to generate string representations
dateFormat)

Constructs a new period with the specified start and end date with a common date format.

public
Period(final DateTime
the start date of the period
start, final Dur
the duration of the period
duration)
Deprecated

Constructs a new period with the specified start date and duration.

public
Period(final T
the start date of the period
start, final TemporalAmount
the duration of the period
duration)

Constructs a new period with the specified start date and duration.

public
Period(final T start, final TemporalAmount duration, CalendarDateFormat dateFormat)

private
Period(final T
the start date of the period
start, final TemporalAmountAdapter
the duration of the period
duration)

Constructs a new period with the specified start date and duration.

private
Period(final T
the start date of the period
start, final TemporalAmountAdapter
the duration of the period
duration, CalendarDateFormat dateFormat)

Constructs a new period with the specified start date and duration.

Method Summary

Modifier and TypeMethod and Description
public final Period<T>

Returns:

a period
add(final Period<T>
the period to add to this one
period)

Creates a period that encompasses both this period and another one.

public final int

Returns:

a postive value if this period is greater, negative if the other is greater, or zero if they are equal
compareTo(final Period<T>
a period to compare with this one
period)

Implements java.lang.Comparable.compareTo.

Compares the specified period with this period.

private int
compareTo(final Period<T> period, TemporalComparator comparator)

public boolean
equals(Object
the reference object with which to compare.
o)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public Component
getComponent()

public final TemporalAmount

Returns:

the duration of this period in milliseconds.
getDuration()

Returns the duration of this period.

public final T

Returns:

the end date of this period.
getEnd()

Returns the end date of this period.

public final T

Returns:

Returns the start.
getStart()

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public final boolean

Returns:

true if the specified date occurs within the current period
includes(final Date
a date to test for inclusion
date, final boolean
indicates if the start and end of the period are included in the test
inclusive)
Deprecated use Period#includes(Temporal) instead.

public final boolean

Returns:

true if the specified date occurs within the current period
includes(final Temporal
a date to test for inclusion
date)

Determines if the specified date occurs within this period (inclusive of period start and end).

public boolean

Returns:

true if the specified period intersects this one, false otherwise.
intersects(Period<?>
a possible intersecting period
other)

Decides whether this period intersects with another one.

public final boolean

Returns:

true if this period consumes no time, otherwise false
isEmpty()

An empty period is one that consumes no time.

public static <
the expected temporal type of the resulting period
T extends Temporal> Period<T>

Returns:

a new period instance
parse(String
a string representation of a period
value)

Parse a string representation of a period.

private static TemporalAmountAdapter
parseDuration(String value)

private static <T extends Temporal> T
parseEndDate(String value, boolean resolve)

private static <T extends Temporal> T
parseStartDate(String value)

public void
setComponent(Component component)

public final PeriodList<T>

Returns:

a list containing zero, one or two periods.
subtract(final Period<T>
a period to subtract from this one
period)

Creates a set of periods resulting from the subtraction of the specified period from this one.

private PeriodList<T>
subtractInterval(Period<T> period)

public Interval
toInterval()

public Interval
toInterval(ZoneId zoneId)

public String

Returns:

a string representation of the period
toString()

Overrides java.lang.Object.toString.

Formats the period as an iCalendar compatible string.

pack-priv String
toString(CalendarDateFormat dateFormat)

public String

Returns:

a string representation of the period as applied in the specified timezone
toString(ZoneId zoneId)

Formats the period as an iCalendar compatible string in the specified timezone.

pack-priv String
toString(CalendarDateFormat dateFormat, ZoneId zoneId)

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

componentback to summary
private Component component
DATE_RANGE_COMPARATORback to summary
private static final TemporalComparator DATE_RANGE_COMPARATOR
dateFormatback to summary
private final transient CalendarDateFormat dateFormat
durationback to summary
private final TemporalAmountAdapter duration
endback to summary
private final T end
startback to summary
private final T start

Constructor Detail

Periodback to summary
public Period(final T start, final T end)

Constructs a new period with the specified start and end date.

Parameters
start:T

the start date of the period

end:T

the end date of the period

Periodback to summary
public Period(final T start, final T end, CalendarDateFormat dateFormat)

Constructs a new period with the specified start and end date with a common date format.

Parameters
start:T

the start date of the period

end:T

the end date of the period

dateFormat:CalendarDateFormat

the format used to generate string representations

Periodback to summary
public Period(final DateTime start, final Dur duration)

Deprecated

Constructs a new period with the specified start date and duration.

Parameters
start:DateTime

the start date of the period

duration:Dur

the duration of the period

Annotations
@Deprecated
Periodback to summary
public Period(final T start, final TemporalAmount duration)

Constructs a new period with the specified start date and duration.

Parameters
start:T

the start date of the period

duration:TemporalAmount

the duration of the period

Periodback to summary
public Period(final T start, final TemporalAmount duration, CalendarDateFormat dateFormat)
Periodback to summary
private Period(final T start, final TemporalAmountAdapter duration)

Constructs a new period with the specified start date and duration.

Parameters
start:T

the start date of the period

duration:TemporalAmountAdapter

the duration of the period

Periodback to summary
private Period(final T start, final TemporalAmountAdapter duration, CalendarDateFormat dateFormat)

Constructs a new period with the specified start date and duration.

Parameters
start:T

the start date of the period

duration:TemporalAmountAdapter

the duration of the period

Method Detail

addback to summary
public final Period<T> add(final Period<T> period)

Creates a period that encompasses both this period and another one. If the other period is null, return a copy of this period.

Note

Resulting periods are specified by explicitly setting a start date and end date (i.e. durations are implied).

Parameters
period:Period<T>

the period to add to this one

Returns:Period<T>

a period

compareToback to summary
public final int compareTo(final Period<T> period)

Implements java.lang.Comparable.compareTo.

Compares the specified period with this period. First, compare the start dates. If they are the same, compare the end dates.

Parameters
period:Period<T>

a period to compare with this one

Returns:int

a postive value if this period is greater, negative if the other is greater, or zero if they are equal

Annotations
@Override
compareToback to summary
private int compareTo(final Period<T> period, TemporalComparator comparator)
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getComponentback to summary
public Component getComponent()
getDurationback to summary
public final TemporalAmount getDuration()

Returns the duration of this period. If an explicit duration is not specified, the duration is derived from the end date.

Returns:TemporalAmount

the duration of this period in milliseconds.

getEndback to summary
public final T getEnd()

Returns the end date of this period. If an explicit end date is not specified, the end date is derived from the duration.

Returns:T

the end date of this period.

getStartback to summary
public final T getStart()
Returns:T

Returns the start.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
includesback to summary
public final boolean includes(final Date date, final boolean inclusive)

Deprecated

use Period#includes(Temporal) instead.

Parameters
date:Date

a date to test for inclusion

inclusive:boolean

indicates if the start and end of the period are included in the test

Returns:boolean

true if the specified date occurs within the current period

Annotations
@Deprecated
includesback to summary
public final boolean includes(final Temporal date)

Determines if the specified date occurs within this period (inclusive of period start and end).

Parameters
date:Temporal

a date to test for inclusion

Returns:boolean

true if the specified date occurs within the current period

intersectsback to summary
public boolean intersects(Period<?> other)

Decides whether this period intersects with another one.

Parameters
other:Period<?>

a possible intersecting period

Returns:boolean

true if the specified period intersects this one, false otherwise.

isEmptyback to summary
public final boolean isEmpty()

An empty period is one that consumes no time.

Returns:boolean

true if this period consumes no time, otherwise false

parseback to summary
public static <T extends Temporal> Period<T> parse(String value)

Parse a string representation of a period.

Parameters
<T>
the expected temporal type of the resulting period
value:String

a string representation of a period

Returns:Period<T>

a new period instance

Exceptions
DateTimeParseException:
if the text cannot be parsed to a period
parseDurationback to summary
private static TemporalAmountAdapter parseDuration(String value)
parseEndDateback to summary
private static <T extends Temporal> T parseEndDate(String value, boolean resolve) throws DateTimeParseException
parseStartDateback to summary
private static <T extends Temporal> T parseStartDate(String value) throws DateTimeParseException
setComponentback to summary
public void setComponent(Component component)
subtractback to summary
public final PeriodList<T> subtract(final Period<T> period)

Creates a set of periods resulting from the subtraction of the specified period from this one. If the specified period is completely contained in this period, the resulting list will contain two periods. Otherwise it will contain one. If the specified period does not intersect this period a list containing this period is returned. If this period is completely contained within the specified period an empty period list is returned.

Parameters
period:Period<T>

a period to subtract from this one

Returns:PeriodList<T>

a list containing zero, one or two periods.

subtractIntervalback to summary
private PeriodList<T> subtractInterval(Period<T> period)
toIntervalback to summary
public Interval toInterval()
toIntervalback to summary
public Interval toInterval(ZoneId zoneId)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Formats the period as an iCalendar compatible string.

Note

Where a period represents floating date/time values the default local timezone is applied prior to formatting.

Returns:String

a string representation of the period

Annotations
@Override
toStringback to summary
pack-priv String toString(CalendarDateFormat dateFormat)
toStringback to summary
public String toString(ZoneId zoneId)

Formats the period as an iCalendar compatible string in the specified timezone.

Returns:String

a string representation of the period as applied in the specified timezone

toStringback to summary
pack-priv String toString(CalendarDateFormat dateFormat, ZoneId zoneId)