Класс Duration

public abstract class Duration
extends Object

Неизменяемое представление временного интервала, как определено в спецификации W3C XML Schema 1.0.

Объект Duration представляет период григорианского времени, который состоит из шести полей (лет, месяцев, дней, часов, минут и секунд) плюс поле знака (+/-).

Первые пять полей содержат неотрицательные целые числа (>=0) или null (что означает, что поле не задано), а поле секунд — неотрицательное десятичное число или null. Минус перед значением указывает на отрицательную продолжительность.

Этот класс предоставляет ряд методов, которые облегчают использование типа данных duration XML Schema 1.0 с ошибками.

Отношение порядка

Объекты Duration имеют только частичный порядок, где две величины A и B могут быть либо:

  1. A<B (A короче, чем B)
  2. A>B (A длиннее, чем B)
  3. A==B (A и B имеют одинаковую продолжительность)
  4. A<>B (Сравнение A и B неопределенно)

Например, 30 дней нельзя осмысленно сравнить с одним месяцем. Метод compare(Duration duration) реализует это отношение.

См. метод isLongerThan(Duration) для получения подробной информации об отношении порядка между объектами Duration.

Операции над Duration

Этот класс предоставляет набор основных арифметических операций, таких как сложение, вычитание и умножение. Поскольку продолжительности не имеют полного порядка, операция может завершиться ошибкой для некоторых комбинаций операций. Например, нельзя вычесть 15 дней из 1 месяца. См. javadoc этих методов для подробных условий, при которых это может произойти.

Также не предусмотрено деление продолжительности на число, потому что класс Duration может обрабатывать только числа с конечной точностью. Например, нельзя представить 1 сек, деленную на 3.

Однако, вы можете заменить деление на 3 умножением на числа, такие как 0,3 или 0,333.

Диапазон допустимых значений

Поскольку некоторые операции над Duration зависят от Calendar, даже если Duration может содержать очень большие или очень малые значения, некоторые методы могут работать неправильно с такими Duration. Затронутые методы документируют свою зависимость от Calendar.

Since:
1.5
См. также:
XMLGregorianCalendar.add(Duration)

Конструкторы

Конструктор Описание
Duration()

Конструктор по умолчанию без аргументов.

Методы

Модификатор и тип Метод Описание
abstract Duration add​(Duration rhs)

Вычисляет новую продолжительность, значение которой this+rhs.
abstract void addTo​(Calendar calendar)

Добавляет эту продолжительность к объекту Calendar.
void addTo​(Date date)

Добавляет эту продолжительность к объекту Date.
abstract int compare​(Duration duration)

Сравнение отношений частичного порядка с этим экземпляром Duration.
boolean equals​(Object duration)

Проверяет, имеет ли этот объект продолжительности такую же продолжительность, как другой объект Duration.
int getDays()

Получает значение поля DAYS как целое число, или 0, если оно не присутствует.
abstract Number getField​(DatatypeConstants.Field field)

Получает значение поля.
int getHours()

Получает значение поля HOURS как целое число, или 0, если оно не присутствует.
int getMinutes()

Получает значение поля MINUTES как целое число, или 0, если оно не присутствует.
int getMonths()

Получает значение поля MONTHS как целое число, или 0, если оно не присутствует.
int getSeconds()

Получает значение поля SECONDS как целое число, или 0, если оно не присутствует.
abstract int getSign()

Возвращает знак этой продолжительности в -1, 0 или 1.
long getTimeInMillis​(Calendar startInstant)

Возвращает длительность продолжительности в миллисекундах.
long getTimeInMillis​(Date startInstant)

Возвращает длительность продолжительности в миллисекундах.
QName getXMLSchemaType()

Возвращает имя типа данных XML Schema date/time, к которому отображается этот экземпляр.
int getYears()

Получает значение года этого Duration как int, или 0, если оно не присутствует.
abstract int hashCode()

