time
Class Interval

java.lang.Object
  time.Interval

All Implemented Interfaces:

java.lang.Comparable<Interval>, java.lang.Iterable<Instant>, java.util.Collection<Instant>, java.util.Set<Instant>, java.util.SortedSet<Instant>

public final class Interval
extends java.lang.Object
implements java.lang.Comparable<Interval>, java.util.SortedSet<Instant>

Interval is the implementation of an immutable time interval. A time interval represents a period of time between two instants.

An Interval contains all Instant that are greater than the start instant (inclusive) and lower than the end instant (exclusive), using the natural order of Instant (that is the chronological order). So the end instant is always greater than or equal to the start instant.

As an Interval can be seen as a sorted set of instant, it implements the java.util.SortedSet<Instant> interface. And as an Interval is immutable, the SortedSet is also immutable: every mutative method of the SortedSet interface throws an UnsupportedOperationException as the Collection interface allows it.

The Interval has not been designed to be iterated through Iterator, because it can contain a lot of Instant objects. For example, if an interval has a duration of one simple day, since the current implementation of Instant is millisecond accurate, it means that it contains 86 400 000 instants. Iterating such an interval will be likely unappropriate (but possible if really needed). And as Instant may be in the future event more accurate (nanoseconds), Interval may contain event more Instant, so you should also not use the size() method. The getDuration() is the appropriate method to know the duration of an Interval.

Interval have an natural order, which is consistent with equals: they are sorted by their starting intant first. If two intervals have the same starting instant, they are sorted by their ending instant. Other Comparator are also provided:

• COMPARATOR_BY_STARTING_ONLY
• COMPARATOR_BY_ENDING_ONLY
• COMPARATOR_BY_ENDING_THEN_STARTING

Author:

Arnaud Roques

See Also:

Instant

Field Summary

static java.util.Comparator<Interval>	COMPARATOR_BY_ENDING_ONLY Comparator that compares Intervals by their ending instant.
static java.util.Comparator<Interval>	COMPARATOR_BY_ENDING_THEN_STARTING Comparator that compares Intervals by their ending instant first, then their starting instant.
static java.util.Comparator<Interval>	COMPARATOR_BY_STARTING_ONLY Comparator that compares Intervals by their starting instant.
static java.util.Comparator<Interval>	COMPARATOR_BY_STARTING_THEN_ENDING Comparator that compares Intervals by their starting instant first, then their ending instant (natural order of Interval).
static Interval	WHOLE_TIME An interval that contains the whole representation of time.

Constructor Summary

Interval(Instant start, Instant end)
Create a new Interval.

Method Summary

boolean	add(Instant o) As Interval are immutable, throws a UnsupportedOperationException.
boolean	addAll(java.util.Collection<? extends Instant> c) As Interval are immutable, throws a UnsupportedOperationException.
void	clear() As Interval are immutable, throws a UnsupportedOperationException.
java.util.Comparator<? super Instant>	comparator() Returns null, as Interval uses the natural order of Instant.
int	compareTo(Interval otherInterval) Compare two interval chronogically.
boolean	contains(java.lang.Object obj) Returns true if this set contains the specified Instant.
boolean	containsAll(java.util.Collection<?> c) Returns true if this set contains all of the elements of the specified collection.
boolean	equals(java.lang.Object obj) Compare two interval for equality.
Instant	first() Returns the first (lowest) Instant currently in this Interval.
long	getDuration() Compute the duration in milliseconds of the Interval.
Instant	getEnd() Return the ending instant of this interval.
Interval	getIntersection(Interval otherInterval) Return the intersection between this interval and another interval.
Instant	getStart() Return the starting instant of this interval.
int	hashCode() Returns a hash code value for this object.
Interval	headSet(Instant toInstant) Return a new interval that contains all instants of this interval strictly less than toInstant.
boolean	isEmpty() Test if the Interval is empty (has a duration of 0L).
java.util.Iterator<Instant>	iterator() Returns an iterator over the instants in this interval.
Instant	last() Returns the last (highest) Instant currently in this Interval.
boolean	remove(java.lang.Object o) As Interval are immutable, throws a UnsupportedOperationException.
boolean	removeAll(java.util.Collection<?> c) As Interval are immutable, throws a UnsupportedOperationException.
boolean	retainAll(java.util.Collection<?> c) As Interval are immutable, throws a UnsupportedOperationException.
int	size() Return the number of Instant in this Interval.
Interval	subSet(Instant fromInstant, Instant toInstant) Return a new interval that contains all instants of this interval greater than or equals to fromInstant and strictly less than toInstant.
Interval	tailSet(Instant fromInstant) Return a new interval that contains all instants of this interval greater than or equals to fromInstant.
java.lang.Object[]	toArray() Returns an array containing all of the instants in this interval.
<T> T[]	toArray(T[] a) Returns an array containing all of the instants in this interval.
java.lang.String	toString() Convert the interval in a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

