com.davisor.data
Class CalendarFields

java.lang.Object
  com.davisor.data.CalendarFields

All Implemented Interfaces:

java.util.Collection, java.util.Set, java.util.SortedSet

public class CalendarFields

extends java.lang.Object

implements java.util.SortedSet

CalendarFields is an calendar arithmetic utility class that itself represents a range of calendar fields, sorted in their order of significance. Calendar fields provides also a set of usefull static calendar field related operations.

Each calendar field has a limited ranges of legal values. These ranges depend on other calendar field values. The order in which calendar fields are processes is therefore significant. When an operation applies to several fiels, the methods in this class always start processing from the less significant fields, and then continue to the more significant fields.

When calendar field values are added together, the field absolute minimum value is considered to be the zero value that will have no effect in the operatoin.

When field values are rounded up or down to an even multiple of a a field value, the field values are treated as ordinary integer values to which the rounding applies standard arithmetic operations. However, if the result is outside the range of legal field values, the value is replaced with the nearest legal value. In particular, rounding under- or overflows will not affect other field values.

Rounding calendar field values may sometimes give unexpected results. In particular, take two calendar values that define the upper and lower bounds of a calendar time pediod. If these limit values are rounded intependently to a given time field precision, the resulting range may not become an even multiple of that same precision.

Since:

JDK1.2

See Also:

add(java.lang.Object), iterator(), sub(java.util.Calendar, java.util.Calendar)

Nested Class Summary

class

CalendarFields.FieldIterator FieldIterator implements a calendar field iterator.

Field Summary

static int	DAY The index of ordered days (of month) field (4).
static int	ERA The index of ordered eras field (7).
static int	FIELD Calendar field code array index (0).
protected static java.lang.Integer[][]	FIELDS Calender fields in their order of significance.
static int	FIRSTDATECODE The index of first date code (4, the index of DAY_OF_MONTH).
static int	HOUR The index of ordered hours (of day) field (3).
protected int	M_first The index of first calendar field range element (inclusive).
protected int	M_last The index of last calendar field range element (inclusive).
static int	MILLISECOND The index of ordered milliseconds field (0).
static int	MINUTE The index of ordered minutes field (2).
static int	MONTH The index of ordered months field (5).
static int	SECOND The index of ordered seconds field (1).
static int	VALUE Calendar field value array index (1).
static int	YEAR The index of ordered years field (6).

Constructor Summary

CalendarFields()
Creates a calendar field set that covers all fields.

CalendarFields(java.util.Calendar calendar)
Creates a calendar field set from given calendar.

CalendarFields(int last)
Creates a calendar field set from MILLISECOND to the given last field.

CalendarFields(int first, int last)
Creates a calendar field set from the given first field to the given last field.

Method Summary

