com.sap.security.api

Interface IUserFactory

All Superinterfaces:

IConfigurable

public interface IUserFactory
extends IConfigurable

The user factory provides means to

1. instantiate user objects,
2. create new users (possibly by copying the data of an existing one),
3. delete users,
4. search for users based on different criteria and
5. perform mass commit/rollback operations on a set of users.

NOTE: As this interface�can be extended, this interface can be freely used, but must not be implemented.

Field Summary

static String

VERSIONSTRING

Method Summary

void	commitUser(IUserMaint user, IUserAccount account) Creates the user and the account object within one transaction Note: Both objects have to be new or exist already.
void	deleteUser(String uniqueID) Delete a user from the user store Note: deletes also the accounts which are assigned to this user as well as the direct group and role assignments of this user.
IUserMaint	getMutableUser(String uniqueId) Get a user object which can be modified.
ISearchResult	getUniqueIDs() Gets the unique IDs of all users in the user store.
IUser	getUser(String uniqueID) Gets the user object with the given unique ID
IUser	getUser(String uniqueID, AttributeList populateAttributes) Gets the user object with the given unique ID and populates the attributes specified in populateAttributes
IUser	getUserByLogonAlias(String logonalias, AttributeList attrlist) Returns a User object for an existing user.
IUser	getUserByLogonID(String logonid) Returns a User object for an existing user.
IUser	getUserByLogonID(String logonid, AttributeList attributeList) Returns a User object for an existing user.
IUser	getUserByPersonID(String personid) Returns a User object who matches the given personid.
IUser	getUserByPersonID(String personid, AttributeList attributeList) Returns a User object who matches the given personid.
IUser	getUserByUniqueName(String uniqueName) Gets the user object with the given uniqueName Note: If you use this method be prepared to get an exception if multiple objects with the same name are found
IUser	getUserByUniqueName(String uniqueName, AttributeList attributeList) Gets the user object with the given uniqueName Note: If you use this method be prepared to get an exception if multiple objects with the same name are found
IUser[]	getUsers(String[] uniqueIDs) Gets the user objects for multiple unique IDs
IUser[]	getUsers(String[] uniqueIDs, AttributeList populateAttributes) Gets the user objects for multiple unique IDs and populates the attributes specified in populateAttributes
IUserSearchFilter	getUserSearchFilter() Returns an IUserSearchFilter object to be used to specify query attributes
void	invalidateCacheEntry(String uniqueid) removes the user object which has the specified uniqueid from the factory's cache Note: Use this method carefully, because calling it too often may cause performance problems
void	invalidateCacheEntryByLogonId(String logonid) removes the user object which belongs to the account which has the specified logonid from the factory's cache.
void	invalidateCacheEntryByUniqueName(String uniqueName) removes the user object which has the specified unique name from the factory's cache Note: Use this method carefully, because calling it too often may cause performance problems * @param uniqueName the uniqueName of the user
boolean	isUserCreationPossible() Returns whether a user can be created with the active UME configuration.
IUserMaint	newUser(String uniqueName) Creates a new, initially blank user object with the given uniqueName.
IUserMaint	newUser(String uniqueName, IUser copyFrom) Creates a new user with the given uniqueName.
IUserMaint[]	newUsers(String[] uniqueNames) Creates a new, initially blank user objects.
void	registerListener(UserListener userListener, int modifier) registerListener allows to subscribe to a predefined eventName UserListener The caller has to provide a receiver object which implements UserListener
void	registerListener(UserListener userListener, int modifier, boolean notifyAfterPhysicalCommitCompleted) registerListener allows to subscribe to a predefined eventName UserListener The caller has to provide a receiver object which implements UserListener
ISearchResult	searchUsers(IUserSearchFilter filter) Search for users in the user store which match the criteria specified in the given filter.
ISearchResult	searchUsers(IUserSearchFilter ufilter, IUserAccountSearchFilter uafilter) Search for users in the user store and user account store which match the criteria specified in the given ufilter and uafilter and combine the result.
void	unregisterListener(UserListener userListener) unregisterListener unsubscribes a receiver from a previously subscribed event.

