Класс Duration

public Duration()

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

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

public QName getXMLSchemaType()

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

Необходимые поля для типов данных Date/Time XML Schema 1.0.
(часовой пояс необязателен для всех типов данных date/time)

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

public abstract int getSign()

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

public int getYears()

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

getYears() — это метод для удобства работы с getField(DatatypeConstants.YEARS).

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

public int getMonths()

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

public int getDays()

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

public int getHours()

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

public int getMinutes()

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

public int getSeconds()

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

public long getTimeInMillis(Calendar startInstant)

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

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

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

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

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).

public abstract Number getField(DatatypeConstants.Field field)

Получает значение поля. Поля объекта продолжительности могут содержать произвольно большие значения. Поэтому этот метод предназначен для возврата объекта Number. В случае ЛЕТ, МЕСЯЦЕВ, ДНЕЙ, ЧАСОВ и МИНУТ возвращаемое число будет неотрицательным целым числом. В случае секунд возвращаемое число может быть неотрицательным десятичным значением.

public abstract boolean isSet(DatatypeConstants.Field field)

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

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 или оба из них нормализованы.

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) предоставляет ту же базовую операцию, что и этот метод, но избегает проблем с переполнением/обнулением.

public void addTo(Date date)

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

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

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

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

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.

public Duration multiply(int factor)

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

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

 multiply(new BigDecimal(String.valueOf(factor)))
 

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) для удаления полей лет и месяцев.

public abstract Duration negate()

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

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

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 содержит очень большое значение в полях года или месяца.

public abstract int compare(Duration duration)

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

Результат сравнения должен соответствовать W3C XML Schema 1.0 Часть 2, Раздел 3.2.7.6.2, Отношение порядка на продолжительности.

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

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

public boolean isLongerThan(Duration duration)

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

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

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

public boolean isShorterThan(Duration duration)

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

public boolean equals(Object duration)

Проверяет, имеет ли этот объект 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"))
 

public abstract int hashCode()

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

public String toString()

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

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

Формально, для любого объекта Duration Object x:

 new Duration(x.toString()).equals(x)