001 /*
002 *
003 * $Revision: 14986 $ $Date: 2009-03-20 21:41:45 +0100 (Fri, 20 Mar 2009) $
004 *
005 * This file is part of *** M y C o R e ***
006 * See http://www.mycore.de/ for details.
007 *
008 * This program is free software; you can use it, redistribute it
009 * and / or modify it under the terms of the GNU General Public License
010 * (GPL) as published by the Free Software Foundation; either version 2
011 * of the License or (at your option) any later version.
012 *
013 * This program is distributed in the hope that it will be useful, but
014 * WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program, in a file called gpl.txt or license.txt.
020 * If not, write to the Free Software Foundation Inc.,
021 * 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA
022 */
023 package org.mycore.access;
024
025 import java.util.Collection;
026
027 import org.jdom.Element;
028 import org.mycore.common.MCRException;
029 import org.mycore.user.MCRUser;
030
031 /**
032 * This serves as an interface to an underlying access controll system.
033 *
034 * @author Thomas Scheffler (yagee)
035 *
036 * @version $Revision: 14986 $ $Date: 2009-03-20 21:41:45 +0100 (Fri, 20 Mar 2009) $
037 * @since 1.3
038 */
039 public interface MCRAccessInterface {
040
041 /**
042 * create an access rule in the rulestore using an rule string in plain text
043 *
044 * @param rule
045 * the rule string in plain text
046 * @param creator
047 * @param description
048 * a String description of the rule in prosa
049 */
050 public void createRule(String rule, String creator, String description);
051
052 /**
053 * create an access rule in the rulestore using an rule string in plain text
054 *
055 * @param rule
056 * the rule string as xml
057 * @param creator
058 * @param description
059 * a String description of the rule in prosa
060 */
061 public void createRule(Element rule, String creator, String description);
062
063 /**
064 * generate rule string from xml
065 *
066 * @param rule
067 * @return the normalized rule string
068 */
069 public String getNormalizedRuleString(Element rule);
070
071 /**
072 * adds an access rule for an ID to an access system. The parameter
073 * <code>id</code> serves as an identifier for the concrete underlying
074 * rule, e.g. a MCRObjectID.
075 *
076 * @param id
077 * the ID-String of the object
078 * @param permission
079 * the access permission for the rule
080 * @param rule
081 * the access rule
082 * @param description
083 * a String description of the rule in prosa
084 * @throws MCRException
085 * if an error occured
086 */
087 public void addRule(String id, String permission, org.jdom.Element rule, String description) throws MCRException;
088
089 /**
090 * adds an access rule for an "a priori-permission" like "create-document"
091 *
092 * @param permission
093 * the access permission for the rule (e.g. "create-document")
094 * @param rule
095 * the access rule
096 * @param description
097 * a String description of the rule in prosa
098 * @throws MCRException
099 * if an error occured
100 */
101 public void addRule(String permission, org.jdom.Element rule, String description) throws MCRException;
102
103 /**
104 * removes a rule. The parameter <code>id</code> serves as an identifier
105 * for the concrete underlying rule, e.g. a MCRObjectID.
106 *
107 * @param id
108 * the ID-String of the object
109 * @param permission
110 * the access permission for the rule
111 * @throws MCRException
112 * if an error occured
113 */
114 public void removeRule(String id, String permission) throws MCRException;
115
116 /**
117 * removes a rule for an "a priori permission" like "create-document"
118 *
119 * @param permission
120 * the access permission for the rule
121 * @throws MCRException
122 * if an error occured
123 */
124 public void removeRule(String permission) throws MCRException;
125
126 /**
127 * removes all rules of the <code>id</code>. The parameter
128 * <code>id</code> serves as an identifier for the concrete underlying
129 * rule, e.g. a MCRObjectID.
130 *
131 * @param id
132 * the ID-String of the object
133 * @throws MCRException
134 * if an errow was occured
135 */
136 public void removeAllRules(String id) throws MCRException;
137
138 /**
139 * updates an access rule for an ID to an access system. The parameter
140 * <code>id</code> serves as an identifier for the concrete underlying
141 * rule, e.g. a MCRObjectID.
142 *
143 * @param id
144 * the ID-String of the object
145 * @param permission
146 * the access permission for the rule
147 * @param rule
148 * the access rule
149 * @param description
150 * a String description of the rule in prosa
151 * @throws MCRException
152 * if an errow was occured
153 */
154 public void updateRule(String id, String permission, Element rule, String description) throws MCRException;
155
156 /**
157 * updates an access rule for an "a priori permission"
158 * of an access system like "create-document".
159 *
160 * @param permission
161 * the access permission for the rule
162 * @param rule
163 * the access rule
164 * @param description
165 * a String description of the rule in prosa
166 * @throws MCRException
167 * if an errow was occured
168 */
169 public void updateRule(String permission, Element rule, String description) throws MCRException;
170
171 /**
172 * determines whether the current user has the permission to perform a
173 * certain action.
174 *
175 * All information regarding the current user is capsulated by a
176 * <code>MCRSession</code> instance which can be retrieved by
177 *
178 * <pre>
179 * MCRSession currentSession = MCRSessionMgr.getCurrentSession();
180 * </pre>
181 *
182 * The parameter <code>id</code> serves as an identifier for the concrete
183 * underlying rule, e.g. a MCRObjectID.
184 *
185 * @param id
186 * the ID-String of the object
187 * @param permission
188 * the permission/action to be granted, e.g. "read"
189 * @return true if the permission is granted, else false
190 * @see org.mycore.common.MCRSessionMgr#getCurrentSession()
191 * @see org.mycore.common.MCRSession
192 */
193 public boolean checkPermission(String id, String permission);
194
195 /**
196 * determines whether a given user has the permission to perform a
197 * certain action. no session data will be checked here.
198 *
199 *
200 * The parameter <code>id</code> serves as an identifier for the concrete
201 * underlying rule, e.g. a MCRObjectID.
202 *
203 * @param id
204 * the ID-String of the object
205 * @param permission
206 * the permission/action to be granted, e.g. "read"
207 * @param user
208 * the MCRUser, whose permissions are checked
209 * @return true if the permission is granted, else false
210 * @see org.mycore.common.MCRSessionMgr#getCurrentSession()
211 * @see org.mycore.common.MCRSession
212 */
213 public boolean checkPermission(String id, String permission, MCRUser user);
214
215 /**
216 * determines whether the current user has the permission to perform a
217 * certain action.
218 *
219 * All information regarding the current user is capsulated by a
220 * <code>MCRSession</code> instance which can be retrieved by
221 *
222 * <pre>
223 * MCRSession currentSession = MCRSessionMgr.getCurrentSession();
224 * </pre>
225 *
226 * This method is used for checking "a priori permissions" like "create-document"
227 * where a String ID does not exist yet
228 *
229 * @param permission
230 * the permission/action to be granted, e.g. "create-document"
231 * @return true if the permission is granted, else false
232 * @see org.mycore.common.MCRSessionMgr#getCurrentSession()
233 * @see org.mycore.common.MCRSession
234 */
235 public boolean checkPermission(String permission);
236
237 /**
238 * determines whether a given user has the permission to perform a
239 * certain action. no session data will be checked here.
240 *
241 * This method is used for checking "a priori permissions" like "create-document"
242 * where a String ID does not exist yet
243 *
244 * @param permission
245 * the permission/action to be granted, e.g. "create-document"
246 * @param user
247 * the MCRUser, whose permissions are checked
248 * @return true if the permission is granted, else false
249 * @see org.mycore.common.MCRSessionMgr#getCurrentSession()
250 * @see org.mycore.common.MCRSession
251 */
252 public boolean checkPermission(String permission, MCRUser user);
253
254 /**
255 * determines whether the current user has the permission to perform a
256 * certain action.
257 *
258 * All information regarding the current user is capsulated by a
259 * <code>MCRSession</code> instance which can be retrieved by
260 *
261 * <pre>
262 * MCRSession currentSession = MCRSessionMgr.getCurrentSession();
263 * </pre>
264 * @param rule
265 * the jdom-representation of a mycore access rule
266 * @return true if the permission is granted, else false
267 * @see org.mycore.common.MCRSessionMgr#getCurrentSession()
268 * @see org.mycore.common.MCRSession
269 */
270 public boolean checkPermission(org.jdom.Element rule) ;
271
272 /**
273 * exports a access rule as JDOM element.
274 *
275 * @param id
276 * the ID-String of the object
277 * @param permission
278 * the access permission for the rule
279 * @return the rule as jdom element, or <code>null</code> if no rule is
280 * defined
281 */
282 public Element getRule(String id, String permission);
283
284 /**
285 * exports a access rule for a "a priori permission"
286 * as JDOM element.
287 *
288 * @param permission
289 * the access permission for the rule
290 * @return the rule as jdom element, or <code>null</code> if no rule is
291 * defined
292 */
293 public Element getRule(String permission);
294
295 /**
296 * returns the prosa description of a defined rule for a "a priori" permission like "create-document".
297 *
298 * @param permission
299 * the access permission for the rule
300 * @return the String of the description
301 */
302 public String getRuleDescription(String permission);
303
304 /**
305 * returns the prosa description of a defined rule.
306 *
307 * @param id
308 * the ID-String of the object
309 * @param permission
310 * the access permission for the rule
311 * @return the String of the description
312 */
313 public String getRuleDescription(String id, String permission);
314
315 /**
316 * lists all permissions defined for the <code>id</code>.
317 *
318 * The parameter <code>id</code> serves as an identifier for the concrete
319 * underlying rule, e.g. a MCRObjectID.
320 *
321 * @param id
322 * @return a <code>List</code> of all for <code>id</code> defined
323 * permission
324 */
325 public Collection<String> getPermissionsForID(String id);
326
327 /**
328 * lists all a-priori permissions like "create-document".
329 *
330 * @return a <code>List</code> of all defined permissions
331 */
332 public Collection<String> getPermissions();
333
334 /**
335 * list all object-related Access Permissions that are defined
336 * in configuration files
337 *
338 * @return a List of permissiond from the configuration
339 */
340 public Collection<String> getAccessPermissionsFromConfiguration();
341
342 /**
343 * lists all String IDs, a permission is assigned to.
344 *
345 * The parameter <code>id</code> serves as an identifier for the concrete
346 * underlying rule, e.g. a MCRObjectID.
347 *
348 * @return a sorted and distinct <code>List</code> of all <code>String</code> IDs
349 */
350 public Collection<String> getAllControlledIDs();
351
352 /**
353 * checks wether a rule with the <code>id</code> and
354 * <code>permission</code> is defined.
355 *
356 * @param id
357 * the ID-String of the object
358 * @param permission
359 * the access permission for the rule
360 * @return false, if getRule(id, permission) would return null, else true
361 */
362 public boolean hasRule(String id, String permission);
363
364 /**
365 * checks wether a rule with the <code>id</code> is defined.
366 *
367 * @param id
368 * the ID-String of the object
369 * @return false, if getPermissionsForID(id) would return an empty list,
370 * else true
371 */
372 public boolean hasRule(String id);
373
374 }