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     */
019    package org.apache.wiki.auth.authorize;
020    
021    import java.security.Principal;
022    import java.util.Properties;
023    
024    import org.apache.wiki.WikiEngine;
025    import org.apache.wiki.api.exceptions.NoRequiredPropertyException;
026    import org.apache.wiki.auth.WikiSecurityException;
027    
028    /**
029     * Defines an interface for loading, persisting and storing wiki groups.
030     * @since 2.4.22
031     */
032    public 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    }