MPXJ: Microsoft Project Exchange

net.sf.mpxj
Class ProjectCalendar

java.lang.Object
  net.sf.mpxj.ProjectEntity
      net.sf.mpxj.ProjectCalendar

public final class ProjectCalendar
extends ProjectEntity

This class represents the a Calendar Definition record. Both base calendars and calendars derived from base calendars are represented by instances of this class. The class is used to define the working and non-working days of the week. The default calendar defines Monday to Friday as working days.

Field Summary

static int	DEFAULT Constant used to represent that a day in a derived calendar used the value specified in the base calendar to indicate if it is working or not.
static java.lang.String	DEFAULT_BASE_CALENDAR_NAME Default base calendar name to use when none is supplied.
static java.util.Date	DEFAULT_END1
static java.util.Date	DEFAULT_END2
static java.util.Date	DEFAULT_START1
static java.util.Date	DEFAULT_START2
static int	NON_WORKING Constant used to represent a non-working day.
static int	WORKING Constant used to represent a working day.

Constructor Summary

ProjectCalendar(ProjectFile file)
Default constructor.

ProjectCalendar(ProjectFile file, ProjectCalendar taskCalendar, ProjectCalendar resourceCalendar)
Create a calendar based on the intersection of a task calendar and a resource calendar.

Method Summary

ProjectCalendarException	addCalendarException() Used to add exceptions to the calendar.
ProjectCalendarHours	addCalendarHours() Adds a set of hours to this calendar without assigning them to a particular day.
ProjectCalendarHours	addCalendarHours(Day day) Used to add working hours to the calendar.
void	addDefaultCalendarHours() This is a convenience method used to add a default set of calendar hours to a calendar.
void	addDefaultCalendarHours(Day day) This is a convenience method used to add a default set of calendar hours to a calendar.
protected void	addDerivedCalendar(ProjectCalendar calendar) Add a reference to a calendar derived from this one.
void	attachHoursToDay(ProjectCalendarHours hours) Attaches a pre-existing set of hours to the correct day within the calendar.
ProjectCalendar	getBaseCalendar() Retrieve the ProjectCalendar instance from which this calendar is derived.
java.util.List<ProjectCalendarException>	getCalendarExceptions() This method retrieves a list of exceptions to the current calendar.
ProjectCalendarHours	getCalendarHours(Day day) This method retrieves the calendar hours for the specified day.
java.util.Date	getDate(java.util.Date startDate, Duration duration, boolean returnNextWorkStart) Given a start date and a duration, this method calculates the end date.
int[]	getDays() Retrieve an array representing the days of the week for this calendar.
java.util.List<ProjectCalendar>	getDerivedCalendars() Retrieve a list of derived calendars.
Duration	getDuration(java.util.Date startDate, java.util.Date endDate) This method is provided to allow an absolute period of time represented by start and end dates into a duration in working days based on this calendar instance.
ProjectCalendarException	getException(java.util.Date date) Retrieve a calendar calendar exception which applies to this date.
java.util.Date	getFinishTime(java.util.Date date) Retrieves the time at which work finishes on the given date, or returns null if this is a non-working day.
ProjectCalendarHours[]	getHours() Retrieve an array representing all of the calendar hours defined by this calendar.
ProjectCalendarHours	getHours(Day day) This method retrieves the calendar hours for the specified day.
java.lang.String	getName() Calendar name.
java.util.Date	getNextWorkStart(java.util.Date date) Utility method to retrieve the next working date time, given a date and time as a starting point.
Resource	getResource() Retrieve the resource to which this calendar is linked.
java.util.Date	getStartDate(java.util.Date finishDate, Duration duration) Given a finish date and a duration, this method calculates backwards to the start date.
java.util.Date	getStartTime(java.util.Date date) Retrieves the time at which work starts on the given date, or returns null if this is a non-working day.
java.lang.Integer	getUniqueID() Accessor method to retrieve the unique ID of this calendar.
Duration	getWork(java.util.Date startDate, java.util.Date endDate, TimeUnit format) This method retrieves a Duration instance representing the amount of work between two dates based on this calendar.
Duration	getWork(java.util.Date date, TimeUnit format) Retrieves the amount of work on a given day, and returns it in the specified format.
int	getWorkingDay(Day day) This method allows the retrieval of the actual working day flag, which can take the values DEFAULT, WORKING, or NONWORKING.
boolean	isBaseCalendar() This method returns a flag indicating if this ProjectCalendar instance represents a base calendar.
boolean	isWorkingDate(java.util.Date date) This method allows the caller to determine if a given date is a working day.
boolean	isWorkingDay(Day day) Method indicating whether a day is a working or non-working day.
void	remove() Removes this calendar from the project.
protected void	removeDerivedCalendar(ProjectCalendar calendar) Remove a reference to a derived calendar.
void	removeHoursFromDay(ProjectCalendarHours hours) Removes a set of calendar hours from the day to which they are currently attached.
void	setBaseCalendar(ProjectCalendar calendar) Sets the ProjectCalendar instance from which this calendar is derived.
void	setName(java.lang.String name) Calendar name.
void	setResource(Resource resource) Sets the resource to which this calendar is linked.
void	setUniqueID(java.lang.Integer uniqueID) Modifier method to set the unique ID of this calendar.
void	setWorkingDay(Day day, boolean working) convenience method for setting working or non-working days.
void	setWorkingDay(Day day, int working) This is a convenience method provided to allow a day to be set as working or non-working, by using the day number to identify the required day.
void	setWorkingDay(Day day, java.lang.Integer working) This is a convenience method provided to allow a day to be set as working or non-working, by using the day number to identify the required day.
java.lang.String	toString()

