diff --git a/src/com/silverwrist/venice/security/PrimordialSecurityMonitor.java b/src/com/silverwrist/venice/security/PrimordialSecurityMonitor.java index 4fca6f2..795553d 100644 --- a/src/com/silverwrist/venice/security/PrimordialSecurityMonitor.java +++ b/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 SEcurityMonitor + * generally fail or return null, except when returning the three defined roles. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @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"; - public static final String SYM_NO_ACCESS = "NoAccess"; - public static final String SYM_UNRESTRICTED = "UnrestrictedUser"; - + // default human readable names 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. + * (PrimordialSecurityMonitor 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 null, in + * which case the security monitor will throw an appropriate default, if applicable. + * @return true if the specified permission was defined and satisfied; false + * 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 PrimordialSecurityMonitor.) + * @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, true is returned. + * (PrimordialSecurityMonitor always returns false.) + * + * @param symbol The programmatic symbol of the permission to test. + * @param level The security level to supply for the test. + * @return true if the specified permission was defined and satisfied; false + * if the specified permission was not defined within this security monitor, or was defined but + * not satisfied. (PrimordialSecurityMonitor always returns false.) + * @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 SecurityMonitor defines the specified permission symbol. + * (PrimordialSecurityMonitor always returns false.) + * + * @param symbol The programmatic symbol of the permission to look up. + * @param no_follow If this is true, we look only in this SecurityMonitor + * for the specified permission, and not in any "parent" SecurityMonitor + * objects. + * @return true if this is a defined permission symbol, false if not. + * (PrimordialSecurityMonitor always returns false.) + */ 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 SecurityMonitor. + * (PrimordialSecurityMonitor always returns null.) + * + * @param symbol The programmatic symbol of the role list to look up. + * @return The associated role list, or null if the role list name was not defined. + * (PrimordialSecurityMonitor always returns null.) + * @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 SecurityMonitor. + * + * @param symbol The programmatic symbol of the role to look up. + * @return The associated role, or null 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 null 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 SecurityMonitor. + * (PrimordialSecurityMonitor always returns null.) + * + * @param symbol The programmatic symbol of the default role to look up. + * @return The associated role, or null if the default role name was not defined. + * (PrimordialSecurityMonitor always returns null.) + * @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 ScopeInfo associated with this SecurityMonitor. + * (PrimordialSecurityMonitor always returns null.) + * + * @return The ScopeInfo associated with this SecurityMonitor. + * (PrimordialSecurityMonitor always returns null.) + * @see ScopeInfo + */ public ScopeInfo getScopeInfo() { return null; // this security monitor HAS no scope } // end getScopeInfo + /** + * Returns the identifier for this SecurityMonitor. (PrimordialSecurityMonitor + * always returns null.) + * + * @return The identifier for this SecurityMonitor. (PrimordialSecurityMonitor + * always returns null.) + */ 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 PrimordialSecurityMonitor. + * + * @return The singleton instance of the PrimordialSecurityMonitor. + */ public static synchronized SecurityMonitor get() { if (self==null) diff --git a/src/com/silverwrist/venice/security/Role.java b/src/com/silverwrist/venice/security/Role.java index f887bb1..07bc044 100644 --- a/src/com/silverwrist/venice/security/Role.java +++ b/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.

+ * Venice uses a system of scoped security roles to govern access to various features. Each role + * has associated with it a security level, which is nominally a 16-bit unsigned integer + * (but is represented in Java as an int). 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.

+ * Access levels are arranged in scopes; 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}.

+ * Each role also has associated with it a human-readable name and a programmatic symbol. The symbol + * will usually be of the form "subsystem.name," such as "Global.Normal," "Community.Host," + * or "Conference.Member."

