com.sap.security.api

Interface IPrincipalFactory

All Superinterfaces:

IConfigurable

public interface IPrincipalFactory
extends IConfigurable

The principal factory provides means to

1. instantiate principal objects,
2. create new principal (possibly by copying the data of an existing one),
3. delete principals,
4. search for principals based on different criteria and
5. get meta-data for custom principal objects.

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

Field Summary

static String	ICUSTOM_OBJECT Deprecated.
static String	IGROUP
static String	IPRINCIPAL
static String	IPRINCIPALSET
static String	IROLE
static String	IUSER
static String	IUSERACCOUNT
static String	VERSIONSTRING

Method Summary

void	addDataSource(InputStream configuration) Adds a new datasource dynamically to IPrincipalFactory.
void	addPrincipalToParent(String customObjectId, String parentPrincipalId) assign customObject with customObjectId to parent-customOjbect with parentPrincipalId.
void	commitPrincipals(IPrincipalMaint[] objects) Commit the changes applied to a set of objects to the object store in one pass.
void	deletePrincipal(String uniqueID) Delete a object from the use store
void	deletePrincipals(String[] uniqueIDs) Delete objects from the principal store
void	deregisterPrincipalMetaData(String principalTypeIdentifier) Deregisters the IPrincipalMetaData object.
IPrincipalMetaData[]	getAvailablePrincipalMetaData() Get all available IPrincipalMetaData objects.
IPrincipalMaint	getMutablePrincipal(String uniqueId) Get a object which can be modified.
IPrincipal	getPrincipal(String uniqueId) Get a principal by using its id.
IPrincipal	getPrincipal(String uniqueId, AttributeList populateAttributes) Get a principal by using its uniqueId and the populateAttributes which should be populated.
IPrincipalMetaData	getPrincipalMetaData(String principalTypeIdentifier) Get a IPrincipalMetaData object for the given principal type identifier.
IPrincipal[]	getPrincipals(String[] uniqueIDs) Gets the objects for multiple unique IDs
IPrincipal[]	getPrincipals(String[] uniqueIDs, AttributeList populateAttributes) Gets the objects for multiple unique IDs and populates all attributes in populateAttributes
IPrincipalSearchFilter	getPrincipalSearchFilter(boolean orMode, String principalTypeIdentifier) Returns an IPrincipalSearchFilter object to be used to specify query attributes IPrincipalSearchFilter only contains attributes which will be queried
String	getPrincipalType(String uniqueId) get the data type out of a principal's uniqueId.
String	getPrincipalTypeIdentifier(String uniqueId) Get the principal type identifier for this custom object.
boolean	isPrincipalAttributeModifiable(IPrincipal principal, String namespace, String attributename) Checks whether a specific attribute of the given principal is modifiable.
boolean	isPrincipalAttributeModifiable(String uniqueId, String namespace, String attributename) Checks whether a specific attribute of the principal with the given uniqueId is modifiable.
boolean	isPrincipalDeletable(String uniqueId) Checks whether the principal with the given uniqueId can be deleted.
boolean	isPrincipalModifiable(String uniqueId) Checks whether at least one attribute of the principal with the given uniqueId is modifiable.
IPrincipalMaint	newPrincipal(IPrincipal copyFrom) Creates a new object.
IPrincipalMaint	newPrincipal(String principalTypeIdentifier) Creates a new, initially blank object.
IPrincipalMetaData	newPrincipalMetaData(String principalTypeIdentifier, int principalType) Returns a new IPrincipalMetaData object, or throws a ObjectAlreadyExistsException, if there is already a IPrincipalMetaData object for the given principalTypeIdentifier.
IPrincipalMaint[]	newPrincipals(String principalTypeIdentifier, int num) Creates new, initially blank object objects.
IPrincipalSet	newPrincipalSet(IPrincipalSet copyFrom) Creates a new object.
IPrincipalSet	newPrincipalSet(String principalTypeIdentifier) Creates a new, initially blank object.
void	registerListener(PrincipalListener objectListener, int modifier) registerListener allows to subscribe to a predefined eventName PrincipalListener The caller has to provide a receiver object which implements PrincipalListener
void	registerListener(PrincipalListener objectListener, int modifier, boolean notifyAfterPhysicalCommitCompleted) registerListener allows to subscribe to a predefined eventName PrincipalListener The caller has to provide a receiver object which implements PrincipalListener
void	registerPrincipalMetaData(IPrincipalMetaData metadata) Registers the given IPrincipalMetaData object.
void	removePrincipalFromParent(String customObjectId, String parentPrincipalId) unassign customObject with customObjectId to parent-customOjbect with parentPrincipalId.
void	rollbackPrincipals(IPrincipalMaint[] objects) Roll back (i.e. discard) the changes applied to a set of objects .
void	savePrincipals(IPrincipalMaint[] objects) Batch save, the data is not made permanent until commitObjects() is called
ISearchResult	searchPrincipals(IPrincipalSearchFilter filter) Search for objects in the objects store which match the criteria specified in the given filter.
ISearchResult	simplePrincipalSearch(String searchCriteria, String principalType, int mode, boolean caseSensitive, Map searchAttributes) Search for principals using the default attributes (or combined) which are defined in the UME configuration.
void	unregisterListener(PrincipalListener objectListener) 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

