com.sap.security.api
Interface IPrincipal

All Superinterfaces:

java.io.Serializable

All Known Subinterfaces:

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

public interface IPrincipal

extends java.io.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.

Version:

1.0

Field Summary

static java.lang.String	BYTE_TYPE Constant used for attribute byte type
static java.lang.String	DEFAULT_NAMESPACE Constant used for default namespace
static java.lang.String	DEFAULT_RELATION_NAMESPACE Constant used for default relation namespace
static java.lang.String	DESCRIPTION Constant used for description attribute
static java.lang.String	DISPLAYNAME Constant used for displayname attribute
static java.lang.String	PRINCIPAL_CREATION_DATE Constant used for attribute creation date
static java.lang.String	PRINCIPAL_MODIFY_DATE Constant used for attribute modification date
static java.lang.String	PRINCIPAL_RELATION_MEMBER_ATTRIBUTE Constant used for member attribute
static java.lang.String	PRINCIPAL_RELATION_PARENT_ATTRIBUTE Constant used for parent member attribute
static java.lang.String	STRING_TYPE Constant used for attribute string type
static java.lang.String	TRANSIENT_NAMESPACE Constant used for transient data namespace
static java.lang.String	UNIQUE_NAME Constant used for uniquename attribute
static java.lang.String	VERSIONSTRING

Method Summary

java.util.Date	created() Gets the date when the object's data record was created in the data store.
boolean	equals(java.lang.Object another) To compare the two instances of the implementation.
java.lang.String[]	getAttribute(java.lang.String namespace, java.lang.String name) Generic get method to access additional attributes.
java.lang.String[]	getAttributeNames(java.lang.String namespace) Gets the names of all attributes contained in the given namespace, or null if that namespace does not exist.
java.lang.String[]	getAttributeNamespaces() Gets all non-null namespaces defined for this user.
java.lang.String	getAttributeType(java.lang.String namespace, java.lang.String attributeName) Gets the type of the attribute.
byte[]	getBinaryAttribute(java.lang.String namespace, java.lang.String name) Generic get method to access additional binary attributes.
java.lang.String	getDisplayName() Gets the principal's display name.
java.util.Iterator	getParents(java.lang.String[] principalTypeIdentifiers, boolean recursive) Gets the list of all parent principals including parents, grandparents, ...
java.lang.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.
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
java.util.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

Field Detail

VERSIONSTRING

public static final java.lang.String VERSIONSTRING

DEFAULT_NAMESPACE

public static final java.lang.String DEFAULT_NAMESPACE

Constant used for default namespace

DEFAULT_RELATION_NAMESPACE

public static final java.lang.String DEFAULT_RELATION_NAMESPACE

Constant used for default relation namespace

TRANSIENT_NAMESPACE

public static final java.lang.String TRANSIENT_NAMESPACE

Constant used for transient data namespace

PRINCIPAL_CREATION_DATE

public static final java.lang.String PRINCIPAL_CREATION_DATE

Constant used for attribute creation date

PRINCIPAL_MODIFY_DATE

public static final java.lang.String PRINCIPAL_MODIFY_DATE

Constant used for attribute modification date

PRINCIPAL_RELATION_MEMBER_ATTRIBUTE

public static final java.lang.String PRINCIPAL_RELATION_MEMBER_ATTRIBUTE

Constant used for member attribute

PRINCIPAL_RELATION_PARENT_ATTRIBUTE

public static final java.lang.String PRINCIPAL_RELATION_PARENT_ATTRIBUTE

Constant used for parent member attribute

DISPLAYNAME

public static final java.lang.String DISPLAYNAME

Constant used for displayname attribute

DESCRIPTION

public static final java.lang.String DESCRIPTION

Constant used for description attribute

UNIQUE_NAME

public static final java.lang.String UNIQUE_NAME

Constant used for uniquename attribute

STRING_TYPE

public static final java.lang.String STRING_TYPE

Constant used for attribute string type

BYTE_TYPE

public static final java.lang.String BYTE_TYPE

Constant used for attribute byte type

Method Detail

getUniqueID

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

public java.util.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

public java.util.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

public java.lang.String[] getAttribute(java.lang.String namespace,
                                       java.lang.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

public byte[] getBinaryAttribute(java.lang.String namespace,
                                 java.lang.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

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

public java.lang.String[] getAttributeNames(java.lang.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

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

public 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

public 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

isMutable

public boolean isMutable()

Check if the object can be modified

Returns:

true if the principal object is mutable

equals

public boolean equals(java.lang.Object another)

To compare the two instances of the implementation.

Overrides:

equals in class java.lang.Object

Returns:

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

hashCode

public 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 java.lang.Object

getAttributeType

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

public java.util.Iterator getParents(java.lang.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.) ATTENTION: 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 getParentGroups(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