atg.security
Class AccessControlList

java.lang.Object
  atg.security.AccessControlList

All Implemented Interfaces:

StandardAccessRights, java.io.Serializable, java.lang.Cloneable, java.security.acl.Acl, java.security.acl.Owner

public class AccessControlList
extends java.lang.Object
implements StandardAccessRights, java.security.acl.Acl, java.io.Serializable, java.lang.Cloneable

A set of access rights that determine the accessibility of something to someone.

java.security.acl.Acl compatibility notes:

• ACL ownership is not supported.
• ACL naming is supported but names are not persisted.
• Adding and removing AclEntries is supported only if they are instances of AccessControlEntry.
• getPermissions() returns a match only if the supplied Principal is an instance of Persona.
• checkPermission() does not honor the java.security.acl policy of ignoring Permissions that have both a positive and negative entry for the Principal. A negative entry will deny access regardless of the presence of an allow entry.
• setName() will fail if the ACL is marked read-only.

See Also:

AccessControlEntry, AccessRight, Serialized Form

Field Summary

static java.lang.String	CLASS_VERSION
static AccessControlList	EMPTY An empty access control list, useful as a default or error value for routines that need to return such a thing.
static AccessControlEntry[]	EMPTY_ACL Deprecated.

Fields inherited from interface atg.security.StandardAccessRights

CREATE, DELETE, DESTROY, EXECUTE, LIST, MAP, PRIVILEGE, READ, READ_ACL, READ_OWNER, RENAME, TRAVERSE, WRITE, WRITE_ACL, WRITE_OWNER

Constructor Summary

AccessControlList()
Creates an empty access control list.

AccessControlList(AccessControlEntry[] pAcl)
Creates an access control list for a series of access control entries.

AccessControlList(AccessControlList pAcl)
Creates a copy of an access control list.

AccessControlList(AccessControlList[] pAcls)
Creates a new access control list that is the concatenation of a set of other access control lists.

AccessControlList(AccessControlList pAcl1, AccessControlList pAcl2)
Creates a new access control list that merges two access control lists.

Method Summary

void	add(AccessControlEntry pAce) Adds a given ACE from the ACL.
static AccessControlEntry[]	add(AccessControlEntry[] pAcl, AccessControlEntry pEntry) Adds a new access control entry to an access control list, returning the concatenated list.
void	add(Persona pPersona, AccessRight pRight, int pType) Adds an access right if it does not already exist.
boolean	addEntry(java.security.Principal pCaller, java.security.acl.AclEntry pEntry)
boolean	addOwner(java.security.Principal pCaller, java.security.Principal pNewOwner)
void	append(AccessControlList pAcl) Appends the access control information from another access control list onto this one.
void	canonicalize() Transforms the ACL into a set of ACEs where each ACE has only one access right.
boolean	checkPermission(java.security.Principal pPrincipal, java.security.acl.Permission pPermission)
java.lang.Object	clone() Creates a copy of this object.
boolean	deleteOwner(java.security.Principal pCaller, java.security.Principal pOldOwner)
java.util.Enumeration	entries()
AccessControlEntry[]	getAccessControlEntries() Returns the raw access control entries in the list.
AccessControlEntry[]	getEntriesForPersona(Persona pPersona) Returns the access control entries that apply to a particular user.
int	getLength() Returns the number of access control entries in the list.
java.lang.String	getName()
java.util.Enumeration	getPermissions(java.security.Principal pPrincipal)
Persona[]	getPersonae() Returns a list of personae that are referred to by the ACL.
static boolean	hasAccessRight(User pUser, AccessRight pDesiredRight, AccessControlEntry[] pAcl) Determines whether or not a user has a particular right within an access control list.
boolean	isOwner(java.security.Principal pPrincipal)
boolean	isReadOnly() Returns true if this ACL has been marked as read-only.
void	optimize() Optimizes the ACL.
static AccessControlList	parse(java.lang.String pAclString, SecurityConfiguration pConfig) Converts a string describing an ACL into an actual ACL, validating personae, ACE types, and access rights.
static AccessControlList	parse(java.lang.String pAclString, SecurityConfiguration pConfig, boolean pBestEffort) An ACL parsing variant that will ignore inconsistencies if pBestEffort is true.
static AccessControlEntry[]	parse(java.lang.String pAclString, UserAuthority pAuthority) Deprecated.
void	remove(AccessControlEntry pAce) Removes a given ACE from the ACL.
static AccessControlEntry[]	remove(AccessControlEntry[] pAcl, AccessControlEntry pEntry) Removes an access control entry from an access control list, returning the resulting list.
void	remove(Persona pPersona, AccessRight pRight, int pType) Removes an access right if it exists.
boolean	removeEntry(java.security.Principal pCaller, java.security.acl.AclEntry pEntry)
void	setName(java.security.Principal pCaller, java.lang.String pName)
void	setReadOnly(boolean b) If set to true, this ACL becomes immutable.
java.lang.String	toString() Returns a string representation of an ACL.
static java.lang.String	toString(AccessControlEntry[] pAcl) Converts an access control list into a string.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

