org.yawlfoundation.yawl.resourcing.calendar

Class ResourceCalendar

java.lang.Object

org.yawlfoundation.yawl.resourcing.calendar.ResourceCalendar

public class ResourceCalendar
extends java.lang.Object

Maintains the resource calendar. An entry in the calendar denotes that a resource is NOT available between the entry's start and end times. An entry may refer to an individual resource (by id), or all human resources (eg. a public holiday), or all non-human resources (eg. an equipment maintenance run) or all resources (both human and non-human). Author: Michael Adams Creation Date: 12/03/2010

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ResourceCalendar.ResourceGroup
static class	ResourceCalendar.Status

Method Summary

Modifier and Type	Method and Description
long	addEntry(AbstractResource resource, long startTime, long endTime, ResourceCalendar.Status status, int workload, java.lang.String agent, java.lang.String comment) Adds an entry to the Calendar table.
long	addEntry(CalendarEntry entry) Adds an entry to the Calendar table.
long	addEntry(ResourceCalendar.ResourceGroup entry, long startTime, long endTime, ResourceCalendar.Status status, java.lang.String agent, java.lang.String comment) Adds an entry to the Calendar table.
long	addTransientEntry(CalendarEntry entry)
long	addTransientEntry(java.lang.String id, long startTime, long endTime, ResourceCalendar.Status status, int workload, java.lang.String agent)
org.hibernate.Transaction	beginTransaction()
void	cancel(long entryID)
boolean	canConfirm(long entryID)
boolean	canCreateEntry(AbstractResource resource, long startTime, long endTime, ResourceCalendar.Status status, int workload)
boolean	canCreateEntry(AbstractResource resource, long startTime, long endTime, java.lang.String status, int workload)
boolean	canUnconfirm(long entryID)
boolean	canUpdateEntry(long entryID, ResourceCalendar.Status status)
boolean	canUpdateEntry(long entryID, java.lang.String status)
int	clean(long priorTo) Removes all entries from the Calendar table prior to the timestamp passed.
void	commitTransaction()
void	confirm(long entryID)
long	createEntry(AbstractResource resource, CalendarEntry entry)
long	createEntry(AbstractResource resource, long startTime, long endTime, ResourceCalendar.Status status, java.lang.String comment, java.lang.String agent)
long	createEntry(AbstractResource resource, long startTime, long endTime, java.lang.String status, java.lang.String comment, java.lang.String agent)
java.util.Set<java.lang.String>	freeResourcesForCase(java.lang.String caseID)
java.util.List<TimeSlot>	getAvailability(AbstractResource resource, long startTime, long endTime)
java.util.List	getEntries(AbstractResource resource) Gets the current list of calendar entries for a resource
java.util.List	getEntries(AbstractResource resource, long from, long to)
java.util.List	getEntries(AbstractResource resource, long from, long to, boolean immediateCommit)
java.util.List	getEntries(long from, long to)
java.util.List	getEntries(ResourceCalendar.ResourceGroup entry) Gets the current list of calendar entries for a Resource Entry type
java.util.List	getEntries(ResourceCalendar.ResourceGroup group, long from, long to)
java.util.List	getEntries(ResourceCalendar.ResourceGroup group, long from, long to, boolean immediateCommit)
java.util.List	getEntries(java.lang.String id, long from, long to)
java.util.List	getEntries(java.lang.String id, long from, long to, boolean immediateCommit)
CalendarEntry	getEntry(long entryID) Gets the calendar entry associated with the entry identifier passed
java.lang.String	getEntryString(ResourceCalendar.ResourceGroup entry) Returns a string corresponding to the entry type
static ResourceCalendar	getInstance()
java.util.List	getTimeSlotEntries(AbstractResource resource) Gets the list of calendar entries for a resource.
java.util.List	getTimeSlotEntries(AbstractResource resource, long from, long to) Gets the list of calendar entries within a specified period for a resource.
java.util.List	getTimeSlotEntries(java.lang.String resourceID, boolean isParticipant, long from, long to)
boolean	hasStatus(long entryID, java.lang.String status)
boolean	isAvailable(AbstractResource resource) Checks if the resource is currently available.
boolean	isAvailable(AbstractResource resource, CalendarEntry entry) Checks if the resource is available within the specified period.
boolean	isAvailable(AbstractResource resource, long from, long to, int workload)
boolean	isAvailable(java.util.Set<java.lang.Long> idsToIgnore, AbstractResource resource, long from, long to) Checks if the resource is available within the specified period.
boolean	isAvailable(java.util.Set<java.lang.Long> idsToIgnore, AbstractResource resource, long from, long to, int workload) Checks if the resource is available within the specified period.
java.util.List<TimeSlot>	makeAvailable(AbstractResource resource, long startTime, long endTime)
void	makeAvailable(long entryID)
long	makeUnavailable(AbstractResource resource, CalendarEntry calEntry)
long	makeUnavailable(AbstractResource resource, long startTime, long endTime, java.lang.String agent, java.lang.String comment)
CalendarEntry	reconcileEntry(AbstractResource resource, long entryID, long startTime, long endTime)
void	removeTransientEntries(java.util.Map<java.lang.Long,java.lang.String> transientMap)
long	request(AbstractResource resource, CalendarEntry calEntry)
long	request(AbstractResource resource, long startTime, long endTime, java.lang.String agent, java.lang.String comment)
long	reserve(AbstractResource resource, CalendarEntry calEntry)
long	reserve(AbstractResource resource, long startTime, long endTime, java.lang.String agent, java.lang.String comment)
void	rollBackTransaction()
ResourceCalendar.Status	strToStatus(java.lang.String name)
void	unconfirm(long entryID)
void	unrequest(long entryID)
void	updateEntry(CalendarEntry entry) Updates and saves an existing calendar entry
ResourceCalendar.Status	updateEntry(long entryID, ResourceCalendar.Status status)
ResourceCalendar.Status	updateEntry(long entryID, java.lang.String status)
java.lang.String	updateTransientEntry(long entryID, java.lang.String newStatus)

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static ResourceCalendar getInstance()