Methods inherited from interface com.sap.security.api.IConfigurable

initialize

Field Detail

VERSIONSTRING

static final String VERSIONSTRING

See Also:

Constant Field Values

Method Detail

getUniqueIDs

ISearchResult getUniqueIDs()
                           throws UMException

Gets the unique IDs of all users in the user store.

Note this operation might be very time consuming because all uniqueIDs of the complete user population are returned.

Returns:

ISearchResult

Throws:

UMException

getUser

IUser getUser(String uniqueID)
              throws UMException

Gets the user object with the given unique ID

Parameters:

uniqueID - String representing the uniqueID of a user object.

Throws:

NoSuchUserException - if no user with the given unique ID exists

UMException

getUser

IUser getUser(String uniqueID,
              AttributeList populateAttributes)
              throws UMException

Gets the user object with the given unique ID and populates the attributes specified in populateAttributes

Parameters:

uniqueID - String representing the uniqueID of a role object.

populateAttributes - The attributes that should be populated.

Note: in case only attribute IPrincipal.UNIQUE_NAME is specified the existence of the returned IUser object may not be checked which may lead to following RuntimeException PrincipalNotAccessibleException if other attributes of this IUser object are accessed.

Throws:

NoSuchUserException - if no user with the given unique ID exists

UMException

getUserByUniqueName

IUser getUserByUniqueName(String uniqueName)
                          throws UMException

Gets the user object with the given uniqueName

Note: If you use this method be prepared to get an exception if multiple objects with the same name are found

Parameters:

uniqueName - of IUser object

Throws:

NoSuchUserException - if no user with the given unique name exists

UMException - if given unique name is not unique

getUserByUniqueName

IUser getUserByUniqueName(String uniqueName,
                          AttributeList attributeList)
                          throws UMException

Gets the user object with the given uniqueName

Note: If you use this method be prepared to get an exception if multiple objects with the same name are found

Parameters:

uniqueName - of IUser object

attributeList - The attributes that should be populated

Throws:

NoSuchUserException - if no user with the given unique name exists

UMException - if given unique name is not unique

getUsers

IUser[] getUsers(String[] uniqueIDs)
                 throws UMException

Gets the user objects for multiple unique IDs

Parameters:

uniqueIDs - array of uniqueIDs which are used to get an array of IUser objects.

Returns:

IUser[] array of IUser objects

Throws:

NoSuchUserException - if one or more of the given unique IDs are not assigned to any user

UMException

getUsers

IUser[] getUsers(String[] uniqueIDs,
                 AttributeList populateAttributes)
                 throws UMException

Gets the user objects for multiple unique IDs and populates the attributes specified in populateAttributes

Parameters:

uniqueIDs - array of uniqueIDs which are used to get an array of IUser objects.

populateAttributes - The attributes that should be populated AttributeList

Returns:

IUser[] array of IUser objects

Throws:

NoSuchUserException - if one or more of the given unique IDs are not assigned to any user

UMException

newUser

IUserMaint newUser(String uniqueName)
                   throws UMException

Creates a new, initially blank user object with the given uniqueName. After setting the appropriate data via IUserMaint's set-methods, the user object must be commited to the user store via IPrincipalMaint.commit().

Parameters:

uniqueName - of new IRole object. Note: This name has to be unique for ALL data stores

Returns:

IUserMaint a user object which can be modified

Throws:

UserAlreadyExistsException - if a user with the given uniqueName already exists; depending on the implementation, checking for already existing users may also be deferred to when IPrincipalMaint.commit() is called.

InvalidIDException - if uniqueName doesn't meet the user store's requirements (e.g. its too long)

UserAlreadyExistsException - if user with uniqueName already exists

