time
Class Time

java.lang.Object
  time.Time

All Implemented Interfaces:

java.lang.Comparable<Time>, java.util.Map<TimeField,java.lang.Object>, java.util.SortedMap<TimeField,java.lang.Object>

public final class Time
extends java.lang.Object
implements java.lang.Comparable<Time>, java.util.SortedMap<TimeField,java.lang.Object>

Time is a representation of a piece of time. This is the main class of this API. This class provides a good replacement for java.util.Date . But its usage is larger than simply a date, as it can represent thinks like:

• a normal date. Example: the 20th of October 2005
• a Year. Example: 2005
• a Month of Year . Example: December 2005
• a Week. Example: Week 47 of year 2005
• a Hour/Minutes: Example: 13:10

Indeed, Time are defined using a TimeMask which is the format of the time. The Time is just a map whose keys are the TimeField, so it implements SortedMap<TimeField, Object>.

It is possible to merge several Time objects in one. For example, you can have in one side Time objects that represents a day (like the 20th of October 2005). In one other side, Time objects that represents hour and minutes (for example 9:00). If you want to merge those two Time objects to speak about the 20th of October 2005 9:00, simply use the appropriate constructor.

This class is immutable, so it can itself be used as key in java.util.Map. It is also thread-safe.

Author:

Arnaud Roques

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

Time(java.util.Map<TimeField,java.lang.Object> map)
Create new Time from a map of TimeField.

Time(Time... otherTimes)
Create a new Time object by merging existing other Time objects.

Time(TimeMask mask, java.lang.Object... values)
Create a new Time from a TimeMask and some values.

Method Summary

void	clear() As TimeField are immutable, throws a UnsupportedOperationException.
java.util.Comparator<? super TimeField>	comparator() As the naturel order if TimeField is used, returns null.
int	compareTo(Time other) Compares this Time with the specified Time for order.
boolean	containsKey(java.lang.Object key) Returns true if this Time object contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this Time object maps one or more keys to the specified value.
java.util.Set<java.util.Map.Entry<TimeField,java.lang.Object>>	entrySet() Returns a set view of the mappings contained in this Time object.
boolean	equals(java.lang.Object o) Compare two Time for equality.
TimeField	firstKey() Return the most significant TimeField in this Time object.
java.lang.Object	get(java.lang.Object field) Return the value of a TimeField of this Time.
<V> V	get(TimeField<V> field) Return the value of a TimeField of this Time.
TimeMask	getTimeMask() Return the format of this Time object.
Time	headMap(TimeField toKey) Return a new Time object that contains all TimeField more significant than toKey (excluding).
boolean	isEmpty() Returns true if this Time object contains no key-value mappings.
java.util.Set<TimeField>	keySet() Returns a Set view of the keys contained in this Time object.
TimeField	lastKey() Return the less significant TimeField in this Time object.
java.lang.Comparable	put(TimeField key, java.lang.Object value) As TimeField are immutable, throws a UnsupportedOperationException.
void	putAll(java.util.Map<? extends TimeField,? extends java.lang.Object> t) As TimeField are immutable, throws a UnsupportedOperationException.
java.lang.Comparable	remove(java.lang.Object key) As TimeField are immutable, throws a UnsupportedOperationException.
boolean	sameTimeMask(Time other) Test if two Time objects use the same TimeMask.
boolean	sameTimeMask(TimeMask mask) Test if this Time object uses a certain TimeMask.
int	size() Return the number of TimeField in this Time object.
Time	subMap(java.util.Collection<TimeField> fields) Return a new Time object that contains only some TimeField of this Time object.
Time	subMap(TimeField fromKey, TimeField toKey) Return a new Time object that contains all TimeField less significant than fromKey (including) and more significant than toKey (excluding).
Time	tailMap(TimeField fromKey) Return a new Time object that contains all TimeField less significant than fromKey (including).
java.lang.String	toString() Convert this Time object in a string.
Time	update(TimeField field, java.lang.Object value) Create a new Time by updating or adding a new TimeField in this Time object.
java.util.Collection<java.lang.Object>	values() Returns a collection view of the values contained in this Time object.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

