Spring Security Framework

org.springframework.security.acls.domain
Class AclImpl

java.lang.Object
  extended by org.springframework.security.acls.domain.AclImpl
All Implemented Interfaces:
Serializable, Acl, AuditableAcl, MutableAcl, OwnershipAcl

public class AclImpl
extends Object
implements Acl, MutableAcl, AuditableAcl, OwnershipAcl

Base implementation of Acl.

Version:
$Id
Author:
Ben Alex
See Also:
Serialized Form

Constructor Summary
AclImpl(ObjectIdentity objectIdentity, Serializable id, AclAuthorizationStrategy aclAuthorizationStrategy, AuditLogger auditLogger)
          Minimal constructor, which should be used MutableAclService.createAcl(ObjectIdentity).
AclImpl(ObjectIdentity objectIdentity, Serializable id, AclAuthorizationStrategy aclAuthorizationStrategy, AuditLogger auditLogger, Acl parentAcl, Sid[] loadedSids, boolean entriesInheriting, Sid owner)
          Full constructor, which should be used by persistence tools that do not provide field-level access features.
 
Method Summary
 void deleteAce(int aceIndex)
           
 boolean equals(Object obj)
           
 AccessControlEntry[] getEntries()
          Returns all of the entries represented by the present Acl.
 Serializable getId()
          Obtains an identifier that represents this MutableAcl.
 ObjectIdentity getObjectIdentity()
          Obtains the domain object this Acl provides entries for.
 Sid getOwner()
          Determines the owner of the Acl.
 Acl getParentAcl()
          A domain object may have a parent for the purpose of ACL inheritance.
 void insertAce(int atIndexLocation, Permission permission, Sid sid, boolean granting)
           
 boolean isEntriesInheriting()
          Indicates whether the ACL entries from the Acl.getParentAcl() should flow down into the current Acl.
 boolean isGranted(Permission[] permission, Sid[] sids, boolean administrativeMode)
          Determines authorization.
 boolean isSidLoaded(Sid[] sids)
          For efficiency reasons an Acl may be loaded and not contain entries for every Sid in the system.
 void setEntriesInheriting(boolean entriesInheriting)
          Change the value returned by Acl.isEntriesInheriting().
 void setOwner(Sid newOwner)
          Changes the present owner to a different owner.
 void setParent(Acl newParent)
          Changes the parent of this ACL.
 String toString()
           
 void updateAce(int aceIndex, Permission permission)
           
 void updateAuditing(int aceIndex, boolean auditSuccess, boolean auditFailure)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AclImpl

public AclImpl(ObjectIdentity objectIdentity,
               Serializable id,
               AclAuthorizationStrategy aclAuthorizationStrategy,
               AuditLogger auditLogger)
Minimal constructor, which should be used MutableAclService.createAcl(ObjectIdentity).

Parameters:
objectIdentity - the object identity this ACL relates to (required)
id - the primary key assigned to this ACL (required)
aclAuthorizationStrategy - authorization strategy (required)
auditLogger - audit logger (required)

AclImpl

public AclImpl(ObjectIdentity objectIdentity,
               Serializable id,
               AclAuthorizationStrategy aclAuthorizationStrategy,
               AuditLogger auditLogger,
               Acl parentAcl,
               Sid[] loadedSids,
               boolean entriesInheriting,
               Sid owner)
Full constructor, which should be used by persistence tools that do not provide field-level access features.

Parameters:
objectIdentity - the object identity this ACL relates to (required)
id - the primary key assigned to this ACL (required)
aclAuthorizationStrategy - authorization strategy (required)
auditLogger - audit logger (required)
parentAcl - the parent (may be null)
loadedSids - the loaded SIDs if only a subset were loaded (may be null)
entriesInheriting - if ACEs from the parent should inherit into this ACL
owner - the owner (required)
Method Detail

deleteAce

public void deleteAce(int aceIndex)
               throws NotFoundException
Specified by:
deleteAce in interface MutableAcl
Throws:
NotFoundException

getEntries

public AccessControlEntry[] getEntries()
Description copied from interface: Acl
Returns all of the entries represented by the present Acl. Entries associated with the Acl parents are not returned.

This method is typically used for administrative purposes.

The order that entries appear in the array is important for methods declared in the MutableAcl interface. Furthermore, some implementations MAY use ordering as part of advanced permission checking.

Do NOT use this method for making authorization decisions. Instead use Acl.isGranted(Permission[], Sid[], boolean).

This method must operate correctly even if the Acl only represents a subset of Sids. The caller is responsible for correctly handling the result if only a subset of Sids is represented.

Specified by:
getEntries in interface Acl
Returns:
the list of entries represented by the Acl, or null if there are no entries presently associated with this Acl.

getId

public Serializable getId()
Description copied from interface: MutableAcl
Obtains an identifier that represents this MutableAcl.

Specified by:
getId in interface MutableAcl
Returns:
the identifier, or null if unsaved

getObjectIdentity

public ObjectIdentity getObjectIdentity()
Description copied from interface: Acl
Obtains the domain object this Acl provides entries for. This is immutable once an Acl is created.

Specified by:
getObjectIdentity in interface Acl
Returns:
the object identity (never null)

getOwner

public Sid getOwner()
Description copied from interface: Acl
Determines the owner of the Acl. The meaning of ownership varies by implementation and is unspecified.

