From bf41423b5bd5db40b0cdadc80a890b99c37c0542 Mon Sep 17 00:00:00 2001 From: Ben Alex Date: Fri, 4 Apr 2008 00:49:34 +0000 Subject: [PATCH] Various modest documentation improvements. --- .../springframework/security/acls/Acl.java | 122 ++++++++++-------- .../security/acls/AclFormattingUtils.java | 8 +- .../security/acls/MutableAcl.java | 12 +- .../acls/objectidentity/ObjectIdentity.java | 40 +++--- 4 files changed, 96 insertions(+), 86 deletions(-) diff --git a/acl/src/main/java/org/springframework/security/acls/Acl.java b/acl/src/main/java/org/springframework/security/acls/Acl.java index 5b71398c4a..a5dbc97fe3 100644 --- a/acl/src/main/java/org/springframework/security/acls/Acl.java +++ b/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. * *

- * An Acl represents all ACL entries for a given domain object. In + * 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 @@ -32,6 +32,7 @@ import java.io.Serializable; *

* *

+ * 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 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 {@link + /** + * 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 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 {@link * #isGranted(Permission[], Sid[], 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.

+ * + *

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 + * @return the list of entries represented by the Acl, or null if there are + * no entries presently associated with this Acl. */ AccessControlEntry[] getEntries(); /** - * Obtains the domain object this Acl provides entries for. This is immutable once an - * Acl is created. + * Obtains the domain object this Acl provides entries for. This is immutable once an + * Acl is created. * - * @return the object identity + * @return the object identity (never null) */ ObjectIdentity getObjectIdentity(); /** - * Determines the owner of the Acl. The meaning of ownership varies by implementation and is + * 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) + * @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.

+ * 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 + * @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 + * 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.

+ * 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 + * @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 + * 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 + * 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 + * + *

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 + * 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 + * 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.

+ * + *

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 - * @param sids the security identities held by the principal - * @param administrativeMode if true 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 true denotes the query is for administrative purposes and no logging * or auditing (if supported by the implementation) should be undertaken * - * @return true is authorization is granted + * @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 + * @throws UnloadedSidException thrown if the Acl does not have details for one or more of the + * Sids passed as arguments */ boolean isGranted(Permission[] permission, Sid[] 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 Sid can only be used within the limited scope of the - * Sid instances it actually represents. + * 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. + * 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 + * @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 + * @return true if every passed Sid is represented by this Acl instance */ boolean isSidLoaded(Sid[] sids); } diff --git a/acl/src/main/java/org/springframework/security/acls/AclFormattingUtils.java b/acl/src/main/java/org/springframework/security/acls/AclFormattingUtils.java index caff1cd087..4680086f32 100644 --- a/acl/src/main/java/org/springframework/security/acls/AclFormattingUtils.java +++ b/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 { - //~ Constructors =================================================================================================== - - private AclFormattingUtils() { - } - - //~ Methods ======================================================================================================== +public abstract class AclFormattingUtils { public static String demergePatterns(String original, String removeBits) { Assert.notNull(original, "Original string required"); diff --git a/acl/src/main/java/org/springframework/security/acls/MutableAcl.java b/acl/src/main/java/org/springframework/security/acls/MutableAcl.java index f04d0db438..7eff263139 100644 --- a/acl/src/main/java/org/springframework/security/acls/MutableAcl.java +++ b/acl/src/main/java/org/springframework/security/acls/MutableAcl.java @@ -20,7 +20,7 @@ import java.io.Serializable; /** - * A mutable Acl. + * A mutable Acl. * *

* 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 - * MutableAcl. The returned objects should be immutable outside the package, and therefore it is safe - * to return them to the caller for informational purposes. The AccessControlEntry information is - * needed so that invocations of update and delete methods on the MutableAcl can refer to a valid + * MutableAcl. The returned objects should be immutable outside the package, and therefore it is safe + * to return them to the caller for informational purposes. The AccessControlEntry information is + * needed so that invocations of update and delete methods on the MutableAcl 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 MutableAcl. + * Obtains an identifier that represents this MutableAcl. * - * @return the identifier, or null if unsaved + * @return the identifier, or null if unsaved */ Serializable getId(); diff --git a/acl/src/main/java/org/springframework/security/acls/objectidentity/ObjectIdentity.java b/acl/src/main/java/org/springframework/security/acls/objectidentity/ObjectIdentity.java index 3d1634a088..eedc824964 100644 --- a/acl/src/main/java/org/springframework/security/acls/objectidentity/ObjectIdentity.java +++ b/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. * - *

- * 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 ObjectIdentitys equal if - * identity1.equals(identity2), rather than reference-equality of - * identity1==identity2. + *

+ * As implementations of ObjectIdentity 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 + * ObjectIdentitys equal if identity1.equals(identity2), rather than + * reference-equality of identity1==identity2. *

* * @author Ben Alex @@ -36,35 +36,37 @@ public interface ObjectIdentity extends Serializable { //~ Methods ======================================================================================================== /** - * Refer to the java.lang.Object documentation for the interface contract. - * * @param obj to be compared * - * @return true if the objects are equal, false otherwise + * @return true if the objects are equal, false 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 javaType.

Because ACLs are largely immutable, it is strongly recommended to use + * the same javaType. + * + *

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.

+ * business meaning, as that business meaning may change in the future such change will cascade to the ACL + * subsystem data.

* - * @return the identifier (unique within this javaType + * @return the identifier (unique within this javaType; never null) */ 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 null) */ Class getJavaType(); /** - * Refer to the java.lang.Object documentation for the interface contract. - * - * @return a hash code representation of this object + * @return a hash code representation of the ObjectIdentity + * @see Object#hashCode() */ int hashCode(); }