    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.auth.authorize;
    020
    021import org.apache.wiki.api.core.Engine;
    022import org.apache.wiki.api.exceptions.NoRequiredPropertyException;
    023import org.apache.wiki.auth.WikiSecurityException;
    024
    025import java.security.Principal;
    026import java.util.Properties;
    027
    028/**
    029 * Defines an interface for loading, persisting and storing wiki groups.
    030 * @since 2.4.22
    031 */
    032public interface GroupDatabase {
    033
    034    /**
    035     * Looks up and deletes a {@link Group} from the group database. If the
    036     * group database does not contain the supplied Group. this method throws a
    037     * {@link org.apache.wiki.auth.NoSuchPrincipalException}. The method commits the results
    038     * of the delete to persistent storage.
    039     * @param group the group to remove
    040     * @throws WikiSecurityException if the database does not contain the
    041     * supplied group (thrown as {@link org.apache.wiki.auth.NoSuchPrincipalException}) or if
    042     * the commit did not succeed
    043     */
    044    void delete( Group group ) throws WikiSecurityException;
    045
    046    /**
    047     * Initializes the group database based on values from a Properties object.
    048     * @param engine the wiki engine
    049     * @param props the properties used to initialize the group database
    050     * @throws WikiSecurityException if the database could not be initialized successfully
    051     * @throws NoRequiredPropertyException if a required property is not present
    052     */
    053    void initialize( Engine engine, Properties props ) throws NoRequiredPropertyException, WikiSecurityException;
    054
    055    /**
    056     * Saves a Group to the group database. Note that this method <em>must</em>
    057     * fail, and throw an <code>IllegalArgumentException</code>, if the
    058     * proposed group is the same name as one of the built-in Roles: e.g.,
    059     * Admin, Authenticated, etc. The database is responsible for setting
    060     * create/modify timestamps, upon a successful save, to the Group.
    061     * The method commits the results of the delete to persistent storage.
    062     * @param group the Group to save
    063     * @param modifier the user who saved the Group
    064     * @throws WikiSecurityException if the Group could not be saved successfully
    065     */
    066    void save( Group group, Principal modifier ) throws WikiSecurityException;
    067
    068    /**
    069     * Returns all wiki groups that are stored in the GroupDatabase as an array
    070     * of Group objects. If the database does not contain any groups, this
    071     * method will return a zero-length array. This method causes back-end
    072     * storage to load the entire set of group; thus, it should be called
    073     * infrequently (e.g., at initialization time). Note that this method should
    074     * use the protected constructor {@link Group#Group(String, String)} rather
    075     * than the various "parse" methods ({@link GroupManager#parseGroup(String, String, boolean)})
    076     * to construct the group. This is so as not to flood GroupManager's event
    077     * queue with spurious events.
    078     * @return the wiki groups
    079     * @throws WikiSecurityException if the groups cannot be returned by the back-end
    080     */
    081    Group[] groups() throws WikiSecurityException;
    082
    083}