--- experimental/server/ACL/ACL.java	2001/12/19 23:43:27	1.1
+++ experimental/server/ACL/ACL.java	2001/12/20 00:59:54	1.2
@@ -8,10 +8,15 @@ import java.util.Iterator;
 import java.net.InetAddress;
 
 /**
- * Access Control List
+ * Access Control List for use primarily
+ * with the ACLServerSocket. It could, however
+ * have other uses as it has a fairly generic
+ * behaviour. Rules are added using the add
+ * method, and then checks can be made using
+ * the relevant check method.
  *
  * @author  $Author: tdb $
- * @version $Id: ACL.java,v 1.1 2001/12/19 23:43:27 tdb Exp $
+ * @version $Id: ACL.java,v 1.2 2001/12/20 00:59:54 tdb Exp $
  */
 public class ACL {
 
@@ -20,47 +25,93 @@ public class ACL {
     /**
      * The current CVS revision of this class
      */
-    public static final String REVISION = "$Revision: 1.1 $";
-
+    public static final String REVISION = "$Revision: 1.2 $";
+    
+    /**
+     * static to be used when adding an ALLOW rule to the ACL.
+     */
     public static final boolean ALLOW = true;
+    
+    /**
+     * static to be used when adding a DENY rule to the ACL.
+     */
     public static final boolean DENY = false;
 
 //---STATIC METHODS---
 
 //---CONSTRUCTORS---
 
+    /**
+     * Construct a new Access Control List. The default
+     * mode is to ALLOW anything that isn't explicitly
+     * blocked by a rule.
+     */
     public ACL() {
         // default to ACL.ALLOW
         this(ACL.ALLOW);
     }
     
+    /**
+     * Construct a new Access Control List with a given
+     * default mode. This mode specifies what should
+     * happen if a check does not match any rules.
+     *
+     * @param defaultMode the default mode for non-matched checks
+     */
     public ACL(boolean defaultMode) {
         _defaultMode = defaultMode;
     }
 
 //---PUBLIC METHODS---
 
+    /**
+     * Add a new rule to the ACL immediately after the
+     * previous rule. The rule can either be an ACL.ALLOW
+     * rule, or an ACL.DENY rule. The expression can
+     * contain a wildcard (a * only). Rules can only be
+     * added to the end of the list.
+     *
+     * param allow whether this is an ALLOW or DENY rule
+     * param expression what this rule matches using wildcards
+     */
     public void add(boolean allow, String expression) {
-        _acl.add(new ACLItem(allow, expression));
+        _acl.add(new ACLRule(allow, expression));
     }
     
+    /**
+     * Check to see if a string is permitted by the
+     * ACL. Useful for testing, and non-Socket uses
+     * of this class.
+     *
+     * @param address the string to check
+     * @return whether the address was permitted by the ACL
+     */
     public boolean check(String address) {
         Iterator i = _acl.iterator();
         while(i.hasNext()) {
-            ACLItem item = (ACLItem) i.next();
+            ACLRule item = (ACLRule) i.next();
             if(StringUtils.wildcardCheck(address, item._expression)) {
                 return item._allow;
             }
         }
-        // what to do here?
-        // -- basically a default of deny/allow is needed
         return _defaultMode;
     }
     
+    /**
+     * Check to see if an InetAddress is permitted
+     * by the ACL. Perfect for Socket uses of this
+     * class. It should be made clear that this will
+     * check both the hostname AND IP address against
+     * each rule in turn. The hostname will always be
+     * checked BEFORE the IP address.
+     *
+     * @param address the InetAddress to check
+     * @return whether the InetAddress was permitted by the ACL
+     */
     public boolean check(InetAddress address) {
         Iterator i = _acl.iterator();
         while(i.hasNext()) {
-            ACLItem item = (ACLItem) i.next();
+            ACLRule item = (ACLRule) i.next();
             if(StringUtils.wildcardCheck(address.getHostName(), item._expression)) {
                 return item._allow;
             }
@@ -68,16 +119,19 @@ public class ACL {
                 return item._allow;
             }
         }
-        // what to do here?
-        // -- basically a default of deny/allow is needed
         return _defaultMode;
     }
     
-    public String getACL() {
+    /**
+     * Gets the ACL as a String for debugging.
+     *
+     * @return A String representation of this ACL.
+     */
+    public String getStringACL() {
         String acl = "";
         Iterator i = _acl.iterator();
         while(i.hasNext()) {
-            ACLItem item = (ACLItem) i.next();
+            ACLRule item = (ACLRule) i.next();
             if(item._allow) {
                 acl += "ALLOW:" + item._expression + " ";
             }
@@ -120,22 +174,47 @@ public class ACL {
      * be changed to null for utility classes.
      */
     private String _name = null;
-
+    
+    /**
+     * The ACL is stored in this LinkedList.
+     * This is ideal as the list is always searched
+     * from beginning to end in an iterative fashion.
+     */
     private LinkedList _acl = new LinkedList();
+    
+    /**
+     * The default mode of this ACL.
+     */
     private boolean _defaultMode;
 
 //---STATIC ATTRIBUTES---
 
 //---INNER CLASSES---
 
-    private class ACLItem {
+    /**
+     * Wrapper class for an ACL rule.
+     */
+    private class ACLRule {
         
-        private ACLItem(boolean allow, String expression) {
+        /**
+         * Construct an ACL rule.
+         *
+         * @param allow whether this is an ALLOW or DENY rule
+         * @param expression what this rule matches
+         */
+        private ACLRule(boolean allow, String expression) {
             _allow = allow;
             _expression = expression;
         }
         
+        /**
+         * Whether this is an ALLOW or DENY rule.
+         */
         private boolean _allow;
+        
+        /**
+         * What this rule matches.
+         */
         private String _expression;
         
     }