    001    package org.apache.turbine.om.security;
    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
    022    import java.io.Serializable;
    023    import java.util.Hashtable;
    024
    025    import javax.servlet.http.HttpSessionBindingListener;
    026
    027    /**
    028     * This interface represents functionality that all users of the
    029     * Turbine system require.
    030     *
    031     * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
    032     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    033     * @author <a href="mailto:jon@collab.net">Jon S. Stevens</a>
    034     * @author <a href="mailto:cberry@gluecode.com">Craig D. Berry</a>
    035     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    036     * @version $Id: User.java 1073174 2011-02-21 22:18:45Z tv $
    037     */
    038    public interface User
    039        extends HttpSessionBindingListener, Serializable, SecurityEntity
    040    {
    041        /** The 'perm storage' key name for the first name. */
    042        String FIRST_NAME = "FIRST_NAME";
    043
    044        /** The 'perm storage' key name for the last name. */
    045        String LAST_NAME = "LAST_NAME";
    046
    047        /** The 'perm storage' key name for the last_login field. */
    048        String LAST_LOGIN = "LAST_LOGIN";
    049
    050        /** The 'perm storage' key name for the password field. */
    051        String PASSWORD = "PASSWORD_VALUE";
    052
    053        /** The 'perm storage' key name for the username field. */
    054        String USERNAME = "LOGIN_NAME";
    055
    056        /** The 'perm storage' key for the confirm_value field. */
    057        String CONFIRM_VALUE = "CONFIRM_VALUE";
    058
    059        /** The 'perm storage' key for the email field. */
    060        String EMAIL = "EMAIL";
    061
    062        /** This is the value that is stored in the database for confirmed users */
    063        String CONFIRM_DATA = "CONFIRMED";
    064
    065        /** The 'perm storage' key name for the access counter. */
    066        String ACCESS_COUNTER = "_access_counter";
    067
    068        /** The 'temp storage' key name for the session access counter */
    069        String SESSION_ACCESS_COUNTER = "_session_access_counter";
    070
    071        /** The 'temp storage' key name for the 'has logged in' flag */
    072        String HAS_LOGGED_IN = "_has_logged_in";
    073
    074        /** The session key for the User object. */
    075        String SESSION_KEY = "turbine.user";
    076
    077        /**
    078         * Gets the access counter for a user from perm storage.
    079         *
    080         * @return The access counter for the user.
    081         */
    082        int getAccessCounter();
    083
    084        /**
    085         * Gets the access counter for a user during a session.
    086         *
    087         * @return The access counter for the user for the session.
    088         */
    089        int getAccessCounterForSession();
    090
    091        /**
    092         * Gets the last access date for this User. This is the last time
    093         * that the user object was referenced.
    094         *
    095         * @return A Java Date with the last access date for the user.
    096         */
    097        java.util.Date getLastAccessDate();
    098
    099        /**
    100         * Gets the create date for this User.  This is the time at which
    101         * the user object was created.
    102         *
    103         * @return A Java Date with the date of creation for the user.
    104         */
    105        java.util.Date getCreateDate();
    106
    107        /**
    108         * Returns the user's last login date.
    109         *
    110         * @return A Java Date with the last login date for the user.
    111         */
    112        java.util.Date getLastLogin();
    113
    114        /**
    115         * Returns the user's password. This method should not be used by
    116         * the application directly, because it's meaning depends upon
    117         * the implementation of UserManager that manages this particular
    118         * user object. Some implementations will use this attribute for
    119         * storing a password encrypted in some way, other will not use
    120         * it at all, when user entered password is presented to some external
    121         * authority (like NT domain controller) to validate it.
    122         * See also {@link org.apache.turbine.services.security.UserManager#authenticate(User,String)}.
    123         *
    124         * @return A String with the password for the user.
    125         */
    126        String getPassword();
    127
    128        /**
    129         * Get an object from permanent storage.
    130         *
    131         * @param name The object's name.
    132         * @return An Object with the given name.
    133         */
    134        Object getPerm(String name);
    135
    136        /**
    137         * Get an object from permanent storage; return default if value
    138         * is null.
    139         *
    140         * @param name The object's name.
    141         * @param def A default value to return.
    142         * @return An Object with the given name.
    143         */
    144        Object getPerm(String name, Object def);
    145
    146        /**
    147         * This should only be used in the case where we want to save the
    148         * data to the database.
    149         *
    150         * @return A Hashtable.
    151         */
    152        Hashtable<String, Object> getPermStorage();
    153
    154        /**
    155         * This should only be used in the case where we want to save the
    156         * data to the database.
    157         *
    158         * @return A Hashtable.
    159         */
    160        Hashtable<String, Object> getTempStorage();
    161
    162        /**
    163         * Get an object from temporary storage.
    164         *
    165         * @param name The object's name.
    166         * @return An Object with the given name.
    167         */
    168        Object getTemp(String name);
    169
    170        /**
    171         * Get an object from temporary storage; return default if value
    172         * is null.
    173         *
    174         * @param name The object's name.
    175         * @param def A default value to return.
    176         * @return An Object with the given name.
    177         */
    178        Object getTemp(String name, Object def);
    179
    180        /**
    181         * Returns the first name for this user.
    182         *
    183         * @return A String with the user's first name.
    184         */
    185
    186        String getFirstName();
    187
    188        /**
    189         * Returns the last name for this user.
    190         *
    191         * @return A String with the user's last name.
    192         */
    193        String getLastName();
    194
    195        /**
    196         * Returns the email address for this user.
    197         *
    198         * @return A String with the user's email address.
    199         */
    200        String getEmail();
    201
    202        /**
    203         * This sets whether or not someone has logged in.  hasLoggedIn()
    204         * returns this value.
    205         *
    206         * @param value Whether someone has logged in or not.
    207         */
    208        void setHasLoggedIn(Boolean value);
    209
    210        /**
    211         * The user is considered logged in if they have not timed out.
    212         *
    213         * @return True if the user has logged in.
    214         */
    215        boolean hasLoggedIn();
    216
    217        /**
    218         * Increments the permanent hit counter for the user.
    219         */
    220        void incrementAccessCounter();
    221
    222        /**
    223         * Increments the session hit counter for the user.
    224         */
    225        void incrementAccessCounterForSession();
    226
    227        /**
    228         * Remove an object from temporary storage and return the object.
    229         *
    230         * @param name The name of the object to remove.
    231         * @return An Object.
    232         */
    233        Object removeTemp(String name);
    234
    235        /**
    236         * Sets the access counter for a user, saved in perm storage.
    237         *
    238         * @param cnt The new count.
    239         */
    240        void setAccessCounter(int cnt);
    241
    242        /**
    243         * Sets the session access counter for a user, saved in temp
    244         * storage.
    245         *
    246         * @param cnt The new count.
    247         */
    248        void setAccessCounterForSession(int cnt);
    249
    250        /**
    251         * Sets the last access date for this User. This is the last time
    252         * that the user object was referenced.
    253         */
    254        void setLastAccessDate();
    255
    256        /**
    257         * Set last login date/time.
    258         *
    259         * @param lastLogin The last login date.
    260         */
    261        void setLastLogin(java.util.Date lastLogin);
    262
    263        /**
    264         * Set password. Application should not use this method
    265         * directly, see {@link #getPassword()}.
    266         * See also {@link org.apache.turbine.services.security.UserManager#changePassword(User,String,String)}.
    267         *
    268         * @param password The new password.
    269         */
    270
    271        void setPassword(String password);
    272
    273        /**
    274         * Put an object into permanent storage.
    275         *
    276         * @param name The object's name.
    277         * @param value The object.
    278         */
    279        void setPerm(String name,
    280                     Object value);
    281
    282        /**
    283         * This should only be used in the case where we want to save the
    284         * data to the database.
    285         *
    286         * @param storage A Hashtable.
    287         */
    288        void setPermStorage(Hashtable<String, Object> storage);
    289
    290        /**
    291         * This should only be used in the case where we want to save the
    292         * data to the database.
    293         *
    294         * @param storage A Hashtable.
    295         */
    296        void setTempStorage(Hashtable<String, Object> storage);
    297
    298        /**
    299         * Put an object into temporary storage.
    300         *
    301         * @param name The object's name.
    302         * @param value The object.
    303         */
    304        void setTemp(String name, Object value);
    305
    306        /**
    307         * Sets the first name for this user.
    308         *
    309         * @param firstName User's first name.
    310         */
    311        void setFirstName(String firstName);
    312
    313        /**
    314         * Sets the last name for this user.
    315         *
    316         * @param lastName User's last name.
    317         */
    318        void setLastName(String lastName);
    319
    320        /**
    321         * Sets the creation date for this user.
    322         *
    323         * @param date Creation date
    324         */
    325        void setCreateDate(java.util.Date date);
    326
    327        /**
    328         * Sets the email address.
    329         *
    330         * @param address The email address.
    331         */
    332        void setEmail(String address);
    333
    334        /**
    335         * This method reports whether or not the user has been confirmed
    336         * in the system by checking the TurbineUserPeer.CONFIRM_VALUE
    337         * column to see if it is equal to CONFIRM_DATA.
    338         *
    339         * @return True if the user has been confirmed.
    340         */
    341        boolean isConfirmed();
    342
    343        /**
    344         * Sets the confirmation value.
    345         *
    346         * @param value The confirmation key value.
    347         */
    348        void setConfirmed(String value);
    349
    350        /**
    351         * Gets the confirmation value.
    352         *
    353         * @return The confirmed value
    354         */
    355        String getConfirmed();
    356
    357        /**
    358         * Updates the last login date in the database.
    359         *
    360         * @exception Exception A generic exception.
    361         */
    362        void updateLastLogin()
    363            throws Exception;
    364    }