001package org.apache.fulcrum.security.model.turbine;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import org.apache.fulcrum.security.ModelManager;
023import org.apache.fulcrum.security.entity.Group;
024import org.apache.fulcrum.security.entity.Permission;
025import org.apache.fulcrum.security.entity.Role;
026import org.apache.fulcrum.security.entity.User;
027import org.apache.fulcrum.security.util.DataBackendException;
028import org.apache.fulcrum.security.util.UnknownEntityException;
029
030/**
031 * Describes all the relationships between entities in the "Turbine" model.
032 * 
033 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
034 * @version $Id$
035 */
036public interface TurbineModelManager extends ModelManager
037{
038
039
040        /**
041         * attribute where global group name could be set 
042         */
043    String GLOBAL_GROUP_ATTR_NAME = "globalGroup";
044    
045    /**
046     * The name of the <a href="#global">global group</a>, if no global group name is set in model manager
047     */
048    public String GLOBAL_GROUP_NAME = "global";
049    
050    /**
051     * may be used in implementations
052     *
053     */
054    public enum Privilege {
055        GRANT, REVOKE, REPLACE_ROLE;
056    }
057    
058    /**
059     * TODO 
060     * <li>transactional revoke/grant = replace for global group/role? 
061     * <li>may allow user - group assignments without role, i.e. with default role. Requires adding/defining default/zero role for group, you have then to the global role additionally a global group. 
062     * This may be relevant, if just only one group is sufficient (or at least one). 
063     */
064
065    /**
066     * Provides a reference to the Group object that represents the <a
067     * href="#global">global group</a>.
068     * 
069     * @return A Group object that represents the global group.
070     * @throws DataBackendException generic exception
071     */
072    Group getGlobalGroup() throws DataBackendException;
073    
074    /**
075     * 
076     * @return the configured global group name, by default {@link #GLOBAL_GROUP_ATTR_NAME}
077     */
078    public String getGlobalGroupName();
079    
080    /**
081     * Replaces the assigned old Role to new role in the #global group for User user.
082     *  
083     * @param user
084     *            the User.
085     * @param oldRole
086     *              the old Role
087     * @param newRole
088     *              the new Role
089     * @throws DataBackendException generic exception
090     * @throws UnknownEntityException generic exception
091     */
092    void replace(User user, Role oldRole, Role newRole)  throws DataBackendException, UnknownEntityException;
093
094    /**
095     * Puts a permission in a role
096     * 
097     * This method is used when adding a permission to a role
098     * 
099     * @param role
100     *            the Role.
101     * @param permission
102     *             the Permission
103     * @throws DataBackendException
104     *             if there was an error accessing the data backend.
105     * @throws UnknownEntityException
106     *             if the account is not present.
107     */
108    void grant(Role role, Permission permission) throws DataBackendException, UnknownEntityException;
109
110    /**
111     * Removes a permission from a role
112     * 
113     * @param role
114     *            the Role.
115     * @param permission
116     *             the Permission
117     * @throws DataBackendException
118     *             if there was an error accessing the data backend.
119     * @throws UnknownEntityException
120     *             if the role or permission is not present.
121     */
122    void revoke(Role role, Permission permission) throws DataBackendException, UnknownEntityException;
123    
124
125    /**
126     * Revokes all roles from an User.
127     * 
128     * This method is typically used when deleting an account.
129     * 
130     * @param user
131     *            the User.
132     * @throws DataBackendException
133     *             if there was an error accessing the data backend.
134     * @throws UnknownEntityException
135     *             if the account is not present.
136     */
137    void revokeAll(User user) throws DataBackendException, UnknownEntityException;
138
139    /**
140     * Revokes all permissions from a Role.
141     * 
142     * This method is typically used when deleting a Role.
143     * 
144     * @param role
145     *            the Role
146     * @throws DataBackendException
147     *             if there was an error accessing the data backend.
148     * @throws UnknownEntityException
149     *             if the Role is not present.
150     */
151    void revokeAll(Role role) throws DataBackendException, UnknownEntityException;
152    
153    /**
154     * Revokes all roles and users from a Group.
155     * 
156     * This method is typically used when deleting a Group.
157     * 
158     * @param group
159     *            the Group
160     * @throws DataBackendException
161     *             if there was an error accessing the data backend.
162     * @throws UnknownEntityException
163     *             if the Group is not present.
164     */
165    void revokeAll(Group group) throws DataBackendException, UnknownEntityException;
166
167    /**
168     * Grant an User a Role in a Group.
169     * 
170     * @param user
171     *            the user.
172     * @param group
173     *            the group.
174     * @param role
175     *            the role.
176     * @throws DataBackendException
177     *             if there was an error accessing the data backend.
178     * @throws UnknownEntityException
179     *             if user account, group or role is not present.
180     */
181    void grant(User user, Group group, Role role) throws DataBackendException, UnknownEntityException;
182
183    /**
184     * Revoke a Role in a Group from an User.
185     * 
186     * @param user
187     *            the user.
188     * @param group
189     *            the group.
190     * @param role
191     *            the role.
192     * @throws DataBackendException
193     *             if there was an error accessing the data backend.
194     * @throws UnknownEntityException
195     *             if user account, group or role is not present.
196     */
197    void revoke(User user, Group group, Role role) throws DataBackendException, UnknownEntityException;
198
199    /**
200     * Revokes by default all permissions from a Role and if flag is set
201     * all groups and users for this role
202     * 
203     * This method is used when deleting a Role.
204     * 
205     * @param role
206     *            the Role
207     * @param cascadeDelete
208     *             if <code>true </code> removes all groups and user for this role.
209     * @throws DataBackendException
210     *             if there was an error accessing the data backend.
211     * @throws UnknownEntityException
212     *             if the Role is not present.
213     */
214    void revokeAll( Role role, boolean cascadeDelete )
215        throws DataBackendException, UnknownEntityException;
216}