public final class CalendricalMerger extends Object implements 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.
Constructor and Description |
---|
CalendricalMerger(CalendricalContext context)
Constructor.
|
CalendricalMerger(CalendricalContext context,
Map<CalendricalRule<?>,Object> inputMap)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
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.
|
CalendricalContext |
getContext()
Gets the calendrical context in use for the merge.
|
Map<CalendricalRule<?>,Object> |
getInputMap()
Gets the underlying rule-value map that is being merged.
|
Period |
getOverflow()
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.
|
Calendrical |
merge()
Merges the fields to extract the maximum possible date, time and offset information.
|
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.
|
String |
toString() |
public CalendricalMerger(CalendricalContext context)
context
- the context to use, not nullpublic CalendricalMerger(CalendricalContext context, Map<CalendricalRule<?>,Object> inputMap)
context
- the context to use, not nullinputMap
- the map of data to merge, not nullpublic Map<CalendricalRule<?>,Object> getInputMap()
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.
public CalendricalContext getContext()
public void setContext(CalendricalContext context)
The context must only be updated before merging starts. If the context is updated after merging starts, the result is undefined.
context
- the calendrical context, not nullpublic Period getOverflow()
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.
public void addToOverflow(Period additionalOverflow)
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.
additionalOverflow
- the additional overflow to store, not nullpublic <T> T get(CalendricalRule<T> rule)
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.
get
in interface Calendrical
rule
- the rule to use, not nullpublic <T> T getValue(CalendricalRule<T> rule)
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.
rule
- the rule to use, not nullpublic <T> void storeMerged(CalendricalRule<T> rule, T value)
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.
rule
- the field to store, not nullvalue
- the value to store, not nullCalendricalException
- if the input field does not match a previously stored fieldpublic void removeProcessed(CalendricalRule<?> rule)
This method is called to remove a rule-value pair that can now be derived from another item in the map following a merge.
rule
- the rule to remove, not nullpublic Calendrical merge()
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.
CalendricalException
- if the merge cannot be completed successfullyCopyright © 2014. All rights reserved.