com.sap.security.api

Interface IPrincipal

All Superinterfaces:

Serializable

All Known Subinterfaces:

IGroup, IPrincipalMaint, IPrincipalSet, IRole, IUser, IUserAccount, IUserMaint

public interface IPrincipal
extends Serializable

This interface provides read-access to attributes and the state of an IPrincipal object.

User Management Engine (UME) provides a unique Identifier getUniqueID() for all instances of interface IPrincipal and subinterfaces for example IUser, IGroup, IRole, etc. You can use this identifier to keep and persist references to principals. As this identifier contains internal information and is usually not readable, it should not be used in end user interfaces.

Use method getDisplayName() in order to display an attribute with a nice name for user interfaces.

NOTE: Every method of every object which implements this interface may throw a PrincipalNotAccessibleException if the instantiated object was deleted, or is not accessible because of other reasons. As this interface can be extended, this interface can be freely used, but must not be implemented.

Field Summary

static String	BYTE_TYPE Constant used for attribute byte type
static String	CREATED_BY Constant used for attribute created by
static String	DATASOURCE Constant used for datasource attribute
static String	DEFAULT_NAMESPACE Constant used for default namespace
static String	DEFAULT_RELATION_NAMESPACE Constant used for default relation namespace
static String	DESCRIPTION Constant used for description attribute
static String	DISPLAYNAME Constant used for displayname attribute
static String	LAST_MODIFIED_BY Constant used for attribute last modified by
static String	PRINCIPAL_CREATION_DATE Constant used for attribute creation date
static String	PRINCIPAL_MODIFY_DATE Constant used for attribute modification date
static String	PRINCIPAL_RELATION_MEMBER_ATTRIBUTE Constant used for member attribute
static String	PRINCIPAL_RELATION_PARENT_ATTRIBUTE Constant used for parent member attribute
static String	STRING_TYPE Constant used for attribute string type
static String	TRANSIENT_NAMESPACE Constant used for transient data namespace
static String	UNIQUE_NAME Constant used for uniquename attribute
static String	VERSIONSTRING

Method Summary

Date	created() Gets the date when the object's data record was created in the data store.
boolean	equals(Object another) To compare the two instances of the implementation.
String[]	getAttribute(String namespace, String name) Generic get method to access additional attributes.
String[]	getAttributeNames(String namespace) Gets the names of all attributes contained in the given namespace, or null if that namespace does not exist.
String[]	getAttributeNamespaces() Gets all non-null namespaces defined for this user.
String	getAttributeType(String namespace, String attributeName) Gets the type of the attribute.
byte[]	getBinaryAttribute(String namespace, String name) Generic get method to access additional binary attributes.
String	getDisplayName() Gets the principal's display name.
Iterator	getMessages(boolean clearPermanentMessages) Returns an iterator which contains the IMessage objects assigned to this IPrincipal or null if no messages are assigned.
Iterator	getParents(String[] principalTypeIdentifiers, boolean recursive) Gets the list of all parent principals including parents, grandparents, ...
String	getUniqueID() Gets the unique identifier which unambiguously identifies the object's principal type and principal's data record(s) in the data store (e.g. a relational database).
int	hashCode() Returns a hash code value for the object.
boolean	isExistenceChecked() Checks if this user's existence on the persistence storage was checked
boolean	isMutable() Check if the object can be modified
Date	lastModified() Gets the date when the object's data record was last modified in the data store.
void	refresh() Refresh Object Reads all attributes of this object again from data store Note: The cached principal object is updated with this method.

Field Detail

VERSIONSTRING

static final String VERSIONSTRING

See Also:

Constant Field Values

DEFAULT_NAMESPACE

static final String DEFAULT_NAMESPACE

Constant used for default namespace

See Also:

Constant Field Values

DEFAULT_RELATION_NAMESPACE

static final String DEFAULT_RELATION_NAMESPACE

Constant used for default relation namespace

See Also:

Constant Field Values

TRANSIENT_NAMESPACE

static final String TRANSIENT_NAMESPACE

Constant used for transient data namespace

See Also:

Constant Field Values

PRINCIPAL_CREATION_DATE

static final String PRINCIPAL_CREATION_DATE

Constant used for attribute creation date

See Also:

Constant Field Values

CREATED_BY

static final String CREATED_BY

Constant used for attribute created by

See Also:

Constant Field Values

PRINCIPAL_MODIFY_DATE

static final String PRINCIPAL_MODIFY_DATE

Constant used for attribute modification date

See Also:

Constant Field Values

LAST_MODIFIED_BY

static final String LAST_MODIFIED_BY

Constant used for attribute last modified by

See Also:

Constant Field Values

PRINCIPAL_RELATION_MEMBER_ATTRIBUTE

static final String PRINCIPAL_RELATION_MEMBER_ATTRIBUTE

Constant used for member attribute

See Also:

Constant Field Values

PRINCIPAL_RELATION_PARENT_ATTRIBUTE

static final String PRINCIPAL_RELATION_PARENT_ATTRIBUTE

Constant used for parent member attribute

See Also:

Constant Field Values

DISPLAYNAME

static final String DISPLAYNAME

Constant used for displayname attribute

See Also:

Constant Field Values

DESCRIPTION

static final String DESCRIPTION

Constant used for description attribute

See Also:

Constant Field Values

UNIQUE_NAME

static final String UNIQUE_NAME