COMPARATOR_BY_STARTING_ONLY

public static final java.util.Comparator<Interval> COMPARATOR_BY_STARTING_ONLY

Comparator that compares Intervals by their starting instant.
Please not that this comparator is not consistent with equals, since all Intervals that have the same starting instant are equals according to this comparator, even if they have different ending instants.

COMPARATOR_BY_ENDING_ONLY

public static final java.util.Comparator<Interval> COMPARATOR_BY_ENDING_ONLY

Comparator that compares Intervals by their ending instant.
Please not that this comparator is not consistent with equals, since all Intervals that have the same ending instant are equals according to this comparator, even if they have different starting instants.

COMPARATOR_BY_STARTING_THEN_ENDING

public static final java.util.Comparator<Interval> COMPARATOR_BY_STARTING_THEN_ENDING

Comparator that compares Intervals by their starting instant first, then their ending instant (natural order of Interval).
This comparator is consistent with equals.

COMPARATOR_BY_ENDING_THEN_STARTING

public static final java.util.Comparator<Interval> COMPARATOR_BY_ENDING_THEN_STARTING

Comparator that compares Intervals by their ending instant first, then their starting instant.
This comparator is consistent with equals.

WHOLE_TIME

public static final Interval WHOLE_TIME

An interval that contains the whole representation of time. Its beginning is the BigBang and its ending is the Apocalypse. So all interval are contained in this one.

This interval contains all known Instant objects except the Apocalypse, as the end instant is not included in an interval. (The Apocalypse cannot belong to any interval).

It can be used with headSet() or tailSet(). For example:

        Interval allBefore = WHOLE_TIME.headSet(limit);

Represents an Interval which contains all Instants strictly before limit.

And another example:

        Interval allAfter = WHOLE_TIME.tailSet(limit);

Represents an Interval which contains all Instants after limit, including limit.

See Also:

Instant.BIG_BANG, Instant.APOCALYPSE

Constructor Detail

Interval

public Interval(Instant start,
                Instant end)

Create a new Interval.

Parameters:

start - the starting instant of the new interval

end - the ending instant of the new interval

Throws:

java.lang.NullPointerException - if end or start are null

java.lang.IllegalArgumentException - if the ending instant is before the starting instant.

Method Detail

getDuration

public long getDuration()

Compute the duration in milliseconds of the Interval. If the duration is bigger than Long.MAX_VALUE, return Long.MAX_VALUE (which happens for WHOLE_TIME for example).

Returns:

the duration in milliseconds of the Interval

See Also:

WHOLE_TIME

toString

public java.lang.String toString()

Convert the interval in a String.

Overrides:

toString in class java.lang.Object

Returns:

the String describing the interval.

equals

public boolean equals(java.lang.Object obj)

Compare two interval for equality. The result is true if and only if the argument is not null and is a Interval object that represents the same Interval, as this object.

Specified by:

equals in interface java.util.Collection<Instant>

Specified by:

equals in interface java.util.Set<Instant>

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with.

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for this object.

Specified by:

hashCode in interface java.util.Collection<Instant>

Specified by:

hashCode in interface java.util.Set<Instant>

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(Interval otherInterval)

Compare two interval chronogically.

The order is the same as the one used by COMPARATOR_BY_STARTING_THEN_ENDING. The interval are sorted by their starting instant first, then by their ending instant.

Specified by:

compareTo in interface java.lang.Comparable<Interval>

