public interface Acl extends Serializable
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.
An implementation represents the Permission
list applicable for some or all Sid
instances.
Modifier and Type | Method and Description |
---|---|
AccessControlEntry[] |
getEntries()
Returns all of the entries represented by the present
Acl (not parents). |
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. |
AccessControlEntry[] getEntries()
Acl
(not parents).This method is typically used for administrative purposes.
The order that entries appear in the array is unspecified. However, if implementations use particular ordering logic in authorization decisions, the entries returned by this method MUST be ordered in that manner.
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
Sid
s. The caller is responsible for correctly handling the result if only a subset of
Sid
s is represented.
Acl
ObjectIdentity getObjectIdentity()
Acl
provides entries for. This is immutable once an
Acl
is created.Sid getOwner()
Acl
. The meaning of ownership varies by implementation and is
unspecified.Acl getParentAcl()
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.
Acl
boolean isEntriesInheriting()
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 inheritence of entries.
true
if parent ACL entries inherit into the current Acl
boolean isGranted(Permission[] permission, Sid[] sids, boolean administrativeMode) throws NotFoundException, UnloadedSidException
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.
permission
- the permission or permissions requiredsids
- the security identities held by the principaladministrativeMode
- if true
denotes the query is for administrative purposes and no logging
or auditing (if supported by the implementation) should be undertakentrue
is authorization is grantedNotFoundException
- 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 SIDUnloadedSidException
- thrown if the Acl
does not have details for one or more of the
Sid
s passed as argumentsboolean isSidLoaded(Sid[] sids)
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 Sid
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.
sids
- one or more security identities the caller is interest in knowing whether this Sid
supportstrue
if every passed Sid
is represented by this Acl
instanceCopyright © 2016. All rights reserved.