    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 user password for use with custom authentication. Note that
    107     * the password field is not meaningful for container authentication; the
    108     * user's private credentials are generally stored elsewhere. While it
    109     * depends on the {@link UserDatabase}implementation, in most cases the
    110     * value returned by this method will be a password hash, not the password
    111     * itself.
    112     * @return the password
    113     */
    114    String getPassword();
    115
    116    /**
    117     * Returns the unique identifier for the user profile. If not previously
    118     * set, the value will be <code>null</code>.
    119     * @return the unique ID.
    120     */
    121    String getUid();
    122
    123    /**
    124     * Returns the user's wiki name, based on the full name with all
    125     * whitespace removed.
    126     * @return the wiki name.
    127     */
    128    String getWikiName();
    129
    130    /**
    131     * Returns
    132     * <code>true</code> if the profile is currently locked (disabled); <code>false</code> otherwise.
    133     * By default, profiles are created unlocked. Strictly speaking, calling this method is equivalent to calling {@link #getLockExpiry()}
    134     * and, if it returns a non-<code>null</code> value, checking if the date returned is later than the current time.
    135     * @return the result
    136     */
    137    boolean isLocked();
    138
    139    /**
    140     * Returns <code>true</code> if the profile has never been
    141     * saved before. Implementing classes might check the
    142     * last modified date, for example, to determine this.
    143     * @return whether the profile is new
    144     */
    145    boolean isNew();
    146
    147    /**
    148     * Sets the created date.
    149     * @param date the creation date
    150     */
    151    void setCreated( Date date );
    152
    153    /**
    154     * Sets the user's e-mail address.
    155     * @param email the e-mail address
    156     */
    157    void setEmail( String email );
    158
    159    /**
    160     * Sets the user's full name. For example, "Janne Jalkanen."
    161     * @param arg the full name
    162     */
    163    void setFullname( String arg );
    164
    165    /**
    166     * Sets the last-modified date
    167     * @param date the last-modified date
    168     */
    169    void setLastModified( Date date );
    170
    171    /**
    172     * Locks the profile until a specified lock expiration date.
    173     *
    174     * @param expiry the date the lock expires; setting this value to <code>null</code>
    175     * will cause the lock to be cleared.
    176     */
    177    void setLockExpiry( Date expiry );
    178
    179    /**
    180     * Sets the name by which the user logs in. The login name is used as the
    181     * username for custom authentication (see
    182     * {@link org.apache.wiki.auth.AuthenticationManager#login(org.apache.wiki.api.core.Session, jakarta.servlet.http.HttpServletRequest, String, String)},
    183     * {@link org.apache.wiki.auth.login.UserDatabaseLoginModule}). The login
    184     * name is typically a short name ("jannej"). In contrast, the wiki name is
    185     * typically of type FirstnameLastName ("JanneJalkanen").
    186     * @param name the login name
    187     */
    188    void setLoginName( String name );
    189
    190    /**
    191     * Sets the user's password for use with custom authentication. It is
    192     * <em>not</em> the responsibility of implementing classes to hash the
    193     * password; that responsibility is borne by the UserDatabase implementation
    194     * during save operations (see {@link UserDatabase#save(UserProfile)}).
    195     * Note that the password field is not meaningful for container
    196     * authentication; the user's private credentials are generally stored
    197     * elsewhere.
    198     * @param arg the password
    199     */
    200    void setPassword( String arg );
    201
    202    /**
    203     * Sets the unique identifier for the user profile. Note that UserDatabase implementations
    204     * are required <em>not</em> to change the unique identifier after the initial save.
    205     * @param uid the unique identifier to set
    206     */
    207    void setUid( String uid );
    208
    209    /**
    210     * Returns a string representation of this user profile.
    211     * @return the string
    212     */
    213    @Override
    214    String toString();
    215
    216    /**
    217     * List of recently used passwords in hashed format. may be empty
    218     * @since 3.0.0
    219     * @return non null list
    220     */
    221    default List<String> getPreviousHashedCredentials() {
    222        return new ArrayList<>();
    223    }
    224}