JavaTM 2 Platform
Standard Ed. 5.0

javax.xml.datatype
クラス Duration

java.lang.Object
  上位を拡張 javax.xml.datatype.Duration

public abstract class Duration
extends Object

W3C XML Schema 1.0 仕様に定義された期間の不変の表現です。

Duration オブジェクトはグレゴリオ時間の時間を表し、6 つのフィールド (年、月、日、時間、分、秒) と記号 (+/-) フィールドから構成されます。

先頭の 5 つのフィールドには負以外 (>=0) の整数または null (フィールドが設定されていないことを示す) が入り、2 番目のフィールドには負以外の 10 進数または null が入ります。負の記号は負のデュレーションを示します。

このクラスは正誤表付きの XML Schema 1.0 のデュレーションデータ型に簡単に使用できる多くのメソッドを提供しています。

順序関係

Duration オブジェクトは部分的な順序のみを持ち、A と B の 2 つの値は次のいずれかになります。

  1. A<B (A は B より短い)
  2. A>B (A は B より長い)
  3. A==B (A と B は同じデュレーション)
  4. 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
関連項目:
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 オブジェクトがほかの 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 Schema 日時型の名前を返します。
 int getYears()
          この Duration の年の値を int として返します。
abstract  int hashCode()
          equals メソッドの定義に一致するハッシュコードを返します。
 boolean isLongerThan(Duration duration)
          この Duration オブジェクトが他の Duration オブジェクトより確実に長いかどうかをチェックします。
abstract  boolean isSet(DatatypeConstants.Field field)
          フィールドが設定されているかどうかをチェックします。
 boolean isShorterThan(Duration duration)
          この Duration オブジェクトが他の Duration オブジェクトより確実に短いかどうかをチェックします。
abstract  Duration multiply(BigDecimal factor)
          値がこのデュレーションの値より factor 倍長い新しいデュレーションを計算します。
 Duration multiply(int factor)
          値がこのデュレーションの値より factor 倍長い新しいデュレーションを計算します。
abstract  Duration negate()
          値が -this である新しい Duration オブジェクトを返します。
abstract  Duration normalizeWith(Calendar startTimeInstant)
          特定の時点を参照点として使用して、年および月フィールドを日フィールドに変換します。
 Duration subtract(Duration rhs)
          値が this-rhs である新しいデュレーションを計算します。
 String toString()
          この Duration ObjectString 表現を返します。
 
クラス java.lang.Object から継承されたメソッド
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

コンストラクタの詳細

Duration

public Duration()
メソッドの詳細

getXMLSchemaType

public QName getXMLSchemaType()

このインスタンスが対応する XML Schema 日時型の名前を返します。型は設定されるフィールドに基づいて計算されます。つまり、isSet(DatatypeConstants.Field field) == true となります。

XML Schema 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.DURATIONDatatypeConstants.DURATION_DAYTIME、または DatatypeConstants.DURATION_YEARMONTH のうち、いずれか 1 つの定数
例外:
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 を使用して、この差異をなくす。特に、このメソッドは startInstantstartInstant+duration の差を返す
戻り値:
startInstant から startInstant プラスこの Duration までのミリ秒
例外:
NullPointerException - startInstant パラメータが null の場合

getTimeInMillis

public long getTimeInMillis(Date startInstant)

ミリ秒でデュレーションの長さを返します。

秒フィールドの桁数がミリ秒の桁数より大きい場合、それらは単に破棄されます (つまり、0 として切り捨てられます)。たとえば、任意の Datex の場合、次のようになります。


 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 

このメソッドでは addTo(Date) メソッドを使用するため、フィールドの値が著しく大きい Duration オブジェクトの場合に正しく機能しないことがあります。詳細については addTo(Date) メソッドを参照してください。

パラメータ:
startInstant - 月や年の長さはさまざまに異なる。startInstant を使用して、この差異をなくす。特に、このメソッドは startInstantstartInstant+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 の場合、返される数値は負でない 10 進数値になります。

パラメータ:
field - 6 つの Field 定数 (YEARS、MONTHS、DAYS、HOURS、MINUTES、または SECONDS) のいずれか
戻り値:
指定されたフィールドが存在する場合は、このメソッドはその値を表す null 以外の負でない Number オブジェクトを返す。フィールドが存在しない場合は、null を返す。YEARS、MONTHS、DAYS、HOURS、および MINUTES の場合は、このメソッドは BigInteger オブジェクトを返す。SECONDS の場合は、このメソッドは BigDecimal を返す
例外:
NullPointerException - fieldnull の場合

isSet

public abstract boolean isSet(DatatypeConstants.Field field)
フィールドが設定されているかどうかをチェックします。Duration オブジェクトのフィールドは存在する場合と存在しない場合があります。このメソッドを使用して、フィールドが存在するかどうかを確認できます。

パラメータ:
field - 6 つの Field 定数 (YEARS、MONTHS、DAYS、HOURS、MINUTES、または SECONDS) のいずれか
戻り値:
フィールドが存在する場合は true、そうでない場合は false
例外:
NullPointerException - フィールドパラメータが null の場合

add

public abstract Duration add(Duration rhs)

値が this+rhs である新しいデュレーションを計算します。

次に例を示します。


 "1 日" + "-3 日" = "-2 日"
 "1 年" + "1 日" = "1 年 と 1 日"
 "-(1 時間、50 分)" + "-20 分" = "-(1 時間、70 分)"
 "15 時間" + "-3 日" = "-(2 日 と 9 時間)"
 "1 年" + "-1 日" = IllegalStateException
 

意味上 1 か月から 1 日を減算することはできないため、IllegalStateException で演算が失敗する場合があります。

