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

  • Method Details

    • 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

      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:

      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

      Registers a WikiEventListener with this instance. This is a convenience method.
      Parameters:
      listener - the event listener
    • removeWikiEventListener

      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