com.flexive.shared.interfaces
Interface AccountEngine

All Known Subinterfaces:
AccountEngineLocal

public interface AccountEngine

Account management

Author:
Gregor Schober (gregor.schober@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)

Method Summary
 void addGroup(long accountId, long groupId)
          Adds a usergroup to a user.
 void addRole(long accountId, long roleId)
          Adds a role for a user.
 long create(Account account, java.lang.String password)
          Creates a new user.
 long create(Account account, java.lang.String password, boolean hashPassword)
          Creates a new user.
 void fixContactData()
          Create contact data for all accounts that dont have them
 java.lang.String generateRestToken()
          Generate a new REST API token, overwriting the previous one if it existed.
 int getAccountMatches(java.lang.String name, java.lang.String loginName, java.lang.String email, java.lang.Boolean isActive, java.lang.Boolean isConfirmed, java.lang.Long mandatorId, int[] isInRole, long[] isInGroup)
          Returns number of users matching the parameters.
 java.util.List<UserTicket> getActiveUserTickets()
          Returns all currently active UserTickets.
 java.util.List<Account> getAssignedUsers(long groupId, int startIdx, int maxEntries)
          Returns all users assigned to a group defined by its unique id.
 long getAssignedUsersCount(long groupId, boolean includeInvisible)
          Returns the amount of users within a group.
 java.util.List<UserGroup> getGroups(long accountId)
          Gets the groups a user is assigned to.
 UserTicket getGuestTicket()
          Returns a guest user ticket.
 java.lang.String getPasswordHash(long accountId)
          Load the password hash for the given account ID.
 java.util.List<Role> getRoles(long accountId, RoleLoadMode mode)
          Loads all roles that a user is assigned to.
 UserTicket getUserTicket()
          Gets the user ticket for the current request.
 Account load(long id)
          Loads a user specified by its unique id.
 Account load(java.lang.String loginName)
          Loads a user.
 java.util.List<ACLAssignment> loadAccountAssignments(long accountId)
          Retrieves all ACLs assigned to a given account.
 java.util.List<Account> loadAll()
          Loads all accounts.
 java.util.List<Account> loadAll(long mandatorId)
          Loads all accounts of a mandator.
 java.util.List<Account> loadAll(java.lang.String name, java.lang.String loginName, java.lang.String email, java.lang.Boolean isActive, java.lang.Boolean isConfirmed, java.lang.Long mandatorId, int[] isInRole, long[] isInGroup, int startIdx, int maxEntries)
          Loads all users matching the parameters.
 Account loadForContactData(FxPK contactDataPK)
          Load the account that belongs to the given contact data
 void login(java.lang.String username, java.lang.String password, boolean takeOver)
          Perform a login
 void loginByRestToken(java.lang.String token)
          Login using a REST API token.
 boolean loginCheck(java.lang.String username, java.lang.String password, UserTicket currentTicket)
          Check the password of the currently logged-in user.
 void logout()
          Logout function.
 void remove(long accountId)
          Removes a user.
 void setGroups(long accountId, java.util.List<UserGroup> groups)
          Sets the groups a user defined by its unique id belongs to.
 void setGroups(long accountId, long... groups)
          Sets the groups a user defined by its unique id belongs to.
 void setRoles(long accountId, java.util.List<Role> roles)
          Sets the roles a user is in.
 void setRoles(long accountId, long... roles)
          Sets the roles a user is in.
 void update(long accountId, java.lang.String password, java.lang.Long defaultNode, java.lang.String name, java.lang.String loginName, java.lang.String email, java.lang.Boolean isConfirmed, java.lang.Boolean isActive, java.util.Date validFrom, java.util.Date validTo, java.lang.Long lang, java.lang.String description, java.lang.Boolean allowMultiLogin, java.lang.Long contactDataId)
          Updates the data of a user specified by its unique id.
 void updateUser(long accountId, java.lang.String password, boolean hashPassword, java.lang.String name, java.lang.String loginName, java.lang.String email, java.lang.Long lang)
          Updates some personal data of the specified user
 void updateUser(long accountId, java.lang.String password, java.lang.String name, java.lang.String loginName, java.lang.String email, java.lang.Long lang)
          Updates some personal data of the specified user
 