IUSER

static final String IUSER

See Also:

Constant Field Values

IUSERACCOUNT

static final String IUSERACCOUNT

See Also:

Constant Field Values

IGROUP

static final String IGROUP

See Also:

Constant Field Values

IROLE

static final String IROLE

See Also:

Constant Field Values

IPRINCIPAL

static final String IPRINCIPAL

See Also:

Constant Field Values

IPRINCIPALSET

static final String IPRINCIPALSET

See Also:

Constant Field Values

ICUSTOM_OBJECT

static final String ICUSTOM_OBJECT

Deprecated.

See Also:

Constant Field Values

Method Detail

getPrincipalType

String getPrincipalType(String uniqueId)
                        throws UMException

get the data type out of a principal's uniqueId. Possible values are IUSER, IUSERACCOUNT, IGROUP, IROLE, IPRINCIPAL, IPRINCIPALSET

Parameters:

uniqueId - The unique id of a principal

Returns:

String The data type of the principal

Throws:

UMException

getPrincipal

IPrincipal getPrincipal(String uniqueId)
                        throws UMException

Get a principal by using its id. Throws exception, if the principal doesn't exist.

Parameters:

uniqueId - The unique id of the principal

Returns:

IPrincipal The principal object

Throws:

UMException

getPrincipal

IPrincipal getPrincipal(String uniqueId,
                        AttributeList populateAttributes)
                        throws UMException

Get a principal by using its uniqueId and the populateAttributes which should be populated. Throws exception, if the principal doesn't exist.

Parameters:

uniqueId - The unique id of the principal

populateAttributes - The attributes which should be populated

Returns:

IPrincipal The principal object

Throws:

UMException

isPrincipalModifiable

boolean isPrincipalModifiable(String uniqueId)
                              throws UMException

Checks whether at least one attribute of the principal with the given uniqueId is modifiable. Returns true if at least one attribute is modifiable, false otherwise. Throws exception, if an error occurs during the check.

Parameters:

uniqueId - The unique id of the principal

Returns:

boolean The result of the check

Throws:

UMException

isPrincipalDeletable

boolean isPrincipalDeletable(String uniqueId)
                             throws UMException

Checks whether the principal with the given uniqueId can be deleted. Returns true if the principal can be deleted, false otherwise. Throws exception, if a error occurs during the ceck.

Parameters:

uniqueId - The unique id of the principal

Returns:

boolean The result of the check

Throws:

UMException

isPrincipalAttributeModifiable

boolean isPrincipalAttributeModifiable(IPrincipal principal,
                                       String namespace,
                                       String attributename)
                                       throws UMException

Checks whether a specific attribute of the given principal is modifiable. Returns true if the attribute is modifiable, false otherwise. Throws exception, if a error occurs during the ceck.

Parameters:

principal - The principal

namespace - The namespace of the attribute

attributename - The name of the attribute

Returns:

boolean The result of the check

Throws:

UMException

isPrincipalAttributeModifiable

boolean isPrincipalAttributeModifiable(String uniqueId,
                                       String namespace,
                                       String attributename)
                                       throws UMException

Checks whether a specific attribute of the principal with the given uniqueId is modifiable. Returns true if the attribute is modifiable, false otherwise. Throws exception, if a error occurs during the ceck.

Parameters:

uniqueId - The unique id of the principal

namespace - The namespace of the attribute

