Класс 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()

Получает значение поля 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)

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

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

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

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

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

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

Обратите внимание, что 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.

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

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

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

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

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

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