Класс Duration

java.lang.Object
- javax.xml.datatype.Duration

public abstract class Duration
extends Object

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

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

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

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

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

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

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

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

Подробности о порядке отношений между Duration объектами см. в методе isLongerThan(Duration).

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

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

Также не предусмотрено деление интервала на число, потому что класс 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, которому соответствует этот экземпляр.
`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`.
`abstract Duration`	`multiply(BigDecimal factor)` Вычисляет новый интервал, значение которого `factor` длиннее значения этого интервала.
`Duration`	`multiply(int 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 для даты/времени, к которому сопоставляется этот экземпляр. Тип вычисляется на основе установленных полей, т.е. isSet(DatatypeConstants.Field field) == true.

Обязательные поля для типов данных даты/времени XML Schema 1.0. (часовой пояс необязателен для всех типов данных даты/времени)
Тип данных	год	месяц	день	час	минута	секунда
`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.

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)

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

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

isSet

public abstract boolean isSet(DatatypeConstants.Field field)

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

Параметры:: 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)).

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

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

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

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

addTo

public abstract void addTo(Calendar calendar)

Добавляет эту продолжительность к объекту Calendar.

Вызывает Calendar.add(int,int) в порядке ЛЕТ, МЕСЯЦЕВ, ДНЕЙ, ЧАСОВ, МИНУТ, СЕКУНД и МИЛЛИСЕКУНД, если эти поля присутствуют. Поскольку класс Calendar использует int для хранения значений, в некоторых случаях этот метод может работать неправильно (например, если значения полей превышают диапазон int).

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

Любые дробные части этого объекта Duration после миллисекунд просто игнорируются. Например, если эта продолжительность «P1.23456S», то к СЕКУНДАМ добавляется 1, к МИЛЛИСЕКУНДАМ — 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.

Формально вычисление определяется следующим образом. Сначала можно предположить, что две продолжительности Duration положительные, не теряя общности. (т.е., (-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:: Новая Duration созданная путём вычитания 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.

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

normalizeWith

public abstract Duration normalizeWith(Calendar startTimeInstant)

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

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

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

заданный объект Calendar клонируется
поля лет, месяцев и дней будут добавлены к объекту Calendar с помощью метода Calendar.add(int,int)
разница между двумя объектами Calendar вычисляется в миллисекундах и преобразуется в дни, если остаток возникает из-за летнего/зимнего времени, он отбрасывается
вычисленные дни, а также поля часов, минут и секунд объекта 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.

Возврат:

DatatypeConstants.LESSER если этот Duration короче, чем параметр duration
DatatypeConstants.EQUAL если этот Duration равен параметру duration
DatatypeConstants.GREATER если этот Duration длиннее, чем параметр duration
DatatypeConstants.INDETERMINATE если нельзя определить однозначное отношение частичного порядка

Параметры:: duration - для сравнения
Возвращает:: отношение между this Durationи duration параметром как DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER или DatatypeConstants.INDETERMINATE.
Выбрасывает:: UnsupportedOperationException - Если внутренняя реализация не может разумно обработать запрос, например, W3C XML Schema допускает произвольно большие/малые/точные значения, запрос может быть недоступен для реализации.; NullPointerException - если duration является null.
См. также:: 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.