attributename - The name of the attribute

Returns:

boolean The result of the check

Throws:

UMException

getPrincipals

IPrincipal[] getPrincipals(String[] uniqueIDs)
                           throws NoSuchPrincipalException

Gets the objects for multiple unique IDs

Parameters:

uniqueIDs - array of uniqueIDs which are used to identify the principal objects

Returns:

IPrincipal[] An array of IPrincipal objects.

Throws:

NoSuchPrincipalException - if one or more of the given unique IDs are not assigned to any object

getPrincipals

IPrincipal[] getPrincipals(String[] uniqueIDs,
                           AttributeList populateAttributes)
                           throws NoSuchPrincipalException

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

Parameters:

uniqueIDs - array of uniqueIDs which are used to identify the principal objects

populateAttributes - AttributeList

Returns:

IPrincipal[] An array of IPrincipal objects.

Throws:

NoSuchPrincipalException - if one or more of the given unique IDs are not assigned to any object

newPrincipal

IPrincipalMaint newPrincipal(String principalTypeIdentifier)

Creates a new, initially blank object. The unique ID for the new object will be generated by the object factory. The principalTypeIdentifier has to have exactly 4 uppercase letters (A-Z), whereas identifiers starting with X-Z are reserved for customers, and identifiers starting with A-W are reserved for SAP. Allowed are all values except USER, ROLE, GRUP, TEAM, UACC, OOOO and COMP. After setting the appropriate data via IPrincipalMaint's set-methods, the object object must be commited to the object store via IPrincipalMaint.commit(). Note: don't forget to add this type to the data source configuration. One data source has to be home for this object type

Parameters:

principalTypeIdentifier - 4 letter Identifier for this new principal

Returns:

IPrincipalMaint A principal object implementing IPrincipalMaint.

newPrincipalSet

IPrincipalSet newPrincipalSet(String principalTypeIdentifier)

Creates a new, initially blank object. The unique ID for the new object will be generated by the object factory. For details about the principalTypeIdentifier see newPrincipal(String) After setting the appropriate data via IPrincipalMaint's set-methods, the object object must be commited to the object store via IPrincipalMaint.commit(). Note: don't forget to add this type to the data source configuration. One data source has to be home for this object type

Parameters:

principalTypeIdentifier - 4 letter Identifier for this new principal

Returns:

IPrincipalSet The new object implementing IPrincipalSet

newPrincipalSet

IPrincipalSet newPrincipalSet(IPrincipalSet copyFrom)

Creates a new object. The existing object copyFrom will be used as a template, i.e. some (but not necessarily all) attributes will be copied to the new object. The unique ID for the new object will be generated by the object factory. After setting the appropriate data via set-methods, the principal object must be commited to the principal store via IPrincipalMaint.commit().

Parameters:

copyFrom - The object which is used as a blueprint

Returns:

IPrincipalSet The new object implementing IPrincipalSet

newPrincipal

IPrincipalMaint newPrincipal(IPrincipal copyFrom)

Creates a new object. The existing object copyFrom will be used as a template, i.e. some (but not necessarily all) attributes will be copied to the new object. The unique ID for the new object will be generated by the object factory. After setting the appropriate data via set-methods, the principal object must be commited to the principal store via IPrincipalMaint.commit().

Parameters:

copyFrom - The object which is used as a blueprint

Returns:

IPrincipalMaint The new object implementing IPrincipalMaint

deletePrincipal

void deletePrincipal(String uniqueID)
                     throws UMException

Delete a object from the use store

Parameters:

uniqueID - The unique id of the principal

Throws:

UMException - if the object can't be deleted

deletePrincipals

void deletePrincipals(String[] uniqueIDs)
                      throws UMException

Delete objects from the principal store

Parameters:

uniqueIDs - The unique ids of the principals

Throws:

UMException - if the objects can't be deleted

commitPrincipals

void commitPrincipals(IPrincipalMaint[] objects)
                      throws UMException

Commit the changes applied to a set of objects to the object store in one pass. Depending on the object factory's implementation, this will result in better performance than calling IPrincipalMaint.commit() on each object object individually. Note that either commiting or rolling back changes will be required to unlock objects if the object factory employs pessimistic locking.

Parameters:

objects - Objects which should be stored to the data store

Throws:

UMException - if one or more of the IPrincipalMaint objects cannot be stored successfully.

