This project has retired. For details please refer to its Attic page.
RBACManager xref
View Javadoc

1   package org.apache.archiva.redback.rbac;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   * http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.util.Collection;
23  import java.util.List;
24  import java.util.Map;
25  import java.util.Set;
26  
27  /**
28   * RBACManager
29   *
30   * @author Jesse McConnell <jmcconnell@apache.org>
31   * @author <a href="mailto:joakim@erdfelt.com">Joakim Erdfelt</a>
32   * @todo expand on javadoc
33   */
34  public interface RBACManager
35  {
36  
37      void addListener( RBACManagerListener listener );
38  
39      void removeListener( RBACManagerListener listener );
40  
41  
42      // ------------------------------------------------------------------
43      // Role Methods
44      // ------------------------------------------------------------------
45  
46      /**
47       * Creates an implementation specific {@link Role}, or return an existing {@link Role}, depending
48       * on the provided <code>name</code> parameter.
49       * <p/>
50       * Note: Be sure to use {@link #saveRole(Role)} in order to persist any changes to the Role.
51       *
52       * @param name the name.
53       * @return the new {@link Role} object.
54       */
55      Role createRole( String name );
56  
57      /**
58       * Tests for the existence of a Role.
59       *
60       * @return true if role exists in store.
61       * @throws RbacManagerException
62       */
63      boolean roleExists( String name )
64          throws RbacManagerException;
65  
66      boolean roleExists( Role role )
67          throws RbacManagerException;
68  
69      Role saveRole( Role role )
70          throws RbacObjectInvalidException, RbacManagerException;
71  
72      void saveRoles( Collection<Role> roles )
73          throws RbacObjectInvalidException, RbacManagerException;
74  
75      /**
76       * @param roleName
77       * @return
78       * @throws RbacObjectNotFoundException
79       * @throws RbacManagerException
80       */
81      Role getRole( String roleName )
82          throws RbacObjectNotFoundException, RbacManagerException;
83  
84      Map<String, Role> getRoles( Collection<String> roleNames )
85          throws RbacObjectNotFoundException, RbacManagerException;
86  
87      void addChildRole( Role role, Role childRole )
88          throws RbacObjectInvalidException, RbacManagerException;
89  
90      Map<String, Role> getChildRoles( Role role )
91          throws RbacManagerException;
92  
93      Map<String, Role> getParentRoles( Role role )
94          throws RbacManagerException;
95  
96      /**
97       * Method getRoles
98       */
99      List<Role> getAllRoles()
100         throws RbacManagerException;
101 
102     /**
103      * Method getEffectiveRoles
104      */
105     Set<Role> getEffectiveRoles( Role role )
106         throws RbacObjectNotFoundException, RbacManagerException;
107 
108     /**
109      * Method removeRole
110      *
111      * @param role
112      */
113     void removeRole( Role role )
114         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
115 
116     /**
117      * Method removeRole
118      *
119      * @param roleName
120      */
121     void removeRole( String roleName )
122         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
123 
124     // ------------------------------------------------------------------
125     // Permission Methods
126     // ------------------------------------------------------------------
127 
128     /**
129      * Creates an implementation specific {@link Permission}, or return an existing {@link Permission}, depending
130      * on the provided <code>name</code> parameter.
131      * <p/>
132      * Note: Be sure to use {@link #savePermission(Permission)} in order to persist any changes to the Role.
133      *
134      * @param name the name.
135      * @return the new Permission.
136      * @throws RbacManagerException
137      */
138     Permission createPermission( String name )
139         throws RbacManagerException;
140 
141     /**
142      * Creates an implementation specific {@link Permission} with specified {@link Operation},
143      * and {@link Resource} identifiers.
144      * <p/>
145      * Note: Be sure to use {@link #savePermission(Permission)} in order to persist any changes to the Role.
146      *
147      * @param name               the name.
148      * @param operationName      the {@link Operation#setName(String)} value
149      * @param resourceIdentifier the {@link Resource#setIdentifier(String)} value
150      * @return the new Permission.
151      * @throws RbacManagerException
152      */
153     Permission createPermission( String name, String operationName, String resourceIdentifier )
154         throws RbacManagerException;
155 
156     /**
157      * Tests for the existence of a permission.
158      *
159      * @param name the name to test for.
160      * @return true if permission exists.
161      * @throws RbacManagerException
162      */
163     boolean permissionExists( String name );
164 
165     boolean permissionExists( Permission permission );
166 
167     Permission savePermission( Permission permission )
168         throws RbacObjectInvalidException, RbacManagerException;
169 
170     Permission getPermission( String permissionName )
171         throws RbacObjectNotFoundException, RbacManagerException;
172 
173     List<Permission> getAllPermissions()
174         throws RbacManagerException;
175 
176     void removePermission( Permission permission )
177         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
178 
179     void removePermission( String permissionName )
180         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
181 
182     // ------------------------------------------------------------------
183     // Operation Methods
184     // ------------------------------------------------------------------
185 
186     /**
187      * Creates an implementation specific {@link Operation}, or return an existing {@link Operation}, depending
188      * on the provided <code>name</code> parameter.
189      * <p/>
190      * Note: Be sure to use {@link #saveOperation(Operation)} in order to persist any changes to the Role.
191      *
192      * @param name the name.
193      * @return the new Operation.
194      * @throws RbacManagerException
195      */
196     Operation createOperation( String name )
197         throws RbacManagerException;
198 
199     boolean operationExists( String name );
200 
201     boolean operationExists( Operation operation );
202 
203     /**
204      * Save the new or existing operation to the store.
205      *
206      * @param operation the operation to save (new or existing)
207      * @return the Operation that was saved.
208      * @throws RbacObjectInvalidException
209      * @throws RbacManagerException
210      */
211     Operation saveOperation( Operation operation )
212         throws RbacObjectInvalidException, RbacManagerException;
213 
214     Operation getOperation( String operationName )
215         throws RbacObjectNotFoundException, RbacManagerException;
216 
217     List<Operation> getAllOperations()
218         throws RbacManagerException;
219 
220     void removeOperation( Operation operation )
221         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
222 
223     void removeOperation( String operationName )
224         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
225 
226     // ------------------------------------------------------------------
227     // Resource Methods
228     // ------------------------------------------------------------------
229 
230     /**
231      * Creates an implementation specific {@link Resource}, or return an existing {@link Resource}, depending
232      * on the provided <code>identifier</code> parameter.
233      * <p/>
234      * Note: Be sure to use {@link #saveResource(Resource)} in order to persist any changes to the Role.
235      *
236      * @param identifier the identifier.
237      * @return the new Resource.
238      * @throws RbacManagerException
239      */
240     Resource createResource( String identifier )
241         throws RbacManagerException;
242 
243     boolean resourceExists( String identifier );
244 
245     boolean resourceExists( Resource resource );
246 
247     Resource saveResource( Resource resource )
248         throws RbacObjectInvalidException, RbacManagerException;
249 
250     Resource getResource( String resourceIdentifier )
251         throws RbacObjectNotFoundException, RbacManagerException;
252 
253     List<Resource> getAllResources()
254         throws RbacManagerException;
255 
256     void removeResource( Resource resource )
257         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
258 
259     void removeResource( String resourceIdentifier )
260         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
261 
262     // ------------------------------------------------------------------
263     // UserAssignment Methods
264     // ------------------------------------------------------------------
265 
266     /**
267      * Creates an implementation specific {@link UserAssignment}, or return an existing {@link UserAssignment},
268      * depending on the provided <code>identifier</code> parameter.
269      * <p/>
270      * Note: Be sure to use {@link #saveUserAssignment(UserAssignment)} in order to persist any changes to the Role.
271      *
272      * @param principal the principal reference to the user.
273      * @return the new UserAssignment object.
274      * @throws RbacManagerException
275      */
276     UserAssignment createUserAssignment( String principal )
277         throws RbacManagerException;
278 
279     boolean userAssignmentExists( String principal );
280 
281     boolean userAssignmentExists( UserAssignment assignment );
282 
283     /**
284      * Method saveUserAssignment
285      *
286      * @param userAssignment
287      */
288     UserAssignment saveUserAssignment( UserAssignment userAssignment )
289         throws RbacObjectInvalidException, RbacManagerException;
290 
291     UserAssignment getUserAssignment( String principal )
292         throws RbacObjectNotFoundException, RbacManagerException;
293 
294     /**
295      * Method getAssignments
296      */
297     List<UserAssignment> getAllUserAssignments()
298         throws RbacManagerException;
299 
300     /**
301      * Method getUserAssignmentsForRoless
302      */
303     List<UserAssignment> getUserAssignmentsForRoles( Collection<String> roleNames )
304         throws RbacManagerException;
305 
306     /**
307      * Method removeAssignment
308      *
309      * @param userAssignment
310      */
311     void removeUserAssignment( UserAssignment userAssignment )
312         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
313 
314     /**
315      * Method removeAssignment
316      *
317      * @param principal
318      */
319     void removeUserAssignment( String principal )
320         throws RbacObjectNotFoundException, RbacObjectInvalidException, RbacManagerException;
321 
322     // ------------------------------------------------------------------
323     // UserAssignment Utility Methods
324     // ------------------------------------------------------------------
325 
326     /**
327      * returns the active roles for a given principal
328      * <p/>
329      * NOTE: roles that are returned might have have roles themselves, if
330      * you just want all permissions then use {@link #getAssignedPermissions(String principal)}
331      *
332      * @param principal
333      * @return Collection of {@link Role} objects.
334      * @throws RbacObjectNotFoundException
335      * @throws RbacManagerException
336      */
337     Collection<Role> getAssignedRoles( String principal )
338         throws RbacObjectNotFoundException, RbacManagerException;
339 
340     /**
341      * Get the Collection of {@link Role} objects for this UserAssignment.
342      *
343      * @param userAssignment
344      * @return Collection of {@link Role} objects for the provided UserAssignment.
345      */
346     Collection<Role> getAssignedRoles( UserAssignment userAssignment )
347         throws RbacObjectNotFoundException, RbacManagerException;
348 
349     /**
350      * Get a list of all assignable roles that are currently not effectively assigned to the specific user,
351      * meaning, not a child of any already granted role
352      *
353      * @param principal
354      * @return
355      * @throws RbacManagerException
356      * @throws RbacObjectNotFoundException
357      */
358     Collection<Role> getEffectivelyUnassignedRoles( String principal )
359         throws RbacManagerException, RbacObjectNotFoundException;
360 
361     /**
362      * Get a list of the effectively assigned roles to the specified user, this includes child roles
363      *
364      * @param principal
365      * @return
366      * @throws RbacObjectNotFoundException
367      * @throws RbacManagerException
368      */
369     Collection<Role> getEffectivelyAssignedRoles( String principal )
370         throws RbacObjectNotFoundException, RbacManagerException;
371 
372     /**
373      * Get a list of all assignable roles that are currently not assigned to the specific user.
374      *
375      * @param principal
376      * @return
377      * @throws RbacManagerException
378      * @throws RbacObjectNotFoundException
379      */
380     Collection<Role> getUnassignedRoles( String principal )
381         throws RbacManagerException, RbacObjectNotFoundException;
382 
383     /**
384      * returns a set of all permissions that are in all active roles for a given
385      * principal
386      *
387      * @param principal
388      * @return
389      * @throws RbacObjectNotFoundException
390      * @throws RbacManagerException
391      */
392     Set<Permission> getAssignedPermissions( String principal )
393         throws RbacObjectNotFoundException, RbacManagerException;
394 
395     /**
396      * returns a map of assigned permissions keyed off of operation with a list value of Permissions
397      *
398      * @param principal
399      * @return
400      * @throws RbacObjectNotFoundException
401      * @throws RbacManagerException
402      */
403     Map<String, List<Permission>> getAssignedPermissionMap( String principal )
404         throws RbacObjectNotFoundException, RbacManagerException;
405 
406     /**
407      * returns a list of all assignable roles
408      *
409      * @return
410      * @throws RbacManagerException
411      * @throws RbacObjectNotFoundException
412      */
413     List<Role> getAllAssignableRoles()
414         throws RbacManagerException, RbacObjectNotFoundException;
415 
416     /**
417      * returns the global resource object
418      *
419      * @return
420      * @throws RbacManagerException
421      */
422     Resource getGlobalResource()
423         throws RbacManagerException;
424 
425     void eraseDatabase();
426 
427     /**
428      * consumer of user manager can use it to reload various configuration
429      * with the configurable implementation is possible to change dynamically the real implementation used.
430      *
431      * @since 2.1
432      */
433     void initialize();
434 
435     /**
436      * @return true if this implementation is a final one and not a wrapper (configurable, cached)
437      * @since 2.1
438      */
439     boolean isFinalImplementation();
440 
441     /**
442      * @return a key to be able to customize label in UI
443      * @since 2.1
444      */
445     String getDescriptionKey();
446 
447     /**
448      * Is the RBACManager read only?  if so then create and modify actions are to be disabled
449      *
450      * @return boolean true if user manager is read only
451      */
452     boolean isReadOnly();
453 }