Method Detail

login

void login(java.lang.String username,
           java.lang.String password,
           boolean takeOver)
           throws FxLoginFailedException,
                  FxAccountInUseException
Perform a login

Parameters:
username - the username
password - the password
takeOver - the take over flag
Throws:
FxLoginFailedException - on errors
FxAccountInUseException - on errors

loginCheck

boolean loginCheck(java.lang.String username,
                   java.lang.String password,
                   UserTicket currentTicket)
                   throws FxLoginFailedException,
                          FxDbException
Check the password of the currently logged-in user. The match can only be performed if the current UserTicket matches with the ID of the login account's name

Parameters:
username - the user name
password - the password
currentTicket - the current UserTicket to check
Returns:
returns true if the password matches
Throws:
FxLoginFailedException - on errors
FxDbException - on db errors

getActiveUserTickets

java.util.List<UserTicket> getActiveUserTickets()
Returns all currently active UserTickets.

Returns:
all active UserTickets

logout

void logout()
            throws FxLogoutFailedException
Logout function.

Throws:
FxLogoutFailedException - on errors

load

Account load(long id)
             throws FxApplicationException
Loads a user specified by its unique id.

This function may be called by anyone and performs no security checks.

Parameters:
id - the unique id of the user to load be retrieved.
Returns:
the account
Throws:
FxNotFoundException - if the user does not exist
FxLoadException - if the load failed
FxApplicationException - on errors

load

Account load(java.lang.String loginName)
             throws FxApplicationException
Loads a user.

This function may be called by anyone and performs no security checks.

Parameters:
loginName - the login name of the user to load
Returns:
the account
Throws:
FxNotFoundException - if the user does not exist
FxLoadException - if the load failed
FxApplicationException - on errors

loadForContactData

Account loadForContactData(FxPK contactDataPK)
                           throws FxApplicationException
Load the account that belongs to the given contact data

Parameters:
contactDataPK - contact data
Returns:
the account that belongs to the given contact data
Throws:
FxApplicationException - on errors loading the account or if no account exists for the contact data

getPasswordHash

java.lang.String getPasswordHash(long accountId)
                                 throws FxApplicationException
Load the password hash for the given account ID. May only be called by global supervisors.

Parameters:
accountId - the account ID
Returns:
the hashed password
Throws:
FxApplicationException - on errors
Since:
3.1.6

getUserTicket

UserTicket getUserTicket()
Gets the user ticket for the current request.

Returns:
the user ticket for the current request.

getGuestTicket

UserTicket getGuestTicket()
Returns a guest user ticket.

Returns:
a guest user ticket.
Since:
3.1

getGroups

java.util.List<UserGroup> getGroups(long accountId)
                                    throws FxApplicationException
Gets the groups a user is assigned to.

A user may only see the groups assigned to other users within his mandator. GLOBAL_SUPERVISOR may get the groups for all users.

Parameters:
accountId - the user to get the groupd for
Returns:
the groups a user is assigned to
Throws:
FxLoadException - if the load failed
FxNotFoundException - if the user does not exist
FxNoAccessException - if the caller lacks the permissions to load the groups
FxApplicationException - on errors

getRoles

java.util.List<Role> getRoles(long accountId,
                              RoleLoadMode mode)
                              throws FxApplicationException
Loads all roles that a user is assigned to.

Users may only query roles of users within the same mandator domain.
GLOBAL_SUPERVISOR may get the roles of all users.

Parameters:
accountId - the unique user id to get the roles for
mode - MODE_USER: get all roles the USER himself is assigned to
MODE_GROUPS: get all roles from the groups that the user belongs to
MODE_ALL: get all roles the user belongs to from his groups, or direct assignment
Returns:
the roles assigned to the given user
Throws:
FxLoadException - if the load failed
FxNotFoundException - if the user does not exist
FxNoAccessException - if the caller lacks the permissions to load the roles
FxApplicationException - on errors

