001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/alias/tags/sakai_2-4-1/alias-api/api/src/java/org/sakaiproject/alias/api/AliasService.java $
003: * $Id: AliasService.java 8385 2006-04-27 03:09:38Z 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.alias.api;
021:
022: import java.util.List;
023:
024: import org.sakaiproject.entity.api.EntityProducer;
025: import org.sakaiproject.exception.IdInvalidException;
026: import org.sakaiproject.exception.IdUnusedException;
027: import org.sakaiproject.exception.IdUsedException;
028: import org.sakaiproject.exception.InUseException;
029: import org.sakaiproject.exception.PermissionException;
030:
031: /**
032: * <p>
033: * AliasService provides a single unque namespace where Sakai entities can have alternate case-insenstive names.
034: * </p>
035: */
036: public interface AliasService extends EntityProducer {
037: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
038: static final String APPLICATION_ID = "sakai:alias";
039:
040: /** This string starts the references to resources in this service. */
041: static final String REFERENCE_ROOT = "/alias";
042:
043: /** Name for the event of adding an alias. */
044: static final String SECURE_ADD_ALIAS = "alias.add";
045:
046: /** Name for the event of updating an alias. */
047: static final String SECURE_UPDATE_ALIAS = "alias.upd";
048:
049: /** Name for the event of removing an alias. */
050: static final String SECURE_REMOVE_ALIAS = "alias.del";
051:
052: /**
053: * Check if the current user has permission to set this alias.
054: *
055: * @param alias
056: * The alias.
057: * @param target
058: * The resource reference string alias target.
059: * @return true if the current user has permission to set this alias, false if not.
060: */
061: boolean allowSetAlias(String alias, String target);
062:
063: /**
064: * Allocate an alias for a resource
065: *
066: * @param alias
067: * The alias.
068: * @param target
069: * The resource reference string alias target.
070: * @throws IdUsedException
071: * if the alias is already used.
072: * @throws IdInvalidException
073: * if the alias id is invalid.
074: * @throws PermissionException
075: * if the current user does not have permission to set this alias.
076: */
077: void setAlias(String alias, String target) throws IdUsedException,
078: IdInvalidException, PermissionException;
079:
080: /**
081: * Check to see if the current user can remove this alias.
082: *
083: * @param alias
084: * The alias.
085: * @return true if the current user can remove this alias, false if not.
086: */
087: boolean allowRemoveAlias(String alias);
088:
089: /**
090: * Remove an alias.
091: *
092: * @param alias
093: * The alias.
094: * @exception IdUnusedException
095: * if not found.
096: * @exception PermissionException
097: * if the current user does not have permission to remove this alias.
098: * @exception InUseException
099: * if the Alias object is locked by someone else.
100: */
101: void removeAlias(String alias) throws IdUnusedException,
102: PermissionException, InUseException;
103:
104: /**
105: * Check to see if the current user can remove these aliasese for this target resource reference.
106: *
107: * @param target
108: * The target resource reference string.
109: * @return true if the current user can remove these aliasese for this target resource reference, false if not.
110: */
111: boolean allowRemoveTargetAliases(String target);
112:
113: /**
114: * Remove all aliases for this target resource reference, if any.
115: *
116: * @param target
117: * The target resource reference string.
118: * @throws PermissionException
119: * if the current user does not have permission to remove these aliases.
120: */
121: void removeTargetAliases(String target) throws PermissionException;
122:
123: /**
124: * Find the target resource reference string associated with this alias.
125: *
126: * @param alias
127: * The alias.
128: * @return The target resource reference string associated with this alias.
129: * @throws IdUnusedException
130: * if the alias is not defined.
131: */
132: String getTarget(String alias) throws IdUnusedException;
133:
134: /**
135: * Find all the aliases defined for this target.
136: *
137: * @param target
138: * The target resource reference string.
139: * @return A list (Alias) of all the aliases defined for this target.
140: */
141: List getAliases(String target);
142:
143: /**
144: * Find all the aliases defined for this target, within the record range given (sorted by id).
145: *
146: * @param target
147: * The target resource reference string.
148: * @param first
149: * The first record position to return.
150: * @param last
151: * The last record position to return.
152: * @return A list (Alias) of all the aliases defined for this target, within the record range given (sorted by id).
153: */
154: List getAliases(String target, int first, int last);
155:
156: /**
157: * Find all the aliases within the record range given (sorted by id).
158: *
159: * @param first
160: * The first record position to return.
161: * @param last
162: * The last record position to return.
163: * @return A list (Alias) of all the aliases within the record range given (sorted by id).
164: */
165: List getAliases(int first, int last);
166:
167: /**
168: * Count all the aliases.
169: *
170: * @return The count of all aliases.
171: */
172: int countAliases();
173:
174: /**
175: * Search all the aliases that match this criteria in id or target, returning a subset of records within the record range given (sorted by id).
176: *
177: * @param criteria
178: * The search criteria.
179: * @param first
180: * The first record position to return.
181: * @param last
182: * The last record position to return.
183: * @return A list (Alias) of all the aliases matching the criteria, within the record range given (sorted by id).
184: */
185: List searchAliases(String criteria, int first, int last);
186:
187: /**
188: * Count all the aliases that match this criteria in id or target.
189: *
190: * @return The count of all aliases matching the criteria.
191: */
192: int countSearchAliases(String criteria);
193:
194: /**
195: * Access the internal reference which can be used to access the resource from within the system.
196: *
197: * @param id
198: * The alias id string.
199: * @return The the internal reference which can be used to access the resource from within the system.
200: */
201: String aliasReference(String id);
202:
203: /**
204: * Check to see if the current user can add an alias.
205: *
206: * @return true if the current user can add an alias, false if not.
207: */
208: boolean allowAdd();
209:
210: /**
211: * Add a new alias. Must commit() to make official, or cancel() when done!
212: *
213: * @param id
214: * The alias id.
215: * @return A locked AliasEdit object (reserving the id).
216: * @exception IdInvalidException
217: * if the alias id is invalid.
218: * @exception IdUsedException
219: * if the alias id is already used.
220: * @exception PermissionException
221: * if the current user does not have permission to add an alias.
222: */
223: AliasEdit add(String id) throws IdInvalidException,
224: IdUsedException, PermissionException;
225:
226: /**
227: * Check to see if the current user can edit this alias.
228: *
229: * @param id
230: * The alias id string.
231: * @return true if the current user can edit this alias, false if not.
232: */
233: boolean allowEdit(String id);
234:
235: /**
236: * Get a locked alias object for editing. Must commit() to make official, or cancel() (or remove()) when done!
237: *
238: * @param id
239: * The alias id string.
240: * @return An AliasEdit object for editing.
241: * @exception IdUnusedException
242: * if not found.
243: * @exception PermissionException
244: * if the current user does not have permission to mess with this alias.
245: * @exception InUseException
246: * if the Alias object is locked by someone else.
247: */
248: AliasEdit edit(String id) throws IdUnusedException,
249: PermissionException, InUseException;
250:
251: /**
252: * Commit the changes made to a AliasEdit object, and release the lock. The AliasEdit is disabled, and not to be used after this call.
253: *
254: * @param user
255: * The AliasEdit object to commit.
256: */
257: void commit(AliasEdit edit);
258:
259: /**
260: * Cancel the changes made to a AliasEdit object, and release the lock. The AliasEdit is disabled, and not to be used after this call.
261: *
262: * @param user
263: * The AliasEdit object to commit.
264: */
265: void cancel(AliasEdit edit);
266:
267: /**
268: * Remove this alias information - it must be a user with a lock from edit(). The AliasEdit is disabled, and not to be used after this call.
269: *
270: * @param edit
271: * The locked AliasEdit object to remove.
272: * @exception PermissionException
273: * if the current user does not have permission to remove this alias.
274: */
275: void remove(AliasEdit edit) throws PermissionException;
276: }
|