[jboss-cvs] JBossAS SVN: r85321 - projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl.

[jboss-cvs-commits at lists.jboss.org]

Author: sguilhen at redhat.com
Date: 2009-03-05 13:57:55 -0500 (Thu, 05 Mar 2009)
New Revision: 85321

Modified:
   projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACL.java
   projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACLEntry.java
Log:
SECURITY-374: merged changes made in Branch_2_0

Modified: projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACL.java
===================================================================
--- projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACL.java	2009-03-05 18:57:05 UTC (rev 85320)
+++ projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACL.java	2009-03-05 18:57:55 UTC (rev 85321)
@@ -28,15 +28,15 @@
 
 /**
  * <p>
- * This interface represents an Access Control List (ACL), a data structure used to protect access 
- * to resources. It is composed of entries, where each entry is represented by the {@code ALCEntry}
- * class and represents the permissions assigned to a given identity.
+ * This interface represents an Access Control List (ACL), a data structure used to protect access to resources. It is
+ * composed of entries, where each entry is represented by the {@code ALCEntry} class and represents the permissions
+ * assigned to a given identity.
  * </p>
  * <p>
- * When a client attempts to perform an operation on a resource, the ACL associated to the resource is used
- * to verify if the client has enough permissions to perform that operation. In order to do that, the
- * {@code ACLEntry} corresponding to the client's identity is retrieved and then the permission set
- * contained in the entry is verified to decide if access should be granted or not. 
+ * When a client attempts to perform an operation on a resource, the ACL associated to the resource is used to verify if
+ * the client has enough permissions to perform that operation. In order to do that, the {@code ACLEntry} corresponding
+ * to the client's identity is retrieved and then the permission set contained in the entry is verified to decide if
+ * access should be granted or not.
  * </p>
  * 
  * @author <a href="mailto:sguilhen at redhat.com">Stefan Guilhen</a>
@@ -46,12 +46,12 @@
 
    /**
     * <p>
-    * Adds an entry to this ACL. If the ACL already has an {@code ACLEntry} associated to the new
-    * entry's identity, then the new entry will not be added.
+    * Adds an entry to this ACL. If the ACL already has an {@code ACLEntry} associated to the new entry's identity, then
+    * the new entry will not be added.
     * </p>
     * 
     * @param entry the {@code ACLEntry} to be added.
-    * @return   {@code true} if the entry was added; {@code false} otherwise.
+    * @return {@code true} if the entry was added; {@code false} otherwise.
     */
    public boolean addEntry(ACLEntry entry);
 
@@ -60,9 +60,8 @@
     * Removes an entry from this ACL.
     * </p>
     * 
-    * @param entry  the {@code ACLEntry} to be removed.
-    * @return   {@code true} if the entry is removed; {@code false} if the entry can't be found
-    * in the ACL.
+    * @param entry the {@code ACLEntry} to be removed.
+    * @return {@code true} if the entry is removed; {@code false} if the entry can't be found in the ACL.
     */
    public boolean removeEntry(ACLEntry entry);
 
@@ -71,22 +70,33 @@
     * Obtains the collection of all {@code ACLEntries} in this ACL.
     * </p>
     * 
-    * @return   a {@code Collection} containing all entries in this ACL.
+    * @return a {@code Collection} containing all entries in this ACL.
     */
    public Collection<? extends ACLEntry> getEntries();
 
    /**
     * <p>
-    * Obtains the entry that corresponds to the specified identity.
+    * Obtains the entry that corresponds to the specified identity. Calling this method is the same as doing
+    * {@code getEntry(identity.getName())}.
     * </p>
     * 
     * @param identity a reference to the {@code Identity} object.
-    * @return   the {@code ACLEntry} that corresponds to the identity, or {@code null} if no entry could be found.
+    * @return the {@code ACLEntry} that corresponds to the identity, or {@code null} if no entry could be found.
     */
    public ACLEntry getEntry(Identity identity);
-   
+
    /**
     * <p>
+    * Obtains the entry that corresponds to the specified identity or role name.
+    * </p>
+    * 
+    * @param identityOrRole a {@code String} representing an identity or role.
+    * @return the {@code ACLEntry} that corresponds to the identity or role or {@code null} if no entry could be found.
+    */
+   public ACLEntry getEntry(String identityOrRole);
+
+   /**
+    * <p>
     * Obtains a reference to the resource being protected by this ACL.
     * </p>
     * 
@@ -100,9 +110,8 @@
     * </p>
     * 
     * @param permission the {@code ACLPermission} to be checked for.
-    * @param identity   the {@code Identity} being verified.
-    * @return   {@code true} if the specified permission is assigned to the identity;
-    * {@code false} otherwise.
+    * @param identity the {@code Identity} being verified.
+    * @return {@code true} if the specified permission is assigned to the identity; {@code false} otherwise.
     */
    public boolean isGranted(ACLPermission permission, Identity identity);
 }

Modified: projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACLEntry.java
===================================================================
--- projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACLEntry.java	2009-03-05 18:57:05 UTC (rev 85320)
+++ projects/security/security-spi/trunk/acl/src/main/org/jboss/security/acl/ACLEntry.java	2009-03-05 18:57:55 UTC (rev 85321)
@@ -35,10 +35,18 @@
 
    /**
     * <p>
-    * Obtains the {@code Identity} for which a permission has been assigned in
-    * this entry.
+    * Obtains the identity or role for which a permission has been assigned in this entry.
     * </p>
     * 
+    * @return a {@code String} representing the identity or role name.
+    */
+   public String getIdentityOrRole();
+
+   /**
+    * <p>
+    * Obtains the {@code Identity} for which a permission has been assigned in this entry.
+    * </p>
+    * 
     * @return a reference to the {@code Identity} contained in this entry.
     */
    public Identity getIdentity();
@@ -58,8 +66,7 @@
     * </p>
     * 
     * @param permission the {@code ACLPermission} to be checked for.
-    * @return {@code true} if the permission is part of this entry's permission; 
-    * {@code false} otherwise.
+    * @return {@code true} if the permission is part of this entry's permission; {@code false} otherwise.
     */
    public boolean checkPermission(ACLPermission permission);
 }