users
Class UserManager

java.lang.Object
  users.UserManager

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

UserManagerFilter

public class UserManager
extends Object
implements Serializable

Manages users, their capabilities and their associations to other objects.

The UserManager provides possibilities to manage any number of users. Users can be added, retrieved using their name to identify them, and removed from the system. Additionally, users can be associated to, and disassociated from, any object. Their can be a maximum of one user associated to any given object at any given time.

You can provide a set of default capabilities, that every new user will be provided with.

Since:

v2.0

Author:

Steffen Zschaler

See Also:

User, setDefaultCaps(java.util.Map), SalesPoint, logOn(java.lang.Object, users.User), Serialized Form

Field Summary

protected ListenerHelper

m_lhListeners The list of listeners registered with this UserManager.

Constructor Summary

UserManager()
Create a new UserManager with an empty set of default capabilities, managing direct instances of the User class.

UserManager(Map<String,Capability> mpDefaultCaps)
Create a new UserManager, using a specific set of default capabilities.

UserManager(Map<String,Capability> mpDefaultCaps, UserCreator ucCreator)
Create a new UserManager providing both a set of default capabilities and a User creation factory.

UserManager(UserCreator ucCreator)
Create a new UserManager with an empty set of default capabilities.

Method Summary

void	addUser(User usr) Add a user to the UserManager.
void	addUserDataListener(UserDataListener udl) Add a UserDataListener.
User	createUser(String sName) Create a new user to be managed by this UserManager.
User	deleteUser(String sName) Delete a user from this UserManager.
protected void	fireUserAdded(User usr) Fire a userAdded event to all interested listeners.
protected void	fireUserDeleted(User usr) Fire a userDeleted event to all interested listeners.
User	getCurrentUser(Object o) Retrieve the user currently associated with some Object.
static UserManager	getGlobalUM() Get the global UserManager.
User	getUser(String sName) Retrieve a user by name.
Set<String>	getUserNames() Return all user names registered with this UserManager.
Collection<User>	getUsers() Return all users registered with this UserManager.
User	logOff(Object o) Disassociate the current user from an Object.
User	logOn(Object o, User u) Associate a user with an object.
void	removeUserDataListener(UserDataListener udl) Remove a UserDataListener.
void	setDefaultCapability(Capability cap) Set a capability to be used as a default capability henceforward.
void	setDefaultCaps(Map<String,Capability> mpDefaultCaps) Specify the set of default capabilities to be used when creating new User objects.
static UserManager	setGlobalUM(UserManager umNew) Set a new UserManager to be the global UserManager from now on.
void	setUserCreator(UserCreator ucCreator) Set the factory to be used when creating new User objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_lhListeners

protected ListenerHelper m_lhListeners

The list of listeners registered with this UserManager.

Constructor Detail

UserManager

public UserManager()

Create a new UserManager with an empty set of default capabilities, managing direct instances of the User class.

See Also:

setDefaultCaps(java.util.Map), createUser(java.lang.String)

UserManager

public UserManager(Map<String,Capability> mpDefaultCaps)

Create a new UserManager, using a specific set of default capabilities. This UserManager will manage direct instances of User.

Parameters:

mpDefaultCaps - a map describing the default capabilities any new user should have. The keys of this map should be the name of their associated capability. Specifying null will result in there being no default capabilities.

See Also:

setDefaultCaps(java.util.Map), createUser(java.lang.String), Capability

UserManager

public UserManager(UserCreator ucCreator)

Create a new UserManager with an empty set of default capabilities. This UserManager will create instances of a developer defined subclass of User.

Parameters:

ucCreator - the factory to be used to create new User objects. Specifying null will result in a default implementation being used, which will create direct instances of the User class.

See Also:

setDefaultCaps(java.util.Map), createUser(java.lang.String)

UserManager

public UserManager(Map<String,Capability> mpDefaultCaps,
                   UserCreator ucCreator)

Create a new UserManager providing both a set of default capabilities and a User creation factory.

Parameters:

mpDefaultCaps - a map describing the default capabilities any new user should have. The keys of this map should be the name of their associated capability. Specifying null will result in there being no default capabilities.

ucCreator - the factory to be used to create new User objects. Specifying null will result in a default implementation being used, which will create direct instances of the User class.

See Also:

setDefaultCaps(java.util.Map), Capability, createUser(java.lang.String), User

Method Detail

setUserCreator

public void setUserCreator(UserCreator ucCreator)

Set the factory to be used when creating new User objects.

Parameters:

ucCreator - the factory to be used to create new User objects. Specifying null will result in a default implementation being used, which will create direct instances of the User class.

See Also:

createUser(java.lang.String), User

Override:

Never

setDefaultCaps

public void setDefaultCaps(Map<String,Capability> mpDefaultCaps)

Specify the set of default capabilities to be used when creating new User objects.

Calling this method will not influence the capabilities of users already created.

Parameters:

mpDefaultCaps - a map describing the default capabilities any new user should have. The keys of this map should be the name of their associated capability. Specifying null will result in there being no default capabilities.

See Also:

createUser(java.lang.String), Capability

Override:

Never

setDefaultCapability

public void setDefaultCapability(Capability cap)

Set a capability to be used as a default capability henceforward.

Calling this method will not influence the capabilities of users already created.

If a default capability of the same name as the one given did already exist, it will be replaced by the new capability.

Parameters:

