time
Interface Chronology

All Known Implementing Classes:

GregorianChronology

public interface Chronology

This class represents a system used by humans to describe time.

A chronology provides several TimeField that have a meaning in this chronology. One can merge several TimeField to create TimeMask objects.

Those TimeMask objects define time format that can be used to describe a precise Time object.

If a Time object is well defined, it will describe a peace of time (for example, with a TimeMask with YEAR, MONTH and DAY). Such a Time object is said consistent for interval as it can be safely converted in an Interval object.

A Time object does not necessary have to be consistent for interval. For example, it is possible to define a Time object like "9 hour and 15 minutes". This Time object is not consistent for interval, because it does not define a precise day, just a time in a day. But it still can be usefull, as it may be used to build other Time objects. Indeed, you can combinate it with another Time object that only defines a day, and the combinaison of both gives a Time object that defines day and hour/minute.

Please note that having a good TimeMask is not sufficient for beeing consistent for interval. For example, a Time object which value is [31st February of 2006] is not consistent for interval.

If a Time object provide enough information to be millisecond accurate, it is said consistent for instant as it can be safely converted in an Instant object. Generally, being consistent for instant implies to be consistent for interval (which one millisecond interval duration).

A Chronology provides the following services:

• Methods to test Time object against consistence for instant and consistence for interval.
• Methods to make conversion between Time and Instant/Interval
• Methods that provided java.util.Collection views of this chronology.

Author:

Arnaud Roques

Method Summary

java.util.List<Time>	asList(Time startingTime, int startingPosition) Return a immutable view of some Time objects of this chronology starting at a specified Time.
java.util.List<Time>	asList(TimeMask mask) Return a immutable view of all Time objects of this chronology with a specified TimeMask.
java.util.SortedSet<Time>	asSortedSet(TimeMask mask) Return a immutable view of all Time objects of this chronology with a specified TimeMask.
Instant	getInstant(Time time) Convert a Time object into Instant according to this chronology object.
Interval	getInterval(Time time) Convert a Time object into an Interval object, according to this chronology.
Time	getTime(Instant instant) Convert an Instant object into a Time object with all known TimeField of this chronology.
Time	getTime(Instant instant, TimeMask mask) Convert an Instant object into a Time object with a precise TimeMask according to this chronology.
Time	getTime(Interval interval) Convert an Interval object into a Time object with all known TimeField of this chronology.
Time	getTime(Interval interval, TimeMask mask) Convert an Interval object into a Time object with a precise TimeMask according to this chronology.
boolean	isConsistentForInstant(Time time) Test if a Time object is consistent for instant.
boolean	isConsistentForInterval(Time time) Test if a Time object is consistent for interval.
java.util.SortedSet<TimeField>	knownFields() Return all TimeField of this chronology.
Time	next(Time time) Return the next Time object that directly follows a specified Time object according to this chronology.
Time	previous(Time time) Return the previous Time object that is just before a specified Time object according to this chronology.
java.util.SortedSet<Time>	split(Time timeToSplit, TimeField... fieldsToAdd) Return a immutable view with Time objects by adding some TimeField to an existing Time object.

Method Detail

knownFields

java.util.SortedSet<TimeField> knownFields()

Return all TimeField of this chronology.

All TimeMask and Time object used with this chronology should only use one or several of thoses TimeField objects, otherwise a ClassCastException will be thrown by the other methods of this chronology when such an unappropriate TimeField will be used.

Returns:

all TimeField of this chronology

isConsistentForInstant

boolean isConsistentForInstant(Time time)

Test if a Time object is consistent for instant.

A Time object is consistent for instant if it provides enough information to point a unique Instant in the whole Time.

Parameters:

time - the Time object to be tested.

Returns:

true if time is consistant for instant.

Throws:

java.lang.NullPointerException - if time is null

isConsistentForInterval

boolean isConsistentForInterval(Time time)

Test if a Time object is consistent for interval.

A Time object is consistent for interval, if it provides enough information to point a unique Interval in the whole Time (for example, a day, a week, a month...).

Parameters:

time - the Time object to be tested.

Returns:

true if time is consistant for interval.

Throws:

java.lang.NullPointerException - if time is null

getTime

Time getTime(Instant instant)

Convert an Instant object into a Time object with all known TimeField of this chronology.

Parameters:

instant - the Instant object to be converted.

Returns:

a Time object with all known TimeField of this chronology.

getTime

Time getTime(Instant instant,
             TimeMask mask)
             throws java.lang.ClassCastException

Convert an Instant object into a Time object with a precise TimeMask according to this chronology.

Calling this method should be equivalent as the following:

        getTime(instant).subMap(mask)
 