EMPTY_ACL

public static final AccessControlEntry[] EMPTY_ACL

Deprecated.

An empty set of access control entries, useful as a default or error value for routines that need to return such a thing. This field has been deprecated in favor of AccessControlEntry.EMPTY_ACES and AccessControlList.EMPTY.

See Also:

EMPTY, AccessControlEntry#EMPTY_ACES

EMPTY

public static final AccessControlList EMPTY

An empty access control list, useful as a default or error value for routines that need to return such a thing.

Constructor Detail

AccessControlList

public AccessControlList()

Creates an empty access control list.

AccessControlList

public AccessControlList(AccessControlEntry[] pAcl)

Creates an access control list for a series of access control entries.

AccessControlList

public AccessControlList(AccessControlList pAcl)

Creates a copy of an access control list.

AccessControlList

public AccessControlList(AccessControlList pAcl1,
                         AccessControlList pAcl2)

Creates a new access control list that merges two access control lists. This does not optimize the resulting ACL. Either ACL argument can be null, in which case this simply clones the remaining ACL, but both are not allowed to be since the semantics of a null ACL are different from those of an empty ACL.

AccessControlList

public AccessControlList(AccessControlList[] pAcls)

Creates a new access control list that is the concatenation of a set of other access control lists. This does not optimize the resulting ACL.

Method Detail

add

public void add(AccessControlEntry pAce)

Adds a given ACE from the ACL. Note that this does not do a merge, but rather a literal add. If any or all ACE components already exist in the list, they will be duplicated.

Throws:

java.lang.IllegalStateException - if this ACL has been marked read-only.

See Also:

add(Persona, AccessRight, int), setReadOnly

remove

public void remove(AccessControlEntry pAce)

Removes a given ACE from the ACL. Note that this does not remove a subset of rights; it will only remove an ACE that is a perfect match.

Throws:

java.lang.IllegalStateException - if this ACL has been marked read-only.

See Also:

remove(Persona, AccessRight, int), setReadOnly

add

public void add(Persona pPersona,
                AccessRight pRight,
                int pType)

Adds an access right if it does not already exist.

Throws:

java.lang.IllegalStateException - if this ACL has been marked read-only.

See Also:

setReadOnly

append

public void append(AccessControlList pAcl)

Appends the access control information from another access control list onto this one.

remove

public void remove(Persona pPersona,
                   AccessRight pRight,
                   int pType)

Removes an access right if it exists. If the access right exists multiple times, this will remove all of them.

Throws:

java.lang.IllegalStateException - if this ACL has been marked read-only.

See Also:

setReadOnly

canonicalize

public void canonicalize()

Transforms the ACL into a set of ACEs where each ACE has only one access right.

optimize

public void optimize()

Optimizes the ACL. This performs ACE merging and may re-order the ACL.

Throws:

java.lang.IllegalStateException - if this ACL has been marked read-only.

See Also:

setReadOnly

getAccessControlEntries

public AccessControlEntry[] getAccessControlEntries()

Returns the raw access control entries in the list. If this ACL is marked read-only, a copy will be returned.

getLength

public int getLength()

Returns the number of access control entries in the list.

getPersonae

public Persona[] getPersonae()

Returns a list of personae that are referred to by the ACL.

getEntriesForPersona

public AccessControlEntry[] getEntriesForPersona(Persona pPersona)

Returns the access control entries that apply to a particular user.

isReadOnly

public boolean isReadOnly()

Returns true if this ACL has been marked as read-only.

setReadOnly

public void setReadOnly(boolean b)

If set to true, this ACL becomes immutable.

clone

public java.lang.Object clone()

Creates a copy of this object.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

Returns a string representation of an ACL.

Specified by:

toString in interface java.security.acl.Acl

Overrides:

toString in class java.lang.Object

hasAccessRight

public static boolean hasAccessRight(User pUser,
                                     AccessRight pDesiredRight,
                                     AccessControlEntry[] pAcl)

Determines whether or not a user has a particular right within an access control list.