create

long create(Account account,
            java.lang.String password)
            throws FxApplicationException
Creates a new user.

Role and Groups can be added after creation.
Only callers in ROLE_USER_MANAGEMENTS may create users, and only for their mandatorId.
GLOBAL_SUPERVISOR may create users for all mandators.

Parameters:
account - the account to be created. Use an AccountEdit object for easier account creation.
password - the user's password
Returns:
the ID of the created user
Throws:
FxCreateException - if the create failed
FxInvalidParameterException - if a parameter is invalid (mandatorId, guiLanguage, contentLanguage)
FxNoAccessException - if the caller lacks the permissions to create the user
FxEntryExistsException - if a user with the given login name already exists
FxApplicationException - on errors

create

long create(Account account,
            java.lang.String password,
            boolean hashPassword)
            throws FxApplicationException
Creates a new user.

Role and Groups can be added after creation.
Only callers in ROLE_USER_MANAGEMENTS may create users, and only for their mandatorId.
GLOBAL_SUPERVISOR may create users for all mandators.

Parameters:
account - the account to be created. Use an AccountEdit object for easier account creation.
password - the user's password
hashPassword - whether the password should be hashed (set to false for importing users, otherwise this should always be true)
Returns:
the ID of the created user
Throws:
FxCreateException - if the create failed
FxInvalidParameterException - if a parameter is invalid (mandatorId, guiLanguage, contentLanguage)
FxNoAccessException - if the caller lacks the permissions to create the user
FxEntryExistsException - if a user with the given login name already exists
FxApplicationException - on errors
Since:
3.1.6

remove

void remove(long accountId)
            throws FxApplicationException
Removes a user.

The caller must be in role AccountManagement to remove a user belonging to his mandator.
GlobalSupervisor may remove users belonging to any mandator.
USER_GUEST and USER_GLOBAL_SUPERVISOR may not be removed in any case.

Parameters:
accountId - the id of the user to remove
Throws:
FxNotFoundException - if the given user does not exist
FxNoAccessException - if the caller lacks the permissions to remove the user
FxRemoveException - if the remove failed
FxApplicationException - on errors

setRoles

void setRoles(long accountId,
              long... roles)
              throws FxApplicationException
Sets the roles a user is in. To set roles the caller must be in role AccountManagement, and may only update users belonging to his mandator. GlobalSupervisor may set the roles for all users in the system.

Parameters:
accountId - the user to set the roles for
roles - the roles to set, the array may contain undefined roles (=0) values (which are skipped) to make it easier to build the list.
Duplicated roles are discarded.
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the roles for the given group
FxNotFoundException - if the group does not exist
FxUpdateException - if setting the roles failed
FxApplicationException - on errors

addRole

void addRole(long accountId,
             long roleId)
             throws FxApplicationException
Adds a role for a user. To set roles the caller must be in role AccountManagement, and may only update users belonging to his mandator. GlobalSupervisor may set the roles for all users in the system.

Parameters:
accountId - the user ID
roleId - the role ID to be added
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the roles for the given group
FxNotFoundException - if the group does not exist
FxUpdateException - if setting the roles failed
FxApplicationException - on errors

setRoles

void setRoles(long accountId,
              java.util.List<Role> roles)
              throws FxApplicationException
Sets the roles a user is in.

To set roles the caller must be in role ROLE_ROLE_MANAGEMENT, and may only update users belonging to his mandator. GROUP_GLOBAL_SUPERVISOR may set the roles for all users in the system.

Parameters:
accountId - the user to set the roles for
roles - the roles to set, the array may contain ROLE_UNDEFINED (=0) values (which are skipped) to make it easier to build the list.
Duplicated roles are discarded.
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the roles for the given group
FxNotFoundException - if the group does not exist
FxUpdateException - if setting the roles failed
FxApplicationException - on errors