static boolean	add(java.util.Calendar calendar, java.util.Calendar term) Modifies given calendar by adding the values of another calendar to it.
boolean	add(java.lang.Object o) Ensures that this collection contains the specified element.
boolean	addAll(java.util.Collection c) Adds all of the elements in the specified collection to this collection.
static boolean	ceil(java.util.Calendar calendar, java.util.Calendar precision) Modifies given calendar by rounding it upwards to given precision.
static boolean	ceil(java.util.Calendar calendar, CalendarField precision) Modifies given calendar by rounding one of it's fields upwards to given precision.
void	clear() Clears the field range.
java.util.Comparator	comparator() Returns the comparator associated with this sorted set, or null if it uses its elements' natural ordering.
boolean	contains(java.lang.Object o) Tests whether the current field range contains the given field.
boolean	containsAll(java.util.Collection c) Tests if the current field range contains all of the given fields.
static java.util.Date	dateValue(java.lang.String stringValue, java.text.ParsePosition status, java.text.Format format) Parses given date string value.
boolean	equals(java.lang.Object o) Tests if this object is equal to another object.
static java.lang.Integer	fieldCode(int fieldIndex) Converts the field index to a Calendar field code.
static int	fieldIndex(int fieldCode) Converts Calendar field code to a field code.
static int[]	fieldValue(java.lang.String value, java.text.ParsePosition status) Parses given date field string value.
java.lang.Object	first() Returns the first (lowest) element currently in this sorted set.
static boolean	floor(java.util.Calendar calendar, java.util.Calendar precision) Modifies given calendar by rounding it downwards to given precision.
static boolean	floor(java.util.Calendar calendar, CalendarField precision) Modifies given calendar by rounding one of it's fields downwards to given precision.
int	getFirst() Gets range first field.
static int	getFirst(java.util.Calendar calendar) Gets the index of the least significant calender field which describes a time period shorter than the time set into given calendar.
int	getLast() Gets range last field.
static int	getLast(java.util.Calendar calendar) Gets the index of the most significant calender field which describes a time period shorter than the time set into given calendar.
static java.lang.String	getPattern(int field) Gets SimpleDateFormat pattern string for given Calendar field.
int	hashCode() Returns a hash code value for the object.
java.util.SortedSet	headSet(java.lang.Object toElement) Returns a view of the portion of this sorted set whose elements are strictly less than given element.
boolean	isDate() Tests if the current field range covers only fields that express dates, and not time of day.
boolean	isEmpty() Tests if the current field range is empty.
boolean	isTime() Tests if the current field range covers only fields that express time of day, and not dates.
boolean	isTimestamp() Tests if the current field range covers fields that express both time of day and dates.
java.util.Iterator	iterator() Gets the field iterator.
java.util.Iterator	iterator(boolean forward) Gets the field iterator, with given iteration direction.
java.lang.Object	last() Returns the last (highest) element currently in this sorted set.
static int	next(int fieldCode) Gets the next more significant field of given field.
static int	prev(int fieldCode) Gets the next less significant field of given field.
boolean	remove(java.lang.Object o) Removes a single instance of the specified element from this collection, if it is present.
boolean	removeAll(java.util.Collection c) Removes all this collection's elements that are also contained in the specified collection.
boolean	retainAll(java.util.Collection c) Retains only the elements in this collection that are contained in the specified collection.
int	size() Tells the number of fields in the current field range.
static java.lang.String	stringValue(java.util.Calendar calendar) Gets calendar value string representation.
static java.lang.String	stringValue(java.util.Calendar calendar, int field) Gets calendar field value string representation.
static boolean	sub(java.util.Calendar calendar, java.util.Calendar term) Modifies given calendar by substracting the values of another calendar from it.
java.util.SortedSet	subSet(java.lang.Object fromElement, java.lang.Object toElement) Returns a view of the portion of this sorted set whose elements range between given inclusive and exclusive lower and upper values.
java.util.SortedSet	tailSet(java.lang.Object fromElement) Returns a view of the portion of this sorted set whose elements are greater or euqal than given element.
java.lang.Object[]	toArray() Converts the current field range into an array of integers.
java.lang.Object[]	toArray(java.lang.Object[] a) Converts the current field range into an array of integers.

Methods inherited from class java.lang.Object

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

Field Detail

FIELD

public static final int FIELD

Calendar field code array index (0).

See Also:

Constant Field Values

VALUE

public static final int VALUE

Calendar field value array index (1).

See Also:

Constant Field Values

FIRSTDATECODE

public static final int FIRSTDATECODE

The index of first date code (4, the index of DAY_OF_MONTH).

See Also:

Constant Field Values

MILLISECOND

public static final int MILLISECOND

The index of ordered milliseconds field (0).

See Also:

Constant Field Values

SECOND

public static final int SECOND

The index of ordered seconds field (1).

See Also:

Constant Field Values

MINUTE

public static final int MINUTE

The index of ordered minutes field (2).

See Also:

Constant Field Values

HOUR

public static final int HOUR

The index of ordered hours (of day) field (3).

See Also:

Constant Field Values

DAY

public static final int DAY

The index of ordered days (of month) field (4).

See Also:

Constant Field Values

MONTH

public static final int MONTH

The index of ordered months field (5).

See Also:

Constant Field Values

YEAR

public static final int YEAR

The index of ordered years field (6).

See Also:

Constant Field Values

ERA

public static final int ERA

The index of ordered eras field (7).

See Also:

Constant Field Values

FIELDS

protected static final java.lang.Integer[][] FIELDS

Calender fields in their order of significance. The first index enumerates the principal fields:

• MILLISECOND
• SECOND
• MINUTE
• HOUR_OF_DAY
• DAY_OF_MONTH
• MONTH
• YEAR
• ERA

The first element in second index gives the principal field code, Following elemensts, if any, enumerate secondary fields related to the principal field.

• MILLISECOND: none
• SECOND: none
• MINUTE: none
• HOUR_OF_DAY: HOUR, AM_PM
• DAY_OF_MONTH: DAY_OF_WEEK_IN_MONTH, DAY_OF_WEEK, DAY_OF_YEAR, WEEK_OF_MONTH, WEEK_OF_YEAR
• MONTH: none
• YEAR: none
• ERA: none

M_first

protected int M_first

The index of first calendar field range element (inclusive).

