org.apache.wiki.auth.authorize
Class GroupManager

java.lang.Object
  org.apache.wiki.auth.authorize.GroupManager

All Implemented Interfaces:

EventListener, Authorizer, WikiEventListener

public class GroupManager
extends Object
implements Authorizer, WikiEventListener

Facade class for storing, retrieving and managing wiki groups on behalf of AuthorizationManager, JSPs and other presentation-layer classes. GroupManager works in collaboration with a back-end GroupDatabase, which persists groups to permanent storage.

Note: prior to JSPWiki 2.4.19, GroupManager was an interface; it is now a concrete, final class. The aspects of GroupManager which previously extracted group information from storage (e.g., wiki pages) have been refactored into the GroupDatabase interface.

Since:

2.4.19

Field Summary

protected WikiEngine	m_engine
protected WikiEventListener	m_groupListener
static String	MESSAGES_KEY Key used for adding UI messages to a user's WikiSession.

Constructor Summary

GroupManager()

Method Summary

void	actionPerformed(WikiEvent event) Listens for WikiSecurityEvent.PROFILE_NAME_CHANGED events.
void	addWikiEventListener(WikiEventListener listener) Registers a WikiEventListener with this instance.
protected void	checkGroupName(WikiContext context, String name) Checks if a String is blank or a restricted Group name, and if it is, appends an error to the WikiSession's message list.
protected String[]	extractMembers(String memberLine) Extracts carriage-return separated members into a Set of String objects.
Principal	findRole(String name) Returns a GroupPrincipal matching a given name.
protected void	fireEvent(int type, Object target) Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
Group	getGroup(String name) Returns the Group matching a given name.
GroupDatabase	getGroupDatabase() Returns the current external GroupDatabase in use.
Principal[]	getRoles() Returns an array of GroupPrincipals this GroupManager knows about.
void	initialize(WikiEngine engine, Properties props) Initializes the group cache by initializing the group database and obtaining a list of all of the groups it stores.
boolean	isUserInRole(WikiSession session, Principal role) Determines whether the Subject associated with a WikiSession is in a particular role.
Group	parseGroup(String name, String memberLine, boolean create) Extracts group name and members from passed parameters and populates an existing Group with them.
Group	parseGroup(WikiContext context, boolean create) Extracts group name and members from the HTTP request and populates an existing Group with them.
void	removeGroup(String index) Removes a named Group from the group database.
void	removeWikiEventListener(WikiEventListener listener) Un-registers a WikiEventListener with this instance.
void	setGroup(WikiSession session, Group group) Saves the Group created by a user in a wiki session.
void	validateGroup(WikiContext context, Group group) Validates a Group, 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

MESSAGES_KEY

public static final String MESSAGES_KEY

Key used for adding UI messages to a user's WikiSession.

See Also:

Constant Field Values

m_engine

protected WikiEngine m_engine

m_groupListener

protected WikiEventListener m_groupListener

Constructor Detail

GroupManager

public GroupManager()

Method Detail

findRole

public Principal findRole(String name)

Returns a GroupPrincipal matching a given name. If a group cannot be found, return null.

Specified by:

findRole in interface Authorizer

Parameters:

name - Name of the group. This is case-sensitive.

Returns:

A DefaultGroup instance.

getGroup

public Group getGroup(String name)
               throws NoSuchPrincipalException

Returns the Group matching a given name. If the group cannot be found, this method throws a NoSuchPrincipalException.

Parameters:

name - the name of the group to find

Returns:

the group

Throws:

NoSuchPrincipalException - if the group cannot be found

getGroupDatabase

public GroupDatabase getGroupDatabase()
                               throws WikiSecurityException

Returns the current external GroupDatabase in use. This method is guaranteed to return a properly-initialized GroupDatabase, unless it could not be initialized. In that case, this method throws a WikiException. The GroupDatabase is lazily initialized.

Returns:

the current GroupDatabase

Throws:

WikiSecurityException - if the GroupDatabase could not be initialized

Since:

2.3

getRoles

public Principal[] getRoles()

Returns an array of GroupPrincipals this GroupManager knows about. This method will return an array of GroupPrincipal objects corresponding to the wiki groups managed by this class. This method actually returns a defensive copy of an internally stored hashmap.

Specified by:

getRoles in interface Authorizer

Returns:

an array of Principals representing the roles

initialize

public void initialize(WikiEngine engine,
                       Properties props)
                throws WikiSecurityException

Initializes the group cache by initializing the group database and obtaining a list of all of the groups it stores.

Specified by:

initialize in interface Authorizer

Parameters:

engine - the wiki engine

props - the properties used to initialize the wiki engine

Throws:

WikiSecurityException - if GroupManager cannot be initialized

See Also:

GroupDatabase.initialize(org.apache.wiki.WikiEngine, java.util.Properties), GroupDatabase.groups()

isUserInRole

public boolean isUserInRole(WikiSession session,
                            Principal role)

Determines whether the Subject associated with a WikiSession is in a particular role. This method takes two parameters: the WikiSession containing the subject and the desired role ( which may be a Role or a Group). If either parameter is null, or if the user is not authenticated, this method returns false.

With respect to this implementation, the supplied Principal must be a GroupPrincipal. The Subject posesses the "role" if it the session is authenticated and a Subject's principal is a member of the corresponding Group. This method simply finds the Group in question, then delegates to Group.isMember(Principal) for each of the principals in the Subject's principal set.

