クラスDuration
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オブジェクトと等しいかどうかをチェックします。intgetDays()DAYSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。abstract NumbergetField(DatatypeConstants.Field field) フィールドの値を取得します。intgetHours()HOURSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。intMINUTESフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。intMONTHSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。intSECONDSフィールドの値を整数値として取得するか、フィールドが存在しない場合は0が返されます。abstract intgetSign()この期間の符号を-1、0、1のいずれかで戻します。longgetTimeInMillis(Calendar startInstant) ミリ秒でデュレーションの長さを返します。longgetTimeInMillis(Date startInstant) ミリ秒でデュレーションの長さを返します。このインスタンスが対応するXML Schema日時型の名前を返します。intgetYears()このDurationの年の値をintとして取得します。値が存在しない場合は0を返します。abstract inthashCode()equalsメソッドの定義に一致するハッシュ・コードを返します。booleanisLongerThan(Duration duration) このDurationオブジェクトがほかのDurationオブジェクトより確実に長いかどうかをチェックします。abstract booleanisSet(DatatypeConstants.Field field) フィールドが設定されているかどうかをチェックします。booleanisShorterThan(Duration duration) このDurationオブジェクトがほかのDurationオブジェクトより確実に短いかどうかをチェックします。multiply(int factor) 値がこのデュレーションの値よりfactor倍長い新しいデュレーションを計算します。abstract Durationmultiply(BigDecimal factor) 値がこのデュレーションの値よりfactor倍長い新しいデュレーションを計算します。abstract Durationnegate()値が-thisであるDurationを返します。abstract DurationnormalizeWith(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.DURATIONX X X X X X DatatypeConstants.DURATION_DAYTIMEX X X X DatatypeConstants.DURATION_YEARMONTHX 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) == 10000new 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) == 10000new 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オブジェクトより確実に長いかどうかをチェックします。期間Xは、XMLスキーマの1.0仕様のセクション3.2.6.2で定義されているX > Yの場合のみ、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
-
toString
public String toString()このDuration ObjectのString表現を返します。結果はXMLスキーマの1.0仕様に従って書式設定され、後で
DatatypeFactory.newDuration(String lexicalRepresentation)によって同等のDuration Objectに常に解析できます。形式上、以下は任意の
DurationObjectxを保持します。new Duration(x.toString()).equals(x)
-