Methods inherited from class net.sf.mpxj.ProjectEntity

getParentFile

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BASE_CALENDAR_NAME

public static final java.lang.String DEFAULT_BASE_CALENDAR_NAME

Default base calendar name to use when none is supplied.

See Also:

Constant Field Values

NON_WORKING

public static final int NON_WORKING

Constant used to represent a non-working day.

See Also:

Constant Field Values

WORKING

public static final int WORKING

Constant used to represent a working day.

See Also:

Constant Field Values

DEFAULT

public static final int DEFAULT

Constant used to represent that a day in a derived calendar used the value specified in the base calendar to indicate if it is working or not.

See Also:

Constant Field Values

DEFAULT_START1

public static final java.util.Date DEFAULT_START1

DEFAULT_END1

public static final java.util.Date DEFAULT_END1

DEFAULT_START2

public static final java.util.Date DEFAULT_START2

DEFAULT_END2

public static final java.util.Date DEFAULT_END2

Constructor Detail

ProjectCalendar

ProjectCalendar(ProjectFile file)

Default constructor.

Parameters:

file - the parent file to which this record belongs.

ProjectCalendar

public ProjectCalendar(ProjectFile file,
                       ProjectCalendar taskCalendar,
                       ProjectCalendar resourceCalendar)

Create a calendar based on the intersection of a task calendar and a resource calendar.

Parameters:

file - the parent file to which this record belongs.

taskCalendar - task calendar to merge

resourceCalendar - resource calendar to merge

Method Detail

addCalendarException

public ProjectCalendarException addCalendarException()

Used to add exceptions to the calendar. The MPX standard defines a limit of 250 exceptions per calendar.

Returns:

ProjectCalendarException instance

getCalendarExceptions

public java.util.List<ProjectCalendarException> getCalendarExceptions()

This method retrieves a list of exceptions to the current calendar.

Returns:

List of calendar exceptions

addCalendarHours

public ProjectCalendarHours addCalendarHours(Day day)

Used to add working hours to the calendar. Note that the MPX file definition allows a maximum of 7 calendar hours records to be added to a single calendar.

Parameters:

