com.ccg.util
Class TimeSpan

java.lang.Object
  com.ccg.util.TimeSpan

All Implemented Interfaces:

Serializable

public class TimeSpan
extends Object
implements Serializable

Class used to represent a span of time. This class provides some convience functions for representing a span of time (to the millisecond resolution). This is a serializable class that can be saved and restored.

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

Serialized Form

Field Summary

static int	FROM_END Constant used when setting a duration.
static int	FROM_START Constant used when setting a duration.

Constructor Summary

TimeSpan()
Create a new TimeSpan object which doesn't span any time.

TimeSpan(Date start, Date end)
Create a TimeSpan object with a specific start/end time.

TimeSpan(long start, long end)
Create a TimeSpan object with a specific start/end time.

Method Summary

boolean	containsTime(Date time) Determines if this time span contains another point in time.
boolean	containsTimeMillis(long time) Determines if this time span contains another point in time.
boolean	containsTimeSpan(TimeSpan span) Determines if this time span contains another TimeSpan object.
String	format(String fmtString) Format the TimeSpan in a configurable manner.
double	getDurationDays() Get the time spanned for the time span entry.
double	getDurationHours() Get the time spanned for the time span entry.
long	getDurationMillis() Get the time spanned for the time span entry.
double	getDurationMinutes() Get the time spanned for the time span entry.
double	getDurationSeconds() Get the time spanned for the time span entry in seconds.
Date	getEndTime() Get the ending point of the time span entry.
long	getEndTimeMillis() Get the end point of the time span entry as a millisecond count.
Date	getStartTime() Get the starting point of the time span entry.
long	getStartTimeMillis() Get the start point of the time span entry as a millisecond count.
void	intersect(TimeSpan with) Create the intersection between this object and another TimeSpan.
boolean	intersectsTimeSpan(TimeSpan span) Determines if this time span intersects with another TimeSpan object.
boolean	isEmpty() Determine if time spanned is empty (negative time spanned).
void	setDurationDays(double days, int mode) Set the time spanned for the time span entry in day units.
void	setDurationHours(double hours, int mode) Set the time spanned for the time span entry in hour units.
void	setDurationMillis(long millis, int mode) Set the time spanned for the time span entry.
void	setDurationMinutes(double minutes, int mode) Set the time spanned for the time span entry in minute units.
void	setEndTime(Date d) Set the ending point of the time span entry.
void	setEndTimeMillis(long millis) Set the ending point in time to the specified millisecond count.
void	setStartTime(Date d) Set the starting point of the time span entry.
void	setStartTimeMillis(long millis) Set the starting point in time to the specified millisecond count.
void	shiftDays(double amount) Shift the time span a specified number of days.
void	shiftHours(double amount) Shift the time span a specified number of hours.
void	shiftMillis(long millis) Shift the time span a specified number of milliseconds.
void	shiftMinutes(double minutes) Shift the time span a specified number of minutes.
void	shiftSeconds(double seconds) Shift the time span a specified number of seconds.
String	toString() Get the string representation of the time spanned.
void	union(Date d) Create the union between this object and a Date.
void	union(long milliTime) Create the union between this object and a point in time.
void	union(TimeSpan with) Create the union between this object and another TimeSpan.

Methods inherited from class java.lang.Object

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

Field Detail

FROM_START

public static final int FROM_START

Constant used when setting a duration. This constant is used as the second parameter to some of the setDurationXXX() type functions. It indicates that the duration is to be applied forwards in time from the current start point (ie adjust the end point of the time span).

Since:

1.0

See Also:

FROM_END, setDurationMillis(long, int), Constant Field Values

FROM_END

public static final int FROM_END

Constant used when setting a duration. This constant is used as the second parameter to some of the setDurationXXX() type functions. It indicates that the duration is to be applied backwards in time from the current end point (ie adjust the start point of the time span).

Since:

1.0

See Also:

FROM_START, setDurationMillis(long, int), Constant Field Values

Constructor Detail

TimeSpan

public TimeSpan()

Create a new TimeSpan object which doesn't span any time. If you create a TimeSpan object using this constructor, the object will be initialized such that the object is in a empty state. Objects created in this manner will not be of much use until you use one or more of the "set" members to adjust the start/end times.

Since:

1.0

See Also:

TimeSpan(long,long), TimeSpan(java.util.Date,java.util.Date)

TimeSpan

public TimeSpan(long start,
                long end)

Create a TimeSpan object with a specific start/end time.

Parameters:

start - Standard java millisecond time count to associate with the start of the time span.

end - Standard java millisecond time count to associate with the end of the time span.

Since:

1.0

See Also:

TimeSpan(java.util.Date,java.util.Date)

