Various modest documentation improvements.

acl/src/main/java/org/springframework/security/acls/Acl.java

@@ -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
+     * Returns all of the entries represented by the present <tt>Acl</tt>. Entries associated with
-     * typically used for administrative purposes.</p>
+     * 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
+     * particular ordering logic in authorization decisions, the entries returned by this method 
-     * ordered in that manner.</p>
+     * <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>
      * 
-     * @return the list of entries represented by the <code>Acl</code>
+     * <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 <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
+     * Obtains the domain object this <tt>Acl</tt> provides entries for. This is immutable once an
-     * <code>Acl</code> is created.
+     * <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
+     * be accessed via this method. In turn, the parent's parent (grandparent) can be accessed and so on.
-     * 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>
      * 
-     * @return the parent <code>Acl</code>
+     * <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 <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
+     * required.
-     * principal. In addition, an array of <code>Permission</code>s is presented which will have one or more bits set
+     * 
+     * <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
      * 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
+     * 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 <code>Permission</code>s passed
+     * 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>
      * 
-     * @param permission the permission or permissions required
+     * <p>This method must operate correctly even if the <tt>Acl</tt> only represents a subset of <tt>Sid</tt>s,
-     * @param sids the security identities held by the principal
+     * although the implementation is permitted to throw one of the signature-defined exceptions if the method 
-     * @param administrativeMode if <code>true</code> denotes the query is for administrative purposes and no logging
+     * 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 (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
+     * @throws UnloadedSidException thrown if the <tt>Acl</tt> does not have details for one or more of the
-     *         <code>Sid</code>s passed as arguments
+     *         <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
+     * For efficiency reasons an <tt>Acl</tt> 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
+     * <tt>Sid</tt> in the system. If an <tt>Acl</tt> 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
+     * <tt>Sid</tt>, all methods of the <tt>Acl</tt> can only be used within the limited scope of the
-     * <code>Sid</code> instances it actually represents.
+     * <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
+     * 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 <code>Acl</code>s are
+     * decisions are being made. However, if user interface reporting or modification of <tt>Acl</tt>s are
-     * desired, an <code>Acl</code> should be loaded with all <code>Sid</code>s. This method denotes whether or
+     * desired, an <tt>Acl</tt> should be loaded with all <tt>Sid</tt>s. This method denotes whether or
-     * not the specified <code>Sid</code>s have been loaded or not.
+     * 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);
 }

acl/src/main/java/org/springframework/security/acls/AclFormattingUtils.java

@@ -23,13 +23,7 @@ import org.springframework.util.Assert;
  * @author Ben Alex
  * @version $Id$
  */
-public final class AclFormattingUtils {
+public abstract class AclFormattingUtils {
-    //~ Constructors ===================================================================================================
-
-    private AclFormattingUtils() {
-    }
-
-    //~ Methods ========================================================================================================
 
     public static String demergePatterns(String original, String removeBits) {
         Assert.notNull(original, "Original string required");

acl/src/main/java/org/springframework/security/acls/MutableAcl.java

@@ -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
+     * <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 <code>AccessControlEntry</code> information is
+     * 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 <code>MutableAcl</code> can refer to a valid
+     * 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();
 

acl/src/main/java/org/springframework/security/acls/objectidentity/ObjectIdentity.java

@@ -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>
+ * <p>
- * As implementations are used as the key for caching and lookup, it is
+ * As implementations of <tt>ObjectIdentity</tt> are used as the key to represent 
- * essential that implementations provide methods so that object-equality
+ * domain objects in the ACL subsystem, it is essential that implementations provide
- * rather than reference-equality can be relied upon by caches. In other
+ * methods so that object-equality rather than reference-equality can be relied upon
- * words, a cache can consider two <code>ObjectIdentity</code>s equal if
+ * reliably. In other words, the ACL subsystem can consider two 
- * <code>identity1.equals(identity2)</code>, rather than reference-equality of
+ * <tt>ObjectIdentity</tt>s equal if <tt>identity1.equals(identity2)</tt>, rather than 
- * <code>identity1==identity2</code>.
+ * 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>.
-     * 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>
      * 
-     * @return the identifier (unique within this <code>javaType</code>
+     * <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 in the future such change will cascade to the ACL 
+     * subsystem data.</p>
+     *
+     * @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 the <tt>ObjectIdentity</tt>
-     *
+     * @see Object#hashCode()
-     * @return a hash code representation of this object
      */
     int hashCode();
 }