com.prozima.time
Class TimeTable

java.lang.Object
  com.prozima.time.TimeTable

All Implemented Interfaces:

java.lang.Cloneable

public class TimeTable
extends java.lang.Object
implements java.lang.Cloneable

A timetable stores periods of time, which are referenced by date or by day of the week. The significance of each time period depends on the application which utilises this class. Time periods, which are defined for a specific date, take precedence over periods defined for a day of the week. If no periods have been defined for a specific date or the day of the week it falls on, then there are no periods available for this date.

When time periods are stored for a day of the week, they are associated with an era. Eras allow day specified time periods to vary with time. Each era is associated with a starting date from which the era applies. Dates on or after this starting date use the day of the week periods which correspond to that era. In this way, patterns of time periods which vary through time may be created. Each era applies until the starting date of the following era, if one is specified. By default there is a default era defined, which has ID DEFAULT_ERA_ID.

As date specified time periods take precedence over day specified periods, it is necessary to specify when no time periods are available for a specific date and that the day of week periods should not be used. The method setIsUnavailable(int, int) allows a specific date to be flagged as having no time periods available.

Field Summary

static int

DEFAULT_ERA_ID ID of the default Era.

Constructor Summary

TimeTable()
Create a new instance of a time table.

Method Summary

boolean	addTimePeriod(int inYear, int inDayOfYear, TimePeriod inTimePeriod) Set a time period for a specific date.
boolean	addTimePeriod(int inEraID, TimeConstants.DayOfWeek inDay, TimePeriod inTimePeriod) Set a time period for a day of the week.
void	clearTimePeriods(int inYear, int inDayOfYear) Clear all the stored time periods for a specific date.
void	clearTimePeriods(TimeConstants.DayOfWeek inDay) Clear all the stored time periods for a day of the week.
TimeTable	clone()
static TimeTable	combine(TimeTable inBase, TimeTable inOther) Combine two TimeTables into one.
java.lang.Integer	createEra(DayAndYear inStart) Create a new Era which is used to control DayOfWeek time periods.
boolean	equals(java.lang.Object inObject)
java.lang.Integer	findEraID(DayAndYear inStart) Reverse lookup the Era ID which corresponds to an Era starting date.
java.util.Set<java.lang.Integer>	getAllEraIDs() Get set of all defined Era IDs.
java.util.List<TimePeriod>	getAllTimePeriods(java.util.Date inStartDate, int inDuration) Get all the time periods between a start time and end time of a specific day.
DayAndYear	getEarliestDate() Get the earliest date currently used to index a TimePeriod.
DayAndYear	getLatestDate() Get the latest date currently used to index a TimePeriod.
java.util.Set<DayAndYear>	getModifiedDates() Get all the specific days for which this TimeTable has time periods.
java.util.List<TimePeriod>	getTimePeriods(DayAndYear inDayAndYear) Get a list of the time periods stored for a specific date.
java.util.List<TimePeriod>	getTimePeriods(int inYear, int inDayOfYear) Get a list of the time periods stored for a specific date.
java.util.List<TimePeriod>	getTimePeriods(int inEraID, TimeConstants.DayOfWeek inDayOfWeek) Get a list of the time periods for a specific Day of the Week.
int	getTotalDuration(java.util.Date inStart, int inDuration) Get the total duration of time periods between a Start time and End time of the same day.
int	hashCode()
boolean	removeEra(int inEraID) Remove a previously created Era.
void	setIsUnavailable(int inYear, int inDayOfYear) Set a date as having no available time periods.
boolean	subtractTimePeriod(int inYear, int inDayOfYear, TimePeriod inTimePeriod) Subtract a time period for a specific date.
boolean	subtractTimePeriod(int inEraID, TimeConstants.DayOfWeek inDay, TimePeriod inTimePeriod) Subtract a time period for a day of the week.
java.lang.String	toString() Display full contents of the timetable in text format.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_ERA_ID