beginTransaction

public org.hibernate.Transaction beginTransaction()

commitTransaction

public void commitTransaction()

rollBackTransaction

public void rollBackTransaction()

addEntry

public long addEntry(AbstractResource resource,
                     long startTime,
                     long endTime,
                     ResourceCalendar.Status status,
                     int workload,
                     java.lang.String agent,
                     java.lang.String comment)
              throws CalendarException

Adds an entry to the Calendar table.

Parameters:

resource - the resource to add the entry for

startTime - the date/time when the resource's unavailability starts

endTime - the date/time when the resource's unavailability ends

status - the resource's schedule status

workload - the percentage workload (1-100)

agent - the id of the user or service that is adding the entry

comment - an optional comment string

Returns:

the identifier of the added entry

Throws:

CalendarException - if invalid parameters are passed, or the addition otherwise fails

addEntry

public long addEntry(ResourceCalendar.ResourceGroup entry,
                     long startTime,
                     long endTime,
                     ResourceCalendar.Status status,
                     java.lang.String agent,
                     java.lang.String comment)
              throws CalendarException

Adds an entry to the Calendar table.

Parameters:

entry - an Entry value (for multiple resources)

startTime - the date/time when the resource's unavailability starts

endTime - the date/time when the resource's unavailability ends

status - the resource's schedule status

agent - the id of the user or service that is adding the entry

comment - an optional comment string

Returns:

the identifier of the added entry

Throws:

CalendarException - if invalid parameters are passed, or the addition otherwise fails

getEntry

public CalendarEntry getEntry(long entryID)

Gets the calendar entry associated with the entry identifier passed

Parameters:

entryID - the entry identifier

Returns:

the matching calendar entry, or null if the entry can't be found

getEntries

public java.util.List getEntries(AbstractResource resource)

Gets the current list of calendar entries for a resource

Parameters:

resource - the resource to get the entries for

Returns:

the list of all entries corresponding to the resource

getEntries

public java.util.List getEntries(ResourceCalendar.ResourceGroup entry)

Gets the current list of calendar entries for a Resource Entry type

Parameters:

entry - the Entry type

Returns:

the list of entries corresponding to the Entry type

clean

public int clean(long priorTo)

Removes all entries from the Calendar table prior to the timestamp passed.

Parameters:

priorTo - timestamp that marks when to delete entries up to. Note: priorTo must be a timestamp prior to the current time.

Returns:

the number of entries deleted

isAvailable

public boolean isAvailable(java.util.Set<java.lang.Long> idsToIgnore,
                           AbstractResource resource,
                           long from,
                           long to)

Checks if the resource is available within the specified period. Will return true if there is not an entry in the calendar table for the resource that covers the period within its duration

Parameters:

idsToIgnore - the primary key(s) of entries to exclude from the check. An empty Set (or null) means exclude none, otherwise the corresponding entry is excluded (used when updating an entry)

resource - the resource to check availability for

from - the start of a time range to search for

to - the end of a time range to search for

Returns:

true if available, false if not

isAvailable

public boolean isAvailable(AbstractResource resource)

Checks if the resource is currently available. Will return true if there is not an entry in the calendar table for the resource that covers the current time within its duration

Parameters:

resource - the resource to check availability for

Returns:

true if available, false if not

isAvailable

public boolean isAvailable(java.util.Set<java.lang.Long> idsToIgnore,
                           AbstractResource resource,
                           long from,
                           long to,
                           int workload)