Constant used for uniquename attribute

See Also:

Constant Field Values

STRING_TYPE

static final String STRING_TYPE

Constant used for attribute string type

See Also:

Constant Field Values

BYTE_TYPE

static final String BYTE_TYPE

Constant used for attribute byte type

See Also:

Constant Field Values

DATASOURCE

static final String DATASOURCE

Constant used for datasource attribute

See Also:

Constant Field Values

Method Detail

getUniqueID

String getUniqueID()

Gets the unique identifier which unambiguously identifies the object's principal type and principal's data record(s) in the data store (e.g. a relational database).

Note: the unique ID is a case sensitive string

Use this identifier to keep and persist references to principals. As this identifier contains internal information and is usually not readable, it should not be displayed in user interfaces.

UME implementation guarantees to return Strings which are not longer than 255 characters.

Returns:

a non-null String identifying this principal

created

Date created()

Gets the date when the object's data record was created in the data store.

Returns:

a Date object or null if creation date is not available

lastModified

Date lastModified()

Gets the date when the object's data record was last modified in the data store.

Returns:

a Date object or null if last modification date is not available

getAttribute

String[] getAttribute(String namespace,
                      String name)

Generic get method to access additional attributes. These attributes are contained in separate namespaces, and are accessible via their names. Attributes that are in no distinct namespace are located in the namespace null. Each attribute can have multiple String values.

Parameters:

namespace - namespace the attribute is in (may be null)

name - name of the attribute

Returns:

the values of the respective attribute, or null if this namespace or attribute within this namespace does not exist

getBinaryAttribute

byte[] getBinaryAttribute(String namespace,
                          String name)

Generic get method to access additional binary attributes. These attributes are contained in separate namespaces, and are accessible via their names. Attributes that are in no distinct namespace are located in the namespace null.

Parameters:

namespace - namespace the attribute is in (may be null)

name - name of the attribute

Returns:

the values of the respective attribute, or null if this namespace or attribute within this namespace does not exist

getAttributeNamespaces

String[] getAttributeNamespaces()

Gets all non-null namespaces defined for this user. Implementations must guarantee that even if the namespace null exists, it is not returned as an element in the array. Applications which need to access the namespace null must check for its existence and the contained attributes explicitly via getAttributeNames(null).

Returns:

all non-null namespaces defined for this user

getAttributeNames

String[] getAttributeNames(String namespace)

Gets the names of all attributes contained in the given namespace, or null if that namespace does not exist. If namespace exists but contains no attributes, an empty array will be returned. To retrieve the names of all attributes that are in no distinct namespace, call this method with the parameter null

Parameters:

namespace - namespace or null

Returns:

attribute names in namespace or null

getDisplayName

String getDisplayName()

Gets the principal's display name. Depending on the implementation, this might be an alternative (alias) name, which is not required to be unique and different from the user's unique ID. displayName would be the preferred key to be used in the UI, as it is more human readable and not language dependent.

Returns:

a String representing the displayName

isExistenceChecked

boolean isExistenceChecked()

Checks if this user's existence on the persistence storage was checked

Returns:

true if the existence of this principal is already checked. false if the existence of this principal is not checked yet.

refresh

void refresh()
             throws UMException

Refresh Object Reads all attributes of this object again from data store

Note: The cached principal object is updated with this method. Calling this method has impact on performance and on load of the system because the principal object is read again from the data store.

Throws:

exception - if object could not be refreshed

UMException

isMutable

boolean isMutable()

Check if the object can be modified

Returns:

true if the principal object is mutable

equals

boolean equals(Object another)

To compare the two instances of the implementation.

Overrides:

equals in class Object

Returns:

true if both instances are of the same object type and have the same uniqueId

hashCode

int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

Overrides:

hashCode in class Object

getAttributeType

String getAttributeType(String namespace,
                        String attributeName)

Gets the type of the attribute. Returns STRING_TYPE if the attribute is of type String, or BYTE_TYPE if it is a binary attribute. Returns null if the attribute is not available.

Returns:

the type of the attribute

getParents

Iterator getParents(String[] principalTypeIdentifiers,
                    boolean recursive)

Gets the list of all parent principals including parents, grandparents, ... which have the specified principal types (e.g. USER,GRUP,ROLE etc.) NOTE: using this method can cause performance problems if used recursively, because the number of search requests depends on the principal hierarchy. In the worst case there will be principalTypeIdentifiers.length X depth of the hierarchy Level 1 | Level 2 | Level3 example: USER u1 |-ROLE r1 |-GRUP g1 |-GRUP g3 |-GRUP g4 |-GRUP g5 |-GRUP g6 |-ROLE r2 |-ROLE r3 |-GRUP g2 |-GRUP g3 getParents(new String[] {"USER","GRUP","ROLE"}, true); will lead to 3 X 2 search requests!

Returns:

iterator of uniqueIds of all parent principals of this principal

getMessages

Iterator getMessages(boolean clearPermanentMessages)

Returns an iterator which contains the IMessage objects assigned to this IPrincipal or null if no messages are assigned. If the method is called with parameter true, every subsequent call will return null if no new message was assigned to this IPrincipal.

Parameters:

clearPermanentMessages - Specifies whether permanent messages with life time IMessage.LIFETIME_PERMANENT should be removed from the message buffer.

Returns:

The messages assigned to this IPrincipal object or null.

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