DateTimeBuilder (ThreeTen Date and Time API)

java.lang.Object
- java.time.format.DateTimeBuilder

All Implemented Interfaces:

java.lang.Cloneable, TemporalAccessor
```
public final class DateTimeBuilder
extends java.lang.Object
implements TemporalAccessor, java.lang.Cloneable
```
Builder that can holds date and time fields and related date and time objects.
This class still needs major revision before JDK1.8 ships.
The builder is used to hold onto different elements of date and time. It is designed as two separate maps:
- from TemporalField to long value, where the value may be outside the valid range for the field
- from Class to TemporalAccessor, holding larger scale objects like LocalDateTime.
Specification for implementors
This class is mutable and not thread-safe. It should only be used from a single thread.
Since:

1.8

Constructor Summary

Constructors
Constructor and Description
`DateTimeBuilder()` Creates an empty instance of the builder.
`DateTimeBuilder(TemporalField field, long value)` Creates a new instance of the builder with a single field-value.
`DateTimeBuilder(ZoneId zone, Chrono<?> chrono)` Creates a new instance of the builder.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`DateTimeBuilder`	`addCalendrical(java.lang.Object object)` Adds a date-time object to the builder.
`DateTimeBuilder`	`addFieldValue(TemporalField field, long value)` Adds a field-value pair to the builder.
`DateTimeBuilder`	`clone()` Clones this builder, creating a new independent copy referring to the same map of fields and objects.
`boolean`	`containsFieldValue(TemporalField field)` Checks whether the specified field is present in the builder.
`<R> R`	`extract(java.lang.Class<?> type)`
`java.util.List<java.lang.Object>`	`getCalendricalList()` Gets the list of date-time objects in the builder.
`long`	`getFieldValue(TemporalField field)` Gets the value of the specified field from the builder.
`java.util.Map<TemporalField,java.lang.Long>`	`getFieldValueMap()` Gets the map of field-value pairs in the builder.
`long`	`getLong(TemporalField field)` Gets the value of the specified field as a `long`.
`long`	`getValidFieldValue(TemporalField field)` Gets the value of the specified field from the builder ensuring it is valid.
`boolean`	`isSupported(TemporalField field)` Checks if the specified field is supported.
`<R> R`	`query(TemporalQuery<R> query)` Queries this date-time.
`java.lang.Long[]`	`queryFieldValues(TemporalField... fields)` Queries a list of fields from the builder.
`long`	`removeFieldValue(TemporalField field)` Removes a field-value pair from the builder.
`void`	`removeFieldValues(TemporalField... fields)` Removes a list of fields from the builder.
`DateTimeBuilder`	`resolve()` Resolves the builder, evaluating the date and time.
`java.lang.String`	`toString()` Returns a string representation of the object.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.time.temporal.TemporalAccessor
get, range

- Constructor Detail
  - DateTimeBuilder
```
public DateTimeBuilder()
```
    Creates an empty instance of the builder.
  - DateTimeBuilder
```
public DateTimeBuilder(TemporalField field,
               long value)
```
    Creates a new instance of the builder with a single field-value.
    This is equivalent to using addFieldValue(TemporalField, long) on an empty builder.
    
    Parameters:
    field - the field to add, not null
    value - the value to add, not null
  - DateTimeBuilder
```
public DateTimeBuilder(ZoneId zone,
               Chrono<?> chrono)
```
    Creates a new instance of the builder.
    
    Parameters:
    zone - the zone, may be null
    chrono - the chronology, may be null
- Method Detail
  - getFieldValueMap
```
public java.util.Map<TemporalField,java.lang.Long> getFieldValueMap()
```
    Gets the map of field-value pairs in the builder.
    
    Returns:
    a modifiable copy of the field-value map, not null
  - containsFieldValue
```
public boolean containsFieldValue(TemporalField field)
```
    Checks whether the specified field is present in the builder.
    
    Parameters:
    field - the field to find in the field-value map, not null
    
    Returns:
    true if the field is present
  - getFieldValue
```
public long getFieldValue(TemporalField field)
```
    Gets the value of the specified field from the builder.
    
    Parameters:
    field - the field to query in the field-value map, not null
    
    Returns:
    the value of the field, may be out of range
    
    Throws:
    
    DateTimeException - if the field is not present
  - getValidFieldValue
```
public long getValidFieldValue(TemporalField field)
```
    Gets the value of the specified field from the builder ensuring it is valid.
    
    Parameters:
    field - the field to query in the field-value map, not null
    
    Returns:
    the value of the field, may be out of range
    
    Throws:
    
    DateTimeException - if the field is not present
  - addFieldValue
```
public DateTimeBuilder addFieldValue(TemporalField field,
                            long value)
```
    Adds a field-value pair to the builder.
    This adds a field to the builder. If the field is not already present, then the field-value pair is added to the map. If the field is already present and it has the same value as that specified, no action occurs. If the field is already present and it has a different value to that specified, then an exception is thrown.
    
    Parameters:
    field - the field to add, not null
    value - the value to add, not null
    
    Returns:
    this, for method chaining
    
    Throws:
    
    DateTimeException - if the field is already present with a different value
  - removeFieldValue
```
public long removeFieldValue(TemporalField field)
```
    Removes a field-value pair from the builder.
    This removes a field, which must exist, from the builder. See removeFieldValues(TemporalField...) for a version which does not throw an exception
    
    Parameters:
    field - the field to remove, not null
    
    Returns:
    the previous value of the field
    
    Throws:
    
    DateTimeException - if the field is not found
  - removeFieldValues
