javax.time.calendrical
Interface DateTimeField

All Superinterfaces:

java.util.Comparator<CalendricalObject>

All Known Implementing Classes:

ChronoDateField, JulianDayField, LocalDateField, LocalTimeField, QuarterYearField

public interface DateTimeField
extends java.util.Comparator<CalendricalObject>

A field of date/time.

A date, as expressed by LocalDateTime, is broken down into a number of fields, such as year, month, day-of-month, hour, minute and second. Implementations of this interface represent those fields. The fields include their own calculations which are specific to one calendar system.

Implementation notes

This interface must be implemented with care to ensure other classes operate correctly. All implementations that can be instantiated must be final, immutable and thread-safe. It is recommended to use an enum where possible.

Method Summary

int	compare(CalendricalObject calendrical1, CalendricalObject calendrical2) Compares the value of this field in two calendricals.
long	get(LocalDate date) Gets the value of the associated field.
long	get(LocalDateTime dateTime) Gets the value of the associated field.
long	get(LocalTime time) Gets the value of the associated field.
PeriodUnit	getBaseUnit() Gets the unit that the field is measured in.
java.lang.String	getName() Gets a descriptive name for the field.
PeriodUnit	getRangeUnit() Gets the range that the field is bound by.
long	getValueFrom(CalendricalObject calendrical) Gets the value of the field from the specified calendrical.
DateTimeValueRange	getValueRange() Gets the range of valid values for the field.
DateTimeValueRange	range(LocalDate date) Gets the range of valid values for the associated field.
DateTimeValueRange	range(LocalDateTime dateTime) Gets the range of valid values for the associated field.
DateTimeValueRange	range(LocalTime time) Gets the range of valid values for the associated field.
boolean	resolve(DateTimeBuilder builder, long value) Resolves the date/time information in the builder
LocalDate	roll(LocalDate date, long roll) Rolls the value of the associated field in the result.
LocalDateTime	roll(LocalDateTime dateTime, long roll) Rolls the value of the associated field in the result.
LocalTime	roll(LocalTime time, long roll) Rolls the value of the associated field in the result.
LocalDate	set(LocalDate date, long newValue) Sets the value of the associated field in the result.
LocalDateTime	set(LocalDateTime dateTime, long newValue) Sets the value of the associated field in the result.
LocalTime	set(LocalTime time, long newValue) Sets the value of the associated field in the result.

Methods inherited from interface java.util.Comparator

equals

Method Detail

getName

java.lang.String getName()

Gets a descriptive name for the field.

The should be of the format 'BaseOfRange', such as 'MonthOfYear', unless the field is unbounded, such as 'Year' or 'Era', when only the base unit is mentioned.

Returns:

the name, not null

getValueRange

DateTimeValueRange getValueRange()

Gets the range of valid values for the field.

All fields can be expressed as a long integer. This method returns an object that describes the valid range for that value.

Note that the result only describes the minimum and maximum valid values and it is important not to read too much into them. For example, there could be values within the range that are invalid for the field.

Returns:

the range of valid values for the field, not null

getBaseUnit

PeriodUnit getBaseUnit()

Gets the unit that the field is measured in.

The unit of the field is the period that varies within the range. For example, in the field 'MonthOfYear', the unit is 'Months'. See also getRangeUnit().

Returns:

the period unit defining the base unit of the field, not null

getRangeUnit

PeriodUnit getRangeUnit()

Gets the range that the field is bound by.

The range of the field is the period that the field varies within. For example, in the field 'MonthOfYear', the range is 'Years'. See also getBaseUnit().

The range is never null. For example, the 'Year' field is shorthand for 'YearOfForever'. It therefore has a unit of 'Years' and a range of 'Forever'.

Returns:

the period unit defining the range of the field, not null

getValueFrom

long getValueFrom(CalendricalObject calendrical)

Gets the value of the field from the specified calendrical.

The value will be within the valid range for the field.

Parameters:

calendrical - the calendrical object, not null

Returns:

the value of the field

Throws:

CalendricalException - if unable to get the field

CalendricalException - if the field value is invalid

compare

int compare(CalendricalObject calendrical1,
            CalendricalObject calendrical2)

Compares the value of this field in two calendricals.

All fields implement Comparator on CalendricalObject. This allows a list of calendricals to be compared using the value of a field. For example, you could sort a list of arbitrary calendricals by the value of the month-of-year field - Collections.sort(list, MONTH_OF_YEAR)