day - day number

Returns:

new ProjectCalendarHours instance

addCalendarHours

public ProjectCalendarHours addCalendarHours()

Adds a set of hours to this calendar without assigning them to a particular day.

Returns:

calendar hours instance

attachHoursToDay

public void attachHoursToDay(ProjectCalendarHours hours)

Attaches a pre-existing set of hours to the correct day within the calendar.

Parameters:

hours - calendar hours instance

removeHoursFromDay

public void removeHoursFromDay(ProjectCalendarHours hours)

Removes a set of calendar hours from the day to which they are currently attached.

Parameters:

hours - calendar hours instance

getCalendarHours

public ProjectCalendarHours getCalendarHours(Day day)

This method retrieves the calendar hours for the specified day. Note that this method only returns the hours specification for the current calendar.If this is a derived calendar, it does not refer to the base calendar.

Parameters:

day - Day instance

Returns:

calendar hours

getHours

public ProjectCalendarHours getHours(Day day)

This method retrieves the calendar hours for the specified day. Note that if this is a derived calendar, then this method will refer to the base calendar where no hours are specified in the derived calendar.

Parameters:

day - Day instance

Returns:

calendar hours

getHours

public ProjectCalendarHours[] getHours()

Retrieve an array representing all of the calendar hours defined by this calendar.

Returns:

array of calendar hours

setName

public void setName(java.lang.String name)

Calendar name.

Parameters:

name - calendar name

getName

public java.lang.String getName()

Calendar name.

Returns:

calendar name

setBaseCalendar

public void setBaseCalendar(ProjectCalendar calendar)

Sets the ProjectCalendar instance from which this calendar is derived.

Parameters:

calendar - base calendar instance

getBaseCalendar

public ProjectCalendar getBaseCalendar()

Retrieve the ProjectCalendar instance from which this calendar is derived.

Returns:

ProjectCalendar instance

isWorkingDay

public boolean isWorkingDay(Day day)

Method indicating whether a day is a working or non-working day.

Parameters:

day - required day

Returns:

true if this is a working day

getDays

public int[] getDays()

Retrieve an array representing the days of the week for this calendar.

Returns:

array of days of the week

getWorkingDay

public int getWorkingDay(Day day)

This method allows the retrieval of the actual working day flag, which can take the values DEFAULT, WORKING, or NONWORKING. This differs from the isWorkingDay method as it retrieves the actual flag value. The isWorkingDay method will always refer back to the base calendar to get a boolean value if the underlying flag value is DEFAULT. If isWorkingDay were the only method available to access this flag, it would not be possible to determine that a resource calendar had one or more flags set to DEFAULT.

Parameters:

day - required day

Returns:

value of underlying working day flag

setWorkingDay

public void setWorkingDay(Day day,
                          int working)

This is a convenience method provided to allow a day to be set as working or non-working, by using the day number to identify the required day.

Parameters:

day - required day

working - flag indicating if the day is working/non-working/default

setWorkingDay

public void setWorkingDay(Day day,
                          boolean working)

convenience method for setting working or non-working days.

Parameters:

day - required day

working - flag indicating if the day is a working day

setWorkingDay

public void setWorkingDay(Day day,
                          java.lang.Integer working)

This is a convenience method provided to allow a day to be set as working or non-working, by using the day number to identify the required day.

Parameters:

day - required day

working - flag indicating if the day is a working day

addDefaultCalendarHours

public void addDefaultCalendarHours()

This is a convenience method used to add a default set of calendar hours to a calendar.

addDefaultCalendarHours

public void addDefaultCalendarHours(Day day)

This is a convenience method used to add a default set of calendar hours to a calendar.

Parameters:

day - Day for which to add default hours for

getDuration

public Duration getDuration(java.util.Date startDate,
                            java.util.Date endDate)

This method is provided to allow an absolute period of time represented by start and end dates into a duration in working days based on this calendar instance. This method takes account of any exceptions defined for this calendar.