Parameters:

instant - the Instant object to be converted.

mask - the TimeMask to use.

Returns:

a Time object with mask as TimeMask.

Throws:

java.lang.ClassCastException - if mask is not compatible with this chronology.

java.lang.NullPointerException - if instant or mask is null

getTime

Time getTime(Interval interval)

Convert an Interval object into a Time object with all known TimeField of this chronology.

Parameters:

interval - the Interval object to be converted.

Returns:

a Time object with all known TimeField of this chronology.

Throws:

java.lang.IllegalArgumentException - if interval cannot be converted into a Time object according to this chronology.

java.lang.NullPointerException - if interval is null

getTime

Time getTime(Interval interval,
             TimeMask mask)
             throws java.lang.ClassCastException

Convert an Interval object into a Time object with a precise TimeMask according to this chronology.

Calling this method should be equivalent as the following:

        getTime(interval).subMap(mask)
 

Parameters:

interval - the Interval object to be converted.

mask - the TimeMask to use.

Returns:

a Time object with mask as TimeMask..

Throws:

java.lang.IllegalArgumentException - if interval cannot be converted into a Time object according to this chronology.

java.lang.ClassCastException - if mask is not compatible with this chronology.

java.lang.NullPointerException - if interval or mask is null

getInstant

Instant getInstant(Time time)
                   throws java.lang.ClassCastException

Convert a Time object into Instant according to this chronology object.

Parameters:

time - the Time object to be converted.

Returns:

Instant corresponding to the t object.

Throws:

java.lang.ClassCastException - if time does not have a TimeMask compatible with this Chronology object.

java.lang.IllegalArgumentException - if time is not consistent for instant.

java.lang.NullPointerException - if time is null

getInterval

Interval getInterval(Time time)
                     throws java.lang.ClassCastException

Convert a Time object into an Interval object, according to this chronology.

Parameters:

time - the Time object to be converted

Returns:

the Interval corresponding to t

Throws:

java.lang.ClassCastException - if time is not compatible with this chronology.

java.lang.IllegalArgumentException - if time is not consistent for interval.

java.lang.NullPointerException - if time is null

asSortedSet

java.util.SortedSet<Time> asSortedSet(TimeMask mask)

Return a immutable view of all Time objects of this chronology with a specified TimeMask. Such a view provides a bridge with Java Collections Framework.

For example, assuming that myTime is a Time object, calling:

        asSortedSet(myTime.getTimeMask()).contains(myTime)
 

returns true if myTime is consistent for interval.

Another example, assuming that dayMask is a TimeMask object like [YEAR, MONTH, DAY_OF_MONTH], and that day1 and day2 are two differents days, calling:

        asSortedSet(dayMask).subSet(day1, day2).size()
 

returns the number of days between day1 and day2 according to this chronology.

To have the day following day1, call:

        Iterator it = asSortedSet(day1.getTimeMask()).tailSet(day1).iterator();
        it.next(); // To skip day1
        return it.next()
 

To have the day before day1, call:

        asSortedSet(dayMask).headSet(day1).last()
 

Parameters:

mask - the specified TimeMask

Returns:

a immutable view of all Time objects of this chronology with a specified TimeMask.

Throws:

java.lang.NullPointerException - if mask is null

java.lang.ClassCastException - if mask is not compatible with this chronology

java.lang.IllegalArgumentException - if mask is not consistent with interval

asList

java.util.List<Time> asList(TimeMask mask)

Return a immutable view of all Time objects of this chronology with a specified TimeMask. Such a view provides a bridge with Java Collections Framework.

For example, assuming that myTime is a Time object, calling:

        asList(myTime.getTimeMask()).contains(myTime)
 

returns true if myTime is consistent for interval.

To have the 100th day following day1, call:

        int idx = asList(dayMask).indexOf(day1);
        asList(dayMask).get(idx+100);
 

Please note than unlike Set, a List cannot have more than Integer.MAX_VALUE. So some mask that would have define a too big list cannot be used with this method.

Parameters:

mask - the specified TimeMask

Returns:

a immutable view of all Time objects of this chronology with a specified TimeMask.

Throws:

java.lang.NullPointerException - if mask is null

java.lang.ClassCastException - if mask is not compatible with this chronology

java.lang.IllegalArgumentException - if mask is not consistent with interval

java.lang.IndexOutOfBoundsException - if the returned List would have more than Integer.MAX_VALUE elements.

asList

java.util.List<Time> asList(Time startingTime,
                            int startingPosition)

Return a immutable view of some Time objects of this chronology starting at a specified Time. Such a view provides a bridge with Java Collections Framework.

