View Javadoc

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  import java.util.Map;
22  
23  import org.osgi.service.cm.ConfigurationException;
24  import org.osgi.service.useradmin.Group;
25  import org.osgi.service.useradmin.Role;
26  import org.osgi.service.useradmin.User;
27  import org.osgi.service.useradmin.UserAdmin;
28  
29  /**
30   * The StorageProvider interface defines the methods needed by a UserAdmin
31   * implementation to maintain persistent UserAdmin data.
32   * 
33   * @author Matthias Kuespert
34   * @since 02.07.2009
35   */
36  public interface StorageProvider {
37  
38      /**
39       * Create a new user with the given name. The user initially has no
40       * properties or credentials assigned.
41       * 
42       * @see UserAdmin#createRole(String, int)
43       * @param factory
44       *            The <code>UserAdminFactory</code> used to create the
45       *            implementation object.
46       * @param name
47       *            The user name.
48       * @return An object implementing the <code>User</code> interface or null if
49       *         a role with the given name already exists.
50       * @throws StorageException
51       *             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       * @param factory
61       *            The <code>UserAdminFactory</code> used to create the
62       *            implementation object.
63       * @param name
64       *            The group name.
65       * @return An object implementing the <code>Group</code> interface or null
66       *         if a role with the given name already exists.
67       * @throws StorageException
68       *             if the user could not be created
69       */
70      Group createGroup(UserAdminFactory factory, String name) throws StorageException;
71  
72      /**
73       * Deletes the role with the given name. The role is also removed from all
74       * groups it is a member of.
75       * 
76       * @see UserAdmin#removeRole(String)
77       * @param role
78       *            The <code>Role</code> to delete.
79       * @return True if the role could be deleted.
80       * @throws StorageException
81       *             if an error occured while storing the role
82       */
83      boolean deleteRole(Role role) throws StorageException;
84  
85      // group management
86  
87      /**
88       * Retrieve basic members of the given group. Eventually creates new Role
89       * objects via the given factory.
90       * 
91       * @see Group#getMembers()
92       * @param factory
93       *            The <code>UserAdminFactory</code> used to create member roles.
94       * @param group
95       *            The <code>Group</code> whose members are retrieved.
96       * @return A collection of <code>Role</code> objects that are basic members
97       *         of the given group.
98       * @throws StorageException
99       */
100     Collection<Role> getMembers(UserAdminFactory factory, Group group) throws StorageException;
101 
102     /**
103      * Retrieve required members of the given group. Eventually creates new Role
104      * objects via the given factory.
105      * 
106      * @see Group#getRequiredMembers()
107      * @param factory
108      *            The <code>UserAdminFactory</code> used to create member roles.
109      * @param group
110      *            The <code>Group</code> whose members are retrieved.
111      * @return A collection of <code>Role</code> objects that are required
112      *         members of the given group.
113      * @throws StorageException
114      */
115     Collection<Role> getRequiredMembers(UserAdminFactory factory, Group group) throws StorageException;
116 
117     /**
118      * Adds a role as a basic member to a group.
119      * 
120      * @see Group#addMember(Role)
121      * @param group
122      *            The <code>Group</code> to add the <code>Role</code> as basic
123      *            member.
124      * @param role
125      *            The <code>Role</code> to add.
126      * @return True if the given role was added - false otherwise.
127      * @throws StorageException
128      */
129     boolean addMember(Group group, Role role) throws StorageException;
130 
131     /**
132      * Adds a role as a required member to a group.
133      * 
134      * @see Group#addRequiredMember(Role)
135      * @param group
136      *            The <code>Group</code> to add the <code>Role</code> as
137      *            required member.
138      * @param role
139      *            The <code>Role</code> to add.
140      * @return True if the given role was added - false otherwise.
141      * @throws StorageException
142      */
143     boolean addRequiredMember(Group group, Role role) throws StorageException;
144 
145     /**
146      * Removes a member from the given group.
147      * 
148      * @see Group#removeMember(Role)
149      * @param group
150      * @param role
151      * @return
152      * @throws StorageException
153      */
154     boolean removeMember(Group group, Role role) throws StorageException;
155 
156     // property management
157 
158     /**
159      * Sets a <code>String</code> attribute to a role.
160      * 
161      * @param role
162      *            The <code>Role</code> to set the attribute to.
163      * @param key
164      *            The key of the attribute.
165      * @param value
166      *            The value of the attribute.
167      * @throws StorageException
168      */
169     void setRoleAttribute(Role role, String key, Object value) throws StorageException;
170 
171     /**
172      * Removes an attribute from a role.
173      * 
174      * @param role
175      *            The <code>Role</code> to remove the attribute from.
176      * @param key
177      *            The key of the attribute.
178      * @throws StorageException
179      */
180     void removeRoleAttribute(Role role, String key) throws StorageException;
181 
182     /**
183      * Removes all attributes from the given role.
184      * 
185      * @param role
186      *            The <code>Role</code> to remove the attribute(s) from.
187      * @throws StorageException
188      */
189     void clearRoleAttributes(Role role) throws StorageException;
190 
191     // credential management
192 
193     /**
194      * @return the provider that gives acces to credential information
195      */
196     CredentialProvider getCredentialProvider();
197 
198     // role getters & finders
199 
200     /**
201      * Returns the role with the given name.
202      * 
203      * @see UserAdmin#getRole(String)
204      * @param factory
205      *            The <code>UserAdminFactory</code> used to eventually create
206      *            the implementation object.
207      * @param name
208      *            The role to find.
209      * @return A <code>Role</code> implementation.
210      * @throws StorageException
211      */
212     Role getRole(UserAdminFactory factory, String name) throws StorageException;
213 
214     /**
215      * Retrieves the user with the given attributes.
216      * 
217      * @see UserAdmin#getUser(String, String)
218      * @param factory
219      *            The <code>UserAdminFactory</code> used to eventually create
220      *            the implementation object.
221      * @param key
222      *            The attribute key to search for.
223      * @param value
224      *            The attribute value to search for.
225      * @return The <code>User</code> object matching the query.
226      * @throws StorageException
227      */
228     User getUser(UserAdminFactory factory, String key, String value) throws StorageException;
229 
230     /**
231      * Returns the roles that match the given filter.
232      * 
233      * @see UserAdmin#getRoles(String)
234      * @param factory
235      *            The <code>UserAdminFactory</code> used to eventually create
236      *            the implementation object.
237      * @param filter
238      * @return
239      * @throws StorageException
240      */
241     Collection<Role> findRoles(UserAdminFactory factory, String filter) throws StorageException;
242 
243     /**
244      * Called whenever a configuration is detected for this provider
245      * 
246      * @param properties
247      * @throws ConfigurationException
248      */
249     void configurationUpdated(Map<String, ?> properties) throws ConfigurationException;
250 }