1 package org.apache.fulcrum.security;
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 import java.io.Serializable;
22
23 import org.apache.fulcrum.security.entity.Group;
24 import org.apache.fulcrum.security.entity.Role;
25 import org.apache.fulcrum.security.util.DataBackendException;
26 import org.apache.fulcrum.security.util.EntityExistsException;
27 import org.apache.fulcrum.security.util.RoleSet;
28 import org.apache.fulcrum.security.util.UnknownEntityException;
29
30 /**
31 * A RoleManager performs {@link org.apache.fulcrum.security.entity.Role}
32 * objects related tasks on behalf of the
33 * {@link org.apache.fulcrum.security.BaseSecurityService}.
34 *
35 * The responsibilities of this class include loading data of a role from the
36 * storage and putting them into the
37 * {@link org.apache.fulcrum.security.entity.Role} objects, saving those data
38 * to the permanent storage.
39 *
40 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
41 * @version $Id$
42 */
43 public interface RoleManager extends Serializable
44 {
45 /** Avalon role - used to id the component within the manager */
46 String ROLE = RoleManager.class.getName();
47
48 /**
49 * Construct a blank Role object
50 *
51 * This method calls getRoleClass, and then creates a new object using the
52 * default constructor.
53 *
54 * @param <T> role type
55 * @return an object implementing Role interface.
56 * @throws DataBackendException if the object could not be instantiated
57 */
58 <T extends Role> T getRoleInstance() throws DataBackendException;
59
60 /**
61 * Construct a blank Role object.
62 *
63 * This method calls getRoleClass, and then creates a new object using the
64 * default constructor.
65 *
66 * @param <T> Role
67 * @param roleName
68 * The name of the Role
69 *
70 * @return an object implementing Role interface.
71 * @throws DataBackendException
72 * if the object could not be instantiated.
73 */
74 <T extends Role> T getRoleInstance(String roleName) throws DataBackendException;
75
76 /**
77 * Retrieve a Role object with specified name.
78 *
79 * @param <T> Role
80 * @param name
81 * the name of the Role.
82 * @return an object representing the Role with specified name.
83 * @throws DataBackendException
84 * if there was an error accessing the data backend.
85 * @throws UnknownEntityException
86 * if the role does not exist.
87 */
88 <T extends Role> T getRoleByName(String name) throws DataBackendException, UnknownEntityException;
89
90 /**
91 * Retrieve a Role object with specified Id.
92 *
93 * @param <T> Role
94 * @param id
95 * the Id of the Role.
96 *
97 * @return an object representing the Role with specified name.
98 *
99 * @exception UnknownEntityException
100 * if the permission does not exist in the database.
101 * @exception DataBackendException
102 * if there is a problem accessing the storage.
103 */
104 <T extends Role> T getRoleById(Object id) throws DataBackendException, UnknownEntityException;
105
106 /**
107 * Retrieves all roles defined in the system.
108 *
109 * @return the names of all roles defined in the system.
110 * @throws DataBackendException
111 * if there was an error accessing the data backend.
112 */
113 RoleSet getAllRoles() throws DataBackendException;
114
115 /**
116 * Creates a new role with specified attributes.
117 *
118 * @param <T> Role
119 *
120 * @param role
121 * The object describing the role to be created.
122 * @return the new Role object.
123 * @throws DataBackendException
124 * if there was an error accessing the data backend.
125 * @throws EntityExistsException
126 * if the role already exists.
127 */
128 <T extends Role> T addRole(T role) throws DataBackendException, EntityExistsException;
129
130 /**
131 * Removes a Role from the system.
132 *
133 * @param role
134 * The object describing the role to be removed.
135 * @throws DataBackendException
136 * if there was an error accessing the data backend.
137 * @throws UnknownEntityException
138 * if the role does not exist.
139 */
140 void removeRole(Role role) throws DataBackendException, UnknownEntityException;
141
142 /**
143 * Renames an existing Role.
144 *
145 * @param role
146 * The object describing the role to be renamed.
147 * @param name
148 * the new name for the role.
149 * @throws DataBackendException
150 * if there was an error accessing the data backend.
151 * @throws UnknownEntityException
152 * if the role does not exist.
153 */
154 void renameRole(Role role, String name) throws DataBackendException, UnknownEntityException;
155
156 /**
157 * Determines if the <code>Role</code> exists in the security system.
158 *
159 * @param role
160 * a <code>Role</code> value
161 * @return true if the role exists in the system, false otherwise
162 * @throws DataBackendException
163 * when more than one Role with the same name exists.
164 */
165 boolean checkExists(Role role) throws DataBackendException;
166
167 /**
168 * Determines if a <code>Role</code> exists in the security system with the
169 * specified role name.
170 *
171 * @param roleName
172 * the name of a <code>Role</code> to check.
173 * @return true if the role exists in the system, false otherwise
174 * @throws DataBackendException
175 * when more than one Role with the same name exists.
176 */
177 boolean checkExists(String roleName) throws DataBackendException;
178 }