Specified by:

isUserInRole in interface Authorizer

Parameters:

session - the current WikiSession

role - the role to check

Returns:

true if the user is considered to be in the role, false otherwise

parseGroup

public Group parseGroup(String name,
                        String memberLine,
                        boolean create)
                 throws WikiSecurityException

Extracts group name and members from passed parameters and populates an existing Group with them. The Group will either be a copy of an existing Group (if one can be found), or a new, unregistered Group (if not). Optionally, this method can throw a WikiSecurityException if the Group does not yet exist in the GroupManager cache.

The group parameter in the HTTP request contains the Group name to look up and populate. The members parameter contains the member list. If these differ from those in the existing group, the passed values override the old values.

This method does not commit the new Group to the GroupManager cache. To do that, use setGroup(WikiSession, Group).

Parameters:

name - the name of the group to construct

memberLine - the line of text containing the group membership list

create - whether this method should create a new, empty Group if one with the requested name is not found. If false, groups that do not exist will cause a NoSuchPrincipalException to be thrown

Returns:

a new, populated group

Throws:

WikiSecurityException - if the group name isn't allowed, or if create is false and the Group named name does not exist

See Also:

Group.RESTRICTED_GROUPNAMES

parseGroup

public Group parseGroup(WikiContext context,
                        boolean create)
                 throws WikiSecurityException

Extracts group name and members from the HTTP request and populates an existing Group with them. The Group will either be a copy of an existing Group (if one can be found), or a new, unregistered Group (if not). Optionally, this method can throw a WikiSecurityException if the Group does not yet exist in the GroupManager cache.

The group parameter in the HTTP request contains the Group name to look up and populate. The members parameter contains the member list. If these differ from those in the existing group, the passed values override the old values.

This method does not commit the new Group to the GroupManager cache. To do that, use setGroup(WikiSession, Group).

Parameters:

context - the current wiki context

create - whether this method should create a new, empty Group if one with the requested name is not found. If false, groups that do not exist will cause a NoSuchPrincipalException to be thrown

Returns:

a new, populated group

Throws:

WikiSecurityException - if the group name isn't allowed, or if create is false and the Group does not exist

removeGroup

public void removeGroup(String index)
                 throws WikiSecurityException

Removes a named Group from the group database. If not found, throws a NoSuchPrincipalException. After removal, this method will commit the delete to the back-end group database. It will also fire a WikiSecurityEvent.GROUP_REMOVE event with the GroupManager instance as the source and the Group as target. If index is null, this method throws an IllegalArgumentException.

Parameters:

index - the group to remove

Throws:

WikiSecurityException - if the Group cannot be removed by the back-end

See Also:

GroupDatabase.delete(Group)

setGroup

public void setGroup(WikiSession session,
                     Group group)
              throws WikiSecurityException

Saves the Group created by a user in a wiki session. This method registers the Group with the GroupManager and saves it to the back-end database. If an existing Group with the same name already exists, the new group will overwrite it. After saving the Group, the group database changes are committed.

This method fires the following events:

• When creating a new Group, this method fires a WikiSecurityEvent.GROUP_ADD with the GroupManager instance as its source and the new Group as the target.
• When overwriting an existing Group, this method fires a new WikiSecurityEvent.GROUP_REMOVE with this GroupManager instance as the source, and the new Group as the target. It then fires a WikiSecurityEvent.GROUP_ADD event with the same source and target.

In addition, if the save or commit actions fail, this method will attempt to restore the older version of the wiki group if it exists. This will result in a GROUP_REMOVE event (for the new version of the Group) followed by a GROUP_ADD event (to indicate restoration of the old version).

This method will register the new Group with the GroupManager. For example, AuthenticationManager attaches each WikiSession as a GroupManager listener. Thus, the act of registering a Group with setGroup means that all WikiSessions will automatically receive group add/change/delete events immediately.

Parameters:

session - the wiki session, which may not be null

group - the Group, which may not be null

Throws:

WikiSecurityException - if the Group cannot be saved by the back-end

validateGroup

public void validateGroup(WikiContext context,
                          Group group)

Validates a Group, and appends any errors to the session errors list. Any validation errors are added to the wiki session's messages collection (see WikiSession.getMessages().

Parameters:

context - the current wiki context

group - the supplied Group

extractMembers

protected String[] extractMembers(String memberLine)

Extracts carriage-return separated members into a Set of String objects.

Parameters:

memberLine - the list of members

Returns:

the list of members

checkGroupName

protected void checkGroupName(WikiContext context,
                              String name)
                       throws WikiSecurityException

Checks if a String is blank or a restricted Group name, and if it is, appends an error to the WikiSession's message list.

Parameters:

context - the wiki context

name - the Group name to test

Throws:

WikiSecurityException - if session is null or the Group name is illegal

See Also:

Group.RESTRICTED_GROUPNAMES

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,
                         Object target)

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

Parameters:

type - the event type to be fired

target - the changed Object, which may be null

See Also:

WikiSecurityEvent

actionPerformed

public void actionPerformed(WikiEvent event)

Listens for WikiSecurityEvent.PROFILE_NAME_CHANGED events. If a user profile's name changes, each group is inspected. If an entry contains a name that has changed, it is replaced with the new one. No group events are emitted as a consequence of this method, because the group memberships are still the same; it is only the representations of the names within that are changing.

Specified by:

actionPerformed in interface WikiEventListener

Parameters:

event - the incoming event