javax.time.calendar
Class CalendricalEngine

java.lang.Object
  extended by javax.time.calendar.CalendricalEngine

public final class CalendricalEngine
extends java.lang.Object

Main processing engine to merge and interpret calendrical information.

This stateful class is a tool for manipulating a set of calendrical information. The engine typically takes some calendrical information as input and derives other information from it. For example, a date can be derived from separate year, month and day fields.

This class is mutable and not thread-safe. It must only be used from a single thread and must not be passed between threads.

Author:
Stephen Colebourne

Method Summary
 void addError(java.lang.String error)
          Adds an error to those tracked by the normalizer.
<R> R
derive(CalendricalRule<R> ruleToDerive)
           
static
<R> R
derive(CalendricalRule<R> ruleToDerive, CalendricalRule<?> ruleOfData, Chronology chronology, DateTimeField field)
          Derives the specified rule from a the normalized set of objects.
static
<R> R
derive(CalendricalRule<R> ruleToDerive, CalendricalRule<?> ruleOfData, LocalDate date, LocalTime time, ZoneOffset offset, ZoneId zone, Chronology chronology, DateTimeFields fields)
          Derives the specified rule from a the normalized set of objects.
<R> R
deriveChecked(CalendricalRule<R> ruleToDerive)
           
 Chronology getChronology(boolean storeErrorIfNull)
          Gets the chronology.
 LocalDate getDate(boolean storeErrorIfNull)
          Gets the date.
 java.util.Set<java.lang.String> getErrors()
          Gets the modifiable list of errors that have occurred.
 DateTimeField getField(DateTimeRule rule, boolean storeErrorIfNull)
          Gets a field by rule.
 DateTimeField getFieldDerived(DateTimeRule ruleToDerive, boolean storeErrorIfNull)
          Gets a field by rule, deriving the value.
 java.util.List<Calendrical> getInput()
          The original input provided to the merger.
 ZoneOffset getOffset(boolean storeErrorIfNull)
          Gets the offset.
 CalendricalRule<?> getRule()
          The single rule that defines the data in this merger.
 LocalTime getTime(boolean storeErrorIfNull)
          Gets the time.
 ZoneId getZone(boolean storeErrorIfNull)
          Gets the zone.
static CalendricalEngine merge(Calendrical... calendricals)
          Derives the specified rule from a set of calendricals.
static CalendricalRule<CalendricalEngine> rule()
          Gets the rule for CalendricalEngine.
 void setChronology(Chronology chronology, boolean storeErrorIfClash)
          Sets the chronology.
 void setDate(LocalDate date, boolean storeErrorIfClash)
          Sets the date.
 void setField(DateTimeField field, boolean storeErrorIfClash)
          Sets the specified field.
 void setOffset(ZoneOffset offset, boolean storeErrorIfClash)
          Sets the offset.
 void setTime(LocalTime time, boolean storeErrorIfClash)
          Sets the time.
 void setZone(ZoneId zone, boolean storeErrorIfClash)
          Sets the zone.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

rule

public static CalendricalRule<CalendricalEngine> rule()
Gets the rule for CalendricalEngine.

Returns:
the rule for the engine, not null

merge

public static CalendricalEngine merge(Calendrical... calendricals)
Derives the specified rule from a set of calendricals.

This method is used to combine any number of calendrical objects into a more meaningful form. For example, a Year, MonthDay and LocalTime could be combined into a LocalDateTime.

The returned merger will contain the combined information of the input in a normalized form. Use derive(CalendricalRule) or deriveChecked(CalendricalRule) to derive the desired values or values.

If the input cannot be combined into any sensible normalized output then an exception is thrown. For example, passing in the month January and the date 2011-06-30 will fail as the months are in conflict.

Parameters:
calendricals - the calendricals to merge, not null, no nulls
Returns:
the normalized merger to query, not null
Throws:
CalendricalException - if the calendricals cannot be successfully merged

derive

public static <R> R derive(CalendricalRule<R> ruleToDerive,
                           CalendricalRule<?> ruleOfData,
                           LocalDate date,
                           LocalTime time,
                           ZoneOffset offset,
                           ZoneId zone,
                           Chronology chronology,
                           DateTimeFields fields)
Derives the specified rule from a the normalized set of objects.

This method is designed to be called from Calendrical.get(CalendricalRule). The class implementing the interface must call this method passing in parameters to fully describe the state of the object to be derived from. Avoid duplicating information between the date, time and fields if possible.

Type Parameters:
R - the type of the desired rule
Parameters:
ruleToDerive - the rule to derive, not null
ruleOfData - the rule of the data to derive from, may be null
date - the date to derive from, may be null
time - the time to derive from, may be null
offset - the zone offset to derive from, may be null
zone - the zone ID to derive from, may be null
chronology - the chronology to derive from, may be null
fields - the fields to derive from, may be null
Returns:
the derived value for the rule, null if unable to derive