Parameters:

otherInterval - the instant to be compared.

Returns:

the value 0 if the argument interval is equal to this interval; a value less than 0 if this interval is before the interval argument; and a value greater than 0 if this interval is after than the interval argument.

Throws:

java.lang.NullPointerException - if otherInterval is null.

See Also:

COMPARATOR_BY_STARTING_THEN_ENDING

last

public Instant last()

Returns the last (highest) Instant currently in this Interval.

If the interval is not empty, it differs from 1 milliseconds from the instant returned by getEnd(), as the Instant returned by last() belongs to this interval and the Instant returned by getEnd() does not.

Specified by:

last in interface java.util.SortedSet<Instant>

Throws:

java.util.NoSuchElementException - if the interval is empty.

See Also:

getEnd()

first

public Instant first()

Returns the first (lowest) Instant currently in this Interval.

If the interval is not empty, it is the same instant as the one returned by the getStart() method.

Specified by:

first in interface java.util.SortedSet<Instant>

Throws:

java.util.NoSuchElementException - if the interval is empty.

See Also:

getStart()

size

public int size()

Return the number of Instant in this Interval.

As Instant are millisecond accurate, an Interval can contain a lot of Instant. If the Interval is larger than about 24 days, it will contains more than Integer.MAX_VALUE elements, so this method will return Integer.MAX_VALUE, as specified in Collection interface.

Since future implementations of Instant may be more accurate than millisecond, the value returned by this method may be even larger in the future. Please considere the usage of getDuration() instead.

Specified by:

size in interface java.util.Collection<Instant>

Specified by:

size in interface java.util.Set<Instant>

Returns:

the number of Instants in this interval, or Integer.MAX_VALUE.

See Also:

getDuration()

iterator

public java.util.Iterator<Instant> iterator()

Returns an iterator over the instants in this interval. The instants are returned in chronological order.

Specified by:

iterator in interface java.lang.Iterable<Instant>

Specified by:

iterator in interface java.util.Collection<Instant>

Specified by:

iterator in interface java.util.Set<Instant>

Returns:

an iterator over the instants in this interval.

tailSet

public Interval tailSet(Instant fromInstant)

Return a new interval that contains all instants of this interval greater than or equals to fromInstant.

Specified by:

tailSet in interface java.util.SortedSet<Instant>

Parameters:

fromInstant - starting instant (inclusive) of the new interval.

Returns:

new interval that contains all instants of this interval greater than or equals to fromInstant.

Throws:

java.lang.NullPointerException - if fromInstant is null.

java.lang.IllegalArgumentException - if fromInstant is not in the interval.

headSet

public Interval headSet(Instant toInstant)

Return a new interval that contains all instants of this interval strictly less than toInstant.

Specified by:

headSet in interface java.util.SortedSet<Instant>

Parameters:

toInstant - ending instant (exclusive) of the new interval.

Returns:

new interval that contains all instants of this interval strictly less than toInstant.

Throws:

java.lang.NullPointerException - if toInstant is null.

java.lang.IllegalArgumentException - if toInstant is not in the interval.

subSet

public Interval subSet(Instant fromInstant,
                       Instant toInstant)

Return a new interval that contains all instants of this interval greater than or equals to fromInstant and strictly less than toInstant.

Specified by:

subSet in interface java.util.SortedSet<Instant>

Parameters:

fromInstant - starting instant (inclusive) of the new interval.

toInstant - ending instant (exclusive) of the new interval.

Returns:

a new subinterval of this interval

Throws:

java.lang.NullPointerException - if fromInstant or toInstant are null.

java.lang.IllegalArgumentException - if fromInstant or toInstant are not in the interval.

java.lang.IllegalArgumentException - if toInstant is greater than fromInstant.

comparator

public java.util.Comparator<? super Instant> comparator()

Returns null, as Interval uses the natural order of Instant.

Specified by:

comparator in interface java.util.SortedSet<Instant>

getStart

public Instant getStart()

Return the starting instant of this interval. This method is almost the same as the first() method, except that even if the interval is empty (which means that the starting and ending instants are the same), this method will return the starting instant.

See Also:

first()

getEnd

