001package org.apache.archiva.redback.users;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 * http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.util.List;
023
024/**
025 * User Manager Interface
026 *
027 * @TODO: Add Streaming Methods
028 * @TODO: Improve query to allow multiple sort values
029 * @TODO: Improve query to avoid UnsupportedOperationExceptions (e.g. in LDAP or combined user manager)
030 * @TODO: Improve query to allow upper/lowercase and substring queries for all user managers
031 * @TODO: Add method for total count of users
032 *
033 * @author Jason van Zyl
034 * @author <a href="mailto:joakim@erdfelt.com">Joakim Erdfelt</a>
035 */
036public interface UserManager
037{
038
039    static final String GUEST_USERNAME = "guest";
040
041    /**
042     * Is the UserManager read only?  if so then create and modify actions are to be disabled
043     *
044     * @return boolean true if user manager is disabled
045     */
046    boolean isReadOnly();
047
048    /**
049     * An Identifier for the UserManager.
050     *
051     * @return the user manager identifier.
052     */
053    String getId();
054
055    /**
056     * Add a {@link UserManagerListener} to track major events in the
057     * UserManager.
058     *
059     * @param listener the listener to add.
060     */
061    void addUserManagerListener( UserManagerListener listener );
062
063    /**
064     * Remove a {@link UserManagerListener} from the collection of listeners.
065     *
066     * @param listener the listener to remove.
067     */
068    void removeUserManagerListener( UserManagerListener listener );
069
070    /**
071     * Factory method to create new User Objects based on provider specific
072     * implementation.
073     *
074     * User objects created this way do not exist in the provider's underlying
075     * data store until a call to {@link #addUser(User)} is made.
076     *
077     * @param username     the username for this user.
078     * @param fullName     the full name for this user.
079     * @param emailAddress the email address for this user.
080     * @return the new user object ready to use.
081     * @throws UserManagerException
082     */
083    User createUser( String username, String fullName, String emailAddress )
084        throws UserManagerException;
085
086    /**
087     * Factory method to create the guest user.
088     *
089     * @return The guest user
090     * @throws UserManagerException
091     */
092    User createGuestUser()
093        throws UserManagerException;
094
095    /**
096     * Factory method to create {@link UserQuery}s based on provider specific
097     * implementations.
098     *
099     * @return the provider implementation of UserQuery
100     */
101    UserQuery createUserQuery();
102
103    /**
104     * Get the List of {@link User} objects.
105     *
106     * @return the List of {@link User} Objects.
107     * @throws UserManagerException
108     */
109    List<? extends User> getUsers()
110        throws UserManagerException;
111
112    List<? extends User> getUsers( boolean orderAscending )
113        throws UserManagerException;
114
115    /**
116     * Add a User.
117     *
118     * @param user the user to add.
119     * @return the user that was just added.
120     * @throws UserManagerException
121     */
122    User addUser( User user )
123        throws UserManagerException;
124
125    /**
126     * Update a User.
127     *
128     * @param user the user to update.
129     * @return the user that was just updated.
130     * @throws UserNotFoundException if the user was not found to update.
131     */
132    User updateUser( User user )
133        throws UserNotFoundException, UserManagerException;
134
135    /**
136     * Find a User using a User name.
137     *
138     * @param username the username to find.
139     * @return the user.
140     * @throws UserNotFoundException if the user was not found.
141     */
142    User findUser( String username )
143        throws UserNotFoundException, UserManagerException;
144
145    /**
146     * Find a User using a User name.
147     *
148     * @param username the username to find.
149     * @param useCache to use or not caching
150     * @return the user.
151     * @since 2.2
152     * @throws UserNotFoundException if the user was not found.
153     */
154    User findUser( String username, boolean useCache )
155        throws UserNotFoundException, UserManagerException;
156
157    /**
158     * Get the guest user.
159     *
160     * @return the guest user.
161     */
162    User getGuestUser()
163        throws UserNotFoundException, UserManagerException;
164
165    List<? extends User> findUsersByUsernameKey( String usernameKey, boolean orderAscending )
166        throws UserManagerException;
167
168    List<? extends User> findUsersByFullNameKey( String fullNameKey, boolean orderAscending )
169        throws UserManagerException;
170
171    List<? extends User> findUsersByEmailKey( String emailKey, boolean orderAscending )
172        throws UserManagerException;
173
174    /**
175     * Find users matching properties, ordering and range as specified by the
176     * {@link UserQuery}.
177     *
178     * @param query the query.
179     * @return a List of {@link User} objects.
180     */
181    List<? extends User> findUsersByQuery( UserQuery query )
182        throws UserManagerException;
183
184    /**
185     * true if the user exists, false if it doesn't
186     *
187     * @param principal
188     * @return true, if user exists
189     */
190    boolean userExists( String principal )
191        throws UserManagerException;
192
193    /**
194     * Delete a user using the username.
195     *
196     * @param username the username to look for.
197     * @throws UserNotFoundException the user was not found.
198     */
199    void deleteUser( String username )
200        throws UserNotFoundException, UserManagerException;
201
202    /**
203     * Add a user to the database without checking for consistency or adjusting the password. Should only be used for
204     * re-importing known-good data.
205     *
206     * @param user the user to add
207     */
208    void addUserUnchecked( User user )
209        throws UserManagerException;
210
211    void eraseDatabase();
212
213    User updateUser( User user, boolean passwordChangeRequired )
214        throws UserNotFoundException, UserManagerException;
215
216
217    /**
218     * consumer of user manager can use it to reload various configuration
219     * with the configurable implementation is possible to change dynamically the real implementation used.
220     *
221     * @since 2.1
222     */
223    void initialize();
224
225    /**
226     * @return true if this implementation is a final one and not a wrapper (configurable, cached)
227     * @since 2.1
228     */
229    boolean isFinalImplementation();
230
231    /**
232     * @return a key to be able to customize label in UI
233     * @since 2.1
234     */
235    String getDescriptionKey();
236
237}