Package org.springframework.security.acls.model

# 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 `Sid`s for a given domain object.

## Method Summary

Modifier and Type
Method
Description
`List<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(List<Permission> permission, List<Sid> sids, boolean administrativeMode)`
This is the actual authorization logic method, and must be used whenever ACL authorization decisions are required.
`boolean`
`isSidLoaded(List<Sid> sids)`
For efficiency reasons an `Acl` may be loaded and not contain entries for every `Sid` in the system.

## Method Details

### getEntries

List<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(List, List, boolean)`.

This method must operate correctly even if the `Acl` only represents a subset of `Sid`s. The caller is responsible for correctly handling the result if only a subset of `Sid`s 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 `Sid`s. The caller is responsible for correctly handling the result if only a subset of `Sid`s 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(List<Permission> permission, List<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 `Sid`s are presented, representing security identifies of the current principal. In addition, an array of `Permission`s 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 `Permission`s 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 `Permission`s 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 `Sid`s, 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 `Sid`s passed as arguments

### isSidLoaded

boolean isSidLoaded(List<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 `Sid`s if read-only authorization decisions are being made. However, if user interface reporting or modification of `Acl`s are desired, an `Acl` should be loaded with all `Sid`s. This method denotes whether or not the specified `Sid`s 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