org.springframework.security.acls.model.Acl Maven / Gradle / Ivy
/*
* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.security.acls.model;
import java.io.Serializable;
import java.util.List;
/**
* 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
* {@link org.springframework.security.acls.model.ObjectIdentity} interface.
*
*
*
* Implementing classes may elect to return instances that represent
* {@link org.springframework.security.acls.model.Permission} information for either some
* OR all {@link org.springframework.security.acls.model.Sid} instances. Therefore, an
* instance may NOT necessarily contain ALL Sids for a given domain object.
*
*
* @author Ben Alex
*/
public interface Acl extends Serializable {
/**
* 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
* {@link 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
* {@link #isGranted(List, List, 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.
*
*
* @return the list of entries represented by the Acl, or null if
* there are no entries presently associated with this Acl.
*/
List getEntries();
/**
* Obtains the domain object this Acl provides entries for. This is immutable
* once an Acl is created.
*
* @return the object identity (never null)
*/
ObjectIdentity getObjectIdentity();
/**
* Determines the owner of the Acl. The meaning of ownership varies by
* implementation and is unspecified.
*
* @return the owner (may be null if the implementation does not use
* ownership concepts)
*/
Sid getOwner();
/**
* 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 {@link #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.
*
*
* @return the parent Acl (may be null if this Acl does not
* have a parent)
*/
Acl getParentAcl();
/**
* Indicates whether the ACL entries from the {@link #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.
*
*
* @return true if parent ACL entries inherit into the current Acl
*/
boolean isEntriesInheriting();
/**
* 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 {@link #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 {@link Sid} that was never loaded in this Acl
* .
*
*
* @param permission the permission or permissions required (at least one entry
* required)
* @param sids the security identities held by the principal (at least one entry
* required)
* @param administrativeMode if true denotes the query is for administrative
* purposes and no logging or auditing (if supported by the implementation) should be
* undertaken
*
* @return 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
* @throws UnloadedSidException thrown if the Acl does not have details for
* one or more of the Sids passed as arguments
*/
boolean isGranted(List permission, List sids,
boolean administrativeMode) throws NotFoundException, UnloadedSidException;
/**
* 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.
*
*
* @param sids one or more security identities the caller is interest in knowing
* whether this Sid supports
*
* @return true if every passed Sid is represented by this
* Acl instance
*/
boolean isSidLoaded(List sids);
}