View Javadoc

    1   package org.apache.turbine.om.security;
    2
    3   /*
    4    * Licensed to the Apache Software Foundation (ASF) under one
    5    * or more contributor license agreements.  See the NOTICE file
    6    * distributed with this work for additional information
    7    * regarding copyright ownership.  The ASF licenses this file
    8    * to you under the Apache License, Version 2.0 (the
    9    * "License"); you may not use this file except in compliance
    10   * with the License.  You may obtain a copy of the License at
    11   *
    12   *   http://www.apache.org/licenses/LICENSE-2.0
    13   *
    14   * Unless required by applicable law or agreed to in writing,
    15   * software distributed under the License is distributed on an
    16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    17   * KIND, either express or implied.  See the License for the
    18   * specific language governing permissions and limitations
    19   * under the License.
    20   */
    21
    22  import java.io.Serializable;
    23  import java.util.Hashtable;
    24
    25  import javax.servlet.http.HttpSessionBindingListener;
    26
    27  /**
    28   * This interface represents functionality that all users of the
    29   * Turbine system require.
    30   *
    31   * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
    32   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    33   * @author <a href="mailto:jon@collab.net">Jon S. Stevens</a>
    34   * @author <a href="mailto:cberry@gluecode.com">Craig D. Berry</a>
    35   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    36   * @version $Id: User.java 1073174 2011-02-21 22:18:45Z tv $
    37   */
    38  public interface User
    39      extends HttpSessionBindingListener, Serializable, SecurityEntity
    40  {
    41      /** The 'perm storage' key name for the first name. */
    42      String FIRST_NAME = "FIRST_NAME";
    43
    44      /** The 'perm storage' key name for the last name. */
    45      String LAST_NAME = "LAST_NAME";
    46
    47      /** The 'perm storage' key name for the last_login field. */
    48      String LAST_LOGIN = "LAST_LOGIN";
    49
    50      /** The 'perm storage' key name for the password field. */
    51      String PASSWORD = "PASSWORD_VALUE";
    52
    53      /** The 'perm storage' key name for the username field. */
    54      String USERNAME = "LOGIN_NAME";
    55
    56      /** The 'perm storage' key for the confirm_value field. */
    57      String CONFIRM_VALUE = "CONFIRM_VALUE";
    58
    59      /** The 'perm storage' key for the email field. */
    60      String EMAIL = "EMAIL";
    61
    62      /** This is the value that is stored in the database for confirmed users */
    63      String CONFIRM_DATA = "CONFIRMED";
    64
    65      /** The 'perm storage' key name for the access counter. */
    66      String ACCESS_COUNTER = "_access_counter";
    67
    68      /** The 'temp storage' key name for the session access counter */
    69      String SESSION_ACCESS_COUNTER = "_session_access_counter";
    70
    71      /** The 'temp storage' key name for the 'has logged in' flag */
    72      String HAS_LOGGED_IN = "_has_logged_in";
    73
    74      /** The session key for the User object. */
    75      String SESSION_KEY = "turbine.user";
    76
    77      /**
    78       * Gets the access counter for a user from perm storage.
    79       *
    80       * @return The access counter for the user.
    81       */
    82      int getAccessCounter();
    83
    84      /**
    85       * Gets the access counter for a user during a session.
    86       *
    87       * @return The access counter for the user for the session.
    88       */
    89      int getAccessCounterForSession();
    90
    91      /**
    92       * Gets the last access date for this User. This is the last time
    93       * that the user object was referenced.
    94       *
    95       * @return A Java Date with the last access date for the user.
    96       */
    97      java.util.Date getLastAccessDate();
    98
    99      /**
    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 }