com.bookpac.server.user
Interface IWSUserMgmt

All Superinterfaces:

IWS

public interface IWSUserMgmt
extends IWS

User management web service

Author:

rvuine

Method Summary

void	addRightToRole(String token, String roleName, WSTRight right, String restriction) adds a right to a role
void	addUserToRole(String token, String userName, String roleName) adds a user to a role
WSTUserCreationResult	changeUserParameters(String token, String oldPw, String newPw1, String newPw2, String newUserName, String newEMail, String newOpenID) Changes fundamental user data.
void	changeUserSettings(String token, WSTMap settings) Changes the settings of the current user.
void	changeUserSettingsForUser(String token, String userName, WSTMap settings) Changes the settings of the user with the given name.
WSTUserSettingsChangeResult	changeUserSettingsWithValidation(String token, WSTMap settings) Changes the settings of of the current user and validates the result.
WSTUserNameCheckResult	checkNewUserName(String userName) Deprecated. use checkUserName(String, String)
WSTUserNameCheckResult	checkUserName(String userName, String userNature) Deprecated. this method is only used by flashpac to check the validity of a partial user name during typing
void	clearUserData(String token, ArrayList<String> chunks) Clears a chunk of user data.
WSTUserCreationResult	createExternalUser(String token, String userName, String eMail) Creates a new external user with the given data.
WSTUserCreationResult	createNewUser(String userName, String eMail, String captchaID, String captchaValue, String pw1, String pw2) Deprecated. use createUser(String, String, String, String, String, String, String)
WSTKeyholderRole	createRole(String token, String roleName, ArrayList<WSTRight> rights) creates a new keyholder role
WSTUserCreationResult	createUser(String userName, String eMail, String captchaID, String captchaValue, String pw1, String pw2, String userNature) Creates a new user with the given data
WSTUserCreationResult	createUserWithAffiliate(String userName, String eMail, String pw, WSTMap settings, String affiliateID, String userNature) Creates a new user with the given data.
WSTUserCreationResult	createUserWithSettings(String userName, String eMail, String pw, WSTMap settings, String userNature) Creates a new user with the given data.
void	deactivateUser(String token, String pw) Deactivates/disables the account of the user with the given name.
void	deleteRole(String token, String roleName) Deletes the given role.
void	deleteUserAccount(String token, String pw) Deletes a user account and all related user data forever.
void	disableUserAccount(String token, String userName) Deactivates/disables the account of the user with the given name.
void	enableUserAccount(String token, String userName) Re-enables the account of the user with the given name.
ArrayList<WSTAcquaintance>	getAcquaintances(String token) Returns a list of all acquaintances of the current user.
ArrayList<WSTAcquaintance>	getAcquaintancesOfUser(String token, String user) Returns a list of all acquaintances of the current user.
ArrayList<WSTKeyholderRole>	getAssignableRoles(String token) Returns all user roles that that calling user can assign using addUserToRole(String, String, String) or removeUserFromRole(String, String, String)
ArrayList<WSTKeyholderRole>	getAvailableRoles(String token) Returns all user roles with their assigned rights
WSTKeyholderRole	getRole(String token, String roleName) Returns the role with the given name.
WSTUser	getUser(String token) Returns the current user
WSTUser	getUserByExternalID(String token, String externalID, String externalOrigin) Returns a user for a given externalID and userNature.
WSTUser	getUserByName(String token, String userName) Returns a user for a given name and an optional name space.
ArrayList<String>	getUserNameList(String token, String hint, int maxResults) Returns a list of user names.
WSTUserNature	getUserNature(String token) Deprecated. use IWSReaktorMgmt.getNature(String) instead
WSTUserNature	getUserNatureForAffiliateAndCountry(String affiliateID, String countryCode) Deprecated.
ArrayList<WSTUserNature>	getUserNatures() Deprecated. use IWSReaktorMgmt.getNatures() instead
HashMap<String,String>	getUserSettings(String token) Returns the settings of the current user.
ArrayList<WSTUser>	getUsersInRole(String token, String roleName) Get all users in the given role.
boolean	hasRight(String token, WSTRight right) checks if the token has the given right
void	mergeUserAccounts(String token, String oldUserName, String targetUserName) Merge one user account into another transferring all documents, lists, settings, etc.
WSTUserCreationResult	performPasswordReset(String token, String pw1, String pw2) Performs a password reset.
WSTUserCreationResult	promoteAnonymousUser(String token, String userName, String eMail, String captchaID, String captchaValue, String pw1, String pw2) Promotes the current, anonymous user to the status of a known user.
void	removeAcquaintance(String token, String user) Removes an acquaintance.
void	removeRightFromRole(String token, String roleName, WSTRight right, String restriction) removes a right from a role
void	removeUserFromRole(String token, String userName, String roleName) removes a user from a role
boolean	requestAcquaintance(String token, String user, WSTAcquaintanceType type, String description) Request that an acquaintance relationship between two users be established.
void	requestPasswordReset(String userName) Deprecated. use requestPasswordResetByNature(String, String)
void	requestPasswordResetByNature(String userName, String userNature) Requests that the user should get the opportunity to reset his password.
WSTUserCreationResult	requestUserCreation(String userName, String eMail, String captchaID, String captchaValue, String pw1, String pw2, String userNature) Requests a user creation with the given data.

