javax.xml.datatype
類別 Duration

java.lang.Object
  javax.xml.datatype.Duration

public abstract class Duration
extends Object

W3C XML 網要 1.0 規範中定義的時間範圍的不可變表示形式。

Duration 物件表示一段陽曆時間，它由六個欄位（years、months、days、hours、minutes 和 seconds）加上符號 (+/-) 欄位組成。

前五個欄位為非負 (>=0) 整數或 null（表示不設置欄位），seconds 欄位為非負小數或 null。負號指示負的持續時間。

此類別提供大量的方法，使 XML 網要 1.0 及勘誤中的 duration 資料型別的使用更簡單。

順序關係

Duration 物件只有部分順序，其中值 A 和 B 可以是以下任一順序：

1. A<B（A 比 B 短）
2. A>B（A 比 B 長）
3. A==B（A 和 B 的持續時間相同）
4. A<>B（A 和 B 之間的比較是不確定的）

例如，將 30 天與一個月比較沒有意義。compare(Duration duration) 方法實作此關係。

有關 Duration 物件之間順序關係的詳細資訊，請參閱 isLongerThan(Duration) 方法。

對 Duration 的操作

此類別提供一組基本的算術運算，如加、減和乘。因為持續時間沒有整體順序，對一些組合操作，操作可能失敗。例如，不能從 1 個月減去 15 天。有關發生此情形的詳細情況，請參閱這些方法的 javadoc。

另外，不提供持續時間除以數字的除法，因為 Duration 類別僅處理有限精度的十進制數字。例如，無法表示 1 秒除以 3。

但可以用乘以數字（如 0.3 或 0.333）替代除以 3 的除法。

允許值的範圍

即使 Duration 可以保持非常大或非常小的值，因為某些 Duration 的操作依賴於 Calendar，所以一些方法不能在此類別 Duration 上正常工作。受影響的方法記錄其對 Calendar 的依賴。

從以下版本開始：

1.5

另請參見：

XMLGregorianCalendar.add(Duration)

建構子摘要

Duration()
預設的無參數建構子。

方法摘要

abstract Duration	add(Duration rhs) 計算值為 this+rhs 的新持續時間。
abstract void	addTo(Calendar calendar) 將此持續時間添加到 Calendar 物件。
void	addTo(Date date) 將此持續時間添加到 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 表示的 years 值，如果不存在，則值為 0。
abstract int	hashCode() 返回與 equals 方法的定義一致的雜湊碼。
boolean	isLongerThan(Duration duration) 檢查此持續時間物件是否嚴格長於另一個 Duration 物件。
abstract boolean	isSet(DatatypeConstants.Field field) 檢查是否設置了欄位。
boolean	isShorterThan(Duration duration) 檢查此持續時間物件是否嚴格短於另一個 Duration 物件。
abstract Duration	multiply(BigDecimal factor) 計算新的持續時間，其值是此持續時間值的 factor 倍。
Duration	multiply(int factor) 計算新的持續時間，值為此持續時間值的 factor 倍。
abstract Duration	negate() 返回值為 -this 的新 Duration 物件。
abstract Duration	normalizeWith(Calendar startTimeInstant) 通過使用特定的時間點作為參考點，將 years 和 months 欄位轉換為 days 欄位。
Duration	subtract(Duration rhs) 計算值為 this-rhs 的新持續時間。
String	toString() 返回此 Duration Object 的 String 表示形式。

從類別 java.lang.Object 繼承的方法

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

建構子詳細資訊

Duration

public Duration()

預設的無參數建構子。

註：總是使用 DatatypeFactory 來建構 Duration 實例。無法保證此類別上的建構子產生具有一致狀態並可在以後移除的物件。

方法詳細資訊

getXMLSchemaType

public QName getXMLSchemaType()

返回此實例映射到的 XML 網要日期/時間型別的名稱。型別根據設置的欄位來計算，即 isSet(DatatypeConstants.Field field) == true。

XML 網要 1.0 日期/時間資料型別的必需欄位。 （對於所有日期/時間資料型別，時區是可選的）
資料型別	year	month	day	hour	minute	second
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 網要日期/時間資料型別之一不比對。

getSign

public abstract int getSign()

以 -1、0 或 1 的形式返回此持續時間的符號。

返回：

