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

private static int	DAYS
static int	DURATION
static int	DURATION_DAYTIME
static int	DURATION_YEARMONTH
static int	EQUAL
static int	GREATER
private static int	HOURS
static int	INDETERMINATE
static int	LESSER
private boolean	m_bNegativeSign
private long	m_calcDays
private long	m_calcHours
private long	m_calcMinutes
private long	m_calcMonths
private double	m_calcSeconds
private long	m_calcYears
private long	m_days
private int	m_hashCode
private long	m_hours
private long	m_minutes
private long	m_months
private double	m_seconds
private java.util.Vector	m_setFields
private java.lang.String	m_theDuration
private long	m_years
private static int	MINUTES
private static int	MONTHS
private static java.lang.String[]	NAMES
private static int	SECONDS
private static int	YEARS

Constructor Summary

XMLDuration()

XMLDuration(java.lang.String a_duration)

XMLDuration(XMLDuration a_duration)

Method Summary

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()
private void	init()
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.
private java.lang.String	parseXMLSchemaPart(int a_field, java.lang.String a_strXMLDurationPart)
private void	setField(int a_field, java.lang.Number a_value)
java.lang.String	toString() Returns a String representation of this Duration Object.
private java.lang.String	toString(java.math.BigDecimal bd)
private java.lang.String	toStringJDK5(java.math.BigDecimal bd) Turns BigDecimal to a string representation.

Methods inherited from class java.lang.Object

clone, finalize, 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

YEARS

private static final int YEARS

See Also:

Constant Field Values

MONTHS

private static final int MONTHS

See Also:

Constant Field Values

DAYS

private static final int DAYS

See Also:

Constant Field Values

HOURS

private static final int HOURS

See Also:

Constant Field Values

MINUTES

private static final int MINUTES

See Also:

Constant Field Values

SECONDS

private static final int SECONDS

See Also:

Constant Field Values

NAMES

private static final java.lang.String[] NAMES

m_years

private long m_years

m_months

private long m_months

m_days

private long m_days

m_hours

private long m_hours

m_minutes

private long m_minutes

m_seconds

private double m_seconds

m_bNegativeSign

private boolean m_bNegativeSign

m_theDuration

private java.lang.String m_theDuration

m_setFields

private java.util.Vector m_setFields

m_calcYears

private long m_calcYears

m_calcMonths

private long m_calcMonths

m_calcDays

private long m_calcDays

m_calcHours

private long m_calcHours

m_calcMinutes

private long m_calcMinutes

m_calcSeconds

private double m_calcSeconds

m_hashCode

private int m_hashCode

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

setField

private void setField(int a_field,
                      java.lang.Number a_value)

parseXMLSchemaPart

private java.lang.String parseXMLSchemaPart(int a_field,
                                            java.lang.String a_strXMLDurationPart)
                                     throws XMLParseException

Throws:

XMLParseException

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.

toString

private java.lang.String toString(java.math.BigDecimal bd)

toStringJDK5

private java.lang.String toStringJDK5(java.math.BigDecimal bd)

Turns BigDecimal to a string representation.

Due to a behavior change in the BigDecimal.toString() method in JDK 5, this had to be implemented here.

Parameters:

bd - BigDecimal to format as a String

Returns:

String representation of BigDecimal

init

private void init()