org.apache.wiki.auth

Class UserManager

java.lang.Object

org.apache.wiki.auth.UserManager

public class UserManager
extends Object

Provides a facade for obtaining user information.

Since:

2.3

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UserManager.DummyUserDatabase This is a database that gets used if nothing else is available.
static class	UserManager.JSONUserModule Implements the JSON API for usermanager.

Field Summary

Fields

Modifier and Type	Field and Description
static String	JSON_USERS

Constructor Summary

Constructors

Constructor and Description
UserManager()

Method Summary

Modifier and Type	Method and Description
void	addWikiEventListener(WikiEventListener listener) Registers a WikiEventListener with this instance.
protected void	fireEvent(int type, WikiSession session, Object profile) Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
UserDatabase	getUserDatabase() Returns the UserDatabase employed by this WikiEngine.
UserProfile	getUserProfile(WikiSession session) Retrieves the UserProfilefor the user in a wiki session.
void	initialize(WikiEngine engine, Properties props) Initializes the engine for its nefarious purposes.
Principal[]	listWikiNames() A helper method for returning all of the known WikiNames in this system.
UserProfile	parseProfile(WikiContext context) Extracts user profile parameters from the HTTP request and populates a UserProfile with them.
void	removeWikiEventListener(WikiEventListener listener) Un-registers a WikiEventListener with this instance.
void	setUserProfile(WikiSession session, UserProfile profile) Saves the UserProfilefor the user in a wiki session.
void	startUserProfileCreationWorkflow(WikiSession session, UserProfile profile)
void	validateProfile(WikiContext context, UserProfile profile) Validates a user profile, and appends any errors to the session errors list.

Methods inherited from class java.lang.Object

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

Field Detail

JSON_USERS

public static final String JSON_USERS

See Also:

Constant Field Values

Constructor Detail

UserManager

public UserManager()

Method Detail

initialize

public void initialize(WikiEngine engine,
                       Properties props)

Initializes the engine for its nefarious purposes.

Parameters:

engine - the current wiki engine

props - the wiki engine initialization properties

getUserDatabase

public UserDatabase getUserDatabase()

Returns the UserDatabase employed by this WikiEngine. The UserDatabase is lazily initialized by this method, if it does not exist yet. If the initialization fails, this method will use the inner class DummyUserDatabase as a default (which is enough to get JSPWiki running).

Returns:

the dummy user database

Since:

2.3

getUserProfile

public UserProfile getUserProfile(WikiSession session)

Retrieves the UserProfilefor the user in a wiki session. If the user is authenticated, the UserProfile returned will be the one stored in the user database; if one does not exist, a new one will be initialized and returned. If the user is anonymous or asserted, the UserProfile will always be newly initialized to prevent spoofing of identities. If a UserProfile needs to be initialized, its UserProfile.isNew() method will return true, and its login name will will be set automatically if the user is authenticated. Note that this method does not modify the retrieved (or newly created) profile otherwise; other fields in the user profile may be null.

If a new UserProfile was created, but its UserProfile.isNew() method returns false, this method throws an IllegalStateException. This is meant as a quality check for UserDatabase providers; it should only be thrown if the implementation is faulty.

Parameters:

session - the wiki session, which may not be null

Returns:

the user's profile, which will be newly initialized if the user is anonymous or asserted, or if the user cannot be found in the user database

setUserProfile

public void setUserProfile(WikiSession session,
                           UserProfile profile)
                    throws DuplicateUserException,
                           WikiException

Saves the UserProfilefor the user in a wiki session. This method verifies that a user profile to be saved doesn't collide with existing profiles; that is, the login name or full name is already used by another profile. If the profile collides, a DuplicateUserException is thrown. After saving the profile, the user database changes are committed, and the user's credential set is refreshed; if custom authentication is used, this means the user will be automatically be logged in.

When the user's profile is saved successfully, this method fires a WikiSecurityEvent.PROFILE_SAVE event with the WikiSession as the source and the UserProfile as target. For existing profiles, if the user's full name changes, this method also fires a "name changed" event (WikiSecurityEvent.PROFILE_NAME_CHANGED) with the WikiSession as the source and an array containing the old and new UserProfiles, respectively. The NAME_CHANGED event allows the GroupManager and PageManager can change group memberships and ACLs if needed.

Note that WikiSessions normally attach event listeners to the UserManager, so changes to the profile will automatically cause the correct Principals to be reloaded into the current WikiSession's Subject.

Parameters:

session - the wiki session, which may not be null

profile - the user profile, which may not be null

Throws:

DuplicateUserException - if the proposed profile's login name or full name collides with another

WikiException - if the save fails for some reason. If the current user does not have permission to save the profile, this will be a WikiSecurityException; if if the user profile must be approved before it can be saved, it will be a DecisionRequiredException. All other WikiException indicate a condition that is not normal is probably due to mis-configuration

startUserProfileCreationWorkflow

public void startUserProfileCreationWorkflow(WikiSession session,
                                             UserProfile profile)
                                      throws WikiException

Throws:

WikiException

parseProfile

public UserProfile parseProfile(WikiContext context)

Extracts user profile parameters from the HTTP request and populates a UserProfile with them. The UserProfile will either be a copy of the user's existing profile (if one can be found), or a new profile (if not). The rules for populating the profile as as follows:

• If the email or password parameter values differ from those in the existing profile, the passed parameters override the old values.
• For new profiles, the user-supplied fullname parameter is always used; for existing profiles the existing value is used, and whatever value the user supplied is discarded. The wiki name is automatically computed by taking the full name and extracting all whitespace.
• In all cases, the created/last modified timestamps of the user's existing or new profile always override whatever values the user supplied.
• If container authentication is used, the login name property of the profile is set to the name of WikiSession.getLoginPrincipal(). Otherwise, the value of the loginname parameter is used.

Parameters:

context - the current wiki context

Returns:

a new, populated user profile

validateProfile

public void validateProfile(WikiContext context,
                            UserProfile profile)

Validates a user profile, and appends any errors to the session errors list. If the profile is new, the password will be checked to make sure it isn't null. Otherwise, the password is checked for length and that it matches the value of the 'password2' HTTP parameter. Note that we have a special case when container-managed authentication is used and the user is not authenticated; this will always cause validation to fail. Any validation errors are added to the wiki session's messages collection (see WikiSession.getMessages().

Parameters:

context - the current wiki context

profile - the supplied UserProfile

listWikiNames

public Principal[] listWikiNames()
                          throws WikiSecurityException

A helper method for returning all of the known WikiNames in this system.

Returns:

An Array of Principals

Throws:

WikiSecurityException - If for reason the names cannot be fetched

addWikiEventListener

public void addWikiEventListener(WikiEventListener listener)

Registers a WikiEventListener with this instance. This is a convenience method.

Parameters:

listener - the event listener

removeWikiEventListener

public void removeWikiEventListener(WikiEventListener listener)

Un-registers a WikiEventListener with this instance. This is a convenience method.

Parameters:

listener - the event listener

fireEvent

protected void fireEvent(int type,
                         WikiSession session,
                         Object profile)

Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.

Parameters:

type - the event type to be fired

session - the wiki session supporting the event

profile - the user profile (or array of user profiles), which may be null

See Also:

WikiSecurityEvent