UMException

newUser

IUserMaint newUser(String uniqueName,
                   IUser copyFrom)
                   throws UMException

Creates a new user with the given uniqueName. The existing user copyFrom will be used as a template, i.e. some (but not necessarily all) attributes will be copied to the new user object.

Parameters:

uniqueName - of new IRole object. Note: This name has to be unique for ALL data stores

copyFrom - instance of an IUser object which should be copied.

Returns:

IUserMaint a user object which can be modified

Throws:

UserAlreadyExistsException - if a user with the given uniqueName already exists; depending on the implementation, checking for already existing users may also be deferred to when IPrincipalMaint.commit() is called.

InvalidIDException - if uniqueName doesn't meet the user store's requirements (e.g. its too long)

UserAlreadyExistsException - if user with uniqueName already exists

UMException

deleteUser

void deleteUser(String uniqueID)
                throws UMException

Delete a user from the user store Note: deletes also the accounts which are assigned to this user as well as the direct group and role assignments of this user.

Parameters:

uniqueID - String representing the uniqueID of a user object.

Throws:

UMException - if the user can't be deleted

NoSuchUserException - if the user does not exist

searchUsers

ISearchResult searchUsers(IUserSearchFilter filter)
                          throws UMException

Search for users in the user store which match the criteria specified in the given filter. In order to get a user search filter use getUserSearchFilter(). You can define a search filter using IUserSearchFilter.

Returns:

ISearchResult result of the search operation ISearchResult

Throws:

UMException

searchUsers

ISearchResult searchUsers(IUserSearchFilter ufilter,
                          IUserAccountSearchFilter uafilter)
                          throws UMException

Search for users in the user store and user account store which match the criteria specified in the

given ufilter and uafilter and combine the result. In order to get a user search filter use getUserSearchFilter() and IUserAccountFactory.getUserAccountSearchFilter().

Returns:

ISearchResult result of the search operation ISearchResult

Throws:

UMException

getUserByPersonID

IUser getUserByPersonID(String personid)
                        throws UMException

Returns a User object who matches the given personid.

Parameters:

personid - PersonID of the user

Returns:

IUser the user object

Throws:

UMException - in case of an error

NoSuchUserException - if the user does not exist

getUserByPersonID

IUser getUserByPersonID(String personid,
                        AttributeList attributeList)
                        throws UMException

Returns a User object who matches the given personid.

Parameters:

personid - PersonID of the user

attributeList - The attributes that should be populated

Returns:

IUser the user object

Throws:

UMException - in case of an error

NoSuchUserException - if the user does not exist

getUserByLogonID

IUser getUserByLogonID(String logonid)
                       throws UMException

Returns a User object for an existing user.

Parameters:

logonid - Logon id of the user

Returns:

IUser the user object

Throws:

UMException - in case of an error

NoSuchUserException - if the user does not exist

getUserByLogonID

IUser getUserByLogonID(String logonid,
                       AttributeList attributeList)
                       throws UMException

Returns a User object for an existing user.

Parameters:

logonid - Logon id of the user

attributeList - The attributes that should be populated

Returns:

IUser the user object

Throws:

UMException - in case of an error

NoSuchUserException - if the user does not exist

getUserByLogonAlias

IUser getUserByLogonAlias(String logonalias,
                          AttributeList attrlist)
                          throws UMException

Returns a User object for an existing user. Note: Use this method carefully, because the user objects returned by this method are not read from a cache, which may cause performance problems.

Parameters:

logonalias - Logon alias of the user

attrlist - The attribute list or null.

Returns:

IUser the user object

Throws:

UMException - in case of an error

NoSuchUserException - if the user does not exist

DuplicateKeyException - if multiple users have the same logonalias

newUsers

IUserMaint[] newUsers(String[] uniqueNames)
                      throws UMException

