Class DateTimeFieldRule<T>
- java.lang.Object
-
- javax.time.calendar.CalendricalRule<T>
-
- javax.time.calendar.DateTimeFieldRule<T>
-
- Type Parameters:
T
- the underlying type representing the data, typically aCalendrical
,Number
orEnum
, must be immutable, should be comparable
- All Implemented Interfaces:
Serializable
,Comparable<CalendricalRule<?>>
,Comparator<Calendrical>
public abstract class DateTimeFieldRule<T> extends CalendricalRule<T>
The rule defining how a measurable field of time operates.Rule implementations define how a field like day-of-month operates. This includes the field name and minimum/maximum values.
DateTimeFieldRule is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable subclasses must be final, immutable and thread-safe and must ensure serialization works correctly.
- Author:
- Michael Nascimento Santos, Stephen Colebourne
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
DateTimeFieldRule.TextStore
The mapping between integer values and textual representations.
-
Constructor Summary
Constructors Modifier Constructor Description protected
DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue)
Constructor.protected
DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue, boolean hasText)
Constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description int
checkValue(int value)
Checks if the value is invalid and throws an exception if it is.int
checkValue(long value)
Checks if the value is invalid and throws an exception if it is.int
convertFractionToInt(BigDecimal fraction)
Converts a fraction from 0 to 1 for this field to a value.BigDecimal
convertIntToFraction(int value)
Converts a value for this field to a fraction between 0 and 1.T
convertIntToValue(int value)
Converts theint
to a typed value of the rule.int
convertValueToInt(T value)
Converts the typed value of the rule to theint
equivalent.protected void
createTextStores(EnumMap<DateTimeFormatterBuilder.TextStyle,DateTimeFieldRule.TextStore> textStores, Locale locale)
Creates the text store for each style for the specified locale.int
getInt(Calendrical calendrical)
Gets theint
value of this field from the specified calendrical throwing an exception if the value cannot be returned.Integer
getInteger(Calendrical calendrical)
Gets theInteger
value of this field from the specified calendrical returningnull
if the value cannot be returned.int
getLargestMinimumValue()
Gets the largest possible minimum value that the field can take.int
getMaximumValue()
Gets the maximum value that the field can take.int
getMaximumValue(Calendrical calendrical)
Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.int
getMinimumValue()
Gets the minimum value that the field can take.int
getMinimumValue(Calendrical calendrical)
Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.int
getSmallestMaximumValue()
Gets the smallest possible maximum value that the field can take.String
getText(int value, Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
Gets the text for this field.DateTimeFieldRule.TextStore
getTextStore(Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
Gets the text map for this field with the specified locale and style.boolean
isFixedValueSet()
Is the set of values, from the minimum value to the maximum, a fixed set, or does it vary according to other fields.boolean
isValidValue(int value)
Checks if the value is valid or invalid for this field.boolean
isValidValue(long value)
Checks if the value is valid or invalid for this field.-
Methods inherited from class javax.time.calendar.CalendricalRule
compare, compareTo, derive, deriveValueFor, deriveValueFrom, equals, getChronology, getID, getName, getPeriodRange, getPeriodUnit, getReifiedType, getValue, getValueChecked, hashCode, interpret, merge, reify, toString
-
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface java.util.Comparator
reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
-
-
-
-
Constructor Detail
-
DateTimeFieldRule
protected DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue)
Constructor.- Parameters:
reifiedClass
- the reified class, not nullchronology
- the chronology, not nullname
- the name of the type, not nullperiodUnit
- the period unit, not nullperiodRange
- the period range, not nullminimumValue
- the minimum valuemaximumValue
- the minimum value
-
DateTimeFieldRule
protected DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue, boolean hasText)
Constructor.- Parameters:
reifiedClass
- the reified class, not nullchronology
- the chronology, not nullname
- the name of the type, not nullperiodUnit
- the period unit, not nullperiodRange
- the period range, not nullminimumValue
- the minimum valuemaximumValue
- the minimum valuehasText
- true if this field has a text representation
-
-
Method Detail
-
getInteger
public final Integer getInteger(Calendrical calendrical)
Gets theInteger
value of this field from the specified calendrical returningnull
if the value cannot be returned.This uses
CalendricalRule.getValue(Calendrical)
to find the value and then converts it to anInteger
.- Parameters:
calendrical
- the calendrical to get the field value from, not null- Returns:
- the value of the field, null if unable to extract the field
-
getInt
public final int getInt(Calendrical calendrical)
Gets theint
value of this field from the specified calendrical throwing an exception if the value cannot be returned.This uses
CalendricalRule.getValue(Calendrical)
to find the value and then converts it to anint
ensuring it isn'tnull
.- Parameters:
calendrical
- the calendrical to get the field value from, not null- Returns:
- the value of the field, never null
- Throws:
UnsupportedRuleException
- if the field cannot be extracted
-
convertValueToInt
public int convertValueToInt(T value)
Converts the typed value of the rule to theint
equivalent.This default implementation handles
Integer
andEnum
. When the reified type is another type, this method must be overridden.- Parameters:
value
- the value to convert, not null- Returns:
- the int value of the field
- Throws:
ClassCastException
- if the value cannot be converted
-
convertIntToValue
public T convertIntToValue(int value)
Converts theint
to a typed value of the rule.The
int
will be checked to ensure that it is within the valid range of values for the field.This default implementation handles
Integer
andEnum
. When the reified type is another type, this method must be overridden.- Parameters:
value
- the value to convert, not null- Returns:
- the int value of the field
- Throws:
IllegalCalendarFieldValueException
- if the value is invalidClassCastException
- if the value cannot be converted
-
isValidValue
public boolean isValidValue(int value)
Checks if the value is valid or invalid for this field.This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.
This method performs the same check as
isValidValue(long)
.- Parameters:
value
- the value to check- Returns:
- true if the value is valid, false if invalid
-
isValidValue
public boolean isValidValue(long value)
Checks if the value is valid or invalid for this field.This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.
This method performs the same check as
isValidValue(int)
.- Parameters:
value
- the value to check- Returns:
- true if the value is valid, false if invalid
-
checkValue
public int checkValue(int value)
Checks if the value is invalid and throws an exception if it is.This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.
This method performs the same check as
checkValue(long)
. The implementation usesisValidValue(int)
.- Parameters:
value
- the value to check- Returns:
- the value
- Throws:
IllegalCalendarFieldValueException
- if the value is invalid
-
checkValue
public int checkValue(long value)
Checks if the value is invalid and throws an exception if it is.This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.
This method performs the same check as
checkValue(int)
. The implementation usesisValidValue(long)
.- Parameters:
value
- the value to check- Returns:
- the value cast to an int
- Throws:
IllegalCalendarFieldValueException
- if the value is invalid
-
isFixedValueSet
public boolean isFixedValueSet()
Is the set of values, from the minimum value to the maximum, a fixed set, or does it vary according to other fields.- Returns:
- true if the set of values is fixed
-
getMinimumValue
public int getMinimumValue()
Gets the minimum value that the field can take.- Returns:
- the minimum value for this field
-
getLargestMinimumValue
public int getLargestMinimumValue()
Gets the largest possible minimum value that the field can take.The default implementation returns
getMinimumValue()
. Subclasses must override this as necessary.- Returns:
- the largest possible minimum value for this field
-
getMinimumValue
public int getMinimumValue(Calendrical calendrical)
Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.The result of this method may still be inaccurate, if there is insufficient information in the calendrical.
The default implementation returns
getMinimumValue()
. Subclasses must override this as necessary.- Parameters:
calendrical
- context calendrical, not null- Returns:
- the minimum value of the field given the context
-
getMaximumValue
public int getMaximumValue()
Gets the maximum value that the field can take.- Returns:
- the maximum value for this field
-
getSmallestMaximumValue
public int getSmallestMaximumValue()
Gets the smallest possible maximum value that the field can take.The default implementation returns
getMaximumValue()
. Subclasses must override this as necessary.- Returns:
- the smallest possible maximum value for this field
-
getMaximumValue
public int getMaximumValue(Calendrical calendrical)
Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.The result of this method will still be inaccurate if there is insufficient information in the calendrical.
For example, if this field is the ISO day-of-month field, then the number of days in the month varies depending on the month and year. If both the month and year can be derived from the calendrical, then the maximum value returned will be accurate. Otherwise the 'best guess' value from
getMaximumValue()
will be returned.The default implementation returns
getMaximumValue()
. Subclasses must override this as necessary.- Parameters:
calendrical
- context calendrical, not null- Returns:
- the minimum value of the field given the context
-
getText
public String getText(int value, Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
Gets the text for this field.Some fields have a textual representation, such as day-of-week or month-of-year. This method provides a convenient way to convert a value to such a textual representation. More control is available using
getTextStore(java.util.Locale, javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle)
.If there is no textual mapping, then the value is returned as per
Integer.toString()
. Note that this is different to what occurs in printing /parsing, where a more advanced localized conversion from int to String is used.- Parameters:
value
- the value to convert to text, not nulllocale
- the locale to use, not nulltextStyle
- the text style, not null- Returns:
- the text of the field, never null
-
getTextStore
public DateTimeFieldRule.TextStore getTextStore(Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
Gets the text map for this field with the specified locale and style.Some fields have a textual representation, such as day-of-week or month-of-year. The text store provides details of those textual representations.
To supply text, subclasses should pass true in the constructor and override
createTextStores(java.util.EnumMap<javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle, javax.time.calendar.DateTimeFieldRule.TextStore>, java.util.Locale)
. This method is not normally overridden.- Parameters:
locale
- the locale to use, not nulltextStyle
- the text style, not null- Returns:
- the text cache, null if no text available
-
createTextStores
protected void createTextStores(EnumMap<DateTimeFormatterBuilder.TextStyle,DateTimeFieldRule.TextStore> textStores, Locale locale)
Creates the text store for each style for the specified locale.It is intended that a new copy of the text store should be created in response to calling this method as the result is cached by
getTextStore(java.util.Locale, javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle)
.- Parameters:
textStores
- the map to populate with TextStore instances, not nulllocale
- the locale to use, not null
-
convertIntToFraction
public BigDecimal convertIntToFraction(int value)
Converts a value for this field to a fraction between 0 and 1.The fractional value is between 0 (inclusive) and 1 (exclusive). It can only be returned if
isFixedValueSet()
returns true and thegetMinimumValue()
returns zero. The fraction is obtained by calculation from the field range using 9 decimal places and a rounding mode ofFLOOR
.For example, the second-of-minute value of 15 would be returned as 0.25, assuming the standard definition of 60 seconds in a minute.
- Parameters:
value
- the value to convert, valid for this field- Returns:
- the fractional value of the field
- Throws:
UnsupportedRuleException
- if the value cannot be convertedIllegalCalendarFieldValueException
- if the value is invalid
-
convertFractionToInt
public int convertFractionToInt(BigDecimal fraction)
Converts a fraction from 0 to 1 for this field to a value.The fractional value must be between 0 (inclusive) and 1 (exclusive). It can only be returned if
isFixedValueSet()
returns true and thegetMinimumValue()
returns zero. The value is obtained by calculation from the field range and a rounding mode ofFLOOR
.For example, the fractional second-of-minute of 0.25 would be converted to 15, assuming the standard definition of 60 seconds in a minute.
- Parameters:
fraction
- the fraction to convert, not null- Returns:
- the value of the field, checked for validity
- Throws:
UnsupportedRuleException
- if the value cannot be convertedIllegalCalendarFieldValueException
- if the value is invalid
-
-