com.appiancorp.suiteapi.personalization

Interface UserProfileService

All Superinterfaces:

ContextSensitiveSingletonService, Service

public interface UserProfileService
extends ContextSensitiveSingletonService

Provides the main functionality needed to create, update, delete, and retrieve UserProfile objects from the Personalization service.

Methods of service classes can all throw the unchecked exception ServiceException if any system-level error (for example, server failure) occurs, and will in general throw a checked exception (InvalidXXXException) when an entity to be retrieved is inaccessible, instead of returning null. Exceptions to this paradigm (including the use of ResultList as described below) are noted. All checked exceptions extend AppianException.

It may be necessary to retrieve a subset of results as opposed to an entire collection, and also to sort the subset by some property of the returned object. "Paging" methods which return a ResultPage are provided in certain instances for this purpose. The ResultPage will contain the sorted subset of results (via Result.getResults()), and the total number of items in the available result set (via ResultPage.getAvailableItems()).

It may also be necessary to retrieve some results, even if all results cannot be retrieved (for instance, some of the entities corresponding to a list of entity IDs may no longer exist). Methods which return a ResultList are provided for this purpose. The Result.getResults() method in this case will return all results which can be retrieved. In addition, there will be a list of result codes (ResultList.getResultCodes()) that represent the successful retrieval of an entity, or, if the entity could not be retrieved, the reason for the failure. See the CODE_XXX constants in ResultList for details.

See Also:

GroupService, GroupTypeService, PersonalizationSearchService, UserService

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	authenticateUser$UPDATES
static boolean	createUser$UPDATES
static boolean	createUsers$UPDATES
static boolean	findAllUsersPaging$UPDATES
static boolean	findUsers$UPDATES
static boolean	findUsersPaging$UPDATES
static boolean	getApplicationName$UPDATES
static boolean	getUser$UPDATES
static boolean	getUserByUuid$UPDATES
static boolean	getUserPreferences$UPDATES
static boolean	getUsers$UPDATES
static boolean	getUsersByUuid$UPDATES
static boolean	getUsersCreation$UPDATES
static boolean	getUsersForGroupByRolePaging$UPDATES
static boolean	getWorkspace$UPDATES
static boolean	searchUserProfilesPaging$UPDATES
static boolean	setUserPreferences$UPDATES
static boolean	updateUser$UPDATES
static boolean	updateUsers$UPDATES

Fields inherited from interface com.appiancorp.services.ContextSensitiveSingletonService

CONFIGURE_METHOD_NAME

Method Summary

Modifier and Type	Method and Description
UserProfile	authenticateUser(java.lang.String username_, java.lang.String password_) Deprecated. Since 6.0.2, use #authenticate(String, byte[])
java.lang.String	createUser(UserProfile userprofile_) Creates a new user The username field of the created user must be unique.
java.lang.String[]	createUsers(UserProfile[] userprofiles_) Creates new users.
ResultPage	findAllUsersPaging(boolean caseSensitive_, int startIndex_, int batchSize_, java.lang.Integer sortProperty_, java.lang.Integer sortOrder_) Fast method that gets all users.
UserProfile[]	findUsers(UserSearch userSearch_, boolean caseSensitive_) Deprecated. Use findUsersPaging(UserSearch, boolean, int, int, Integer, Integer) instead.
ResultPage	findUsersPaging(UserSearch userSearch_, boolean caseSensitive_, int startIndex_, int batchSize_, java.lang.Integer sortProperty_, java.lang.Integer sortOrder_) Finds a list of users for a given search criteria.
java.lang.String	getApplicationName() Gets the name of the application on which this service is running.
UserProfile	getUser(java.lang.String username_) Gets a single user by username.
UserProfile	getUserByUuid(java.lang.String uuid) Gets a single user by uuid.
UserPreferences	getUserPreferences() Returns current user's preferences
UserProfile[]	getUsers(java.lang.String[] usernames_) Retrieves a list of users by username.
UserProfile[]	getUsersByUuid(java.lang.String[] uuids) Retrieves a list of users by uuid.
java.sql.Timestamp[]	getUsersCreation(java.lang.String[] usernames) Gets the users creation date
UserProfile[]	getUsersForGroupByRolePaging(java.lang.Long groupId_, int role_, int startIndex_, int batchSize_, java.lang.Integer sortProperty_, java.lang.Integer sortOrder_) Deprecated. Use UserService.getUsersForGroupByRolePaging(Long, Integer, int, int, Integer, Integer)
java.lang.String[]	getWorkspace() Gets the current memory profile for the workspace.
ResultPage	searchUserProfilesPaging(java.lang.String query_, int startIndex_, int batchSize_, java.lang.Integer sortProperty_, java.lang.Integer sortOrder_) Searches for Users by first, last, and username and returns the UserProfile objects for each found User
void	setUserPreferences(UserPreferences preferences_) Set current user's preferences
void	updateUser(UserProfile userprofile_) Updates a user.
void	updateUsers(UserProfile[] userprofiles_) Updates users.

