01: /*
02: * JSPWiki - a JSP-based WikiWiki clone. Copyright (C) 2001-2003 Janne Jalkanen
03: * (Janne.Jalkanen@iki.fi) This program is free software; you can redistribute
04: * it and/or modify it under the terms of the GNU Lesser General Public License
05: * as published by the Free Software Foundation; either version 2.1 of the
06: * License, or (at your option) any later version. This program is distributed
07: * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
08: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
09: * See the GNU Lesser General Public License for more details. You should have
10: * received a copy of the GNU Lesser General Public License along with this
11: * program; if not, write to the Free Software Foundation, Inc., 59 Temple
12: * Place, Suite 330, Boston, MA 02111-1307 USA
13: */
14: package com.ecyrd.jspwiki.auth.authorize;
15:
16: import java.security.Principal;
17: import java.util.Properties;
18:
19: import com.ecyrd.jspwiki.NoRequiredPropertyException;
20: import com.ecyrd.jspwiki.WikiEngine;
21: import com.ecyrd.jspwiki.auth.NoSuchPrincipalException;
22: import com.ecyrd.jspwiki.auth.WikiSecurityException;
23:
24: /**
25: * Defines an interface for loading, persisting and storing wiki groups.
26: * @author Andrew Jaquith
27: * @since 2.4.22
28: */
29: public interface GroupDatabase {
30: /**
31: * No-op method that in previous versions of JSPWiki was intended to
32: * atomically commit changes to the user database. Now, the
33: * {@link #save(Group, Principal)} and {@link #delete(Group)} methods
34: * are atomic themselves.
35: * @throws WikiSecurityException never...
36: * @deprecated there is no need to call this method because the save and
37: * delete methods contain their own commit logic
38: */
39: public void commit() throws WikiSecurityException;
40:
41: /**
42: * Looks up and deletes a {@link Group} from the group database. If the
43: * group database does not contain the supplied Group. this method throws a
44: * {@link NoSuchPrincipalException}. The method commits the results
45: * of the delete to persistent storage.
46: * @param group the group to remove
47: * @throws WikiSecurityException if the database does not contain the
48: * supplied group (thrown as {@link NoSuchPrincipalException}) or if
49: * the commit did not succeed
50: */
51: public void delete(Group group) throws WikiSecurityException;
52:
53: /**
54: * Initializes the group database based on values from a Properties object.
55: * @param engine the wiki engine
56: * @param props the properties used to initialize the group database
57: * @throws WikiSecurityException if the database could not be initialized successfully
58: * @throws NoRequiredPropertyException if a required property is not present
59: */
60: public void initialize(WikiEngine engine, Properties props)
61: throws NoRequiredPropertyException, WikiSecurityException;
62:
63: /**
64: * Saves a Group to the group database. Note that this method <em>must</em>
65: * fail, and throw an <code>IllegalArgumentException</code>, if the
66: * proposed group is the same name as one of the built-in Roles: e.g.,
67: * Admin, Authenticated, etc. The database is responsible for setting
68: * create/modify timestamps, upon a successful save, to the Group.
69: * The method commits the results of the delete to persistent storage.
70: * @param group the Group to save
71: * @param modifier the user who saved the Group
72: * @throws WikiSecurityException if the Group could not be saved successfully
73: */
74: public void save(Group group, Principal modifier)
75: throws WikiSecurityException;
76:
77: /**
78: * Returns all wiki groups that are stored in the GroupDatabase as an array
79: * of Group objects. If the database does not contain any groups, this
80: * method will return a zero-length array. This method causes back-end
81: * storage to load the entire set of group; thus, it should be called
82: * infrequently (e.g., at initialization time). Note that this method should
83: * use the protected constructor {@link Group#Group(String, String)} rather
84: * than the various "parse" methods ({@link GroupManager#parseGroup(String, String, boolean)})
85: * to construct the group. This is so as not to flood GroupManager's event
86: * queue with spurious events.
87: * @return the wiki groups
88: * @throws WikiSecurityException if the groups cannot be returned by the back-end
89: */
90: public Group[] groups() throws WikiSecurityException;
91: }
|