Creates a new, initially blank user objects. Given uniqueNames are set to the users. After setting the appropriate data via IUserMaint's set-methods, each user object must be saved and commited to the user store via IPrincipalMaint.commit(). For batch save and commit use IPrincipalMaint.save() and IPrincipalMaint.commit()

Parameters:

uniqueNames - Array of uniqueNames Note: This name has to be unique for ALL data stores

Returns:

IUserMaint[] array of user objects which can be modified

Throws:

UserAlreadyExistsException - if user with uniqueName already exists

UMException

getMutableUser

IUserMaint getMutableUser(String uniqueId)
                          throws UMException

Get a user object which can be modified. This method returns an object which implements IUserMaint interface which contains the corresponding set-methods. After setting the appropriate data via IUserMaint's set-methods, each user object must be saved and commited to the user store via IPrincipalMaint.commit().

Parameters:

uniqueId - of an IUser object

Returns:

IUserMaint[] array of user objects which can be modified

Throws:

UMException

getUserSearchFilter

IUserSearchFilter getUserSearchFilter()
                                      throws UMException

Returns an IUserSearchFilter object to be used to specify query attributes

Returns:

IUserSearchFilter container for values to be used as a search filter

Throws:

UMException

FeatureNotAvailableException

registerListener

void registerListener(UserListener userListener,
                      int modifier)

registerListener allows to subscribe to a predefined eventName UserListener The caller has to provide a receiver object which implements UserListener

Parameters:

userListener - object which implements interface UserListener

modifier - constant defined in UserListener

registerListener

void registerListener(UserListener userListener,
                      int modifier,
                      boolean notifyAfterPhysicalCommitCompleted)

registerListener allows to subscribe to a predefined eventName UserListener The caller has to provide a receiver object which implements UserListener

Parameters:

userListener - object which implements interface UserListener

modifier - constant defined in UserListener

notifyAfterPhysicalCommitCompleted - Allows callers when set to false, to get a notification before the physical transaction is completed in order to include their actions into the same physical transaction.

unregisterListener

void unregisterListener(UserListener userListener)

unregisterListener unsubscribes a receiver from a previously subscribed event.

Parameters:

userListener - object which implements interface UserListener

invalidateCacheEntryByLogonId

void invalidateCacheEntryByLogonId(String logonid)
                                   throws UMException

removes the user object which belongs to the account which has the specified logonid from the factory's cache. Calling this method also removes the user account which has the specified logonid from the UserAccountFactory's cache. Note: Use this method carefully, because calling it too often may cause performance problems

Parameters:

logonid - the logonid of the user account

Throws:

UMException - if a error occurs

invalidateCacheEntryByUniqueName

void invalidateCacheEntryByUniqueName(String uniqueName)
                                      throws UMException

removes the user object which has the specified unique name from the factory's cache Note: Use this method carefully, because calling it too often may cause performance problems * @param uniqueName the uniqueName of the user

Throws:

UMException - if an error occurs

invalidateCacheEntry

void invalidateCacheEntry(String uniqueid)
                          throws UMException

removes the user object which has the specified uniqueid from the factory's cache Note: Use this method carefully, because calling it too often may cause performance problems

Parameters:

uniqueid - the uniqueid of the user

Throws:

UMException - if an error occurs

commitUser

void commitUser(IUserMaint user,
                IUserAccount account)
                throws UMException

Creates the user and the account object within one transaction Note: Both objects have to be new or exist already. Mixing creation and update is not possible

Parameters:

user - the user object

account - the user account object

Throws:

UMException - if an error occurs

isUserCreationPossible

boolean isUserCreationPossible()
                               throws UMException

Returns whether a user can be created with the active UME configuration.

Returns:

true if an IUser can be created, otherwise false.

Throws:

UMException - if an error occurs

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGINEAPI	[sap.com] com.sap.security.api.sda
[sap.com] ENGFACADE	[sap.com] tc/je/usermanagement/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib