edu.columbia.cpl
Class Duration

java.lang.Object
  edu.columbia.cpl.Duration

All Implemented Interfaces:

Cloneable

public class Duration

extends Object

implements Cloneable

Duration represents a duration field in an iCalendar recurrence or a CPL time-switch.

It represents a duration of time, expressed as a number of days, hours, minutes, and seconds, or a number of weeks.

The iCalendar spec forbids a duration from simultaneously specifying weeks and other units. The Duration class enforces this restriction. Trying to specify a week value when there are any non-zero non-week values, or a non-week value when there is a non-zero week value, will throw an InvalidStateException exception.

Values may be specified which are larger than permitted for their enclosing fields. They will be normalized appropriately.

Change history:

1.0

Initial version

See Also:

Recurrence

Constructor Summary

Duration()
Construct a Duration object and initializes it to a zero-length interval.

Duration(int w)
Construct a Duration object with the specified duration.

Duration(int h, int m, int s)
Construct a Duration object with the specified duration.

Duration(int d, int h, int m, int s)
Construct a Duration object with the specified duration.

Duration(String s)
Construct a Duration object described by the given string.

Method Summary

protected void	checkNonWeeksOkay(int f) Check if it would be okay to set a non-weeks field of this duration.
protected void	checkWeeksOkay(int f) Check if it would be okay to set the weeks field of this duration.
void	clear() Reset the duration to a zero-length interval.
Object	clone() Overrides Cloneable
int	getDays() Get the days field of this duration.
int	getHours() Get the hours field of this duration.
long	getInterval() Get the interval represented by this Duration, in milliseconds.
int	getMinutes() Get the minutes field of this duration.
int	getSeconds() Get the seconds field of this duration.
String	getString() Get the standardized string representation of the Duration.
int	getWeeks() Get the weeks field of this duration.
protected void	normalize() Normalize the duration, so that every field is within its legal range.
void	setDays(int d) Set the days field of this duration.
void	setHours(int h) Set the hours field of this duration.
void	setInterval(long millis) Set the duration's interval to the specified number of milliseconds.
void	setMinutes(int m) Set the minutes field of this duration.
void	setSeconds(int s) Set the seconds field of this duration.
void	setString(String str) Set the value of the Duration object to the given string.
void	setWeeks(int w) Set the weeks field of this duration.
String	toString() Return a string representation of this duration.

Methods inherited from class java.lang.Object

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

Constructor Detail

Duration

public Duration()

Construct a Duration object and initializes it to a zero-length interval.

Duration

public Duration(int d,
                int h,
                int m,
                int s)

Construct a Duration object with the specified duration.

Parameters:

d - The number of days.

h - The number of hours.

m - The number of minutes.

s - The number of seconds.

Duration

public Duration(int h,
                int m,
                int s)

Construct a Duration object with the specified duration.

Parameters:

h - The number of hours.

m - The number of minutes.

s - The number of seconds.

Duration

public Duration(int w)

Construct a Duration object with the specified duration.

Parameters:

w - The number of weeks.

Duration

public Duration(String s)

Construct a Duration object described by the given string. A duration string is defined as follows, according to RFC 2445:

     dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)

     dur-date   = dur-day [dur-time]
     dur-time   = "T" (dur-hour / dur-minute / dur-second)
     dur-week   = 1*DIGIT "W"
     dur-hour   = 1*DIGIT "H" [dur-minute]
     dur-minute = 1*DIGIT "M" [dur-second]
     dur-second = 1*DIGIT "S"
     dur-day    = 1*DIGIT "D"
 

Parameters:

s - The string representation of the duration.

Throws:

IllegalArgumentException - If the given string does not describe a valid Duration

Method Detail

clear

public void clear()

Reset the duration to a zero-length interval.

setString

public void setString(String str)

