AccessControlList (ATG Java API)

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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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

Class AccessControlList

Field Summary

Fields inherited from interface atg.security.StandardAccessRights

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLASS_VERSION

EMPTY_ACL

EMPTY

Constructor Detail

AccessControlList

AccessControlList

AccessControlList

AccessControlList

AccessControlList

Method Detail

add

remove

add

append

remove

canonicalize

optimize

getAccessControlEntries

getLength

getPersonae

getEntriesForPersona

isReadOnly

setReadOnly

clone

toString

hasAccessRight

add

remove

parse

parse

parse

toString

addEntry

checkPermission

entries

getName

getPermissions

removeEntry

setName

addOwner

deleteOwner

isOwner