org.apache.wiki.auth.authorize

Class DefaultGroupManager

java.lang.Object

org.apache.wiki.auth.authorize.DefaultGroupManager

All Implemented Interfaces:

java.util.EventListener, Initializable, GroupManager, Authorizer, WikiEventListener

public class DefaultGroupManager
extends java.lang.Object
implements GroupManager, 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

Fields

Modifier and Type	Field and Description
protected Engine	m_engine
protected WikiEventListener	m_groupListener

Fields inherited from interface org.apache.wiki.auth.authorize.GroupManager

MESSAGES_KEY, PROP_GROUPDATABASE

Constructor Summary

Constructors

Constructor and Description
DefaultGroupManager()

Method Summary

Modifier and Type	Method and Description
void	actionPerformed(WikiEvent event)
void	addWikiEventListener(WikiEventListener listener) Registers a WikiEventListener with this instance.
void	checkGroupName(Context context, java.lang.String name) Checks if a String is blank or a restricted Group name, and if it is, appends an error to the Session's message list.
protected java.lang.String[]	extractMembers(java.lang.String memberLine) Extracts carriage-return separated members into a Set of String objects.
java.security.Principal	findRole(java.lang.String name) Looks up and returns a role Principal matching a given String.
Group	getGroup(java.lang.String name) Returns the Group matching a given name.
GroupDatabase	getGroupDatabase() Returns the current external GroupDatabase in use.
java.security.Principal[]	getRoles() Returns an array of role Principals this Authorizer knows about.
void	initialize(Engine engine, java.util.Properties props) Initializes the authorizer.
boolean	isUserInRole(Session session, java.security.Principal role) Determines whether the Subject associated with a WikiSession is in a particular role.
Group	parseGroup(java.lang.String name, java.lang.String memberLine, boolean create) Extracts group name and members from passed parameters and populates an existing Group with them.
void	removeGroup(java.lang.String index) Removes a named Group from the group database.
void	removeWikiEventListener(WikiEventListener listener) Un-registers a WikiEventListener with this instance.
void	setGroup(Session session, Group group) Saves the Group created by a user in a wiki session.
void	validateGroup(Context 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

Methods inherited from interface org.apache.wiki.auth.authorize.GroupManager

fireEvent, parseGroup

Field Detail

m_engine

protected Engine m_engine

m_groupListener

protected WikiEventListener m_groupListener

Constructor Detail

DefaultGroupManager

public DefaultGroupManager()

Method Detail

findRole

public java.security.Principal findRole(java.lang.String name)

Looks up and returns a role Principal matching a given String. If a matching role cannot be found, this method returns null. Note that it may not always be feasible for an Authorizer implementation to return a role Principal.

Specified by:

findRole in interface Authorizer

Parameters:

name - the name of the role to retrieve

Returns:

the role Principal

getGroup

public Group getGroup(java.lang.String name)
               throws NoSuchPrincipalException

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

Specified by:

getGroup in interface GroupManager

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.

Specified by:

getGroupDatabase in interface GroupManager

Returns:

the current GroupDatabase

Throws:

WikiSecurityException - if the GroupDatabase could not be initialized

getRoles

public java.security.Principal[] getRoles()

Returns an array of role Principals this Authorizer knows about. This method will always return an array; an implementing class may choose to return an zero-length array if it has no ability to identify the roles under its control.

Specified by:

getRoles in interface Authorizer

Returns:

an array of Principals representing the roles

initialize

public void initialize(Engine engine,
                       java.util.Properties props)
                throws WikiSecurityException

Initializes the authorizer.

Specified by:

initialize in interface Initializable

Specified by:

initialize in interface Authorizer

Parameters:

engine - the current wiki engine

props - the wiki engine initialization properties

Throws:

WikiSecurityException - if the Authorizer could not be initialized

isUserInRole

public boolean isUserInRole(Session session,
                            java.security.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, this method must return false.

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(java.lang.String name,
                        java.lang.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 GroupManager.setGroup(Session, Group).

Specified by:

parseGroup in interface GroupManager

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

removeGroup

public void removeGroup(java.lang.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.

Specified by:

removeGroup in interface GroupManager

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(Session 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 Session as a GroupManager listener. Thus, the act of registering a Group with setGroup means that all Sessions will automatically receive group add/change/delete events immediately.

Specified by:

setGroup in interface GroupManager

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(Context 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 Session.getMessages().

Specified by:

validateGroup in interface GroupManager

Parameters:

context - the current wiki context

group - the supplied Group

checkGroupName

public void checkGroupName(Context context,
                           java.lang.String name)
                    throws WikiSecurityException

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

Specified by:

checkGroupName in interface GroupManager

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

extractMembers

protected java.lang.String[] extractMembers(java.lang.String memberLine)

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

Parameters:

memberLine - the list of members

Returns:

the list of members

addWikiEventListener

public void addWikiEventListener(WikiEventListener listener)

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

Specified by:

addWikiEventListener in interface GroupManager

Parameters:

listener - the event listener

removeWikiEventListener

public void removeWikiEventListener(WikiEventListener listener)

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

Specified by:

removeWikiEventListener in interface GroupManager

Parameters:

listener - the event listener

actionPerformed

public void actionPerformed(WikiEvent event)

Specified by:

actionPerformed in interface WikiEventListener