TimeSpan

public TimeSpan(Date start,
                Date end)

Create a TimeSpan object with a specific start/end time.

Parameters:

start - Time to set the start of the time span to (pass null to use the current time).

end - Time to set the end of the time span to (pass null to use the current time).

Since:

1.0

See Also:

TimeSpan(long,long)

Method Detail

setStartTimeMillis

public void setStartTimeMillis(long millis)

Set the starting point in time to the specified millisecond count. Use this function if you know the time as the standard millisecond count employed by Java to represent time with (like the System.currentTimeMillis() function returns).

Parameters:

millis - Millisecond count from 1970-Jan-1 00:00:00 GMT

Since:

1.0

See Also:

setEndTimeMillis(long), setStartTime(java.util.Date)

setStartTime

public void setStartTime(Date d)

Set the starting point of the time span entry. You can use this function to set the starting point of the time span entry to either the current time (by passing null), or the time contained by a standard java.util.Date object.

Parameters:

date - Standard Java date object (or null if you want the current time);

Since:

1.0

See Also:

setEndTime(java.util.Date), setStartTimeMillis(long)

getStartTimeMillis

public long getStartTimeMillis()

Get the start point of the time span entry as a millisecond count.

Returns:

Millisecond count from 1970-Jan-1 00:00:00 GMT

Since:

1.0

See Also:

getEndTimeMillis(), getStartTime()

getStartTime

public Date getStartTime()

Get the starting point of the time span entry. You can use this function to get the starting point of the time span entry as a standard java.util.Date object.

Returns:

Standard Java date object.

Since:

1.0

See Also:

getEndTime(), getStartTimeMillis()

setEndTimeMillis

public void setEndTimeMillis(long millis)

Set the ending point in time to the specified millisecond count. Use this function if you know the time as the standard millisecond count employed by Java to represent time with (like the System.currentTimeMillis() function returns).

Parameters:

millis - Millisecond count from 1970-Jan-1 00:00:00 GMT

Since:

1.0

See Also:

setStartTimeMillis(long), setEndTime(java.util.Date)

setEndTime

public void setEndTime(Date d)

Set the ending point of the time span entry. You can use this function to set the ending point of the time span entry to either the current time (by passing null), or the time contained by a standard java.util.Date object.

Parameters:

date - Standard Java date object (or null if you want the current time);

Since:

1.0

See Also:

setStartTime(java.util.Date), setEndTimeMillis(long)

getEndTimeMillis

public long getEndTimeMillis()

Get the end point of the time span entry as a millisecond count.

Returns:

Millisecond count from 1970-Jan-1 00:00:00 GMT

Since:

1.0

See Also:

getStartTimeMillis(), getEndTime()

getEndTime

public Date getEndTime()

Get the ending point of the time span entry. You can use this function to get the ending point of the time span entry as a standard java.util.Date object.

Returns:

Standard Java date object.

Since:

1.0

See Also:

getStartTime(), getEndTimeMillis()

setDurationMillis

public void setDurationMillis(long millis,
                              int mode)

Set the time spanned for the time span entry. This function can be used after first setting either the start time or end time associated with the time span entry. To use this function, you must specify the length of the duration, and whether the duration spans FROM_START (forwards from the current start time), or FROM_END (backwards from the current end time).

Parameters:

millis - Length of duration in milliseconds.

mode - If set to FROM_END, then the duration will be assumed to be measured backwards from the current end point in time. Otherwise the duration will be assumed to be measured forward from the current start point in time.

Since:

1.0

See Also:

setStartTime(java.util.Date), setEndTime(java.util.Date), setDurationHours(double, int)

setDurationMinutes

public final void setDurationMinutes(double minutes,
                                     int mode)

Set the time spanned for the time span entry in minute units. This function can be used after first setting either the start time or end time associated with the time span entry. To use this function, you must specify the length of the duration, and whether the duration spans FROM_START (forwards from the current start time), or FROM_END (backwards from the current end time).

Parameters:

minutes - Length of duration in minutes.

mode - If set to FROM_END, then the duration will be assumed to be measured backwards from the current end point in time. Otherwise the duration will be assumed to be measured forward from the current start point in time.

Since:

1.0

See Also:

setStartTime(java.util.Date), setEndTime(java.util.Date), setDurationMillis(long, int)

setDurationHours

public final void setDurationHours(double hours,
                                   int mode)

Set the time spanned for the time span entry in hour units. This function can be used after first setting either the start time or end time associated with the time span entry. To use this function, you must specify the length of the duration, and whether the duration spans FROM_START (forwards from the current start time), or FROM_END (backwards from the current end time).

Parameters:

hours - Length of duration in hours.

