com.sap.security.api

Interface IPrincipalMaint

All Superinterfaces:

IPrincipal, Serializable

All Known Subinterfaces:

IGroup, IPrincipalSet, IRole, IUserAccount, IUserMaint

public interface IPrincipalMaint
extends IPrincipal

This interface extends IPrincipal and provides write access to a principal. It provides methods to change a principal's attributes, to commit these changes to the principal store or to roll them back (i.e. discard them) if appropriate. It is intended for administration of user profiles (including self-administration). The set-methods with boolean return values return true if the new value is different from the previous value. Calling of set-methods with a value of null to effectively remove an attribute. If invalid arguments in set-methods are detected, a UMRuntimeException is thrown. NOTE: For consistency reasons no leading or trailing spaces are allowed in namespaces, attribute names and String values. All setter methods like setAttribute(String, String, String[]) of this interface and all setter methods of derived interfaces like IUserMaint.setLastName(String) always return true to avoid performance issues due to roundtrips to the persistency.

Field Summary

Fields inherited from interface com.sap.security.api.IPrincipal

BYTE_TYPE, CREATED_BY, DATASOURCE, DEFAULT_NAMESPACE, DEFAULT_RELATION_NAMESPACE, DESCRIPTION, DISPLAYNAME, LAST_MODIFIED_BY, PRINCIPAL_CREATION_DATE, PRINCIPAL_MODIFY_DATE, PRINCIPAL_RELATION_MEMBER_ATTRIBUTE, PRINCIPAL_RELATION_PARENT_ATTRIBUTE, STRING_TYPE, TRANSIENT_NAMESPACE, UNIQUE_NAME, VERSIONSTRING

Method Summary

boolean	addAttributeValue(String namespace, String name, String value) Generic method to add arbitrary text data to a principal's attribute.
void	commit() Commit changed principal data to the principal store.
boolean	isModified() Check if the object has been modified
boolean	removeAttributeValue(String namespace, String name, String value) Generic method to remove arbitrary text data from a principal's attribute.
void	rollback() Roll back (i.e. discard) the changes applied to a principal object up to the point when IPrincipalMaint was requested or until the latest call of commit.
void	save() Call this function to save/update the principal data.
boolean	setAttribute(String namespace, String name, String[] values) Generic method to associate arbitrary text data with a principal.
boolean	setBinaryAttribute(String namespace, String name, byte[] value) Generic method to associate arbitrary binary data with a principal.
boolean	setDisplayName(String displayName) Sets the displayName of this principal.

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

created, equals, getAttribute, getAttributeNames, getAttributeNamespaces, getAttributeType, getBinaryAttribute, getDisplayName, getMessages, getParents, getUniqueID, hashCode, isExistenceChecked, isMutable, lastModified, refresh

Method Detail

setAttribute

boolean setAttribute(String namespace,
                     String name,
                     String[] values)

Generic method to associate arbitrary text data with a principal. The method will return true if values is different from the attribute's previous values, false otherwise. Namespace and name can have up to 255 characters. Each value String can have up to 255 characters. If the given values array is null, the attribute is deleted on the persistence. NOTE: Doublets in the values array are removed. I.e. if the values array contains ["t1","t1","t2"], it will be stored as ["t1","t2"].

Parameters:

namespace - namespace of the attribute to set (max. 255 characters).

name - name of the attribute (max. 255 characters)

values - values of the attribute (each max. 255 characters)

Throws:

UMRuntimeException - if either namespace or name is not supported

addAttributeValue

boolean addAttributeValue(String namespace,
                          String name,
                          String value)

Generic method to add arbitrary text data to a principal's attribute. The method will return true if the operation changes the attribute's previous values, false otherwise. Namespace and name can have up to 255 characters. Each value String can have up to 255 characters. The given value must not be null. NOTE: Doublets will lead to an AttributeValueAlreadyExistsException during commit().

Parameters:

namespace - namespace of the attribute to set (max. 255 characters).

name - name of the attribute (max. 255 characters)

value - value to add to the attribute (each max. 255 characters)

Throws:

UMRuntimeException - if either namespace or name is not supported

removeAttributeValue

boolean removeAttributeValue(String namespace,
                             String name,
                             String value)

Generic method to remove arbitrary text data from a principal's attribute. The method will return true if the operation changes the attribute's previous values, false otherwise. Namespace and name can have up to 255 characters. Each value String can have up to 255 characters. The given value must not be null.

Parameters:

namespace - namespace of the attribute to set (max. 255 characters).

name - name of the attribute (max. 255 characters)

value - value to remove from the attribute (each max. 255 characters)

Throws:

UMRuntimeException - if either namespace or name is not supported

setBinaryAttribute

boolean setBinaryAttribute(String namespace,
                           String name,
                           byte[] value)

Generic method to associate arbitrary binary data with a principal. The method will return true if values is different from the attribute's previous values, false otherwise. If the given value is null, the attribute is deleted on the persistence. Namespace and name can have up to 255 characters.

Parameters:

namespace - namespace of the attribute to set (max. 255 characters).

name - name of the attribute (max. 255 characters)

value - byte array of values of the attribute

Throws:

UMRuntimeException - if either namespace or name is not supported

isModified

boolean isModified()

Check if the object has been modified

Returns:

true if any of the set method on this object have been called.

setDisplayName

boolean setDisplayName(String displayName)
                       throws UMException

Sets the displayName of this principal.

Throws:

UMException - if the displayName could not be set

commit

void commit()
            throws UMException

Commit changed principal data to the principal store. Calling one of commit() or rollback will be required to unlock the principal if the principal factory employs pessimistic locking. Note: This method will throw a

• PrincipalAlreadyExistsException if the principal already exists
• AttributeValueAlreadyExistsException if a duplicate value should be added for an attribute and this is not supported by the persistence which should store the attribute

Throws:

UMException - if the data can't be commited to the principal store.

rollback

void rollback()

Roll back (i.e. discard) the changes applied to a principal object up to the point when IPrincipalMaint was requested or until the latest call of commit. Calling one of commit() or rollback will be required to unlock the principal if the principal factory employs pessimistic locking.

save

void save()
          throws UMException

Call this function to save/update the principal data. However, the data will not be stored permanently until commit() is called. rollback() may be called to revert back to the old state. rollback() must be called to release the resources (like db connections) and locks (if implemented). The purpose of this method is to simulate a commit operation. Instead of committing the changes the data store checks if there are potential errors which would prevent the principal to be stored successfully. This method can be called optionally before doing a commit. Depending on the data store which is used to store principals there might be different UMExceptions which could be thrown.

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