atg.userdirectory
Interface DirectoryPrincipal

All Superinterfaces:

java.security.Principal

All Known Subinterfaces:

Organization, OrganizationalEntity, RelativeRole, Role, User

public interface DirectoryPrincipal
extends java.security.Principal

A DirectoryPrincipal is a Principal that is managed by a UserDirectory.

Notes:

In general, a DirectoryPrincipal is not serializable in a portable fashion.

Field Summary

static java.lang.String

CLASS_VERSION

Method Summary

RelativeRole	createRelativeRole(java.lang.String pFunctionName) Create an assignable relative role, which represents the fulfillment of some function relative to this principal.
java.util.Collection	getAccessRights() Get all AccessRights that are associated with this principal
java.lang.String	getDescription() Return a short textual description of this principal.
java.util.Collection	getEffectivePrincipals() Get a collection of all the effective principals in the directory with which this principal is implicitly associated.
java.util.Collection	getMembers() Get all users and organizations that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
java.util.Collection	getOrganizationMembersSortOnName(int pStartIndex, int pEndIndex, int pSortOrder) Get all organizations that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
java.lang.Object	getPrimaryKey() Get the primary key of a principal which can be used to retrieve that principals from the directory.
RelativeRole	getRelativeRole(java.lang.String pFunctionName) Given the name of a logical function, obtain the corresponding role representing that function performed relative to this principal if it exists, otherwise return null.
java.util.List	getRelativeRoles() Obtain a set of roles that may be assumed relative to this principal.
UserDirectory	getUserDirectory()
java.util.Collection	getUserMembersSortOnEmailAddress(int pStartIndex, int pEndIndex, int pSortOrder) Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
java.util.Collection	getUserMembersSortOnFirstName(int pStartIndex, int pEndIndex, int pSortOrder) Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
java.util.Collection	getUserMembersSortOnLastName(int pStartIndex, int pEndIndex, int pSortOrder) Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
java.util.Collection	getUserMembersSortOnLogin(int pStartIndex, int pEndIndex, int pSortOrder) Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals().
boolean	hasMember(java.security.Principal pMember) Determine whether a principal has a particular principal as one of its members, that is, is an effective principal associated with that entity.

Methods inherited from interface java.security.Principal

equals, getName, hashCode, toString

Field Detail

CLASS_VERSION

static final java.lang.String CLASS_VERSION

See Also:

Constant Field Values

Method Detail

getDescription

java.lang.String getDescription()

Return a short textual description of this principal.

Returns:

the description

getPrimaryKey

java.lang.Object getPrimaryKey()

Get the primary key of a principal which can be used to retrieve that principals from the directory. Primary keys can be used as stable, serializable handles to DirectoryPrincipals, which are not themselves serializable.

Returns:

the primary key of this principal

getUserDirectory

UserDirectory getUserDirectory()

Returns:

The UserDirectory associated with this principal.

getEffectivePrincipals

java.util.Collection getEffectivePrincipals()

Get a collection of all the effective principals in the directory with which this principal is implicitly associated. The effective principals are defined as the union of: this principal's ancestor organizations, all roles assigned to this principal, and all dynamical roles to which this principal belongs. No principals are duplicated in this collection.

The order of the elements as returned by the collection's iterator is significant, as it orders the effective principals from "most specific" to "least specific" in their relationship to the original principal. An access right may granted to one effective principal but denied to another effective principal; in such cases, a security model may need to determine which principal takes precedence, and the order of this collection can be used for this purpose.

As a general policy, effective principals at greater distances in the organizational graph from the original should be less specific. Also, a role should be considered to be less specific than the effective principal that has that role. A dynamic role, being implicit and rule-based, is less specific than any roles explicitly assigned to its principal. Finally, effective principals that could be considered to have multiple rankings should be assigned the most specific of those rankings.

Parameters:

A - collection of effective DirectoryPrincipals

getMembers

java.util.Collection getMembers()

Get all users and organizations that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizagtions and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pPrincipal - a principal

Returns:

a collection of the principal's member Principals, or null if the principal is not valid

See Also:

getEffectivePrincipals()

getOrganizationMembersSortOnName

java.util.Collection getOrganizationMembersSortOnName(int pStartIndex,
                                                      int pEndIndex,
                                                      int pSortOrder)

Get all organizations that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B. This method finds only those members that are organizations, sorted on the name of the organization, with index control of the return set.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizations and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pStartIndex - starting index of the sorted result set.

pEndEndex - end index of the sorted result set. a value of -1 sets the end index to infinite.

pSortOrder - sort order of the return set. valid values = { UserDirectory.ASCENDING, UserDirectory.DESCENDING }

Returns:

a collection of atg.userdirectory.Organizations which are members of this Principal, or null if the principal is not valid.

See Also:

getMembers(), getEffectivePrincipals()

getUserMembersSortOnLogin

java.util.Collection getUserMembersSortOnLogin(int pStartIndex,
                                               int pEndIndex,
                                               int pSortOrder)

Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B. This method finds only those members that are users, sorted on the login of the user, with index control of the return set.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizations and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pStartIndex - starting index of the sorted result set.