Parameters:

startDate - start of the period

endDate - end of the period

Returns:

new Duration object

getStartTime

public java.util.Date getStartTime(java.util.Date date)

Retrieves the time at which work starts on the given date, or returns null if this is a non-working day.

Parameters:

date - Date instance

Returns:

start time, or null for non-working day

getFinishTime

public java.util.Date getFinishTime(java.util.Date date)

Retrieves the time at which work finishes on the given date, or returns null if this is a non-working day.

Parameters:

date - Date instance

Returns:

finish time, or null for non-working day

getDate

public java.util.Date getDate(java.util.Date startDate,
                              Duration duration,
                              boolean returnNextWorkStart)

Given a start date and a duration, this method calculates the end date. It takes account of working hours in each day, non working days and calendar exceptions. If the returnNextWorkStart parameter is set to true, the method will return the start date and time of the next working period if the end date is at the end of a working period.

Parameters:

startDate - start date

duration - duration

returnNextWorkStart - if set to true will return start of next working period

Returns:

end date

getStartDate

public java.util.Date getStartDate(java.util.Date finishDate,
                                   Duration duration)

Given a finish date and a duration, this method calculates backwards to the start date. It takes account of working hours in each day, non working days and calendar exceptions.

Parameters:

finishDate - finish date

duration - duration

Returns:

start date

getNextWorkStart

public java.util.Date getNextWorkStart(java.util.Date date)

Utility method to retrieve the next working date time, given a date and time as a starting point.

Parameters:

date - date and time start point

Returns:

date and time of next work start

isWorkingDate

public boolean isWorkingDate(java.util.Date date)

This method allows the caller to determine if a given date is a working day. This method takes account of calendar exceptions.

Parameters:

date - Date to be tested

Returns:

boolean value

isBaseCalendar

public boolean isBaseCalendar()

This method returns a flag indicating if this ProjectCalendar instance represents a base calendar.

Returns:

boolean flag

setUniqueID

public void setUniqueID(java.lang.Integer uniqueID)

Modifier method to set the unique ID of this calendar.

Parameters:

uniqueID - unique identifier

getUniqueID

public java.lang.Integer getUniqueID()

Accessor method to retrieve the unique ID of this calendar.

Returns:

calendar unique identifier

getResource

public Resource getResource()

Retrieve the resource to which this calendar is linked.

Returns:

resource instance

setResource

public void setResource(Resource resource)

Sets the resource to which this calendar is linked. Note that this method updates the calendar's name to be the same as the resource name. If the resource does not yet have a name, then the calendar is given a default name.

Parameters:

resource - resource instance

remove

public void remove()

Removes this calendar from the project.

getException

public ProjectCalendarException getException(java.util.Date date)

Retrieve a calendar calendar exception which applies to this date.

Parameters:

date - target date

Returns:

calendar exception, or null if none match this date

getWork

public Duration getWork(java.util.Date date,
                        TimeUnit format)

Retrieves the amount of work on a given day, and returns it in the specified format.

Parameters:

date - target date

format - required format

Returns:

work duration

getWork

public Duration getWork(java.util.Date startDate,
                        java.util.Date endDate,
                        TimeUnit format)

This method retrieves a Duration instance representing the amount of work between two dates based on this calendar.

Parameters:

startDate - start date

endDate - end date

format - required duration format

Returns:

amount of work

addDerivedCalendar

protected void addDerivedCalendar(ProjectCalendar calendar)

Add a reference to a calendar derived from this one.

Parameters:

calendar - derived calendar instance

removeDerivedCalendar

protected void removeDerivedCalendar(ProjectCalendar calendar)

Remove a reference to a derived calendar.

Parameters:

calendar - derived calendar instance

getDerivedCalendars

public java.util.List<ProjectCalendar> getDerivedCalendars()

Retrieve a list of derived calendars.

Returns:

list of derived calendars

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object