View Javadoc

    1   package org.apache.turbine.services.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.util.List;
    23
    24  import org.apache.commons.configuration.Configuration;
    25  import org.apache.fulcrum.security.acl.AccessControlList;
    26  import org.apache.fulcrum.security.util.DataBackendException;
    27  import org.apache.fulcrum.security.util.EntityExistsException;
    28  import org.apache.fulcrum.security.util.PasswordMismatchException;
    29  import org.apache.fulcrum.security.util.UnknownEntityException;
    30  import org.apache.turbine.om.security.User;
    31  import org.apache.turbine.services.InitializationException;
    32
    33  /**
    34   * An UserManager performs {@link org.apache.turbine.om.security.User} objects
    35   * related tasks on behalf of the
    36   * {@link org.apache.turbine.services.security.DefaultSecurityService}.
    37   *
    38   * The responsibilities of this class include loading data of an user from the
    39   * storage and putting them into the
    40   * {@link org.apache.turbine.om.security.User} objects, saving those data
    41   * to the permanent storage, and authenticating users.
    42   *
    43   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
    44   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    45   * @version $Id: UserManager.java 1706239 2015-10-01 13:18:35Z tv $
    46   */
    47  public interface UserManager
    48  {
    49      /**
    50       * Initializes the UserManager
    51       *
    52       * @param conf A Configuration object to init this Manager
    53       *
    54       * @throws InitializationException When something went wrong.
    55       */
    56      void init(Configuration conf)
    57          throws InitializationException;
    58
    59      /**
    60       * Check whether a specified user's account exists.
    61       *
    62       * The login name is used for looking up the account.
    63       *
    64       * @param user The user to be checked.
    65       * @return true if the specified account exists
    66       * @throws DataBackendException if there was an error accessing the data
    67       *         backend.
    68       */
    69      boolean accountExists(User user)
    70              throws DataBackendException;
    71
    72      /**
    73       * Check whether a specified user's account exists.
    74       *
    75       * The login name is used for looking up the account.
    76       *
    77       * @param userName The name of the user to be checked.
    78       * @return true if the specified account exists
    79       * @throws DataBackendException if there was an error accessing the data
    80       *         backend.
    81       */
    82      boolean accountExists(String userName)
    83              throws DataBackendException;
    84
    85      /**
    86       * Retrieve a user from persistent storage using username as the
    87       * key.
    88       *
    89       * @param username the name of the user.
    90       * @return an User object.
    91       * @throws UnknownEntityException if the user's record does not
    92       *         exist in the database.
    93       * @throws DataBackendException if there is a problem accessing the
    94       *         storage.
    95       */
    96      <U extends User> U retrieve(String username)
    97              throws UnknownEntityException, DataBackendException;
    98
    99      /**
    100      * Retrieve a list of users that meet the specified criteria.
    101      *
    102      * As the keys for the criteria, you should use the constants that
    103      * are defined in {@link User} interface, plus the names
    104      * of the custom attributes you added to your user representation
    105      * in the data storage. Use verbatim names of the attributes -
    106      * without table name prefix in case of DB implementation.
    107      *
    108      * @param criteria The criteria of selection.
    109      * @return a List of users meeting the criteria.
    110      * @throws DataBackendException if there is a problem accessing the
    111      *         storage.
    112      */
    113     List<? extends User> retrieveList(Object criteria)
    114         throws DataBackendException;
    115
    116     /**
    117      * Retrieve a user from persistent storage using username as the
    118      * key, and authenticate the user. The implementation may chose
    119      * to authenticate to the server as the user whose data is being
    120      * retrieved.
    121      *
    122      * @param username the name of the user.
    123      * @param password the user supplied password.
    124      * @return an User object.
    125      * @throws PasswordMismatchException if the supplied password was incorrect.
    126      * @throws UnknownEntityException if the user's record does not
    127      *         exist in the database.
    128      * @throws DataBackendException if there is a problem accessing the storage.
    129      */
    130     <U extends User> U retrieve(String username, String password)
    131             throws PasswordMismatchException, UnknownEntityException,
    132             DataBackendException;
    133
    134     /**
    135      * Save an User object to persistent storage. User's record is
    136      * required to exist in the storage.
    137      *
    138      * @param user an User object to store.
    139      * @throws UnknownEntityException if the user's record does not
    140      *         exist in the database.
    141      * @throws DataBackendException if there is a problem accessing the storage.
    142      */
    143     void store(User user)
    144             throws UnknownEntityException, DataBackendException;
    145
    146     /**
    147      * Saves User data when the session is unbound. The user account is required
    148      * to exist in the storage.
    149      *
    150      * LastLogin, AccessCounter, persistent pull tools, and any data stored
    151      * in the permData hashtable that is not mapped to a column will be saved.
    152      *
    153      * @param user the user in the session
    154      *
    155      * @exception UnknownEntityException if the user's account does not
    156      *            exist in the database.
    157      * @exception DataBackendException if there is a problem accessing the
    158      *            storage.
    159      */
    160     void saveOnSessionUnbind(User user)
    161             throws UnknownEntityException, DataBackendException;
    162
    163     /**
    164      * Authenticate an User with the specified password. If authentication
    165      * is successful the method returns nothing. If there are any problems,
    166      * exception was thrown.
    167      *
    168      * @param user an User object to authenticate.
    169      * @param password the user supplied password.
    170      * @throws PasswordMismatchException if the supplied password was incorrect.
    171      * @throws UnknownEntityException if the user's record does not
    172      *         exist in the database.
    173      * @throws DataBackendException if there is a problem accessing the storage.
    174      */
    175     void authenticate(User user, String password)
    176             throws PasswordMismatchException, UnknownEntityException,
    177             DataBackendException;
    178
    179     /**
    180      * Creates new user account with specified attributes.
    181      *
    182      * @param user the object describing account to be created.
    183      * @param initialPassword password for the new user
    184      * @throws DataBackendException if there was an error accessing the data
    185      *         backend.
    186      * @throws EntityExistsException if the user account already exists.
    187      */
    188     void createAccount(User user, String initialPassword)
    189             throws EntityExistsException, DataBackendException;
    190
    191     /**
    192      * Removes an user account from the system.
    193      *
    194      * @param user the object describing the account to be removed.
    195      * @throws DataBackendException if there was an error accessing the data
    196      *         backend.
    197      * @throws UnknownEntityException if the user account is not present.
    198      */
    199     void removeAccount(User user)
    200             throws UnknownEntityException, DataBackendException;
    201
    202     /**
    203      * Change the password for an User.
    204      *
    205      * @param user an User to change password for.
    206      * @param oldPassword the current password suplied by the user.
    207      * @param newPassword the current password requested by the user.
    208      * @throws PasswordMismatchException if the supplied password was incorrect.
    209      * @throws UnknownEntityException if the user's record does not
    210      *         exist in the database.
    211      * @throws DataBackendException if there is a problem accessing the storage.
    212      */
    213     void changePassword(User user, String oldPassword,
    214                         String newPassword)
    215             throws PasswordMismatchException, UnknownEntityException,
    216             DataBackendException;
    217
    218     /**
    219      * Forcibly sets new password for an User.
    220      *
    221      * This is supposed by the administrator to change the forgotten or
    222      * compromised passwords. Certain implementatations of this feature
    223      * would require administrative level access to the authenticating
    224      * server / program.
    225      *
    226      * @param user an User to change password for.
    227      * @param password the new password.
    228      * @throws UnknownEntityException if the user's record does not
    229      *            exist in the database.
    230      * @throws DataBackendException if there is a problem accessing the storage.
    231      */
    232     void forcePassword(User user, String password)
    233             throws UnknownEntityException, DataBackendException;
    234
    235     /**
    236      * Constructs an User object to represent an anonymous user of the
    237      * application.
    238      *
    239      * @return An anonymous Turbine User.
    240      * @throws UnknownEntityException
    241      *             if the anonymous User object couldn't be constructed.
    242      */
    243     <T extends User> T getAnonymousUser() throws UnknownEntityException;
    244
    245     /**
    246      * Checks whether a passed user object matches the anonymous user pattern
    247      * according to the configured user manager
    248      *
    249      * @param u a user object
    250      *
    251      * @return True if this is an anonymous user
    252      *
    253      */
    254     boolean isAnonymousUser(User u);
    255
    256     /**
    257      * Construct a blank User object.
    258      *
    259      * This method calls getUserClass, and then creates a new object using the
    260      * default constructor.
    261      *
    262      * @return an object implementing User interface.
    263      * @throws DataBackendException
    264      *             if the object could not be instantiated.
    265      */
    266     <T extends User> T getUserInstance() throws DataBackendException;
    267
    268     /**
    269      * Construct a blank User object.
    270      *
    271      * This method calls getUserClass, and then creates a new object using the
    272      * default constructor.
    273      *
    274      * @param userName
    275      *            The name of the user.
    276      *
    277      * @return an object implementing User interface.
    278      * @throws DataBackendException
    279      *             if the object could not be instantiated.
    280      */
    281     <T extends User> T getUserInstance(String userName) throws DataBackendException;
    282
    283     /**
    284      * Return a Class object representing the system's chosen implementation of
    285      * of ACL interface for the given user
    286      *
    287      * @param user the user
    288      * @return systems's chosen implementation of ACL interface.
    289      * @throws UnknownEntityException
    290      *             if the implementation of ACL interface could not be
    291      *             determined, or does not exist.
    292      */
    293     <T extends AccessControlList> T getACL(User user) throws UnknownEntityException;
    294 }