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
5. get meta-data for custom principal objects

Version:

1.0

Field Summary

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

Method Summary

void	addDataSource(java.io.InputStream configuration) Adds a new datasource dynamically to IPrincipalFactory.
void	addPrincipalToParent(java.lang.String customObjectId, java.lang.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(java.lang.String uniqueID) Delete a object from the use store
void	deregisterPrincipalMetaData(java.lang.String principalTypeIdentifier) Deregisters the IPrincipalMetaData object.
IPrincipalMetaData[]	getAvailablePrincipalMetaData() Get all available IPrincipalMetaData objects.
IPrincipalMaint	getMutablePrincipal(java.lang.String uniqueId) Get a object which can be modified.
IPrincipal	getPrincipal(java.lang.String uniqueId) Get a principal by using its id.
IPrincipal	getPrincipal(java.lang.String uniqueId, AttributeList populateAttributes) Get a principal by using its uniqueId and the populateAttributes which should be populated.
IPrincipalMetaData	getPrincipalMetaData(java.lang.String principalTypeIdentifier) Get a IPrincipalMetaData object for the given principal type identifier.
IPrincipal[]	getPrincipals(java.lang.String[] uniqueIDs) Gets the objects for multiple unique IDs
IPrincipal[]	getPrincipals(java.lang.String[] uniqueIDs, AttributeList populateAttributes) Gets the objects for multiple unique IDs and populates all attributes in populateAttributes
IPrincipalSearchFilter	getPrincipalSearchFilter(boolean orMode, java.lang.String principalTypeIdentifier) Returns an IPrincipalSearchFilter object to be used to specify query attributes
java.lang.String	getPrincipalType(java.lang.String uniqueId) get the data type out of a principal's uniqueId.
java.lang.String	getPrincipalTypeIdentifier(java.lang.String uniqueId) Get the principal type identifier for this custom object.
boolean	isPrincipalAttributeModifiable(java.lang.String uniqueId, java.lang.String namespace, java.lang.String attributename) Checks whether a specific attribute of the principal with the given uniqueId is modifiable.
boolean	isPrincipalDeletable(java.lang.String uniqueId) Checks whether the principal with the given uniqueId can be deleted.
boolean	isPrincipalModifiable(java.lang.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(java.lang.String principalTypeIdentifier) Creates a new, initially blank object.
IPrincipalMetaData	newPrincipalMetaData(java.lang.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(java.lang.String principalTypeIdentifier, int num) Creates new, initially blank object objects.
IPrincipalSet	newPrincipalSet(IPrincipalSet copyFrom) Creates a new object.
IPrincipalSet	newPrincipalSet(java.lang.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	registerPrincipalMetaData(IPrincipalMetaData metadata) Registers the given IPrincipalMetaData object.
void	removePrincipalFromParent(java.lang.String customObjectId, java.lang.String parentPrincipalId) unassign customObject with customObjectId to parent-customOjbect with parentPrincipalId.
void	rollbackPrincipals(IPrincipalMaint[] objects) Roll back (i.e.
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
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

public static final java.lang.String VERSIONSTRING

IUSER

public static final java.lang.String IUSER

IUSERACCOUNT

public static final java.lang.String IUSERACCOUNT

IGROUP

public static final java.lang.String IGROUP

IROLE

public static final java.lang.String IROLE

IPRINCIPAL

public static final java.lang.String IPRINCIPAL

IPRINCIPALSET

public static final java.lang.String IPRINCIPALSET

ICUSTOM_OBJECT

public static final java.lang.String ICUSTOM_OBJECT

Deprecated.

Method Detail

getPrincipalType

public java.lang.String getPrincipalType(java.lang.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

public IPrincipal getPrincipal(java.lang.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

public IPrincipal getPrincipal(java.lang.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

public boolean isPrincipalModifiable(java.lang.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

public boolean isPrincipalDeletable(java.lang.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

public boolean isPrincipalAttributeModifiable(java.lang.String uniqueId,
                                              java.lang.String namespace,
                                              java.lang.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

public IPrincipal[] getPrincipals(java.lang.String[] uniqueIDs)
                           throws NoSuchPrincipalException

Gets the objects for multiple unique IDs

Parameters:

String[] - 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

public IPrincipal[] getPrincipals(java.lang.String[] uniqueIDs,
                                  AttributeList populateAttributes)
                           throws NoSuchPrincipalException

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

Parameters:

String[] - 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

public IPrincipalMaint newPrincipal(java.lang.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

public IPrincipalSet newPrincipalSet(java.lang.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

public 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:

IPrincipalSet - The object which is used as a blueprint

Returns:

IPrincipalSet The new object implementing IPrincipalSet

newPrincipal

public 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:

IPrincipal - The object which is used as a blueprint

Returns:

IPrincipalMaint The new object implementing IPrincipalMaint

deletePrincipal

public void deletePrincipal(java.lang.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

commitPrincipals

public 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:

IPrincipalMaint[] - Objects which should be stored to the data store

Throws:

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

rollbackPrincipals

public 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:

IPrincipalMaint[] - Objects which should be stored to the data store

Throws:

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

searchPrincipals

public 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:

IPrincipalSearchFilter - filter defined to search for principals

Returns:

ISearchResult The result of the search

savePrincipals

public void savePrincipals(IPrincipalMaint[] objects)
                    throws UMException

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

Parameters:

IPrincipalMaint[] - objects which should be saved

newPrincipals

public IPrincipalMaint[] newPrincipals(java.lang.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

principalTypeIdentifier -

num - number of new blank objects requested

getMutablePrincipal

public IPrincipalMaint getMutablePrincipal(java.lang.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

public java.lang.String getPrincipalTypeIdentifier(java.lang.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:

the - unique id of the object

Returns:

the principal type identifier

getPrincipalSearchFilter

public IPrincipalSearchFilter getPrincipalSearchFilter(boolean orMode,
                                                       java.lang.String principalTypeIdentifier)
                                                throws UMException

Returns an IPrincipalSearchFilter object to be used to specify query attributes

IPrincipalSearchFilter only contains attributes which will be queried

Returns:

IPrincipalSearchFilter

Throws:

UMException -

FeatureNotAvailableException -

addPrincipalToParent

public void addPrincipalToParent(java.lang.String customObjectId,
                                 java.lang.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

public void removePrincipalFromParent(java.lang.String customObjectId,
                                      java.lang.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

public 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:

PrincipalListener - object which should be registered

modifier - constant defined in PrincipalListener

unregisterListener

public void unregisterListener(PrincipalListener objectListener)

unregisterListener unsubscribes a receiver from a previously subscribed event.

Parameters:

PrincipalListener - object which should be unregistered

newPrincipalMetaData

public IPrincipalMetaData newPrincipalMetaData(java.lang.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

registerPrincipalMetaData

public 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

deregisterPrincipalMetaData

public void deregisterPrincipalMetaData(java.lang.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.

getAvailablePrincipalMetaData

public 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

getPrincipalMetaData

public IPrincipalMetaData getPrincipalMetaData(java.lang.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

addDataSource

public void addDataSource(java.io.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:

throws - UMException if an error occurs.