public static final int DEFAULT_ERA_ID

ID of the default Era. Era begins with the earliest possible start date. This Era cannot be deleted and its start date cannot be modified. All subsequently created Eras have an ID which is larger than this value.

See Also:

Constant Field Values

Constructor Detail

TimeTable

public TimeTable()

Create a new instance of a time table.

Method Detail

addTimePeriod

public boolean addTimePeriod(int inYear,
                             int inDayOfYear,
                             TimePeriod inTimePeriod)

Set a time period for a specific date. These time periods have a higher priority than periods defined for a day of the week.

Parameters:

inYear - Year in Calendar.YEAR format.

inDayOfYear - Day of the year in Calendar.DAY_OF_YEAR format.

inTimePeriod - A time period which is to be stored.

Returns:

true if the time period could be set ok, otherwise false.

addTimePeriod

public boolean addTimePeriod(int inEraID,
                             TimeConstants.DayOfWeek inDay,
                             TimePeriod inTimePeriod)

Set a time period for a day of the week. These periods have a lower priority than periods defined for a specific date. If the new period overlaps with an already existing time period, they will be consolidated.

Parameters:

inEraID - ID of the Era.

inDay - A specific day of the week.

inTimePeriod - A time period.

Returns:

true if the time period could be set ok, otherwise false.

clearTimePeriods

public void clearTimePeriods(int inYear,
                             int inDayOfYear)

Clear all the stored time periods for a specific date. If the date has previously been set as "unavailable" then this flag is also cleared. Effect is that after calling this method for a specific date, only the day of week time periods for this date will apply.

Parameters:

inYear - Year in Calendar.YEAR format.

inDayOfYear - Day of the year in Calendar.DAY_OF_YEAR format.

clearTimePeriods

public void clearTimePeriods(TimeConstants.DayOfWeek inDay)

Clear all the stored time periods for a day of the week. Calling this method does not clear time periods for any specific date.

Parameters:

inDay - A day of the week.

clone

public TimeTable clone()
                throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

combine

public static final TimeTable combine(TimeTable inBase,
                                      TimeTable inOther)

Combine two TimeTables into one. Day of Week and Date TimePeriods from the inOther TimeTable take priority over the inBase TimePeriods.

Parameters:

inBase - Base TimeTable - lowest priority.

inOther - TimeTable with highest priority.

Returns:

New TimeTable that combines both.

createEra

public java.lang.Integer createEra(DayAndYear inStart)

Create a new Era which is used to control DayOfWeek time periods.

Parameters:

inStart - Start of the era.

Returns:

ID allocated to the Era or null if no Era could be created. If an Era already exists with the same start then its ID is returned.

equals

public boolean equals(java.lang.Object inObject)

Overrides:

equals in class java.lang.Object

findEraID

public java.lang.Integer findEraID(DayAndYear inStart)

Reverse lookup the Era ID which corresponds to an Era starting date.

Parameters:

inStart - Start date of the Era. If parameter is null then method will return null.

Returns:

ID of the Era or null if no Era exists which has this start date.

getAllEraIDs

public java.util.Set<java.lang.Integer> getAllEraIDs()

Get set of all defined Era IDs.

Returns:

Set of IDs identifying each Era.

getAllTimePeriods

public java.util.List<TimePeriod> getAllTimePeriods(java.util.Date inStartDate,
                                                    int inDuration)

Get all the time periods between a start time and end time of a specific day. This includes all date-specific and day of week specific time periods. Partial time periods are returned if they span the start or end times.

Parameters:

inStartDate - Start date and time.

inDuration - Duration of period to be examined in Minutes. Zero duration will result in empty result list. Must not be a negative number.

Returns:

List of time periods. List is empty if no time periods overlap with this span of time.

getEarliestDate

public DayAndYear getEarliestDate()

Get the earliest date currently used to index a TimePeriod. This only applies to TimePeriods stored by the method addTimePeriod(int, int, TimePeriod).