如果此持續時間為負，則返回 -1；如果持續時間為零，則返回 0；如果持續時間為正，則返回 1。

getYears

public int getYears()

獲取此 Duration 以 int 表示的 years 值，如果不存在，則值為 0。

getYears() 是 getField(DatatypeConstants.YEARS) 的一個便捷方法。

由於返回值是 int，所以對於具有超出 int 範圍的年值的 Duration，返回不正確的值。使用 getField(DatatypeConstants.YEARS) 避免可能的精度丟失。

返回：

如果存在 years 欄位，則返回以 int 表示的值，否則返回 0。

getMonths

public int getMonths()

獲取整數值形式的 MONTHS 欄位的值，如果不存在，則值為 0。 除了對 MONTHS 欄位的作用之外，此方法的其他功能與 getYears() 相似。

返回：

此 Duration 的月。

getDays

public int getDays()

獲取整數值形式的 DAYS 欄位的值，如果不存在，則值為 0。 除了對 MONTHS 欄位的作用之外，此方法的其他功能與 getYears() 相似。

返回：

此 Duration 的日。

getHours

public int getHours()

獲取整數值形式的 HOURS 欄位的值，如果不存在，則值為 0。 除了對 HOURS 欄位的作用之外，此方法的其他功能與 getYears() 相似。

返回：

此 Duration 的時。

getMinutes

public int getMinutes()

獲取整數值形式的 MINUTES 欄位的值，如果不存在，則值為 0。 除了對 MINUTES 欄位的作用之外，此方法的其他功能與 getYears() 相似。

返回：

此 Duration 的分。

getSeconds

public int getSeconds()

獲取整數值形式的 SECONDS 欄位的值，如果不存在，則值為 0。 除了對 SECONDS 欄位的作用之外，此方法的其他功能與 getYears() 相似。

返回：

秒的整數值。將丟棄秒的小數部分（例如，如果實際值是 2.5，則此方法返回 2）

getTimeInMillis

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 參數為 null。

getTimeInMillis

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 參數為 null。

另請參見：

getTimeInMillis(Calendar)

getField

public abstract Number getField(DatatypeConstants.Field field)

獲取欄位的值。 duration 物件的欄位可以包含任意大的值。因此，設計此方法的目的是返回 Number 物件。 就 YEARS、MONTHS、DAYS、HOURS 和 MINUTES 來說，返回的數字將是一個非負整數。就 seconds 來說，返回的數字可以是一個非負的十進制值。

參數：

field - 六個欄位常數之一（YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。）

返回：

如果指定的欄位存在，則此方法返回表示其值的非 null 的非負 Number 物件。如果不存在，則返回 null。對於 YEARS、MONTHS、DAYS、HOURS 和 MINUTES，此方法返回 BigInteger 物件。對於 SECONDS，此方法返回 BigDecimal。

拋出：

NullPointerException - 如果 field 為 null。

isSet

public abstract boolean isSet(DatatypeConstants.Field field)

檢查是否設置了欄位。 duration 物件的欄位不一定存在。可以使用此方法測試欄位是否存在。

參數：

field - 六個欄位常數之一（YEARS、MONTHS、DAYS、HOURS、MINUTES 或 SECONDS。）

返回：

如果欄位存在，則返回 true，否則返回 false。

拋出：

NullPointerException - 如果欄位參數為 null。

add

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.signum()*rhs.signum()!=-1，或將它們兩個標準化，則 lhs.add(rhs) 將總是成功的。

參數：

rhs - 要添加到此 Duration 的 Duration

返回：

非 null 的有效 Duration 物件。

拋出：

NullPointerException - 如果 rhs 參數為 null。

IllegalStateException - 如果兩個持續時間的相加沒有意義。例如，將負的一天添加到一月將導致此異常。

另請參見：

subtract(Duration)

addTo

public abstract void addTo(Calendar calendar)

將此持續時間添加到 Calendar 物件。

按 YEARS、MONTHS、DAYS、HOURS、MINUTES、SECONDS 和 MILLISECONDS 的順序調用 Calendar.add(int,int)，如果這些欄位存在的話。因為 Calendar 類別使用整數保持值，所以存在此方法不能正確工作的情況（例如，如果欄位的值超出整數的範圍。）