Specified by:
getOwner in interface Acl
Returns:
the owner (may be null if the implementation does not use ownership concepts)

getParentAcl

public Acl getParentAcl()
Description copied from interface: Acl
A domain object may have a parent for the purpose of ACL inheritance. If there is a parent, its ACL can be accessed via this method. In turn, the parent's parent (grandparent) can be accessed and so on.

This method solely represents the presence of a navigation hierarchy between the parent Acl and this Acl. For actual inheritance to take place, the Acl.isEntriesInheriting() must also be true.

This method must operate correctly even if the Acl only represents a subset of Sids. The caller is responsible for correctly handling the result if only a subset of Sids is represented.

Specified by:
getParentAcl in interface Acl
Returns:
the parent Acl (may be null if this Acl does not have a parent)

insertAce

public void insertAce(int atIndexLocation,
                      Permission permission,
                      Sid sid,
                      boolean granting)
               throws NotFoundException
Specified by:
insertAce in interface MutableAcl
Throws:
NotFoundException

isEntriesInheriting

public boolean isEntriesInheriting()
Description copied from interface: Acl
Indicates whether the ACL entries from the Acl.getParentAcl() should flow down into the current Acl.

The mere link between an Acl and a parent Acl on its own is insufficient to cause ACL entries to inherit down. This is because a domain object may wish to have entirely independent entries, but maintain the link with the parent for navigation purposes. Thus, this method denotes whether or not the navigation relationship also extends to the actual inheritance of entries.

Specified by:
isEntriesInheriting in interface Acl
Returns:
true if parent ACL entries inherit into the current Acl

isGranted

public boolean isGranted(Permission[] permission,
                         Sid[] sids,
                         boolean administrativeMode)
                  throws NotFoundException,
                         UnloadedSidException
Determines authorization. The order of the permission and sid arguments is extremely important! The method will iterate through each of the permissions in the order specified. For each iteration, all of the sids will be considered, again in the order they are presented. A search will then be performed for the first AccessControlEntry object that directly matches that permission:sid combination. When the first full match is found (ie an ACE that has the SID currently being searched for and the exact permission bit mask being search for), the grant or deny flag for that ACE will prevail. If the ACE specifies to grant access, the method will return true. If the ACE specifies to deny access, the loop will stop and the next permission iteration will be performed. If each permission indicates to deny access, the first deny ACE found will be considered the reason for the failure (as it was the first match found, and is therefore the one most logically requiring changes - although not always). If absolutely no matching ACE was found at all for any permission, the parent ACL will be tried (provided that there is a parent and isEntriesInheriting() is true. The parent ACL will also scan its parent and so on. If ultimately no matching ACE is found, a NotFoundException will be thrown and the caller will need to decide how to handle the permission check. Similarly, if any of the SID arguments presented to the method were not loaded by the ACL, UnloadedSidException will be thrown.

Specified by:
isGranted in interface Acl
Parameters:
permission - the exact permissions to scan for (order is important)
sids - the exact SIDs to scan for (order is important)
administrativeMode - if true denotes the query is for administrative purposes and no auditing will be undertaken
Returns:
true if one of the permissions has been granted, false if one of the permissions has been specifically revoked
Throws:
NotFoundException - if an exact ACE for one of the permission bit masks and SID combination could not be found
UnloadedSidException - if the passed SIDs are unknown to this ACL because the ACL was only loaded for a subset of SIDs

isSidLoaded

public boolean isSidLoaded(Sid[] sids)
Description copied from interface: Acl
For efficiency reasons an Acl may be loaded and not contain entries for every Sid in the system. If an Acl has been loaded and does not represent every Sid, all methods of the Acl can only be used within the limited scope of the Sid instances it actually represents.

It is normal to load an Acl for only particular Sids if read-only authorization decisions are being made. However, if user interface reporting or modification of Acls are desired, an Acl should be loaded with all Sids. This method denotes whether or not the specified Sids have been loaded or not.

Specified by:
isSidLoaded in interface Acl
Parameters:
sids - one or more security identities the caller is interest in knowing whether this Sid supports
Returns:
true if every passed Sid is represented by this Acl instance

setEntriesInheriting

public void setEntriesInheriting(boolean entriesInheriting)
Description copied from interface: MutableAcl
Change the value returned by Acl.isEntriesInheriting().

Specified by:
setEntriesInheriting in interface MutableAcl
Parameters:
entriesInheriting - the new value

setOwner

public void setOwner(Sid newOwner)
Description copied from interface: MutableAcl
Changes the present owner to a different owner.

Specified by:
setOwner in interface MutableAcl
Specified by:
setOwner in interface OwnershipAcl
Parameters:
newOwner - the new owner (mandatory; cannot be null)

setParent

public void setParent(Acl newParent)
Description copied from interface: MutableAcl
Changes the parent of this ACL.

Specified by:
setParent in interface MutableAcl
Parameters:
newParent - the new parent

toString

public String toString()
Overrides:
toString in class Object

updateAce

public void updateAce(int aceIndex,
                      Permission permission)
               throws NotFoundException
Specified by:
updateAce in interface MutableAcl
Throws:
NotFoundException

updateAuditing

public void updateAuditing(int aceIndex,
                           boolean auditSuccess,
                           boolean auditFailure)
Specified by:
updateAuditing in interface AuditableAcl

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

Spring Security Framework

Copyright © 2004-2010 SpringSource, Inc. All Rights Reserved.