hashCode

Constructor Detail

Time

public Time(java.util.Map<TimeField,java.lang.Object> map)

Create new Time from a map of TimeField.

Parameters:

map - the map whose keys are TimeField and values the values of the TimeFields.

Time

public Time(TimeMask mask,
            java.lang.Object... values)

Create a new Time from a TimeMask and some values. This is the main constructor for Time. The order of values should be the same as the order in the mask.

Parameters:

mask - the TimeMask which defines the format

values - all values of the TimeFields contained in the TimeMask.

Throws:

java.lang.IllegalArgumentException - if mask and values do not have the same size.

java.lang.IllegalArgumentException - if a value is incompatible with the mask.

Time

public Time(Time... otherTimes)

Create a new Time object by merging existing other Time objects. The new Time objects contains all keys and values of all other Time objects.

Throws:

java.lang.IllegalArgumentException - if two or more Time objects has the same TimeField with different values.

Method Detail

getTimeMask

public TimeMask getTimeMask()

Return the format of this Time object.

Returns:

the TimeMask of this Time object.

get

public java.lang.Object get(java.lang.Object field)

Return the value of a TimeField of this Time.

You should consider the get(TimeField<V>) methods instead, as it avoid casting.

Specified by:

get in interface java.util.Map<TimeField,java.lang.Object>

Returns:

the value of the TimeField provided.

Throws:

java.lang.NullPointerException - if field is null.

java.lang.ClassCastException - if field is not a TimeField.

java.lang.IllegalArgumentException - if the field is not in this Time object keys'.

See Also:

get(TimeField)

get

public <V> V get(TimeField<V> field)

Return the value of a TimeField of this Time.

Returns:

the value of the TimeField provided.

Throws:

java.lang.NullPointerException - if field is null.

java.lang.IllegalArgumentException - if the field is not in this Time object keys'.

update

public Time update(TimeField field,
                   java.lang.Object value)

Create a new Time by updating or adding a new TimeField in this Time object.

Returns:

a new Time that contains all TimeField of this Time object and the field provided.

Throws:

java.lang.IllegalArgumentException - if value is not a valid value for field

compareTo

public int compareTo(Time other)

Compares this Time with the specified Time for order. The comparaison is made with the most significant TimeFields of each Time. If values of both the most significant TimeField of each Time are the same, the comparaison is made on the next most significant TimeField, until a difference is founded. If all TimeFields of each Time object have the same values, a zero is return (and this is consistent with equals).

Specified by:

compareTo in interface java.lang.Comparable<Time>

Returns:

a negative integer, zero, or a positive integer as this Time is less than, equal to, or greater than the specified Time.

Throws:

java.lang.IllegalArgumentException - if both Time objects do not have the same TimeMask.

equals

public boolean equals(java.lang.Object o)

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

Specified by:

equals in interface java.util.Map<TimeField,java.lang.Object>

Overrides:

equals in class java.lang.Object

Returns:

true if the objects are the same; false otherwise.

toString

public java.lang.String toString()

Convert this Time object in a string.

Overrides:

toString in class java.lang.Object

Returns:

a String describing this object.

sameTimeMask

public boolean sameTimeMask(TimeMask mask)

Test if this Time object uses a certain TimeMask.

Parameters:

mask - the TimeMask to be tested

Returns:

true if mask is the TimeMask of this Time object

sameTimeMask

public boolean sameTimeMask(Time other)

Test if two Time objects use the same TimeMask.

Parameters:

other - the Time to test with

Returns:

true if this Time object has the same TimeMask than other.

entrySet

public java.util.Set<java.util.Map.Entry<TimeField,java.lang.Object>> entrySet()

Returns a set view of the mappings contained in this Time object. The set's iterator returns the mappings in ascending key order. Each element in the returned set is a Map.Entry<TimeField, Object>.

This method is can be useful to test in an instant is part of another instant. Example:

        Time myMonth = new Time(MONTH_MASK, 2005, Month.DECEMBER);
        Time other = new Time(...);
        boolean test = other.entrySet().containsAll(myMonth.entrySet());
 