```
public void removeFieldValues(TemporalField... fields)
```
    Removes a list of fields from the builder.
    This removes the specified fields from the builder. No exception is thrown if the fields are not present.
    
    Parameters:
    fields - the fields to remove, not null
  - queryFieldValues
```
public java.lang.Long[] queryFieldValues(TemporalField... fields)
```
    Queries a list of fields from the builder.
    This gets the value of the specified fields from the builder into an array where the positions match the order of the fields. If a field is not present, the array will contain null in that position.
    
    Parameters:
    fields - the fields to query, not null
    
    Returns:
    the array of field values, not null
  - getCalendricalList
```
public java.util.List<java.lang.Object> getCalendricalList()
```
    Gets the list of date-time objects in the builder.
    This map is intended for use with ZoneOffset and ZoneId. The returned map is live and may be edited.
    
    Returns:
    the editable list of date-time objects, not null
  - addCalendrical
```
public DateTimeBuilder addCalendrical(java.lang.Object object)
```
    Adds a date-time object to the builder.
    This adds a date-time object to the builder. If the object is a DateTimeBuilder, each field is added using addFieldValue(java.time.temporal.TemporalField, long). If the object is not already present, then the object is added. If the object is already present and it is equal to that specified, no action occurs. If the object is already present and it is not equal to that specified, then an exception is thrown.
    
    Parameters:
    object - the object to add, not null
    
    Returns:
    this, for method chaining
    
    Throws:
    
    DateTimeException - if the field is already present with a different value
  - resolve
```
public DateTimeBuilder resolve()
```
    Resolves the builder, evaluating the date and time.
    This examines the contents of the builder and resolves it to produce the best available date and time, throwing an exception if a problem occurs. Calling this method changes the state of the builder.
    
    Returns:
    this, for method chaining
  - query
```
public <R> R query(TemporalQuery<R> query)
```
    Description copied from interface: TemporalAccessor
    Queries this date-time.
    This queries this date-time using the specified query strategy object.
    Queries are a key tool for extracting information from date-times. They exists to externalize the process of querying, permitting different approaches, as per the strategy design pattern. Examples might be a query that checks if the date is the day before February 29th in a leap year, or calculates the number of days to your next birthday.
    The most common query implementations are method references, such as LocalDate::from and ZoneId::from. Further implementations are on Queries. Queries may also be defined by applications.
    Specification for implementors
    The default implementation must behave equivalent to this code:
```
  if (query == Queries.zoneId() || query == Queries.chrono() || query == Queries.precision()) {
    return null;
  }
  return query.queryFrom(this);
 
```
    Future versions are permitted to add further queries to the if statement.
    All classes implementing this interface and overriding this method must call TemporalAccessor.super.query(query). JDK classes may avoid calling super if they provide behavior equivalent to the default behaviour, however non-JDK classes may not utilize this optimization and must call super.
    If the implementation can supply a value for one of the queries listed in the if statement of the default implementation, then it must do so. For example, an application-defined HourMin class storing the hour and minute must override this method as follows:
```
  if (query == Queries.precision()) {
    return MINUTES;
  }
  return TemporalAccessor.super.query(query);
 
```
    Specified by:
    
    query in interface TemporalAccessor
    
    Type Parameters:
    R - the type of the result
    Parameters:
    query - the query to invoke, not null
    
    Returns:
    the query result, null may be returned (defined by the query)
  - extract
```
public <R> R extract(java.lang.Class<?> type)
```
  - clone
```
public DateTimeBuilder clone()
```
    Clones this builder, creating a new independent copy referring to the same map of fields and objects.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    the cloned builder, not null
    See Also:
    Cloneable
  - toString
```
public java.lang.String toString()
```
    Description copied from class: java.lang.Object
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.
    The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
    getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    a string representation of the object.
  - isSupported
```
public boolean isSupported(TemporalField field)
```
    Description copied from interface: TemporalAccessor
    
    Checks if the specified field is supported.
    This checks if the date-time can be queried for the specified field. If false, then calling the range and get methods will throw an exception.
    Specification for implementors
    Implementations must check and handle all fields defined in ChronoField. If the field is supported, then true is returned, otherwise false
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.doIsSupported(TemporalAccessor) passing this as the argument.
    Implementations must not alter either this object.
    
    Specified by:
    
    isSupported in interface TemporalAccessor
    
    Parameters:
    field - the field to check, null returns false
    
    Returns:
    true if this date-time can be queried for the field, false if not
  - getLong
```
public long getLong(TemporalField field)
```
    Description copied from interface: TemporalAccessor
    
    Gets the value of the specified field as a long.
    This queries the date-time for the value for the specified field. The returned value may be outside the valid range of values for the field. If the date-time cannot return the value, because the field is unsupported or for some other reason, an exception will be thrown.
    Specification for implementors
    Implementations must check and handle all fields defined in ChronoField. If the field is supported, then the value of the field must be returned. If unsupported, then a DateTimeException must be thrown.
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.doGet(TemporalAccessor) passing this as the argument.
    Implementations must not alter either this object.
    
    Specified by:
    
    getLong in interface TemporalAccessor
    
    Parameters:
    field - the field to get, not null
    
    Returns:
    the value for the field

Class DateTimeBuilder

Specification for implementors

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.time.temporal.TemporalAccessor

Constructor Detail

DateTimeBuilder

DateTimeBuilder

DateTimeBuilder

Method Detail

getFieldValueMap

containsFieldValue

getFieldValue

getValidFieldValue

addFieldValue

removeFieldValue

removeFieldValues

queryFieldValues

getCalendricalList

addCalendrical

resolve

query

Specification for implementors

extract

clone

toString

isSupported

Specification for implementors

getLong

Specification for implementors