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.content.FxPK;
036: import com.flexive.shared.exceptions.*;
037: import com.flexive.shared.security.*;
038:
039: import javax.ejb.Remote;
040: import java.util.ArrayList;
041: import java.util.Date;
042: import java.util.List;
043:
044: /**
045: * @author Gregor Schober (gregor.schober@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
046: */
047: @Remote
048: public interface AccountEngine {
049:
050: // For the loadRoles function
051: enum RoleLoadMode {
052: FROM_USER_ONLY, FROM_GROUPS_ONLY, ALL
053: }
054:
055: /**
056: * Perform a login
057: *
058: * @param username the username
059: * @param password the password
060: * @param takeOver the take over flag
061: * @throws FxLoginFailedException on errors
062: * @throws FxAccountInUseException on errors
063: */
064: void login(String username, String password, boolean takeOver)
065: throws FxLoginFailedException, FxAccountInUseException;
066:
067: /**
068: * Returns all currently active UserTickets.
069: *
070: * @return all active UserTickets
071: */
072: List<UserTicket> getActiveUserTickets();
073:
074: /**
075: * Logout function.
076: *
077: * @throws FxLogoutFailedException on errors
078: */
079: void logout() throws FxLogoutFailedException;
080:
081: /**
082: * Loads a user specified by its unique id.
083: * <p/>
084: * This function may be called by anyone and performs no security checks.
085: *
086: * @param id the unique id of the user to load
087: * be retrieved.
088: * @return the account
089: * @throws com.flexive.shared.exceptions.FxNotFoundException
090: * if the user does not exist
091: * @throws com.flexive.shared.exceptions.FxLoadException
092: * if the load failed
093: * @throws FxApplicationException on errors
094: */
095: Account load(final long id) throws FxApplicationException;
096:
097: /**
098: * Loads a user.
099: * <p/>
100: * This function may be called by anyone and performs no security checks.
101: *
102: * @param loginName the login name of the user to load
103: * @return the account
104: * @throws FxNotFoundException if the user does not exist
105: * @throws FxLoadException if the load failed
106: * @throws FxApplicationException on errors
107: */
108: Account load(final String loginName) throws FxApplicationException;
109:
110: /**
111: * Load the account that belongs to the given contact data
112: *
113: * @param contactDataPK contact data
114: * @return the account that belongs to the given contact data
115: * @throws FxApplicationException on errors loading the account or if no account exists for the contact data
116: */
117: Account loadForContactData(FxPK contactDataPK)
118: throws FxApplicationException;
119:
120: /**
121: * Gets the user ticket for the current request.
122: *
123: * @return the user ticket for the current request.
124: */
125: UserTicket getUserTicket();
126:
127: /**
128: * Gets the groups a user is assigned to.
129: * <p/>
130: * A user may only see the groups assigned to other users within his mandator.
131: * GLOBAL_SUPERVISOR may get the groups for all users.
132: *
133: * @param accountId the user to get the groupd for
134: * @return the groups a user is assigned to
135: * @throws FxLoadException if the load failed
136: * @throws FxNotFoundException if the user does not exist
137: * @throws FxNoAccessException if the caller lacks the permissions to load the groups
138: * @throws FxApplicationException on errors
139: */
140: UserGroupList getGroups(long accountId)
141: throws FxApplicationException;
142:
143: /**
144: * Gets the groups a user is assigned to.
145: * <p/>
146: * A user may only see the groups assigned to other users within his mandator.
147: * GLOBAL_SUPERVISOR may get the groups for all users.
148: *
149: * @param accountId the user to get the groupd for
150: * @return the groups a user is assigned to
151: * @throws FxLoadException if the load failed
152: * @throws FxNotFoundException if the user does not exist
153: * @throws FxNoAccessException if the caller lacks the permissions to load the groups
154: * @throws FxApplicationException on errors
155: */
156: ArrayList<UserGroup> getGroupList(long accountId)
157: throws FxApplicationException;
158:
159: /**
160: * Loads all roles that a user is assigned to.
161: * <p/>
162: * Users may only query roles of users within the same mandator domain.<br>
163: * GLOBAL_SUPERVISOR may get the roles of all users.
164: *
165: * @param accountId the unique user id to get the roles for
166: * @param mode MODE_USER: get all roles the USER himself is assigned to<br>
167: * MODE_GROUPS: get all roles from the groups that the user belongs to<br>
168: * MODE_ALL: get all roles the user belongs to from his groups, or direct assignment
169: * @return the roles assigned to the given user
170: * @throws FxLoadException if the load failed
171: * @throws FxNotFoundException if the user does not exist
172: * @throws FxNoAccessException if the caller lacks the permissions to load the roles
173: * @throws FxApplicationException on errors
174: */
175: Role[] getRoles(long accountId, RoleLoadMode mode)
176: throws FxApplicationException;
177:
178: /**
179: * Loads all roles that a user is assigned to.
180: * <p/>
181: * Users may only query roles of users within the same mandator domain.<br>
182: * GLOBAL_SUPERVISOR may get the roles of all users.
183: *
184: * @param accountId the unique user id to get the roles for
185: * @param mode MODE_USER: get all roles the USER himself is assigned to<br>
186: * MODE_GROUPS: get all roles from the groups that the user belongs to<br>
187: * MODE_ALL: get all roles the user belongs to from his groups, or direct assignment
188: * @return the roles assigned to the given user
189: * @throws FxLoadException if the load failed
190: * @throws FxNotFoundException if the user does not exist
191: * @throws FxNoAccessException if the caller lacks the permissions to load the roles
192: * @throws FxApplicationException on errors
193: */
194: public List<Role> getRoleList(long accountId, RoleLoadMode mode)
195: throws FxApplicationException;
196:
197: /**
198: * Creates a new user.
199: * <p/>
200: * Role and Groups can be added after creation.<br>
201: * Only callers in ROLE_USER_MANAGEMENTS may create users, and only for their mandatorId.<br>
202: * GLOBAL_SUPERVISOR may create users for all mandators.
203: *
204: * @param userName the name of the user, not unique
205: * @param loginName the unqiue (over all mandators) login name of the user
206: * @param password the password of the user
207: * @param email the email of the user
208: * @param lang the language of the user
209: * @param mandatorId the mandatorId of the user
210: * @param isActive the active flag of the user
211: * @param isConfirmed the confirmed flag of the user
212: * @param validFrom the valid from date
213: * @param validTo the valid to date
214: * @param defaultNode the desired start node in the tree for the user
215: * @param description description for the user
216: * @param allowMultiLogin if true more than one client may login with this account at the same time
217: * @param checkUserRoles perform checks if the calling user is a member of valid roles, should only be disabled if
218: * called from run-once scripts or the like
219: * @return the ID of the created user
220: * @throws FxCreateException if the create failed
221: * @throws FxInvalidParameterException if a parameter is invalid (mandatorId, guiLanguage, contentLanguage)
222: * @throws FxNoAccessException if the caller lacks the permissions to create the user
223: * @throws FxEntryExistsException if a user with the given login name already exists
224: * @throws FxApplicationException on errors
225: */
226: long create(String userName, String loginName, String password,
227: String email, long lang, long mandatorId, boolean isActive,
228: boolean isConfirmed, Date validFrom, Date validTo,
229: long defaultNode, String description,
230: boolean allowMultiLogin, boolean checkUserRoles)
231: throws FxApplicationException;
232:
233: /**
234: * Removes a user.
235: * <p/>
236: * The caller must be in role AccountManagement to remove a user belonging to his mandator.<br>
237: * GlobalSupervisor may remove users belonging to any mandator.<br>
238: * USER_GUEST and USER_GLOBAL_SUPERVISOR may not be removed in any case.
239: *
240: * @param accountId the id of the user to remove
241: * @throws FxNotFoundException if the given user does not exist
242: * @throws FxNoAccessException if the caller lacks the permissions to remove the user
243: * @throws FxRemoveException if the remove failed
244: * @throws FxApplicationException on errors
245: */
246: void remove(long accountId) throws FxApplicationException;
247:
248: /**
249: * Sets the roles a user is in.
250: * To set roles the caller must be in role AccountManagement, and may only update users belonging
251: * to his mandator. GlobalSupervisor may set the roles for all users in the system.
252: *
253: * @param accountId the user to set the roles for
254: * @param roles the roles to set, the array may contain undefined roles (=0) values (which are skipped) to make it
255: * easier to build the list. <br>
256: * Duplicated roles are discarded.
257: * @throws FxNoAccessException if the calling user lacks the permissions to set the roles for the given group
258: * @throws FxNotFoundException if the group does not exist
259: * @throws FxUpdateException if setting the roles failed
260: * @throws FxApplicationException on errors
261: */
262: void setRoles(long accountId, long... roles)
263: throws FxApplicationException;
264:
265: /**
266: * Sets the roles a user is in.
267: * <p/>
268: * To set roles the caller must be in role ROLE_ROLE_MANAGEMENT, and may only update users belonging
269: * to his mandator. GROUP_GLOBAL_SUPERVISOR may set the roles for all users in the system.
270: *
271: * @param accountId the user to set the roles for
272: * @param roles the roles to set, the array may contain ROLE_UNDEFINED (=0) values (which are skipped) to make it
273: * easier to build the list. <br>
274: * Duplicated roles are discarded.
275: * @throws FxNoAccessException if the calling user lacks the permissions to set the roles for the given group
276: * @throws FxNotFoundException if the group does not exist
277: * @throws FxUpdateException if setting the roles failed
278: * @throws FxApplicationException on errors
279: */
280: void setRoleList(long accountId, List<Role> roles)
281: throws FxApplicationException;
282:
283: /**
284: * Sets the groups a user defined by its unique id belongs to.
285: * <p/>
286: * The caller must be in role ROLE_GROUP_MANAGEMENT or AccountManagement, and may
287: * only update users belonging to his mandator. He may only assign groups that also belong to
288: * his mandator, plus GROUP_EVERYONE and GROUP_OWNER.<br>
289: * GROUP_GLOBAL_SUPERVISOR may set all groups for all users.
290: *
291: * @param accountId the accountId to get the lifecycle for
292: * @param groups the groups the user should belong to
293: * @throws FxNoAccessException if the calling user lacks the permissions to set the groups
294: * @throws FxNotFoundException if the user does not exist
295: * @throws FxUpdateException if setting the groups failed
296: * @throws FxApplicationException on errors
297: */
298: void setGroups(long accountId, long[] groups)
299: throws FxApplicationException;
300:
301: void setGroupList(long accountId, List<UserGroup> groups)
302: throws FxApplicationException;
303:
304: /**
305: * Loads all users matching the parameters.
306: * <p/>
307: * The Name, LoginName and Email are compared case insensitive.<br>
308: * The caller may only search users within its own mandator<br>.
309: * Users in the group GROUP_GLOBAL_SUPERVISOR may load users within all mandators.
310: *
311: * @param name (a substring of) the name of the users to load, or null if the name should not filter the result
312: * @param loginName (a substring of) the login name of the users to load, or null if the login name should not filter
313: * the result
314: * @param email (a substring of) the email of the users to load, or null if the email should not filter the result
315: * @param isActive true|false to restrict by the active flag, or null if the active flag should not filter the result
316: * @param isConfirmed true | false to restrict by the confirmed flag, or null if the confirmed flag should not filter
317: * the result
318: * @param mandatorId the function returns only users belonging to this mandator. If set to null the mandator of the
319: * calling user is used. GROUP_GLOBAL_SUPERVISOR may use -1 to load users within all mandators, all other callers may
320: * only load users within the mandator they belong to, or a FxNoAccessException is thrown.
321: * @param isInRole if set the function only loads users which are in all specified roles. The result will be empty
322: * if a invalid role id is used.
323: * @param isInGroup if set the function only loads users which belong to all specified groups. The result will be empty
324: * if a invalid group id is used.
325: * @param startIdx the start index in the result, 0 based
326: * @param maxEntries the maximum amount of users returned by the funktion (-1 for all), starting at startIdx
327: * @return all matching accounts
328: * @throws FxNoAccessException if the caller may not load users of the specified mandator
329: * @throws FxLoadException if the load failed
330: * @throws FxApplicationException on errors
331: */
332: Account[] loadAll(String name, String loginName, String email,
333: Boolean isActive, Boolean isConfirmed, Long mandatorId,
334: int[] isInRole, long[] isInGroup, int startIdx,
335: int maxEntries) throws FxApplicationException;
336:
337: /**
338: * Loads all accounts of a mandator.
339: *
340: * @param mandatorId the mandator ID
341: * @return all accounts of the mandator.
342: * @throws FxApplicationException on errors
343: */
344: Account[] loadAll(long mandatorId) throws FxApplicationException;
345:
346: /**
347: * Returns number of users matching the parameters.
348: * <p/>
349: * The caller may only search users within its own mandator<br>.
350: * Users in the group GROUP_GLOBAL_SUPERVISOR may load users within all mandators.
351: *
352: * @param name (a substring of) the name of the users to load,
353: * or null if the name should not filter the result
354: * @param loginName (a substring of) the login name of the users to load,
355: * or null if the login name should not filter the result
356: * @param email (a substring of) the email of the users to load,
357: * or null if the email should not filter the result
358: * @param isActive true|false to restrict by the active flag,
359: * or null if the active flag should not filter the result
360: * @param isConfirmed true | false to restrict by the confirmed flag,
361: * or null if the confirmed flag should not filter the result
362: * @param mandatorId the function returns only users belonging to this mandator. If set to null the mandator of the
363: * calling user is used. GROUP_GLOBAL_SUPERVISOR may use -1 to load users within all mandators,
364: * all other callers may only load users within the mandator they belong to,
365: * or a FxNoAccessException is thrown.
366: * @param isInRole if set the function only loads users which are in all specified roles.
367: * The result will be empty if an invalid role id is used.
368: * @param isInGroup if set the function only loads users which belong to all specified groups.
369: * The result will be empty if a invalid group id is used.
370: * @return The number of users matching the given parameters
371: * @throws FxNoAccessException if the caller may not load users of the specified mandator
372: * @throws FxLoadException if the load failed
373: * @throws FxApplicationException on errors
374: */
375: int getAccountMatches(String name, String loginName, String email,
376: Boolean isActive, Boolean isConfirmed, Long mandatorId,
377: int[] isInRole, long[] isInGroup)
378: throws FxApplicationException;
379:
380: /**
381: * Updates the data of a user specified by its unique id.
382: * <p/>
383: * Only callers in ROLE_USER_MANAGEMENTS may create users, and only for their mandator.<br>
384: * GLOBAL_SUPERVISOR may create users for all mandators.<br>
385: * Any user can change HIS OWN password, email, contentLanguage and guiLanguage using this function,
386: * but setting any other parameters will cause a FxNoAccessException.
387: *
388: * @param accountId the unique id of the user to update
389: * @param password the new password, or null if the old value should be kept
390: * @param defaultNode the new defaultNode, or null if the old value should be kept
391: * @param name the new name (not unique), or null if the old value should be kept
392: * @param loginName the new login name (unqiue over all mandators), or null if the old value should be kept
393: * @param email the new email, or null if the old value should be kept
394: * @param isConfirmed the new confirmed state, or null if the old value should be kept
395: * @param isActive the new active state, or null if the old value should be kept
396: * @param validTo the new valid to date, or null if the old value should be kept
397: * @param validFrom the new valid from date, or null if the old value should be kept
398: * @param lang the new language, or null if the old value should be kept
399: * @param description the new description, or null if the old value should be kept
400: * @param allowMultiLogin true if the account may be active more than once at the same
401: * time, may be null to keep the old value
402: * @param contactDataId id of the contact data
403: * @throws FxEntryExistsException if a user with the given login name already exists
404: * @throws FxNoAccessException if the caller lacks the permissions to update the user
405: * @throws FxUpdateException if the update failed
406: * @throws FxNotFoundException if the user to update does not exist
407: * @throws FxInvalidParameterException if a parameter was invalid
408: * @throws FxApplicationException on errors
409: */
410:
411: void update(long accountId, String password, Long defaultNode,
412: String name, String loginName, String email,
413: Boolean isConfirmed, Boolean isActive, Date validFrom,
414: Date validTo, Long lang, String description,
415: Boolean allowMultiLogin, Long contactDataId)
416: throws FxApplicationException;
417:
418: /**
419: * Updates some personal data of the specified user
420: *
421: * @param accountId the user to update the data for
422: * @param password the new password to assign
423: * @param name user name
424: * @param loginName the new login name to assign
425: * @param email the new e-mail address to assign
426: * @param lang the new language to assign
427: * @throws FxApplicationException on errors
428: */
429: void updateUser(long accountId, String password, String name,
430: String loginName, String email, Long lang)
431: throws FxApplicationException;
432:
433: /**
434: * Returns all users assigned to a group defined by its unique id.
435: * <p/>
436: * This function provides the parameters startIdx and maxEntries to allow a page-view of the users
437: * in the GUI. This is neccesarry since a group may contain many thousands of users, which should
438: * not be transfered at once to the client.<br>
439: * The caller may only see groups of the mandator he belongs to plus GROUP_EVERYONE and GROUPE_PRIVATE.<br>
440: * GLOBAL_SUPERVISOR may see the groups/users of all mandators.
441: *
442: * @param groupId the group to get the users for
443: * @param startIdx the start index in the result, 0 based
444: * @param maxEntries the maximum amount of users returned by the funktion (-1 for all), starting at startIdx
445: * @return all users assigned to the given group
446: * @throws FxApplicationException on errors
447: * @throws FxNoAccessException if the caller may not see the group
448: * @throws FxLoadException if the get failed
449: * @throws FxNotFoundException if the group does not exist
450: */
451: Account[] getAssignedUsers(long groupId, int startIdx,
452: int maxEntries) throws FxApplicationException;
453:
454: /**
455: * Returns the amount of users within a group.
456: *
457: * @param groupId the group to return the assignment count for
458: * @param includeInvisible a group may contain users belonging to a foreign mandator, which are invisible
459: * for the caller (except GLOBAL_SUPERVISOR). This parameter specifies wether to count those invisible
460: * users or not.
461: * @return the amount of users belonging to the group
462: * @throws FxApplicationException on errors
463: * @throws FxLoadException if the load of the count failed
464: */
465: long getAssignedUsersCount(long groupId, boolean includeInvisible)
466: throws FxApplicationException;
467:
468: /**
469: * Retrives all ACLs assigned to a given account.
470: * <p/>
471: * A empty resultset is returned if the account does not exist.<br>
472: * A user may only see his own ACLAssignment.<br>
473: * MANDATOR_FLEXIVE may retrive ACLAssignments for all his users.<br>
474: * GLOBAL_SUPERVISOR may retrive the ACLAssignments of all users.
475: *
476: * @param accountId the user to get the ACLAssignments for
477: * @return the ACLAssignments of the user
478: * @throws FxLoadException if the function failed to load the ACLAssignments
479: * @throws FxNoAccessException if the calling user may not access the ACLAssignment of the given user
480: * @throws FxApplicationException on errors
481: */
482: ACLAssignment[] loadAccountAssignments(long accountId)
483: throws FxApplicationException;
484:
485: /**
486: * Create contact data for all accounts that dont have them
487: *
488: * @throws FxApplicationException on errors
489: */
490: void fixContactData() throws FxApplicationException;
491: }
|