Возвращает код хеширования, согласованный с определением метода equals.
boolean isLongerThan​(Duration duration)

Проверяет, строго ли этот объект продолжительности длиннее другого объекта Duration.
abstract boolean isSet​(DatatypeConstants.Field field)

Проверяет, установлено ли поле.
boolean isShorterThan​(Duration duration)

Проверяет, строго ли этот объект продолжительности короче другого объекта Duration.
Duration multiply​(int factor)

Вычисляет новую продолжительность, значение которой factor раз больше значения этой продолжительности.
abstract Duration multiply​(BigDecimal factor)

Вычисляет новую продолжительность, значение которой factor раз больше значения этой продолжительности.
abstract Duration negate()

Возвращает новый объект Duration со значением -this.
abstract Duration normalizeWith​(Calendar startTimeInstant)

Преобразует поля лет и месяцев в поле дней, используя определенный момент времени в качестве точки отсчета.
Duration subtract​(Duration rhs)

Вычисляет новую продолжительность, значение которой this-rhs.
String toString()

Возвращает представление String для этой Duration Object.

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

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Конструкторы

Duration

public Duration()

Конструктор по умолчанию без аргументов.

Примечание: всегда используйте DatatypeFactory для создания экземпляра Duration. Конструктор в этом классе не гарантирует создание объекта с согласованным состоянием и может быть удалён в будущем.

Методы

getXMLSchemaType

public QName getXMLSchemaType()

Возвращает имя типа XML Schema date/time, к которому сопоставляется этот экземпляр. Тип вычисляется на основе установленных полей, т.е. isSet(DatatypeConstants.Field field) == true.

Тип данных год месяц день час минута секунда
DatatypeConstants.DURATION X X X X X X
DatatypeConstants.DURATION_DAYTIME X X X X
DatatypeConstants.DURATION_YEARMONTH X X

Возвращает:
одно из следующих констант: DatatypeConstants.DURATION, DatatypeConstants.DURATION_DAYTIME или DatatypeConstants.DURATION_YEARMONTH.
Исключение:
IllegalStateException - Если комбинация установленных полей не соответствует одному из типов данных XML Schema date/time.

getSign

public abstract int getSign()

Возвращает знак этой продолжительности в -1, 0 или 1.

Возвращает:
-1, если продолжительность отрицательная, 0, если продолжительность равна нулю, и 1, если продолжительность положительная.

getYears

public int getYears()

Получает значение года этой Duration в виде int или 0 если не задано.

getYears() - это метод-обёртка для getField(DatatypeConstants.YEARS).

Поскольку возвращаемое значение является int, неверное значение будет возвращено для Duration с годами, выходящими за пределы диапазона int. Используйте getField(DatatypeConstants.YEARS) для предотвращения возможной потери точности.

Возвращает:
Если поле years присутствует, возвращает его значение в виде int, иначе возвращает 0.

getMonths

public int getMonths()

Получает значение поля MONTHS в виде целочисленного значения или 0, если оно не задано. Этот метод работает точно так же, как getYears(), за исключением того, что этот метод работает с полем MONTHS.

Возвращает:
Месяцы этой Duration.

getDays

public int getDays()

Получает значение поля DAYS в виде целочисленного значения или 0, если оно не задано. Этот метод работает точно так же, как getYears(), за исключением того, что этот метод работает с полем DAYS.

Возвращает:
Дни этой Duration.

getHours

public int getHours()

Получает значение поля HOURS в виде целочисленного значения или 0, если оно не задано. Этот метод работает точно так же, как getYears(), за исключением того, что этот метод работает с полем HOURS.

Возвращает:
Часы этой Duration.

getMinutes

public int getMinutes()

Получает значение поля MINUTES в виде целочисленного значения или 0, если оно не задано. Этот метод работает точно так же, как getYears(), за исключением того, что этот метод работает с полем MINUTES.

Возвращает:
Минуты этой Duration.

getSeconds

public int getSeconds()

