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.Group;
024import org.apache.fulcrum.security.util.DataBackendException;
025import org.apache.fulcrum.security.util.EntityExistsException;
026import org.apache.fulcrum.security.util.GroupSet;
027import org.apache.fulcrum.security.util.UnknownEntityException;
028
029/**
030 * A GroupManager performs {@link org.apache.fulcrum.security.entity.Group}
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 group from the
035 * storage and putting them into the
036 * {@link org.apache.fulcrum.security.entity.Group} 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 GroupManager extends Serializable
043{
044
045    /** Avalon role - used to id the component within the manager */
046    String ROLE = GroupManager.class.getName();
047
048    /**
049     * Construct a blank Group object.
050     *
051     * This method calls getGroupClass, and then creates a new object using the
052     * default constructor.
053     *
054     * @param <T> The group extending {@link Group}
055     * @return an object implementing Group interface.
056     * @throws DataBackendException
057     *             if the object could not be instantiated.
058     */
059    <T extends Group> T getGroupInstance() throws DataBackendException;
060
061    /**
062     * Construct a blank Group object.
063     *
064     * This method calls getGroupClass, and then creates a new object using the
065     * default constructor.
066     *
067     * @param <T> The group of type {@link Group}
068     * @param groupName
069     *            The name of the Group
070     *
071     * @return an object implementing Group interface.
072     * @throws DataBackendException
073     *             if the object could not be instantiated.
074     */
075    <T extends Group> T getGroupInstance(String groupName) throws DataBackendException;
076
077    /**
078     * Retrieve a Group object with specified name.
079     * 
080     *@param <T> The group of type {@link Group}
081     * @param name
082     *            the name of the Group.
083     * @return an object representing the Group with specified name.
084     * @throws DataBackendException
085     *             if there was an error accessing the data backend.
086     * @throws UnknownEntityException
087     *             if the group does not exist.
088     */
089    <T extends Group> T getGroupByName(String name) throws DataBackendException, UnknownEntityException;
090
091    /**
092     * Retrieve a Group object with specified Id.
093     *
094     * @param <T> Group type
095     * @param id
096     *            the Id of the Group.
097     *
098     * @return an object representing the Group with specified name.
099     *
100     * @exception UnknownEntityException
101     *                if the permission does not exist in the database.
102     * @exception DataBackendException
103     *                if there is a problem accessing the storage.
104     */
105    <T extends Group> T getGroupById(Object id) throws DataBackendException, UnknownEntityException;
106
107    /**
108     * Renames an existing Group.
109     *
110     * @param group
111     *            The object describing the group to be renamed.
112     * @param name
113     *            the new name for the group.
114     * @throws DataBackendException
115     *             if there was an error accessing the data backend.
116     * @throws UnknownEntityException
117     *             if the group does not exist.
118     */
119    void renameGroup(Group group, String name) throws DataBackendException, UnknownEntityException;
120
121    /**
122     * Removes a Group from the system.
123     *
124     * @param group
125     *            The object describing the group to be removed.
126     * @throws DataBackendException
127     *             if there was an error accessing the data backend.
128     * @throws UnknownEntityException
129     *             if the group does not exist.
130     */
131    void removeGroup(Group group) throws DataBackendException, UnknownEntityException;
132
133    /**
134     * Creates a new group with specified attributes.
135     *
136     * @param <T>
137     * @param group
138     *            the object describing the group to be created.
139     * @return the new Group object.
140     * @throws DataBackendException
141     *             if there was an error accessing the data backend.
142     * @throws EntityExistsException
143     *             if the group already exists.
144     */
145    <T extends Group> T addGroup(T group) throws DataBackendException, EntityExistsException;
146
147    /**
148     * Retrieves all groups defined in the system.
149     *
150     * @return the names of all groups defined in the system.
151     * @throws DataBackendException
152     *             if there was an error accessing the data backend.
153     */
154    GroupSet getAllGroups() throws DataBackendException;
155
156    /**
157     * Determines if the <code>Group</code> exists in the security system.
158     *
159     * @param group
160     *            a <code>Group</code> value
161     * @return true if the group exists in the system, false otherwise
162     * @throws DataBackendException
163     *             when more than one group with the same name exists.
164     */
165    boolean checkExists(Group group) throws DataBackendException;
166
167    /**
168     * Determines if a <code>Group</code> exists in the security system with the
169     * specified name.
170     *
171     * @param groupName
172     *            the name of a <code>Group</code> to check.
173     * @return true if the group exists in the system, false otherwise
174     * @throws DataBackendException
175     *             when more than one group with the same name exists.
176     */
177    boolean checkExists(String groupName) throws DataBackendException;
178}