W3C XML Schema 1.0仕様に定義された期間の不変の表現です。
Durationオブジェクトはグレゴリオ時間の時間を表し、6つのフィールド(年、月、日、時間、分、秒)と記号(+/-)フィールドから構成されます。
先頭の5つのフィールドには負以外(>=0)の整数またはnull (フィールドが設定されていないことを示す)が入り、2番目のフィールドには負以外の10進数またはnullが入ります。 負の記号は負のデュレーションを示します。
このクラスは正誤表付きのXML Schema 1.0のデュレーション・データ型に簡単に使用できる多くのメソッドを提供しています。
順序関係
Durationオブジェクトは部分的な順序のみを持ち、AとBの2つの値は次のいずれかになります。
- A<B (AはBより短い)
- A>B (AはBより長い)
- A==B (AとBは同じデュレーション)
- A<>B (AとBの比較は判定不可)
たとえば、30日と1か月は意味上比較できません。 compare(Duration duration)
メソッドでこの関係を実装します。
Duration
オブジェクト間の順序関係の詳細は、isLongerThan(Duration)
メソッドを参照してください。
デュレーションの演算
このクラスは、加算、減算、乗算などの一連の基本算術演算を実行します。 デュレーションには全体順序がないため、演算の組み合わせによっては、演算が失敗する可能性があります。 たとえば、1か月から15日を減算することはできません。 失敗する可能性のある詳しい状況については、これらのメソッドのJavadocを参照してください。
さらに、Duration
クラスが処理できるのは有限精度10進数にかぎられるため、数値によるデュレーションの除算は行われません。 たとえば、1秒割る3 (1秒÷3)は表現できません。
ただし、0.3や0.333などの数値で乗算して、3による除算に代えることはできます。
許可される値の範囲
Duration
にはきわめて大きい値や小さい値を保持できますが、Duration
の一部の演算はCalendar
に依存しているため、そうしたDuration
に対しては一部のメソッドが正常に動作しないことがあります。 影響を受けるメソッドには、それらのCalendar
への依存関係が記述されています。
- 導入されたバージョン:
- 1.5
- 関連項目:
-
コンストラクタのサマリー
-
メソッドのサマリー
修飾子と型メソッド説明abstract Duration
値がthis+rhs
である新しいデュレーションを計算します。abstract void
この期間をCalendar
オブジェクトに追加します。void
この期間をDate
オブジェクトに追加します。abstract int
このDuration
インスタンスと部分順序リレーションを比較します。boolean
このDurationオブジェクトがほかのDuration
オブジェクトと等しいかどうかをチェックします。int
getDays()
DAYSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。abstract Number
getField
(DatatypeConstants.Field field) フィールドの値を取得します。int
getHours()
HOURSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。int
MINUTESフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。int
MONTHSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。int
SECONDSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。abstract int
getSign()
この期間の符号を-1、0、1のいずれかで戻します。long
getTimeInMillis
(Calendar startInstant) ミリ秒でデュレーションの長さを返します。long
getTimeInMillis
(Date startInstant) ミリ秒でデュレーションの長さを返します。このインスタンスが対応するXML Schema日時型の名前を返します。int
getYears()
このDuration
の年の値をint
として取得します。値が存在しない場合は0
を返します。abstract int
hashCode()
equalsメソッドの定義に一致するハッシュ・コードを返します。boolean
isLongerThan
(Duration duration) このDurationオブジェクトがほかのDuration
オブジェクトより確実に長いかどうかをチェックします。abstract boolean
isSet
(DatatypeConstants.Field field) フィールドが設定されているかどうかをチェックします。boolean
isShorterThan
(Duration duration) このDurationオブジェクトがほかのDuration
オブジェクトより確実に短いかどうかをチェックします。multiply
(int factor) 値がこのデュレーションの値よりfactor
倍長い新しいデュレーションを計算します。abstract Duration
multiply
(BigDecimal factor) 値がこのデュレーションの値よりfactor
倍長い新しいデュレーションを計算します。abstract Duration
negate()
値が-this
であるDuration
を返します。abstract Duration
normalizeWith
(Calendar startTimeInstant) 特定の時点を参照点として使用して、年および月フィールドを日フィールドに変換します。値がthis-rhs
である新しいデュレーションを計算します。toString()
このDuration Object
のString
表現を返します。
-
コンストラクタの詳細
-
Duration
public Duration()デフォルトの引数なしのコンストラクタです。ノート:
Duration
のインスタンスを構築するには、常にDatatypeFactory
を使用します。 このクラス上のコンストラクタは、一貫した状態のオブジェクトを生成するとは保証されておらず、将来削除される可能性があります。
-
-
メソッドの詳細
-
getXMLSchemaType
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 - 戻り値:
- 次の定数のいずれか。
DatatypeConstants.DURATION
、DatatypeConstants.DURATION_DAYTIME
、またはDatatypeConstants.DURATION_YEARMONTH
。 - 例外:
IllegalStateException
- 設定フィールドの組み合わせが、XML Schema日時データ型のいずれかに一致しない場合。
-
getSign
public abstract int getSign()この期間の符号を-1、0、1のいずれかで戻します。- 戻り値:
- このデュレーションが負の場合は -1、0の場合は0、正の場合は1。
-
getYears
public int getYears()このDuration
の年の値をint
として取得します。値が存在しない場合は0
を返します。getYears()
はgetField(DatatypeConstants.YEARS)
の簡易メソッドです。戻り値が
int
の場合、int
の範囲を超える年を含むDuration
に対して不正な値が返されます。 精度の低下を防ぐため、getField(DatatypeConstants.YEARS)
を使用してください。- 戻り値:
- 年フィールドが存在する場合は、値を
int
として返し、そうでない場合は0
を返す。
-
getMonths
public int getMonths()MONTHSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。 このメソッドの機能はMONTHSフィールドに有効であることを除けば、getYears()
とまったく同じです。- 戻り値:
- この
Duration
の月。
-
getDays
public int getDays()DAYSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。 このメソッドの機能はDAYSフィールドに有効であることを除けば、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) ミリ秒でデュレーションの長さを返します。秒フィールドの桁数がミリ秒の桁数より大きい場合、それらは単に破棄されます(つまり、0として切り捨てられます)。 たとえば、任意のCalendar値
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) ミリ秒でデュレーションの長さを返します。秒フィールドの桁数がミリ秒の桁数より大きい場合、それらは単に破棄されます(つまり、0として切り捨てられます)。 たとえば、任意の
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の場合。- 関連項目:
-
getField
public abstract Number getField(DatatypeConstants.Field field) フィールドの値を取得します。 Durationオブジェクトのフィールドには任意の大きな値を格納できます。 そのため、このメソッドはNumber
オブジェクトを返すように設計されています。 YEARS、MONTHS、DAYS、HOURS、およびMINUTESの場合、返される数値は負でない整数になります。 SECONDSの場合、返される数値は負でない10進数値になります。- パラメータ:
field
- 6つの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
- 6つのField定数(YEARS、MONTHS、DAYS、HOURS、MINUTES、またはSECONDS)のいずれか。- 戻り値:
- フィールドが存在する場合はtrue、そうでない場合はfalse。
- 例外:
NullPointerException
- fieldパラメータがnullの場合。
-
add
値が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
で演算が失敗する場合があります。形式上、計算は次のように定義されます。
まず、加算する2つの
Duration
は、汎用性を失わずに、ともに正であるとします(つまり、(-X)+Y=Y-X
、X+(-Y)=X-Y
、(-X)+(-Y)=-(X+Y)
)2つの正の
Duration
の加算は、単にフィールドごとの加算として定義され、フィールドがない場合は0として扱われます。結果として得られる
Duration
のフィールドは、2つの入力Duration
の各フィールドが設定されていない場合にのみ、設定されません。lhs.add(rhs)
は、lhs.signum()*rhs.signum()!=-1
またはそれらの両方とも正規化されている場合、常に成功します。- パラメータ:
rhs
- このDuration
に追加するDuration
- 戻り値:
- null以外の有効なDurationオブジェクト。
- 例外:
NullPointerException
- rhsパラメータがnullの場合。IllegalStateException
- 2つのデュレーションを意味上追加できない場合。 たとえば、負の1日を1か月に追加すると、この例外が生成される。- 関連項目:
-
addTo
public abstract void addTo(Calendar calendar) この期間をCalendar
オブジェクトに追加します。YEARS、MONTHS、DAYS、HOURS、MINUTES、SECONDS、およびMILLISECONDSフィールドが存在する場合、この順番で、
Calendar.add(int,int)
を呼び出します。Calendar
クラスではintを使用して値を保持するため、このメソッドが正常に機能しないことがあります(たとえば、フィールドの値がintの範囲を超える場合)。さらに、このDurationクラスはグレゴリオ・デュレーションであるため、指定された
Calendar
オブジェクトがほかのカレンダ・システムに基づく場合、このメソッドは正しく機能しません。この
Duration
オブジェクトのミリ秒を超える小数部は単に無視されます。 たとえば、このデュレーションがP1.23456Sの場合、SECONDSに1が追加され、MILLISECONDSに234が追加されて、残りの部分は使用されません。Calendar.add(int, int)
ではint
を使用しているため、Duration
のフィールドの値がint
の範囲を超える場合に、指定したCalendar
のオーバーフローやアンダーフローが発生します。XMLGregorianCalendar.add(Duration)
では、オーバーフローやアンダーフローの問題を回避しながら、このメソッドと同じ基本演算を実行できます。- パラメータ:
calendar
- 値を変更するCalendarオブジェクト。- 例外:
NullPointerException
- calendarパラメータがnullの場合。
-
addTo
public void addTo(Date date) この期間をDate
オブジェクトに追加します。指定した日付がまず
GregorianCalendar
に変換され、次にaddTo(Calendar)
メソッドとまったく同じように、デュレーションが追加されます。更新された時点がふたたび
Date
オブジェクトに変換されて、指定したDate
オブジェクトの更新に使用されます。これには、月と年のデュレーションを正確に判断するために、いくらかの重複した計算が必要になります。
- パラメータ:
date
- 値を変更するDateオブジェクト。- 例外:
NullPointerException
- dateパラメータがnullの場合。
-
subtract
値が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
で演算が失敗する場合があります。形式上、計算は次のように定義されます。 まず、2つの
Duration
は、汎用性を失わずに、ともに正であるとします。(つまり、(-X)-Y=-(X+Y)
、X-(-Y)=X+Y
、(-X)-(-Y)=-(X-Y)
)次に2つのデュレーションがフィールドごとに減算されます。 0以外のフィールド
F
の記号が最上位フィールドの記号と異なる場合、1 (F
が負の場合)または -1 (それ以外の場合)がF
の隣の上位の単位から借りられます。このプロセスは、0以外のすべてのフィールドの記号が同じになるまで繰り返されます。
日フィールドで借りが発生する場合(つまり、日を補正するために1か月または -1か月を借りる必要がある場合)、
IllegalStateException
がスローされ、計算が失敗します。- パラメータ:
rhs
- このDuration
から減算するDuration
。- 戻り値:
- この
Duration
からrhs
を減算して作成される新しいDuration
。 - 例外:
IllegalStateException
- 2つのデュレーションを意味上減算できない場合。 たとえば、1か月から1日を減算すると、この例外が生成される。NullPointerException
- rhsパラメータがnullの場合。- 関連項目:
-
multiply
public Duration multiply(int factor) 値がこのデュレーションの値よりfactor
倍長い新しいデュレーションを計算します。このメソッドは便宜上提供されています。 機能的に次のコードと同じです。
multiply(new BigDecimal(String.valueOf(factor)))
- パラメータ:
factor
- 作成する新しいDuration
の長くする係数。- 戻り値:
- この
Duration
よりfactor
倍長い新しいDuration
。 - 関連項目:
-
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
の精度で、フィールドごとに実行されます。 秒を除くすべてのフィールドは整数のみを保持するように制限されているため、計算によって生成された小数はすべて下位の単位に繰り下げられます。 たとえば、P1D (1日)に0.5をかけると、0.5日になりますが、これはPT12H (12時間)に繰り下げられます。 月の小数部を意味上、日に繰下げできない場合、または年を月に繰下げできない場合、IllegalStateException
がスローされます。 たとえば、1か月に0.5をかけた場合などです。IllegalStateException
を回避するには、normalizeWith(Calendar)
メソッドを使用して、年および月フィールドを削除します。- パラメータ:
factor
- かける数- 戻り値:
- null以外の有効な
Duration
オブジェクトを返す - 例外:
IllegalStateException
- 月フィールドの演算で小数が生成された場合。NullPointerException
-factor
パラメータがnull
の場合。
-
negate
public abstract Duration negate()値が-this
であるDuration
を返します。Duration
クラスは不変なため、このメソッドは、このオブジェクトの値を変更しません。 新しいDurationオブジェクトを計算して、それを返すだけです。- 戻り値:
- 常にnull以外の有効な
Duration
オブジェクトを返す。
-
normalizeWith
特定の時点を参照点として使用して、年および月フィールドを日フィールドに変換します。たとえば、開始時間インスタンスを「July 8th 2003, 17:40:32」として、1か月のデュレーションを31日に正規化します。
形式上、次のように計算されます。
- 指定したCalendarオブジェクトが複製される
Calendar.add(int,int)
メソッドを使用して、年、月、日フィールドがCalendar
オブジェクトに追加される。- 2つのCalendarの差がミリ秒で計算されてから日に変換される。サマー・タイムのために余剰が出た場合は、破棄される。
- 計算された日と、このDurationオブジェクトの時間、分、秒フィールドを使用して、新しいDurationオブジェクトが構築される。
Calendarクラスでは
int
を使用して、年および月の値を保持するため、このDurationオブジェクトの年または月フィールドに著しく大きな値を保持する場合に、このメソッドは予想しない結果を生成することがあります。- パラメータ:
startTimeInstant
-Calendar
参照点。- 戻り値:
- この
Duration
の年および月の、日としてのDuration
。 - 例外:
NullPointerException
- startTimeInstantパラメータがnullの場合。
-
compare
public abstract int compare(Duration duration) このDuration
インスタンスと部分順序リレーションを比較します。比較結果は「W3C XML Schema 1.0 Part 2」のセクション3.2.7.6.2「Order relation on duration」に従う必要があります。
次の値を戻します。
- この
Duration
がduration
パラメータより短い場合はDatatypeConstants.LESSER
- この
Duration
がduration
パラメータに等しい場合はDatatypeConstants.EQUAL
- この
Duration
がduration
パラメータより長い場合はDatatypeConstants.GREATER
- 最終的な部分順序リレーションが判定できない場合は
DatatypeConstants.INDETERMINATE
- パラメータ:
duration
- 比較する対象- 戻り値:
DatatypeConstants.LESSER
、DatatypeConstants.EQUAL
、DatatypeConstants.GREATER
、またはDatatypeConstants.INDETERMINATE
としてのthis Duration
とduration
パラメータの関係。- 例外:
UnsupportedOperationException
- W3C XML Schemaが大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある。NullPointerException
-duration
がnull
の場合。- 関連項目:
- この
-
isLongerThan
public boolean isLongerThan(Duration duration) このDurationオブジェクトがほかのDuration
オブジェクトより確実に長いかどうかをチェックします。XMLスキーマ1.0仕様のセクション3.2.6.2で定義されているX> Yの場合に限り、継続時間XはYより"longer"です。
たとえば、「P1D」(1日)>「PT12H」(12時間)、および「P2Y」(2年)>「P23M」(23か月)になります。
- パラメータ:
duration
- このDuration
をテストするDuration
。- 戻り値:
- このオブジェクトによって示されたデュレーションが指定された長い場合はtrue、そうでない場合はfalse。
- 例外:
UnsupportedOperationException
- W3C XML Schemaが大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある。NullPointerException
-duration
がnullの場合。- 関連項目:
-
isShorterThan
public boolean isShorterThan(Duration duration) このDurationオブジェクトがほかのDuration
オブジェクトより確実に短いかどうかをチェックします。- パラメータ:
duration
- このDuration
をテストするDuration
。- 戻り値:
- この
duration
パラメータがDuration
より短い場合はtrue
、そうでない場合はfalse
。 - 例外:
UnsupportedOperationException
- W3C XML Schemaが大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある。NullPointerException
-duration
がnullの場合。- 関連項目:
-
equals
public boolean equals(Object duration) このDurationオブジェクトがほかのDuration
オブジェクトと等しいかどうかをチェックします。たとえば、P1D (1日)はPT24H (24時間)と同じです。
t+Xとt+Yの時点がXML Schema 1.0仕様のセクション3.2.6.2に指定されたすべてのテスト時点と同じ場合にのみ、Duration XはYと同じになります。
たとえば、1か月と30日など、2つの
Duration
が「比較不可能」な場合があります。 たとえば、!new Duration("P1M").isShorterThan(new Duration("P30D")) !new Duration("P1M").isLongerThan(new Duration("P30D")) !new Duration("P1M").equals(new Duration("P30D"))
- オーバーライド:
equals
、クラスObject
- パラメータ:
duration
- このDuration
と比較するオブジェクト。- 戻り値:
- このデュレーションが
duration
と同じ長さの場合はtrue
。duration
がnull
であるか、Duration
オブジェクトでないか、またはこのデュレーションと長さが異なる場合はfalse
。 - 例外:
UnsupportedOperationException
- W3C XML Schemaが大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある。- 関連項目:
-
hashCode
public abstract int hashCode()equalsメソッドの定義に一致するハッシュ・コードを返します。 -
toString
public String toString()このDuration Object
のString
表現を返します。結果は、XML Schema 1.0仕様に従ってフォーマットされており、あとでいつでも
DatatypeFactory.newDuration(String lexicalRepresentation)
によって、対応するDuration Object
に解析できます。形式上、以下は任意の
Duration
Object
xを保持します。new Duration(x.toString()).equals(x)
-