Получает значение поля SECONDS в виде целочисленного значения или 0, если оно не задано. Этот метод работает точно так же, как getYears(), за исключением того, что этот метод работает с полем SECONDS.

Возвращает:
Секунды в целочисленном значении. Дробная часть секунд будет отброшена (например, если фактическое значение равно 2,5, этот метод возвращает 2).

getTimeInMillis

public long getTimeInMillis(Calendar startInstant)

Возвращает длительность продолжительности в миллисекундах.

Если поле секунд содержит больше цифр, чем порядок миллисекунд, они просто отбрасываются (или, другими словами, округляются до нуля). Например, для любого значения Calendar x,

new Duration("PT10.00099S").getTimeInMills(x) == 10000
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000

Обратите внимание, что этот метод использует метод addTo(Calendar), который может работать неправильно с объектами Duration с очень большими значениями в их полях. Подробности см. в методе addTo(Calendar).

Параметры:
startInstant - Длина месяца/года варьируется. startInstant используется для устранения этой вариации. В частности, этот метод возвращает разницу между startInstant и startInstant+duration
Возвращает:
миллисекунды между startInstant и startInstant плюс эта Duration
Исключение:
NullPointerException - если параметр startInstant равен null.

getTimeInMillis

public long getTimeInMillis(Date startInstant)

Возвращает длительность продолжительности в миллисекундах.

Если поле секунд содержит больше цифр, чем порядок миллисекунд, они просто отбрасываются (или, другими словами, округляются до нуля). Например, для любого значения Date x,

new Duration("PT10.00099S").getTimeInMills(x) == 10000
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000

Обратите внимание, что этот метод использует метод addTo(Date), который может работать неправильно с объектами Duration с очень большими значениями в их полях. Подробности см. в методе addTo(Date).

Параметры:
startInstant - Длина месяца/года варьируется. startInstant используется для устранения этой вариации. В частности, этот метод возвращает разницу между startInstant и startInstant+duration.
Возвращает:
миллисекунды между startInstant и startInstant плюс эта Duration
Исключение:
NullPointerException - Если параметр startInstant равен null.
См. также:
getTimeInMillis(Calendar)

getField

public abstract Number getField(DatatypeConstants.Field field)

Получает значение поля. Поля объекта продолжительности могут содержать произвольно большие значения. Поэтому этот метод предназначен для возврата объекта Number. В случае YEARS, MONTHS, DAYS, HOURS и MINUTES возвращаемое число будет неотрицательным целым числом. В случае секунд возвращаемое число может быть неотрицательным десятичным значением.

Параметры:
field - одна из шести констант поля (YEARS, MONTHS, DAYS, HOURS, MINUTES или SECONDS).
Возвращает:
Если указанное поле присутствует, этот метод возвращает ненулевой ненулевой объект Number, представляющий его значение. Если его нет, возвращается null. Для YEARS, MONTHS, DAYS, HOURS и MINUTES этот метод возвращает объект BigInteger. Для SECONDS этот метод возвращает объект BigDecimal.
Исключение:
NullPointerException - Если field null.

isSet

public abstract boolean isSet(DatatypeConstants.Field field)

Проверяет, установлено ли поле. Поле объекта продолжительности может быть или не быть установлено. Этот метод может использоваться для проверки наличия поля.

Параметры:
field - одна из шести констант поля (YEARS, MONTHS, DAYS, HOURS, MINUTES или SECONDS).
Возвращает:
true, если поле установлено. false, если нет.
Исключение:
NullPointerException - Если параметр field равен null.

add

public abstract Duration add(Duration rhs)

Вычисляет новую продолжительность, значение которой равно this+rhs.

Например,

"1 day" + "-3 days" = "-2 days"
 "1 year" + "1 day" = "1 year and 1 day"
 "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
 "15 hours" + "-3 days" = "-(2 days,9 hours)"
 "1 year" + "-1 day" = IllegalStateException