mode - If set to FROM_END, then the duration will be assumed to be measured backwards from the current end point in time. Otherwise the duration will be assumed to be measured forward from the current start point in time.

Since:

1.0

See Also:

setStartTime(java.util.Date), setEndTime(java.util.Date), setDurationMillis(long, int)

setDurationDays

public final void setDurationDays(double days,
                                  int mode)

Set the time spanned for the time span entry in day units. This function can be used after first setting either the start time or end time associated with the time span entry. To use this function, you must specify the length of the duration, and whether the duration spans FROM_START (forwards from the current start time), or FROM_END (backwards from the current end time).

Parameters:

days - Length of duration in days.

mode - If set to FROM_END, then the duration will be assumed to be measured backwards from the current end point in time. Otherwise the duration will be assumed to be measured forward from the current start point in time.

Since:

1.0

See Also:

setStartTime(java.util.Date), setEndTime(java.util.Date), setDurationMillis(long, int)

getDurationMillis

public long getDurationMillis()

Get the time spanned for the time span entry.

Returns:

Length of duration in milliseconds.

Since:

1.0

See Also:

getStartTime(), getEndTime(), getDurationHours()

getDurationSeconds

public final double getDurationSeconds()

Get the time spanned for the time span entry in seconds.

Returns:

Length of duration in seconds.

Since:

1.0

See Also:

getStartTime(), getEndTime(), getDurationMillis()

getDurationMinutes

public final double getDurationMinutes()

Get the time spanned for the time span entry.

Returns:

Length of duration in minutes.

Since:

1.0

See Also:

getStartTime(), getEndTime(), getDurationHours()

getDurationHours

public final double getDurationHours()

Get the time spanned for the time span entry.

Returns:

Length of duration in hours.

Since:

1.0

See Also:

getStartTime(), getEndTime(), getDurationDays()

getDurationDays

public final double getDurationDays()

Get the time spanned for the time span entry.

Returns:

Length of duration in days.

Since:

1.0

See Also:

getStartTime(), getEndTime(), getDurationMillis()

containsTimeMillis

public boolean containsTimeMillis(long time)

Determines if this time span contains another point in time.

Parameters:

time - Time to check.

Returns:

true if time to check falls within time spanned by this object.

Since:

1.0

See Also:

containsTimeSpan(com.ccg.util.TimeSpan), containsTime(java.util.Date)

containsTime

public boolean containsTime(Date time)

Determines if this time span contains another point in time.

Parameters:

time - Time to check (if you pass null, the current system time will be checked).

Returns:

true if time to check falls within time spanned by this object.

Since:

1.0

See Also:

containsTimeSpan(com.ccg.util.TimeSpan), containsTimeMillis(long)

containsTimeSpan

public boolean containsTimeSpan(TimeSpan span)

Determines if this time span contains another TimeSpan object.

Parameters:

span - TimeSpan object to check (must not be null).

Returns:

true if this time span contains the time span object passed.

Since:

1.0

See Also:

containsTime(java.util.Date), containsTimeMillis(long), intersectsTimeSpan(com.ccg.util.TimeSpan)

intersectsTimeSpan

public boolean intersectsTimeSpan(TimeSpan span)

Determines if this time span intersects with another TimeSpan object.

Parameters:

span - TimeSpan object to check for intersection (must not be null).

Returns:

true if this time span intersects the time span object passed.

Since:

1.0

See Also:

containsTimeSpan(com.ccg.util.TimeSpan)

intersect

public void intersect(TimeSpan with)

Create the intersection between this object and another TimeSpan. This method allows one to create the intersection between the time spanned by this object and the time spanned by another TimeSpan object. The results of the intersection will be stored in this object. The other time span passed as a parameter will be unaffected. It is possible that the two objects don't actually intersect. You can use the isEmpty() method to check for this condition (it will return true if the two time spans didn't overlap).

NOTE: If the result is empty, then the duration spanned will be negative for this object and any use of the "contains" methods will return false for all points in time and non-negative time spans. In other words, a empty time span will behave as one would expect (or hope for).

Parameters:

with - Another TimeSpan object to form the intersection with (it will remain unchanged). Must not be null.

Since:

1.0

See Also:

union(com.ccg.util.TimeSpan), intersectsTimeSpan(com.ccg.util.TimeSpan), isEmpty()

union

public void union(TimeSpan with)

Create the union between this object and another TimeSpan. This method allows one to create the union between the time spanned by this object and the time spanned by another TimeSpan object. The results of the union will be stored in this object and the time spanned will be just large enough to contain both of the two original time spans. The other time span passed as a parameter will be unaffected.

Parameters:

