001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/user/tags/sakai_2-4-1/user-api/api/src/java/org/sakaiproject/user/api/PreferencesService.java $
003: * $Id: PreferencesService.java 8388 2006-04-27 03:12:14Z ggolden@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.user.api;
021:
022: import org.sakaiproject.entity.api.EntityProducer;
023: import org.sakaiproject.exception.IdUnusedException;
024: import org.sakaiproject.exception.IdUsedException;
025: import org.sakaiproject.exception.InUseException;
026: import org.sakaiproject.exception.PermissionException;
027:
028: /**
029: * <p>
030: * The PreferencesService keeps sets of preferences for each user (id)
031: * </p>
032: */
033: public interface PreferencesService extends EntityProducer {
034: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
035: static final String APPLICATION_ID = "sakai:preferences";
036:
037: /** This string starts the references to resources in this service. */
038: static final String REFERENCE_ROOT = "/prefs";
039:
040: /** Securiy / Event for adding a preferences. */
041: static final String SECURE_ADD_PREFS = "prefs.add";
042:
043: /** Securiy / Event for updating a preferences. */
044: static final String SECURE_EDIT_PREFS = "prefs.upd";
045:
046: /** Securiy / Event for removing a preferences. */
047: static final String SECURE_REMOVE_PREFS = "prefs.del";
048:
049: /**
050: * Access a set of preferences associated with this id.
051: *
052: * @param id
053: * The preferences id.
054: * @return The Preferences object.
055: */
056: Preferences getPreferences(String id);
057:
058: /**
059: * Check to see if the current user can add or modify permissions with this id.
060: *
061: * @param id
062: * The preferences id.
063: * @return true if the user is allowed to update or add these preferences, false if not.
064: */
065: boolean allowUpdate(String id);
066:
067: /**
068: * Add a new set of preferences with this id. Must commit(), remove() or cancel() when done.
069: *
070: * @param id
071: * The preferences id.
072: * @return A PreferencesEdit object for editing, possibly new.
073: * @exception PermissionException
074: * if the current user does not have permission add preferences for this id.
075: * @exception IdUsedException
076: * if these preferences already exist.
077: */
078: PreferencesEdit add(String id) throws PermissionException,
079: IdUsedException;
080:
081: /**
082: * Get a locked Preferences object for editing. Must commit(), cancel() or remove() when done.
083: *
084: * @param id
085: * The preferences id.
086: * @return A PreferencesEdit object for editing, possibly new.
087: * @exception PermissionException
088: * if the current user does not have permission to edit these preferences.
089: * @exception InUseException
090: * if the preferences object is locked by someone else.
091: * @exception IdUnusedException
092: * if there is not preferences object with this id.
093: */
094: PreferencesEdit edit(String id) throws PermissionException,
095: InUseException, IdUnusedException;
096:
097: /**
098: * Commit the changes made to a PreferencesEdit object, and release the lock. The PreferencesEdit is disabled, and not to be used after this call.
099: *
100: * @param user
101: * The PreferencesEdit object to commit.
102: */
103: void commit(PreferencesEdit edit);
104:
105: /**
106: * Cancel the changes made to a PreferencesEdit object, and release the lock. The PreferencesEdit is disabled, and not to be used after this call.
107: *
108: * @param user
109: * The PreferencesEdit object to commit.
110: */
111: void cancel(PreferencesEdit edit);
112:
113: /**
114: * Remove this PreferencesEdit - it must be locked from edit(). The PreferencesEdit is disabled, and not to be used after this call.
115: *
116: * @param user
117: * The PreferencesEdit object to remove.
118: */
119: void remove(PreferencesEdit edit);
120: }
|