M_last

protected int M_last

The index of last calendar field range element (inclusive).

Constructor Detail

CalendarFields

public CalendarFields()

Creates a calendar field set that covers all fields.

CalendarFields

public CalendarFields(int last)

Creates a calendar field set from MILLISECOND to the given last field.

Parameters:

last - last time field included (a Calendar time field code)

See Also:

fieldIndex(int)

CalendarFields

public CalendarFields(int first,
                      int last)

Creates a calendar field set from the given first field to the given last field.

Parameters:

first - first time field included (a Calendar time field code)

last - last time field included (a Calendar time field code)

See Also:

fieldIndex(int)

CalendarFields

public CalendarFields(java.util.Calendar calendar)

Creates a calendar field set from given calendar. The resulting calender field range will cover all fields the given time difference would direcly change if added to an another calendar value.

For example, for a Gregorian calendar and GMT time zone, a value of 86400000 milliseconds (24h * 60min * 60s * 1000ms) that represents one Gregorian day would affect directly the day field only, and result a range of [day,day]. A value of 86401000 milliseconds (a day and a second), would result a range of [second,day].

Parameters:

calendar - calendar value

See Also:

getFirst(Calendar), getLast(Calendar)

Method Detail

add

public boolean add(java.lang.Object o)

Ensures that this collection contains the specified element. The object is assumed to be instance of CalendarFields.

Specified by:

add in interface java.util.Set

Parameters:

o - element whose presence in this collection is to be ensured

Returns:

true if this collection changed as a result of the call

Throws:

java.lang.ClassCastException - if the object is not an instance of CalendarFields

addAll

public boolean addAll(java.util.Collection c)

Adds all of the elements in the specified collection to this collection.

Specified by:

addAll in interface java.util.Set

Parameters:

c - elements to be inserted into this collection

Returns:

true if this collection changed as a result of the call

Throws:

java.lang.ClassCastException - if the object is not an instance of CalendarFields

See Also:

add(Object)

clear

public void clear()

Clears the field range.

Specified by:

clear in interface java.util.Set

contains

public boolean contains(java.lang.Object o)

Tests whether the current field range contains the given field.

Specified by:

contains in interface java.util.Set

Parameters:

o - the field to be tested, expressed as a Number

Returns:

false.

containsAll

public boolean containsAll(java.util.Collection c)

Tests if the current field range contains all of the given fields.

Specified by:

containsAll in interface java.util.Set

Parameters:

c - collection of fields, expressed as Number instances.

Returns:

false.

See Also:

contains(java.lang.Object)

isEmpty

public boolean isEmpty()

Tests if the current field range is empty.

Specified by:

isEmpty in interface java.util.Set

iterator

public java.util.Iterator iterator()

Gets the field iterator.

Specified by:

iterator in interface java.util.Set

remove

public boolean remove(java.lang.Object o)

Removes a single instance of the specified element from this collection, if it is present.

Specified by:

remove in interface java.util.Set

Throws:

java.lang.UnsupportedOperationException - always

removeAll

public boolean removeAll(java.util.Collection c)

Removes all this collection's elements that are also contained in the specified collection.

Specified by:

removeAll in interface java.util.Set

Throws:

java.lang.UnsupportedOperationException - always

retainAll

public boolean retainAll(java.util.Collection c)

Retains only the elements in this collection that are contained in the specified collection.

Specified by:

retainAll in interface java.util.Set

Throws:

java.lang.UnsupportedOperationException - always

size

public int size()

Tells the number of fields in the current field range.

Specified by:

size in interface java.util.Set

toArray

public java.lang.Object[] toArray()

Converts the current field range into an array of integers.

Specified by:

toArray in interface java.util.Set

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)

Converts the current field range into an array of integers.

Specified by:

toArray in interface java.util.Set

equals

public boolean equals(java.lang.Object o)

Tests if this object is equal to another object.

CalendarField objects are equal if they share the same field range.

Specified by:

equals in interface java.util.Set

hashCode

public int hashCode()

Returns a hash code value for the object.

Specified by:

hashCode in interface java.util.Set

add

public static boolean add(java.util.Calendar calendar,
                          java.util.Calendar term)

Modifies given calendar by adding the values of another calendar to it. Only fields that are set in the term calendar are added. Furhermore, field values are compencated by their actual minimum values, so that adding a minimum value will have no effect.

calendar.fieldValue += term.fieldValue - term.actualMinimumFieldValue

Parameters:

calendar - calendar to add to (modified)

term - calendar to add from

Returns:

true if calendar was modified

ceil