Method Detail

getUserNatures

@Deprecated
ArrayList<WSTUserNature> getUserNatures()
                                        throws WSException

Deprecated. use IWSReaktorMgmt.getNatures() instead

Returns the list of all user natures. The returned user natures only contains a very basic set of properties.

Returns:

the list of all user natures, never null

Throws:

WSException - should only occur on internal errors

getUserNature

@Deprecated
WSTUserNature getUserNature(String token)
                            throws WSException

Deprecated. use IWSReaktorMgmt.getNature(String) instead

Returns the user nature of the token owner with a set of properties that depends on his rights.

Parameters:

token - a valid session ID, must not be null

Returns:

the user nature, never null

Throws:

WSException - should only occur on internal errors

getUserNatureForAffiliateAndCountry

@Deprecated
WSTUserNature getUserNatureForAffiliateAndCountry(String affiliateID,
                                                             String countryCode)
                                                  throws WSException

Deprecated.

Returns the user nature that the given affiliate should use.

Parameters:

affiliateID - ID of the affiliate, must not be null

countryCode - the country where the user/device is located (e.g. determined from the locale), must not be null

Returns:

the suggested locale or null

Throws:

WSException

checkNewUserName

@Deprecated
WSTUserNameCheckResult checkNewUserName(String userName)
                                        throws WSException

Deprecated. use checkUserName(String, String)

Checks if a given user name would be valid and available

Parameters:

userName - the user name

Returns:

a UserNameCheckResult, never null

Throws:

WSException

checkUserName

@Deprecated
WSTUserNameCheckResult checkUserName(String userName,
                                                String userNature)
                                     throws WSException

Deprecated. this method is only used by flashpac to check the validity of a partial user name during typing

Checks if a given user name would be valid and available within a given nature

Parameters:

userName - userName the user name

userNature - userNature name to be checked against

Returns:

a UserNameCheckResult, never null

Throws:

WSException

createNewUser

@Deprecated
WSTUserCreationResult createNewUser(String userName,
                                               String eMail,
                                               String captchaID,
                                               String captchaValue,
                                               String pw1,
                                               String pw2)
                                    throws WSException

Deprecated. use createUser(String, String, String, String, String, String, String)

Throws:

WSException

createUser

WSTUserCreationResult createUser(String userName,
                                 String eMail,
                                 String captchaID,
                                 String captchaValue,
                                 String pw1,
                                 String pw2,
                                 String userNature)
                                 throws WSException

Creates a new user with the given data

Parameters:

userName - the user name, must be valid and available, must not be longer than 1024 bytes

eMail - the user's email address, must not be longer than 1024 bytes

captchaID - the ID of the captcha delivered to the user

captchaValue - the value in the captcha

pw1 - the password, SHA1-hashed (40 bytes)

pw2 - the password again, SHA1-hashed (40 bytes)

userNature - the nature of the new user

Returns:

a UserCreationResult

Throws:

WSException

requestUserCreation

