org.springframework.security.acls
Interface Acl

All Superinterfaces:

Serializable

All Known Subinterfaces:

AuditableAcl, MutableAcl, OwnershipAcl

All Known Implementing Classes:

AclImpl

public interface Acl
extends Serializable

Represents an access control list (ACL) for a domain object.

An Acl represents all ACL entries for a given domain object. In order to avoid needing references to the domain object itself, this interface handles indirection between a domain object and an ACL object identity via the ObjectIdentity interface.

Implementing classes may elect to return instances that represent Permission information for either some OR all Sid instances. Therefore, an instance may NOT necessarily contain ALL Sids for a given domain object.

Version:

$Id$

Author:

Ben Alex

Method Summary

AccessControlEntry[]	getEntries() Returns all of the entries represented by the present Acl.
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.
boolean	isEntriesInheriting() Indicates whether the ACL entries from the getParentAcl() should flow down into the current Acl.
boolean	isGranted(Permission[] permission, Sid[] sids, boolean administrativeMode) This is the actual authorization logic method, and must be used whenever ACL authorization decisions are required.
boolean	isSidLoaded(Sid[] sids) For efficiency reasons an Acl may be loaded and not contain entries for every Sid in the system.

Method Detail

getEntries

AccessControlEntry[] getEntries()

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 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.

Returns:

the list of entries represented by the Acl, or null if there are no entries presently associated with this Acl.

getObjectIdentity

ObjectIdentity getObjectIdentity()

Obtains the domain object this Acl provides entries for. This is immutable once an Acl is created.

Returns:

the object identity (never null)

getOwner

Sid getOwner()

Determines the owner of the Acl. The meaning of ownership varies by implementation and is unspecified.

Returns:

the owner (may be null if the implementation does not use ownership concepts)

getParentAcl

Acl getParentAcl()

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 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.

Returns:

the parent Acl (may be null if this Acl does not have a parent)

isEntriesInheriting

boolean isEntriesInheriting()

Indicates whether the ACL entries from the 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.

Returns:

true if parent ACL entries inherit into the current Acl

isGranted

boolean isGranted(Permission[] permission,
                  Sid[] sids,
                  boolean administrativeMode)
                  throws NotFoundException,
                         UnloadedSidException

This is the actual authorization logic method, and must be used whenever ACL authorization decisions are required.

An array of Sids are presented, representing security identifies of the current principal. In addition, an array of Permissions is presented which will have one or more bits set in order to indicate the permissions needed for an affirmative authorization decision. An array is presented because holding any of the Permissions inside the array will be sufficient for an affirmative authorization.

The actual approach used to make authorization decisions is left to the implementation and is not specified by this interface. For example, an implementation MAY search the current ACL in the order the ACL entries have been stored. If a single entry is found that has the same active bits as are shown in a passed Permission, that entry's grant or deny state may determine the authorization decision. If the case of a deny state, the deny decision will only be relevant if all other Permissions passed in the array have also been unsuccessfully searched. If no entry is found that match the bits in the current ACL, provided that isEntriesInheriting() is true, the authorization decision may be passed to the parent ACL. If there is no matching entry, the implementation MAY throw an exception, or make a predefined authorization decision.

This method must operate correctly even if the Acl only represents a subset of Sids, although the implementation is permitted to throw one of the signature-defined exceptions if the method is called requesting an authorization decision for a Sid that was never loaded in this Acl.

Parameters:

permission - the permission or permissions required (at least one entry required)

sids - the security identities held by the principal (at least one entry required)

administrativeMode - if true denotes the query is for administrative purposes and no logging or auditing (if supported by the implementation) should be undertaken

Returns:

true if authorization is granted

Throws:

NotFoundException - MUST be thrown if an implementation cannot make an authoritative authorization decision, usually because there is no ACL information for this particular permission and/or SID

UnloadedSidException - thrown if the Acl does not have details for one or more of the Sids passed as arguments

isSidLoaded

boolean isSidLoaded(Sid[] sids)

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.

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