Class CalendricalMerger
- All Implemented Interfaces:
Calendrical
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 Summary
FieldsModifier and TypeFieldDescriptionprivate CalendricalContext
The merge context to use.private final Map<CalendricalRule<?>,
Object> The map of potentially invalid data to being merged, never null.private Iterator<CalendricalRule<?>>
Current iterator, updated when the state of the map is changed.private Period
The overflow period to be added to the resultant date/time.private final Map<CalendricalRule<?>,
Object> The map of in range data to be merged, never null. -
Constructor Summary
ConstructorsConstructorDescriptionCalendricalMerger
(CalendricalContext context) Constructor.CalendricalMerger
(CalendricalContext context, Map<CalendricalRule<?>, Object> inputMap) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addToOverflow
(Period additionalOverflow) Gets the overflow that results from the merge.<T> T
get
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule from the merged result.Gets the calendrical context in use for the merge.Map<CalendricalRule<?>,
Object> Gets the underlying rule-value map that is being merged.Gets the overflow that results from the merge.<T> T
getValue
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule from the merged result.private void
Interprets each value in the input map, converting to standard types.merge()
Merges the fields to extract the maximum possible date, time and offset information.private void
Performs the merge based on the rules.private void
Removes any field from the processing map that can be derived from another field.void
removeProcessed
(CalendricalRule<?> rule) Removes a rule and its value from the map being processed.void
setContext
(CalendricalContext context) Sets the calendrical context to use for the merge.<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.toString()
-
Field Details
-
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
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
The merge context to use. -
iterator
Current iterator, updated when the state of the map is changed. -
overflow
The overflow period to be added to the resultant date/time.
-
-
Constructor Details
-
CalendricalMerger
Constructor.- Parameters:
context
- the context to use, not null
-
CalendricalMerger
Constructor.- Parameters:
context
- the context to use, not nullinputMap
- the map of data to merge, not null
-
-
Method Details
-
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
Gets the calendrical context in use for the merge.- Returns:
- the calendrical context, never null
-
setContext
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
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
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
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 interfaceCalendrical
- Parameters:
rule
- the rule to use, not null- Returns:
- the value for the rule, null if the value cannot be returned
-
getValue
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
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 nullvalue
- the value to store, not null- Throws:
CalendricalException
- if the input field does not match a previously stored field
-
removeProcessed
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
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
-