Checks if the resource is available within the specified period. Will return true if the workload total of all the entries in the calendar table for the resource that covers the period within its duration, plus the workload passed, doesn't exceed 100%

Parameters:

idsToIgnore - the primary key(s) of entries to exclude from the check. An empty Set (or null) means exclude none, otherwise the corresponding entry is excluded (used when updating an entry)

resource - the resource to check availability for

from - the start of a time range to search for

to - the end of a time range to search for

workload - the percentage workload to check for (0-100)

Returns:

true if available, false if not

isAvailable

public boolean isAvailable(AbstractResource resource,
                           long from,
                           long to,
                           int workload)

isAvailable

public boolean isAvailable(AbstractResource resource,
                           CalendarEntry entry)

Checks if the resource is available within the specified period. Will return true if the workload total of all the entries in the calendar table for the resource that covers the period within its duration, plus the workload passed, doesn't exceed 100%

Parameters:

resource - the resource to check availability for

entry - a CalendarEntry object containing the required parameters

Returns:

true if available, false if not

getTimeSlotEntries

public java.util.List getTimeSlotEntries(AbstractResource resource,
                                         long from,
                                         long to)

Gets the list of calendar entries within a specified period for a resource. Covers 4 overlapping possibilities : 1. A record's time range is wholly within start <-> end 2. start <-> end is wholly within a record's time range 3. start is prior to the record's time range, and end falls within it 4. end is after the record's time range, and start falls within it

Parameters:

resource - the resource to get the entries for

from - the start of a time range to search for (-ve value for all start times)

to - the end of a time range to search for (-ve value for all end times)

Returns:

the matching list of calendar entries (as CalendarEntry objects)

getTimeSlotEntries

public java.util.List getTimeSlotEntries(java.lang.String resourceID,
                                         boolean isParticipant,
                                         long from,
                                         long to)

getTimeSlotEntries

public java.util.List getTimeSlotEntries(AbstractResource resource)

Gets the list of calendar entries for a resource.

Parameters:

resource - the resource to get the entries for

Returns:

the matching list of calendar entries (as CalendarEntry objects)

getEntries

public java.util.List getEntries(long from,
                                 long to)

getAvailability

public java.util.List<TimeSlot> getAvailability(AbstractResource resource,
                                                long startTime,
                                                long endTime)

createEntry

public long createEntry(AbstractResource resource,
                        long startTime,
                        long endTime,
                        java.lang.String status,
                        java.lang.String comment,
                        java.lang.String agent)
                 throws CalendarException,
                        ScheduleStateException

Throws:

CalendarException

ScheduleStateException

createEntry

public long createEntry(AbstractResource resource,
                        long startTime,
                        long endTime,
                        ResourceCalendar.Status status,
                        java.lang.String comment,
                        java.lang.String agent)
                 throws CalendarException,
                        ScheduleStateException

Throws:

CalendarException

ScheduleStateException

createEntry

public long createEntry(AbstractResource resource,
                        CalendarEntry entry)
                 throws CalendarException,
                        ScheduleStateException

Throws:

CalendarException

ScheduleStateException

canCreateEntry

public boolean canCreateEntry(AbstractResource resource,
                              long startTime,
                              long endTime,
                              java.lang.String status,
                              int workload)
                       throws CalendarException

Throws:

CalendarException

canCreateEntry

public boolean canCreateEntry(AbstractResource resource,
                              long startTime,
                              long endTime,
                              ResourceCalendar.Status status,
                              int workload)

updateEntry

public ResourceCalendar.Status updateEntry(long entryID,
                                           java.lang.String status)
                                    throws CalendarException,
                                           ScheduleStateException

Throws:

CalendarException

ScheduleStateException

updateEntry

public ResourceCalendar.Status updateEntry(long entryID,
                                           ResourceCalendar.Status status)
                                    throws CalendarException,
                                           ScheduleStateException

Throws:

CalendarException

ScheduleStateException

canUpdateEntry

public boolean canUpdateEntry(long entryID,
                              java.lang.String status)
                       throws CalendarException,
                              ScheduleStateException

Throws:

CalendarException

ScheduleStateException

canUpdateEntry

public boolean canUpdateEntry(long entryID,
                              ResourceCalendar.Status status)
                       throws CalendarException,
                              ScheduleStateException

Throws:

CalendarException

ScheduleStateException

reconcileEntry

public CalendarEntry reconcileEntry(AbstractResource resource,
                                    long entryID,
                                    long startTime,
                                    long endTime)
                             throws CalendarException

Throws:

CalendarException

makeAvailable

public java.util.List<TimeSlot> makeAvailable(AbstractResource resource,
                                              long startTime,
                                              long endTime)
                                       throws ScheduleStateException

Throws:

ScheduleStateException

makeAvailable

public void makeAvailable(long entryID)
                   throws CalendarException

