Класс TemporalQueries

java.lang.Object

java.time.temporal.TemporalQueries

public final class TemporalQueries extends Object

Общие реализации TemporalQuery.

Этот класс предоставляет общие реализации TemporalQuery. Они определены здесь, так как должны быть константами, а определение лямбда-выражений не гарантирует этого. Присваивая им значения здесь один раз, они становятся обычными Java-константами.

Запросы являются ключевым инструментом для извлечения информации из временных объектов. Они существуют для внешней организации процесса запроса, позволяя различные подходы, в соответствии с шаблоном проектирования стратегия. Примерами могут быть запрос, проверяющий, является ли дата днём перед 29 февраля в високосном году, или вычисление количества дней до следующего дня рождения.

Интерфейс TemporalField предоставляет другой механизм для запроса временных объектов. Этот интерфейс ограничен возвращением long. В отличие от этого, запросы могут возвращать любой тип.

Существует два эквивалентных способа использования TemporalQuery. Первый — вызвать метод непосредственно в этом интерфейсе. Второй — использовать TemporalAccessor.query(TemporalQuery):

   // these two lines are equivalent, but the second approach is recommended
   temporal = thisQuery.queryFrom(temporal);
   temporal = temporal.query(thisQuery);

Рекомендуется использовать второй подход, query(TemporalQuery), так как он намного понятнее в коде.

Наиболее распространённые реализации — ссылки на методы, такие как LocalDate::from и ZoneId::from. Дополнительные общие запросы предназначены для возвращения:

календаря,
даты,
времени,
смещения часового пояса,
точности,
часового пояса, или
идентификатора часового пояса.

Since:: 1.8

Краткое описание методов

Модификатор и тип	Метод	Описание
`static TemporalQuery<Chronology>`	`chronology()`	Запрос для `Chronology`.
`static TemporalQuery<LocalDate>`	`localDate()`	Запрос для `LocalDate`, возвращающий null, если не найден.
`static TemporalQuery<LocalTime>`	`localTime()`	Запрос для `LocalTime` возвращающий null, если не найден.
`static TemporalQuery<ZoneOffset>`	`offset()`	Запрос для `ZoneOffset` возвращающий null, если не найден.
`static TemporalQuery<TemporalUnit>`	`precision()`	Запрос для наименьшего поддерживаемого единицы измерения.
`static TemporalQuery<ZoneId>`	`zone()`	Допускающий запрос для `ZoneId`, используя `ZoneOffset` в качестве резервного варианта.
`static TemporalQuery<ZoneId>`	`zoneId()`	Строгий запрос для `ZoneId`.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание методов

zoneId

public static TemporalQuery<ZoneId> zoneId()

Строгий запрос для ZoneId.

Этот запрос извлекает часовой пояс из TemporalAccessor. Часовой пояс возвращается только если временная метка концептуально содержит ZoneId. Он не возвращается, если временная метка концептуально содержит только ZoneOffset. Таким образом, ZonedDateTime вернёт результат getZone(), а OffsetDateTime вернёт null.

В большинстве случаев приложения должны использовать zone(), так как этот запрос слишком строгий.

Результат работы классов JDK, реализующих TemporalAccessor выглядит следующим образом:
LocalDate возвращает null
LocalTime возвращает null
LocalDateTime возвращает null
ZonedDateTime возвращает связанный часовой пояс
OffsetTime возвращает null
OffsetDateTime возвращает null
ChronoLocalDate возвращает null
ChronoLocalDateTime возвращает null
ChronoZonedDateTime возвращает связанный часовой пояс
Era возвращает null
DayOfWeek возвращает null
Month возвращает null
Year возвращает null
YearMonth возвращает null
MonthDay возвращает null
ZoneOffset возвращает null
Instant возвращает null

Возвращает:: запрос, который может получить идентификатор часового пояса временной метки, не null

chronology

public static TemporalQuery<Chronology> chronology()

Запрос для Chronology.

Этот запрос извлекает хронологию из TemporalAccessor. Если целевая TemporalAccessor представляет дату или часть даты, то она должна вернуть хронологию, в которой выражена дата. В результате этого определения объекты, представляющие только время, такие как LocalTime, вернут null.

Результат работы классов JDK, реализующих TemporalAccessor выглядит следующим образом:
LocalDate возвращает IsoChronology.INSTANCE
LocalTime возвращает null (не представляет дату)
LocalDateTime возвращает IsoChronology.INSTANCE
ZonedDateTime возвращает IsoChronology.INSTANCE
OffsetTime возвращает null (не представляет дату)
OffsetDateTime возвращает IsoChronology.INSTANCE
ChronoLocalDate возвращает связанную хронологию
ChronoLocalDateTime возвращает связанную хронологию
ChronoZonedDateTime возвращает связанную хронологию
Era возвращает связанную хронологию
DayOfWeek возвращает null (общий для всех хронологий)
Month возвращает IsoChronology.INSTANCE
Year возвращает IsoChronology.INSTANCE
YearMonth возвращает IsoChronology.INSTANCE
MonthDay возвращает null IsoChronology.INSTANCE
ZoneOffset возвращает null (не представляет дату)
Instant возвращает null (не представляет дату)