setGroups

void setGroups(long accountId,
               long... groups)
               throws FxApplicationException
Sets the groups a user defined by its unique id belongs to.

The caller must be in role ROLE_GROUP_MANAGEMENT or AccountManagement, and may only update users belonging to his mandator. He may only assign groups that also belong to his mandator, plus GROUP_EVERYONE and GROUP_OWNER.
GROUP_GLOBAL_SUPERVISOR may set all groups for all users.

Parameters:
accountId - the accountId
groups - the groups the user should belong to
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the groups
FxNotFoundException - if the user does not exist
FxUpdateException - if setting the groups failed
FxApplicationException - on errors

addGroup

void addGroup(long accountId,
              long groupId)
              throws FxApplicationException
Adds a usergroup to a user.

The caller must be in role ROLE_GROUP_MANAGEMENT or AccountManagement, and may only update users belonging to his mandator. He may only assign groups that also belong to his mandator, plus GROUP_EVERYONE and GROUP_OWNER.
GROUP_GLOBAL_SUPERVISOR may set all groups for all users.

Parameters:
accountId - the accountId
groupId - the groupID to be added
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the groups
FxNotFoundException - if the user does not exist
FxUpdateException - if setting the groups failed
FxApplicationException - on errors

setGroups

void setGroups(long accountId,
               java.util.List<UserGroup> groups)
               throws FxApplicationException
Sets the groups a user defined by its unique id belongs to.

The caller must be in role ROLE_GROUP_MANAGEMENT or AccountManagement, and may only update users belonging to his mandator. He may only assign groups that also belong to his mandator, plus GROUP_EVERYONE and GROUP_OWNER.
GROUP_GLOBAL_SUPERVISOR may set all groups for all users.

Parameters:
accountId - the accountId
groups - the groups the user should belong to
Throws:
FxNoAccessException - if the calling user lacks the permissions to set the groups
FxNotFoundException - if the user does not exist
FxUpdateException - if setting the groups failed
FxApplicationException - on errors

loadAll

java.util.List<Account> loadAll(java.lang.String name,
                                java.lang.String loginName,
                                java.lang.String email,
                                java.lang.Boolean isActive,
                                java.lang.Boolean isConfirmed,
                                java.lang.Long mandatorId,
                                int[] isInRole,
                                long[] isInGroup,
                                int startIdx,
                                int maxEntries)
                                throws FxApplicationException
Loads all users matching the parameters.

The Name, LoginName and Email are compared case insensitive.
The caller may only search users within its own mandator
. Users in the group GROUP_GLOBAL_SUPERVISOR may load users within all mandators.

Parameters:
name - (a substring of) the name of the users to load, or null if the name should not filter the result
loginName - (a substring of) the login name of the users to load, or null if the login name should not filter the result
email - (a substring of) the email of the users to load, or null if the email should not filter the result
isActive - true|false to restrict by the active flag, or null if the active flag should not filter the result
isConfirmed - true | false to restrict by the confirmed flag, or null if the confirmed flag should not filter the result
mandatorId - the function returns only users belonging to this mandator. If set to null the mandator of the calling user is used. GROUP_GLOBAL_SUPERVISOR may use -1 to load users within all mandators, all other callers may only load users within the mandator they belong to, or a FxNoAccessException is thrown.
isInRole - if set the function only loads users which are in all specified roles. The result will be empty if a invalid role id is used.
isInGroup - if set the function only loads users which belong to all specified groups. The result will be empty if a invalid group id is used.
startIdx - the start index in the result, 0 based
maxEntries - the maximum amount of users returned by the funktion (-1 for all), starting at startIdx
Returns:
all matching accounts
Throws:
FxNoAccessException - if the caller may not load users of the specified mandator
FxLoadException - if the load failed
FxApplicationException - on errors

loadAll

java.util.List<Account> loadAll(long mandatorId)
                                throws FxApplicationException
Loads all accounts of a mandator.