Поскольку нет способа осмысленно вычесть 1 день из 1 месяца, есть случаи, когда операция терпит неудачу в IllegalStateException.

Формально вычисление определяется следующим образом.

Во-первых, мы можем предположить, что две продолжительности, которые нужно сложить, являются положительными, не теряя общности (т.е., Duration, (-X)+Y=Y-X, X+(-Y)=X-Y, (-X)+(-Y)=-(X+Y)).

Сложение двух положительных продолжительностей определяется просто как полевое сложение, где пропущенные поля обрабатываются как 0.

Поле результирующей продолжительности будет не установлено только в том случае, если соответствующие поля двух входных продолжительностей не установлены.

Обратите внимание, что lhs.add(rhs) всегда будет успешным, если lhs.signum()*rhs.signum()!=-1 или оба они нормализованы.

Параметры:
rhs - Duration для добавления к этой Duration
Возвращает:
непустой допустимый объект Duration.
Исключение:
NullPointerException - Если параметр rhs равен null.
IllegalStateException - Если две продолжительности нельзя осмысленно сложить. Например, добавление минус одного дня к одному месяцу вызывает это исключение.
См. также:
subtract(Duration)

addTo

public abstract void addTo(Calendar calendar)

Добавляет этот интервал времени к объекту Calendar.

Вызывает Calendar.add(int,int) в порядке YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS и MILLISECONDS, если эти поля присутствуют. Поскольку класс Calendar использует int для хранения значений, существуют случаи, когда этот метод не будет работать корректно (например, если значения полей превышают диапазон int).

Кроме того, поскольку этот класс интервала времени — григорианский, этот метод не будет работать корректно, если данный объект Calendar основан на других системах календарей.

Любые дробные части этого объекта Duration интервала времени за миллисекундами будут просто проигнорированы. Например, если этот интервал времени равен "P1.23456S", то к SECONDS будет добавлено 1, к MILLISECONDS — 234, а остальное будет неиспользовано.

Обратите внимание, что поскольку Calendar.add(int, int) использует int, Duration со значениями за пределами диапазона int в своих полях приведет к переполнению/потере значащих разрядов в заданном объекте Calendar. XMLGregorianCalendar.add(Duration) предоставляет ту же основную операцию, что и этот метод, избегая проблем переполнения/потери значащих разрядов.

Parameters:
calendar - Объект календаря, значение которого будет изменено.
Throws:
NullPointerException - если параметр calendar равен null.

addTo

public void addTo(Date date)

Добавляет этот интервал времени к объекту Date.

Заданная дата сначала преобразуется в GregorianCalendar, затем интервал времени добавляется точно так же, как и в методе addTo(Calendar).

Обновленное мгновение времени затем преобразуется обратно в объект Date и используется для обновления заданного объекта Date.

Эта несколько избыточная вычислительная операция необходима для однозначного определения продолжительности месяцев и лет.

Parameters:
date - Объект даты, значение которого будет изменено.
Throws:
NullPointerException - если параметр date равен null.

subtract

public Duration subtract(Duration rhs)

Вычисляет новый интервал времени, значение которого равно this-rhs.

Например: 

"1 day" - "-3 days" = "4 days"
 "1 year" - "1 day" = IllegalStateException
 "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
 "15 hours" - "-3 days" = "3 days and 15 hours"
 "1 year" - "-1 day" = "1 year and 1 day"

Поскольку нет способа осмысленно вычесть 1 день из 1 месяца, в некоторых случаях операция завершается ошибкой в IllegalStateException.

Формально вычисление определяется следующим образом. Сначала мы можем предположить, что оба интервала времени положительны, не теряя общности. (т.е. (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y)).

Затем два интервала времени вычитаются полем за полем. Если знак любого ненулевого поля F отличается от знака самого значимого поля, 1 (если F отрицательно) или -1 (в противном случае) заимствуется из следующей большей единицы F.

