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}