1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.security.api;
23
24 import java.util.ArrayList;
25 import java.util.Collection;
26 import java.util.Iterator;
27 import java.util.List;
28
29 /**
30 * Provides access to users and roles.
31 */
32 public interface UserProvider {
33
34 /** The constant indicating that a provider should be consulted for all organizations */
35 String ALL_ORGANIZATIONS = "*";
36
37 /**
38 * Gets the provider name
39 *
40 * @return the provider name
41 */
42 String getName();
43
44 /**
45 * Gets all known users.
46 *
47 * @return the users
48 */
49 Iterator<User> getUsers();
50
51 /**
52 * Loads a user by username, or returns null if this user is not known to this provider.
53 *
54 * @param userName
55 * the username
56 * @return the user
57 */
58 User loadUser(String userName);
59
60 /**
61 * Returns the number of users in the provider
62 *
63 * @return the count of users in the provider
64 */
65 long countUsers();
66
67 /**
68 * Returns the identifier for the organization that is associated with this user provider. If equal to
69 * {@link #ALL_ORGANIZATIONS}, this provider will always be consulted, regardless of the organization.
70 *
71 * @return the defining organization
72 */
73 String getOrganization();
74
75 /**
76 * Return the found user's as an iterator.
77 *
78 * @param query
79 * the query. Use the wildcards "_" to match any single character and "%" to match an arbitrary number of
80 * characters (including zero characters).
81 * @param offset
82 * the offset
83 * @param limit
84 * the limit. 0 means no limit
85 * @return an iterator of user's
86 * @throws IllegalArgumentException
87 * if the query is <code>null</code>
88 */
89 Iterator<User> findUsers(String query, int offset, int limit);
90
91 /**
92 * Find a list of users by their user names
93 *
94 * Note that the default implementation of this might be slow, as it calls <code>loadUser</code> on every single user.
95 * @param userNames A list of user names
96 * @return A list of resolved user objects
97 */
98 default Iterator<User> findUsers(Collection<String> userNames) {
99 List<User> result = new ArrayList<>(0);
100 for (String name : userNames) {
101 final User e = loadUser(name);
102 if (e != null) {
103 result.add(e);
104 }
105 }
106 return result.iterator();
107 }
108
109 /**
110 * Discards any cached value for given user name.
111 *
112 * @param userName
113 * the user name
114 */
115 void invalidate(String userName);
116
117 }