Throws:

CalendarException

makeUnavailable

public long makeUnavailable(AbstractResource resource,
                            long startTime,
                            long endTime,
                            java.lang.String agent,
                            java.lang.String comment)
                     throws ScheduleStateException,
                            CalendarException

Throws:

ScheduleStateException

CalendarException

makeUnavailable

public long makeUnavailable(AbstractResource resource,
                            CalendarEntry calEntry)
                     throws ScheduleStateException,
                            CalendarException

Throws:

ScheduleStateException

CalendarException

reserve

public long reserve(AbstractResource resource,
                    long startTime,
                    long endTime,
                    java.lang.String agent,
                    java.lang.String comment)
             throws ScheduleStateException,
                    CalendarException

Throws:

ScheduleStateException

CalendarException

reserve

public long reserve(AbstractResource resource,
                    CalendarEntry calEntry)
             throws ScheduleStateException,
                    CalendarException

Throws:

ScheduleStateException

CalendarException

cancel

public void cancel(long entryID)
            throws ScheduleStateException,
                   CalendarException

Throws:

ScheduleStateException

CalendarException

request

public long request(AbstractResource resource,
                    long startTime,
                    long endTime,
                    java.lang.String agent,
                    java.lang.String comment)
             throws ScheduleStateException,
                    CalendarException

Throws:

ScheduleStateException

CalendarException

request

public long request(AbstractResource resource,
                    CalendarEntry calEntry)
             throws ScheduleStateException,
                    CalendarException

Throws:

ScheduleStateException

CalendarException

unrequest

public void unrequest(long entryID)
               throws ScheduleStateException,
                      CalendarException

Throws:

ScheduleStateException

CalendarException

confirm

public void confirm(long entryID)
             throws ScheduleStateException,
                    CalendarException

Throws:

ScheduleStateException

CalendarException

unconfirm

public void unconfirm(long entryID)
               throws ScheduleStateException,
                      CalendarException

Throws:

ScheduleStateException

CalendarException

canConfirm

public boolean canConfirm(long entryID)
                   throws CalendarException

Throws:

CalendarException

canUnconfirm

public boolean canUnconfirm(long entryID)
                     throws ScheduleStateException,
                            CalendarException

Throws:

ScheduleStateException

CalendarException

strToStatus

public ResourceCalendar.Status strToStatus(java.lang.String name)
                                    throws CalendarException

Throws:

CalendarException

addTransientEntry

public long addTransientEntry(CalendarEntry entry)
                       throws CalendarException

Throws:

CalendarException

addTransientEntry

public long addTransientEntry(java.lang.String id,
                              long startTime,
                              long endTime,
                              ResourceCalendar.Status status,
                              int workload,
                              java.lang.String agent)
                       throws CalendarException

Throws:

CalendarException

updateTransientEntry

public java.lang.String updateTransientEntry(long entryID,
                                             java.lang.String newStatus)
                                      throws CalendarException

Throws:

CalendarException

removeTransientEntries

public void removeTransientEntries(java.util.Map<java.lang.Long,java.lang.String> transientMap)

freeResourcesForCase

public java.util.Set<java.lang.String> freeResourcesForCase(java.lang.String caseID)
                                                     throws CalendarException

Throws:

CalendarException

addEntry

public long addEntry(CalendarEntry entry)
              throws CalendarException

Adds an entry to the Calendar table.

Parameters:

entry - the CalendarEntry to add

Returns:

the identifier of the added entry

Throws:

CalendarException - if invalid parameters are passed, or the addition otherwise fails

getEntries

public java.util.List getEntries(java.lang.String id,
                                 long from,
                                 long to,
                                 boolean immediateCommit)

getEntries

public java.util.List getEntries(java.lang.String id,
                                 long from,
                                 long to)

getEntries

public java.util.List getEntries(ResourceCalendar.ResourceGroup group,
                                 long from,
                                 long to,
                                 boolean immediateCommit)

getEntries

public java.util.List getEntries(ResourceCalendar.ResourceGroup group,
                                 long from,
                                 long to)

getEntries

public java.util.List getEntries(AbstractResource resource,
                                 long from,
                                 long to,
                                 boolean immediateCommit)

getEntries

public java.util.List getEntries(AbstractResource resource,
                                 long from,
                                 long to)

updateEntry

public void updateEntry(CalendarEntry entry)

Updates and saves an existing calendar entry

Parameters:

entry - the entry to update

getEntryString

public java.lang.String getEntryString(ResourceCalendar.ResourceGroup entry)

Returns a string corresponding to the entry type

Parameters:

entry - the entry type

Returns:

its matching string

Precondition:

entry is a valid Entry type

hasStatus

public boolean hasStatus(long entryID,
                         java.lang.String status)
                  throws CalendarException

Throws:

CalendarException