+ * Roles are created as part of a {@link SecurityMonitor}, such as {@link StaticSecurityMonitor}, and + * are managed by it. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @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) - { - this.level = level; - this.name = name; - this.symbol = null; - - } // end constructor - + /** + * Creates a new instance of a Role object. + * + * @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. + * @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 Role objects are equivalent + * iff the levels that they enclose are equal. + * + * @param obj The other object to compare to this one. + * @return true 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 equals, a Role'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(']'); - if (symbol!=null) - buf.append('{').append(symbol).append('}'); + buf.append('[').append(level).append("]{").append(symbol).append('}'); return buf.toString(); } // end toString @@ -94,6 +131,16 @@ public final class Role implements Comparable, Cloneable *-------------------------------------------------------------------------------- */ + /** + * Compares one Role object to another. A Role 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 Role is logically "less than" the specified one; a + * value greater than 0 if this Role is logically "greater than" the other one; 0 if + * the two are equal. + * @exception java.lang.ClassCastException If obj is not a Role 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 Role. + * + * @return The security level associated with this Role. + */ public final int getLevel() { return level; } // end getLevel + /** + * Returns the human-readable name associated with this Role. + * + * @return The human-readable name associated with this Role. + */ public final String getName() { return name; } // end getName + /** + * Returns the programmatic symbol associated with this Role. + * + * @return The programmatic symbol associated with this Role. + */ public final String getSymbol() { return symbol; } // end getSymbol + /** + * Returns true if the capability associated with this Role 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 Role. + * @return true 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 Role. + * + * @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 Role object. + */ static final Role create(int level, String name, String symbol) { return new Role(level,name,symbol); diff --git a/src/com/silverwrist/venice/security/ScopeInfo.java b/src/com/silverwrist/venice/security/ScopeInfo.java index 5127380..295fe20 100644 --- a/src/com/silverwrist/venice/security/ScopeInfo.java +++ b/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, x and y, if + * x<y, that means that all values in the lowband of scope x are less than all + * values in the lowband of scope y, and all values in the highband of scope x are + * greater than all values in the highband of scope y. 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.

