001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/calendar/tags/sakai_2-4-1/calendar-api/api/src/java/org/sakaiproject/calendar/api/CalendarService.java $
003: * $Id: CalendarService.java 14459 2006-09-12 18:37:51Z 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.List;
023:
024: import org.sakaiproject.entity.api.Entity;
025: import org.sakaiproject.entity.api.EntityProducer;
026: import org.sakaiproject.exception.IdInvalidException;
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.time.api.Time;
032: import org.sakaiproject.time.api.TimeRange;
033:
034: /**
035: * <p>CalendarService is the interface for the Calendar service.</p>
036: * <p>The service manages a set of calendars, each containing a set of events.</p>
037: */
038: public interface CalendarService extends EntityProducer {
039: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
040: static final String APPLICATION_ID = "sakai:calendar";
041:
042: /** This string starts the references to resources in this service. */
043: public static final String REFERENCE_ROOT = Entity.SEPARATOR
044: + "calendar";
045:
046: /** Name for the event of adding a calendar event. */
047: public static final String EVENT_ADD_CALENDAR = "calendar.new";
048:
049: /** Name for the event of removing a calendar event */
050: public static final String EVENT_REMOVE_CALENDAR = "calendar.delete";
051:
052: /** Name for the event of removing or changing any events in a calendar. */
053: public static final String EVENT_MODIFY_CALENDAR = "calendar.revise";
054:
055: /** Security lock for adding a calendar event */
056: public static final String AUTH_ADD_CALENDAR = "calendar.new";
057:
058: /** Security lock for removing any calendar event */
059: public static final String AUTH_REMOVE_CALENDAR_ANY = "calendar.delete.any";
060:
061: /** Security lock for removing user's own calendar event */
062: public static final String AUTH_REMOVE_CALENDAR_OWN = "calendar.delete.own";
063:
064: /** Security lock for changing any events (or fields) in a calendar. */
065: public static final String AUTH_MODIFY_CALENDAR_ANY = "calendar.revise.any";
066:
067: /** Security lock for changing user's own events in a calendar. */
068: public static final String AUTH_MODIFY_CALENDAR_OWN = "calendar.revise.own";
069:
070: /** Security lock for importing events into a calendar. */
071: public static final String AUTH_IMPORT_CALENDAR = "calendar.import";
072:
073: /** Security lock for adding to a calendar. */
074: public static final String AUTH_READ_CALENDAR = "calendar.read";
075:
076: /** Security function granted to users who will then have membership in all site groups based on their site membership. */
077: public static final String AUTH_ALL_GROUPS_CALENDAR = "calendar.all.groups";
078:
079: /** The Reference type for a calendar. */
080: public static final String REF_TYPE_CALENDAR = "calendar";
081:
082: /** The Reference type for a calendar pdf. */
083: public static final String REF_TYPE_CALENDAR_PDF = "calpdf";
084:
085: /** The Reference type for an event. */
086: public static final String REF_TYPE_EVENT = "event";
087:
088: /** Recurring event modification intention: no intention. */
089: public static final int MOD_NA = 0;
090:
091: /** Recurring event modification intention: just this one. */
092: public static final int MOD_THIS = 1;
093:
094: /** Recurring event modification intention: all. */
095: public static final int MOD_ALL = 2;
096:
097: /** Recurring event modification intention: this and subsequent. */
098: public static final int MOD_REST = 3;
099:
100: /** Recurring event modification intention: this and prior. */
101: public static final int MOD_PRIOR = 4;
102:
103: /** Calendar Printing Views. */
104: public static final int UNKNOWN_VIEW = -1;
105: public static final int DAY_VIEW = 0;
106: public static final int WEEK_VIEW = 2;
107: public static final int MONTH_VIEW = 3;
108: public static final int LIST_VIEW = 5;
109:
110: /** Security function / event for reading site / event. */
111: public static final String SECURE_READ = "read";
112:
113: /** Security function / event for adding site / event. */
114: public static final String SECURE_ADD = "new";
115:
116: /** Security function / event for removing event */
117: public static final String SECURE_REMOVE = "delete";
118:
119: /** Security function / event for updating event. */
120: public static final String SECURE_UPDATE = "revise";
121:
122: /** Security function giving the user permission to all groups, if granted to at the calendar or calendar level. */
123: public static final String SECURE_ALL_GROUPS = "calendar.all.groups";
124:
125: /** session attribute for list of all calendars user can reference */
126: public static final String SESSION_CALENDAR_LIST = "calendar.ref.list";
127:
128: /**
129: * Return a List of all the defined calendars.
130: * @return a List of Calendar objects (may be empty)
131: */
132: public List getCalendars();
133:
134: /**
135: * Add a new calendar.
136: * Must commitCalendar() to make official, or cancelCalendar() when done!
137: * @param ref The new calendar reference.
138: * @return The newly created calendar.
139: * @exception IdUsedException if the id is not unique.
140: * @exception IdInvalidException if the id is not made up of valid characters.
141: * @exception PermissionException if the user does not have permission to add a calendar.
142: */
143: public CalendarEdit addCalendar(String ref) throws IdUsedException,
144: IdInvalidException, PermissionException;
145:
146: /**
147: * check permissions for getCalendar().
148: * @param ref The calendar reference.
149: * @return true if the user is allowed to getCalendar(ref), false if not.
150: */
151: public boolean allowGetCalendar(String ref);
152:
153: /**
154: * Return a specific calendar.
155: * @param ref The calendar reference.
156: * @return the Calendar that has the specified name.
157: * @exception IdUnusedException If this name is not defined for any calendar.
158: * @exception PermissionException If the user does not have any permissions to the calendar.
159: */
160: public Calendar getCalendar(String ref) throws IdUnusedException,
161: PermissionException;
162:
163: /**
164: * check permissions for importing calendar events
165: * @param ref The calendar reference.
166: * @return true if the user is allowed to import events, false if not.
167: */
168: public boolean allowImportCalendar(String ref);
169:
170: /**
171: * check permissions for editCalendar() e.g. add/delete fields
172: * @param ref The calendar reference.
173: * @return true if the user is allowed to edit the calendar, false if not.
174: */
175: public boolean allowEditCalendar(String ref);
176:
177: /**
178: * check permissions for mergeCalendar()
179: * @param ref The calendar reference.
180: * @return true if the user is allowed to merge the calendar, false if not.
181: */
182: public boolean allowMergeCalendar(String ref);
183:
184: /**
185: * Get a locked calendar object for editing.
186: * Must commitCalendar() to make official, or cancelCalendar() or removeCalendar() when done!
187: * @param ref The calendar reference.
188: * @return A CalendarEdit object for editing.
189: * @exception IdUnusedException if not found, or if not an CalendarEdit object
190: * @exception PermissionException if the current user does not have permission to mess with this user.
191: * @exception InUseException if the Calendar object is locked by someone else.
192: */
193: public CalendarEdit editCalendar(String ref)
194: throws IdUnusedException, PermissionException,
195: InUseException;
196:
197: /**
198: * Commit the changes made to a CalendarEdit object, and release the lock.
199: * The CalendarEdit is disabled, and not to be used after this call.
200: * @param edit The CalendarEdit object to commit.
201: */
202: public void commitCalendar(CalendarEdit edit);
203:
204: /**
205: * Cancel the changes made to a CalendarEdit object, and release the lock.
206: * The CalendarEdit is disabled, and not to be used after this call.
207: * @param edit The CalendarEdit object to commit.
208: */
209: public void cancelCalendar(CalendarEdit edit);
210:
211: /**
212: * Remove a calendar that is locked for edit.
213: * @param edit The calendar to remove.
214: * @exception PermissionException if the user does not have permission to remove a calendar.
215: */
216: public void removeCalendar(CalendarEdit edit)
217: throws PermissionException;
218:
219: /**
220: * Access the internal reference which can be used to access the calendar from within the system.
221: * @param context The context.
222: * @param id The calendar id.
223: * @return The the internal reference which can be used to access the calendar from within the system.
224: */
225: public String calendarReference(String context, String id);
226:
227: /**
228: * Access the internal reference which can be used to access the calendar-in-pdf format from within the system.
229: * @param context The context.
230: * @param id The calendar id.
231: * @return The the internal reference which can be used to access the calendar-in-pdf format from within the system.
232: */
233: public String calendarPdfReference(String context, String id,
234: int scheduleType, String timeRangeString, String userName,
235: TimeRange dailyTimeRange);
236:
237: /**
238: * Access the internal reference which can be used to access the event from within the system.
239: *
240: * @param context
241: * The context.
242: * @param calendarlId
243: * The channel id.
244: * @param id
245: * The event id.
246: * @return The the internal reference which can be used to access the event from within the system.
247: */
248: public String eventReference(String context, String calendarId,
249: String id);
250:
251: /**
252: * Takes several calendar References and merges their events from within a given time range.
253: * @param references The List of calendar References.
254: * @param range The time period to use to select events.
255: * @return CalendarEventVector object with the union of all events from the list of calendars in the given time range.
256: */
257: public CalendarEventVector getEvents(List references,
258: TimeRange range);
259:
260: /**
261: * Construct a new recurrence rule who's frequency description matches the frequency parameter.
262: * @param frequency The frequency description of the desired rule.
263: * @return A new recurrence rule.
264: */
265: RecurrenceRule newRecurrence(String frequency);
266:
267: /**
268: * Construct a new recurrence rule who's frequency description matches the frequency parameter.
269: * @param frequency The frequency description of the desired rule.
270: * @param interval The recurrence interval.
271: * @return A new recurrence rule.
272: */
273: RecurrenceRule newRecurrence(String frequency, int interval);
274:
275: /**
276: * Construct a new recurrence rule who's frequency description matches the frequency parameter.
277: * @param frequency The frequency description of the desired rule.
278: * @param interval The recurrence interval.
279: * @param count The number of reecurrences limit.
280: * @return A new recurrence rule.
281: */
282: RecurrenceRule newRecurrence(String frequency, int interval,
283: int count);
284:
285: /**
286: * Construct a new recurrence rule who's frequency description matches the frequency parameter.
287: * @param frequency The frequency description of the desired rule.
288: * @param interval The recurrence interval.
289: * @param until The time after which recurrences stop.
290: * @return A new recurrence rule.
291: */
292: RecurrenceRule newRecurrence(String frequency, int interval,
293: Time until);
294:
295: } // CalendarService
|