with - Another TimeSpan object to form the union with (it will remain unchanged). Must not be null.

Since:

1.0

See Also:

intersect(com.ccg.util.TimeSpan), isEmpty()

union

public void union(Date d)

Create the union between this object and a Date.

This method expands the time span (if necessary) such that the Date object specified will be contained. This may move the end or start time of the time span. The resulting duration of time spanned after invoking this method will be larger than or equal to its prior duration (the time span will never shrink).

Parameters:

d - A Date object to form the union with (null is OK - just results in nothing being done). Time spanned will be enlarged (if necessary) to include this specified point in time.

Since:

1.0

See Also:

union(TimeSpan)

union

public void union(long milliTime)

Create the union between this object and a point in time.

This method expands the time span (if necessary) such that the point in time specified will be contained. This may move the end or start time of the time span. The resulting duration of time spanned after invoking this method will be larger than or equal to its prior duration (the time span will never shrink).

Parameters:

timeMilli - A standard Java millisecond count which represents a point in time. The time spanned will be enlarged (if necessary) to include this specified point in time.

Since:

1.0

See Also:

union(TimeSpan)

isEmpty

public boolean isEmpty()

Determine if time spanned is empty (negative time spanned). After intersecting one TimeSpan object with another, one may want to use this method to check and see if the resulting intersection was empty (ie the two time spans which the intersection was performed on didn't have any common area). Any TimeSpan object which is empty will always return false when you check to see if it contains a single point in time or a non-empty TimeSpan object.

Returns:

true if time is spanned is negative (start time is less then the end time). This could result from a intersection.

Since:

1.0

See Also:

intersect(com.ccg.util.TimeSpan)

format

public String format(String fmtString)

Format the TimeSpan in a configurable manner. This routine is designed to allow one to format a time span in a configurable manner. If you just want the default format, you can use the toString() method. You pass this function a string (or null) in a standard java.text.MessageFormat style. The subsitution fields defined are:

{0,date}

Start time of span

{1,date}

End time of span

{2,number}

Duration of time span in milliseconds

{3,number}

Duration of time span in seconds

{4,number}

Duration of time span in minutes

{5,number}

Duration of time span in hours

{6,number}

Duration of time span in days

Parameters:

formatString - A specific format string, or null if you want the default of "[START,END]" where the times are formatted in the ISO standard fashion.

Returns:

Formatted results

Since:

1.0

See Also:

toString()

toString

public String toString()

Get the string representation of the time spanned.

Overrides:

toString in class Object

Returns:

String representation of object in standard format.

Since:

1.0

See Also:

format(java.lang.String)

shiftMillis

public void shiftMillis(long millis)

Shift the time span a specified number of milliseconds. Use this function if you want to "shift" your time span either forwards (positive amount) or backwards (negative amount). This is a easy way to move the window of time spanned a specific amount.

Parameters:

amount - Millisecond duration (positive to shift forward in time, negative to shift backwards) to adjust your time span by.

Since:

1.0

See Also:

shiftSeconds(double), shiftMinutes(double), shiftHours(double), shiftDays(double)

shiftSeconds

public void shiftSeconds(double seconds)

Shift the time span a specified number of seconds. Use this function if you want to "shift" your time span either forwards (positive amount) or backwards (negative amount). This is a easy way to move the window of time spanned a specific amount.

Parameters:

amount - Duration, in seconds, to adjust your time span by. Positive to shift forward in time, negative to shift backwards.

Since:

1.0

See Also:

shiftMillis(long)

shiftMinutes

public void shiftMinutes(double minutes)

Shift the time span a specified number of minutes. Use this function if you want to "shift" your time span either forwards (positive amount) or backwards (negative amount). This is a easy way to move the window of time spanned a specific amount.

Parameters:

amount - Duration, in minutes, to adjust your time span by. Positive to shift forward in time, negative to shift backwards.

Since:

1.0

See Also:

shiftMillis(long)

shiftHours

public void shiftHours(double amount)

Shift the time span a specified number of hours. Use this function if you want to "shift" your time span either forwards (positive amount) or backwards (negative amount). This is a easy way to move the window of time spanned a specific amount.

Parameters:

amount - Duration, in hours, to adjust your time span by. Positive to shift forward in time, negative to shift backwards.

Since:

1.0

See Also:

shiftMillis(long)

shiftDays

public void shiftDays(double amount)

Shift the time span a specified number of days. Use this function if you want to "shift" your time span either forwards (positive amount) or backwards (negative amount). This is a easy way to move the window of time spanned a specific amount.

Parameters:

amount - Duration, in days, to adjust your time span by. Positive to shift forward in time, negative to shift backwards.

Since:

1.0

See Also:

shiftMillis(long)