001: /* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
002: *
003: * Licensed under the Apache License, Version 2.0 (the "License");
004: * you may not use this file except in compliance with the License.
005: * You may obtain a copy of the License at
006: *
007: * http://www.apache.org/licenses/LICENSE-2.0
008: *
009: * Unless required by applicable law or agreed to in writing, software
010: * distributed under the License is distributed on an "AS IS" BASIS,
011: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: * See the License for the specific language governing permissions and
013: * limitations under the License.
014: */
015: package org.acegisecurity.acls;
016:
017: import org.acegisecurity.acls.objectidentity.ObjectIdentity;
018: import org.acegisecurity.acls.sid.Sid;
019:
020: import java.io.Serializable;
021:
022: /**
023: * Represents an access control list (ACL) for a domain object.
024: *
025: * <p>
026: * An <code>Acl</code> represents all ACL entries for a given domain object. In
027: * order to avoid needing references to the domain object itself, this
028: * interface handles indirection between a domain object and an ACL object
029: * identity via the {@link
030: * org.acegisecurity.acls.objectidentity.ObjectIdentity} interface.
031: * </p>
032: *
033: * <p>
034: * An implementation represents the {@link org.acegisecurity.acls.Permission}
035: * list applicable for some or all {@link org.acegisecurity.acls.sid.Sid}
036: * instances.
037: * </p>
038: *
039: * @author Ben Alex
040: * @version $Id: Acl.java 1784 2007-02-24 21:00:24Z luke_t $
041: */
042: public interface Acl extends Serializable {
043: //~ Methods ========================================================================================================
044:
045: /**
046: * Returns all of the entries represented by the present <code>Acl</code> (not parents).<p>This method is
047: * typically used for administrative purposes.</p>
048: * <p>The order that entries appear in the array is unspecified. However, if implementations use
049: * particular ordering logic in authorization decisions, the entries returned by this method <em>MUST</em> be
050: * ordered in that manner.</p>
051: * <p>Do <em>NOT</em> use this method for making authorization decisions. Instead use {@link
052: * #isGranted(Permission[], Sid[], boolean)}.</p>
053: * <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
054: * <code>Sid</code>s. The caller is responsible for correctly handling the result if only a subset of
055: * <code>Sid</code>s is represented.</p>
056: *
057: * @return the list of entries represented by the <code>Acl</code>
058: */
059: AccessControlEntry[] getEntries();
060:
061: /**
062: * Obtains the domain object this <code>Acl</code> provides entries for. This is immutable once an
063: * <code>Acl</code> is created.
064: *
065: * @return the object identity
066: */
067: ObjectIdentity getObjectIdentity();
068:
069: /**
070: * Determines the owner of the <code>Acl</code>. The meaning of ownership varies by implementation and is
071: * unspecified.
072: *
073: * @return the owner (may be null if the implementation does not use ownership concepts)
074: */
075: Sid getOwner();
076:
077: /**
078: * A domain object may have a parent for the purpose of ACL inheritance. If there is a parent, its ACL can
079: * be accessed via this method. In turn, the parent's parent (grandparent) can be accessed and so on.<p>This
080: * method solely represents the presence of a navigation hierarchy between the parent <code>Acl</code> and this
081: * <code>Acl</code>. For actual inheritance to take place, the {@link #isEntriesInheriting()} must also be
082: * <code>true</code>.</p>
083: * <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
084: * <code>Sid</code>s. The caller is responsible for correctly handling the result if only a subset of
085: * <code>Sid</code>s is represented.</p>
086: *
087: * @return the parent <code>Acl</code>
088: */
089: Acl getParentAcl();
090:
091: /**
092: * Indicates whether the ACL entries from the {@link #getParentAcl()} should flow down into the current
093: * <code>Acl</code>.<p>The mere link between an <code>Acl</code> and a parent <code>Acl</code> on its own
094: * is insufficient to cause ACL entries to inherit down. This is because a domain object may wish to have entirely
095: * independent entries, but maintain the link with the parent for navigation purposes. Thus, this method denotes
096: * whether or not the navigation relationship also extends to the actual inheritence of entries.</p>
097: *
098: * @return <code>true</code> if parent ACL entries inherit into the current <code>Acl</code>
099: */
100: boolean isEntriesInheriting();
101:
102: /**
103: * This is the actual authorization logic method, and must be used whenever ACL authorization decisions are
104: * required.<p>An array of <code>Sid</code>s are presented, representing security identifies of the current
105: * principal. In addition, an array of <code>Permission</code>s is presented which will have one or more bits set
106: * in order to indicate the permissions needed for an affirmative authorization decision. An array is presented
107: * because holding <em>any</em> of the <code>Permission</code>s inside the array will be sufficient for an
108: * affirmative authorization.</p>
109: * <p>The actual approach used to make authorization decisions is left to the implementation and is not
110: * specified by this interface. For example, an implementation <em>MAY</em> search the current ACL in the order
111: * the ACL entries have been stored. If a single entry is found that has the same active bits as are shown in a
112: * passed <code>Permission</code>, that entry's grant or deny state may determine the authorization decision. If
113: * the case of a deny state, the deny decision will only be relevant if all other <code>Permission</code>s passed
114: * in the array have also been unsuccessfully searched. If no entry is found that match the bits in the current
115: * ACL, provided that {@link #isEntriesInheriting()} is <code>true</code>, the authorization decision may be
116: * passed to the parent ACL. If there is no matching entry, the implementation MAY throw an exception, or make a
117: * predefined authorization decision.</p>
118: * <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
119: * <code>Sid</code>s.</p>
120: *
121: * @param permission the permission or permissions required
122: * @param sids the security identities held by the principal
123: * @param administrativeMode if <code>true</code> denotes the query is for administrative purposes and no logging
124: * or auditing (if supported by the implementation) should be undertaken
125: *
126: * @return <code>true</code> is authorization is granted
127: *
128: * @throws NotFoundException MUST be thrown if an implementation cannot make an authoritative authorization
129: * decision, usually because there is no ACL information for this particular permission and/or SID
130: * @throws UnloadedSidException thrown if the <code>Acl</code> does not have details for one or more of the
131: * <code>Sid</code>s passed as arguments
132: */
133: boolean isGranted(Permission[] permission, Sid[] sids,
134: boolean administrativeMode) throws NotFoundException,
135: UnloadedSidException;
136:
137: /**
138: * For efficiency reasons an <code>Acl</code> may be loaded and <em>not</em> contain entries for every
139: * <code>Sid</code> in the system. If an <code>Acl</code> has been loaded and does not represent every
140: * <code>Sid</code>, all methods of the <code>Sid</code> can only be used within the limited scope of the
141: * <code>Sid</code> instances it actually represents.
142: * <p>
143: * It is normal to load an <code>Acl</code> for only particular <code>Sid</code>s if read-only authorization
144: * decisions are being made. However, if user interface reporting or modification of <code>Acl</code>s are
145: * desired, an <code>Acl</code> should be loaded with all <code>Sid</code>s. This method denotes whether or
146: * not the specified <code>Sid</code>s have been loaded or not.
147: * </p>
148: *
149: * @param sids one or more security identities the caller is interest in knowing whether this <code>Sid</code>
150: * supports
151: *
152: * @return <code>true</code> if every passed <code>Sid</code> is represented by this <code>Acl</code> instance
153: */
154: boolean isSidLoaded(Sid[] sids);
155: }
|