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}