Parameters:
mandatorId - the mandator ID
Returns:
all accounts of the mandator.
Throws:
FxApplicationException - on errors

loadAll

java.util.List<Account> loadAll()
                                throws FxApplicationException
Loads all accounts. Unless the calling user is a global supervisor, this call returns the same result as calling loadAll(long) with the user mandator ID.

Returns:
all accounts.
Throws:
FxApplicationException - on errors

getAccountMatches

int getAccountMatches(java.lang.String name,
                      java.lang.String loginName,
                      java.lang.String email,
                      java.lang.Boolean isActive,
                      java.lang.Boolean isConfirmed,
                      java.lang.Long mandatorId,
                      int[] isInRole,
                      long[] isInGroup)
                      throws FxApplicationException
Returns number of users matching the parameters.

The caller may only search users within its own mandator
. Users in the group GROUP_GLOBAL_SUPERVISOR may load users within all mandators.

Parameters:
name - (a substring of) the name of the users to load, or null if the name should not filter the result
loginName - (a substring of) the login name of the users to load, or null if the login name should not filter the result
email - (a substring of) the email of the users to load, or null if the email should not filter the result
isActive - true|false to restrict by the active flag, or null if the active flag should not filter the result
isConfirmed - true | false to restrict by the confirmed flag, or null if the confirmed flag should not filter the result
mandatorId - the function returns only users belonging to this mandator. If set to null the mandator of the calling user is used. GROUP_GLOBAL_SUPERVISOR may use -1 to load users within all mandators, all other callers may only load users within the mandator they belong to, or a FxNoAccessException is thrown.
isInRole - if set the function only loads users which are in all specified roles. The result will be empty if an invalid role id is used.
isInGroup - if set the function only loads users which belong to all specified groups. The result will be empty if a invalid group id is used.
Returns:
The number of users matching the given parameters
Throws:
FxNoAccessException - if the caller may not load users of the specified mandator
FxLoadException - if the load failed
FxApplicationException - on errors

update

void update(long accountId,
            java.lang.String password,
            java.lang.Long defaultNode,
            java.lang.String name,
            java.lang.String loginName,
            java.lang.String email,
            java.lang.Boolean isConfirmed,
            java.lang.Boolean isActive,
            java.util.Date validFrom,
            java.util.Date validTo,
            java.lang.Long lang,
            java.lang.String description,
            java.lang.Boolean allowMultiLogin,
            java.lang.Long contactDataId)
            throws FxApplicationException
Updates the data of a user specified by its unique id.

Only callers in ROLE_USER_MANAGEMENTS may create users, and only for their mandator.
GLOBAL_SUPERVISOR may create users for all mandators.
Any user can change HIS OWN password, email, contentLanguage and guiLanguage using this function, but setting any other parameters will cause a FxNoAccessException.

Parameters:
accountId - the unique id of the user to update
password - the new password, or null if the old value should be kept
defaultNode - the new defaultNode, or null if the old value should be kept
name - the new name (not unique), or null if the old value should be kept
loginName - the new login name (unqiue over all mandators), or null if the old value should be kept
email - the new email, or null if the old value should be kept
isConfirmed - the new confirmed state, or null if the old value should be kept
isActive - the new active state, or null if the old value should be kept
validTo - the new valid to date, or null if the old value should be kept
validFrom - the new valid from date, or null if the old value should be kept
lang - the new language, or null if the old value should be kept
description - the new description, or null if the old value should be kept
allowMultiLogin - true if the account may be active more than once at the same time, may be null to keep the old value
contactDataId - id of the contact data
Throws:
FxEntryExistsException - if a user with the given login name already exists
FxNoAccessException - if the caller lacks the permissions to update the user
FxUpdateException - if the update failed
FxNotFoundException - if the user to update does not exist
FxInvalidParameterException - if a parameter was invalid
FxApplicationException - on errors

updateUser

void updateUser(long accountId,
                java.lang.String password,
                java.lang.String name,
                java.lang.String loginName,
                java.lang.String email,
                java.lang.Long lang)
                throws FxApplicationException