Methods inherited from interface com.appiancorp.services.ContextSensitiveSingletonService

configureContextSensitiveSingletonService

Field Detail

getUser$UPDATES

static final boolean getUser$UPDATES

See Also:

Constant Field Values

getUsers$UPDATES

static final boolean getUsers$UPDATES

See Also:

Constant Field Values

getUserByUuid$UPDATES

static final boolean getUserByUuid$UPDATES

See Also:

Constant Field Values

getUsersByUuid$UPDATES

static final boolean getUsersByUuid$UPDATES

See Also:

Constant Field Values

getUsersCreation$UPDATES

static final boolean getUsersCreation$UPDATES

See Also:

Constant Field Values

getUsersForGroupByRolePaging$UPDATES

static final boolean getUsersForGroupByRolePaging$UPDATES

See Also:

Constant Field Values

authenticateUser$UPDATES

static final boolean authenticateUser$UPDATES

See Also:

Constant Field Values

findUsers$UPDATES

static final boolean findUsers$UPDATES

See Also:

Constant Field Values

findUsersPaging$UPDATES

static final boolean findUsersPaging$UPDATES

See Also:

Constant Field Values

createUser$UPDATES

static final boolean createUser$UPDATES

See Also:

Constant Field Values

createUsers$UPDATES

static final boolean createUsers$UPDATES

See Also:

Constant Field Values

updateUser$UPDATES

static final boolean updateUser$UPDATES

See Also:

Constant Field Values

updateUsers$UPDATES

static final boolean updateUsers$UPDATES

See Also:

Constant Field Values

findAllUsersPaging$UPDATES

static final boolean findAllUsersPaging$UPDATES

See Also:

Constant Field Values

searchUserProfilesPaging$UPDATES

static final boolean searchUserProfilesPaging$UPDATES

See Also:

Constant Field Values

getApplicationName$UPDATES

static final boolean getApplicationName$UPDATES

See Also:

Constant Field Values

getWorkspace$UPDATES

static final boolean getWorkspace$UPDATES

See Also:

Constant Field Values

getUserPreferences$UPDATES

static final boolean getUserPreferences$UPDATES

See Also:

Constant Field Values

setUserPreferences$UPDATES

static final boolean setUserPreferences$UPDATES

See Also:

Constant Field Values

Method Detail

getUser

UserProfile getUser(java.lang.String username_)
             throws InvalidUserException

Gets a single user by username.

Parameters:

username_ - the unique username of the user

Returns:

a UserProfile corresponding to the username_

Throws:

InvalidUserException - if the given username does correspond to a valid user

ServiceException - if any system-level error occurs

getUsers

UserProfile[] getUsers(java.lang.String[] usernames_)
                throws InvalidUserException

Retrieves a list of users by username.

Parameters:

usernames_ - the unique usernames of the users objects

Returns:

an array of UserProfile objects corresponding to the usernames_

