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}