Specified by:

compare in interface java.util.Comparator<CalendricalObject>

Parameters:

calendrical1 - the first calendrical to compare, not null

calendrical2 - the second calendrical to compare, not null

Throws:

CalendricalException - if unable to obtain the value for this field

range

DateTimeValueRange range(LocalDate date)

Gets the range of valid values for the associated field.

All fields can be expressed as a long integer. This method returns an object that describes the valid range for that value.

The date-time object is used to provide context to refine the valid value range.

Parameters:

date - the context date object, not null

Returns:

the range of valid values for the associated field, not null

range

DateTimeValueRange range(LocalTime time)

Gets the range of valid values for the associated field.

All fields can be expressed as a long integer. This method returns an object that describes the valid range for that value.

The time object is used to provide context to refine the valid value range.

Parameters:

time - the context time object, not null

Returns:

the range of valid values for the associated field, not null

range

DateTimeValueRange range(LocalDateTime dateTime)

Gets the range of valid values for the associated field.

All fields can be expressed as a long integer. This method returns an object that describes the valid range for that value.

The date-time object is used to provide context to refine the valid value range.

Parameters:

dateTime - the context date-time object, not null

Returns:

the range of valid values for the associated field, not null

get

long get(LocalDate date)

Gets the value of the associated field.

The value of the associated field is expressed as a long integer and is extracted from the specified date-time object.

Parameters:

date - the date object to query, not null

Returns:

the value of the associated field, not null

get

long get(LocalTime time)

Gets the value of the associated field.

The value of the associated field is expressed as a long integer and is extracted from the specified date-time object.

Parameters:

time - the time object to query, not null

Returns:

the value of the associated field, not null

get

long get(LocalDateTime dateTime)

Gets the value of the associated field.

The value of the associated field is expressed as a long integer and is extracted from the specified date-time object.

Parameters:

dateTime - the date-time object to query, not null

Returns:

the value of the associated field, not null

set

LocalDate set(LocalDate date,
              long newValue)

Sets the value of the associated field in the result.

The new value of the associated field is expressed as a long integer. The result will be adjusted to set the value of the associated field.

Parameters:

date - the date-time object to adjust, not null

newValue - the new value of the field

Returns:

the adjusted date object, not null

Throws:

CalendricalException - if the value is invalid

set

LocalTime set(LocalTime time,
              long newValue)

Sets the value of the associated field in the result.

The new value of the associated field is expressed as a long integer. The result will be adjusted to set the value of the associated field.

Parameters:

time - the date-time object to adjust, not null

newValue - the new value of the field

Returns:

the adjusted time object, not null

Throws:

CalendricalException - if the value is invalid

set

LocalDateTime set(LocalDateTime dateTime,
                  long newValue)

Sets the value of the associated field in the result.

The new value of the associated field is expressed as a long integer. The result will be adjusted to set the value of the associated field.

Parameters:

dateTime - the date-time object to adjust, not null

newValue - the new value of the field

Returns:

the adjusted date-time object, not null

Throws:

CalendricalException - if the value is invalid

roll

LocalDate roll(LocalDate date,
               long roll)

Rolls the value of the associated field in the result.

The result will have the associated field rolled by the amount specified.

Parameters:

date - the date object to adjust, not null

roll - the amount to roll by

Returns:

the adjusted date object, not null

roll

LocalTime roll(LocalTime time,
               long roll)

Rolls the value of the associated field in the result.

The result will have the associated field rolled by the amount specified.

Parameters:

time - the time object to adjust, not null

roll - the amount to roll by

Returns:

the adjusted time object, not null

roll

LocalDateTime roll(LocalDateTime dateTime,
                   long roll)

Rolls the value of the associated field in the result.

The result will have the associated field rolled by the amount specified.

Parameters:

dateTime - the date-time object to adjust, not null

roll - the amount to roll by

Returns:

the adjusted date-time object, not null

resolve

boolean resolve(DateTimeBuilder builder,
                long value)

Resolves the date/time information in the builder

This method is invoked during the resolve of the builder. Implementations should combine the associated field with others to form objects like LocalDate, LocalTime and LocalDateTime

Parameters:

builder - the builder to resolve, not null

value - the value of the associated field

Returns:

true if builder has been changed, false otherwise

Throws:

CalendricalException - if unable to resolve