com.jivesoftware.base
Interface UserManager

All Superinterfaces:

JiveManager

All Known Subinterfaces:

IntrospectiveUserManager

public interface UserManager
extends JiveManager

Centralized management of users in the Jive system including creating, retrieving, and deleting User objects.

Instructions for those that wish to implement this interface to provide a custom implementation appear in red. If you wish to use a custom implementation, you must set the Jive property UserManager.className 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.

See Also:

User

Method Summary

boolean	authenticate(java.lang.String username, java.lang.String password)
User	createUser(java.lang.String username, java.lang.String password, java.lang.String email) Factory method for creating a new User with all required values: a password, email address, and unique username.
User	createUser(java.lang.String username, java.lang.String password, java.lang.String name, java.lang.String email, boolean nameVisible, boolean emailVisible, java.util.Map<java.lang.String,java.lang.String> properties) Factory method for creating a new User with all required AND optional values.
void	deleteUser(User user) Deletes a user.
int	getEnabledUserCount()
User	getUser(long userID) Returns a User specified by their ID.
User	getUser(java.lang.String username) Returns the User specified by username.
int	getUserCount() Returns the number of users in the system.
User	getUserFromEmailAddress(java.lang.String email) Returns a user object corresponding to the email address given.
long	getUserID(java.lang.String username) Returns the userID specified by the username.
java.lang.Iterable<User>	users() Returns an iterator for all users in the system.
java.lang.Iterable<User>	users(int startIndex, int numResults) Returns an iterator for all users starting at startIndex with the given number of results.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy, initialize

Method Detail

createUser

User createUser(java.lang.String username,
                java.lang.String password,
                java.lang.String email)
                throws UserAlreadyExistsException

Factory method for creating a new User with all required values: a password, email address, and unique username.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Parameters:

username - the new and unique username for the account.

password - the password for the account as plain text.

email - the email address for the account.

Returns:

a new User.

Throws:

UserAlreadyExistsException - if the username already exists in the system.

createUser

User createUser(java.lang.String username,
                java.lang.String password,
                java.lang.String name,
                java.lang.String email,
                boolean nameVisible,
                boolean emailVisible,
                java.util.Map<java.lang.String,java.lang.String> properties)
                throws UserAlreadyExistsException

Factory method for creating a new User with all required AND optional values.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Parameters:

username - the new and unique username for the account.

password - the password for the account as plain text.

name - the name for the account.

email - the email address for the account.

nameVisible - true if the user's name should be visible to others.

emailVisible - true if the user's email address should be visible to others.

properties - the user's extended properties.

Returns:

a new User.

Throws:

UserAlreadyExistsException - if the username already exists in the system.

getUser

User getUser(long userID)
             throws UserNotFoundException

Returns a User specified by their ID.

Because this method will be called often by other parts of the API, a cache of User objects should be used. UserManagerFactory.userCache can be used for this purpose. The algorithm should be:

1. Look for the user object in cache with new Long(userID) as the key.
2. If the object is found in cache, return it.
3. If the object is not found in cache, load the object from the back-end store then add it to cache with new Long(userID) as the key. Finally, return the user object.

Parameters:

userID - the id of the User to lookup.

Returns:

the User specified by userID.

Throws:

UserNotFoundException - if the user does not exist.

getUser

User getUser(java.lang.String username)
             throws UserNotFoundException

Returns the User specified by username.

The method should typically be implemented as:
return getUser(getUserID(username));

Parameters:

username - the username of the user.

Returns:

the User that matches username.

Throws:

UserNotFoundException - if the user does not exist.

getUserID

long getUserID(java.lang.String username)
               throws UserNotFoundException

Returns the userID specified by the username. This method is only useful in specialized cases, as its generally easier to call getUser(username).getID() instead of this method.

Because this method will be called often by other parts of the API, a cache should be used that maps usernames to userIDs. UserManagerFactory.userIDCache can be used for this purpose. The algorithm should be:

1. Look for the username to userID mapping in cache.
2. If the mapping is found, return the userID.
3. If the mapping is not found in cache, load the user object from the back-end store to figure out the correct userID, add the mapping to cache, then return the userID.

Parameters:

username - the username of the usedr.

Returns:

the userID that matches username.

Throws:

UserNotFoundException - if the user does not exist.

deleteUser

void deleteUser(User user)
                throws UnauthorizedException

Deletes a user. To maintain data consistency, deleting a user will cause all data created by that user to be deleted. An alternative to deleting a user (and thus deleting all of their content) is to ban the user from logging in.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Parameters:

user - the user to delete.

Throws:

UnauthorizedException - if not an administrator

getUserCount

int getUserCount()

Returns the number of users in the system.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Returns:

the total number of users.

users

java.lang.Iterable<User> users()

Returns an iterator for all users in the system.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Returns:

an Iterator for all users.

users

java.lang.Iterable<User> users(int startIndex,
                               int numResults)

Returns an iterator for all users starting at startIndex 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.

If your back-end user store does not support this operation, throw an UnsupportedOperationException.

Parameters:

startIndex - the beginning index to start the results at.

numResults - the total number of results to return.

Returns:

an Iterator for all users in the specified range.

getUserFromEmailAddress

User getUserFromEmailAddress(java.lang.String email)

Returns a user object corresponding to the email address given. If no user is found which corresponds to the given email address null should be returned. If more than one user corresponds to the given email address it is up to the implementation to decide what to do (i.e. return one of the users or return null).

Parameters:

email - the email address to get a user object for.

Returns:

a user object corresponding to the given email address.

getEnabledUserCount

int getEnabledUserCount()

authenticate

boolean authenticate(java.lang.String username,
                     java.lang.String password)