public static boolean ceil(java.util.Calendar calendar,
                           java.util.Calendar precision)

Modifies given calendar by rounding it upwards to given precision. Each field in given calendar is rounded up to even multiply of corresponding precision field value. No value will however exceed field spesific maximum legal value. Unset fields in either calendar will cause that field to be skipped.

Parameters:

calendar - calendar to round upwards (modified)

precision - calendar field precisions

Returns:

true if calendar was modified

See Also:

ceil(Calendar,CalendarField), floor(Calendar,Calendar), floor(Calendar,CalendarField)

ceil

public static boolean ceil(java.util.Calendar calendar,
                           CalendarField precision)

Modifies given calendar by rounding one of it's fields upwards to given precision. Rounding up works by first rounding the calendar down with the help of floor(Calendar,CalendarField) method. If this modifies the calendar, the value is rounded up by adding given field value to the rounded down value. If the rounding down did not modify the calendar value, the value was already at even precision boundary, and it therefore does not need to be rounded up, either.

Parameters:

calendar - calendar to round upwards (modified)

precision - calendar field to round off againts

Returns:

true if calendar was modified

See Also:

ceil(Calendar,Calendar), floor(Calendar,Calendar), floor(Calendar,CalendarField)

dateValue

public static java.util.Date dateValue(java.lang.String stringValue,
                                       java.text.ParsePosition status,
                                       java.text.Format format)
                                throws InvalidDataException

Parses given date string value. The value is first assumed to contain one of the known special time period keywords, possible prepended with a multiplier and a single white space character. If this fails, parsing is attempted with given formatter, if any. If formatter is not available, Java default SQL timestamp, date, and time formats are tried. null or empty string values result a null date value.

Parameters:

stringValue - data string value (may be null)

status - parse status (may be null)

format - date string parser (may be null)

Returns:

date value corresponding to given value (may be null)

Throws:

InvalidDataException - if value can not be interpreted as a date

fieldCode

public static java.lang.Integer fieldCode(int fieldIndex)

Converts the field index to a Calendar field code.

See Also:

fieldIndex(int)

fieldIndex

public static int fieldIndex(int fieldCode)

Converts Calendar field code to a field code.

See Also:

fieldCode(int)

fieldValue

public static int[] fieldValue(java.lang.String value,
                               java.text.ParsePosition status)
                        throws InvalidDataException

Parses given date field string value. The value is assumed to contain one of the known special time period keywords, possible prepended with a multiplier and a single whitespace character.

Parameters:

value - data string value

status - parse status (may be null)

Returns:

field code and value

Throws:

InvalidDataException - if value can not be interpreted as a date

floor

public static boolean floor(java.util.Calendar calendar,
                            java.util.Calendar precision)

Modifies given calendar by rounding it downwards to given precision. Each field in given calendar is rounded down to even multiply of corresponding precision field value. Unset fields in either calendar will cause that field to be skipped.

Parameters:

calendar - calendar to round downwards (modified)

precision - calendar field precisions

Returns:

true if calendar was modified

See Also:

ceil(Calendar,Calendar), ceil(Calendar,CalendarField), floor(Calendar,CalendarField)

floor

public static boolean floor(java.util.Calendar calendar,
                            CalendarField precision)

Modifies given calendar by rounding one of it's fields downwards to given precision. Rounding works by first clearing all calendar fields up to and not including the given field. The given field is then rounded down to even multiply of given calendar field precision value.

If the rounded down value would be less or more than the actual minimum or maximum field value, the minimum or maximum value is used instead.

Clearing calendar fields is tricky business, as Calendars tend to run back to default values whenever there is even the least possible excuse to try to interprete incomplete or conflicting calendar settings. In particular, in order for the rounding down to work propertly, all fields related to a given time unit must always be cleared as a one unit operation. In practice, calendars may therefore be rounded down to the principal field values only. Calendar principal fields are enumerated by FIELDS constant.

Parameters:

calendar - calendar to round downwards (modified)

precision - calendar field to round off againts

Returns:

true if calendar was modified

See Also:

ceil(Calendar,Calendar), ceil(Calendar,CalendarField), fieldCode(int), fieldIndex(int), floor(Calendar,Calendar)

getFirst

public int getFirst()

Gets range first field.

See Also:

getFirst(Calendar), getLast()

getFirst

public static int getFirst(java.util.Calendar calendar)

Gets the index of the least significant calender field which describes a time period shorter than the time set into given calendar. The search is made by iterating through calendar fields in their order of significance, starting from the least significant field, and returning the first field that has a value not equal to the actual minimum value of that field.