Throws:

InvalidUserException - if a given username does not exist

ServiceException - if any system-level error occurs

getUserByUuid

UserProfile getUserByUuid(@ConvertWith(value=com.appiancorp.kougar.mapper.parameters.UuidParameterConverter.class)
                          java.lang.String uuid)
                   throws InvalidUserException

Gets a single user by uuid.

Parameters:

uuid - the unique uuid of the user

Returns:

a UserProfile corresponding to the uuid

Throws:

InvalidUserException - if the given uuid does correspond to a valid user

ServiceException - if any system-level error occurs

getUsersByUuid

UserProfile[] getUsersByUuid(@ConvertWith(value=com.appiancorp.kougar.mapper.parameters.UuidParameterConverter[].class[])
                             java.lang.String[] uuids)
                      throws InvalidUserException

Retrieves a list of users by uuid.

Parameters:

uuids - the unique uuids of the users objects

Returns:

an array of UserProfile objects corresponding to the uuids

Throws:

InvalidUserException - if a given uuid does not correspond to a valid user

ServiceException - if any system-level error occurs

getUsersCreation

java.sql.Timestamp[] getUsersCreation(java.lang.String[] usernames)
                               throws InvalidUserException

Gets the users creation date

Parameters:

usernames - The list of users

Returns:

An array of timestamps with the user creation date.

Throws:

InvalidUserException

getUsersForGroupByRolePaging

@Deprecated
UserProfile[] getUsersForGroupByRolePaging(java.lang.Long groupId_,
                                                       int role_,
                                                       int startIndex_,
                                                       int batchSize_,
                                                       java.lang.Integer sortProperty_,
                                                       java.lang.Integer sortOrder_)
                                                throws InvalidGroupException,
                                                       UnsupportedRoleException

Deprecated. Use UserService.getUsersForGroupByRolePaging(Long, Integer, int, int, Integer, Integer)

Retrieves a list of users for a given group by user role.

Parameters:

groupId_ - ID of the group whose users should be retrieved

role_ - the role for which to retrieve users. Valid roles are one of the USER_ROLE_XXX constants in User

startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.

batchSize_ - the number of results to return. Use Constants.COUNT_ALL to return the entire collection, but this is STRONGLY discouraged.

sortProperty_ - the property by which the results will be sorted. This is one of the SORT_BY_XXX constants in UserProfile.

sortOrder_ - the order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING

Returns:

an array of UserProfile objects corresponding to the users in the group with the given role

Throws:

InvalidGroupException - if the group given by groupId_ does not exist

UnsupportedRoleException - if the role is invalid

ServiceException - if any system-level error occurs

authenticateUser

@Deprecated
UserProfile authenticateUser(java.lang.String username_,
                                         java.lang.String password_)
                                  throws InvalidLoginException

Deprecated. Since 6.0.2, use #authenticate(String, byte[])

Used to validate a user (the login mechanism).

Parameters:

username_ - the unique username of a user

password_ - the password for the user

Returns:

the UserProfile of the user with the given username

Throws:

InvalidLoginException - if the given username_ and password_ are not those of a valid user

ServiceException - if any system-level error occurs

findUsers

@Deprecated
UserProfile[] findUsers(UserSearch userSearch_,
                                    boolean caseSensitive_)
                             throws UnsupportedOperatorException

Deprecated. Use findUsersPaging(UserSearch, boolean, int, int, Integer, Integer) instead.

Finds a list of users for a given search criteria.

The userSearch_ object should be populated with the user fields to be searched on, and the criteria to be used in performing the search. For example, the userSearch_ might have the username field set to "john.doe", the lastName fields set to "Doe", the operatorUsername field set to Operator#EQUALS and the operatorLastName field set to Operator#ENDS_WITH. Such a search will return all users whose username is "john.doe", and whose last name ends with "Doe".

See GroupTypeService.getOperatorsForDataType(int) to obtain a list of possible operators for a given data type.