Updates some personal data of the specified user

Parameters:
accountId - the user to update the data for
password - the new password to assign
name - user name
loginName - the new login name to assign
email - the new e-mail address to assign
lang - the new language to assign
Throws:
FxApplicationException - on errors

updateUser

void updateUser(long accountId,
                java.lang.String password,
                boolean hashPassword,
                java.lang.String name,
                java.lang.String loginName,
                java.lang.String email,
                java.lang.Long lang)
                throws FxApplicationException
Updates some personal data of the specified user

Parameters:
accountId - the user to update the data for
password - the new password to assign
hashPassword - whether the password should be hashed (set to false for importing users, otherwise this should always be true)
name - user name
loginName - the new login name to assign
email - the new e-mail address to assign
lang - the new language to assign
Throws:
FxApplicationException - on errors
Since:
3.2.0

getAssignedUsers

java.util.List<Account> getAssignedUsers(long groupId,
                                         int startIdx,
                                         int maxEntries)
                                         throws FxApplicationException
Returns all users assigned to a group defined by its unique id.

This function provides the parameters startIdx and maxEntries to allow a page-view of the users in the GUI. This is neccesarry since a group may contain many thousands of users, which should not be transfered at once to the client.
The caller may only see groups of the mandator he belongs to plus GROUP_EVERYONE and GROUPE_PRIVATE.
GLOBAL_SUPERVISOR may see the groups/users of all mandators.

Parameters:
groupId - the group to get the users for
startIdx - the start index in the result, 0 based
maxEntries - the maximum amount of users returned by the funktion (-1 for all), starting at startIdx
Returns:
all users assigned to the given group
Throws:
FxApplicationException - on errors
FxNoAccessException - if the caller may not see the group
FxLoadException - if the get failed
FxNotFoundException - if the group does not exist

getAssignedUsersCount

long getAssignedUsersCount(long groupId,
                           boolean includeInvisible)
                           throws FxApplicationException
Returns the amount of users within a group.

Parameters:
groupId - the group to return the assignment count for
includeInvisible - a group may contain users belonging to a foreign mandator, which are invisible for the caller (except GLOBAL_SUPERVISOR). This parameter specifies wether to count those invisible users or not.
Returns:
the amount of users belonging to the group
Throws:
FxApplicationException - on errors
FxLoadException - if the load of the count failed

loadAccountAssignments

java.util.List<ACLAssignment> loadAccountAssignments(long accountId)
                                                     throws FxApplicationException
Retrieves all ACLs assigned to a given account.

A empty resultset is returned if the account does not exist.
A user may only see his own ACLAssignment.
MANDATOR_FLEXIVE may retrive ACLAssignments for all his users.
GLOBAL_SUPERVISOR may retrive the ACLAssignments of all users.

Parameters:
accountId - the user to get the ACLAssignments for
Returns:
the ACLAssignments of the user
Throws:
FxLoadException - if the function failed to load the ACLAssignments
FxNoAccessException - if the calling user may not access the ACLAssignment of the given user
FxApplicationException - on errors

fixContactData

void fixContactData()
                    throws FxApplicationException
Create contact data for all accounts that dont have them

Throws:
FxApplicationException - on errors

generateRestToken

java.lang.String generateRestToken()
                                   throws FxApplicationException
Generate a new REST API token, overwriting the previous one if it existed.

Returns:
the API token
Throws:
FxApplicationException - on errors
Since:
3.2.0

loginByRestToken

void loginByRestToken(java.lang.String token)
                      throws FxApplicationException
Login using a REST API token. Currently this is implemented as a "light" login, i.e. the request ticket will be set appropriately, but no "real" login is performed as the REST API calls don't have an associated session.

Parameters:
token - the REST API token
Throws:
FxApplicationException - on errors
FxRestApiTokenExpiredException - when the token is expired or invalid (was replaced by a newer one)
Since:
3.2.0