+ * 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 <erbo@silcom.com> + * @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 - public static final int L_NO_ACCESS = 65500; // global "no access" constant + /** + * The defined "not there" value. + */ + 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 ScopeInfo 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 ScopeInfo objects are equivalent + * iff the scopes that they enclose are equal. + * + * @param obj The other object to compare to this one. + * @return true 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 equals, a ScopeInfo'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 ScopeInfo. + * + * @return The string equivalent for this ScopeInfo. + */ public String toString() { StringBuffer buf = new StringBuffer("{ScopeInfo("); @@ -97,6 +156,16 @@ public final class ScopeInfo implements Cloneable, Comparable *-------------------------------------------------------------------------------- */ + /** + * Compares one ScopeInfo object to another. A ScopeInfo is logically less + * than another one if its scope is less than the other one's scope. + * + * @param obj The other ScopeInfo object to compare to. + * @return A value less than 0 if this ScopeInfo is logically "less than" the specified one; a + * value greater than 0 if this ScopeInfo is logically "greater than" the other one; + * 0 if the two are equal. + * @exception java.lang.ClassCastException If obj is not a ScopeInfo 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 ScopeInfo object. + * + * @return The scope associated with this ScopeInfo 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 true to return a value within the highband of this scope, false + * 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 true if the specified level represents a value within this scope, + * false if not. + * + * @param value The level value to be tested. + * @return true 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 true if the specified index represents a valid scope, false if not. + * + * @param s The scope index to be tested. + * @return true if the specified index represents a valid scope. + */ public static final boolean isValidScope(int s) { return ((s>=0) && (sHB_HIGH[0])) diff --git a/src/com/silverwrist/venice/security/SecurityMonitor.java b/src/com/silverwrist/venice/security/SecurityMonitor.java index c483997..1209457 100644 --- a/src/com/silverwrist/venice/security/SecurityMonitor.java +++ b/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 security monitor. 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 <erbo@silcom.com> + * @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 null, in + * which case the security monitor will throw an appropriate default, if applicable. + * @return true if the specified permission was defined and satisfied; false + * 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, true is returned. + * + * @param symbol The programmatic symbol of the permission to test. + * @param level The security level to supply for the test. + * @return true if the specified permission was defined and satisfied; false + * 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 SecurityMonitor defines the specified permission symbol. + * + * @param symbol The programmatic symbol of the permission to look up. + * @param no_follow If this is true, we look only in this SecurityMonitor + * for the specified permission, and not in any "parent" SecurityMonitor + * objects. + * @return true if this is a defined permission symbol, false if not. + */ public abstract boolean permissionDefined(String symbol, boolean no_follow); + /** + * Returns a defined list of roles for this SecurityMonitor. + * + * @param symbol The programmatic symbol of the role list to look up. + * @return The associated role list, or null if the role list name was not defined. + * @see Role + */ public abstract List getRoleList(String symbol); + /** + * Returns a defined role for this SecurityMonitor. + * + * @param symbol The programmatic symbol of the role to look up. + * @return The associated role, or null 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 null if no such role could be found. + * @see Role + */ public abstract Role getRoleForLevel(int level); + /** + * Returns a defined default role for this SecurityMonitor. + * + * @param symbol The programmatic symbol of the default role to look up. + * @return The associated role, or null if the default role name was not defined. + * @see Role + */ public abstract Role getDefaultRole(String symbol); + /** + * Returns the ScopeInfo associated with this SecurityMonitor. + * + * @return The ScopeInfo associated with this SecurityMonitor. + * @see ScopeInfo + */ public abstract ScopeInfo getScopeInfo(); + /** + * Returns the identifier for this SecurityMonitor. + * + * @return The identifier for this SecurityMonitor. + */ public abstract String getID(); } // end interface SecurityMonitor diff --git a/src/com/silverwrist/venice/security/StaticSecurityMonitor.java b/src/com/silverwrist/venice/security/StaticSecurityMonitor.java index 6a3f99d..c8c5a79 100644 --- a/src/com/silverwrist/venice/security/StaticSecurityMonitor.java +++ b/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 SecurityMonitor 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 <erbo@silcom.com> + * @version X + */ public class StaticSecurityMonitor implements SecurityMonitor { /*-------------------------------------------------------------------------------- @@ -33,8 +41,8 @@ public class StaticSecurityMonitor implements SecurityMonitor final class StaticPermission { - private Role role; - private String message; + private Role role; // the role for the test + private String message; // the failure message StaticPermission(Role role, String message) { @@ -98,6 +106,14 @@ public class StaticSecurityMonitor implements SecurityMonitor *-------------------------------------------------------------------------------- */ + /** + * Creates a new StaticSecurityMonitor from information stored as XML in a configuration file. + * + * @param cfg The root element of the security monitor configuration, which must be a + * <security-definition/> 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 null, in + * which case the security monitor will throw an appropriate default, if applicable. + * @return true if the specified permission was defined and satisfied; false + * 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, true is returned. + * + * @param symbol The programmatic symbol of the permission to test. + * @param level The security level to supply for the test. + * @return true if the specified permission was defined and satisfied; false + * 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 SecurityMonitor defines the specified permission symbol. + * + * @param symbol The programmatic symbol of the permission to look up. + * @param no_follow If this is true, we look only in this SecurityMonitor + * for the specified permission, and not in any "parent" SecurityMonitor + * objects. + * @return true if this is a defined permission symbol, false 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 SecurityMonitor. + * + * @param symbol The programmatic symbol of the role list to look up. + * @return The associated role list, or null 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 SecurityMonitor. + * + * @param symbol The programmatic symbol of the role to look up. + * @return The associated role, or null 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 null 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 SecurityMonitor. + * + * @param symbol The programmatic symbol of the default role to look up. + * @return The associated role, or null 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 ScopeInfo associated with this SecurityMonitor. + * + * @return The ScopeInfo associated with this SecurityMonitor. + * @see ScopeInfo + */ public ScopeInfo getScopeInfo() { return scope; } // end getScopeInfo + /** + * Returns the identifier for this SecurityMonitor. + * + * @return The identifier for this SecurityMonitor. + */ public String getID() { return id;