Parameters:

userSearch_ - the search criteria

caseSensitive_ - whether the search is case sensitive

Returns:

the users that meet the given search criteria

Throws:

UnsupportedOperatorException - if userSearch_ contains an invalid operator

ServiceException - if any system-level error occurs

findUsersPaging

ResultPage findUsersPaging(UserSearch userSearch_,
                           boolean caseSensitive_,
                           int startIndex_,
                           int batchSize_,
                           java.lang.Integer sortProperty_,
                           java.lang.Integer sortOrder_)
                    throws UnsupportedOperatorException

Finds a list of users for a given search criteria. This method will return the paged resultset corresponding to findUsers(UserSearch, boolean)

Parameters:

userSearch_ - criteria for the search

caseSensitive_ - whether the search is case sensitive

startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.

batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.

sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in UserProfile

sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order

Returns:

a ResultPage containing an array of UserProfile objects correpsonding to users who match the search criteria

Throws:

UnsupportedOperatorException - if userSearch_ contains an invalid operator

ServiceException - if any system-level error occurs

createUser

java.lang.String createUser(UserProfile userprofile_)
                     throws DuplicateNameException,
                            PrivilegeException,
                            InvalidSupervisorException,
                            InvalidUserException,
                            InvalidNameException

Creates a new user

The username field of the created user must be unique. User fields required for creation are: username.

NOTES:

1) Although this call will complete successfully if only the username field is populated, if the password field is not also populated the created user will not able to log into the application.

2) The password field must be hashed to work properly with the the product interface.

3)In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username be validated for illegal characters (only allow alphanumeric symbols, underscores, and periods).

If, after a user is created, it is necessary to call any method using that user's UserServiceContext, then activateUserSession must be called on the following services:

• ProcessDesignService
• ProcessAnalyticsService
• ContentService
• DiscussionMetadataCoreService

Parameters:

userprofile_ - a user to create

Returns:

the username of the user

Throws:

DuplicateNameException - if the username already exists

PrivilegeException - if the current user is not a System Administrator

InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user

InvalidUserException - if user_ is empty

ServiceException - if any system-level error occurs

InvalidNameException - Never thrown. Is only declared for backwards compatibility.

createUsers

java.lang.String[] createUsers(UserProfile[] userprofiles_)
                        throws DuplicateNameException,
                               InvalidNameException,
                               PrivilegeException,
                               InvalidSupervisorException,
                               InvalidUserException

Creates new users.

The username field of the created user must be unique. User fields required for creation are: username.

NOTES:

1) Although this call will complete successfully if only the username field is populated, if the password field is not also populated the created user will not able to log into the application.

2) The password field must be hashed to work properly with the the product interface.

3)In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username be validated for illegal characters (only allow alphanumeric symbols, underscores, and periods).

If, after a user is created, it is necessary to call any method using that user's UserServiceContext, then activateUserSession must be called on the following services:

• ProcessDesignService
• ProcessAnalyticsService
• ContentService
• DiscussionMetadataCoreService

Parameters:

userprofiles_ - users to create.

Returns:

the usernames of the users

Throws:

DuplicateNameException - if any of the usernames already exists

InvalidNameException - if any username is null

PrivilegeException - if the user is not a System Administrator Must be a System Administrator to create a user.

InvalidSupervisorException - if the supervisor property is not either null or the login of a valid user

InvalidUserException - if one of users_ is empty

ServiceException - if any system-level error occurs

updateUser

void updateUser(UserProfile userprofile_)
         throws InvalidUserException,
                InvalidSupervisorException,
                PrivilegeException

Updates a user. Does not modify username or passwordfields.

In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username field be validated for illegal characters (only allow alphanumeric symbols and underscores).

This method will ignore any changes to the properties userTypeId and userTypeName when applied to the 'Administrator' user.

Parameters:

userprofile_ - the user to modify

Throws:

InvalidUserException - if a user with the given username does not exist

InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user

