did some javadocs for the new security classes, now that they're pretty much

in their final form

src/com/silverwrist/venice/security/PrimordialSecurityMonitor.java

@@ -22,6 +22,14 @@ import java.util.*;
 import org.apache.log4j.*;
 import com.silverwrist.venice.except.AccessError;
 
+/**
+ * The security monitor "below the root" of the security monitor tree, which defines the three roles
+ * which are "outside the standard scopes."  Calls delegated to this instance of <CODE>SEcurityMonitor</CODE>
+ * generally fail or return <CODE>null</CODE>, except when returning the three defined roles.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public class PrimordialSecurityMonitor implements SecurityMonitor
 {
   /*--------------------------------------------------------------------------------
@@ -33,14 +41,32 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   private static Category logger = Category.getInstance(PrimordialSecurityMonitor.class);
 
-  public static final String SYM_NOT_IN_LIST = "NotInList";
+  // default human readable names
-  public static final String SYM_NO_ACCESS = "NoAccess";
-  public static final String SYM_UNRESTRICTED = "UnrestrictedUser";
-
   private static final String NAME_NOT_IN_LIST = "(not in list)";
   private static final String NAME_NO_ACCESS = "No Access";
   private static final String NAME_UNRESTRICTED = "'Unrestricted' User";
 
+  /**
+   * The programmatic name of the "not in list" defined role.
+   *
+   * @see ScopeInfo#L_NOT_THERE
+   */
+  public static final String SYM_NOT_IN_LIST = "NotInList";
+
+  /**
+   * The programmatic name of the "no access" defined role.
+   *
+   * @see ScopeInfo#L_NO_ACCESS
+   */
+  public static final String SYM_NO_ACCESS = "NoAccess";
+
+  /**
+   * The programmatic name of the "unrestricted user" defined role.
+   *
+   * @see ScopeInfo#L_UNRESTRICTED
+   */
+  public static final String SYM_UNRESTRICTED = "UnrestrictedUser";
+
   /*--------------------------------------------------------------------------------
    * Attributes
    *--------------------------------------------------------------------------------
@@ -55,6 +81,9 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new instance of this object.  Only one is ever created.
+   */
   private PrimordialSecurityMonitor()
   {
     String name_not_in_list = null, name_no_access = null, name_unrestricted_user = null;
@@ -89,6 +118,21 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is less
+   * than the defined security level for this permission, an exception is thrown.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always throws this exception.)
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @param errormsg The error message to be thrown if the test fails.  May be <CODE>null</CODE>, in
+   *                 which case the security monitor will throw an appropriate default, if applicable.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor.
+   * @exception com.silverwrist.venice.except.AccessError If the specified permission was defined but
+   *            not satisfied.  (Always thrown by <CODE>PrimordialSecurityMonitor</CDOE>.)
+   * @see #testPermission(java.lang.String,int)
+   */
   public boolean testPermission(String symbol, int level, String errormsg) throws AccessError
   {
     if (symbol==null)
@@ -98,6 +142,18 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end testPermission
 
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is greater
+   * than or equal to the defined security level for this permission, <CODE>true</CODE> is returned.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>false</CODE>.)
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor, or was defined but
+   *         not satisfied.  (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>false</CODE>.)
+   * @see #testPermission(java.lang.String,int,java.lang.String)
+   */
   public boolean testPermission(String symbol, int level)
   {
     if (symbol==null)
@@ -107,6 +163,17 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end testPermission
 
+  /**
+   * Determines whether this <CODE>SecurityMonitor</CODE> defines the specified permission symbol.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>false</CODE>.)
+   *
+   * @param symbol The programmatic symbol of the permission to look up.
+   * @param no_follow If this is <CODE>true</CODE>, we look only in this <CODE>SecurityMonitor</CODE>
+   *                  for the specified permission, and not in any "parent" <CODE>SecurityMonitor</CODE>
+   *                  objects.
+   * @return <CODE>true</CODE> if this is a defined permission symbol, <CODE>false</CODE> if not.
+   *         (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>false</CODE>.)
+   */
   public boolean permissionDefined(String symbol, boolean no_follow)
   {
     if (symbol==null)
@@ -115,6 +182,15 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end permissionDefined
 
+  /**
+   * Returns a defined list of roles for this <CODE>SecurityMonitor</CODE>.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   *
+   * @param symbol The programmatic symbol of the role list to look up.
+   * @return The associated role list, or <CODE>null</CODE> if the role list name was not defined.
+   *         (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   * @see Role
+   */
   public List getRoleList(String symbol)
   {
     if (symbol==null)
@@ -124,6 +200,13 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end getRoleList
 
+  /**
+   * Returns a defined role for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the role name was not defined.
+   * @see Role
+   */
   public Role getRole(String symbol)
   {
     if (symbol==null)
@@ -139,6 +222,13 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end getRole
 
+  /**
+   * Returns the defined role that has the given level.
+   *
+   * @param level The level value to look up.
+   * @return The associated role, or <CODE>null</CODE> if no such role could be found.
+   * @see Role
+   */
   public Role getRoleForLevel(int level)
   {
     if (level==ScopeInfo.L_NOT_THERE)
@@ -152,6 +242,15 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end getRoleForLevel
 
+  /**
+   * Returns a defined default role for this <CODE>SecurityMonitor</CODE>.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   *
+   * @param symbol The programmatic symbol of the default role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the default role name was not defined.
+   *         (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   * @see Role
+   */
   public Role getDefaultRole(String symbol)
   {
     logger.error("getDefaultRole: symbol \"" + symbol + "\" has no default role");
@@ -159,12 +258,27 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
 
   } // end getDefaultRole
 
+  /**
+   * Returns the <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   * (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   *
+   * @return The <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   *         (<CODE>PrimordialSecurityMonitor</CODE> always returns <CODE>null</CODE>.)
+   * @see ScopeInfo
+   */
   public ScopeInfo getScopeInfo()
   {
     return null;  // this security monitor HAS no scope
 
   } // end getScopeInfo
 
+  /**
+   * Returns the identifier for this <CODE>SecurityMonitor</CODE>. (<CODE>PrimordialSecurityMonitor</CODE>
+   * always returns <CODE>null</CODE>.)
+   *
+   * @return The identifier for this <CODE>SecurityMonitor</CODE>. (<CODE>PrimordialSecurityMonitor</CODE>
+   *         always returns <CODE>null</CODE>.)
+   */
   public String getID()
   {
     return null;  // this security monitor HAS no ID
@@ -176,6 +290,11 @@ public class PrimordialSecurityMonitor implements SecurityMonitor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the singleton instance of the <CODE>PrimordialSecurityMonitor</CODE>.
+   *
+   * @return The singleton instance of the <CODE>PrimordialSecurityMonitor</CODE>.
+   */
   public static synchronized SecurityMonitor get()
   {
     if (self==null)

src/com/silverwrist/venice/security/Role.java

@@ -19,6 +19,26 @@ package com.silverwrist.venice.security;
 
 import java.util.*;
 
+/**
+ * Represents a security role for a user within the Venice architecture.<P>
+ * Venice uses a system of scoped security roles to govern access to various features.  Each role
+ * has associated with it a <EM>security level</EM>, which is nominally a 16-bit unsigned integer
+ * (but is represented in Java as an <CODE>int</CODE>).  Each access permission also has associated
+ * with it an access level; if the user's granted level is greater than or equal to the access level,
+ * access is granted.<P>
+ * Access levels are arranged in <EM>scopes</EM>; if an object is logically contained within another
+ * object, then its scope is greater than that of the containing object.  The system itself has
+ * scope 0; communities use scope 3 by default; objects such as conferences (within communities) are
+ * at scope 6.  The scope system is described further in {@link ScopeInfo}.<P>
+ * Each role also has associated with it a human-readable name and a programmatic symbol.  The symbol
+ * will usually be of the form "<EM>subsystem.name</EM>," such as "Global.Normal," "Community.Host,"
+ * or "Conference.Member."<P>
+ * Roles are created as part of a {@link SecurityMonitor}, such as {@link StaticSecurityMonitor}, and
+ * are managed by it.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public final class Role implements Comparable, Cloneable
 {
   /*--------------------------------------------------------------------------------
@@ -35,14 +55,14 @@ public final class Role implements Comparable, Cloneable
    *--------------------------------------------------------------------------------
    */
 
-  protected Role(int level, String name)
+  /**
-  {
+   * Creates a new instance of a <CODE>Role</CODE> object.
-    this.level = level;
+   *
-    this.name = name;
+   * @param level The level to encode in this role.
-    this.symbol = null;
+   * @param name The human-readable name of the role.
-
+   * @param symbol The programmatic symbol of the role.
-  } // end constructor
+   * @see #create(int,java.lang.String,java.lang.String)
-
+   */
   protected Role(int level, String name, String symbol)
   {
     this.level = level;
@@ -56,6 +76,13 @@ public final class Role implements Comparable, Cloneable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Tests this object for equality with another object.  Two <CODE>Role</CODE> objects are equivalent
+   * iff the levels that they enclose are equal.
+   *
+   * @param obj The other object to compare to this one.
+   * @return <CODE>true</CODE> if the two objects are equal.
+   */
   public boolean equals(Object obj)
   {
     if (obj==null)
@@ -73,18 +100,28 @@ public final class Role implements Comparable, Cloneable
 
   } // end equals
 
+  /**
+   * Returns a hash code that can be used as an index for this object in a hash table.  In keeping
+   * with the definition of <CODE>equals</CODE>, a <CODE>Role</CODE>'s hash code is its level.
+   *
+   * @return The hash code for this object.
+   * @see #equals(java.lang.Object)
+   */
   public int hashCode()
   {
     return level;
 
   } // end hashCode
 
+  /**
+   * Returns a "debugging" string equivalent for this role.
+   *
+   * @return The string equivalent for this role.
+   */
   public String toString()
   {
     StringBuffer buf = new StringBuffer(name);
-    buf.append('[').append(level).append(']');
+    buf.append('[').append(level).append("]{").append(symbol).append('}');
-    if (symbol!=null)
-      buf.append('{').append(symbol).append('}');
     return buf.toString();
 
   } // end toString
@@ -94,6 +131,16 @@ public final class Role implements Comparable, Cloneable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Compares one <CODE>Role</CODE> object to another.  A <CODE>Role</CODE> is logically less
+   * than another one if its enclosed level is less than the other one's enclosed level.
+   *
+   * @param obj The other role object to compare to.
+   * @return A value less than 0 if this <CODE>Role</CODE> is logically "less than" the specified one; a
+   *         value greater than 0 if this <CODE>Role</CODE> is logically "greater than" the other one; 0 if
+   *         the two are equal.
+   * @exception java.lang.ClassCastException If <CODE>obj</CODE> is not a <CODE>Role</CODE> object.
+   */
   public int compareTo(Object obj)
   {
     if (obj==null)
@@ -110,24 +157,47 @@ public final class Role implements Comparable, Cloneable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the security level associated with this <CODE>Role</CODE>.
+   *
+   * @return The security level associated with this <CODE>Role</CODE>.
+   */
   public final int getLevel()
   {
     return level;
 
   } // end getLevel
 
+  /**
+   * Returns the human-readable name associated with this <CODE>Role</CODE>.
+   *
+   * @return The human-readable name associated with this <CODE>Role</CODE>.
+   */
   public final String getName()
   {
     return name;
 
   } // end getName
 
+  /**
+   * Returns the programmatic symbol associated with this <CODE>Role</CODE>.
+   *
+   * @return The programmatic symbol associated with this <CODE>Role</CODE>.
+   */
   public final String getSymbol()
   {
     return symbol;
 
   } // end getSymbol
 
+  /**
+   * Returns <CODE>true</CODE> if the capability associated with this <CODE>Role</CODE> would
+   * be satisfied by the specified security level, i.e. the parameter is greater than or equal to
+   * the level associated with this role.
+   *
+   * @param l The level to test against this <CODE>Role</CODE>.
+   * @return <CODE>true</CODE> if the role is satisfied by this level.
+   */
   public final boolean isSatisfiedBy(int l)
   {
     return (l>=level);
@@ -139,6 +209,14 @@ public final class Role implements Comparable, Cloneable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new <CODE>Role</CODE>.
+   *
+   * @param level The level to encode in this role.
+   * @param name The human-readable name of the role.
+   * @param symbol The programmatic symbol of the role.
+   * @return The new associated <CODE>Role</CODE> object.
+   */
   static final Role create(int level, String name, String symbol)
   {
     return new Role(level,name,symbol);

src/com/silverwrist/venice/security/ScopeInfo.java

@@ -17,6 +17,25 @@
  */
 package com.silverwrist.venice.security;
 
+/**
+ * The information that represents a single security "scope" within Venice.  A security "scope"
+ * defines two subranges of the 16-bit range for security levels, the "lowband" range and the "highband"
+ * range.  Scopes are numbered from 0 to 15; for any pair of scopes, <EM>x</EM> and <EM>y</EM>, if
+ * <EM>x&lt;y</EM>, that means that all values in the lowband of scope <EM>x</EM> are less than all
+ * values in the lowband of scope <EM>y</EM>, and all values in the highband of scope <EM>x</EM> are
+ * greater than all values in the highband of scope <EM>y</EM>.  In general, security scopes with
+ * higher indexes are used for more specific objects.  The system itself, for instance, uses scope 0;
+ * communities use scope 3; conferences and other objects inside communities use scope 6.<P>
+ * Three levels are defined that are outside the scope system: the "not in list" value, which is defined
+ * as the (integer) value -1; the "no access" value, which is greater than any value in the lowband or
+ * highband of any scope; and the "unrestricted user" value, which is greater than any value in the lowband
+ * of any scope, but less than any value in the highband of any scope.  (Administrator levels are generally
+ * defined within the highband of their scope, allowing administrators to exert control over any enclosed
+ * objects as well.)
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public final class ScopeInfo implements Cloneable, Comparable
 {
   /*--------------------------------------------------------------------------------
@@ -37,11 +56,25 @@ public final class ScopeInfo implements Cloneable, Comparable
       { 64999, 62999, 60999, 58999, 56999, 54999, 52999, 50999, 48999, 46999, 44999, 42999, 40999, 38999,
 	36999, 34999 };
 
-  public static final int L_NOT_THERE = -1;         // global "not there" constant
+  /**
-  public static final int L_UNRESTRICTED = 32500;   // global "unrestricted user" constant
+   * The defined "not there" value.
-  public static final int L_NO_ACCESS = 65500;      // global "no access" constant
+   */
+  public static final int L_NOT_THERE = -1;
 
-  public static final int BAND_WIDTH = 1999;        // offset between "high and low" values within a band
+  /**
+   * The defined "unrestricted user" value.
+   */
+  public static final int L_UNRESTRICTED = 32500;
+
+  /**
+   * The defined "no access" value.
+   */
+  public static final int L_NO_ACCESS = 65500;
+
+  /**
+   * A value which represents the difference between the low end and high end of a single band.
+   */
+  public static final int BAND_WIDTH = 1999;
 
   /*--------------------------------------------------------------------------------
    * Attributes
@@ -55,6 +88,13 @@ public final class ScopeInfo implements Cloneable, Comparable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new <CODE>ScopeInfo</CODE> object.
+   *
+   * @param scope The scope value.
+   * @exception java.lang.IndexOutOfBoundsException The given scope value is out of range.  It must be
+   *            between 0 and 15.
+   */
   public ScopeInfo(int scope)
   {
     if ((scope<0) || (scope>=LB_LOW.length))
@@ -68,6 +108,13 @@ public final class ScopeInfo implements Cloneable, Comparable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Tests this object for equality with another object.  Two <CODE>ScopeInfo</CODE> objects are equivalent
+   * iff the scopes that they enclose are equal.
+   *
+   * @param obj The other object to compare to this one.
+   * @return <CODE>true</CODE> if the two objects are equal.
+   */
   public boolean equals(Object o)
   {
     if ((o==null) || !(o instanceof ScopeInfo))
@@ -77,12 +124,24 @@ public final class ScopeInfo implements Cloneable, Comparable
 
   } // end equals
 
+  /**
+   * Returns a hash code that can be used as an index for this object in a hash table.  In keeping
+   * with the definition of <CODE>equals</CODE>, a <CODE>ScopeInfo</CODE>'s hash code is its scope.
+   *
+   * @return The hash code for this object.
+   * @see #equals(java.lang.Object)
+   */
   public int hashCode()
   {
     return scope;
 
   } // end hashCode
 
+  /**
+   * Returns a "debugging" string equivalent for this <CODE>ScopeInfo</CODE>.
+   *
+   * @return The string equivalent for this <CODE>ScopeInfo</CODE>.
+   */
   public String toString()
   {
     StringBuffer buf = new StringBuffer("{ScopeInfo(");
@@ -97,6 +156,16 @@ public final class ScopeInfo implements Cloneable, Comparable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Compares one <CODE>ScopeInfo</CODE> object to another.  A <CODE>ScopeInfo</CODE> is logically less
+   * than another one if its scope is less than the other one's scope.
+   *
+   * @param obj The other <CODE>ScopeInfo</CODE> object to compare to.
+   * @return A value less than 0 if this <CODE>ScopeInfo</CODE> is logically "less than" the specified one; a
+   *         value greater than 0 if this <CODE>ScopeInfo</CODE> is logically "greater than" the other one;
+   *         0 if the two are equal.
+   * @exception java.lang.ClassCastException If <CODE>obj</CODE> is not a <CODE>ScopeInfo</CODE> object.
+   */
   public int compareTo(Object o)
   {
     if (o==null)
@@ -111,39 +180,75 @@ public final class ScopeInfo implements Cloneable, Comparable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the scope associated with this <CODE>ScopeInfo</CODE> object.
+   *
+   * @return The scope associated with this <CODE>ScopeInfo</CODE> object.
+   */
   public final int getScope()
   {
     return scope;
 
   } // end getScope
 
+  /**
+   * Returns the lower limit of the lowband of this scope.
+   *
+   * @return The lower limit of the lowband of this scope.
+   */
   public final int getLowBandLow()
   {
     return LB_LOW[scope];
 
   } // end getLowBandLow
 
+  /**
+   * Returns the upper limit of the lowband of this scope.
+   *
+   * @return The upper limit of the lowband of this scope.
+   */
   public final int getLowBandHigh()
   {
     return LB_HIGH[scope];
 
   } // end getLowBandHigh
 
+  /**
+   * Returns the lower limit of the highband of this scope.
+   *
+   * @return The lower limit of the highband of this scope.
+   */
   public final int getHighBandLow()
   {
     return HB_LOW[scope];
 
   } // end getHighBandLow
 
+  /**
+   * Returns the upper limit of the highband of this scope.
+   *
+   * @return The upper limit of the highband of this scope.
+   */
   public final int getHighBandHigh()
   {
     return HB_HIGH[scope];
 
   } // end getHighBandHigh
 
+  /**
+   * Computes a new level within the scope.
+   *
+   * @param highband <CODE>true</CODE> to return a value within the highband of this scope, <CODE>false</CODE>
+   *                 to return a value within a lowband of this scope.
+   * @param offset Offset from the lower limit of the band.  If this value is negative, it is viewed as
+   *               an offset from the upper limit of the band.
+   * @return The computed level.
+   * @exception java.lang.IllegalArgumentException If the computed level would be outside this scope.
+   */
   public final int getLevel(boolean highband, int offset)
   {
-    int rc;
+    int rc;  // return from this method
+
     if (highband)
     { // it's in the highband
       if (offset<0)
@@ -185,6 +290,13 @@ public final class ScopeInfo implements Cloneable, Comparable
 
   } // end getLevel
 
+  /**
+   * Returns <CODE>true</CODE> if the specified level represents a value within this scope,
+   * <CODE>false</CODE> if not.
+   *
+   * @param value The level value to be tested.
+   * @return <CODE>true</CODE> if the specified level represents a value within this scope.
+   */
   public final boolean isInScope(int value)
   {
     if ((value>=LB_LOW[scope]) && (value<=LB_HIGH[scope]))
@@ -200,12 +312,25 @@ public final class ScopeInfo implements Cloneable, Comparable
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns <CODE>true</CODE> if the specified index represents a valid scope, <CODE>false</CODE> if not.
+   *
+   * @param s The scope index to be tested.
+   * @return <CODE>true</CODE> if the specified index represents a valid scope.
+   */
   public static final boolean isValidScope(int s)
   {
     return ((s>=0) && (s<LB_LOW.length));
 
   } // end isValidScope
 
+  /**
+   * Given a level value, returns the index of the scope that would contain it.
+   *
+   * @param value The level value to be tested.
+   * @return The index of the scope that contains this level.  If this value lies outside any scope,
+   *         returns -1.
+   */
   public static final int getScopeOf(int value)
   {
     if ((value<LB_LOW[0]) || (value>HB_HIGH[0]))

src/com/silverwrist/venice/security/SecurityMonitor.java

@@ -20,24 +20,105 @@ package com.silverwrist.venice.security;
 import java.util.List;
 import com.silverwrist.venice.except.AccessError;
 
+/**
+ * Defines a service interface for a <EM>security monitor</EM>.  A security monitor is specific to a
+ * particular type of object within Venice, and defines the security scope used to deal with that
+ * object, the roles used, lists of roles, default role values, and permissions that may be tested.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface SecurityMonitor
 {
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is less
+   * than the defined security level for this permission, an exception is thrown.
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @param errormsg The error message to be thrown if the test fails.  May be <CODE>null</CODE>, in
+   *                 which case the security monitor will throw an appropriate default, if applicable.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor.
+   * @exception com.silverwrist.venice.except.AccessError If the specified permission was defined but
+   *            not satisfied.
+   * @see #testPermission(java.lang.String,int)
+   */
   public abstract boolean testPermission(String symbol, int level, String errormsg) throws AccessError;
 
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is greater
+   * than or equal to the defined security level for this permission, <CODE>true</CODE> is returned.
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor, or was defined but
+   *         not satisfied.
+   * @see #testPermission(java.lang.String,int,java.lang.String)
+   */
   public abstract boolean testPermission(String symbol, int level);
 
+  /**
+   * Determines whether this <CODE>SecurityMonitor</CODE> defines the specified permission symbol.
+   *
+   * @param symbol The programmatic symbol of the permission to look up.
+   * @param no_follow If this is <CODE>true</CODE>, we look only in this <CODE>SecurityMonitor</CODE>
+   *                  for the specified permission, and not in any "parent" <CODE>SecurityMonitor</CODE>
+   *                  objects.
+   * @return <CODE>true</CODE> if this is a defined permission symbol, <CODE>false</CODE> if not.
+   */
   public abstract boolean permissionDefined(String symbol, boolean no_follow);
 
+  /**
+   * Returns a defined list of roles for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the role list to look up.
+   * @return The associated role list, or <CODE>null</CODE> if the role list name was not defined.
+   * @see Role
+   */
   public abstract List getRoleList(String symbol);
 
+  /**
+   * Returns a defined role for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the role name was not defined.
+   * @see Role
+   */
   public abstract Role getRole(String symbol);
 
+  /**
+   * Returns the defined role that has the given level.
+   *
+   * @param level The level value to look up.
+   * @return The associated role, or <CODE>null</CODE> if no such role could be found.
+   * @see Role
+   */
   public abstract Role getRoleForLevel(int level);
 
+  /**
+   * Returns a defined default role for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the default role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the default role name was not defined.
+   * @see Role
+   */
   public abstract Role getDefaultRole(String symbol);
 
+  /**
+   * Returns the <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   *
+   * @return The <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   * @see ScopeInfo
+   */
   public abstract ScopeInfo getScopeInfo();
 
+  /**
+   * Returns the identifier for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @return The identifier for this <CODE>SecurityMonitor</CODE>.
+   */
   public abstract String getID();
 
 } // end interface SecurityMonitor

src/com/silverwrist/venice/security/StaticSecurityMonitor.java

@@ -24,6 +24,14 @@ import com.silverwrist.util.DOMElementHelper;
 import com.silverwrist.venice.except.AccessError;
 import com.silverwrist.venice.except.ConfigException;
 
+/**
+ * A <CODE>SecurityMonitor</CODE> which is configured by means of XML data, supplied by means of a Venice
+ * configuration file.  The configuration file defines roles, role lists, defaults, and permissions within
+ * the security monitor's scope.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public class StaticSecurityMonitor implements SecurityMonitor
 {
   /*--------------------------------------------------------------------------------
@@ -33,8 +41,8 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   final class StaticPermission
   {
-    private Role role;
+    private Role role;           // the role for the test
-    private String message;
+    private String message;      // the failure message
 
     StaticPermission(Role role, String message)
     {
@@ -98,6 +106,14 @@ public class StaticSecurityMonitor implements SecurityMonitor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Creates a new <CODE>StaticSecurityMonitor</CODE> from information stored as XML in a configuration file.
+   *
+   * @param cfg The root element of the security monitor configuration, which must be a
+   *            <CODE>&lt;security-definition/&gt;</CODE> element.
+   * @exception com.silverwrist.venice.except.ConfigException The XML configuration data was incorrect in
+   *            some fashion.
+   */
   public StaticSecurityMonitor(Element cfg) throws ConfigException
   {
     boolean set_root_monitor = false;
@@ -605,6 +621,20 @@ public class StaticSecurityMonitor implements SecurityMonitor
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is less
+   * than the defined security level for this permission, an exception is thrown.
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @param errormsg The error message to be thrown if the test fails.  May be <CODE>null</CODE>, in
+   *                 which case the security monitor will throw an appropriate default, if applicable.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor.
+   * @exception com.silverwrist.venice.except.AccessError If the specified permission was defined but
+   *            not satisfied.
+   * @see #testPermission(java.lang.String,int)
+   */
   public boolean testPermission(String symbol, int level, String errormsg) throws AccessError
   {
     if (symbol==null)
@@ -625,6 +655,17 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end testPermission
 
+  /**
+   * Tests a specified permission within this security monitor.  If the supplied security level is greater
+   * than or equal to the defined security level for this permission, <CODE>true</CODE> is returned.
+   *
+   * @param symbol The programmatic symbol of the permission to test.
+   * @param level The security level to supply for the test.
+   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
+   *         if the specified permission was not defined within this security monitor, or was defined but
+   *         not satisfied.
+   * @see #testPermission(java.lang.String,int,java.lang.String)
+   */
   public boolean testPermission(String symbol, int level)
   {
     if (symbol==null)
@@ -644,6 +685,15 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end testPermission
 
+  /**
+   * Determines whether this <CODE>SecurityMonitor</CODE> defines the specified permission symbol.
+   *
+   * @param symbol The programmatic symbol of the permission to look up.
+   * @param no_follow If this is <CODE>true</CODE>, we look only in this <CODE>SecurityMonitor</CODE>
+   *                  for the specified permission, and not in any "parent" <CODE>SecurityMonitor</CODE>
+   *                  objects.
+   * @return <CODE>true</CODE> if this is a defined permission symbol, <CODE>false</CODE> if not.
+   */
   public boolean permissionDefined(String symbol, boolean no_follow)
   {
     if (symbol==null)
@@ -656,6 +706,13 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end permissionDefined
 
+  /**
+   * Returns a defined list of roles for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the role list to look up.
+   * @return The associated role list, or <CODE>null</CODE> if the role list name was not defined.
+   * @see Role
+   */
   public List getRoleList(String symbol)
   {
     if (symbol==null)
@@ -667,6 +724,13 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end getRoleList
 
+  /**
+   * Returns a defined role for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the role name was not defined.
+   * @see Role
+   */
   public Role getRole(String symbol)
   {
     if (symbol==null)
@@ -678,6 +742,13 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end getRole
 
+  /**
+   * Returns the defined role that has the given level.
+   *
+   * @param level The level value to look up.
+   * @return The associated role, or <CODE>null</CODE> if no such role could be found.
+   * @see Role
+   */
   public Role getRoleForLevel(int level)
   {
     Role rc = (Role)(level_to_role.get(new Integer(level)));
@@ -687,6 +758,13 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end getRoleForLevel
 
+  /**
+   * Returns a defined default role for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @param symbol The programmatic symbol of the default role to look up.
+   * @return The associated role, or <CODE>null</CODE> if the default role name was not defined.
+   * @see Role
+   */
   public Role getDefaultRole(String symbol)
   {
     if (symbol==null)
@@ -698,12 +776,23 @@ public class StaticSecurityMonitor implements SecurityMonitor
 
   } // end getDefaultRole
 
+  /**
+   * Returns the <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   *
+   * @return The <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
+   * @see ScopeInfo
+   */
   public ScopeInfo getScopeInfo()
   {
     return scope;
 
   } // end getScopeInfo
 
+  /**
+   * Returns the identifier for this <CODE>SecurityMonitor</CODE>.
+   *
+   * @return The identifier for this <CODE>SecurityMonitor</CODE>.
+   */
   public String getID()
   {
     return id;