pEndEndex - end index of the sorted result set. a value of -1 sets the end index to infinite.

pSortOrder - sort order of the return set. valid values = { UserDirectory.ASCENDING, UserDirectory.DESCENDING }

Returns:

a collection of atg.userdirectory.Users which are members of this Principal, or null if the principal is not valid.

See Also:

getMembers(), getEffectivePrincipals()

getUserMembersSortOnFirstName

java.util.Collection getUserMembersSortOnFirstName(int pStartIndex,
                                                   int pEndIndex,
                                                   int pSortOrder)

Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B. This method finds only those members that are users, sorted on the firstName of the user, with index control of the return set.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizations and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pStartIndex - starting index of the sorted result set.

pEndEndex - end index of the sorted result set. a value of -1 sets the end index to infinite.

pSortOrder - sort order of the return set. valid values = { UserDirectory.ASCENDING, UserDirectory.DESCENDING }

Returns:

a collection of atg.userdirectory.Users which are members of this Principal, or null if the principal is not valid.

See Also:

getMembers(), getEffectivePrincipals()

getUserMembersSortOnLastName

java.util.Collection getUserMembersSortOnLastName(int pStartIndex,
                                                  int pEndIndex,
                                                  int pSortOrder)

Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B. This method finds only those members that are users, sorted on the lastName of the user, with index control of the return set.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizations and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pStartIndex - starting index of the sorted result set.

pEndEndex - end index of the sorted result set. a value of -1 sets the end index to infinite.

pSortOrder - sort order of the return set. valid values = { UserDirectory.ASCENDING, UserDirectory.DESCENDING }

Returns:

a collection of atg.userdirectory.Users which are members of this Principal, or null if the principal is not valid.

See Also:

getMembers(), getEffectivePrincipals()

getUserMembersSortOnEmailAddress

java.util.Collection getUserMembersSortOnEmailAddress(int pStartIndex,
                                                      int pEndIndex,
                                                      int pSortOrder)

Get all users that are "members" of this principal, viewing the effective-principal relationship from the end opposite to that taken by getEffectivePrincipals(). If A has B as one of its effective principals, then A is said to be a member of B. This method finds only those members that are users, sorted on the emailAddress of the user, with index control of the return set.

Following the definition of effective principals, it follows that:

• an organization's members include all of its descendants.
• a role's members include all organizations and users assigned that role, either explicitly or by inheritance
• a dynamic role's members include all users determined to belong to it at the time

Parameters:

pStartIndex - starting index of the sorted result set.

pEndEndex - end index of the sorted result set. a value of -1 sets the end index to infinite.

pSortOrder - sort order of the return set. valid values = { UserDirectory.ASCENDING, UserDirectory.DESCENDING }

Returns:

a collection of atg.userdirectory.Users which are members of this Principal, or null if the principal is not valid.

See Also:

getMembers(), getEffectivePrincipals()

hasMember

boolean hasMember(java.security.Principal pMember)

Determine whether a principal has a particular principal as one of its members, that is, is an effective principal associated with that entity. This operation will generally be more efficient than invoking either getEffectivePrincipals().contains() or getMembers().contains()

Parameters:

pPrincipal - a principal that might have pMember as a member

pMember - a principal representing a user or organization

Returns:

true if both principals are valid and pMember is a member of pPrincipal

getRelativeRoles

java.util.List getRelativeRoles()

Obtain a set of roles that may be assumed relative to this principal. For instance, the organization "ATG Sales" may possess relative roles such as "VP of ATG Sales", "Content Admin for ATG Sales", etc. The getRelativeRoles() method, invoked on the Organization "ATG Sales", would return those relative roles.

Note that an individual having a role relative to some organization need not actually belong to that organization.

The createRelativeRole() method can be used to create a new assignable role relative to this principal.

Returns:

a collection of RelativeRoles that are pertinent to this principal.

See Also:

createRelativeRole(java.lang.String)

getRelativeRole

RelativeRole getRelativeRole(java.lang.String pFunctionName)

Given the name of a logical function, obtain the corresponding role representing that function performed relative to this principal if it exists, otherwise return null.

Parameters:

pFunctionName - the logical name of a function relative to this principal

Returns:

the relative role which represents the fulfillment of that function relative to this principal, or null if the function is not pertinent to this principal

createRelativeRole

RelativeRole createRelativeRole(java.lang.String pFunctionName)
                                throws DirectoryModificationException

Create an assignable relative role, which represents the fulfillment of some function relative to this principal.

For instance, an relative role created for the organization "ATG Sales" and the function name "Content Admin" has the semantics of "Content Admin for ATG Sales". The resulting role can be examined with getOrganization() and getFunctionName() to find both the organization and function whose intersection it represents.

If the specified relative role already exists, it is simply returned, without any modification to the directory having taken place.

Parameters:

pFunctionName - the logical name of a function relative to this principal

Returns:

a Principal representing the relative role.

Throws:

DirectoryModificationException - occurs if the operation fails unexpectedly; a nested exception provides details.

getAccessRights

java.util.Collection getAccessRights()

Get all AccessRights that are associated with this principal

Returns:

a collection of AccessRights