com.tivoli.pd.rgy
Interface RgyEntity

All Known Subinterfaces:

RgyGroup, RgyUser

public interface RgyEntity

This Interface provides the common methods for the RgyUser and RgyGroup Interfaces.

Security Access Manager entities are extensions (layered on top) of the underlying registry's User and Group entities. This interface provides access to both layers attributes and IDs. The underlying registry's entity is referred to as the Native entity by this API. When the Security Access Manager extensions are added to the Native entity, the entity is then known as the SAM entity by this API. This Interface can be used for the Native entity or a complete SAM entity.

To detect if the Interface represents a complete SAM entity, a virtual attribute (one that does not exist in the registry) is provided by the implementation of this interface to allow determination. See RgyAttributes.IS_SEC_ENTITY_NAME.

For User entities, almost all the Native entity attributes will be provided (for example, if there is a telephoneNumber attribute associated with the LDAP registry entry (say cn=testuser,o=ibm,c=us), it will be available). For security and integrity purposes, if there is an attribute at the Registry level that has the same name as any available at the SAM level, it will not be returned.

Also for User entities any per-user policy attributes that exists will be returned. This will not include any global policy attributes, though global policy attributes will still have an effect on the user if the corresponding per-user policy attribute does not exist.

Binary attributes are returned as byte[], non-binary as String.

For User entities, "userPassword" is not returned, and can not be updated as an Attribute. There are specific methods in the RgyUser interface for updating "userPassword".

Multiple threads should not access the same instance of this interface at the same time.

Method Summary

void	attributeAdd(java.lang.String name, java.lang.Object value) Adds an additional value to attribute.
void	attributeAdd(java.lang.String name, java.lang.Object[] values) Adds an additional values to attribute.
void	attributeDelete(java.lang.String name) Deletes an entity's attribute from the registry.
void	attributeDelete(java.lang.String name, java.lang.Object value) Deletes a specific attribute/value pair.
void	attributeDelete(java.lang.String name, java.lang.Object[] values) Deletes the specific attribute values.
java.util.Iterator<java.lang.String>	attributeNameIterator()
void	attributeReplace(java.lang.String name, java.lang.Object value) Replaces all the values for the specific attribute with the one provided.
void	attributeReplace(java.lang.String name, java.lang.Object[] values) Replaces all the values for the specific attribute with the ones provided.
java.lang.Object[]	getAttributeValues(java.lang.String name) Returns all of the attribute's values.
java.lang.String	getDomain() Returns the SAM domain this RgyEntity was fetched from.
java.lang.String	getId() Returns the Security Access Manager ID for the entity, for example, "sec_master".
java.lang.String	getNativeId() Returns the registry Native ID for the Entity.
java.lang.Object	getOneAttributeValue(java.lang.String name) Returns one of the attribute's values.
RgyRegistry	getRgyRegistry() Return the RgyRegistry instance that generated this RgyEntity.

Method Detail

getId

java.lang.String getId()

Returns the Security Access Manager ID for the entity, for example, "sec_master".

Returns:

Security Access Manager entity ID. Returns null if the entity is not a Security Access Manager entity.

getNativeId

java.lang.String getNativeId()

Returns the registry Native ID for the Entity. For example: "cn=testgroup,o=ibm,c=us'

Returns:

Registry Native ID

getRgyRegistry

RgyRegistry getRgyRegistry()

Return the RgyRegistry instance that generated this RgyEntity.

Returns:

RgyRegistry that generated this RgyEntity.

getDomain

java.lang.String getDomain()

Returns the SAM domain this RgyEntity was fetched from.

Returns:

The SAM domain for this RgyEntity.

attributeNameIterator

java.util.Iterator<java.lang.String> attributeNameIterator()

Returns:

Iterator that iterates over all the attribute names for the entity.

getOneAttributeValue

java.lang.Object getOneAttributeValue(java.lang.String name)
                                      throws RgyException

Returns one of the attribute's values. There is no guarantee which one if there is more than one available.

Parameters:

name - The name of the attribute to fetch the value from.

Returns:

String or byte[] depending on the type of attribute. LDAP binary attributes are returned as byte[]. Returns null if the attribute does not exist or the invoker does not have permission to view the attribute.

Throws:

RgyException

getAttributeValues

java.lang.Object[] getAttributeValues(java.lang.String name)
                                      throws RgyException

Returns all of the attribute's values.

Parameters:

name - The name of the attribute.

Returns:

An array of String or byte[] depending on the attribute type. Returns null if the attribute does not exist, or the invoker does not have permission to view the attribute.

Throws:

RgyException

attributeDelete

void attributeDelete(java.lang.String name)
                     throws RgyException

