code: public User login (String username, Password password, boolean persist,
                         HttpServletRequest req, HttpServletResponse rsp, Authenticator auth)
          throws PersistenceException, AuthenticationFailedException
      {
          // load up the requested user
          User user = _repository.loadUser(username);
          if (user == null) {
              throw new NoSuchUserException("error.no_such_user");
          }
  
          // run the user through the authentication gamut
          auth.authenticateUser(user, username, password);
  
          // give them the necessary cookies and business
          effectLogin(user, persist ? PERSIST_EXPIRE_DAYS : NON_PERSIST_EXPIRE_DAYS, req, rsp);
  
          return user;
      }
docs: Attempts to authenticate the requester and initiate an authenticated session for them. An
  authenticated session involves their receiving a cookie that proves them to be authenticated
  and an entry in the session database being created that maps their information to their
  userid. If this call completes, the session was established and the proper cookies were set
  in the supplied response object. If invalid authentication information is provided or some
  other error occurs, an exception will be thrown.
  
  @param username The username supplied by the user.
  @param password The password supplied by the user.
  @param persist If true, the cookie will expire in one month, if false, the cookie will
  expire at the end of the user's browser session.
  @param req The request via which the login page was loaded.
  @param rsp The response in which the cookie is to be set.
  @param auth The authenticator used to check whether the user should be authenticated.
  
  @return the user object of the authenticated user.