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