For example, if the calendar has been set to a time of the first day of the first month in the second year, the index of the YEAR field is returned. If the time would have been the second hour of that same day, the index of the HOUR field would have been returned.

If all fields are at their minimum values, the index of the MILLISECONDS field is returned (zero).

Parameters:

calendar - calendar to examine

Returns:

the index of calendar field range first field

See Also:

getFirst(), getLast(Calendar)

getLast

public int getLast()

Gets range last field.

See Also:

getFirst(), getLast(Calendar)

getLast

public static int getLast(java.util.Calendar calendar)

Gets the index of the most significant calender field which describes a time period shorter than the time set into given calendar. The search is made by iterating through calendar fields in their order of significance, starting from the most significant field, and returning the first field that has a value not equal to the actual minimum value of that field.

For example, if the calendar has been set to a time of the second day of the first month in the first year, the index of the DAY field is returned. If the time would have been the second day of the second year, the index of the YEAR field would have been returned.

If all fields are at their minimum values, the index of the MILLISECONDS field is returned (zero).

Parameters:

calendar - calendar to examine

Returns:

the index of calendar field range last field

See Also:

getFirst(Calendar), getLast()

getPattern

public static java.lang.String getPattern(int field)

Gets SimpleDateFormat pattern string for given Calendar field.

Parameters:

field - Calendar field code

Returns:

corresponding SimpleDateFormat pattern, or an empty string

isDate

public boolean isDate()

Tests if the current field range covers only fields that express dates, and not time of day.

See Also:

isTime(), isTimestamp()

isTime

public boolean isTime()

Tests if the current field range covers only fields that express time of day, and not dates.

See Also:

isDate(), isTimestamp()

isTimestamp

public boolean isTimestamp()

Tests if the current field range covers fields that express both time of day and dates.

See Also:

isDate(), isTime()

iterator

public java.util.Iterator iterator(boolean forward)

Gets the field iterator, with given iteration direction.

next

public static int next(int fieldCode)

Gets the next more significant field of given field.

See Also:

prev(int), fieldIndex(int), fieldCode(int)

prev

public static int prev(int fieldCode)

Gets the next less significant field of given field.

See Also:

next(int), fieldIndex(int), fieldCode(int)

stringValue

public static java.lang.String stringValue(java.util.Calendar calendar)

Gets calendar value string representation.

Parameters:

calendar - calendar value

See Also:

stringValue(Calendar,int)

stringValue

public static java.lang.String stringValue(java.util.Calendar calendar,
                                           int field)

Gets calendar field value string representation. This consists of field value and field pattern, concatenated togeter. However, if field value is zero, the result will be an empty string.

Parameters:

calendar - calendar value

field - calendar field code

See Also:

stringValue(Calendar)

sub

public static boolean sub(java.util.Calendar calendar,
                          java.util.Calendar term)

Modifies given calendar by substracting the values of another calendar from it. Only fields that are set in the term calendar are substracted. Furhermore, field values are compencated by their actual minimum values, so that substracting a minimum value will have no effect.

calendar.fieldValue -= term.fieldValue - term.actualMinimumFieldValue

Parameters:

calendar - calendar to add to (modified)

term - calendar to add from

Returns:

true if calendar was modified

comparator

public java.util.Comparator comparator()

Returns the comparator associated with this sorted set, or null if it uses its elements' natural ordering.

Specified by:

comparator in interface java.util.SortedSet

Returns:

null

first

public java.lang.Object first()

Returns the first (lowest) element currently in this sorted set.

Specified by:

first in interface java.util.SortedSet

See Also:

getFirst()

headSet

public java.util.SortedSet headSet(java.lang.Object toElement)

Returns a view of the portion of this sorted set whose elements are strictly less than given element.

This method is currently unimplemented.

Specified by:

headSet in interface java.util.SortedSet

last

public java.lang.Object last()

Returns the last (highest) element currently in this sorted set.

Specified by:

last in interface java.util.SortedSet

See Also:

getLast()

subSet

public java.util.SortedSet subSet(java.lang.Object fromElement,
                                  java.lang.Object toElement)

Returns a view of the portion of this sorted set whose elements range between given inclusive and exclusive lower and upper values.

This method is currently unimplemented.

Specified by:

subSet in interface java.util.SortedSet

tailSet

public java.util.SortedSet tailSet(java.lang.Object fromElement)

Returns a view of the portion of this sorted set whose elements are greater or euqal than given element.

This method is currently unimplemented.

Specified by:

tailSet in interface java.util.SortedSet