Class DateTimeFields

java.lang.Object
javax.time.calendar.DateTimeFields
All Implemented Interfaces:
Serializable, Iterable<DateTimeFieldRule<?>>, Calendrical, CalendricalMatcher

public final class DateTimeFields extends Object implements Calendrical, CalendricalMatcher, Iterable<DateTimeFieldRule<?>>, Serializable
A set of date-time fields.

Instances of this class store a map of field-value pairs. Together these specify constraints on the dates and times that match. For example, if an instance stores 'DayOfMonth=13' and 'DayOfWeek=Friday' then it represents and matches only dates of Friday the Thirteenth.

All the values will be within the valid range for the field. However, there is no cross validation between fields. Thus, it is possible for the date-time represented to never exist. For example, if an instance stores 'DayOfMonth=31' and 'MonthOfYear=February' then there will never be a matching date.

See Also:
  • Field Details

    • EMPTY

      public static final DateTimeFields EMPTY
      A singleton empty DateTimeFields, placing no restrictions on the date-time.
    • serialVersionUID

      private static final long serialVersionUID
      Serialization version.
      See Also:
    • fieldValueMap

      private final TreeMap<DateTimeFieldRule<?>,Integer> fieldValueMap
      The date time map, never null, may be empty.
  • Constructor Details

    • DateTimeFields

      private DateTimeFields(TreeMap<DateTimeFieldRule<?>,Integer> assignedMap)
      Constructor.
      Parameters:
      assignedMap - the map of fields, which is assigned, not null
  • Method Details

    • of

      public static DateTimeFields of(DateTimeFieldRule<?> fieldRule, int value)
      Obtains an instance of DateTimeFields from a field-value pair.

      This factory allows the creation of a fields object with a single field-value pair. The value must be within the valid range for the field.

      Parameters:
      fieldRule - the rule, not null
      value - the field value, may be invalid
      Returns:
      the fields instance, never null
      Throws:
      NullPointerException - if the field rule is null
      IllegalCalendarFieldValueException - if the value is invalid
    • of

      public static DateTimeFields of(DateTimeFieldRule<?> fieldRule1, int value1, DateTimeFieldRule<?> fieldRule2, int value2)
      Obtains an instance of DateTimeFields from two field-value pairs.

      This factory allows the creation of a fields object with two field-value pairs. Each value must be within the valid range for that field.

      The two fields are not cross-validated. Thus, you can specify MonthOfYear of June and DayOfMonth of 31, which is a date that can never occur.

      Parameters:
      fieldRule1 - the first rule, not null
      value1 - the first field value
      fieldRule2 - the second rule, not null
      value2 - the second field value
      Returns:
      the fields instance, never null
      Throws:
      NullPointerException - if either field rule is null
      IllegalCalendarFieldValueException - if either value is invalid
    • of

      public static DateTimeFields of(Map<DateTimeFieldRule<?>,Integer> fieldValueMap)
      Obtains an instance of DateTimeFields from a map of field-value pairs.

      This factory allows the creation of a fields object from a map of field-value pairs. Each value must be within the valid range for that field.

      The fields are not cross-validated. Thus, you can specify MonthOfYear of June and DayOfMonth of 31, which is a date that can never occur.

      Parameters:
      fieldValueMap - a map of fields that will be used to create a field set, not updated by this factory, not null, contains no nulls
      Returns:
      the fields instance, never null
      Throws:
      NullPointerException - if the map contains null keys or values
      IllegalCalendarFieldValueException - if any value is invalid
    • createMap

      private static TreeMap<DateTimeFieldRule<?>,Integer> createMap()
      Creates a new empty map.
      Returns:
      ordered representation of internal map
    • readResolve

      private Object readResolve() throws ObjectStreamException
      Ensure EMPTY singleton.
      Returns:
      the resolved instance
      Throws:
      ObjectStreamException - if an error occurs
    • size

      public int size()
      Returns the size of the map of fields to values.

      This method returns the number of field-value pairs stored.

      Returns:
      number of field-value pairs, zero or greater
    • iterator

      public Iterator<DateTimeFieldRule<?>> iterator()
      Iterates through all the field rules.

      This method fulfills the Iterable interface and allows looping around the fields using the for-each loop. The values can be obtained using get(javax.time.calendar.CalendricalRule<T>) or getInt(javax.time.calendar.DateTimeFieldRule<?>).

      Specified by:
      iterator in interface Iterable<DateTimeFieldRule<?>>
      Returns:
      an iterator over the fields in this object, never null
    • contains

      public boolean contains(DateTimeFieldRule<?> fieldRule)
      Checks if this object contains a mapping for the specified field.

      This method returns true if a value can be obtained for the specified field.

      Parameters:
      fieldRule - the field to query, null returns false
      Returns:
      true if the field is supported, false otherwise
    • get

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

      This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this instance then an attempt is made to derive the value. If that fails, 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
    • getInt

      public int getInt(DateTimeFieldRule<?> rule)
      Gets the value for the specified field throwing an exception if the field is not in the field-value map.

      The value will be within the valid range for the field.

      No attempt is made to derive values. The result is simply based on the contents of the stored field-value map. If you want to derive a value then use get(javax.time.calendar.CalendricalRule<T>) or a CalendricalMerger.

      Parameters:
      rule - the rule to query from the map, not null
      Returns:
      the value mapped to the specified field
      Throws:
      UnsupportedRuleException - if the field is not in the map
    • getQuiet

      public Integer getQuiet(DateTimeFieldRule<?> fieldRule)
      Gets the value for the specified field quietly returning null if the field is not in the field-value map.

      The value will be within the valid range for the field.

      Parameters:
      fieldRule - the rule to query from the map, null returns null
      Returns:
      the value mapped to the specified field, null if not present
    • with

      public DateTimeFields with(DateTimeFieldRule<?> fieldRule, int value)
      Returns a copy of this DateTimeFields with the specified field value.

      If this instance already has a value for the field then the value is replaced. Otherwise the value is added to the map.

      This instance is immutable and unaffected by this method call.

      Parameters:
      fieldRule - the field to set in the returned object, not null
      value - the value to set in the returned set of fields
      Returns:
      a new, updated DateTimeFields, never null
      Throws:
      NullPointerException - if DateTimeFieldRule is null
      IllegalCalendarFieldValueException - if the value is invalid
    • with

      public DateTimeFields with(DateTimeFields fields)
      Returns a copy of this DateTimeFields with the specified fields added.

      If this instance already has a value for the field then the value is replaced. Otherwise the value is added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      fields - the fields to add to the returned object, not null
      Returns:
      a new, updated DateTimeFields, never null
    • withFieldRemoved

      public DateTimeFields withFieldRemoved(DateTimeFieldRule<?> fieldRule)
      Returns a copy of this object with the specified field removed.

      If this instance does not contain the field then the returned instance is the same as this one.

      This instance is immutable and unaffected by this method call.

      Parameters:
      fieldRule - the field to remove from the returned object, not null
      Returns:
      a new, updated DateTimeFields, never null
    • matchesCalendrical

      public boolean matchesCalendrical(Calendrical calendrical)
      Checks if the fields in this object match those in the specified calendrical.

      This implementation checks that all calendrical fields in this object match.

      Specified by:
      matchesCalendrical in interface CalendricalMatcher
      Parameters:
      calendrical - the calendrical to match, not null
      Returns:
      true if the calendrical fields match, false otherwise
    • toFieldValueMap

      public SortedMap<DateTimeFieldRule<?>,Integer> toFieldValueMap()
      Converts this object to a map of fields to values.

      The returned map will never be null, however it may be empty. It is independent of this object - changes will not be reflected back.

      Returns:
      an independent, modifiable copy of the field-value map, never null
    • clonedMap

      private TreeMap<DateTimeFieldRule<?>,Integer> clonedMap()
      Clones the field-value map.
      Returns:
      a clone of the field-value map, never null
    • equals

      public boolean equals(Object obj)
      Is this object equal to the specified object.

      This compares the map of field-value pairs.

      Overrides:
      equals in class Object
      Parameters:
      obj - the other fields to compare to, null returns false
      Returns:
      true if this instance is equal to the specified field set
    • hashCode

      public int hashCode()
      A hash code for these fields.
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code
    • toString

      public String toString()
      Outputs the fields as a String.

      The output will consist of the field-value map in standard map format.

      Overrides:
      toString in class Object
      Returns:
      the formatted date-time string, never null