另外，由於此 duration 類別是陽曆持續時間，所以如果給定的 Calendar 物件基於一些其他日曆系統，則此方法將不能正確工作。

對於此 Duration 物件的小數部分，只忽略毫秒之外的數字。例如，如果此持續時間是“P1.23456S”，那麼將 1 添加到 SECONDS，將 234 添加到 MILLISECONDS，不使用其餘部分。

注意，因為 Calendar.add(int, int) 正在使用 int，所以帶有超出其欄位中 int 範圍值的 Duration 將導致給定 Calendar 的上溢/下溢。link XMLGregorianCalendar#add(Duration)} 提供與此方法相同的基本操作，同時避免上溢/下溢問題。

參數：

calendar - 值將被修改的日曆物件。

拋出：

NullPointerException - 如果日曆參數為 null。

addTo

public void addTo(Date date)

將此持續時間添加到 Date 物件。

將給定的資料首先轉換為 GregorianCalendar，然後完全按照 addTo(Calendar) 方法添加持續時間。

然後將更新的時間點轉換回 Date 物件，並用於更新給定的 Date 物件。

此冗余計算對明確地確定月和年的持續時間是必需的。

參數：

date - 值將被修改的日期物件。

拋出：

NullPointerException - 如果日期參數為 null。

subtract

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（如果為非負）。

重複此過程，直到所有的非零欄位具有相同符號。

如果在 days 欄位中發生借用（換句話說，如果計算需要借用 1 或 -1 月，以補償 days），那麼計算會失敗，並拋出 IllegalStateException。

參數：

rhs - 從 Duration 減去的 Duration。

返回：

通過從此 Duration 減去 rhs 創建的新 Duration。

拋出：

IllegalStateException - 如果兩個持續時間的相減沒有意義。例如，從一月減去一天會導致此異常。

NullPointerException - 如果 rhs 參數為 null。

另請參見：

add(Duration)

multiply

public Duration multiply(int factor)

計算新的持續時間，值為此持續時間值的 factor 倍。

提供此方法是為了方便使用。它在功能上等同於以下程式碼：

 multiply(new BigDecimal(String.valueOf(factor)))
 

參數：

factor - 要創建的新 Duration 的 Factor 倍數。

返回：

作為此 Duration 的 factor 倍的新 Duration。

另請參見：

multiply(BigDecimal)

multiply

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 的精度逐欄位執行操作。由於除 seconds 外的所有欄位限於保持整數，計算產生的任何小數向下進位到下一個低單位。例如，如果 "P1D"（1 天）乘 "0.5"，那麼將得到 0.5 天，它將向下進位到 "PT12H"（12 小時）。當月的小數向下進位到日或年的小數向下進位到月沒有意義時，將導致拋出 IllegalStateException。例如，將一個月乘以 0.5 時將拋出上述異常。

要避免 IllegalStateException，請使用 normalizeWith(Calendar) 方法移除 years 和 months 欄位。

參數：

factor - 相乘的因子

返回：

返回非 null 的有效 Duration 物件

拋出：

IllegalStateException - 如果操作在 months 欄位中產生小數。

NullPointerException - 如果 factor 參數為 null。

negate

public abstract Duration negate()

返回值為 -this 的新 Duration 物件。

由於 Duration 類別是不可變的，所以此方法不更改此物件的值。它僅計算新的 Duration 物件，並返回它。

返回：

總是返回非 null 的有效 Duration 物件。

normalizeWith

public abstract Duration normalizeWith(Calendar startTimeInstant)

通過使用特定的時間點作為參考點，將 years 和 months 欄位轉換為 days 欄位。

例如，一個月的持續時間可以標準化為 31 天，給出的時間點是 "July 8th 2003, 17:40:32"。

正式地說，應按以下方法進行計算：

1. 複製給定的 Calendar 物件
2. 使用 Calendar.add(int,int) 方法將 years、months 和 days 欄位添加到 Calendar 物件
3. 兩個 Calendar 在以毫秒計算並轉換為天數上存在差異，如果由於夏令時 (Daylight Savings Time) 而發生餘數，則丟棄該餘數。
4. 計算的 days 以及此持續時間物件的 hours、minutes 和 seconds 欄位用於建構新的持續時間物件。

注意，由於 Calendar 類別使用 int 保持年和月的值，所以如果此持續時間物件在 years 或 months 欄位中保持非常大的值，則此方法可能產生不可預料的結果。