形式上、次のように計算されます。

まず、加算する 2 つの Duration は、汎用性を失わずに、ともに正であるとします (つまり、(-X)+Y=Y-XX+(-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 か月に追加すると、この例外が生成される
関連項目:
subtract(Duration)

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 - 値を変更する Calender オブジェクト
例外:
NullPointerException - calendar パラメータが null の場合

addTo

public void addTo(Date date)
このデュレーションを Date オブジェクトに追加します。

指定した日付がまず GregorianCalendar に変換され、次に、addTo(Calendar) メソッドとまったく同じように、デュレーションが追加されます。

更新された時点が再び Date オブジェクトに変換されて、指定した Date オブジェクトの更新に使用されます。

これには、月と年のデュレーションを正確に判断するために、いくらかの重複した計算が必要になります。

パラメータ:
date - 値を変更する Date オブジェクト
例外:
NullPointerException - date パラメータが null の場合

subtract

public Duration subtract(Duration rhs)

値が this-rhs である新しいデュレーションを計算します。

次に例を示します。


 "1 日" - "-3 日" = "4 日"
 "1 年" - "1 日" = IllegalStateException
 "-(1 時間、50 分)" - "-20 分" = "-(1 時間、30 分)"
 "15 時間" - "-3 日" = "3 日と 15 時間"
 "1 年" - "-1 日" = "1 年と 1 日"
 

意味上 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 の場合
関連項目:
add(Duration)

multiply

public Duration multiply(int factor)

値がこのデュレーションの値より factor 倍長い新しいデュレーションを計算します。

このメソッドは便宜上提供されています。機能的に次のコードと同じです。


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

パラメータ:
factor - 作成する新しい Duration の長くする係数
戻り値:
この Duration より factor 倍長い新しい Duration
関連項目:
multiply(BigDecimal)

multiply

public abstract Duration multiply(BigDecimal factor)
値がこのデュレーションの値より factor 倍長い新しいデュレーションを計算します。

次に例を示します。


 "P1M" (1 か月) * "12" = "P12M" (12 か月)
 "PT1M" (1 分) * "0.3" = "PT18S" (18 秒)
 "P1M" (1 か月) * "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

public abstract Duration normalizeWith(Calendar startTimeInstant)

特定の時点を参照点として使用して、年および月フィールドを日フィールドに変換します。

たとえば、開始時刻インスタンスを「July 8th 2003, 17:40:32」として、1 か月のデュレーションを 31 日に正規化します。

形式上、次のように計算されます。

  1. 指定した Calendar オブジェクトが複製される
  2. Calendar.add(int,int) メソッドを使用して、年、月、日フィールドが Calendar オブジェクトに追加される
  3. 2 つの Calendar の差がミリ秒で計算されてから日に変換される。夏時間のために余剰が出た場合は、破棄される
  4. 計算された日と、この 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 - 比較するデュレーション
戻り値:
this DurationDatatypeConstants.LESSERDatatypeConstants.EQUALDatatypeConstants.GREATER、または DatatypeConstants.INDETERMINATE としての durationパラメータの関係
例外:
UnsupportedOperationException - W3C XML Schema が大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある
NullPointerException - durationnull の場合
関連項目:
isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

この Duration オブジェクトが他の Duration オブジェクトより確実に長いかどうかをチェックします。

XML Schema 1.0 仕様のセクション 3.2.6.2 に定義されているように X>Y の場合にのみ Duration X は Y より「長く」なります。

たとえば、P1D (1 日) > PT12H (12 時間)、および P2Y (2 年) > P23M (23 か月)になります。

パラメータ:
duration - この Duration に照らして判定する Duration
戻り値:
このオブジェクトによって示されたデュレーションが指定されたデュレーションより長い場合は true、そうでない場合は false
例外:
UnsupportedOperationException - W3C XML Schema が大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある
NullPointerException - duration が null の場合
関連項目:
isShorterThan(Duration), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

この Duration オブジェクトが他の Duration オブジェクトより確実に短いかどうかをチェックします。

パラメータ:
duration - この Duration に照らして判定する Duration
戻り値:
Duration パラメータがこの Duration より短い場合は true、そうでない場合は false
例外:
UnsupportedOperationException - W3C XML Schema が大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある
NullPointerException - duration が null の場合
関連項目:
isLongerThan(Duration duration), compare(Duration duration)

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"))
 

オーバーライド:
クラス Object 内の equals
パラメータ:
duration - null 以外の有効な Duration オブジェクト
戻り値:
このデュレーションが duration と同じ長さの場合は truedurationDuration オブジェクトでないか、またはこのデュレーションと長さが異なる場合は false
例外:
UnsupportedOperationException - W3C XML Schema が大きい、小さい、あるいは正確な値を任意に許可するなど、実装が要求を適切に処理できない場合は、要求が実装能力を超えている可能性がある
NullPointerException - パラメータが null の場合
関連項目:
compare(Duration duration)

hashCode

public abstract int hashCode()
equals メソッドの定義に一致するハッシュコードを返します。

オーバーライド:
クラス Object 内の hashCode
戻り値:
このオブジェクトのハッシュコード値
関連項目:
Object.hashCode()

toString

public String toString()

この Duration ObjectString 表現を返します。

結果は、XML Schema 1.0 仕様に従ってフォーマットされており、あとでいつでも DatatypeFactory.newDuration(String lexicalRepresentation) によって、対応する Duration Object に解析できます。

形式上、以下は任意の Duration Object x を保持します。


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

オーバーライド:
クラス Object 内の toString
戻り値:
この Durationnull 以外の有効な String 表現

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。