rollbackPrincipals

void rollbackPrincipals(IPrincipalMaint[] objects)
                        throws UMException

Roll back (i.e. discard) the changes applied to a set of objects . Note that either commiting or rolling back changes will be required to unlock objects if the object factory employs pessimistic locking.

Parameters:

objects - Objects which should be stored to the data store

Throws:

UMException - if one or more of the IPrincipalMaint objects cannot be discarded successfully.

searchPrincipals

ISearchResult searchPrincipals(IPrincipalSearchFilter filter)
                               throws UMException

Search for objects in the objects store which match the criteria specified in the

given filter. In order to get a principal search filter use getPrincipalSearchFilter(boolean,String). You can define a search filter using methods of IPrincipalSearchFilter.

Parameters:

filter - filter defined to search for principals

Returns:

ISearchResult The result of the search

Throws:

UMException

savePrincipals

void savePrincipals(IPrincipalMaint[] objects)
                    throws UMException

Batch save, the data is not made permanent until commitObjects() is called

Parameters:

objects - objects which should be saved

Throws:

UMException

newPrincipals

IPrincipalMaint[] newPrincipals(String principalTypeIdentifier,
                                int num)

Creates new, initially blank object objects. The unique ID for the new object will be generated by the object factory. After setting the appropriate data via IPrincipalMaint's set-methods, each object object must be saved and commited to the object store via IPrincipalMaint.commit(). For batch save and commit savePrincipals(IPrincipalMaint[]) and commitPrincipals(IPrincipalMaint[])

Parameters:

principalTypeIdentifier - The principal type identifier

num - number of new blank objects requested

getMutablePrincipal

IPrincipalMaint getMutablePrincipal(String uniqueId)
                                    throws UMException

Get a object which can be modified. This method returns an object which implements IPrincipalMaint interface which contains the corresponding set-methods.

Parameters:

uniqueId - The unique id of a principal

Returns:

IPrincipalMaint The principal object which can be modified

Throws:

UMException - if no modifiable object can be provided.

getPrincipalTypeIdentifier

String getPrincipalTypeIdentifier(String uniqueId)
                                  throws UMException

Get the principal type identifier for this custom object. This method returns a string which represents the type identifier of the object or throws a NoPrincipalException if the given id is a id of a ume object like IUser or IGroup etc.

Parameters:

uniqueId - the unique id of the object

Returns:

the principal type identifier

Throws:

UMException

getPrincipalSearchFilter

IPrincipalSearchFilter getPrincipalSearchFilter(boolean orMode,
                                                String principalTypeIdentifier)
                                                throws UMException

Returns an IPrincipalSearchFilter object to be used to specify query attributes

IPrincipalSearchFilter only contains attributes which will be queried

Parameters:

orMode - used to define the logical operator of the searched attributes. If orMode is true the searchfilter will combine the specified attributes with the logical OR operator. If orMode is false the defined search attributes are combined with the logical AND operator.

principalTypeIdentifier - specifies the type of the principal. Examples of reserved principal types are "USER", "ROLE" or "GRUP". For details about the principalTypeIdentifier see newPrincipal(String)

Returns:

IPrincipalSearchFilter

Throws:

UMException

FeatureNotAvailableException

addPrincipalToParent

void addPrincipalToParent(String customObjectId,
                          String parentPrincipalId)
                          throws UMException

assign customObject with customObjectId to parent-customOjbect with parentPrincipalId. Implicitly a commit is done if you call this method.

Parameters:

customObjectId - uniqueId of Principal

parentPrincipalId - uniqueId of the parent Principal

Throws:

UMException - if data cannot be stored successfully

removePrincipalFromParent

void removePrincipalFromParent(String customObjectId,
                               String parentPrincipalId)
                               throws UMException

unassign customObject with customObjectId to parent-customOjbect with parentPrincipalId. Implicitly a commit is done if you call this method.

Parameters:

customObjectId - uniqueId of Principal

parentPrincipalId - uniqueId of the parent Principal

Throws:

UMException - if data cannot be stored successfully

registerListener

void registerListener(PrincipalListener objectListener,
                      int modifier)

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

Parameters:

objectListener - object which should be registered

modifier - constant defined in PrincipalListener

registerListener

void registerListener(PrincipalListener objectListener,
                      int modifier,
                      boolean notifyAfterPhysicalCommitCompleted)

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