WSTUserCreationResult requestUserCreation(String userName,
                                          String eMail,
                                          String captchaID,
                                          String captchaValue,
                                          String pw1,
                                          String pw2,
                                          String userNature)
                                          throws WSException

Requests a user creation with the given data. The given eMail address will receive mail from the Reaktor, asking the owner to confirm her eMail and that she wants to join. The user will only be created after the link in the eMail has been used. The link will point to an action request that can be executed in WSActionRequestMgmt.

Parameters:

userName - the user name, must be valid and available, must not be longer than 1024 bytes

eMail - the user's email address, must not be longer than 1024 bytes

captchaID - the ID of the captcha delivered to the user

captchaValue - the value in the captcha

pw1 - the password, SHA1-hashed (40 bytes)

pw2 - the password again, SHA1-hashed (40 bytes)

userNature - the nature of the new user

Returns:

a UserCreationResult that will indicate if this user could be created. Only if the result is OK the action request will have been created and a mail will have been sent out.

Throws:

WSException

createUserWithSettings

WSTUserCreationResult createUserWithSettings(String userName,
                                             String eMail,
                                             String pw,
                                             WSTMap settings,
                                             String userNature)
                                             throws WSException

Creates a new user with the given data.

Parameters:

userName - the user name, must be valid and available, must not be longer than 1024 bytes

eMail - the user's email address, must not be longer than 1024 bytes

pw - the password, SHA1-hashed (40 bytes)

settings - non-null additional settings like address etc.

userNature - the nature of the new user

Returns:

a UserCreationResult

Throws:

WSException

createUserWithAffiliate

WSTUserCreationResult createUserWithAffiliate(String userName,
                                              String eMail,
                                              String pw,
                                              @Nullable
                                              WSTMap settings,
                                              String affiliateID,
                                              String userNature)
                                              throws WSException

Creates a new user with the given data.

Parameters:

userName - the user name, must be valid and available, must not be longer than 1024 bytes

eMail - the user's email address, must not be longer than 1024 bytes

pw - the password, SHA1-hashed (40 bytes)

settings - non-null additional settings like address etc.

affiliateID - an affiliate id.

userNature - the nature of the new user

Returns:

a UserCreationResult

Throws:

WSException

createExternalUser

WSTUserCreationResult createExternalUser(String token,
                                         String userName,
                                         String eMail)
                                         throws WSException

Creates a new external user with the given data. The user will be added to the nature of the token holder. If a user already exists, his email is updated and

Parameters:

token - a valid token identifying a user with the right WSTRight.MANAGE_EXTERNAL_USERS

userName - the unique user identifier that is used to login at the remote system, e.g. an email (which may not be the primary external ID!!!), must not be null

eMail - the user's email address, must not be longer than 1024 bytes

Returns:

WSTUserCreationResult.OK if the user was successfully created or updated, otherwise WSTUserCreationResult.FAILURE

Throws:

WSException

promoteAnonymousUser

WSTUserCreationResult promoteAnonymousUser(String token,
                                           String userName,
                                           String eMail,
                                           @Nullable
                                           String captchaID,
                                           @Nullable
                                           String captchaValue,
                                           String pw1,
                                           String pw2)
                                           throws WSException

Promotes the current, anonymous user to the status of a known user.

Parameters:

token - a valid session ID, must not be null

userName - the user name to be used, must be valid and available, must not be longer than 1024 bytes

eMail - the email address, may be null, must not be longer than 1024 bytes

captchaID - the ID of the captcha delivered to the user

captchaValue - the value in the captcha

pw1 - the password, SHA1-hashed (40 bytes)

pw2 - the password again, SHA1-hashed (40 bytes)

Returns:

a UserCreationResult

Throws:

WSException

requestPasswordReset

@Deprecated
void requestPasswordReset(String userName)
                          throws WSException

Deprecated. use requestPasswordResetByNature(String, String)

Requests that the user should get the opportunity to reset his password. This method will cause the following action: - A temporary token will be created for the user (the token will time out normally) - An eMail will be sent to the user's eMail address. This eMail will contain the newly created token, embedded in a link that will lead to a password alteration page.