add

public static AccessControlEntry[] add(AccessControlEntry[] pAcl,
                                       AccessControlEntry pEntry)

Adds a new access control entry to an access control list, returning the concatenated list. Note that this DOES NOT create clean references.

remove

public static AccessControlEntry[] remove(AccessControlEntry[] pAcl,
                                          AccessControlEntry pEntry)

Removes an access control entry from an access control list, returning the resulting list. Note that this DOES NOT create clean references.

parse

public static AccessControlEntry[] parse(java.lang.String pAclString,
                                         UserAuthority pAuthority)

Deprecated.

Converts a string describing an ACL into an actual ACL. This method has been deprecated in favor of parse(String, SecurityConfig) which performs validation. This implementation will utilize the standard access rights if possible, or manufacture new instances of GenericAccessRight if necessary.

The properties entry list is expected to be in the form:

   acl ::= ace ( ';' ace )+
   ace ::= ( ace-type '{' persona-and-rights '}' ) | persona-and-rights
   ace-type ::= "grant" | "deny" | "inheritable" | "effective"
   persona-and-rights ::= persona ':' right ( ',' right )+
 

where persona is determined by the user authority in the security configuration, and right is selected from StandardAccessRights.MAP or manufactured out of GenericAccessRight.

See Also:

StandardAccessControlRights#MAP

parse

public static AccessControlList parse(java.lang.String pAclString,
                                      SecurityConfiguration pConfig)
                               throws InvalidPersonaException,
                                      InvalidAccessRightException,
                                      atg.security.InvalidAccessControlListException

Converts a string describing an ACL into an actual ACL, validating personae, ACE types, and access rights.

The properties entry list is expected to be in the form:

   acl ::= ace ( ';' ace )+
   ace ::= ( ace-type '{' persona-and-rights '}' ) | persona-and-rights
   ace-type ::= "grant" | "deny" | "inheritable" | "effective"
   persona-and-rights ::= persona ':' right ( ',' right )+
 

where persona is determined by the user authority passed in the security configuration, and right is determined by the access rights map passed in the security configuration.

The returned ACL will be marked read-only.

Throws:

InvalidPersonaException - if a persona in the ACL does not valid.

InvalidAccessRightException - if an access right in the ACL is not valid.

InvalidAccessControlListException - if there is a syntactic error in the ACL.

parse

public static AccessControlList parse(java.lang.String pAclString,
                                      SecurityConfiguration pConfig,
                                      boolean pBestEffort)
                               throws InvalidPersonaException,
                                      InvalidAccessRightException,
                                      atg.security.InvalidAccessControlListException

An ACL parsing variant that will ignore inconsistencies if pBestEffort is true. This is typically used from within a security domain to parse ACLs stored as strings.

The returned ACL will be marked read-only.

Throws:

InvalidPersonaException

InvalidAccessRightException

atg.security.InvalidAccessControlListException

toString

public static java.lang.String toString(AccessControlEntry[] pAcl)

Converts an access control list into a string.

addEntry

public boolean addEntry(java.security.Principal pCaller,
                        java.security.acl.AclEntry pEntry)

Specified by:

addEntry in interface java.security.acl.Acl

checkPermission

public boolean checkPermission(java.security.Principal pPrincipal,
                               java.security.acl.Permission pPermission)

Specified by:

checkPermission in interface java.security.acl.Acl

entries

public java.util.Enumeration entries()

Specified by:

entries in interface java.security.acl.Acl

getName

public java.lang.String getName()

Specified by:

getName in interface java.security.acl.Acl

getPermissions

public java.util.Enumeration getPermissions(java.security.Principal pPrincipal)

Specified by:

getPermissions in interface java.security.acl.Acl

removeEntry

public boolean removeEntry(java.security.Principal pCaller,
                           java.security.acl.AclEntry pEntry)

Specified by:

removeEntry in interface java.security.acl.Acl

setName

public void setName(java.security.Principal pCaller,
                    java.lang.String pName)

Specified by:

setName in interface java.security.acl.Acl

addOwner

public boolean addOwner(java.security.Principal pCaller,
                        java.security.Principal pNewOwner)

Specified by:

addOwner in interface java.security.acl.Owner

deleteOwner

public boolean deleteOwner(java.security.Principal pCaller,
                           java.security.Principal pOldOwner)

Specified by:

deleteOwner in interface java.security.acl.Owner

isOwner

public boolean isOwner(java.security.Principal pPrincipal)

Specified by:

isOwner in interface java.security.acl.Owner