Класс Duration

public Duration()

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

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

public QName getXMLSchemaType()

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

Необходимые поля для типов данных XML Schema 1.0 Date/Time.
(часовой пояс необязателен для всех типов данных 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)

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

Если поле секунд содержит больше цифр, чем порядок миллисекунд, они просто отбрасываются (или, другими словами, округляются до нуля.) Например, для любого значения Calendar 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)

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

public abstract boolean isSet(DatatypeConstants.Field field)

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

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) в порядке YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, и MILLISECONDS, если эти поля присутствуют. Поскольку класс Calendar использует int для хранения значений, в некоторых случаях этот метод не будет работать правильно (например, если значения полей превышают диапазон int).

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

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

Обратите внимание, что так как 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) для удаления полей years и months.

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 Part 2, Section 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)