Этот процесс повторяется до тех пор, пока все ненулевые поля не будут иметь одинаковый знак.

Если заимствование происходит в поле дней (другими словами, если вычисление должно заимствовать 1 или -1 месяц для компенсации дней), то вычисление завершается ошибкой с IllegalStateException.

Parameters:
rhs - Duration для вычитания из этого Duration.
Returns:
Новый интервал времени, созданный путем вычитания rhs из этого Duration.
Throws:
IllegalStateException - Если два интервала времени не могут быть осмысленно вычтены. Например, вычитание одного дня из одного месяца вызывает эту ошибку.
NullPointerException - Если параметр rhs равен null.
See Also:
add(Duration)

multiply

public Duration multiply(int factor)

Вычисляет новый интервал времени, значение которого factor в разы больше значения этого интервала времени.

Этот метод предоставлен для удобства. Он функционально эквивалентен следующему коду: 

multiply(new BigDecimal(String.valueOf(factor)))
Parameters:
factor - Множитель, определяющий во сколько раз больше новый интервал времени.
Returns:
Новый интервал времени, который factor раз длиннее, чем этот Duration.
See Also:
multiply(BigDecimal)

multiply

public abstract Duration multiply(BigDecimal factor)

Вычисляет новый интервал времени, значение которого factor в разы больше значения этого интервала времени.

Например, 

"P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException

Поскольку класс Duration неизменяемый, этот метод не изменяет значение этого объекта. Он просто вычисляет новый объект Duration и возвращает его.

Операция будет выполняться полем за полем с точностью BigDecimal. Поскольку все поля, кроме секунд, ограничены целыми числами, любая дробь, полученная в ходе вычисления, будет переноситься к следующей меньшей единице. Например, если вы умножите "P1D" (1 день) на "0.5", то это будет 0.5 дня, что переносится в "PT12H" (12 часов). Когда дроби месяцев не могут осмысленно переноситься в дни или годы в месяцы, это приведет к ошибке IllegalStateException. Например, если вы умножите один месяц на 0.5.

Чтобы избежать IllegalStateException, используйте метод normalizeWith(Calendar) для удаления полей лет и месяцев.

Parameters:
factor - на которое умножить
Returns:
возвращает непустой допустимый объект Duration
Throws:
IllegalStateException - если операция производит дробь в поле месяцев.
NullPointerException - если параметр factor равен null.

negate

public abstract Duration negate()

Возвращает новый объект Duration, значение которого равно -this.

Поскольку класс Duration неизменяемый, этот метод не изменяет значение этого объекта. Он просто вычисляет новый объект Duration и возвращает его.

Returns:
всегда возвращает непустой допустимый объект Duration.

normalizeWith

public abstract Duration normalizeWith(Calendar startTimeInstant)

Преобразует поля лет и месяцев в поле дней, используя определенный момент времени в качестве точки отсчета.

Например, интервал времени в один месяц нормализуется до 31 дня, если начальный момент времени — "8 июля 2003 г., 17:40:32".

Формально вычисление выполняется следующим образом:

  1. заданный объект Calendar клонируется
  2. поля лет, месяцев и дней будут добавлены к объекту Calendar с использованием метода Calendar.add(int,int)
  3. разница между двумя Calendar вычисляется в миллисекундах и преобразуется в дни, если остаток возникает из-за перехода на летнее/зимнее время, он отбрасывается
  4. вычисленные дни вместе с часами, минутами и секундами этого объекта Duration используются для создания нового объекта Duration.

Обратите внимание, что поскольку класс Calendar использует int для хранения значения года и месяца, этот метод может привести к неожиданному результату, если этот объект Duration содержит очень большое значение в полях лет или месяцев.

Parameters:
startTimeInstant - Calendar точка отсчета.
Returns:
Duration лет и месяцев этого объекта Duration в днях.
Throws:
NullPointerException - если параметр startTimeInstant равен null.

compare

public abstract int compare(Duration duration)

