public final class DateTimeBuilder extends java.lang.Object implements TemporalAccessor, java.lang.Cloneable
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:
TemporalField
to long
value, where the value may be
outside the valid range for the field
Class
to TemporalAccessor
, holding larger scale objects
like LocalDateTime
.
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.
|
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.
|
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
get, range
public DateTimeBuilder()
public DateTimeBuilder(TemporalField field, long value)
This is equivalent to using addFieldValue(TemporalField, long)
on an empty builder.
field
- the field to add, not nullvalue
- the value to add, not nullpublic java.util.Map<TemporalField,java.lang.Long> getFieldValueMap()
public boolean containsFieldValue(TemporalField field)
field
- the field to find in the field-value map, not nullpublic long getFieldValue(TemporalField field)
field
- the field to query in the field-value map, not nullDateTimeException
- if the field is not presentpublic long getValidFieldValue(TemporalField field)
field
- the field to query in the field-value map, not nullDateTimeException
- if the field is not presentpublic DateTimeBuilder addFieldValue(TemporalField field, long value)
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.
field
- the field to add, not nullvalue
- the value to add, not nullthis
, for method chainingDateTimeException
- if the field is already present with a different valuepublic long removeFieldValue(TemporalField field)
This removes a field, which must exist, from the builder.
See removeFieldValues(TemporalField...)
for a version which does not throw an exception
field
- the field to remove, not nullDateTimeException
- if the field is not foundpublic void removeFieldValues(TemporalField... fields)
This removes the specified fields from the builder. No exception is thrown if the fields are not present.
fields
- the fields to remove, not nullpublic java.lang.Long[] queryFieldValues(TemporalField... fields)
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.
fields
- the fields to query, not nullpublic java.util.List<java.lang.Object> getCalendricalList()
This map is intended for use with ZoneOffset
and ZoneId
.
The returned map is live and may be edited.
public DateTimeBuilder addCalendrical(java.lang.Object object)
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.
object
- the object to add, not nullthis
, for method chainingDateTimeException
- if the field is already present with a different valuepublic DateTimeBuilder resolve()
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.
this
, for method chainingpublic <R> R query(TemporalQuery<R> query)
TemporalAccessor
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.
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);
query
in interface TemporalAccessor
R
- the type of the resultquery
- the query to invoke, not nullpublic <R> R extract(java.lang.Class<?> type)
public DateTimeBuilder clone()
clone
in class java.lang.Object
Cloneable
public java.lang.String toString()
java.lang.Object
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())
toString
in class java.lang.Object
public boolean isSupported(TemporalField field)
TemporalAccessor
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.
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.
isSupported
in interface TemporalAccessor
field
- the field to check, null returns falsepublic long getLong(TemporalField field)
TemporalAccessor
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.
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.
getLong
in interface TemporalAccessor
field
- the field to get, not null