Package org.apache.wiki.auth.authorize

# Interface GroupManager

All Superinterfaces:
  `Authorizer`, `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
Description
`static final String`
`MESSAGES_KEY`
Key used for adding UI messages to a user's Session.
`static final String`
`PROP_GROUPDATABASE`

## Method Summary

Modifier and Type
Method
Description
`void`
`addWikiEventListener(WikiEventListener listener)`
Registers a WikiEventListener with this instance.
`void`
`checkGroupName(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.
`default 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.
`Group`
`parseGroup(String name, String memberLine, boolean create)`
Extracts group name and members from passed parameters and populates an existing Group with them.
`default Group`
`parseGroup(Context 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(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.auth.Authorizer

`findRole, getRoles, initialize, isUserInRole`

### Methods inherited from interface org.apache.wiki.api.engine.Initializable

`initialize`

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

`actionPerformed`

## Field Details

### MESSAGES_KEY

static final String MESSAGES_KEY
Key used for adding UI messages to a user's Session.

See Also:
  - Constant Field Values

### PROP_GROUPDATABASE

static final String PROP_GROUPDATABASE

See Also:
  - Constant Field Values

## Method Details

### getGroup

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

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(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(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(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, 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, 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`