001/* 002 Licensed to the Apache Software Foundation (ASF) under one 003 or more contributor license agreements. See the NOTICE file 004 distributed with this work for additional information 005 regarding copyright ownership. The ASF licenses this file 006 to you under the Apache License, Version 2.0 (the 007 "License"); you may not use this file except in compliance 008 with the License. You may obtain a copy of the License at 009 010 http://www.apache.org/licenses/LICENSE-2.0 011 012 Unless required by applicable law or agreed to in writing, 013 software distributed under the License is distributed on an 014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 KIND, either express or implied. See the License for the 016 specific language governing permissions and limitations 017 under the License. 018 */ 019package org.apache.wiki.auth.user; 020 021import java.io.Serializable; 022import java.util.ArrayList; 023import java.util.Date; 024import java.util.List; 025import java.util.Map; 026 027/** 028 * Class for representing wiki user information, such as the login name, full 029 * name, wiki name, and e-mail address. Note that since 2.6 the wiki name is 030 * required to be automatically computed from the full name. 031 * As of 2.8, user profiles can store custom key/value String/Serializable attributes, and store 032 * a unique ID. Locks are checked by {@link org.apache.wiki.auth.AuthenticationManager}; 033 * if a profile is locked, the user cannot log with that profile. 034 * @since 2.3 035 */ 036public interface UserProfile extends Serializable 037{ 038 /** 039 * IP 040 */ 041 String ATTR_PREVIOUS_LOGIN_IP = "PREVIOUS_LOGIN_IP"; 042 /** 043 * LONG time in ms since epoch 044 */ 045 String ATTR_PREVIOUS_LOGIN_TIMESTAMP = "PREVIOUS_LOGIN_TIMESTAMP"; 046 /** 047 * IP 048 */ 049 String ATTR_CURRENT_LOGIN_IP = "CURRENT_LOGIN_IP"; 050 /** 051 * LONG time in ms since epoch 052 */ 053 String ATTR_CURRENT_LOGIN_TIMESTAMP = "CURRENT_LOGIN_TIMESTAMP"; 054 055 /** 056 * Returns the attributes associated with this profile as a Map of key/value pairs. 057 * The Map should generally be a "live" Map; changes to the keys or values will be reflected 058 * in the UserProfile. 059 * @return the attributes 060 */ 061 Map<String,Serializable> getAttributes(); 062 063 /** 064 * Returns the creation date. 065 * @return the creation date 066 */ 067 Date getCreated(); 068 069 /** 070 * Returns the user's e-mail address. 071 * @return the e-mail address 072 */ 073 String getEmail(); 074 075 /** 076 * Returns the user's full name. 077 * @return the full name 078 */ 079 String getFullname(); 080 081 /** 082 * Returns the last-modified date. 083 * @return the date and time of last modification 084 */ 085 Date getLastModified(); 086 087 /** 088 * Returns the date/time of expiration of the profile's lock, if it has been 089 * previously locked via {@link #setLockExpiry(Date)} and the lock is 090 * still active. If the profile is unlocked, this method returns <code>null</code>. 091 * Note that calling this method after the expiration date, <em>even if had previously 092 * been set explicitly by {@link #setLockExpiry(Date)}</em>, will always return 093 * <code>null</null>. 094 * 095 * @return the lock expiration date 096 */ 097 Date getLockExpiry(); 098 099 /** 100 * Returns the user's login name. 101 * @return the login name 102 */ 103 String getLoginName(); 104 105 /** 106 * Returns the date the password was last changed, or <code>null</code> if it is not known, which is the case for the profiles that 107 * were saved before the date was recorded, or if the {@link UserDatabase} does not record it. The date is set by the 108 * {@link UserDatabase} when a profile is saved with a password that is different from the stored one. 109 * 110 * @return the date of the last password change 111 * @since 3.0.1 112 */ 113 default Date getPasswordChanged() { 114 return null; 115 } 116 117 /** 118 * Sets the date the password was last changed. Saving the profile with a different password sets it to the current time, which 119 * replaces the value given here. 120 * 121 * @param date the date of the last password change, or <code>null</code> if it is not known 122 * @since 3.0.1 123 */ 124 default void setPasswordChanged( final Date date ) { 125 // implementations that keep the date override this 126 } 127 128 /** 129 * Returns the user password for use with custom authentication. Note that 130 * the password field is not meaningful for container authentication; the 131 * user's private credentials are generally stored elsewhere. While it 132 * depends on the {@link UserDatabase}implementation, in most cases the 133 * value returned by this method will be a password hash, not the password 134 * itself. 135 * @return the password 136 */ 137 String getPassword(); 138 139 /** 140 * Returns the unique identifier for the user profile. If not previously 141 * set, the value will be <code>null</code>. 142 * @return the unique ID. 143 */ 144 String getUid(); 145 146 /** 147 * Returns the user's wiki name, based on the full name with all 148 * whitespace removed. 149 * @return the wiki name. 150 */ 151 String getWikiName(); 152 153 /** 154 * Returns 155 * <code>true</code> if the profile is currently locked (disabled); <code>false</code> otherwise. 156 * By default, profiles are created unlocked. Strictly speaking, calling this method is equivalent to calling {@link #getLockExpiry()} 157 * and, if it returns a non-<code>null</code> value, checking if the date returned is later than the current time. 158 * @return the result 159 */ 160 boolean isLocked(); 161 162 /** 163 * Returns <code>true</code> if the profile has never been 164 * saved before. Implementing classes might check the 165 * last modified date, for example, to determine this. 166 * @return whether the profile is new 167 */ 168 boolean isNew(); 169 170 /** 171 * Sets the created date. 172 * @param date the creation date 173 */ 174 void setCreated( Date date ); 175 176 /** 177 * Sets the user's e-mail address. 178 * @param email the e-mail address 179 */ 180 void setEmail( String email ); 181 182 /** 183 * Sets the user's full name. For example, "Janne Jalkanen." 184 * @param arg the full name 185 */ 186 void setFullname( String arg ); 187 188 /** 189 * Sets the last-modified date 190 * @param date the last-modified date 191 */ 192 void setLastModified( Date date ); 193 194 /** 195 * Locks the profile until a specified lock expiration date. 196 * 197 * @param expiry the date the lock expires; setting this value to <code>null</code> 198 * will cause the lock to be cleared. 199 */ 200 void setLockExpiry( Date expiry ); 201 202 /** 203 * Sets the name by which the user logs in. The login name is used as the 204 * username for custom authentication (see 205 * {@link org.apache.wiki.auth.AuthenticationManager#login(org.apache.wiki.api.core.Session, jakarta.servlet.http.HttpServletRequest, String, String)}, 206 * {@link org.apache.wiki.auth.login.UserDatabaseLoginModule}). The login 207 * name is typically a short name ("jannej"). In contrast, the wiki name is 208 * typically of type FirstnameLastName ("JanneJalkanen"). 209 * @param name the login name 210 */ 211 void setLoginName( String name ); 212 213 /** 214 * Sets the user's password for use with custom authentication. It is 215 * <em>not</em> the responsibility of implementing classes to hash the 216 * password; that responsibility is borne by the UserDatabase implementation 217 * during save operations (see {@link UserDatabase#save(UserProfile)}). 218 * Note that the password field is not meaningful for container 219 * authentication; the user's private credentials are generally stored 220 * elsewhere. 221 * @param arg the password 222 */ 223 void setPassword( String arg ); 224 225 /** 226 * Sets the unique identifier for the user profile. Note that UserDatabase implementations 227 * are required <em>not</em> to change the unique identifier after the initial save. 228 * @param uid the unique identifier to set 229 */ 230 void setUid( String uid ); 231 232 /** 233 * Returns a string representation of this user profile. 234 * @return the string 235 */ 236 @Override 237 String toString(); 238 239 /** 240 * List of recently used passwords in hashed format. may be empty 241 * @since 3.0.0 242 * @return non null list 243 */ 244 default List<String> getPreviousHashedCredentials() { 245 return new ArrayList<>(); 246 } 247}