cap - the capability to be set as a default capability.

See Also:

createUser(java.lang.String)

Override:

Never

createUser

public User createUser(String sName)

Create a new user to be managed by this UserManager.

This method uses the defined UserCreator (see setUserCreator(users.UserCreator)) to create the new User object. The new user will later be accessible using its name.

The newly created user will get all the default capabilities defined at the time this method is called.

A userAdded event will be received by any UserDataListener that registered an interest in this UserManager.

Parameters:

sName - the name of the new user. This must be unique, i.e. there must not be a user with the same name already managed by this UserManager.

Returns:

the newly created user.

Throws:

DuplicateUserException - if there already was a user with the given name.

See Also:

setDefaultCaps(java.util.Map), setUserCreator(users.UserCreator), User, UserCreator.createUser(java.lang.String), UserDataListener.userAdded(users.events.UserDataEvent)

Override:

Never Rather than overriding this method, you should provide a new UserCreator.

addUser

public void addUser(User usr)

Add a user to the UserManager.

A userAdded event will be received by any UserDataListener that registered an interest in this UserManager.

Parameters:

usr - the user to be added.

Throws:

DuplicateUserException - if there already is a user of the same name.

See Also:

UserDataListener.userAdded(users.events.UserDataEvent)

Override:

Never

getUser

public User getUser(String sName)

Retrieve a user by name.

If no user with the given name exists, this method will return null.

Parameters:

sName - the name of the user looked for.

Returns:

the user corresponding to the given name, if any. null will be returned if no such user can be found.

See Also:

createUser(java.lang.String)

Override:

Never

getUserNames

public Set<String> getUserNames()

Return all user names registered with this UserManager.

The returned set is backed by the UserManager, i.e. it will reflect changes made through createUser() or removeUser(). The set itself is unmodifiable and ordered alphabetically.

Returns:

an unmodifiable, ordered set of all user names in this UserManager.

See Also:

createUser(java.lang.String), deleteUser(java.lang.String)

Override:

Never

getUsers

public Collection<User> getUsers()

Return all users registered with this UserManager.

The returned collection is backed by the UserManager, i.e. it will reflect changes made through createUser() or removeUser(). The collection itself is unmodifiable and ordered alphabetically by the users' names.

Returns:

an unmodifiable, ordered set of all users in this UserManager.

See Also:

createUser(java.lang.String), deleteUser(java.lang.String)

Override:

Never

deleteUser

public User deleteUser(String sName)

Delete a user from this UserManager.

The user will be removed from the UserManager and will no longer be available via getUser(java.lang.String). A userDeleted event will be received by all UserDataListeners registered with this UserManager if a user was removed. If no user with the given name existed no exception will be thrown and no event will be fired.

If the user is currently associated to some object, it will stay so until it is disassociated explicitly. It will not have the possibility to log in again, though.

Parameters:

sName - the name of the user to be removed

Returns:

the user that was just removed or null if none.

See Also:

UserDataListener.userDeleted(users.events.UserDataEvent)

Override:

Never

addUserDataListener

public void addUserDataListener(UserDataListener udl)

Add a UserDataListener. UserDataListeners will receive an event whenever a user was created or removed.

Parameters:

udl - the UserDataListener to add.

Override:

Never

removeUserDataListener

public void removeUserDataListener(UserDataListener udl)

Remove a UserDataListener.

Parameters:

udl - the UserDataListener to remove.

Override:

Never

fireUserAdded

protected void fireUserAdded(User usr)

Fire a userAdded event to all interested listeners.

Parameters:

usr - the user that was added.

Override:

Never

fireUserDeleted

protected void fireUserDeleted(User usr)

Fire a userDeleted event to all interested listeners.

Parameters:

usr - the user that was deleted.

Override:

Never

logOn

public User logOn(Object o,
                  User u)

Associate a user with an object.

Only one user at a time can be associated with one Object. If there is already another user associated with the given Object, its association is undone and the user is returned.

Only users that are actually managed by this UserManager can be logged in. An exception will be thrown if you try to log in a user that is unknown to this UserManager. Especially, this can happen if you try to log in a user that was previously removed using deleteUser(java.lang.String).

Parameters:

o - the Object with which to associate the user.

u - the user to associate with the Object

Returns:

the user that was previously associated with the Object or null if none.

Throws:

UnknownUserException - if the user to log in is not known at this UserManager. A user is known at a UserManager, if the User object is registered, i.e. no equals() method of any kind is called.

See Also:

User.loggedOn(java.lang.Object)

Override:

Never

logOff

public User logOff(Object o)

Disassociate the current user from an Object.

Parameters:

o - the Object from which to disassociate a user.

Returns:

the user just logged off or null if none.

See Also:

User.loggedOff(java.lang.Object)

Override:

Never

getCurrentUser

public User getCurrentUser(Object o)

Retrieve the user currently associated with some Object.

Parameters:

o - the Object with which the searched user must be associated.

Returns:

the user associated with the given Object or null if none.

Override:

Never

getGlobalUM

public static UserManager getGlobalUM()

Get the global UserManager.

The global UserManager can be used as a centralized instance to manage all the users in an application.

Returns:

the global UserManager.

setGlobalUM

public static UserManager setGlobalUM(UserManager umNew)

Set a new UserManager to be the global UserManager from now on.

Parameters:

umNew - the new global UserManager.

Returns:

the previous UserManager.