001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/calendar/tags/sakai_2-4-1/calendar-api/api/src/java/org/sakaiproject/calendar/api/Calendar.java $
003: * $Id: Calendar.java 15708 2006-10-05 19:18:37Z bkirschn@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.calendar.api;
021:
022: import java.util.Collection;
023: import java.util.List;
024:
025: import org.sakaiproject.calendar.api.CalendarEvent.EventAccess;
026: import org.sakaiproject.entity.api.Entity;
027: import org.sakaiproject.exception.IdUnusedException;
028: import org.sakaiproject.exception.IdUsedException;
029: import org.sakaiproject.exception.InUseException;
030: import org.sakaiproject.exception.PermissionException;
031: import org.sakaiproject.javax.Filter;
032: import org.sakaiproject.time.api.TimeRange;
033: import org.w3c.dom.Element;
034:
035: /**
036: * <p>Calendar is the base interface for Calendar service calendars.</p>
037: * <p>Calendars contains collections of CalendarEvents.</p>
038: */
039: public interface Calendar extends Entity {
040: /**
041: * Access the context of the resource.
042: * @return The context.
043: */
044: public String getContext();
045:
046: /**
047: * check permissions for getEvents() and getEvent() on a SITE / calendar level.
048: * @return true if the user is allowed to get events from the calendar, false if not.
049: */
050: public boolean allowGetEvents();
051:
052: /**
053: * check permissions for getEvent() for a particular event.
054: * @return true if the user is allowed to get the event from the calendar, false if not.
055: */
056: public boolean allowGetEvent(String eventId);
057:
058: /**
059: * Return a List of all or filtered events in the calendar.
060: * The order in which the events will be found in the iteration is by event start date.
061: * @param range A time range to limit the iterated events. May be null; all events will be returned.
062: * @param filter A filtering object to accept events into the iterator, or null if no filtering is desired.
063: * @return a List of all or filtered CalendarEvents in the calendar (may be empty).
064: * @exception PermissionException if the user does not have read permission to the calendar.
065: */
066: public List getEvents(TimeRange range, Filter filter)
067: throws PermissionException;
068:
069: /**
070: * Return a specific calendar event, as specified by event name.
071: * @param eventId The id of the event to get.
072: * @return the CalendarEvent that has the specified id.
073: * @exception IdUnusedException If this id is not a defined event in this calendar.
074: * @exception PermissionException If the user does not have any permissions to read the calendar.
075: */
076: public CalendarEvent getEvent(String eventId)
077: throws IdUnusedException, PermissionException;
078:
079: /**
080: * Return the extra fields kept for each event in this calendar.
081: * @return the extra fields kept for each event in this calendar, formatted into a single string. %%%
082: */
083: public String getEventFields();
084:
085: /**
086: * check permissions for addEvent().
087: * @return true if the user is allowed to addEvent(...), false if not.
088: */
089: public boolean allowAddEvent();
090:
091: /**
092: * Check if the user has permission to add a calendar-wide (not grouped) message.
093: *
094: * @return true if the user has permission to add a calendar-wide (not grouped) message.
095: */
096: boolean allowAddCalendarEvent();
097:
098: /**
099: * Add a new event to this calendar.
100: * @param range The event's time range.
101: * @param displayName The event's display name (PROP_DISPLAY_NAME) property value.
102: * @param description The event's description (PROP_DESCRIPTION) property value.
103: * @param type The event's calendar event type (PROP_CALENDAR_TYPE) property value.
104: * @param location The event's calendar event location (PROP_CALENDAR_LOCATION) property value.
105: * @param access The event's access type site or grouped
106: * @param groups The groups which can access this event
107: * @param attachments The event attachments, a vector of Reference objects.
108: * @return The newly added event.
109: * @exception PermissionException If the user does not have permission to modify the calendar.
110: */
111: public CalendarEvent addEvent(TimeRange range, String displayName,
112: String description, String type, String location,
113: EventAccess access, Collection groups, List attachments)
114: throws PermissionException;
115:
116: /**
117: * Add a new event to this calendar.
118: * @param range The event's time range.
119: * @param displayName The event's display name (PROP_DISPLAY_NAME) property value.
120: * @param description The event's description (PROP_DESCRIPTION) property value.
121: * @param type The event's calendar event type (PROP_CALENDAR_TYPE) property value.
122: * @param location The event's calendar event location (PROP_CALENDAR_LOCATION) property value.
123: * @param attachments The event attachments, a vector of Reference objects.
124: * @return The newly added event.
125: * @exception PermissionException If the user does not have permission to modify the calendar.
126: */
127: public CalendarEvent addEvent(TimeRange range, String displayName,
128: String description, String type, String location,
129: List attachments) throws PermissionException;
130:
131: /**
132: * Add a new event to this calendar.
133: * Must commitEvent() to make official, or cancelEvent() when done!
134: * @return The newly added event, locked for update.
135: * @exception PermissionException If the user does not have write permission to the calendar.
136: */
137: public CalendarEventEdit addEvent() throws PermissionException;
138:
139: /**
140: * check permissions for editEvent()
141: * @param id The event id.
142: * @return true if the user is allowed to update the event, false if not.
143: */
144: public boolean allowEditEvent(String eventId);
145:
146: /**
147: * Return a specific calendar event, as specified by event name, locked for update.
148: * Must commitEvent() to make official, or cancelEvent(), or removeEvent() when done!
149: * @param eventId The id of the event to get.
150: * @param editType add, remove or modifying calendar?
151: * @return the Event that has the specified id.
152: * @exception IdUnusedException If this name is not a defined event in this calendar.
153: * @exception PermissionException If the user does not have any permissions to edit the event.
154: * @exception InUseException if the event is locked for edit by someone else.
155: */
156: public CalendarEventEdit getEditEvent(String eventId,
157: String editType) throws IdUnusedException,
158: PermissionException, InUseException;
159:
160: /**
161: * Commit the changes made to a CalendarEventEdit object, and release the lock.
162: * The CalendarEventEdit is disabled, and not to be used after this call.
163: * @param edit The CalendarEventEdit object to commit.
164: * @param intention The recurring event modification intention,
165: * based on values in the GenericCalendarService "MOD_*",
166: * used if the event is part of a recurring event sequence to determine how much of the sequence is changed by this commmit.
167: */
168: public void commitEvent(CalendarEventEdit edit, int intention);
169:
170: /**
171: * Commit the changes made to a CalendarEventEdit object, and release the lock.
172: * The CalendarEventEdit is disabled, and not to be used after this call.
173: * Note: if the event is a recurring event, the entire sequence is modified by this commit (MOD_ALL).
174: * @param edit The CalendarEventEdit object to commit.
175: */
176: public void commitEvent(CalendarEventEdit edit);
177:
178: /**
179: * Cancel the changes made to a CalendarEventEdit object, and release the lock.
180: * The CalendarEventEdit is disabled, and not to be used after this call.
181: * @param edit The CalendarEventEdit object to commit.
182: */
183: public void cancelEvent(CalendarEventEdit edit);
184:
185: /**
186: * Merge in a new event as defined in the xml.
187: * @param el The event information in XML in a DOM element.
188: * @exception PermissionException If the user does not have write permission to the calendar.
189: * @exception IdUsedException if the user id is already used.
190: */
191: public CalendarEventEdit mergeEvent(Element el)
192: throws PermissionException, IdUsedException;
193:
194: /**
195: * check permissions for removeEvent().
196: * @param event The event from this calendar to remove.
197: * @return true if the user is allowed to removeEvent(event), false if not.
198: */
199: public boolean allowRemoveEvent(CalendarEvent event);
200:
201: /**
202: * Remove an event from the calendar, one locked for edit.
203: * @param edit The event from this calendar to remove.
204: * @param intention The recurring event modification intention,
205: * based on values in the GenericCalendarService "MOD_*",
206: * used if the event is part of a recurring event sequence to determine how much of the sequence is removed.
207: * @throws PermissionException if the end user does not have permission to remove.
208: */
209: public void removeEvent(CalendarEventEdit edit, int intention)
210: throws PermissionException;
211:
212: /**
213: * Remove an event from the calendar, one locked for edit.
214: * Note: if the event is a recurring event, the entire sequence is removed by this commit (MOD_ALL).
215: * @param edit The event from this calendar to remove.
216: * @throws PermissionException if the end user does not have permission to remove.
217: */
218: public void removeEvent(CalendarEventEdit edit)
219: throws PermissionException;
220:
221: /**
222: * Get the collection of Groups defined for the context of this calendar that the end user has add event permissions in.
223: *
224: * @return The Collection (Group) of groups defined for the context of this calendar that the end user has add event permissions in, empty if none.
225: */
226: Collection getGroupsAllowAddEvent();
227:
228: /**
229: * Get the collection of Group defined for the context of this calendar that the end user has get event permissions in.
230: *
231: * @return The Collection (Group) of groups defined for the context of this calendar that the end user has get event permissions in, empty if none.
232: */
233: Collection getGroupsAllowGetEvent();
234:
235: /**
236: * Get the collection of Group defined for the context of this channel that the end user has remove event permissions in.
237: *
238: * @param own boolean flag indicating whether user owns event
239: *
240: * @return The Collection (Group) of groups defined for the context of this channel that the end user has remove event permissions in, empty if none.
241: */
242: Collection getGroupsAllowRemoveEvent(boolean own);
243:
244: } // Calendar
|