Various modest documentation improvements.
This commit is contained in:
Ben Alex
parent
b7188b11d8
commit
bf41423b5b
|
|
@ -24,7 +24,7 @@ import java.io.Serializable;
|
|||
* Represents an access control list (ACL) for a domain object.
|
||||
*
|
||||
* <p>
|
||||
* An <code>Acl</code> represents all ACL entries for a given domain object. In
|
||||
* An <tt>Acl</tt> 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
|
||||
|
|
@ -32,6 +32,7 @@ import java.io.Serializable;
|
|||
* </p>
|
||||
*
|
||||
* <p>
|
||||
* TODO: Clarify this paragraph
|
||||
* An implementation represents the {@link org.springframework.security.acls.Permission}
|
||||
* list applicable for some or all {@link org.springframework.security.acls.sid.Sid}
|
||||
* instances.
|
||||
|
|
@ -41,115 +42,128 @@ import java.io.Serializable;
|
|||
* @version $Id$
|
||||
*/
|
||||
public interface Acl extends Serializable {
|
||||
//~ Methods ========================================================================================================
|
||||
|
||||
/**
|
||||
* Returns all of the entries represented by the present <code>Acl</code> (not parents).<p>This method is
|
||||
* typically used for administrative purposes.</p>
|
||||
* <p>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 <em>MUST</em> be
|
||||
* ordered in that manner.</p>
|
||||
* <p>Do <em>NOT</em> use this method for making authorization decisions. Instead use {@link
|
||||
/**
|
||||
* Returns all of the entries represented by the present <tt>Acl</tt>. Entries associated with
|
||||
* the <tt>Acl</tt> parents are not returned.
|
||||
*
|
||||
* <p>This method is typically used for administrative purposes.</p>
|
||||
*
|
||||
* <p>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
|
||||
* <em>MUST</em> be ordered in that manner.</p>
|
||||
*
|
||||
* <p>Do <em>NOT</em> use this method for making authorization decisions. Instead use {@link
|
||||
* #isGranted(Permission[], Sid[], boolean)}.</p>
|
||||
* <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
|
||||
* <code>Sid</code>s. The caller is responsible for correctly handling the result if only a subset of
|
||||
* <code>Sid</code>s is represented.</p>
|
||||
*
|
||||
* <p>This method must operate correctly even if the <tt>Acl</tt> only represents a subset of
|
||||
* <tt>Sid</tt>s. The caller is responsible for correctly handling the result if only a subset of
|
||||
* <tt>Sid</tt>s is represented.</p>
|
||||
*
|
||||
* @return the list of entries represented by the <code>Acl</code>
|
||||
* @return the list of entries represented by the <tt>Acl</tt>, or <tt>null</tt> if there are
|
||||
* no entries presently associated with this <tt>Acl</tt>.
|
||||
*/
|
||||
AccessControlEntry[] getEntries();
|
||||
|
||||
/**
|
||||
* Obtains the domain object this <code>Acl</code> provides entries for. This is immutable once an
|
||||
* <code>Acl</code> is created.
|
||||
* Obtains the domain object this <tt>Acl</tt> provides entries for. This is immutable once an
|
||||
* <tt>Acl</tt> is created.
|
||||
*
|
||||
* @return the object identity
|
||||
* @return the object identity (never <tt>null</tt>)
|
||||
*/
|
||||
ObjectIdentity getObjectIdentity();
|
||||
|
||||
/**
|
||||
* Determines the owner of the <code>Acl</code>. The meaning of ownership varies by implementation and is
|
||||
* Determines the owner of the <tt>Acl</tt>. The meaning of ownership varies by implementation and is
|
||||
* unspecified.
|
||||
*
|
||||
* @return the owner (may be null if the implementation does not use ownership concepts)
|
||||
* @return the owner (may be <tt>null</tt> 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.<p>This
|
||||
* method solely represents the presence of a navigation hierarchy between the parent <code>Acl</code> and this
|
||||
* <code>Acl</code>. For actual inheritance to take place, the {@link #isEntriesInheriting()} must also be
|
||||
* <code>true</code>.</p>
|
||||
* <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
|
||||
* <code>Sid</code>s. The caller is responsible for correctly handling the result if only a subset of
|
||||
* <code>Sid</code>s is represented.</p>
|
||||
* be accessed via this method. In turn, the parent's parent (grandparent) can be accessed and so on.
|
||||
*
|
||||
* <p>This method solely represents the presence of a navigation hierarchy between the parent <tt>Acl</tt> and this
|
||||
* <tt>Acl</tt>. For actual inheritance to take place, the {@link #isEntriesInheriting()} must also be
|
||||
* <tt>true</tt>.</p>
|
||||
*
|
||||
* <p>This method must operate correctly even if the <tt>Acl</tt> only represents a subset of
|
||||
* <tt>Sid</tt>s. The caller is responsible for correctly handling the result if only a subset of
|
||||
* <tt>Sid</tt>s is represented.</p>
|
||||
*
|
||||
* @return the parent <code>Acl</code>
|
||||
* @return the parent <tt>Acl</tt> (may be <tt>null</tt> if this <tt>Acl</tt> does not have a parent)
|
||||
*/
|
||||
Acl getParentAcl();
|
||||
|
||||
/**
|
||||
* Indicates whether the ACL entries from the {@link #getParentAcl()} should flow down into the current
|
||||
* <code>Acl</code>.<p>The mere link between an <code>Acl</code> and a parent <code>Acl</code> on its own
|
||||
* <tt>Acl</tt>.<p>The mere link between an <tt>Acl</tt> and a parent <tt>Acl</tt> 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.</p>
|
||||
* whether or not the navigation relationship also extends to the actual inheritance of entries.</p>
|
||||
*
|
||||
* @return <code>true</code> if parent ACL entries inherit into the current <code>Acl</code>
|
||||
* @return <tt>true</tt> if parent ACL entries inherit into the current <tt>Acl</tt>
|
||||
*/
|
||||
boolean isEntriesInheriting();
|
||||
|
||||
/**
|
||||
* This is the actual authorization logic method, and must be used whenever ACL authorization decisions are
|
||||
* required.<p>An array of <code>Sid</code>s are presented, representing security identifies of the current
|
||||
* principal. In addition, an array of <code>Permission</code>s is presented which will have one or more bits set
|
||||
* required.
|
||||
*
|
||||
* <p>An array of <tt>Sid</tt>s are presented, representing security identifies of the current
|
||||
* principal. In addition, an array of <tt>Permission</tt>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 <em>any</em> of the <code>Permission</code>s inside the array will be sufficient for an
|
||||
* because holding <em>any</em> of the <tt>Permission</tt>s inside the array will be sufficient for an
|
||||
* affirmative authorization.</p>
|
||||
* <p>The actual approach used to make authorization decisions is left to the implementation and is not
|
||||
*
|
||||
* <p>The actual approach used to make authorization decisions is left to the implementation and is not
|
||||
* specified by this interface. For example, an implementation <em>MAY</em> 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 <code>Permission</code>, 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 <code>Permission</code>s passed
|
||||
* passed <tt>Permission</tt>, 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 <tt>Permission</tt>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 {@link #isEntriesInheriting()} is <code>true</code>, the authorization decision may be
|
||||
* ACL, provided that {@link #isEntriesInheriting()} is <tt>true</tt>, 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.</p>
|
||||
* <p>This method must operate correctly even if the <code>Acl</code> only represents a subset of
|
||||
* <code>Sid</code>s.</p>
|
||||
*
|
||||
* <p>This method must operate correctly even if the <tt>Acl</tt> only represents a subset of <tt>Sid</tt>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 {@link Sid} that was never loaded in this <tt>Acl</tt>.
|
||||
* </p>
|
||||
*
|
||||
* @param permission the permission or permissions required
|
||||
* @param sids the security identities held by the principal
|
||||
* @param administrativeMode if <code>true</code> denotes the query is for administrative purposes and no logging
|
||||
* @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 <tt>true</tt> denotes the query is for administrative purposes and no logging
|
||||
* or auditing (if supported by the implementation) should be undertaken
|
||||
*
|
||||
* @return <code>true</code> is authorization is granted
|
||||
* @return <tt>true</tt> 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 <code>Acl</code> does not have details for one or more of the
|
||||
* <code>Sid</code>s passed as arguments
|
||||
* @throws UnloadedSidException thrown if the <tt>Acl</tt> does not have details for one or more of the
|
||||
* <tt>Sid</tt>s passed as arguments
|
||||
*/
|
||||
boolean isGranted(Permission[] permission, Sid[] sids, boolean administrativeMode)
|
||||
throws NotFoundException, UnloadedSidException;
|
||||
|
||||
/**
|
||||
* For efficiency reasons an <code>Acl</code> may be loaded and <em>not</em> contain entries for every
|
||||
* <code>Sid</code> in the system. If an <code>Acl</code> has been loaded and does not represent every
|
||||
* <code>Sid</code>, all methods of the <code>Sid</code> can only be used within the limited scope of the
|
||||
* <code>Sid</code> instances it actually represents.
|
||||
* For efficiency reasons an <tt>Acl</tt> may be loaded and <em>not</em> contain entries for every
|
||||
* <tt>Sid</tt> in the system. If an <tt>Acl</tt> has been loaded and does not represent every
|
||||
* <tt>Sid</tt>, all methods of the <tt>Acl</tt> can only be used within the limited scope of the
|
||||
* <tt>Sid</tt> instances it actually represents.
|
||||
* <p>
|
||||
* It is normal to load an <code>Acl</code> for only particular <code>Sid</code>s if read-only authorization
|
||||
* decisions are being made. However, if user interface reporting or modification of <code>Acl</code>s are
|
||||
* desired, an <code>Acl</code> should be loaded with all <code>Sid</code>s. This method denotes whether or
|
||||
* not the specified <code>Sid</code>s have been loaded or not.
|
||||
* It is normal to load an <tt>Acl</tt> for only particular <tt>Sid</tt>s if read-only authorization
|
||||
* decisions are being made. However, if user interface reporting or modification of <tt>Acl</tt>s are
|
||||
* desired, an <tt>Acl</tt> should be loaded with all <tt>Sid</tt>s. This method denotes whether or
|
||||
* not the specified <tt>Sid</tt>s have been loaded or not.
|
||||
* </p>
|
||||
*
|
||||
* @param sids one or more security identities the caller is interest in knowing whether this <code>Sid</code>
|
||||
* @param sids one or more security identities the caller is interest in knowing whether this <tt>Sid</tt>
|
||||
* supports
|
||||
*
|
||||
* @return <code>true</code> if every passed <code>Sid</code> is represented by this <code>Acl</code> instance
|
||||
* @return <tt>true</tt> if every passed <tt>Sid</tt> is represented by this <tt>Acl</tt> instance
|
||||
*/
|
||||
boolean isSidLoaded(Sid[] sids);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -23,13 +23,7 @@ import org.springframework.util.Assert;
|
|||
* @author Ben Alex
|
||||
* @version $Id$
|
||||
*/
|
||||
public final class AclFormattingUtils {
|
||||
//~ Constructors ===================================================================================================
|
||||
|
||||
private AclFormattingUtils() {
|
||||
}
|
||||
|
||||
//~ Methods ========================================================================================================
|
||||
public abstract class AclFormattingUtils {
|
||||
|
||||
public static String demergePatterns(String original, String removeBits) {
|
||||
Assert.notNull(original, "Original string required");
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ import java.io.Serializable;
|
|||
|
||||
|
||||
/**
|
||||
* A mutable <code>Acl</code>.
|
||||
* A mutable <tt>Acl</tt>.
|
||||
*
|
||||
* <p>
|
||||
* A mutable ACL must ensure that appropriate security checks are performed
|
||||
|
|
@ -37,9 +37,9 @@ public interface MutableAcl extends Acl {
|
|||
|
||||
/**
|
||||
* Retrieves all of the non-deleted {@link AccessControlEntry} instances currently stored by the
|
||||
* <code>MutableAcl</code>. The returned objects should be immutable outside the package, and therefore it is safe
|
||||
* to return them to the caller for informational purposes. The <code>AccessControlEntry</code> information is
|
||||
* needed so that invocations of update and delete methods on the <code>MutableAcl</code> can refer to a valid
|
||||
* <tt>MutableAcl</tt>. The returned objects should be immutable outside the package, and therefore it is safe
|
||||
* to return them to the caller for informational purposes. The <tt>AccessControlEntry</tt> information is
|
||||
* needed so that invocations of update and delete methods on the <tt>MutableAcl</tt> can refer to a valid
|
||||
* {@link AccessControlEntry#getId()}.
|
||||
*
|
||||
* @return DOCUMENT ME!
|
||||
|
|
@ -47,9 +47,9 @@ public interface MutableAcl extends Acl {
|
|||
AccessControlEntry[] getEntries();
|
||||
|
||||
/**
|
||||
* Obtains an identifier that represents this <code>MutableAcl</code>.
|
||||
* Obtains an identifier that represents this <tt>MutableAcl</tt>.
|
||||
*
|
||||
* @return the identifier, or <code>null</code> if unsaved
|
||||
* @return the identifier, or <tt>null</tt> if unsaved
|
||||
*/
|
||||
Serializable getId();
|
||||
|
||||
|
|
|
|||
|
|
@ -18,15 +18,15 @@ import java.io.Serializable;
|
|||
|
||||
|
||||
/**
|
||||
* Interface representing the identity of an individual domain object instance.
|
||||
* Represents the identity of an individual domain object instance.
|
||||
*
|
||||
* <P>
|
||||
* As implementations are used as the key for caching and lookup, it is
|
||||
* essential that implementations provide methods so that object-equality
|
||||
* rather than reference-equality can be relied upon by caches. In other
|
||||
* words, a cache can consider two <code>ObjectIdentity</code>s equal if
|
||||
* <code>identity1.equals(identity2)</code>, rather than reference-equality of
|
||||
* <code>identity1==identity2</code>.
|
||||
* <p>
|
||||
* As implementations of <tt>ObjectIdentity</tt> are used as the key to represent
|
||||
* domain objects in the ACL subsystem, it is essential that implementations provide
|
||||
* methods so that object-equality rather than reference-equality can be relied upon
|
||||
* reliably. In other words, the ACL subsystem can consider two
|
||||
* <tt>ObjectIdentity</tt>s equal if <tt>identity1.equals(identity2)</tt>, rather than
|
||||
* reference-equality of <tt>identity1==identity2</tt>.
|
||||
* </p>
|
||||
*
|
||||
* @author Ben Alex
|
||||
|
|
@ -36,35 +36,37 @@ public interface ObjectIdentity extends Serializable {
|
|||
//~ Methods ========================================================================================================
|
||||
|
||||
/**
|
||||
* Refer to the <code>java.lang.Object</code> documentation for the interface contract.
|
||||
*
|
||||
* @param obj to be compared
|
||||
*
|
||||
* @return <code>true</code> if the objects are equal, <code>false</code> otherwise
|
||||
* @return <tt>true</tt> if the objects are equal, <tt>false</tt> otherwise
|
||||
* @see Object#equals(Object)
|
||||
*/
|
||||
boolean equals(Object obj);
|
||||
|
||||
/**
|
||||
* Obtains the actual identifier. This identifier must not be reused to represent other domain objects with
|
||||
* the same <code>javaType</code>.<p>Because ACLs are largely immutable, it is strongly recommended to use
|
||||
* the same <tt>javaType</tt>.
|
||||
*
|
||||
* <p>Because ACLs are largely immutable, it is strongly recommended to use
|
||||
* a synthetic identifier (such as a database sequence number for the primary key). Do not use an identifier with
|
||||
* business meaning, as that business meaning may change.</p>
|
||||
* business meaning, as that business meaning may change in the future such change will cascade to the ACL
|
||||
* subsystem data.</p>
|
||||
*
|
||||
* @return the identifier (unique within this <code>javaType</code>
|
||||
* @return the identifier (unique within this <tt>javaType</tt>; never <tt>null</tt>)
|
||||
*/
|
||||
Serializable getIdentifier();
|
||||
|
||||
/**
|
||||
* Obtains the Java type represented by the domain object.
|
||||
* Obtains the Java type represented by the domain object. The Java type can be an interface or a class, but is
|
||||
* most often the domain object implementation class.
|
||||
*
|
||||
* @return the Java type of the domain object
|
||||
* @return the Java type of the domain object (never <tt>null</tt>)
|
||||
*/
|
||||
Class getJavaType();
|
||||
|
||||
/**
|
||||
* Refer to the <code>java.lang.Object</code> documentation for the interface contract.
|
||||
*
|
||||
* @return a hash code representation of this object
|
||||
* @return a hash code representation of the <tt>ObjectIdentity</tt>
|
||||
* @see Object#hashCode()
|
||||
*/
|
||||
int hashCode();
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue