1 /**
2 * Copyright 2009 OPS4J
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 *
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.ops4j.pax.useradmin.service.spi;
19
20 import java.util.Collection;
21
22 import org.osgi.service.useradmin.Group;
23 import org.osgi.service.useradmin.Role;
24 import org.osgi.service.useradmin.User;
25 import org.osgi.service.useradmin.UserAdmin;
26
27 /**
28 * The StorageProvider interface defines the methods needed by a UserAdmin
29 * implementation to maintain persistent UserAdmin data.
30 *
31 * @author Matthias Kuespert
32 * @since 02.07.2009
33 */
34 public interface StorageProvider {
35
36 // private enum GroupType { BASIC, REQUIRED };
37
38 // role management
39
40 /**
41 * Create a new user with the given name. The user initially has no
42 * properties or credentials assigned.
43 *
44 * @see UserAdmin#createRole(String, int)
45 *
46 * @param factory The <code>UserAdminFactory</code> used to create the
47 * implementation object.
48 * @param name The user name.
49 * @return An object implementing the <code>User</code> interface or null if
50 * a role with the given name already exists.
51 * @throws StorageException if the user could not be created
52 */
53 User createUser(UserAdminFactory factory, String name) throws StorageException;
54
55 /**
56 * Create a new group with the given name. The group initially has no
57 * properties or credentials assigned.
58 *
59 * @see UserAdmin#createRole(String, int)
60 *
61 * @param factory The <code>UserAdminFactory</code> used to create the
62 * implementation object.
63 * @param name The group name.
64 * @return An object implementing the <code>Group</code> interface or null
65 * if a role with the given name already exists.
66 * @throws StorageException if the user could not be created
67 */
68 Group createGroup(UserAdminFactory factory, String name) throws StorageException;
69
70 /**
71 * Deletes the role with the given name. The role is also removed from all
72 * groups it is a member of.
73 *
74 * @see UserAdmin#removeRole(String)
75 *
76 * @param role The <code>Role</code> to delete.
77 * @throws StorageException if the role could not be deleted.
78 */
79 boolean deleteRole(Role role) throws StorageException;
80
81 // group management
82
83 /**
84 * Retrieve basic members of the given group. Eventually creates new Role
85 * objects via the given factory.
86 *
87 * @see Group#getMembers()
88 *
89 * @param factory The <code>UserAdminFactory</code> used to create member
90 * roles.
91 * @param group The <code>Group</code> whose members are retrieved.
92 * @return A collection of <code>Role</code> objects that are basic members
93 * of the given group.
94 * @throws StorageException
95 */
96 Collection<Role> getMembers(UserAdminFactory factory, Group group) throws StorageException;
97
98 /**
99 * Retrieve required members of the given group. Eventually creates new Role
100 * objects via the given factory.
101 *
102 * @see Group#getRequiredMembers()
103 *
104 * @param factory The <code>UserAdminFactory</code> used to create member
105 * roles.
106 * @param group The <code>Group</code> whose members are retrieved.
107 * @return A collection of <code>Role</code> objects that are required members
108 * of the given group.
109 * @throws StorageException
110 */
111 Collection<Role> getRequiredMembers(UserAdminFactory factory, Group group) throws StorageException;
112
113 /**
114 * Adds a role as a basic member to a group.
115 *
116 * @see Group#addMember(Role)
117 *
118 * @param group The <code>Group</code> to add the <code>Role</code> as basic member.
119 * @param role The <code>Role</code> to add.
120 * @return True if the given role was added - false otherwise.
121 * @throws StorageException
122 */
123 boolean addMember(Group group, Role role) throws StorageException;
124
125 /**
126 * Adds a role as a required member to a group.
127 *
128 * @see Group#addRequiredMember(Role)
129 *
130 * @param group The <code>Group</code> to add the <code>Role</code> as required member.
131 * @param role The <code>Role</code> to add.
132 * @return True if the given role was added - false otherwise.
133 * @throws StorageException
134 */
135 boolean addRequiredMember(Group group, Role role) throws StorageException;
136
137 /**
138 * Removes a member from the given group.
139 *
140 * @see Group#removeMember(Role)
141 *
142 * @param group
143 * @param role
144 * @return
145 * @throws StorageException
146 */
147 boolean removeMember(Group group, Role role) throws StorageException;
148
149 // property management
150
151 /**
152 * Sets a <code>String</code> attribute to a role.
153 *
154 * @param role The <code>Role</code> to set the attribute to.
155 * @param key The key of the attribute.
156 * @param value The value of the attribute.
157 * @throws StorageException
158 */
159 void setRoleAttribute(Role role, String key, Object value) throws StorageException;
160
161 /**
162 * Removes an attribute from a role.
163 *
164 * @param role The <code>Role</code> to remove the attribute from.
165 * @param key The key of the attribute.
166 * @throws StorageException
167 */
168 void removeRoleAttribute(Role role, String key) throws StorageException;
169
170 /**
171 * Removes all attributes from the given role.
172 *
173 * @param role The <code>Role</code> to remove the attribute(s) from.
174 * @throws StorageException
175 */
176 void clearRoleAttributes(Role role) throws StorageException;
177
178 // credential management
179
180 /**
181 * Sets a <code>String</code> credential to a user.
182 *
183 * @param user The <code>User</code> to set the credential to.
184 * @param key The key of the credential.
185 * @param value The value of the credential.
186 * @throws StorageException
187 */
188 void setUserCredential(User user, String key, Object value) throws StorageException;
189
190 /**
191 * Removes a credential from a role.
192 *
193 * @param user The <code>User</code> to remove the credential from.
194 * @param key The key of the credential.
195 * @throws StorageException
196 */
197 void removeUserCredential(User user, String key) throws StorageException;
198
199 /**
200 * Removes all credentials for a user.
201 *
202 * @param user The <code>User</code> to remove the credentials for.
203 * @throws StorageException
204 */
205 void clearUserCredentials(User user) throws StorageException;
206
207 // role getters & finders
208
209 /**
210 * Returns the role with the given name.
211 *
212 * @see UserAdmin#getRole(String)
213 *
214 * @param factory The <code>UserAdminFactory</code> used to eventually create the
215 * implementation object.
216 * @param name The role to find.
217 * @return A <code>Role</code> implementation.
218 * @throws StorageException
219 */
220 Role getRole(UserAdminFactory factory, String name) throws StorageException;
221
222 /**
223 * Retrieves the user with the given attributes.
224 *
225 * @see UserAdmin#getUser(String, String)
226 *
227 * @param factory The <code>UserAdminFactory</code> used to eventually create the
228 * implementation object.
229 * @param key The attribute key to search for.
230 * @param value The attribute value to search for.
231 * @return The <code>User</code> object matching the query.
232 * @throws StorageException
233 */
234 User getUser(UserAdminFactory factory, String key, String value) throws StorageException;
235
236 /**
237 * Returns the roles that match the given filter.
238 *
239 * @see UserAdmin#getRoles(String)
240 *
241 * @param factory The <code>UserAdminFactory</code> used to eventually create the
242 * implementation object.
243 * @param filter
244 * @return
245 * @throws StorageException
246 */
247 Collection<Role> findRoles(UserAdminFactory factory, String filter) throws StorageException;
248 }