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