java.time.temporal.TemporalQueries Maven / Gradle / Ivy
Show all versions of java-time-backport Show documentation
/*
* Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* * Neither the name of JSR-310 nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package java.time.temporal;
import static java.time.temporal.ChronoField.EPOCH_DAY;
import static java.time.temporal.ChronoField.NANO_OF_DAY;
import static java.time.temporal.ChronoField.OFFSET_SECONDS;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.OffsetDateTime;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.chrono.Chronology;
/**
* Common implementations of {@code TemporalQuery}.
*
* This class provides common implementations of {@link TemporalQuery}.
* These queries are primarily used as optimizations, allowing the internals
* of other objects to be extracted effectively. Note that application code
* can also use the {@code from(TemporalAccessor)} method on most temporal
* objects as a method reference matching the query interface, such as
* {@code LocalDate::from} and {@code ZoneId::from}.
*
* There are two equivalent ways of using a {@code TemporalQuery}.
* The first is to invoke the method on the interface directly.
* The second is to use {@link TemporalAccessor#query(TemporalQuery)}:
*
* // these two lines are equivalent, but the second approach is recommended
* dateTime = query.queryFrom(dateTime);
* dateTime = dateTime.query(query);
*
* It is recommended to use the second approach, {@code query(TemporalQuery)},
* as it is a lot clearer to read in code.
*
* Specification for implementors
* This is a thread-safe utility class.
* All returned adjusters are immutable and thread-safe.
*/
public final class TemporalQueries {
// note that it is vital that each method supplies a constant, not a
// calculated value, as they will be checked for using ==
// it is also vital that each constant is different (due to the == checking)
/**
* Private constructor since this is a utility class.
*/
private TemporalQueries() {
}
//-----------------------------------------------------------------------
// special constants should be used to extract information from a TemporalAccessor
// that cannot be derived in other ways
// Javadoc added here, so as to pretend they are more normal than they really are
/**
* A strict query for the {@code ZoneId}.
*
* This queries a {@code TemporalAccessor} for the zone.
* The zone is only returned if the date-time conceptually contains a {@code ZoneId}.
* It will not be returned if the date-time only conceptually has an {@code ZoneOffset}.
* Thus a {@link ZonedDateTime} will return the result of
* {@code getZone()}, but an {@link OffsetDateTime} will
* return null.
*
* In most cases, applications should use {@link #ZONE} as this query is too strict.
*
* The result from JDK classes implementing {@code TemporalAccessor} is as follows:
* {@code LocalDate} returns null
* {@code LocalTime} returns null
* {@code LocalDateTime} returns null
* {@code ZonedDateTime} returns the associated zone
* {@code OffsetTime} returns null
* {@code OffsetDateTime} returns null
* {@code ChronoLocalDate} returns null
* {@code ChronoLocalDateTime} returns null
* {@code ChronoZonedDateTime} returns the associated zone
* {@code Era} returns null
* {@code DayOfWeek} returns null
* {@code Month} returns null
* {@code Year} returns null
* {@code YearMonth} returns null
* {@code MonthDay} returns null
* {@code ZoneOffset} returns null
* {@code Instant} returns null
*
* @return a query that can obtain the zone ID of a temporal, not null
*/
public static final TemporalQuery zoneId() {
return ZONE_ID;
}
static final TemporalQuery ZONE_ID = new TemporalQuery() {
@Override
public ZoneId queryFrom(TemporalAccessor temporal) {
return temporal.query(this);
}
};
/**
* A query for the {@code Chronology}.
*
* This queries a {@code TemporalAccessor} for the chronology.
* If the target {@code TemporalAccessor} represents a date, or part of a date,
* then it should return the chronology that the date is expressed in.
* As a result of this definition, objects only representing time, such as
* {@code LocalTime}, will return null.
*
* The result from JDK classes implementing {@code TemporalAccessor} is as follows:
* {@code LocalDate} returns {@code IsoChronology.INSTANCE}
* {@code LocalTime} returns null (does not represent a date)
* {@code LocalDateTime} returns {@code IsoChronology.INSTANCE}
* {@code ZonedDateTime} returns {@code IsoChronology.INSTANCE}
* {@code OffsetTime} returns null (does not represent a date)
* {@code OffsetDateTime} returns {@code IsoChronology.INSTANCE}
* {@code ChronoLocalDate} returns the associated chronology
* {@code ChronoLocalDateTime} returns the associated chronology
* {@code ChronoZonedDateTime} returns the associated chronology
* {@code Era} returns the associated chronology
* {@code DayOfWeek} returns null (shared across chronologies)
* {@code Month} returns {@code IsoChronology.INSTANCE}
* {@code Year} returns {@code IsoChronology.INSTANCE}
* {@code YearMonth} returns {@code IsoChronology.INSTANCE}
* {@code MonthDay} returns null {@code IsoChronology.INSTANCE}
* {@code ZoneOffset} returns null (does not represent a date)
* {@code Instant} returns null (does not represent a date)
*
* The method {@link Chronology#from(TemporalAccessor)} can be used as a
* {@code TemporalQuery} via a method reference, {@code Chrono::from}.
* That method is equivalent to this query, except that it throws an
* exception if a chronology cannot be obtained.
*
* @return a query that can obtain the chronology of a temporal, not null
*/
public static final TemporalQuery chronology() {
return CHRONO;
}
static final TemporalQuery CHRONO = new TemporalQuery() {
@Override
public Chronology queryFrom(TemporalAccessor temporal) {
return temporal.query(this);
}
};
/**
* A query for the smallest supported unit.
*
* This queries a {@code TemporalAccessor} for the time precision.
* If the target {@code TemporalAccessor} represents a consistent or complete date-time,
* date or time then this must return the smallest precision actually supported.
* Note that fields such as {@code NANO_OF_DAY} and {@code NANO_OF_SECOND}
* are defined to always return ignoring the precision, thus this is the only
* way to find the actual smallest supported unit.
* For example, were {@code GregorianCalendar} to implement {@code TemporalAccessor}
* it would return a precision of {@code MILLIS}.
*
* The result from JDK classes implementing {@code TemporalAccessor} is as follows:
* {@code LocalDate} returns {@code DAYS}
* {@code LocalTime} returns {@code NANOS}
* {@code LocalDateTime} returns {@code NANOS}
* {@code ZonedDateTime} returns {@code NANOS}
* {@code OffsetTime} returns {@code NANOS}
* {@code OffsetDateTime} returns {@code NANOS}
* {@code ChronoLocalDate} returns {@code DAYS}
* {@code ChronoLocalDateTime} returns {@code NANOS}
* {@code ChronoZonedDateTime} returns {@code NANOS}
* {@code Era} returns {@code ERAS}
* {@code DayOfWeek} returns {@code DAYS}
* {@code Month} returns {@code MONTHS}
* {@code Year} returns {@code YEARS}
* {@code YearMonth} returns {@code MONTHS}
* {@code MonthDay} returns null (does not represent a complete date or time)
* {@code ZoneOffset} returns null (does not represent a date or time)
* {@code Instant} returns {@code NANOS}
*
* @return a query that can obtain the precision of a temporal, not null
*/
public static final TemporalQuery precision() {
return PRECISION;
}
static final TemporalQuery PRECISION = new TemporalQuery() {
@Override
public TemporalUnit queryFrom(TemporalAccessor temporal) {
return temporal.query(this);
}
};
//-----------------------------------------------------------------------
// non-special constants are standard queries that derive information from other information
/**
* A lenient query for the {@code ZoneId}, falling back to the {@code ZoneOffset}.
*
* This queries a {@code TemporalAccessor} for the zone.
* It first tries to obtain the zone, using {@link #zoneId()}.
* If that is not found it tries to obtain the {@link #offset()}.
*
* In most cases, applications should use this query rather than {@code #zoneId()}.
*
* This query examines the {@link ChronoField#OFFSET_SECONDS offset-seconds}
* field and uses it to create a {@code ZoneOffset}.
*
* The method {@link ZoneId#from(TemporalAccessor)} can be used as a
* {@code TemporalQuery} via a method reference, {@code ZoneId::from}.
* That method is equivalent to this query, except that it throws an
* exception if a zone cannot be obtained.
*
* @return a query that can obtain the zone ID or offset of a temporal, not null
*/
public static final TemporalQuery zone() {
return ZONE;
}
static final TemporalQuery ZONE = new TemporalQuery() {
@Override
public ZoneId queryFrom(TemporalAccessor temporal) {
ZoneId zone = temporal.query(ZONE_ID);
return (zone != null ? zone : temporal.query(OFFSET));
}
};
/**
* A query for {@code ZoneOffset} returning null if not found.
*
* This returns a {@code TemporalQuery} that can be used to query a temporal
* object for the offset. The query will return null if the temporal
* object cannot supply an offset.
*
* The query implementation examines the {@link ChronoField#OFFSET_SECONDS OFFSET_SECONDS}
* field and uses it to create a {@code ZoneOffset}.
*
* @return a query that can obtain the offset of a temporal, not null
*/
public static final TemporalQuery offset() {
return OFFSET;
}
static final TemporalQuery OFFSET = new TemporalQuery() {
@Override
public ZoneOffset queryFrom(TemporalAccessor temporal) {
if (temporal.isSupported(OFFSET_SECONDS)) {
return ZoneOffset.ofTotalSeconds(temporal.get(OFFSET_SECONDS));
}
return null;
}
};
/**
* A query for {@code LocalDate} returning null if not found.
*
* This returns a {@code TemporalQuery} that can be used to query a temporal
* object for the local date. The query will return null if the temporal
* object cannot supply a local date.
*
* The query implementation examines the {@link ChronoField#EPOCH_DAY EPOCH_DAY}
* field and uses it to create a {@code LocalDate}.
*
* @return a query that can obtain the date of a temporal, not null
*/
public static final TemporalQuery localDate() {
return LOCAL_DATE;
}
static final TemporalQuery LOCAL_DATE = new TemporalQuery() {
@Override
public LocalDate queryFrom(TemporalAccessor temporal) {
if (temporal.isSupported(EPOCH_DAY)) {
return LocalDate.ofEpochDay(temporal.getLong(EPOCH_DAY));
}
return null;
}
};
/**
* A query for {@code LocalTime} returning null if not found.
*
* This returns a {@code TemporalQuery} that can be used to query a temporal
* object for the local time. The query will return null if the temporal
* object cannot supply a local time.
*
* The query implementation examines the {@link ChronoField#NANO_OF_DAY NANO_OF_DAY}
* field and uses it to create a {@code LocalTime}.
*
* @return a query that can obtain the date of a temporal, not null
*/
public static final TemporalQuery localTime() {
return LOCAL_TIME;
}
static final TemporalQuery LOCAL_TIME = new TemporalQuery() {
@Override
public LocalTime queryFrom(TemporalAccessor temporal) {
if (temporal.isSupported(NANO_OF_DAY)) {
return LocalTime.ofNanoOfDay(temporal.getLong(NANO_OF_DAY));
}
return null;
}
};
}