001package org.apache.fulcrum.security;
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 */
021import java.io.Serializable;
022
023import org.apache.fulcrum.security.entity.Permission;
024import org.apache.fulcrum.security.util.DataBackendException;
025import org.apache.fulcrum.security.util.EntityExistsException;
026import org.apache.fulcrum.security.util.PermissionSet;
027import org.apache.fulcrum.security.util.UnknownEntityException;
028
029/**
030 * A PermissionManager performs {@link org.apache.fulcrum.security.entity.Permission}
031 * objects related tasks on behalf of the
032 * {@link org.apache.fulcrum.security.BaseSecurityService}.
033 *
034 * The responsibilities of this class include loading data of an permission from the
035 * storage and putting them into the
036 * {@link org.apache.fulcrum.security.entity.Permission} objects, saving those data
037 * to the permanent storage.
038 *
039 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
040 * @version $Id$
041 */
042public interface PermissionManager extends Serializable
043{
044
045    /** Avalon role - used to id the component within the manager */
046    String ROLE = PermissionManager.class.getName();
047
048    /**
049     * Construct a blank Permission object.
050     *
051     * This method calls getPermissionClass, and then creates a new object using
052     * the default constructor.
053     *
054     * @param <T> permission type
055     * @return an object implementing Permission interface.
056     * @throws DataBackendException
057     *                          if there was an error accessing the data backend. 
058     */
059    <T extends Permission> T getPermissionInstance() throws DataBackendException;
060
061    /**
062     * Construct a blank Permission object.
063     *
064     * This method calls getPermissionClass, and then creates a new object using
065     * the default constructor.
066     * 
067     * @param <T> permission type
068     * @param permName
069     *            The name of the Permission
070     *
071     * @return an object implementing Permission interface.
072     * @throws DataBackendException
073     *                          if there was an error accessing the data backend. 
074     */
075    <T extends Permission> T getPermissionInstance(String permName) throws DataBackendException;
076
077    /**
078     * Retrieve a Permission object with specified name.
079     * 
080     * @param <T> permission type
081     * @param name
082     *            the name of the Permission.
083     * @return an object representing the Permission with specified name.
084     * @throws DataBackendException
085     *             if there was an error accessing the data backend.
086     * @throws UnknownEntityException
087     *             if the permission does not exist.
088     */
089    <T extends Permission> T getPermissionByName(String name) throws DataBackendException, UnknownEntityException;
090
091    /**
092     * Retrieve a Permission object with specified Id.
093     * 
094     * @param <T> permission type
095     *
096     * @param id
097     *            the Id of the Permission.
098     *
099     * @return an object representing the Permission with specified name.
100     *
101     * @exception UnknownEntityException
102     *                if the permission does not exist in the database.
103     * @exception DataBackendException
104     *                if there is a problem accessing the storage.
105     */
106    <T extends Permission> T getPermissionById(Object id) throws DataBackendException, UnknownEntityException;
107
108    /**
109     * Retrieves all permissions defined in the system.
110     *
111     * @return the names of all permissions defined in the system.
112     * @throws DataBackendException
113     *             if there was an error accessing the data backend.
114     */
115    PermissionSet getAllPermissions() throws DataBackendException;
116
117    /**
118     * Creates a new permission with specified attributes.
119     *
120     * @param permission
121     *            The object describing the permission to be created.
122     * @return the new Permission object.
123     * @throws DataBackendException
124     *             if there was an error accessing the data backend.
125     * @throws EntityExistsException
126     *             if the permission already exists.
127     */
128    <T extends Permission> T addPermission(T permission) throws DataBackendException, EntityExistsException;
129
130    /**
131     * Removes a Permission from the system.
132     *
133     * @param permission
134     *            The object describing the permission to be removed.
135     * @throws DataBackendException
136     *             if there was an error accessing the data backend.
137     * @throws UnknownEntityException
138     *             if the permission does not exist.
139     */
140    void removePermission(Permission permission) throws DataBackendException, UnknownEntityException;
141
142    /**
143     * Renames an existing Permission.
144     *
145     * @param permission
146     *            The object describing the permission to be renamed.
147     * @param name
148     *            the new name for the permission.
149     * @throws DataBackendException
150     *             if there was an error accessing the data backend.
151     * @throws UnknownEntityException
152     *             if the permission does not exist.
153     */
154    void renamePermission(Permission permission, String name) throws DataBackendException, UnknownEntityException;
155
156    /**
157     * Determines if the <code>Permission</code> exists in the security system.
158     *
159     * @param permission
160     *            a <code>Permission</code> value
161     * @return true if the permission exists in the system, false otherwise
162     * @throws DataBackendException
163     *             when more than one Permission with the same name exists.
164     */
165    boolean checkExists(Permission permission) throws DataBackendException;
166
167    /**
168     * Determines if a <code>Permission</code> exists in the security system
169     * with the specified name.
170     *
171     * @param permissionName
172     *            the name of a <code>Permission</code> to check
173     * @return true if the permission exists in the system, false otherwise
174     * @throws DataBackendException
175     *             when more than one Permission with the same name exists.
176     */
177    boolean checkExists(String permissionName) throws DataBackendException;
178}