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 java.security.Principal;
022import java.util.Properties;
023
024import org.apache.wiki.WikiEngine;
025import org.apache.wiki.api.exceptions.NoRequiredPropertyException;
026import org.apache.wiki.auth.WikiSecurityException;
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     * No-op method that in previous versions of JSPWiki was intended to 
036     * atomically commit changes to the user database. Now, the
037     * {@link #save(Group, Principal)} and {@link #delete(Group)} methods
038     * are atomic themselves.
039     * @throws WikiSecurityException never...
040     * @deprecated there is no need to call this method because the save and
041     * delete methods contain their own commit logic
042     */
043    void commit() throws WikiSecurityException;
044
045    /**
046     * Looks up and deletes a {@link Group} from the group database. If the
047     * group database does not contain the supplied Group. this method throws a
048     * {@link org.apache.wiki.auth.NoSuchPrincipalException}. The method commits the results
049     * of the delete to persistent storage.
050     * @param group the group to remove
051     * @throws WikiSecurityException if the database does not contain the
052     * supplied group (thrown as {@link org.apache.wiki.auth.NoSuchPrincipalException}) or if
053     * the commit did not succeed
054     */
055    void delete( Group group ) throws WikiSecurityException;
056
057    /**
058     * Initializes the group database based on values from a Properties object.
059     * @param engine the wiki engine
060     * @param props the properties used to initialize the group database
061     * @throws WikiSecurityException if the database could not be initialized successfully
062     * @throws NoRequiredPropertyException if a required property is not present
063     */
064    void initialize( WikiEngine engine, Properties props ) throws NoRequiredPropertyException, WikiSecurityException;
065
066    /**
067     * Saves a Group to the group database. Note that this method <em>must</em>
068     * fail, and throw an <code>IllegalArgumentException</code>, if the
069     * proposed group is the same name as one of the built-in Roles: e.g.,
070     * Admin, Authenticated, etc. The database is responsible for setting
071     * create/modify timestamps, upon a successful save, to the Group.
072     * The method commits the results of the delete to persistent storage.
073     * @param group the Group to save
074     * @param modifier the user who saved the Group
075     * @throws WikiSecurityException if the Group could not be saved successfully
076     */
077    void save( Group group, Principal modifier ) throws WikiSecurityException;
078
079    /**
080     * Returns all wiki groups that are stored in the GroupDatabase as an array
081     * of Group objects. If the database does not contain any groups, this
082     * method will return a zero-length array. This method causes back-end
083     * storage to load the entire set of group; thus, it should be called
084     * infrequently (e.g., at initialization time). Note that this method should
085     * use the protected constructor {@link Group#Group(String, String)} rather
086     * than the various "parse" methods ({@link GroupManager#parseGroup(String, String, boolean)})
087     * to construct the group. This is so as not to flood GroupManager's event
088     * queue with spurious events.
089     * @return the wiki groups
090     * @throws WikiSecurityException if the groups cannot be returned by the back-end
091     */
092    Group[] groups() throws WikiSecurityException;
093}