Class CalendricalMerger

java.lang.Object
javax.time.calendar.CalendricalMerger
All Implemented Interfaces:
Calendrical

public final class CalendricalMerger extends Object implements Calendrical
Stateful class used to merge calendrical information.

This class is a tool for merging any set of calendrical information into the most meaningful set of information. For example, separate year, month and day fields will be merged into a date. And if both date and time are present, then they will be merged into a date-time.

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

  • Field Details

    • inputMap

      private final Map<CalendricalRule<?>,Object> inputMap
      The map of potentially invalid data to being merged, never null. This is a concurrent hash map mainly to gain the no-nulls implementation.
    • processingMap

      private final Map<CalendricalRule<?>,Object> processingMap
      The map of in range data to be merged, never null. This is a concurrent hash map mainly to gain the no-nulls implementation.
    • context

      private CalendricalContext context
      The merge context to use.
    • iterator

      private Iterator<CalendricalRule<?>> iterator
      Current iterator, updated when the state of the map is changed.
    • overflow

      private Period overflow
      The overflow period to be added to the resultant date/time.
  • Constructor Details

    • CalendricalMerger

      public CalendricalMerger(CalendricalContext context)
      Constructor.
      Parameters:
      context - the context to use, not null
    • CalendricalMerger

      public CalendricalMerger(CalendricalContext context, Map<CalendricalRule<?>,Object> inputMap)
      Constructor.
      Parameters:
      context - the context to use, not null
      inputMap - the map of data to merge, not null
  • Method Details

    • getInputMap

      public Map<CalendricalRule<?>,Object> getInputMap()
      Gets the underlying rule-value map that is being merged.

      The map returned is the live data from this instance. Updating the map will update the data held by the merger.

      Values in this map may be invalid, for example the day-of-month may be an invalid negative value, or the hour represented as a currency. Some of these, like a negative day-of-month, may be capable of being interpreted by a lenient merger. Others, like a currency, cannot.

      The map must only be updated before merging starts. If the map is updated after merging starts, the result is undefined.

      Returns:
      the rule-value map being merged, doesn't accept nulls, never null
    • getContext

      public CalendricalContext getContext()
      Gets the calendrical context in use for the merge.
      Returns:
      the calendrical context, never null
    • setContext

      public void setContext(CalendricalContext context)
      Sets the calendrical context to use for the merge.

      The context must only be updated before merging starts. If the context is updated after merging starts, the result is undefined.

      Parameters:
      context - the calendrical context, not null
    • getOverflow

      public Period getOverflow()
      Gets the overflow that results from the merge.

      When some sets of fields are merged, the result may include an overflow. This is a period that should be added to a date-time to make the result whole.

      Returns:
      the overflow resulting from the merge, never null
    • addToOverflow

      public void addToOverflow(Period additionalOverflow)
      Gets the overflow that results from the merge.

      When some sets of fields are merged, the result may include an overflow. This is a period that should be added to a date-time to make the result whole.

      Parameters:
      additionalOverflow - the additional overflow to store, not null
    • get

      public <T> T get(CalendricalRule<T> rule)
      Gets the value of the specified calendrical rule from the merged result.

      This method queries the value of the specified calendrical rule using the merged rule-value map. If the value cannot be returned for the rule from this date then null will be returned.

      Specified by:
      get in interface Calendrical
      Parameters:
      rule - the rule to use, not null
      Returns:
      the value for the rule, null if the value cannot be returned
    • getValue

      public <T> T getValue(CalendricalRule<T> rule)
      Gets the value of the specified calendrical rule from the merged result.

      This method queries the value of the specified calendrical rule using the merged rule-value map. If the value cannot be returned for the rule from this date then null will be returned.

      Parameters:
      rule - the rule to use, not null
      Returns:
      the value for the rule, null if the value cannot be returned
    • storeMerged

      public <T> void storeMerged(CalendricalRule<T> rule, T value)
      Stores a rule-value pair into this map ensuring that it does not clash with any previous value defined for that rule.

      This method adds the specified rule-value pair to the map. If this instance already has a value for the rule then the value is checked to see if it is the same with an exception being thrown if it is not. If this instance does not hold the rule already, then the value is simply added.

      The merged value should be within the valid range for the rule.

      Parameters:
      rule - the field to store, not null
      value - the value to store, not null
      Throws:
      CalendricalException - if the input field does not match a previously stored field
    • removeProcessed

      public void removeProcessed(CalendricalRule<?> rule)
      Removes a rule and its value from the map being processed.

      This method is called to remove a rule-value pair that can now be derived from another item in the map following a merge.

      Parameters:
      rule - the rule to remove, not null
    • merge

      public Calendrical merge()
      Merges the fields to extract the maximum possible date, time and offset information.

      The merge process aims to extract the maximum amount of information possible from this set of fields. Ideally the outcome will be a date, time or both, however there may be insufficient information to achieve this.

      The process repeatedly calls the field rule merge method to perform the merge on each individual field. Sometimes two or more fields will combine to form a more significant field. Sometimes they will combine to form a date or time. The process stops when there no more merges can occur.

      The process is based around hierarchies that can be combined. For example, QuarterOfYear and MonthOfQuarter can be combined to form MonthOfYear. Then, MonthOfYear can be combined with DayOfMonth and Year to form a date. Any fields which take part in a merge will be removed from the result as their values can be derived from the merged field.

      The exact definition of which fields combine with which is chronology dependent. For example, see ISOChronology.

      The details of the process are controlled by the merge context. This includes strict/lenient behavior.

      The merge must result in consistent values for each field, date and time. If two different values are produced an exception is thrown. For example, both Year/MonthOfYear/DayOfMonth and Year/DayOfYear will merge to form a date. If both sets of fields do not produce the same date then an exception will be thrown.

      Throws:
      CalendricalException - if the merge cannot be completed successfully
    • mergeLoop

      private void mergeLoop()
      Performs the merge based on the rules.
      Throws:
      CalendricalException - if the merge cannot be completed successfully
    • interpret

      private void interpret()
      Interprets each value in the input map, converting to standard types.
      Throws:
      CalendricalException - if the value for any rule is invalid
    • removeDerivable

      private void removeDerivable()
      Removes any field from the processing map that can be derived from another field.
    • toString

      public String toString()
      Overrides:
      toString in class Object