Returns:

DayAndYear or null if there are no TimePeriods stored by date.

getLatestDate

public DayAndYear getLatestDate()

Get the latest date currently used to index a TimePeriod. This only applies to TimePeriods stored by the method addTimePeriod(int, int, TimePeriod).

Returns:

DayAndYear or null if there are no TimePeriods stored by date.

getModifiedDates

public java.util.Set<DayAndYear> getModifiedDates()

Get all the specific days for which this TimeTable has time periods.

Returns:

Set of DayAndYear objects.

getTimePeriods

public java.util.List<TimePeriod> getTimePeriods(DayAndYear inDayAndYear)

Get a list of the time periods stored for a specific date. None of the time periods stored for whatever Day of the Week this is are returned.

Parameters:

inDayAndYear - Specific day and year.

Returns:

A List of TimePeriods.

getTimePeriods

public java.util.List<TimePeriod> getTimePeriods(int inYear,
                                                 int inDayOfYear)

Get a list of the time periods stored for a specific date. None of the time periods stored for whatever day of the week this is are returned.

Parameters:

inYear - Year in Calendar.YEAR format.

inDayOfYear - Day of the year in Calendar.DAY_OF_YEAR format.

Returns:

A list of time periods. List may be empty.

getTimePeriods

public java.util.List<TimePeriod> getTimePeriods(int inEraID,
                                                 TimeConstants.DayOfWeek inDayOfWeek)

Get a list of the time periods for a specific Day of the Week.

Parameters:

inEraID - ID of the Era.

inDayOfWeek - Day of the week.

Returns:

A list of time periods. List may be empty if no time periods are defined.

getTotalDuration

public int getTotalDuration(java.util.Date inStart,
                            int inDuration)

Get the total duration of time periods between a Start time and End time of the same day. This includes all date-specific or Day of Week specific time periods.

Parameters:

inStart - Start date/time.

inDuration - Duration of period being checked.

Returns:

Duration in Minutes of all the periods between two times.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

removeEra

public boolean removeEra(int inEraID)

Remove a previously created Era. All time periods stored for this Era are also deleted. The default Era can never be deleted.

Parameters:

inEraID - ID of the Era.

Returns:

true if an Era exists with this ID and it was successfully removed. false if an Era does not exist with this ID.

setIsUnavailable

public void setIsUnavailable(int inYear,
                             int inDayOfYear)

Set a date as having no available time periods. This method of flagging specific dates as unavailable is required because normally, when a date has no time periods set, the time periods for the corresponding day of the week are used. Therefore, it is required to flag dates for which there are no time periods.

Parameters:

inYear - Year in Calendar.YEAR format.

inDayOfYear - Day of the year in Calendar.DAY_OF_YEAR format.

subtractTimePeriod

public boolean subtractTimePeriod(int inYear,
                                  int inDayOfYear,
                                  TimePeriod inTimePeriod)

Subtract a time period for a specific date. Where this period does not overlap with an already present period, there will be no effect.

Parameters:

inYear - Year in Calendar.YEAR format.

inDayOfYear - Day of the year in Calendar.DAY_OF_YEAR format.

inTimePeriod - A time period.

Returns:

true if the time period could be subtracted ok, otherwise false.

subtractTimePeriod

public boolean subtractTimePeriod(int inEraID,
                                  TimeConstants.DayOfWeek inDay,
                                  TimePeriod inTimePeriod)

Subtract a time period for a day of the week. Where this period does not overlap with an already present period, there will be no effect.

Parameters:

inEraID - ID of the Era.

inDay - A day of the week.

inTimePeriod - A time period which is to be subtracted.

Returns:

true if the time period could be subtracted ok, otherwise false.

toString

public java.lang.String toString()

Display full contents of the timetable in text format. Designed to help with debugging and nothing else.

Overrides:

toString in class java.lang.Object