anon.util

Class XMLDuration

java.lang.Object

anon.util.XMLDuration

public class XMLDuration
extends java.lang.Object

Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification.

A Duration object represents a period of Gregorian time, which consists of six fields (years, months, days, hours, minutes, and seconds) plus a sign (+/-) field.

The first five fields have non-negative (>=0) integers or null (which represents that the field is not set), and the seconds field has a non-negative decimal or null. A negative sign indicates a negative duration.

This class provides a number of methods that make it easy to use for the duration datatype of XML Schema 1.0 with the errata.

Order relationship

Duration objects only have partial order, where two values A and B maybe either:

1. A<B (A is shorter than B)
2. A>B (A is longer than B)
3. A==B (A and B are of the same duration)
4. A<>B (Comparison between A and B is indeterminate)

*

For example, 30 days cannot be meaningfully compared to one month. The #compare(Duration duration) method implements this relationship.

See the #isLongerThan(Duration) method for details about the order relationship among Duration objects.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DURATION
static int	DURATION_DAYTIME
static int	DURATION_YEARMONTH
static int	EQUAL
static int	GREATER
static int	INDETERMINATE
static int	LESSER

Constructor Summary

Constructors

Constructor and Description
XMLDuration()
XMLDuration(java.lang.String a_duration)
XMLDuration(XMLDuration a_duration)

Method Summary

Modifier and Type	Method and Description
int	compare(XMLDuration a_duration) Partial order relation comparison with this Duration instance.
boolean	equals(java.lang.Object a_duration)
long	getDays()
java.lang.Number	getField(int a_field) Gets the value of a field.
java.lang.Number	getField(java.lang.Object a_field)
static java.lang.String	getFieldName(int a_field)
static java.lang.String	getFieldName(java.lang.Object a_field)
java.util.Enumeration	getFields()
long	getHours()
int	getLastFieldSet()
long	getMinutes()
long	getMonths()
double	getSeconds()
int	getSign() Returns the sign of this duration in -1,0, or 1.
java.lang.String	getXMLSchema()
int	getXMLSchemaType() Return the name of the XML Schema date/time type that this instance maps to.
long	getYears()
int	hashCode()
boolean	isLongerThan(XMLDuration a_duration) Checks if this duration object is strictly longer than another Duration object.
boolean	isSet(int a_field) Checks if a field is set.
boolean	isShorterThan(XMLDuration a_duration) Checks if this duration object is strictly shorter than another Duration object.
XMLDuration	negate() Returns a new Duration object whose value is -this.
java.lang.String	toString() Returns a String representation of this Duration Object.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

DURATION

public static final int DURATION

See Also:

Constant Field Values

DURATION_DAYTIME

public static final int DURATION_DAYTIME

See Also:

Constant Field Values

DURATION_YEARMONTH

public static final int DURATION_YEARMONTH

See Also:

Constant Field Values

LESSER

public static final int LESSER

See Also:

Constant Field Values

EQUAL

public static final int EQUAL

See Also:

Constant Field Values

GREATER

public static final int GREATER

See Also:

Constant Field Values

INDETERMINATE

public static final int INDETERMINATE

See Also:

Constant Field Values

Constructor Detail

XMLDuration

public XMLDuration()

XMLDuration

public XMLDuration(XMLDuration a_duration)

XMLDuration

public XMLDuration(java.lang.String a_duration)
            throws XMLParseException

Throws:

XMLParseException

Method Detail

getXMLSchema

public java.lang.String getXMLSchema()

getXMLSchemaType

public int getXMLSchemaType()
                     throws java.lang.IllegalStateException

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that are set, i.e. isSet(int a_field) == true.

Required fields for XML Schema 1.0 Date/Time Datatypes. (timezone is optional for all date/time datatypes)
Datatype	year	month	day	hour	minute	second
DURATION	X	X	X	X	X	X
DURATION_DAYTIME			X	X	X	X
URATION_YEARMONTH	X	X

Returns:

one of the following constants: DURATION, DURATION_DAYTIME or DURATION_YEARMONTH.

Throws:

java.lang.IllegalStateException - If the combination of set fields does not match one of the XML Schema date/time datatypes.

getSign

public int getSign()

Returns the sign of this duration in -1,0, or 1.

Returns:

-1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.

getYears

public long getYears()

getMonths

public long getMonths()

getDays

public long getDays()

getHours

public long getHours()

getMinutes

public long getMinutes()

getSeconds

public double getSeconds()

getFieldName

public static java.lang.String getFieldName(java.lang.Object a_field)

getFieldName

public static java.lang.String getFieldName(int a_field)

getFields

public java.util.Enumeration getFields()

getField

public java.lang.Number getField(java.lang.Object a_field)

getField

public java.lang.Number getField(int a_field)

Gets the value of a field. Fields of a duration object may contain arbitrary large value. Therefore this method is designed to return a Number object. In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned number will be a non-negative integer. In case of seconds, the returned number may be a non-negative decimal value.

Parameters:

field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)

Returns:

If the specified field is present, this method returns a non-null non-negative Number object that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method returns a BigInteger object. For SECONDS, this method returns a BigDecimal.

Throws:

java.lang.NullPointerException - If the field is null.

isSet

public boolean isSet(int a_field)

Checks if a field is set. A field of a duration object may or may not be present. This method can be used to test if a field is present.

Parameters:

field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)

Returns:

true if the field is present. false if not.

negate

public XMLDuration negate()

Returns a new Duration object whose value is -this.

Since the Duration class is immutable, this method doesn't change the value of this object. It simply computes a new Duration object and returns it.

Returns:

always return a non-null valid Duration object.

compare

public int compare(XMLDuration a_duration)

Partial order relation comparison with this Duration instance.

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration.

Return:

• LESSER if this Duration is shorter than duration parameter
• EQUAL if this Duration is equal to duration parameter
• GREATER if this Duration is longer than duration parameter
• NDETERMINATE if a conclusive partial order relation cannot be determined

Parameters:

duration - to compare

Returns:

the relationship between this Durationand duration parameter as LESSER, EQUAL,GREATER or INDETERMINATE.

Throws:

java.lang.NullPointerException - if duration is null.

See Also:

#isShorterThan(Duration), #isLongerThan(Duration)

equals

public boolean equals(java.lang.Object a_duration)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

isLongerThan

public boolean isLongerThan(XMLDuration a_duration)

Checks if this duration object is strictly longer than another Duration object.

Duration X is "longer" than Y if and only if X>Y as defined in the section 3.2.6.2 of the XML Schema 1.0 specification.

For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months).

Parameters:

duration - Duration to test this Duration against.

Returns:

true if the duration represented by this object is longer than the given duration. false otherwise.

Throws:

java.lang.NullPointerException - If duration is null.

See Also:

#isShorterThan(Duration), #compare(Duration duration)

isShorterThan

public boolean isShorterThan(XMLDuration a_duration)

Checks if this duration object is strictly shorter than another Duration object.

Parameters:

duration - Duration to test this Duration against.

Returns:

true if duration parameter is shorter than this Duration, else false.

Throws:

java.lang.NullPointerException - if duration is null.

See Also:

#isLongerThan(Duration duration), #compare(Duration duration)

getLastFieldSet

public int getLastFieldSet()

toString

public java.lang.String toString()

Returns a String representation of this Duration Object.

The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent Duration Object.

Formally, the following holds for any Duration Object x:

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

Overrides:

toString in class java.lang.Object

Returns:

A non-null valid String representation of this Duration.