Class 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.

    Author:
    Michael Nascimento Santos, Stephen Colebourne
    • Constructor Detail

      • 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 Detail

      • 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