public abstract class Duration extends Object
Неизменное представление отрезка времени как определено в спецификации XML-схемы 1.0 W3C.
Объект Продолжительности представляет период Грегорианского времени, которое состоит из шести полей (годы, месяцы, дни, часы, минуты, и секунды) плюс знак (+/-) поле.
Первые пять полей имеют неотрицательный (> =0) целые числа или нуль (который представляет это, поле не устанавливается), и у поля секунд есть неотрицательное десятичное число или нуль. Знак минус указывает на отрицательную продолжительность.
Этот class обеспечивает много методов, которые облегчают использовать для типа данных продолжительности XML-схемы 1.0 с опечатками.
Продолжительность возражает, только имеют частичный порядок, где два значения A и B возможно также:
Например, 30 дней не могут быть обоснованно по сравнению с одним месяцем. compare(Duration duration)
метод реализует это отношение.
См. isLongerThan(Duration)
метод для деталей об отношении порядка среди Duration
объекты.
Этот class обеспечивает ряд основных арифметических операций, таких как дополнение, вычитание и умножение. Поскольку у продолжительностей нет полного порядка, работа могла перестать работать для некоторых комбинаций операций. Например, невозможно вычесть 15 дней с 1 месяца. См. javadoc тех методов для подробных условий, где это могло произойти.
Кроме того, подразделению продолжительности числом не предоставляют потому что Duration
class может только иметь дело с конечными десятичными числами точности. Например, нельзя представить 1 секунду, разделенную на 3.
Однако, Вы могли заменить подразделением 3 с умножением на числа такой как 0.3 или 0.333.
Поскольку некоторые операции Duration
положиться Calendar
даже при том, что Duration
может содержать очень большие или очень маленькие значения, некоторые из методов, возможно, не работают правильно над таким Duration
s. Закрепленные методы документируют свою зависимость от Calendar
.
XMLGregorianCalendar.add(Duration)
Конструктор и Описание |
---|
Duration()
Значение по умолчанию конструктор без аргументов.
|
Модификатор и Тип | Метод и Описание |
---|---|
abstract Duration |
add(Duration rhs)
Вычисляет новую продолжительность, значение которой
this+rhs . |
abstract void |
addTo(Calendar calendar)
Добавляет эта продолжительность к a
Calendar объект. |
void |
addTo(Date date)
Добавляет эта продолжительность к a
Date объект. |
abstract int |
compare(Duration duration)
Сравнение отношения частичного порядка с этим
Duration экземпляр. |
boolean |
equals(Object duration)
Проверки, если у этого объекта продолжительности есть та же самая продолжительность как другой
Duration объект. |
int |
getDays()
Получает значение поля DAYS как целочисленное значение, или 0 если не существующий.
|
abstract Number |
getField(DatatypeConstants.Field field)
Получает значение поля.
|
int |
getHours()
Получает значение поля HOURS как целочисленное значение, или 0 если не существующий.
|
int |
getMinutes()
Получает значение поля MINUTES как целочисленное значение, или 0 если не существующий.
|
int |
getMonths()
Получает значение поля MONTHS как целочисленное значение, или 0 если не существующий.
|
int |
getSeconds()
Получает значение поля SECONDS как целочисленное значение, или 0 если не существующий.
|
abstract int |
getSign()
Возвращает знак этой продолжительности в-1,0, или 1.
|
long |
getTimeInMillis(Calendar startInstant)
Возвращает продолжительность продолжительности в миллисекундах.
|
long |
getTimeInMillis(Date startInstant)
Возвращает продолжительность продолжительности в миллисекундах.
|
QName |
getXMLSchemaType()
Возвратите имя типа даты/времени XML-схемы, на который отображается этот экземпляр.
|
int |
getYears()
Получите значение лет этого
Duration как int или 0 если не существующий. |
abstract int |
hashCode()
Возвращается хэш-код, непротиворечивый с определением, равняется методу.
|
boolean |
isLongerThan(Duration duration)
Проверки, если этот объект продолжительности строго более длинен чем другой
Duration объект. |
abstract boolean |
isSet(DatatypeConstants.Field field)
Проверки, если поле устанавливается.
|
boolean |
isShorterThan(Duration duration)
Проверки, если этот объект продолжительности строго короче чем другой
Duration объект. |
abstract Duration |
multiply(BigDecimal factor)
Вычисляет новую продолжительность, значение которой
factor времена дольше чем значение этой продолжительности. |
Продолжительность |
multiply(int factor)
Вычисляет новую продолжительность, значение которой
factor времена дольше чем значение этой продолжительности. |
abstract Duration |
negate()
Возвращает новое
Duration возразите, чье значение -this . |
abstract Duration |
normalizeWith(Calendar startTimeInstant)
Преобразовывает годы и поля месяцев в дневное поле при использовании определенного момента времени как контрольная точка.
|
Продолжительность |
subtract(Duration rhs)
Вычисляет новую продолжительность, значение которой
this-rhs . |
Строка |
toString()
Возвраты a
String представление этого Duration Object . |
public Duration()
Отметьте: Всегда используйте DatatypeFactory
создать экземпляр Duration
. Конструктор на этом class, как могут гарантировать, не произведет объект с непротиворечивым состоянием и может быть удален в будущем.
public QName getXMLSchemaType()
Возвратите имя типа даты/времени XML-схемы, на который отображается этот экземпляр. Тип вычисляется основанный на полях, которые устанавливаются, то есть. isSet(DatatypeConstants.Field field)
== true
.
Обязательные поля для Типов данных Даты/Времени XML-схемы 1.0. (часовой пояс является дополнительным для всех типов данных даты/времени), |
||||||
---|---|---|---|---|---|---|
Тип данных | год | месяц | день | час | минута | второй |
DatatypeConstants.DURATION |
X | X | X | X | X | X |
DatatypeConstants.DURATION_DAYTIME |
X | X | X | X | ||
DatatypeConstants.DURATION_YEARMONTH |
X | X |
DatatypeConstants.DURATION
, DatatypeConstants.DURATION_DAYTIME
или DatatypeConstants.DURATION_YEARMONTH
.IllegalStateException
- Если комбинация полей набора не соответствует один из типов данных даты/времени XML-схемы.public abstract int getSign()
public int getYears()
Получите значение лет этого Duration
как int
или 0
если не существующий.
getYears()
метод удобства для getField(DatatypeConstants.YEARS)
.
Поскольку возвращаемое значение int
, неправильное значение будет возвращено для Duration
s с годами, которые проходят вне диапазона int
. Использовать getField(DatatypeConstants.YEARS)
избегать возможной потери точности.
int
, еще возвратитесь 0
.public int getMonths()
getYears()
за исключением того, что этот метод работает над полем MONTHS.Duration
.public int getDays()
getYears()
за исключением того, что этот метод работает над полем DAYS.Duration
.public int getHours()
getYears()
за исключением того, что этот метод работает над полем HOURS.Duration
.public int getMinutes()
getYears()
за исключением того, что этот метод работает над полем MINUTES.Duration
.public int getSeconds()
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)
метод для деталей.
startInstant
- Продолжительность месяца/года изменяется. startInstant
используется, чтобы снять неоднозначность этого различия. Определенно, этот метод возвращает различие между startInstant
и startInstant+duration
startInstant
и startInstant
плюс это Duration
NullPointerException
- если startInstant
параметр является нулем.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)
метод для деталей.
startInstant
- Продолжительность месяца/года изменяется. startInstant
используется, чтобы снять неоднозначность этого различия. Определенно, этот метод возвращает различие между startInstant
и startInstant+duration
.startInstant
и startInstant
плюс это Duration
NullPointerException
- Если startInstant параметр является нулем.getTimeInMillis(Calendar)
public abstract Number getField(DatatypeConstants.Field field)
Number
объект. В случае ЛЕТ, МЕСЯЦЕВ, ДНЕЙ, ЧАСОВ, и МИНУТ, возвращенное число будет неотрицательным целым числом. В случае секунд возвращенное число может быть неотрицательным десятичным значением.field
- одна из шести Полевых констант (ГОДЫ, МЕСЯЦЫ, ДНИ, ЧАСЫ, МИНУТЫ, или СЕКУНДЫ.)Number
объект, который представляет его значение. Если это не присутствует, возвратите нуль. В течение многих ЛЕТ, МЕСЯЦЕВ, ДНЕЙ, ЧАСОВ, и МИНУТ, этот метод возвращает a BigInteger
объект. В течение многих СЕКУНД этот метод возвращает a BigDecimal
.NullPointerException
- Если field
null
.public abstract boolean isSet(DatatypeConstants.Field field)
field
- одна из шести Полевых констант (ГОДЫ, МЕСЯЦЫ, ДНИ, ЧАСЫ, МИНУТЫ, или СЕКУНДЫ.)NullPointerException
- Если полевой параметр является нулем.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
s, чтобы быть добавленными оба положительны, не теряя общность (то есть, (-X)+Y=Y-X
, X+(-Y)=X-Y
, (-X)+(-Y)=-(X+Y)
)
Добавление два положительный Duration
s просто определяются как поле полевым дополнением, где недостающие поля обрабатываются как 0.
Поле получающегося Duration
будет сброшен, если и только если соответствующие поля два вводят Duration
s сбрасываются.
Отметьте это lhs.add(rhs)
будет всегда успешно если lhs.signum()*rhs.signum()!=-1
или они оба нормализуются.
rhs
- Duration
добавить к этому Duration
NullPointerException
- Если rhs параметр является нулем.IllegalStateException
- Если две продолжительности не могут быть обоснованно добавлены. Например, добавление отрицательного однажды к одному месяцу вызывает это исключение.subtract(Duration)
public abstract void addTo(Calendar calendar)
Calendar
объект. Вызовы Calendar.add(int,int)
в порядке ЛЕТ, МЕСЯЦЕВ, ДНЕЙ, ЧАСОВ, МИНУТ, СЕКУНД, и МИЛЛИСЕКУНД, если те поля присутствуют. Поскольку Calendar
class использует интервал, чтобы содержать значения, есть случаи, где этот метод не будет работать правильно (например, если значения полей превысят диапазон интервала),
Кроме того, начиная с этой продолжительности class является Грегорианской продолжительностью, этот метод не будет работать правильно если данный Calendar
объект основан на некоторых других календарных системах.
Любые дробные части этого Duration
объект вне миллисекунд будет просто проигнорирован. Например, если эта продолжительность является "P1.23456S", то 1 добавляется к СЕКУНДАМ, 234 добавляется к МИЛЛИСЕКУНДАМ, и остальные будут неиспользованы.
Отметьте это потому что Calendar.add(int, int)
использует int
, Duration
со значениями вне диапазона int
в его полях вызовет переполнение/потерю значимости к данному Calendar
. XMLGregorianCalendar.add(Duration)
обеспечивает ту же самую основную работу как этот метод, избегая проблем переполнения/потери значимости.
calendar
- Календарный объект, значение которого будет изменено.NullPointerException
- если календарный параметр является нулем.public void addTo(Date date)
Date
объект. Данная дата сначала преобразовывается в a GregorianCalendar
, тогда продолжительность добавляется точно как addTo(Calendar)
метод.
Обновленный момент времени тогда преобразовывается назад в a Date
возразите и используемый, чтобы обновить данный Date
объект.
Это несколько избыточное вычисление необходимо, чтобы однозначно определить продолжительность месяцев и лет.
date
- Объект даты, значение которого будет изменено.NullPointerException
- если параметр даты является нулем.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
s оба положительны, не теряя общность. (то есть, (-X)-Y=-(X+Y)
, X-(-Y)=X+Y
, (-X)-(-Y)=-(X-Y)
)
Затем две продолжительности являются вычтенным полем полем. Если знак любого ненулевого поля F
отличается от знака старшего значащего поля, 1 (если F
отрицательно), или-1 (иначе) будет заимствован от следующего большего модуля F
.
Этот процесс повторяется, пока у всех ненулевых полей нет того же самого знака.
Если заимствовать происходит в дневном поле (другими словами, если вычисление должно заимствовать 1 или-1 месяц, чтобы компенсировать дни), то сбои вычисления, бросая IllegalStateException
.
rhs
- Duration
вычитать из этого Duration
.Duration
создаваемый из вычитания rhs
от этого Duration
.IllegalStateException
- Если две продолжительности не могут быть обоснованно вычтены. Например, вычитание одного дня с одного месяца вызывает это исключение.NullPointerException
- Если rhs параметр является нулем.add(Duration)
public Duration multiply(int factor)
Вычисляет новую продолжительность, значение которой factor
времена дольше чем значение этой продолжительности.
Этот метод обеспечивается для удобства. Это функционально эквивалентно следующему коду:
multiply(new BigDecimal(String.valueOf(factor)))
factor
- Факторные времена дольше новых Duration
создать.Duration
это factor
времена дольше чем это Duration
.multiply(BigDecimal)
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
class является неизменным, этот метод не изменяет значение этого объекта. Это просто вычисляет новый объект Продолжительности и возвращает это.
Работа будет выполняемым полем полем с точностью BigDecimal
. Так как все поля кроме секунд ограничиваются, чтобы содержать целые числа, любую часть, произведенную вычислением, перенесут вниз к следующему более низкому модулю. Например, если Вы умножите "P1D" (1 день) с "0.5", то тогда это будут 0.5 дня, которые перенесут вниз к "PT12H" (12 часов). Когда части месяца нельзя будет обоснованно перенести вниз ко дням, или году к месяцам, это вызовет IllegalStateException
быть брошенным. Например, если Вы многократный один месяц 0.5.
Избегать IllegalStateException
, используйте normalizeWith(Calendar)
метод, чтобы удалить годы и поля месяцев.
factor
- умножитьсяDuration
объектIllegalStateException
- если работа производит часть в поле месяцев.NullPointerException
- если factor
параметр null
.public abstract Duration negate()
Duration
возразите, чье значение -this
. Начиная с Duration
class является неизменным, этот метод не изменяет значение этого объекта. Это просто вычисляет новый объект Продолжительности и возвращает это.
Duration
объект.public abstract Duration normalizeWith(Calendar startTimeInstant)
Преобразовывает годы и поля месяцев в дневное поле при использовании определенного момента времени как контрольная точка.
Например, продолжительность одного месяца нормализует к 31 дню, данному экземпляр времени запуска "8-ого июля 2003, 17:40:32".
Формально, вычисление делается следующим образом:
Calendar
объект при использовании Calendar.add(int,int)
методОтметьте, что начиная с Календаря class использует int
чтобы содержать значение года и месяца, этот метод может привести к неожиданному результату, если этот объект продолжительности содержит очень большое значение в годах или поля месяцев.
startTimeInstant
- Calendar
контрольная точка.Duration
из лет и месяцев этого Duration
как дни.NullPointerException
- Если startTimeInstant параметр является нулем.public abstract int compare(Duration duration)
Сравнение отношения частичного порядка с этим Duration
экземпляр.
Результат сравнения должен быть в соответствии с
Возвратитесь:
DatatypeConstants.LESSER
если это Duration
короче чем duration
параметрDatatypeConstants.EQUAL
если это Duration
равно duration
параметрDatatypeConstants.GREATER
если это Duration
более длинно чем duration
параметрDatatypeConstants.INDETERMINATE
если заключительное отношение частичного порядка не может быть определеноduration
- сравнитьсяthis
Duration
и duration
параметр как DatatypeConstants.LESSER
, DatatypeConstants.EQUAL
, DatatypeConstants.GREATER
или DatatypeConstants.INDETERMINATE
.UnsupportedOperationException
- Если базовая реализация не может разумно обработать запрос, например, XML-схема W3C учитывает произвольно большие/маленькие/точные значения, запрос может быть вне возможности реализаций.NullPointerException
- если duration
null
.isShorterThan(Duration)
, isLongerThan(Duration)
public boolean isLongerThan(Duration duration)
Проверки, если этот объект продолжительности строго более длинен чем другой Duration
объект.
Продолжительность X "более длительна" чем Y если и только если X> Y как определено в разделе 3.2.6.2 из спецификации XML-схемы 1.0.
Например, "P1D" (однажды)> "PT12H" (12 часов) и "P2Y" (два года)> "P23M" (23 месяца).
duration
- Duration
протестировать это Duration
против.UnsupportedOperationException
- Если базовая реализация не может разумно обработать запрос, например, XML-схема W3C учитывает произвольно большие/маленькие/точные значения, запрос может быть вне возможности реализаций.NullPointerException
- Если duration
нуль.isShorterThan(Duration)
, compare(Duration duration)
public boolean isShorterThan(Duration duration)
Проверки, если этот объект продолжительности строго короче чем другой Duration
объект.
duration
- Duration
протестировать это Duration
против.true
если duration
параметр короче чем это Duration
, еще false
.UnsupportedOperationException
- Если базовая реализация не может разумно обработать запрос, например, XML-схема W3C учитывает произвольно большие/маленькие/точные значения, запрос может быть вне возможности реализаций.NullPointerException
- если duration
нуль.isLongerThan(Duration duration)
, compare(Duration duration)
public boolean equals(Object duration)
Проверки, если у этого объекта продолжительности есть та же самая продолжительность как другой Duration
объект.
Например, "P1D" (1 день) равен "PT24H" (24 часа).
Продолжительность X равна Y, если и только если момент времени t+X и t+Y является тем же самым в течение всех тестовых моментов времени, определенных в разделе 3.2.6.2 из спецификации XML-схемы 1.0.
Отметьте, что есть случаи где два Duration
s "несравнимы" друг с другом, как один месяц и 30 дней. Например,
!new Duration("P1M").isShorterThan(new Duration("P30D")) !new Duration("P1M").isLongerThan(new Duration("P30D")) !new Duration("P1M").equals(new Duration("P30D"))
equals
в class Object
duration
- Объект сравнить это Duration
против.true
если эта продолжительность является той же самой длиной как duration
. false
если duration
null
, не a Duration
объект, или его длина отличается от этой продолжительности.UnsupportedOperationException
- Если базовая реализация не может разумно обработать запрос, например, XML-схема W3C учитывает произвольно большие/маленькие/точные значения, запрос может быть вне возможности реализаций.compare(Duration duration)
public abstract int hashCode()
hashCode
в class Object
Object.hashCode()
public String toString()
Возвраты a String
представление этого Duration
Object
.
Результат форматируется согласно спецификации XML-схемы 1.0 и может всегда анализироваться назад позже в эквивалент Duration
Object
DatatypeFactory.newDuration(String lexicalRepresentation)
.
Формально, следующее содержит для любого Duration
Object
x:
new Duration(x.toString()).equals(x)
Для дальнейшей ссылки API и документации разработчика, см. Java Документация SE. Та документация содержит более подробные, предназначенные разработчиком описания, с концептуальными краткими обзорами, определениями сроков, обходных решений, и рабочих примеров кода.
Авторское право © 1993, 2013, Oracle и/или его филиалы. Все права защищены.
Проект сборка-b92