001: /***************************************************************
002: * This file is part of the [fleXive](R) project.
003: *
004: * Copyright (c) 1999-2008
005: * UCS - unique computing solutions gmbh (http://www.ucs.at)
006: * All rights reserved
007: *
008: * The [fleXive](R) project is free software; you can redistribute
009: * it and/or modify it under the terms of the GNU General Public
010: * License as published by the Free Software Foundation;
011: * either version 2 of the License, or (at your option) any
012: * later version.
013: *
014: * The GNU General Public License can be found at
015: * http://www.gnu.org/copyleft/gpl.html.
016: * A copy is found in the textfile GPL.txt and important notices to the
017: * license from the author are found in LICENSE.txt distributed with
018: * these libraries.
019: *
020: * This library is distributed in the hope that it will be useful,
021: * but WITHOUT ANY WARRANTY; without even the implied warranty of
022: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
023: * GNU General Public License for more details.
024: *
025: * For further information about UCS - unique computing solutions gmbh,
026: * please see the company website: http://www.ucs.at
027: *
028: * For further information about [fleXive](R), please see the
029: * project website: http://www.flexive.org
030: *
031: *
032: * This copyright notice MUST APPEAR in all copies of the file!
033: ***************************************************************/package com.flexive.shared.interfaces;
034:
035: import com.flexive.shared.exceptions.*;
036: import com.flexive.shared.security.Role;
037: import com.flexive.shared.security.RoleList;
038: import com.flexive.shared.security.UserGroup;
039: import com.flexive.shared.security.UserGroupList;
040:
041: import javax.ejb.Remote;
042: import java.util.List;
043:
044: /**
045: * Interface to the user group engine.
046: *
047: * @author Gregor Schober (gregor.schober@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
048: */
049: @Remote
050: public interface UserGroupEngine {
051:
052: /**
053: * Loads a group defined by its unique id.
054: * <p/>
055: * No permission checks are performed<br>
056: *
057: * @param groupId the unique id of the group to load
058: * @return the requested user group
059: * @throws FxApplicationException TODO
060: * @throws com.flexive.shared.exceptions.FxNoAccessException
061: * if the user may not access the group
062: * @throws com.flexive.shared.exceptions.FxNotFoundException
063: * if the group does not exist
064: * @throws com.flexive.shared.exceptions.FxLoadException
065: * if the load failed
066: */
067: UserGroup load(long groupId) throws FxApplicationException;
068:
069: /**
070: * Load the user group that contains all users of a given mandator
071: *
072: * @param mandatorId mandator
073: * @return UserGroup containing all users of the mandator
074: * @throws FxApplicationException on errors
075: */
076: public UserGroup loadMandatorGroup(long mandatorId)
077: throws FxApplicationException;
078:
079: /**
080: * Loads all groups belonging to a specific mandator, plus GROUP_EVERYONE and GROUP_OWNER.
081: * <p/>
082: * Specify -1 t load all groups within the system (all mandators).
083: *
084: * @param mandatorId the mandator id to load the groups for, or -1 to load all groups
085: * @return all groups belonging to the mandator
086: * @throws FxApplicationException TODO
087: * @throws FxNoAccessException If the calling user may not access the groups of the given mandator
088: * @throws FxLoadException if the load failed
089: */
090: UserGroupList loadAll(long mandatorId)
091: throws FxApplicationException;
092:
093: /**
094: * Creates a new group for a specific mandator.
095: * <p/>
096: * A user may only create groups for the mandator he belongs to, and only if he is in the role
097: * ROLE_GROUP_MANAGEMENT.
098: * Global supervisors are a exception and may create groups for all mandators.
099: *
100: * @param name the unique name for the group
101: * @param color the color of the group as 7 digit string holding the RGB value, eg '#FF0000' for pure red,
102: * or the name of a CSS class
103: * @param mandatorId the mandator the group belongs to
104: * @return the created group's ID
105: * @throws FxApplicationException TODO
106: * @throws FxNoAccessException if the calling user lacks the permissions to create the group
107: * @throws com.flexive.shared.exceptions.FxEntryExistsException
108: * if a group with the given name exists
109: * @throws com.flexive.shared.exceptions.FxInvalidParameterException
110: * if a parameter was invalid (name,color,mandator)
111: * @throws com.flexive.shared.exceptions.FxCreateException
112: * if the create failed
113: */
114: int create(String name, String color, long mandatorId)
115: throws FxApplicationException;
116:
117: /**
118: * Updates a group defined by its unique id.
119: * <p/>
120: * Users may only update groups of the mandator they belong to if they are in role
121: * ROLE_GROUP_MANAGEMENT.<br>
122: * Global supervisors may update the groups of all mandators.
123: *
124: * @param groupId The group that should be updated
125: * @param color the color of the group as 6 digit RGB value (eg 'FF0000' for pure red), or null to keep the old value
126: * @param name the new name of the group, or null to keep the old value
127: * @throws FxApplicationException TODO
128: * @throws FxNotFoundException if the group to update does not exist
129: * @throws FxNoAccessException if the user lacks the permissions to update the group
130: * @throws FxUpdateException if the update failed
131: * @throws FxEntryExistsException if a group with the desired new name does already exist
132: * @throws FxInvalidParameterException if a parameter was invalid (eg. the color format)
133: */
134: void update(long groupId, String name, String color)
135: throws FxApplicationException;
136:
137: /**
138: * Removes a group defined by its unique id.
139: * <p/>
140: * Users may only remove groups belonging to their mandator, and only if they are in
141: * ROLE_GROUP_MANAGEMENT.<br>
142: * Global supervisors may remove groups of all mandators.
143: * The groups GROUP_EVERYONE and GROUP_OWNER may not be removed in any case.
144: *
145: * @param groupId the unqiue id of the group to remove
146: * @throws FxApplicationException TODO
147: * @throws FxNoAccessException if the user lacks the permissions to remove the group
148: * @throws FxNotFoundException if the group does not exist
149: * @throws FxRemoveException if the remove failed
150: */
151: void remove(long groupId) throws FxApplicationException;
152:
153: /**
154: * Sets the roles a group is in.
155: * <p/>
156: * To set roles the caller must be in role ROLE_ROLE_MANAGEMENT, and may only update groups belonging
157: * to his mandator.<br>
158: * GROUP_GLOBAL_SUPERVISOR may set the roles for groups of all users.<br>
159: *
160: * @param groupId the group to set the roles for
161: * @param roles the roles to set
162: * @throws FxApplicationException TODO
163: * @throws FxNoAccessException if the calling user lacks the permissions to set the roles for the given group
164: * @throws FxNotFoundException if the group does not exist
165: * @throws FxUpdateException if setting the roles failed
166: */
167: void setRoles(long groupId, long[] roles)
168: throws FxApplicationException;
169:
170: /**
171: * Sets the roles a group is in.
172: * <p/>
173: * To set roles the caller must be in role ROLE_ROLE_MANAGEMENT, and may only update groups belonging
174: * to his mandator.<br>
175: * GROUP_GLOBAL_SUPERVISOR may set the roles for groups of all users.<br>
176: *
177: * @param groupId the group to set the roles for
178: * @param roles the roles to set
179: * @throws FxApplicationException TODO
180: * @throws FxNoAccessException if the calling user lacks the permissions to set the roles for the given group
181: * @throws FxNotFoundException if the group does not exist
182: * @throws FxUpdateException if setting the roles failed
183: */
184: void setRoles(long groupId, List<Role> roles)
185: throws FxApplicationException;
186:
187: /**
188: * Gets all roles that are assigned to a group.
189: * <p/>
190: * The caller may see the role assignments for all groups belonging to his mandator.<br>
191: * GLOBAL_SUPERVISOR may see the role assignments of all groups.
192: *
193: * @param groupId the group to get the assigned roles for
194: * @return a list of the roles that ate assigned to the group
195: * @throws FxApplicationException TODO
196: * @throws FxNoAccessException if the caller lacks the permissions to get the roles
197: * @throws FxNotFoundException if the group does not exist
198: * @throws FxLoadException if the function failed to load the data
199: */
200: RoleList getRoles(long groupId) throws FxApplicationException;
201:
202: /**
203: * Rebuild the mandator groups
204: *
205: * @throws FxApplicationException on errors
206: */
207: public void rebuildMandatorGroups() throws FxApplicationException;
208:
209: }
|