Класс Duration

public Duration()

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

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

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

public abstract int getSign()

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

public int getYears()

Возвращает значение поля лет этой Duration в виде int или 0, если оно отсутствует.

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

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

public int getMonths()

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

public int getDays()

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

public int getHours()

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

public int getMinutes()

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

public int getSeconds()

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

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)

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

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.

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

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

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

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

Обратите внимание, что 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", к SECONDS будет прибавлено 1, к MILLISECONDS — 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.

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

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

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

Если заимствование происходит в поле дней (то есть если для компенсации дней необходимо заимствовать 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.

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

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.

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

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

public boolean isShorterThan(Duration duration)

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

public boolean equals(Object duration)

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

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

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

Обратите внимание, что в некоторых случаях две Durations несравнимы, например месяц и 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()

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

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

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

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