Specified by:

entrySet in interface java.util.Map<TimeField,java.lang.Object>

Returns:

a set view of the mappings contained in this Time object.

values

public java.util.Collection<java.lang.Object> values()

Returns a collection view of the values contained in this Time object.

The collection's iterator will return the values in the order that their corresponding keys appear in this Time object.

Specified by:

values in interface java.util.Map<TimeField,java.lang.Object>

Returns:

a collection view of the values contained in this Time object.

keySet

public java.util.Set<TimeField> keySet()

Returns a Set view of the keys contained in this Time object. The set's iterator will return the keys in ascending order.

Specified by:

keySet in interface java.util.Map<TimeField,java.lang.Object>

Returns:

a set view of the keys contained in this Time object.

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this Time object maps one or more keys to the specified value.

Specified by:

containsValue in interface java.util.Map<TimeField,java.lang.Object>

Returns:

true if this Time object maps one or more keys to the specified value.

Throws:

java.lang.NullPointerException - if value is null.

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this Time object contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map<TimeField,java.lang.Object>

Returns:

true if this Time object contains a mapping for the specified key.

Throws:

java.lang.NullPointerException - if value is null.

java.lang.ClassCastException - if value is not a TimeField.

isEmpty

public boolean isEmpty()

Returns true if this Time object contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map<TimeField,java.lang.Object>

Returns:

true if this Time object contains no key-value mappings.

size

public int size()

Return the number of TimeField in this Time object.

Specified by:

size in interface java.util.Map<TimeField,java.lang.Object>

Returns:

the number of TimeField in this Time object.

clear

public void clear()

As TimeField are immutable, throws a UnsupportedOperationException.

Specified by:

clear in interface java.util.Map<TimeField,java.lang.Object>

putAll

public void putAll(java.util.Map<? extends TimeField,? extends java.lang.Object> t)

As TimeField are immutable, throws a UnsupportedOperationException.

Specified by:

putAll in interface java.util.Map<TimeField,java.lang.Object>

remove

public java.lang.Comparable remove(java.lang.Object key)

As TimeField are immutable, throws a UnsupportedOperationException.

Specified by:

remove in interface java.util.Map<TimeField,java.lang.Object>

put

public java.lang.Comparable put(TimeField key,
                                java.lang.Object value)

As TimeField are immutable, throws a UnsupportedOperationException.

Specified by:

put in interface java.util.Map<TimeField,java.lang.Object>

lastKey

public TimeField lastKey()

Return the less significant TimeField in this Time object.

Specified by:

lastKey in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

the less significant TimeField in this Time object.

firstKey

public TimeField firstKey()

Return the most significant TimeField in this Time object.

Specified by:

firstKey in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

the most significant TimeField in this Time object.

comparator

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

As the naturel order if TimeField is used, returns null. TimeField are indeed sorted in this Time object.

Specified by:

comparator in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

null.

tailMap

public Time tailMap(TimeField fromKey)

Return a new Time object that contains all TimeField less significant than fromKey (including).

Specified by:

tailMap in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

a new Time object that contains all TimeField less significant than fromKey (including).

headMap

public Time headMap(TimeField toKey)

Return a new Time object that contains all TimeField more significant than toKey (excluding).

Specified by:

headMap in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

a new Time object that contains all TimeField more significant than toKey (excluding).

subMap

public Time subMap(TimeField fromKey,
                   TimeField toKey)

Return a new Time object that contains all TimeField less significant than fromKey (including) and more significant than toKey (excluding).

Specified by:

subMap in interface java.util.SortedMap<TimeField,java.lang.Object>

Returns:

a new Time object that contains all TimeField less significant than fromKey (including) and more significant than toKey (excluding).

subMap

public Time subMap(java.util.Collection<TimeField> fields)

Return a new Time object that contains only some TimeField of this Time object.

Parameters:

fields - the TimeField to be kept.

Returns:

a new Time object that contains only some TimeField