Parameters:

userName - the name of the user that forgot his password

Throws:

WSException

requestPasswordResetByNature

void requestPasswordResetByNature(String userName,
                                  String userNature)
                                  throws WSException

Requests that the user should get the opportunity to reset his password. This method will cause the following action: - A temporary token will be created for the user (the token will time out normally) - An eMail will be sent to the user's eMail address. This eMail will contain the newly created token, embedded in a link that will lead to a password alteration page.

Parameters:

userName - the name of the user that forgot his password

userNature - the name of the current userNature

Throws:

WSException

performPasswordReset

WSTUserCreationResult performPasswordReset(String token,
                                           String pw1,
                                           String pw2)
                                           throws WSException

Performs a password reset.

Parameters:

token - the session ID that identifies the user.

pw1 - the password, SHA1-hashed (40 bytes)

pw2 - the password again, SHA1-hashed (40 bytes)

Returns:

a user creation result, never null

Throws:

WSException

getUserSettings

HashMap<String,String> getUserSettings(String token)
                                       throws WSException

Returns the settings of the current user.

Parameters:

token - the session if, must not be null and valid

Returns:

a key-value map with settings

Throws:

WSException

changeUserSettings

void changeUserSettings(String token,
                        WSTMap settings)
                        throws WSException

Changes the settings of the current user. Settings not specified in the settings hash will not be touched. To remove a setting completely, set its value to ""

Parameters:

token - the session ID, must not be null

settings - the settings, may be null or empty, all keys and values must not be longer than 1024 bytes

Throws:

WSException

changeUserSettingsWithValidation

WSTUserSettingsChangeResult changeUserSettingsWithValidation(String token,
                                                             WSTMap settings)
                                                             throws WSException

Changes the settings of of the current user and validates the result. If the complete change of the settings is rolled-back.

Parameters:

token - the session ID, must not be null

settings - the settings, may be null or empty, all keys and values must not be longer than 1024 bytes

Returns:

an object containing the new user settings and the result of the validation, including details about the problem if any validation failed

Throws:

WSException

changeUserSettingsForUser

void changeUserSettingsForUser(String token,
                               String userName,
                               WSTMap settings)
                               throws WSException

Changes the settings of the user with the given name. Settings not specified in the settings hash will not be touched. To remove a setting completely, set its value to ""

Parameters:

token - a valid token of a user with the right WSTRight.EDIT_USERS.

userName - the name of the user

settings - the settings, may be null or empty, all keys and values must not be longer than 1024 bytes

Throws:

WSException

changeUserParameters

WSTUserCreationResult changeUserParameters(String token,
                                           String oldPw,
                                           String newPw1,
                                           String newPw2,
                                           String newUserName,
                                           String newEMail,
                                           String newOpenID)
                                           throws WSException

Changes fundamental user data.

Parameters:

token - the session ID of the user, must be valid and != null

oldPw - the SHA1 hash of the old password, must be != null and valid

newPw1 - the password, SHA1-hashed (40 bytes), may be null to indicate no change

newPw2 - the password again, SHA1-hashed (40 bytes), may be null to indicate no change

newUserName - deprecated, this parameter must be the empty string, null or the old userName which results in NO change

newEMail - the new eMail address, may be null to indicate no change

newOpenID - deprecated

Returns:

a WSTUserCreationResult

Throws:

WSException

createRole

WSTKeyholderRole createRole(String token,
                            String roleName,
                            ArrayList<WSTRight> rights)
                            throws WSException

creates a new keyholder role

Parameters:

token - the token of the user that has the right WSTRight.EDIT_ROLE

roleName - name of the new role

rights - the rights for the role see WSTRight

Returns:

the new role

Throws:

WSException - if an exceptions occurs

addUserToRole

void addUserToRole(String token,
                   String userName,
                   String roleName)
                   throws WSException

adds a user to a role

Parameters:

token - the token of the user that has the right WSTRight.ASSIGN_ROLE_TO_USER with the possible restriction that is only applies to the given role

userName - the name of the user

roleName - the name of the role

Throws:

WSException - if an exceptions occurs

removeUserFromRole

