Класс Duration

public Duration()

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

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

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.

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

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

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

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

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

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