uk.ac.ed.epcc.safe.accounting.parsers.value

Class XMLDurationParser

java.lang.Object

uk.ac.ed.epcc.safe.accounting.parsers.value.XMLDurationParser

All Implemented Interfaces:

ValueFormatter<uk.ac.ed.epcc.webapp.model.data.Duration>, ValueParser<uk.ac.ed.epcc.webapp.model.data.Duration>

public class XMLDurationParser
extends java.lang.Object
implements ValueParser<uk.ac.ed.epcc.webapp.model.data.Duration>

Parser that parses a string into a duration measured in seconds (represented as a Number. The number may be a floating point number if the time was measured to an accuracy greater than a second. The format of the string should follow the XML schema Duration specification. A NullPointerException is thrown if the string provided is null.

Durations are harder to parse than most strings that represent one entity. Durations can be specified using days, months and years. The length in seconds of a month and year vary depending when the measurement was made. In the same way, if a duration is measured by observing the time at the start and end of the duration, the length of a day can vary if the measurement was made across a day boundary when daylight saving changes were applied.

This parser takes two approaches to parsing a duration. If used in the same way as other ValueParsers, this parser takes no arguments. In this mode it can parse any duration that does not contain months or years. Days are assumed to always be 24 hours long (i.e. daylight saving changes are ignored). If months and years are present in a duration when a parser is in this mode, the parse will fail. Alternatively, a date can be specified for when the duration started. This can be done at construction time or after using the appropriate setter method. All durations may then be parsed. In this mode, daylight saving changes will be taken into account.

The parser uses the DatatypeFactory factory to generate Duration objects to parse it's dates (regardless of which mode it is in). As such, has the same restrictions as the factory when generating Duration objects from a string. The parser also makes use of some of the int returning methods in Duration and as such is susceptible to integer overflow as stated in Duration's documentation. This should only happen for very large durations.

Author:

jgreen4

Field Summary

Fields

Modifier and Type	Field and Description
static XMLDurationParser	PARSER WARNING: this default static parser is constructed using the no-argument constructor of XMLDurationParser.

Constructor Summary

Constructors

Constructor and Description
XMLDurationParser()
XMLDurationParser(java.util.Calendar durationStart)
XMLDurationParser(java.util.Date durationStart)

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	format(uk.ac.ed.epcc.webapp.model.data.Duration duration) Formats the duration as an XML duration.
java.lang.Class<uk.ac.ed.epcc.webapp.model.data.Duration>	getType() Returns the Class of object this ValueParser can handle.
uk.ac.ed.epcc.webapp.model.data.Duration	parse(java.lang.String valueString) Parses an XML duration string and converts it into a duration in seconds.
javax.xml.datatype.Duration	parseToDuration(java.lang.String valueString) Convenient method to parse a string into a Duration object instead of a Java Date object.
void	setStartOfDuration(java.util.Calendar durationStart)
void	setStartOfDuration(java.util.Date durationStart)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PARSER

public static final XMLDurationParser PARSER

WARNING: this default static parser is constructed using the no-argument constructor of XMLDurationParser. As such it suffers the limitations of the parser in this state. See the documentation for this class for more information as to what they are.

Constructor Detail

XMLDurationParser

public XMLDurationParser()

XMLDurationParser

public XMLDurationParser(java.util.Date durationStart)

XMLDurationParser

public XMLDurationParser(java.util.Calendar durationStart)

Method Detail

getType

public java.lang.Class<uk.ac.ed.epcc.webapp.model.data.Duration> getType()

Description copied from interface: ValueParser

Returns the Class of object this ValueParser can handle. The ValueParser.parse(String) method must return objects that are assignable to this type. The #format(T) method can format any object assignable to this type. The returned class will be the exact Class (i.e. not a subclass) of this ValueParser's type

Specified by:

getType in interface ValueFormatter<uk.ac.ed.epcc.webapp.model.data.Duration>

Specified by:

getType in interface ValueParser<uk.ac.ed.epcc.webapp.model.data.Duration>

Returns:

The Type of this ValueParser

setStartOfDuration

public void setStartOfDuration(java.util.Date durationStart)

setStartOfDuration

public void setStartOfDuration(java.util.Calendar durationStart)

parse

public uk.ac.ed.epcc.webapp.model.data.Duration parse(java.lang.String valueString)
                                               throws java.lang.IllegalArgumentException,
                                                      java.lang.NullPointerException

Parses an XML duration string and converts it into a duration in seconds. This operation can be greatly complicated if the duration features a number of days, months or years. In this situation, it is impossible to determine the number of seconds that have occurred in the duration without knowing when the duration started because the number of seconds in a day/month/year depends on which day/month/year was measured. This parser allows the start date of a duration to be set.

If a parse is attempted without the start date being set, this parser attempts to parse the duration anyway. If the duration contains months and years, the parse will fail. If the duration contains days, the parser assumes a day contains 24 hours. This is usually correct but can be wrong if duration is measured using the start and end time of an event when the event happens over a change in daylight saving changes (then, a day appears to have 23 or 25 hours in it when measuring duration as the difference between start and end datetimes).

Specified by:

parse in interface ValueParser<uk.ac.ed.epcc.webapp.model.data.Duration>

Throws:

java.lang.IllegalArgumentException

java.lang.NullPointerException

Parameters:

valueString - The string to parse

Returns:

The object representation of valueString

See Also:

ValueParser.parse(java.lang.String)

parseToDuration

public javax.xml.datatype.Duration parseToDuration(java.lang.String valueString)
                                            throws java.lang.IllegalArgumentException

Convenient method to parse a string into a Duration object instead of a Java Date object.

Throws:

java.lang.IllegalArgumentException - If valueString cannot be parsed into a Duration object

Parameters:

valueString - The string to parse

Returns:

The Duration object valueString represents

format

public java.lang.String format(uk.ac.ed.epcc.webapp.model.data.Duration duration)

Formats the duration as an XML duration. The units used are hours, minutes, seconds and milliseconds. The duration uses as much of the largest unit as it can before moving down to the next biggest unit until the duration is completely represented. For example. Three hours, sixty minutes will always be represented as PT4H and never, PT3H60M. The formatted string will be as accurate as the duration given to it, but it may be more precise than the given duration.

Specified by:

format in interface ValueFormatter<uk.ac.ed.epcc.webapp.model.data.Duration>

Specified by:

format in interface ValueParser<uk.ac.ed.epcc.webapp.model.data.Duration>

Parameters:

duration - The object to format

Returns:

the duration as an XML duration

See Also:

ValueFormatter.format(java.lang.Object)