void removeUserFromRole(String token,
                        String userName,
                        String roleName)
                        throws WSException

removes a user from a role

Parameters:

token - the token of the user that has the right WSTRight.ASSIGN_ROLE_TO_USER with the possible restriction that is only applies to the given role

userName - the name of the user

roleName - the name of the role

Throws:

WSException - if an exceptions occurs

getAvailableRoles

ArrayList<WSTKeyholderRole> getAvailableRoles(String token)
                                              throws WSException

Returns all user roles with their assigned rights

Parameters:

token - must be a valid token

Returns:

the roles, never null

Throws:

WSException - if an error occurs

getAssignableRoles

ArrayList<WSTKeyholderRole> getAssignableRoles(String token)
                                               throws WSException

Returns all user roles that that calling user can assign using addUserToRole(String, String, String) or removeUserFromRole(String, String, String)

Parameters:

token - must be a valid token

Returns:

the roles, never null

Throws:

WSException - if an error occurs

getRole

WSTKeyholderRole getRole(String token,
                         String roleName)
                         throws WSException

Returns the role with the given name. The returned role object includes all assigned rights.

Parameters:

token - must be a valid token

roleName - the name of the role

Returns:

the role, never null

Throws:

WSException - if the given name is unknown

hasRight

boolean hasRight(String token,
                 WSTRight right)
                 throws WSException

checks if the token has the given right

Parameters:

token - must be a valid token

right - the right. See WSTRight

Returns:

if the token has the right

Throws:

WSException

addRightToRole

void addRightToRole(String token,
                    String roleName,
                    WSTRight right,
                    String restriction)
                    throws WSException

adds a right to a role

Parameters:

token - the token of the user that has the right WSTRight.EDIT_ROLE

roleName - name of the role

right - the new right. See WSTRight