Метод Chronology.from(TemporalAccessor) может быть использован как TemporalQuery с помощью ссылки на метод, Chronology::from. Этот метод эквивалентен этому запросу, за исключением того, что он выбрасывает исключение, если хронология не может быть получена.

Возвращает:: запрос, который может получить хронологию временной метки, не null

precision

public static TemporalQuery<TemporalUnit> precision()

Запрос на минимальное поддерживаемое значение.

Этот запрос извлекает точность времени из TemporalAccessor. Если целевая TemporalAccessor представляет согласованную или полную дату-время, дату или время, то она должна вернуть наименьшую поддерживаемую точность. Обратите внимание, что такие поля, как NANO_OF_DAY и NANO_OF_SECOND определены так, что они всегда возвращают значение, игнорируя точность, поэтому это единственный способ найти фактическое минимальное поддерживаемое значение. Например, если бы GregorianCalendar реализовывала TemporalAccessor, она вернула бы точность MILLIS.

Результат работы классов JDK, реализующих TemporalAccessor выглядит следующим образом:
LocalDate возвращает DAYS
LocalTime возвращает NANOS
LocalDateTime возвращает NANOS
ZonedDateTime возвращает NANOS
OffsetTime возвращает NANOS
OffsetDateTime возвращает NANOS
ChronoLocalDate возвращает DAYS
ChronoLocalDateTime возвращает NANOS
ChronoZonedDateTime возвращает NANOS
Era возвращает ERAS
DayOfWeek возвращает DAYS
Month возвращает MONTHS
Year возвращает YEARS
YearMonth возвращает MONTHS
MonthDay возвращает null (не представляет полную дату или время)
ZoneOffset возвращает null (не представляет дату или время)
Instant возвращает NANOS

Возвращает:: запрос, который может получить точность временной метки, не null

zone

public static TemporalQuery<ZoneId> zone()

Ленивый запрос для ZoneId, использующий ZoneOffset в качестве резервного варианта.

Этот запрос извлекает часовой пояс из TemporalAccessor. Сначала он пытается получить часовой пояс, используя zoneId(). Если это не удаётся, он пытается получить offset(). Таким образом, ZonedDateTime вернёт результат getZone(), а OffsetDateTime вернёт результат getOffset().

В большинстве случаев приложения должны использовать этот запрос вместо #zoneId().

Метод ZoneId.from(TemporalAccessor) может быть использован как TemporalQuery с помощью ссылки на метод, ZoneId::from. Этот метод эквивалентен этому запросу, за исключением того, что он выбрасывает исключение, если часовой пояс не может быть получен.

Возвращает:: запрос, который может получить идентификатор часового пояса или смещение временной метки, не null

offset

public static TemporalQuery<ZoneOffset> offset()

Запрос для ZoneOffset, возвращающий null, если не найден.

Это возвращает TemporalQuery, который может быть использован для запроса временной метки относительно смещения. Запрос вернёт null, если временная метка не может предоставить смещение.

Реализация запроса использует поле OFFSET_SECONDS для создания ZoneOffset.

Метод ZoneOffset.from(TemporalAccessor) может быть использован как TemporalQuery с помощью ссылки на метод, ZoneOffset::from. Этот запрос и ZoneOffset::from вернут одинаковый результат, если временная метка содержит смещение. Если временная метка не содержит смещения, то ссылка на метод выбросит исключение, а этот запрос вернёт null.

Возвращает:: запрос, который может получить смещение временной метки, не null

localDate

public static TemporalQuery<LocalDate> localDate()

Запрос для LocalDate возвращающий null, если не найден.

Это возвращает TemporalQuery, который может быть использован для запроса временной метки относительно локальной даты. Запрос вернёт null, если временная метка не может предоставить локальную дату.

Реализация запроса использует поле EPOCH_DAY для создания LocalDate.

Метод ZoneOffset.from(TemporalAccessor) может быть использован как TemporalQuery с помощью ссылки на метод, LocalDate::from. Этот запрос и LocalDate::from вернут одинаковый результат, если временная метка содержит дату. Если временная метка не содержит дату, то ссылка на метод выбросит исключение, а этот запрос вернёт null.

Возвращает:: запрос, который может получить дату временной метки, не null

localTime

public static TemporalQuery<LocalTime> localTime()

Запрос для LocalTime возвращающий null, если не найден.

Это возвращает TemporalQuery, который может быть использован для запроса временной метки относительно локального времени. Запрос вернёт null, если временная метка не может предоставить локальное время.

Реализация запроса использует поле NANO_OF_DAY для создания LocalTime.

Метод ZoneOffset.from(TemporalAccessor) может быть использован как TemporalQuery с помощью ссылки на метод, LocalTime::from. Этот запрос и LocalTime::from вернут одинаковый результат, если временная метка содержит время. Если временная метка не содержит время, то ссылка на метод выбросит исключение, а этот запрос вернёт null.

Возвращает:: запрос, который может получить время временной метки, не null

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/temporal/TemporalQueries.html