Set the value of the Duration object to the given string. A duration string is defined as follows, according to RFC 2445:

     dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)

     dur-date   = dur-day [dur-time]
     dur-time   = "T" (dur-hour / dur-minute / dur-second)
     dur-week   = 1*DIGIT "W"
     dur-hour   = 1*DIGIT "H" [dur-minute]
     dur-minute = 1*DIGIT "M" [dur-second]
     dur-second = 1*DIGIT "S"
     dur-day    = 1*DIGIT "D"
 

Parameters:

str - The string representation of the duration.

Throws:

IllegalArgumentException - If the given string does not describe a valid Duration

getString

public String getString()

Get the standardized string representation of the Duration.

Returns:

The string representation, of the form P(W|[D]T[H][M][S]). A zero-time duration is represented as PT0S.

getWeeks

public int getWeeks()

Get the weeks field of this duration.

Returns:

The number of weeks.

setWeeks

public void setWeeks(int w)

Set the weeks field of this duration.

Parameters:

w - The number of weeks.

Throws:

IllegalArgumentException - If w is negative.

IllegalStateException - If any non-week field is set.

getDays

public int getDays()

Get the days field of this duration.

Returns:

The number of days.

setDays

public void setDays(int d)

Set the days field of this duration.

Parameters:

d - The number of days.

Throws:

IllegalArgumentException - If d is negative.

IllegalStateException - If the week field is set.

getHours

public int getHours()

Get the hours field of this duration.

Returns:

The number of hours.

setHours

public void setHours(int h)

Set the hours field of this duration.

Parameters:

h - The number of hours.

Throws:

IllegalArgumentException - If h is negative.

IllegalStateException - If the week field is set.

getMinutes

public int getMinutes()

Get the minutes field of this duration.

Returns:

The number of minutes.

setMinutes

public void setMinutes(int m)

Set the minutes field of this duration.

Parameters:

m - The number of minutes.

Throws:

IllegalArgumentException - If m is negative.

IllegalStateException - If the week field is set.

getSeconds

public int getSeconds()

Get the seconds field of this duration.

Returns:

The number of seconds.

setSeconds

public void setSeconds(int s)

Set the seconds field of this duration.

Parameters:

s - The number of days.

Throws:

IllegalArgumentException - If s is negative.

IllegalStateException - If the week field is set.

getInterval

public long getInterval()

Get the interval represented by this Duration, in milliseconds. Pure Gregorian time is used; leap-seconds and daylight-savings time transitions are ignored.

Returns:

the number of milliseconds equivalent to this duration.

setInterval

public void setInterval(long millis)

Set the duration's interval to the specified number of milliseconds. Pure-Gregorian time is used; leap-seconds and daylight-savings time transitions are ignored. The duration is rounded to a whole number of seconds. The duration is broken down into the days, hours, minutes, and seconds fields; the weeks field will be zero after this method is called.

Parameters:

millis - The number of milliseconds for this duration.

Throws:

IllegalArgumentException - If millis is negative.

normalize

protected void normalize()

Normalize the duration, so that every field is within its legal range.

checkWeeksOkay

protected void checkWeeksOkay(int f)

Check if it would be okay to set the weeks field of this duration. This is allowed if none of the other fields are set, or if the prospective value for the weeks field is zero.

Parameters:

f - The prospective value for the weeks field

Throws:

IllegalStateException - If it wouldn't be okay.

checkNonWeeksOkay

protected void checkNonWeeksOkay(int f)

Check if it would be okay to set a non-weeks field of this duration. This is allowed if the weeks field is not set, or if the prospective value for this non-weeks field is zero.

Parameters:

f - The prospective value for the non-weeks field

Throws:

IllegalStateException - If it wouldn't be okay.

clone

public Object clone()

Overrides Cloneable

Returns:

A clone of this object.

toString

public String toString()

Return a string representation of this duration. This method is intended to be used only for debugging purposes. The returned string may be empty but may not be null.

Returns:

a string representation of this duration.