time
Class TimeField<V>

java.lang.Object
  time.TimeField<V>

All Implemented Interfaces:

java.lang.Comparable<TimeField<V>>, java.util.Comparator<V>

public final class TimeField<V>
extends java.lang.Object
implements java.lang.Comparable<TimeField<V>>, java.util.Comparator<V>

Implements a field used in time representation.

A TimeField can be used by one or several different Chronologies. For example, Julian and Gregorian chronologies will likely share the same TimeFields. But Chinese chronology will have its own TimeField, although it may use the same TimeField for hour, minutes, second and millisecond.

TimeField objects are provided by Chronologies, and the end user should not create new ones.

A TimeField can have several values. Thoses value are defined with the TimeField itself, at TimeField creation. For example,

• for Month : JANUARY, FEBRUARY, MARCH [...], DECEMBER
• for Hour : 0, 1, [...], 23

The TimeField object defines also an order for its possible values, and that's why it implements Comparable<V>. There are two options:

• Either a java.util.Comparator is provided at TimeField creation, and this Comparator is used to achieve comparaisons between values.
• Or no specific java.util.Comparator is used, and the natural order of values are used to achieve comparaisons. (so values must implement Comparable in this case).

TimeField have a typical duration which is exprimed in milliseconds. The typical duration of a TimeField is the mean, or the most common duration of this TimeField. More formaly, this typical duration is the variation of time implied by the minimal change of this TimeField values.

Here some examples of typical duration:

• for Month: 30 days [2 592 000 000 milliseconds] (some month last 31 days, some 30 days, some 28 or even 29), so 30 days is a good typical duration.
• for Hour : 3 600 000 milliseconds, as an hour lasts 3600 seconds.
• for Days : 24 hours [86 400 000 milliseconds], as almost everyday lasts 24 hours, except with Day Light Saving, where some days last 23 hours, and some 25 hours.

The typical duration is only used for sorting the TimeFields together. TimeField have indeed a natural order.

TimeField are first compared by their typical duration. The greater the typical duration, the smaller the TimeField. So a TimeField like Month is before a TimeField like Days, which is before Hour. This allows to sort TimeFields with most significant TimeFields in first position. Two TimeFields objects with the same typical duration are sorted lexicographically using their name. It is suggested that a Chronology does not provide such TimeFields with the same typical duration.

As equals() method is not redefined, the natural order is not consistent with equals(): two TimeField defined by two different chronologies with the same name and duration will be equals according to compareTo() but not according to equals(). This should not be a problem as such TimeField should not be used together in the same TimeMask.

Author:

Arnaud Roques

See Also:

TimeMask, Chronology

Constructor Summary

TimeField(java.lang.String name, long typicalDuration, java.util.Collection<V> possibleValues, java.util.Comparator<V> comparator)
Create a new TimeField.

Method Summary

int	compare(V o1, V o2) Compare two possibles values of a TimeField according to this TimeField rule.
int	compareTo(TimeField other) Compare this TimeField with another one.
java.lang.String	getName() Return the name of this TimeField.
boolean	isValueOk(V value) Test if a value is acceptable for this TimeField.
java.lang.String	toString() Convert this TimeField into a String.
java.util.SortedSet<V>	values() Return all possible values of this TimeField.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

equals

Constructor Detail

TimeField

public TimeField(java.lang.String name,
                 long typicalDuration,
                 java.util.Collection<V> possibleValues,
                 java.util.Comparator<V> comparator)

Create a new TimeField.
End user should not create new TimeField. This constructor is provided for new Chronology implementations.

If values of this TimeField object are not Comparable, the order of the possibleValues collection is used to achieve comparaisons between values. (this collections is assumed ordered by ascending order).

The provided possibleValues set should not be changed after TimeField creation (with add or remove methods for example), as this implementation keeps a reference to this set for testing future acceptable values.

Parameters:

name - the name of the new TimeField

typicalDuration - the typical duration in millisecond of the new TimeField

possibleValues - all possible values of the new TimeField

comparator - null if the natural order of possibleValues is used, otherwise a comparator that defines the order for possibleValues.

Throws:

java.lang.NullPointerException - if name is null

java.lang.IllegalArgumentException - if possibleValues is empty.

See Also:

isValueOk(V)

Method Detail

compareTo

public int compareTo(TimeField other)

Compare this TimeField with another one. The most significant TimeField is sorted first.

Specified by:

compareTo in interface java.lang.Comparable<TimeField<V>>

Returns:

0 if this TimeField has the same typical duration and name than the other TimeField; a value less than 0 if this TimeField is more significant than the other TimeField (ie has a higher typical duration), or if it has the same typical duration, but a name lexicographically smaller; a value greater than 0 if this TimeField is less significant than the other TimeField (ie has a lower typical duration), or if it has the same typical duration, but a name lexicographically greater;

Throws:

java.lang.NullPointerException - if other is null.

getName

public java.lang.String getName()

Return the name of this TimeField. The name was specified at TimeField creation.

Returns:

the name of this TimeField

values

public java.util.SortedSet<V> values()

Return all possible values of this TimeField.

Returns:

all possible values of this TimeField.

isValueOk

public boolean isValueOk(V value)

Test if a value is acceptable for this TimeField.

The value is acceptable if is contained in the possible value set provided at TimeField creation.

Returns:

true if value is acceptable for this TimeField; false otherwise.

Throws:

java.lang.NullPointerException - if value is null.

toString

public java.lang.String toString()

Convert this TimeField into a String.

Overrides:

toString in class java.lang.Object

Returns:

a String describing the TimeField

compare

public int compare(V o1,
                   V o2)

Compare two possibles values of a TimeField according to this TimeField rule.

If the values are Comparable if no Comparator have been provided at TimeField creation, the natural order of the values is used.

Otherwise, the Comparator provided at TimeField creation is used.

Specified by:

compare in interface java.util.Comparator<V>

Returns:

the result

Throws:

java.lang.IllegalArgumentException - if o1 or o2 is not a legal value for this TimeField object.

java.lang.ClassCastException - if values are not Comparable and no Comparator have been provided