參數：

startTimeInstant - Calendar 參考點。

返回：

以日為單位返回此 Duration 的年和月的 Duration。

拋出：

NullPointerException - 如果 startTimeInstant 參數為 null。

compare

public abstract int compare(Duration duration)

與此 Duration 實例的部分順序關係比較。

比較結果必須依照 W3C XML 網要 1.0 第二部分 3.2.7.6.2 節 Order relation on duration。

返回：

• DatatypeConstants.LESSER 如果此 Duration 比 duration 參數短
• DatatypeConstants.EQUAL 如果此 Duration 等於 duration 參數
• DatatypeConstants.GREATER 如果此 Duration 比 duration 參數長
• DatatypeConstants.INDETERMINATE 如果無法確定最終的部分順序關係

參數：

duration - 要比較的持續時間

返回：

此 Duration 和 duration 參數之間的關係：DatatypeConstants.LESSER、DatatypeConstants.EQUAL、DatatypeConstants.GREATER 或 DatatypeConstants.INDETERMINATE。

拋出：

UnsupportedOperationException - 如果底層實作無法合理處理該請求，例如，W3C XML 網要允許任意大/小/精確的值，該請求可能超出實作功能。

NullPointerException - 如果 duration 為 null。

另請參見：

isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

檢查此持續時間物件是否嚴格長於另一個 Duration 物件。

根據 XML 網要 1.0 規範的第 3.2.6.2 節中的定義，當且僅當 X>Y 時，持續時間 X 比 Y「長」。

例如，"P1D"（一天）> "PT12H"（12 小時），並且 "P2Y"（兩年）>"P23M"（23 月）。

參數：

duration - 測試此 Duration 的 Duration。

返回：

如果此物件表示的持續時間比給定的持續時間長，則返回 true，否則返回 false。

拋出：

UnsupportedOperationException - 如果底層實作無法合理處理該請求，例如，W3C XML 網要允許任意大/小/精確的值，該請求可能超出實作功能。

NullPointerException - 如果 duration 為 null。

另請參見：

isShorterThan(Duration), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

檢查此持續時間物件是否嚴格短於另一個 Duration 物件。

參數：

duration - 測試此 Duration 的 Duration。

返回：

如果 duration 參數比此 Duration 短，則返回 true，否則返回 false。

拋出：

UnsupportedOperationException - 如果底層實作無法合理處理該請求，例如，W3C XML 網要允許任意大/小/精確的值，該請求可能超出實作功能。

NullPointerException - 如果 duration 為 null。

另請參見：

isLongerThan(Duration duration), compare(Duration duration)

equals

public boolean equals(Object duration)

檢查此持續時間物件是否與另一個 Duration 物件具有相同的持續時間。

例如，"P1D"（1 天）等於 "PT24H"（24 小時）。

當且僅當時間點 t+X 和 t+Y 對 XML 網要 1.0 規範的第 3.2.6.2 節中指定的所有測試時間點都相同時，持續時間 X 才等於 Y。

注意，存在兩個 Duration 互相「不能比較」的情況，如一個月和 30 天。例如，

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
 

覆寫：

類別 Object 中的 equals

參數：

duration - 用來對照比較此 Duration 的物件。

返回：

如果此持續時間與 duration 長度相同，則返回 true。如果 duration 是 null，而不是 Duration 物件，或者其長度與此持續時間不同，則返回 false。

拋出：

UnsupportedOperationException - 如果底層實作無法合理處理該請求，例如，W3C XML 網要允許任意大/小/精確的值，該請求可能超出實作功能。

另請參見：

compare(Duration duration)

hashCode

public abstract int hashCode()

返回與 equals 方法的定義一致的雜湊碼。

覆寫：

類別 Object 中的 hashCode

返回：

此物件的一個雜湊碼值。

另請參見：

Object.hashCode()

toString

public String toString()

返回此 Duration Object 的 String 表示形式。

根據 XML 網要 1.0 規範格式化該結果，之後始終可以通過 DatatypeFactory.newDuration(String lexicalRepresentation) 將其解析為等效的 Duration Object。

正式地說，以下內容保持任何 Duration Object x：

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

覆寫：

類別 Object 中的 toString

返回：

此 Duration 的非 null 有效 String 表示形式。