All Time objects of the returned list have the same TimeMask as startingTime. The first element of the list is startingTime if startingPosition=0. Otherwise, if startingPosition>0, it specifies the position of startingTime in the returned list. So we have:

        asList(myTime, x).get(x).equals(myTime)==true
 

If startingPosition<0, the returned list does not contains startingTime and starts with the (-startingPosition) Time objects that follows logically startingTime.

To sumurize, startingPosition is always the logically (even if it's negative) position of startingTime in the returned list.

To have the 100th day following day1, call:

        asList(day1, 0).get(100);
 

or:

        asList(day1, 100).get(0);
 

Please note than unlike Set, a List cannot have more than Integer.MAX_VALUE.

Parameters:

startingTime - an absolute reference for Time

startingPosition - the logical position of startingTime in the returned list

Returns:

a immutable view of some Time objects of this chronology.

Throws:

java.lang.NullPointerException - if startingTime is null

java.lang.ClassCastException - if startingTime is not compatible with this chronology

java.lang.IllegalArgumentException - if startingTime is not consistent with interval

java.lang.IndexOutOfBoundsException - if the returned List would have more than Integer.MAX_VALUE elements.

split

java.util.SortedSet<Time> split(Time timeToSplit,
                                TimeField... fieldsToAdd)

Return a immutable view with Time objects by adding some TimeField to an existing Time object.

The provided timeToSplit must be consistent for interval. The returned set is a view of timeToSplit as set of its component. For example:

• a year as a set of its months
• a year as a set of its weeks
• a month as a set of days
• a day is a set of hours
• ...

The returned set contains Time objects whose TimeMask is the time mask of timeToExplode merged with all fieldsToAdd. All possibles values are contained in the returned set.

For example, if one have:

        timeToSplit = new Time(DAY_MASK, 2005, Month.NOVEMBER, 11);
 

calling the following method:

        split(timeToSplit, HOUR, MINUTE);
 

return a set that contains all hours/minutes from 00:00 to 23:59.
[2005, NOVEMBER, 11, 0 , 0] ... [2005, NOVEMBER, 11, 0 , 59],
[2005, NOVEMBER, 11, 1 , 0] ... [2005, NOVEMBER, 11, 1 , 59],
[2005, NOVEMBER, 11, 2 , 0] ... [2005, NOVEMBER, 11, 2 , 59],
...
[2005, NOVEMBER, 11, 22 , 0] ... [2005, NOVEMBER, 11, 22 , 59],
[2005, NOVEMBER, 11, 23 , 0] ... [2005, NOVEMBER, 11, 23 , 59]


Another example, if you want to know the number of days in a month:

        Time myMonth = new Time(MONTH_MASK, 2005, Month.DECEMBER);
        int nbDays = myChronology.split(myMonth, DAY_OF_MONTH).size();
 

Parameters:

timeToSplit - the time to split.

fieldsToAdd - all TimeField to add.

Returns:

an immutable view of Time objects.

next

Time next(Time time)
          throws java.lang.IllegalArgumentException,
                 java.lang.ClassCastException

Return the next Time object that directly follows a specified Time object according to this chronology.

More formally, this method returns a Time object that have the same TimeMask than time, with the following property: the ending instant (according to this chronoloy) of time is the starting instant (according to this chronology) of the resulted Time object.

If no exception is thrown, the following test is always true:

        getInterval(time).getEnd().equals(next(time).getStart())
 

This is equivalent of the following call:

        Iterator it = asSortedSet(time.getTimeMask()).tailSet(time).iterator();
        it.next(); // To skip time
        return it.next()
 

Parameters:

time - the time whose next time is return

Returns:

the Time object that directly follows time.

Throws:

java.lang.ClassCastException - if time does not have a TimeMask compatible with this Chronology object.

java.lang.IllegalArgumentException - if time does not have a following Time.

previous

Time previous(Time time)
              throws java.lang.IllegalArgumentException,
                     java.lang.ClassCastException

Return the previous Time object that is just before a specified Time object according to this chronology.

More formally, this method returns a Time object that have the same TimeMask than time, with the following property: the starting instant (according to this chronoloy) of time is the ending instant (according to this chronology) of the resulted Time object.

If no exception is thrown, the following test is always true:

        getInterval(time).getStart().equals(previous(time).getEnd())
 

This is equivalent of the following call:

        asSortedSet(time.getTimeMask()).headSet(time).last()
 

Parameters:

time - the time whose previous time is return

Returns:

the Time object that is just before time.

Throws:

java.lang.ClassCastException - if time does not have a TimeMask compatible with this Chronology object.

java.lang.IllegalArgumentException - if time does not have a previous Time.