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 }