ServiceException - if any system-level error occurs

PrivilegeException

updateUsers

void updateUsers(UserProfile[] userprofiles_)
          throws InvalidUserException,
                 InvalidSupervisorException,
                 PrivilegeException

Updates users. Does not modify username or passwordfields. In order to minimize possible breaks with the user interface, it is HIGHLY recommended that the username field be validated for illegal characters (only allow alphanumeric symbols and underscores).

This method will ignore any changes to the properties userTypeId and userTypeName when applied to the 'Administrator' user.

Parameters:

userprofiles_ - users to update

Throws:

InvalidUserException - if any user with a given username does not exist

InvalidSupervisorException - if the supervisor property is neither null nor the login of a valid user

ServiceException - if any system-level error occurs

PrivilegeException

See Also:

UserProfile, UserService.changeUserPassword(String, byte[], boolean)

findAllUsersPaging

ResultPage findAllUsersPaging(boolean caseSensitive_,
                              int startIndex_,
                              int batchSize_,
                              java.lang.Integer sortProperty_,
                              java.lang.Integer sortOrder_)

Fast method that gets all users. The ResultPage returned contains UserProfile objects sorted by the given sortProperty.

Parameters:

caseSensitive_ - whether the results should be sorted in a case sensitive manner. Pass false to sort in the common lexicographical order (e.g., a, A, b, B, c, C).

startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.

batchSize_ - the number of results to return. use of Constants.COUNT_ALL will result in the entire collection being returned, but this is STRONGLY discouraged.

sortProperty_ - the property by which the results will be sorted This is one of the SORT_BY_XXX constants in UserProfile

sortOrder_ - Constants.SORT_ORDER_ASCENDING for sorting results in ascending order, Constants.SORT_ORDER_DESCENDING for sorting results in descending order

Returns:

a ResultPage containing an array of UserProfile objects

Throws:

ServiceException - if any system-level error occurs

searchUserProfilesPaging

ResultPage searchUserProfilesPaging(java.lang.String query_,
                                    int startIndex_,
                                    int batchSize_,
                                    java.lang.Integer sortProperty_,
                                    java.lang.Integer sortOrder_)

Searches for Users by first, last, and username and returns the UserProfile objects for each found User

Parameters:

query_ - The query by which to search for UserProfiles.

startIndex_ - the index into the collection of total results at which to start. Negative numbers are treated as zeros.

batchSize_ - the number of results to return. Use Constants.COUNT_ALL to return the entire collection, but this is STRONGLY discouraged.

sortProperty_ - the property by which the results will be sorted. This is one of the SORT_BY_XXX constants in UserProfile

sortOrder_ - the order in which to sort the results. This is one of Constants.SORT_ORDER_ASCENDING or Constants.SORT_ORDER_DESCENDING

Returns:

A ResultPage of UserProfile objects which match the query.

Throws:

ServiceException - if any system-level error occurs

getApplicationName

java.lang.String getApplicationName()

Gets the name of the application on which this service is running.

Returns:

the name of the application

Throws:

ServiceException - if any system-level error occurs

getWorkspace

java.lang.String[] getWorkspace()

Gets the current memory profile for the workspace.

Returns:

array of Strings of length 4 describing memory usage:

• [0]Used - Memory Used by the Server so far for storage
• [1]Allocated - Memory allocated for use. Often if a large data item was allocated by a server and subsequently freed, this value will be large compared to "Used". If nearly all memory allocated is in use, this value will be close to (but always higher than) "Used"
• [2]Mapped - is the space used by memory-mapped files
• [3]Available - is the total available memory for the Server process

Note: All usage statistics are in Bytes.

Throws:

ServiceException - if any system-level error occurs

getUserPreferences

UserPreferences getUserPreferences()

Returns current user's preferences

Returns:

the UserPreferences

setUserPreferences

void setUserPreferences(UserPreferences preferences_)

Set current user's preferences

Parameters:

preferences_ - The UserPreferences for the current user