Deletes an entity's attribute from the registry. This may fail on attributes that are required to exist or are virtual, such as cn, isGSOuser, sn, secUUID, etc. This may fail for attributes this API has specific methods for such as userPassword, or member.

Parameters:

name - The name of the attribute to delete.

Throws:

RgyException

attributeDelete

void attributeDelete(java.lang.String name,
                     java.lang.Object value)
                     throws RgyException

Deletes a specific attribute/value pair. This may fail on attributes that are required to exist (and only have the one value) or are virtual, such as cn, isGSOuser, sn, secUUID, etc. This will fail for attributes this API has specific methods for such as userPassword, or member.

The underlying JNDI/LDAP registry values may be case-insensitive allowing a different case for the value than is stored in the RgyEntry cache of attributes. To ensure consistency between the cache of attribute values in the RgyEntity and the JNDI/LDAP registry, it is recommended that you pass in values returned from getOneAttributeValue or getAttributeValues to this method to ensure the case matches, thus the cached attribute value is also removed.

Parameters:

name - The name of the attribute who's value is to be removed.

value - The specific value of the attribute to remove.

Throws:

RgyException

NoSuchAttributeRgyException - If the attribute/value pair does not exist.

ObjectClassViolationRgyException - if the Registry does not allow modification of the attribute, or the attribute is a required attribute that must exist in the Entity.

attributeDelete

void attributeDelete(java.lang.String name,
                     java.lang.Object[] values)
                     throws RgyException

Deletes the specific attribute values. This may fail on attributes that are required to exist (and all values are removed) or are virtual, such as cn, isGSOuser, sn, secUUID, etc. This will fail for attributes this API has specific methods for such as userPassword, or member.

The underlying JNDI/LDAP registry values may be case-insensitive allowing a different case for the value than is stored in the RgyEntry cache of attributes. To ensure consistency between the cache of attribute values in the RgyEntity and the JNDI/LDAP registry, it is recommended that you pass in values returned from getOneAttributeValue or getAttributeValues to this method to ensure the case matches, thus the cached attribute value is also removed.

Parameters:

name - The name of the attribute who's value is to be removed.

values - The specific values of the attribute to remove.

Throws:

RgyException

NoSuchAttributeRgyException - If the attribute/value pair does not exist.

ObjectClassViolationRgyException - if the Registry does not allow modification of the attribute, or the attribute is a required attribute that must exist in the Entity.

attributeReplace

void attributeReplace(java.lang.String name,
                      java.lang.Object value)
                      throws RgyException

Replaces all the values for the specific attribute with the one provided. If the attribute did not exist, it will be created. This may fail on attributes that are restricted or virtual, such as isGSOuser, secUUID, etc. This may fail for attributes this API has specific methods for such as userPassword, or member.

Parameters:

name - The name of the entity attribute to replace.

value - The new value of the attribute.

Throws:

RgyException

ObjectClassViolationRgyException - For attributes that this API does not allow modification to.

attributeReplace

void attributeReplace(java.lang.String name,
                      java.lang.Object[] values)
                      throws RgyException

Replaces all the values for the specific attribute with the ones provided. If the attribute did not exist, it will be created. This may fail on attributes that are restricted or virtual, such as isGSOuser, secUUID, etc. This may fail for attributes this API has specific methods for such as userPassword, or member. This may fail for attributes that only permit a single value and multiple are provided.

Parameters:

name - The name of the entity attribute to replace.

values - The new value of the attribute.

Throws:

RgyException

ObjectClassViolationRgyException - For attributes that this API does not allow modification to.

attributeAdd

void attributeAdd(java.lang.String name,
                  java.lang.Object value)
                  throws RgyException

Adds an additional value to attribute. This may fail for attributes that are not multi-value and the attribute already has a value. This may fail on attributes that are restricted, or are virtual, such as isGSOuser, secUUID. This may fail for attributes this API has specific methods for such as userPassword or member. Add the attribute/value pair.

Parameters:

name - The name of the attribute to add the value to.

value - The value to add to the attribute.

Throws:

RgyException

ObjectClassViolationRgyException - For attributes that this API does not allow modification to.

attributeAdd

void attributeAdd(java.lang.String name,
                  java.lang.Object[] values)
                  throws RgyException

Adds an additional values to attribute. This may fail for attributes that are not multi-value. This may fail on attributes that are restricted, or are virtual, such as isGSOuser, secUUID. This may fail for attributes this API has specific methods for such as userPassword or member. Add the attribute/value pair.

Parameters:

name - The name of the attribute to add the value to.

values - The values to add to the attribute. Must be all the same class.

Throws:

RgyException

ObjectClassViolationRgyException - For attributes that this API does not allow modification to.