net.time4j.engine

Interface ElementRule<T,V>

Type Parameters:

T - generic type of time context compatible to ChronoEntity

V - generic type of elment value

public interface ElementRule<T,V>

Represents the rule of a chronological element how to calculate or to manipulate its context-dependent temporal value.

Element rules will be searched by Time4J according to following criteria:

1. An element rule will be registered in the Chronology together with its associated chronological element. For each chronology and each element instance there is exactly one rule instance. In most cases it is an inner class of the temporal type in question.
2. If there is no registered rule for an element in a given chronology then Time4J checks if the associated element is a BasicElement and if the element supports the chronology. If yes then its internal rule will be evaluated.
3. As last resort Time4J checks if there is any other chronology which is compatible to Calendrical and contains the element in question as registered element. In this case the current chronology must also be compatible to Calendrical. If yes then Time4J will generate an element rule which automatically converts between both chronologies.
4. If the search did not yield any result then a RuleNotFoundException will be thrown.

Author:

Meno Hochschild, Meno Hochschild

See Also:

Chronology.Builder.appendElement(ChronoElement,ElementRule), BasicElement.derive(Chronology)

Method Summary

Methods

Modifier and Type	Method and Description
ChronoElement<?>	getChildAtCeiling(T context) Yields the child element whose value is to be set to the maximum value.
ChronoElement<?>	getChildAtFloor(T context) Yields the child element whose value is to be set to the minimum value.
V	getMaximum(T context) Yields the maximum value suitable for given chronological context.
V	getMinimum(T context) Yields the minimum value suitable for given chronological context.
V	getValue(T context) Yields the current value of associated element in given chronological context.
boolean	isValid(T context, V value) Queries if given value is valid for the element associated with this rule in given context.
T	withValue(T context, V value, boolean lenient) Determines the new value of the associated element in given chronological context and yields the result.

Method Detail

getValue

V getValue(T context)

Yields the current value of associated element in given chronological context.

Will be called by ChronoEntity.get(ChronoElement).

If the element associated with this rule is a primary element which directly represents a part of the state of an entity then any implementation will request the value directly from the state, otherwise derive from context using a specific logic. The term primary refers to if the context itself stores the value.

Parameters:

context - time context to be evaluated

Returns:

current element value as object (never null)

getMinimum

V getMinimum(T context)

Yields the minimum value suitable for given chronological context.

Will be called by ChronoEntity.getMinimum(ChronoElement).

ATTENTION: Defining a minimum and maximum does not imply a continuum between minimum and maximum without any gaps, see for example summer time switches or hebrew leap months. Furthermore, a chronologically ascending order cannot be guaranteed.

Parameters:

context - time context to be evaluated

Returns:

minimum legal and sometimes context-dependent value

See Also:

getMaximum(T)

getMaximum

V getMaximum(T context)

Yields the maximum value suitable for given chronological context.

Will be called by ChronoEntity.getMaximum(ChronoElement).

ATTENTION: Defining a minimum and maximum does not imply a continuum between minimum and maximum without any gaps, see for example summer time switches or hebrew leap months. Furthermore, a chronologically ascending order cannot be guaranteed.

Parameters:

context - time context to be evaluated

Returns:

maximum legal and sometimes context-dependent value

See Also:

getMinimum(T)

isValid

boolean isValid(T context,
              V value)

Queries if given value is valid for the element associated with this rule in given context.

Will be called by ChronoEntity.isValid(ChronoElement, V). A numerical overflow causing an ArithmeticException will usually not be checked.

Parameters:

context - time context to be evaluated

value - candidate value to be validated (optional)

Returns:

true if valid else false

withValue

T withValue(T context,
          V value,
          boolean lenient)

Determines the new value of the associated element in given chronological context and yields the result.

Will be called by ChronoEntity.with(ChronoElement, V). The third parameter is in most cases only relevant if the value type is no enum type but for example an integer type. The lenient mode causes the tolerant interpretation of invalid values like 31st of April as 1st of May. This mode is only active if an element is either explicitly declared as lenient or if the method AdvancedElement.setLenient() is used.

Parameters:

context - time context to be evaluated

value - new element value (optional)

lenient - leniency mode

Returns:

changed copy of context which itself remains unaffected

Throws:

IllegalArgumentException - if given value is out of range or not valid dependent on the given time context

ArithmeticException - in case of numerical overflow

See Also:

isValid(T, V), AdvancedElement.setLenient(Comparable, Class), ChronoElement.isLenient(), ProportionalElement.setLenient(Number)

getChildAtFloor

ChronoElement<?> getChildAtFloor(T context)

Yields the child element whose value is to be set to the minimum value.

The access to this method only happens indirectly in the class AdvancedElement.

Parameters:

context - time context to be evaluated

Returns:

child element or null if not available

See Also:

AdvancedElement.atFloor(Class)

getChildAtCeiling

ChronoElement<?> getChildAtCeiling(T context)

Yields the child element whose value is to be set to the maximum value.

The access to this method only happens indirectly in the class AdvancedElement.

Parameters:

context - time context to be evaluated

Returns:

child element or null if not available

See Also:

AdvancedElement.atCeiling(Class)