org.sakaiproject.service.legacy.calendar
Interface Calendar

All Superinterfaces:
Entity
All Known Subinterfaces:
CalendarEdit
All Known Implementing Classes:
BaseCalendarService.BaseCalendarEdit

public interface Calendar
extends Entity

Calendar is the base interface for CHEF Calendar service calendars.

Calendars contains collections of CalendarEvents.

Version:
$Revision: 2371 $
Author:
University of Michigan, CHEF Software Development Team

Field Summary
 
Fields inherited from interface org.sakaiproject.service.legacy.entity.Entity
SEPARATOR
 
Method Summary
 CalendarEventEdit addEvent()
          Add a new event to this calendar.
 CalendarEvent addEvent(TimeRange range, String displayName, String description, String type, String location, List attachments)
          Add a new event to this calendar.
 boolean allowAddEvent()
          check permissions for addEvent().
 boolean allowEditEvent(String eventId)
          check permissions for editEvent()
 boolean allowGetEvents()
          check permissions for getEvents() and getEvent().
 boolean allowRemoveEvent(CalendarEvent event)
          check permissions for removeEvent().
 void cancelEvent(CalendarEventEdit edit)
          Cancel the changes made to a CalendarEventEdit object, and release the lock.
 void commitEvent(CalendarEventEdit edit)
          Commit the changes made to a CalendarEventEdit object, and release the lock.
 void commitEvent(CalendarEventEdit edit, int intention)
          Commit the changes made to a CalendarEventEdit object, and release the lock.
 CalendarEventEdit editEvent(String eventId)
          Return a specific calendar event, as specified by event name, locked for update.
 String getContext()
          Access the context of the resource.
 CalendarEvent getEvent(String eventId)
          Return a specific calendar event, as specified by event name.
 String getEventFields()
          Return the extra fields kept for each event in this calendar.
 List getEvents(TimeRange range, Filter filter)
          Return a List of all or filtered events in the calendar.
 CalendarEventEdit mergeEvent(Element el)
          Merge in a new event as defined in the xml.
 void removeEvent(CalendarEventEdit edit)
          Remove an event from the calendar, one locked for edit.
 void removeEvent(CalendarEventEdit edit, int intention)
          Remove an event from the calendar, one locked for edit.
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.Entity
getId, getProperties, getReference, getReference, getUrl, getUrl, toXml
 

Method Detail

getContext

public String getContext()
Access the context of the resource.

Returns:
The context.

allowGetEvents

public boolean allowGetEvents()
check permissions for getEvents() and getEvent().

Returns:
true if the user is allowed to get events from the calendar, false if not.

getEvents

public List getEvents(TimeRange range,
                      Filter filter)
               throws PermissionException
Return a List of all or filtered events in the calendar. The order in which the events will be found in the iteration is by event start date.

Parameters:
range - A time range to limit the iterated events. May be null; all events will be returned.
filter - A filtering object to accept events into the iterator, or null if no filtering is desired.
Returns:
a List of all or filtered CalendarEvents in the calendar (may be empty).
Throws:
PermissionException - if the user does not have read permission to the calendar.

getEvent

public CalendarEvent getEvent(String eventId)
                       throws IdUnusedException,
                              PermissionException
Return a specific calendar event, as specified by event name.

Parameters:
eventId - The id of the event to get.
Returns:
the CalendarEvent that has the specified id.
Throws:
IdUnusedException - If this id is not a defined event in this calendar.
PermissionException - If the user does not have any permissions to read the calendar.

getEventFields

public String getEventFields()
Return the extra fields kept for each event in this calendar.

Returns:
the extra fields kept for each event in this calendar, formatted into a single string. %%%

allowAddEvent

public boolean allowAddEvent()
check permissions for addEvent().

Returns:
true if the user is allowed to addEvent(...), false if not.

addEvent

public CalendarEvent addEvent(TimeRange range,
                              String displayName,
                              String description,
                              String type,
                              String location,
                              List attachments)
                       throws PermissionException
Add a new event to this calendar.

Parameters:
range - The event's time range.
displayName - The event's display name (PROP_DISPLAY_NAME) property value.
description - The event's description (PROP_DESCRIPTION) property value.
type - The event's calendar event type (PROP_CALENDAR_TYPE) property value.
location - The event's calendar event location (PROP_CALENDAR_LOCATION) property value.
attachments - The event attachments, a vector of Reference objects.
Returns:
The newly added event.
Throws:
PermissionException - If the user does not have permission to modify the calendar.

addEvent

public CalendarEventEdit addEvent()
                           throws PermissionException
Add a new event to this calendar. Must commitEvent() to make official, or cancelEvent() when done!

Returns:
The newly added event, locked for update.
Throws:
PermissionException - If the user does not have write permission to the calendar.

allowEditEvent

public boolean allowEditEvent(String eventId)
check permissions for editEvent()

Returns:
true if the user is allowed to update the event, false if not.

editEvent

public CalendarEventEdit editEvent(String eventId)
                            throws IdUnusedException,
                                   PermissionException,
                                   InUseException
Return a specific calendar event, as specified by event name, locked for update. Must commitEvent() to make official, or cancelEvent(), or removeEvent() when done!

Parameters:
eventId - The id of the event to get.
Returns:
the Event that has the specified id.
Throws:
IdUnusedException - If this name is not a defined event in this calendar.
PermissionException - If the user does not have any permissions to edit the event.
InUseException - if the event is locked for edit by someone else.

commitEvent

public void commitEvent(CalendarEventEdit edit,
                        int intention)
Commit the changes made to a CalendarEventEdit object, and release the lock. The CalendarEventEdit is disabled, and not to be used after this call.

Parameters:
edit - The CalendarEventEdit object to commit.
intention - The recurring event modification intention, based on values in the GenericCalendarService "MOD_*", used if the event is part of a recurring event sequence to determine how much of the sequence is changed by this commmit.

commitEvent

public void commitEvent(CalendarEventEdit edit)
Commit the changes made to a CalendarEventEdit object, and release the lock. The CalendarEventEdit is disabled, and not to be used after this call. Note: if the event is a recurring event, the entire sequence is modified by this commit (MOD_ALL).

Parameters:
edit - The CalendarEventEdit object to commit.

cancelEvent

public void cancelEvent(CalendarEventEdit edit)
Cancel the changes made to a CalendarEventEdit object, and release the lock. The CalendarEventEdit is disabled, and not to be used after this call.

Parameters:
edit - The CalendarEventEdit object to commit.

mergeEvent

public CalendarEventEdit mergeEvent(Element el)
                             throws PermissionException,
                                    IdUsedException
Merge in a new event as defined in the xml.

Parameters:
el - The event information in XML in a DOM element.
Throws:
PermissionException - If the user does not have write permission to the calendar.
IdUsedException - if the user id is already used.

allowRemoveEvent

public boolean allowRemoveEvent(CalendarEvent event)
check permissions for removeEvent().

Parameters:
event - The event from this calendar to remove.
Returns:
true if the user is allowed to removeEvent(event), false if not.

removeEvent

public void removeEvent(CalendarEventEdit edit,
                        int intention)
Remove an event from the calendar, one locked for edit.

Parameters:
edit - The event from this calendar to remove.
intention - The recurring event modification intention, based on values in the GenericCalendarService "MOD_*", used if the event is part of a recurring event sequence to determine how much of the sequence is removed.

removeEvent

public void removeEvent(CalendarEventEdit edit)
Remove an event from the calendar, one locked for edit. Note: if the event is a recurring event, the entire sequence is removed by this commit (MOD_ALL).

Parameters:
edit - The event from this calendar to remove.