Сравнение отношений частичного порядка с этим экземпляром Duration.

Результат сравнения должен соответствовать W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration.

Возвращаемое значение:

Parameters:
duration - для сравнения
Returns:
отношение между this Duration и параметром duration как DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER или DatatypeConstants.INDETERMINATE.
Throws:
UnsupportedOperationException - Если внутренняя реализация не может разумно обработать запрос, например, W3C XML Schema допускает произвольно большие/маленькие/точные значения, запрос может быть недоступным для реализации.
NullPointerException - если duration равен null.
See Also:
isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

Проверяет, является ли этот объект продолжительности строго длиннее другого объекта Duration.

Продолжительность X «длиннее», чем Y, тогда и только тогда, когда X > Y, как определено в разделе 3.2.6.2 спецификации XML Schema 1.0.

Например, «P1D» (один день) > «PT12H» (12 часов) и «P2Y» (два года) > «P23M» (23 месяца).

Параметры:
duration - Duration для проверки этого Duration.
Возвращает:
true, если продолжительность, представленная этим объектом, длиннее заданной продолжительности. false в противном случае.
Выбрасывает:
UnsupportedOperationException - Если основная реализация не может разумно обработать запрос, например, W3C XML Schema допускает произвольно большие/малые/точные значения, запрос может быть вне возможностей реализации.
NullPointerException - Если duration равно null.
См. также:
isShorterThan(Duration), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

Проверяет, является ли этот объект продолжительности строго короче другого объекта Duration.

Параметры:
duration - Duration для проверки этого Duration.
Возвращает:
true если duration параметр короче этого Duration, иначе false.
Выбрасывает:
UnsupportedOperationException - Если основная реализация не может разумно обработать запрос, например, W3C XML Schema допускает произвольно большие/малые/точные значения, запрос может быть вне возможностей реализации.
NullPointerException - если duration равно null.
См. также:
isLongerThan(Duration duration), compare(Duration duration)

equals

public boolean equals(Object duration)

Проверяет, имеет ли этот объект продолжительности ту же продолжительность, что и другой объект Duration.

Например, «P1D» (1 день) равен «PT24H» (24 часа).

Продолжительность X равна Y тогда и только тогда, когда временные моменты t+X и t+Y совпадают для всех тестовых временных моментов, указанных в разделе 3.2.6.2 спецификации XML Schema 1.0.

Обратите внимание, что существуют случаи, когда два объекта Duration «несравнимы» друг с другом, например, один месяц и 30 дней. Например, 

!new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
Переопределяет:
equals в классе Object
Параметры:
duration - Объект для сравнения с этим Duration.
Возвращает:
true если эта продолжительность имеет такую же длину, как duration. false если duration равно null, не является объектом Duration или его длина отличается от этой продолжительности.
Выбрасывает:
UnsupportedOperationException - Если основная реализация не может разумно обработать запрос, например, W3C XML Schema допускает произвольно большие/малые/точные значения, запрос может быть вне возможностей реализации.
См. также:
compare(Duration duration)

hashCode

public abstract int hashCode()

Возвращает код хэширования, соответствующий определению метода equals.

Переопределяет:
hashCode в классе Object
Возвращает:
значение кода хэширования для этого объекта.
См. также:
Object.hashCode()

toString

public String toString()

Возвращает строковое представление этого объекта Duration Object.

Результат форматируется в соответствии со спецификацией XML Schema 1.0 и всегда может быть повторно парсирован в эквивалентную продолжительность Duration Object с помощью DatatypeFactory.newDuration(String lexicalRepresentation).

Формально, следующее выполняется для любого объекта Duration Object x: 

new Duration(x.toString()).equals(x)
Переопределяет:
toString в классе Object
Возвращает:
Не-null действительное строковое представление этого Duration.

© 1993, 2020, 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/11/docs/api/java.xml/javax/xml/datatype/Duration.html

Spec-Zone .ru
спецификации, руководства, описания, API