UserManager.java 3.49 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
package org.jivesoftware.messenger.user;

import org.jivesoftware.messenger.container.Module;
import org.jivesoftware.messenger.auth.UnauthorizedException;
import java.util.Iterator;

/**
 * Centralized management of users in the Jive system including creating, retrieving, and deleting
 * User objects.<p>
 * <p/>
 * In some cases, you may wish to plug in your own user system implementation. In that case, you
 * should set the Jive property <tt>UserManager.className</tt> with the name of your UserManager
 * class. Your class must have a public, no-argument constructor. The class must also create and
 * return User object implementations as necessary.
 *
 * @author Iain Shigeoka
 * @see User
 */
public interface UserManager extends Module {

    /**
     * Factory method for creating a new User with all required values: a password, and a unique username.
     *
     * @param username the new and unique username for the account.
     * @param password the password for the account as plain text.
     * @param email    The email address to associate with the new account
     * @return a new User.
     * @throws UserAlreadyExistsException    if the username already exists in the system.
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
    public User createUser(String username, String password, String email)
            throws UserAlreadyExistsException, UnauthorizedException, UnsupportedOperationException;

    /**
     * Deletes a user (optional operation).
     *
     * @param user the user to delete.
     * @throws UnauthorizedException         If the caller doesn't have permission to take the given action
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
    public void deleteUser(User user) throws UnauthorizedException, UnsupportedOperationException;

    /**
     * Returns the User specified by username.
     *
     * @param username the username of the user.
     * @return the User that matches <tt>username</tt>.
     * @throws UserNotFoundException if the user does not exist.
     */
    public User getUser(String username) throws UserNotFoundException;

    /**
     * Returns the number of users in the system.
     *
     * @return the total number of users.
     */
    public int getUserCount();

    /**
     * Returns an iterator for all users in the system.
     *
     * @return an Iterator for all users.
     */
    public Iterator users() throws UnauthorizedException;

    /**
     * Returns an iterator for all users starting at <tt>startIndex</tt> with the given number of
     * results. This is useful to support pagination in a GUI where you may only want to display a
     * certain number of results per page. It is possible that the number of results returned will
     * be less than that specified by numResults if numResults is greater than the number of records
     * left in the system to display.
     *
     * @param startIndex the beginning index to start the results at.
     * @param numResults the total number of results to return.
     * @return an Iterator for all users in the specified range.
     */
    public Iterator users(int startIndex, int numResults) throws UnauthorizedException;
}