org.apache.wiki.auth.authorize

Interface GroupManager

All Superinterfaces:

Authorizer, java.util.EventListener, Initializable, WikiEventListener

All Known Implementing Classes:

DefaultGroupManager

public interface GroupManager
extends Initializable, 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
static java.lang.String	MESSAGES_KEY Key used for adding UI messages to a user's Session.
static java.lang.String	PROP_GROUPDATABASE

Method Summary

Modifier and Type	Method and Description
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.
default void	fireEvent(int type, java.lang.Object target) Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
Group	getGroup(java.lang.String name) Returns the Group matching a given name.
GroupDatabase	getGroupDatabase() Returns the current external GroupDatabase in use.
default Group	parseGroup(Context context, boolean create) Extracts group name and members from the HTTP request and populates an existing Group with them.
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 interface org.apache.wiki.api.engine.Initializable

initialize

Methods inherited from interface org.apache.wiki.auth.Authorizer

findRole, getRoles, initialize, isUserInRole

Methods inherited from interface org.apache.wiki.event.WikiEventListener

actionPerformed

Field Detail

MESSAGES_KEY

static final java.lang.String MESSAGES_KEY

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

See Also:

Constant Field Values

PROP_GROUPDATABASE

static final java.lang.String PROP_GROUPDATABASE

See Also:

Constant Field Values

Method Detail

getGroup

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.

Parameters:

name - the name of the group to find

Returns:

the group

Throws:

NoSuchPrincipalException - if the group cannot be found

getGroupDatabase

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

parseGroup

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 setGroup(Session, 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

default Group parseGroup(Context 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(Session, 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

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.

Parameters:

index - the group to remove

Throws:

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

See Also:

GroupDatabase.delete(Group)

setGroup

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.

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

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().

Parameters:

context - the current wiki context

group - the supplied Group

checkGroupName

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.

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

void addWikiEventListener(WikiEventListener listener)

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

Parameters:

listener - the event listener

removeWikiEventListener

void removeWikiEventListener(WikiEventListener listener)

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

Parameters:

listener - the event listener

fireEvent

default void fireEvent(int type,
                       java.lang.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