derive

public static <R> R derive(CalendricalRule<R> ruleToDerive,
                           CalendricalRule<?> ruleOfData,
                           Chronology chronology,
                           DateTimeField field)
Derives the specified rule from a the normalized set of objects.

This method is designed to be called from Calendrical.get(CalendricalRule). The class implementing the interface must call this method passing in parameters to fully describe the state of the object to be derived from.

Type Parameters:
R - the type of the desired rule
Parameters:
ruleToDerive - the rule to derive, not null
ruleOfData - the rule of the data to derive from, may be null
chronology - the chronology to derive from, may be null
field - the field to derive from, not null
Returns:
the derived value for the rule, null if unable to derive

getInput

public java.util.List<Calendrical> getInput()
The original input provided to the merger.

Returns:
the unmodifiable original input, not null

getRule

public CalendricalRule<?> getRule()
The single rule that defines the data in this merger.

This will only be present if this merger is created from a single conceptual object as opposed to being merged.

Returns:
the rule of the data, may be null

getDate

public LocalDate getDate(boolean storeErrorIfNull)
Gets the date.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
storeErrorIfNull - true to store an error if the value is null
Returns:
the date, may be null

getTime

public LocalTime getTime(boolean storeErrorIfNull)
Gets the time.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
storeErrorIfNull - true to store an error if the value is null
Returns:
the date, may be null

getOffset

public ZoneOffset getOffset(boolean storeErrorIfNull)
Gets the offset.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
storeErrorIfNull - true to store an error if the value is null
Returns:
the date, may be null

getZone

public ZoneId getZone(boolean storeErrorIfNull)
Gets the zone.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
storeErrorIfNull - true to store an error if the value is null
Returns:
the date, may be null

getChronology

public Chronology getChronology(boolean storeErrorIfNull)
Gets the chronology.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
storeErrorIfNull - true to store an error if the value is null
Returns:
the date, may be null

getField

public DateTimeField getField(DateTimeRule rule,
                              boolean storeErrorIfNull)
Gets a field by rule.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
rule - the rule to retrieve, null returns null
Returns:
the field, may be null

getFieldDerived

public DateTimeField getFieldDerived(DateTimeRule ruleToDerive,
                                     boolean storeErrorIfNull)
Gets a field by rule, deriving the value.

The flag is set to true if the value is required and an error should be stored if it is not available. Note that the value is returned whether it is null or not and no exception is thrown.

Parameters:
ruleToDerive - the rule to retrieve, null returns null
Returns:
the field, may be null

setDate

public void setDate(LocalDate date,
                    boolean storeErrorIfClash)
Sets the date.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks.

Parameters:
date - the date to store, may be null
storeErrorIfClash - true to store an error if the date clashes with the stored value

setTime

public void setTime(LocalTime time,
                    boolean storeErrorIfClash)
Sets the time.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks.

Parameters:
time - the time to store, may be null
storeErrorIfClash - true to store an error if the time clashes with the stored value

setOffset

public void setOffset(ZoneOffset offset,
                      boolean storeErrorIfClash)
Sets the offset.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks.

Parameters:
offset - the offset to store, may be null
storeErrorIfClash - true to store an error if the offset clashes with the stored value

setZone

public void setZone(ZoneId zone,
                    boolean storeErrorIfClash)
Sets the zone.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks.

Parameters:
zone - the zone to store, may be null
storeErrorIfClash - true to store an error if the zone clashes with the stored value

setChronology

public void setChronology(Chronology chronology,
                          boolean storeErrorIfClash)
Sets the chronology.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks.

Parameters:
chronology - the chronology to store, may be null
storeErrorIfClash - true to store an error if the chronology clashes with the stored value

setField

public void setField(DateTimeField field,
                     boolean storeErrorIfClash)
Sets the specified field.

If the flag is true, then a check is performed to see if the specified object clashes with the stored object, storing an error if it does. If the flag is false, then the current value is overwritten without further checks. The flag should be set to true to cause the method to check if the value for the field clashes with an existing value. A false value simply overwrites any previous value.

Parameters:
field - the field to store, null ignored
storeErrorIfClash - true to store an error if the field clashes with an existing field

derive

public <R> R derive(CalendricalRule<R> ruleToDerive)

deriveChecked

public <R> R deriveChecked(CalendricalRule<R> ruleToDerive)

getErrors

public java.util.Set<java.lang.String> getErrors()
Gets the modifiable list of errors that have occurred.

Use addError(java.lang.String) to add to this list.

Returns:
the list of errors, not null, no nulls

addError

public void addError(java.lang.String error)
Adds an error to those tracked by the normalizer.

Parameters:
error - the error text, not null

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object