Package 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

    • 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

      • 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

      • 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