restriction - a restriction on the right (e.g. a role name for WSTRight.ASSIGN_ROLE_TO_USER

Throws:

WSException - if an exception occurs

removeRightFromRole

void removeRightFromRole(String token,
                         String roleName,
                         WSTRight right,
                         String restriction)
                         throws WSException

removes a right from a role

Parameters:

token - the token of the user that has the right WSTRight.EDIT_ROLE

roleName - name of the role

right - the new right. See WSTRight

restriction - a restriction on the right (e.g. a role name for WSTRight.ASSIGN_ROLE_TO_USER

Throws:

WSException - if an exception occurs

deleteRole

void deleteRole(String token,
                String roleName)
                throws WSException

Deletes the given role.

Parameters:

token - the token of a user that has the right WSTRight.EDIT_ROLE

roleName - the role to delete.

Throws:

WSException - in case of errors.

getUsersInRole

ArrayList<WSTUser> getUsersInRole(String token,
                                  String roleName)
                                  throws WSException

Get all users in the given role.

Parameters:

token - the token of a user that has the right WSTRight.EDIT_ROLE

roleName - the role

Returns:

a possibly empty list of users

Throws:

WSException - in case of errors

deactivateUser

void deactivateUser(String token,
                    String pw)
                    throws WSException

Deactivates/disables the account of the user with the given name. A deactivated user cannot authenticate against the reaktor and is invisible to other users.

Parameters:

token - a valid user token

pw - the SHA1 hash of the old password

Throws:

WSException - in case of errors.

deleteUserAccount

void deleteUserAccount(String token,
                       String pw)
                       throws WSException

Deletes a user account and all related user data forever. User name, email, password and all settings will be deleted and the user will be removed from all groups.

Deleted user accounts cannot be recovered!

Parameters:

token - a valid user token

pw - the SHA1 hash of the old password

Throws:

WSException

disableUserAccount

void disableUserAccount(String token,
                        String userName)
                        throws WSException

Deactivates/disables the account of the user with the given name. A deactivated user cannot authenticate against the reaktor and are invisible to other users.

Parameters:

token - a valid token of a user with the right WSTRight.EDIT_USERS.

userName - the name of the user to deactivate.

Throws:

WSException - in case of errors.

enableUserAccount

void enableUserAccount(String token,
                       String userName)
                       throws WSException

Re-enables the account of the user with the given name. New user accounts are enabled by default. This method is only required if deactivateUser(String, String) or disableUserAccount(String, String) have been called.

Parameters:

token - a valid token of a user with the right WSTRight.EDIT_USERS.

userName - the name of the user to activate.

Throws:

WSException - in case of errors.

getUser

WSTUser getUser(String token)
                throws WSException

Returns the current user

Parameters:

token -

Returns:

the current user

Throws:

WSException

getUserByName

WSTUser getUserByName(String token,
                      String userName)
                      throws WSException

Returns a user for a given name and an optional name space. This call requires the right WSTRight.EDIT_USERS or WSTRight.MANAGE_EXTERNAL_USERS.

Parameters:

token - token must be a valid token

userName - the name of the requested user. If the given user comes from another name space, the name space has to be prepended to the user name followed by a colon, e.g. "FACEBOOK:peter" for peter from facebook

Returns:

the user or null

Throws:

WSException

getUserByExternalID

WSTUser getUserByExternalID(String token,
                            String externalID,
                            String externalOrigin)
                            throws WSException

Returns a user for a given externalID and userNature. This call requires the right WSTRight.MANAGE_EXTERNAL_USERS.

Parameters:

token - token must be a valid token

externalID - the external ID of the requested user

externalOrigin - the external origin of the user, e.g. FACEBOOK

Returns:

the user or null

Throws:

WSException

getUserNameList

ArrayList<String> getUserNameList(String token,
                                  String hint,
                                  int maxResults)
                                  throws WSException

Returns a list of user names.

Parameters:

token - a valid session ID of the current user

hint - a hint for searching for users, may be empty or null to request all users. Currently, hints are always interpreted as the first characters of the user names to be returned (i.e. for an autocompleter field)

maxResults - maximum number of users to be returned

Returns:

a list of user names

Throws:

WSException

clearUserData

void clearUserData(String token,
                   ArrayList<String> chunks)
                   throws WSException

Clears a chunk of user data. Currently, the only supported data chunk is "PAYMENT", which will clear all payment data of the user.

Parameters:

token - the session ID, must not be null

chunks - a list of data chunks to be cleared

Throws:

WSException

requestAcquaintance

boolean requestAcquaintance(String token,
                            String user,
                            WSTAcquaintanceType type,
                            String description)
                            throws WSException

Request that an acquaintance relationship between two users be established. Depending on the acquaintance type, this will create an action request for the other user to confirm that the two users know each other, or just add the other user as an acquaintance of the given type.

Parameters:

token - the session ID, must not be null

user - the other user

type - the type of the acquaintance

description - a description for the acquaintance

Returns:

true if the request was created, false if creating the request wouldn't make any sense (because the users are already acquainted, for instance)

Throws:

WSException

getAcquaintances

ArrayList<WSTAcquaintance> getAcquaintances(String token)
                                            throws WSException

Returns a list of all acquaintances of the current user.

Parameters:

token - the session ID, must not be null

Returns:

a list of acquaintances, which may be empty, but never null

Throws:

WSException

getAcquaintancesOfUser

ArrayList<WSTAcquaintance> getAcquaintancesOfUser(String token,
                                                  String user)
                                                  throws WSException

Returns a list of all acquaintances of the current user. The list returned may be empty or filtered, depending on the type of acquaintance (some are published, some are not)

Parameters:

token - the session ID, must not be null

user - the user whose acquaintances you want to see

Returns:

a list of acquaintances, which may be empty, but never null

Throws:

WSException

removeAcquaintance

void removeAcquaintance(String token,
                        String user)
                        throws WSException

Removes an acquaintance. This will be done silently without any messages being sent around.

Parameters:

token - the session ID, must not be null

user - the guy you want to get rid of

Throws:

WSException

mergeUserAccounts

void mergeUserAccounts(String token,
                       String oldUserName,
                       String targetUserName)
                       throws WSException

Merge one user account into another transferring all documents, lists, settings, etc. to the new account and deleting the old account afterwards.

Parameters:

token - a token with right EDIT_USERS

oldUserName - the user name of the old/source account

targetUserName - the user name of the new/target account

Throws:

WSException - in case of errors