Package org.apache.wiki.auth.authorize

# Class DefaultGroupManager

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

All Implemented Interfaces:
  `EventListener`, `org.apache.wiki.api.engine.Initializable`, `GroupManager`, `Authorizer`, `org.apache.wiki.event.WikiEventListener`

public class DefaultGroupManager extends Object implements GroupManager, Authorizer, org.apache.wiki.event.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
Description
`protected org.apache.wiki.api.core.Engine`
`m_engine`
`protected org.apache.wiki.event.WikiEventListener`
`m_groupListener`

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

`MESSAGES_KEY, PROP_GROUPDATABASE`

## Constructor Summary

Constructors
Constructor
Description
`DefaultGroupManager()`

## Method Summary

Modifier and Type
Method
Description
`void`
`actionPerformed(org.apache.wiki.event.WikiEvent event)`
`void`
`addWikiEventListener(org.apache.wiki.event.WikiEventListener listener)`
Registers a WikiEventListener with this instance.
`void`
`checkGroupName(org.apache.wiki.api.core.Context context, 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 String[]`
`extractMembers(String memberLine)`
Extracts carriage-return separated members into a Set of String objects.
`Principal`
`findRole(String name)`
Looks up and returns a role Principal matching a given String.
`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 role Principals this Authorizer knows about.
`void`
`initialize(org.apache.wiki.api.core.Engine engine, Properties props)`
Initializes the authorizer.
`boolean`
`isUserInRole(org.apache.wiki.api.core.Session 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.
`void`
`removeGroup(String index)`
Removes a named Group from the group database.
`void`
`removeWikiEventListener(org.apache.wiki.event.WikiEventListener listener)`
Un-registers a WikiEventListener with this instance.
`void`
`setGroup(org.apache.wiki.api.core.Session session, Group group)`
Saves the `Group` created by a user in a wiki session.
`void`
`validateGroup(org.apache.wiki.api.core.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 Details

### m_engine

protected org.apache.wiki.api.core.Engine m_engine

### m_groupListener

protected org.apache.wiki.event.WikiEventListener m_groupListener

## Constructor Details

### DefaultGroupManager

public DefaultGroupManager()

## Method Details

### findRole

public Principal findRole(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(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 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(org.apache.wiki.api.core.Engine engine, Properties props) throws WikiSecurityException
Initializes the authorizer.

Specified by:
  `initialize` in interface `Authorizer`
Specified by:
  `initialize` in interface `org.apache.wiki.api.engine.Initializable`
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(org.apache.wiki.api.core.Session 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`, 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(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 `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(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(org.apache.wiki.api.core.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(org.apache.wiki.api.core.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(org.apache.wiki.api.core.Context 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 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 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

### addWikiEventListener

public void addWikiEventListener(org.apache.wiki.event.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(org.apache.wiki.event.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(org.apache.wiki.event.WikiEvent event)

Specified by:
  `actionPerformed` in interface `org.apache.wiki.event.WikiEventListener`