public Instant getEnd()

Return the ending instant of this interval. This method is almost the same as the last() method, with two exception:

• if the interval is not empty, the following test :

    getEnding().millisBetween(last())==1L

  is always true,
• if the interval is empty, (which means that the starting and ending instants are the same), this method will return the ending instant.

See Also:

last()

clear

public void clear()

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

clear in interface java.util.Collection<Instant>

Specified by:

clear in interface java.util.Set<Instant>

removeAll

public boolean removeAll(java.util.Collection<?> c)

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

removeAll in interface java.util.Collection<Instant>

Specified by:

removeAll in interface java.util.Set<Instant>

retainAll

public boolean retainAll(java.util.Collection<?> c)

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

retainAll in interface java.util.Collection<Instant>

Specified by:

retainAll in interface java.util.Set<Instant>

addAll

public boolean addAll(java.util.Collection<? extends Instant> c)

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

addAll in interface java.util.Collection<Instant>

Specified by:

addAll in interface java.util.Set<Instant>

remove

public boolean remove(java.lang.Object o)

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

remove in interface java.util.Collection<Instant>

Specified by:

remove in interface java.util.Set<Instant>

add

public boolean add(Instant o)

As Interval are immutable, throws a UnsupportedOperationException.

Specified by:

add in interface java.util.Collection<Instant>

Specified by:

add in interface java.util.Set<Instant>

toArray

public <T> T[] toArray(T[] a)

Returns an array containing all of the instants in this interval.

As the interval may contain a lot of instants, the returned array may be very big, so this method should be used very carefully.

Specified by:

toArray in interface java.util.Collection<Instant>

Specified by:

toArray in interface java.util.Set<Instant>

Returns:

an array containing the instants of this interval.

Throws:

java.lang.OutOfMemoryError - if the interval is too big.

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the instants in this interval. Obeys the general contract of the Collection.toArray method.

As the interval may contain a lot of instants, the returned array may be very big, so this method should be used very carefully.

Specified by:

toArray in interface java.util.Collection<Instant>

Specified by:

toArray in interface java.util.Set<Instant>

Returns:

an array containing the instants of this interval.

Throws:

java.lang.OutOfMemoryError - if the interval is too big.

containsAll

public boolean containsAll(java.util.Collection<?> c)

Returns true if this set contains all of the elements of the specified collection.

• If the specified collection is an Interval object, this method returns true if it is a subintervall of this interval. The method is in this case executed in constant time
• If the specified collection is a set, this method returns true if it is a subset of this interval.

Specified by:

containsAll in interface java.util.Collection<Instant>

Specified by:

containsAll in interface java.util.Set<Instant>

Parameters:

c - collection to be checked for containment in this interval.

Returns:

true if this interval contains all of the elements of the specified collection.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.NullPointerException - if c contains one or more null elements.

java.lang.ClassCastException - if c contains one or more elements that are not Instant.

contains

public boolean contains(java.lang.Object obj)

Returns true if this set contains the specified Instant.

• If obj is null, a NullPointerException is thrown.
• If obj is not an Instant, a ClassCastException is thrown.
• If obj is an Instant which occurs after the starting instant of the interval (not strictly) and before the ending instant (strictly), return true. Return false otherwise.

Specified by:

contains in interface java.util.Collection<Instant>

Specified by:

contains in interface java.util.Set<Instant>

Throws:

java.lang.NullPointerException - if obj is null.

java.lang.ClassCastException - if obj is not an Instant.

isEmpty

public boolean isEmpty()

Test if the Interval is empty (has a duration of 0L).

Specified by:

isEmpty in interface java.util.Collection<Instant>

Specified by:

isEmpty in interface java.util.Set<Instant>

Returns:

true if the duration is 0L.

getIntersection

public Interval getIntersection(Interval otherInterval)

Return the intersection between this interval and another interval. More formally, return the larger interval that are contained by both this interval and the other interval.
Return null if there is no intersection, ie the two intervals do not intersect at all.
If the ending of an interval is the starting of the other, return an interval that have a duration of 0.

Returns:

the intersection or null is there is no intersection.

Throws:

java.lang.NullPointerException - if otherInterval is null.