Parameters:

objectListener - object which should be registered

modifier - constant defined in PrincipalListener

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(PrincipalListener objectListener)

unregisterListener unsubscribes a receiver from a previously subscribed event.

Parameters:

objectListener - object which should be unregistered

newPrincipalMetaData

IPrincipalMetaData newPrincipalMetaData(String principalTypeIdentifier,
                                        int principalType)
                                        throws UMException

Returns a new IPrincipalMetaData object, or throws a ObjectAlreadyExistsException, if there is already a IPrincipalMetaData object for the given principalTypeIdentifier. The IPrincipalMetaData object will NOT become persistent until it is registered.

Parameters:

principalTypeIdentifier - The principalTypeIdentifier which is described by the new IPrincipalMetaData object

principalType - The semantic principal type, e.g. IPrincipalMetaData.IPrincipalSet or IPrincipalMetaData.IPrincipal

Returns:

IPrincipalMetaData the new object

Throws:

ObjectAlreadyExistsException - if there is already a object for the given principal type

UMException

registerPrincipalMetaData

void registerPrincipalMetaData(IPrincipalMetaData metadata)
                               throws UMException

Registers the given IPrincipalMetaData object. After the registration the IPrincipalMetaData object is visible for other applications and returned by the method getAvailablePrincipalMetaData(). This method modifies a already existing IPrincipalMetaData object which has the same principal type identifier as the given one. The object becomes persistent, and will also be available after the restart of the system.

Parameters:

metadata - The IPrincipalMetaData object that should be registered

Throws:

UMException

deregisterPrincipalMetaData

void deregisterPrincipalMetaData(String principalTypeIdentifier)
                                 throws UMException

Deregisters the IPrincipalMetaData object. After the deregistration the IPrincipalMetaData object is no longer visible for all applications and is no longer returned by the method getAvailablePrincipalMetaData().

Parameters:

principalTypeIdentifier - The principal type identifier.

Throws:

UMException

getAvailablePrincipalMetaData

IPrincipalMetaData[] getAvailablePrincipalMetaData()
                                                   throws UMException

Get all available IPrincipalMetaData objects. The returned array is empty, if no IPrincipalMetaData object is available.

Returns:

IPrincipalMetaData[] The list of available IPrincipalMetaData objects

Throws:

UMException

getPrincipalMetaData

IPrincipalMetaData getPrincipalMetaData(String principalTypeIdentifier)
                                        throws NoSuchObjectException,
                                               UMException

Get a IPrincipalMetaData object for the given principal type identifier. If no IPrincipalMetaData object is registered for the given principal type identifier, a NoSuchObjectException is thrown.

Parameters:

principalTypeIdentifier - The principal type identifier

Returns:

IPrincipalMetaData The found IPrincipalMetaData object

Throws:

NoSuchObjectException - If no IPrincipalMetaData object is registered for the given principal type identifier

UMException

addDataSource

void addDataSource(InputStream configuration)
                   throws UMException

Adds a new datasource dynamically to IPrincipalFactory. An object for the new data source will be instantiated and initialized by an XML formatted file. This file contains information about the principal datatype and the relevant implementing java class.

NOTE: The configuration of the new datasource has to be compatible to the configurations of already loaded datasources. Otherwise malfunctions might occur. The implementing class must be accessible from UME-core.

Parameters:

configuration - a java.io.InputStream containing the data source information in xml format which should be used to initialize the given datasource

Throws:

UMException - if an error occurs.

simplePrincipalSearch

ISearchResult simplePrincipalSearch(String searchCriteria,
                                    String principalType,
                                    int mode,
                                    boolean caseSensitive,
                                    Map searchAttributes)
                                    throws UMException

Search for principals using the default attributes (or combined) which are defined in the UME configuration.

Parameters:

searchCriteria - The search criteria which may contain wildcards if ISearchAttribute.LIKE_OPERATOR is used as mode

principalType - The type of principal to search. Possible values are: IUSER, IUSERACCOUNT, IGROUP, IROLE

mode - The modes defined in ISearchAttribute (e.g. ISearchAttribute.EQUALS_OPERATOR)

caseSensitive - The case sensitivity

searchAttributes - A map with additional search attributes like key:"company", value:"SAP"

Returns:

ISearchResult

Throws:

UMException

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