added community getJoinRequirement and did some more documentation work

elsewhere

build.xml

@@ -429,7 +429,8 @@
   <target name="javadoc">
     <mkdir dir="javadocs"/>
     <javadoc destdir="javadocs" access="package" source="1.4"
-             packagenames="com.silverwrist.util.*,com.silverwrist.dynamo.*,com.silverwrist.venice.*">
+             packagenames="com.silverwrist.util.*,com.silverwrist.dynamo.*,com.silverwrist.venice.*"
+             windowtitle="Venice Web Communities System">
       <sourcepath>
         <pathelement location="src/baseutil"/>
         <pathelement location="src/dynamo-framework"/>
@@ -438,6 +439,12 @@
       <classpath>
         <path refid="base.build.path"/>
       </classpath>
+      <group title="Base Utility Packages" packages="com.silverwrist.util:com.silverwrist.util.*"/>
+      <group title="Low-Level Dynamo Framework" packages="com.silverwrist.dynamo:com.silverwrist.dynamo.*"/>
+      <group title="Mid-Level Venice Classes" packages="com.silverwrist.venice:com.silverwrist.venice.*"/>
+      <link href="http://java.sun.com/j2se/1.4.1/docs/api/"/>
+      <link href="http://jakarta.apache.org/commons/collections/api/"/>
+      <link href="http://jakarta.apache.org/commons/lang/api/"/>
     </javadoc>
   </target>
 

conf/venice-db-init-mysql.sql

@@ -614,12 +614,12 @@ INSERT INTO acedata (aceid, perm_nsid, perm_name) VALUES
   (1, 4, 'remove.member');
 UPDATE groups SET gaclid = 1 WHERE gid = 1;
 
-# Create the "all users" group.
+# Create the "all users" group.  (N.B.: "Anonymous_Honyak" is NOT a member of "All Users")
 # (GID 2)
 INSERT INTO groups (gid, groupname) VALUES (2, 'All_Users');
 INSERT INTO groupmembers (gid, uid) VALUES (2, 2);
 
-# Create the "all verified users" group.
+# Create the "all verified users" group.  (N.B.: "Anonymous_Honyak" is NOT a member of "All Verified Users")
 # (GID 3)
 INSERT INTO groups (gid, groupname) VALUES (3, 'Verified_Users');
 INSERT INTO groupmembers (gid, uid) VALUES (3, 2);
@@ -652,7 +652,8 @@ INSERT INTO acedata (aceid, perm_nsid, perm_name) VALUES
   (2, 13, 'show.admin.menu'           ),
   (2, 14, 'see.member.community.lists'),
   (2, 14, 'community.directory.all'   ),
-  (2, 14, 'community.search.all'      );
+  (2, 14, 'community.search.all'      ),
+  (2, 14, 'join.any'                  );
 INSERT INTO ace (aceid, pri, flags) VALUES (3, 2, 0);
 INSERT INTO acldata (aclid, seq, aceid) VALUES (2, 1, 3);
 INSERT INTO acedata (aceid, perm_nsid, perm_name) VALUES
@@ -738,6 +739,12 @@ INSERT INTO aclowner (aclid, ownerid, flags) VALUES (5, 5, 1);
 INSERT INTO ace (aceid, pri, flags) VALUES (8, 2, 0);
 INSERT INTO acldata (aclid, seq, aceid) VALUES (5, 0, 8);
 INSERT INTO acedata (aceid, perm_nsid, perm_name) VALUES
+  (8, 14, 'grant.revoke.access'),
+  (8, 15, 'set.category'       ),
+  (8, 15, 'set.visibility'     ),
+  (8, 15, 'set.name'           ),
+  (8, 15, 'set.alias'          ),
+  (8, 15, 'set.property'       ),
   (8, 15, 'remove.property'    );
 INSERT INTO ace (aceid, pri, flags) VALUES (9, 5, 1);
 INSERT INTO acldata (aclid, seq, aceid) VALUES (5, 1, 9);
@@ -1123,10 +1130,12 @@ INSERT INTO refcategory (catid, parent, symlink, name) VALUES
 
 UPDATE refcategory SET dontuse = 1 WHERE catid = 15;
 
-# Create the initial community entry.
+# Create the initial community entry.  Anybody can join it.
 # (CID 1)
 INSERT INTO communities (cid, member_gid, host_gid, host_uid, aclid, name, alias, createdate)
   VALUES (1, 4, 5, 2, 5, 'La Piazza', 'piazza', '05-27-2003 09:00:00');
+INSERT INTO commaccess (cid, ugid, is_group, single_use, auth_nsid, auth_name, source_data, auth_data)
+  VALUES (1, 2, 1, 0, NULL, NULL, NULL, NULL);
 
 # Create the properties for the initial community.
 INSERT INTO commprops (cid, nsid, prop_name, prop_value) VALUES

src/baseutil/com/silverwrist/util/Country.java

@@ -76,7 +76,7 @@ public final class Country implements Comparable
 
   /**
    * Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those
-   * provided by <CODE>java.util.Hashtable</CODE>.
+   * provided by {@link java.util.Hashtable Hashtable}.
    *
    * @return A hash code value for this object.
    */

src/dynamo-framework/com/silverwrist/dynamo/iface/DynamicWrapper.java

@@ -11,14 +11,26 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
 package com.silverwrist.dynamo.iface;
 
+/**
+ * An interface implemented on objects that "wrap" other objects, to allow external code to get at the "wrapped"
+ * object.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface DynamicWrapper
 {
+  /**
+   * Returns the object "wrapped" by this one.
+   *
+   * @return The object "wrapped" by this one.
+   */
   public Object unwrap();
 
 } // end interface DynamicWrapper

src/dynamo-framework/com/silverwrist/dynamo/iface/ObjectStore.java

@@ -62,8 +62,8 @@ public interface ObjectStore extends ObjectProvider
    * namespace.
    *
    * @param namespace The namespace to look for names under.
-   * @return A <CODE>java.util.Collection</CODE> containing <CODE>String</CODE> objects specifying all the
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects specifying
-   *         object names for this namespace.
+   *         all the object names for this namespace.
    */
   public Collection getNamesForNamespace(String namespace);
 

src/dynamo-framework/com/silverwrist/dynamo/iface/SecureObjectStore.java

@@ -11,7 +11,7 @@
  * 
  * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
  * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
- * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
+ * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
  * 
  * Contributor(s): 
  */
@@ -21,16 +21,66 @@ import java.util.Collection;
 import com.silverwrist.dynamo.except.DatabaseException;
 import com.silverwrist.dynamo.except.DynamoSecurityException;
 
+/**
+ * An extension to {@link com.silverwrist.dynamo.iface.ObjectProvider ObjectProvider} which allows objects to be
+ * set into this object as well as retrieved from it.  This interface is used in place of
+ * {@link com.silverwrist.dynamo.iface.ObjectStore ObjectStore} in cases where the object store is restricted
+ * to access by specified users or groups of users.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface SecureObjectStore extends ObjectProvider
 {
+  /**
+   * Sets an object into this <CODE>SecureObjectStore</CODE>.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be set.
+   * @param value The object to set into the <CODE>SecureObjectStore</CODE>.
+   * @return The previous object that was set into the <CODE>SecureObjectStore</CODE> under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error setting the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            set this object value into this <CODE>SecureObjectStore</CODE>.
+   */
   public Object setObject(DynamoUser caller, String namespace, String name, Object value)
       throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Removes an object from this <CODE>SecureObjectStore</CODE>.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be removed.
+   * @return The previous object that was set into the <CODE>SecureObjectStore</CODE> under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error removing the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            remove this object value from this <CODE>SecureObjectStore</CODE>.
+   */
   public Object removeObject(DynamoUser caller, String namespace, String name)
       throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Returns a collection of all object namespaces that have been set into this <CODE>SecureObjectStore</CODE>.
+   *
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects specifying
+   *         all the object namespaces.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the namespace list.
+   */
   public Collection getNamespaces() throws DatabaseException;
 
+  /**
+   * Returns a collection of all object names that have been set into this <CODE>SecureObjectStore</CODE> under
+   * a given namespace.
+   *
+   * @param namespace The namespace to look for names under.
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects
+   *         specifying all the object names for this namespace.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the object name list.
+   */
   public Collection getNamesForNamespace(String namespace) throws DatabaseException;
 
 } // end interface SecureObjectStore

src/venice-base/com/silverwrist/venice/CommunityVisibility.java

@@ -20,6 +20,13 @@ package com.silverwrist.venice;
 import java.util.*;
 import org.apache.commons.lang.enum.*;
 
+/**
+ * A type-safe enumerated type that indicates the visibility of a
+ * {@link com.silverwrist.venice.iface.VeniceCommunity community}.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 public final class CommunityVisibility extends Enum
 {
   /*--------------------------------------------------------------------------------
@@ -27,8 +34,19 @@ public final class CommunityVisibility extends Enum
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Indicates that the community is visible through both the hierarchical directory and searches.
+   */
   public static final CommunityVisibility SEARCHDIR  = new CommunityVisibility("SEARCHDIR");
+
+  /**
+   * Indicates that the community is visible through searches, but not the hierarchical directory.
+   */
   public static final CommunityVisibility SEARCHONLY = new CommunityVisibility("SEARCHONLY");
+
+  /**
+   * Indicates that the community is visible through neither the hierarchical directory nor searches.
+   */
   public static final CommunityVisibility NONE       = new CommunityVisibility("NONE");
 
   /*--------------------------------------------------------------------------------
@@ -36,6 +54,11 @@ public final class CommunityVisibility extends Enum
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Internal constructor which creates a new element of this enumerated type.
+   *
+   * @param name The name of the <CODE>CommunityVisibility</CODE> to be created.
+   */
   private CommunityVisibility(String name)
   {
     super(name);
@@ -47,24 +70,48 @@ public final class CommunityVisibility extends Enum
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Gets a <CODE>CommunityVisibility</CODE> by name.
+   *
+   * @param name The name of the <CODE>CommunityVisibility</CODE> to get; may be <CODE>null</CODE>.
+   * @return The <CODE>CommunityVisibility</CODE> object, or <CODE>null</CODE> if the <CODE>CommunityVisibility</CODE>
+   *         does not exist.
+   */
   public static CommunityVisibility getEnum(String name)
   {
     return (CommunityVisibility)getEnum(CommunityVisibility.class,name);
 
   } // end getEnum
 
+  /**
+   * Gets the <CODE>Map</CODE> of <CODE>CommunityVisibility</CODE> objects by name.
+   *
+   * @return The <CODE>CommunityVisibility</CODE> object <CODE>Map</CODE>.
+   */
   public static Map getEnumMap()
   {
     return getEnumMap(CommunityVisibility.class);
 
   } // end getEnumMap
 
+  /**
+   * Gets the <CODE>List</CODE> of <CODE>CommunityVisibility</CODE> objects, in the order in which the objects are
+   * listed in the code above.
+   *
+   * @return The <CODE>CommunityVisibility</CODE> object <CODE>List</CODE>.
+   */
   public static List getEnumList()
   {
     return getEnumList(CommunityVisibility.class);
 
   } // end getEnumList
 
+  /**
+   * Gets an iterator over all <CODE>CommunityVisibility</CODE> objects, in the order in which the objects are listed
+   * in the code above.
+   *
+   * @return The <CODE>CommunityVisibility</CODE> object iterator.
+   */
   public static Iterator iterator()
   {
     return iterator(CommunityVisibility.class);

src/venice-base/com/silverwrist/venice/community/CommunityImpl.java

@@ -33,6 +33,13 @@ import com.silverwrist.venice.VeniceNamespaces;
 import com.silverwrist.venice.event.*;
 import com.silverwrist.venice.iface.*;
 
+/**
+ * Concrete implementation of the {@link com.silverwrist.venice.iface.VeniceCommunity VeniceCommunity} interface,
+ * which provides all the basic community functions.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 class CommunityImpl implements VeniceCommunity
 {
   /*--------------------------------------------------------------------------------
@@ -73,6 +80,27 @@ class CommunityImpl implements VeniceCommunity
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new concrete community implementation.
+   *
+   * @param ops The {@link com.silverwrist.venice.community.CommunityOps CommunityOps} object providing access to the
+   *            database.
+   * @param nscache The {@link com.silverwrist.dynamo.db.NamespaceCache NamespaceCache} object providing conversion
+   *                between namespace URIs and integer namespace identifiers.
+   * @param srm The {@link com.silverwrist.dynamo.security.SecurityReferenceMonitor SecurityReferenceMonitor} object
+   *            through which security is tested.
+   * @param users The {@link com.silverwrist.dynamo.db.UserManagement UserManagetment} object used to retrieve user
+   *              and group objects.
+   * @param alook The {@link com.silverwrist.dynamo.iface.AuthenticatorLookup AuthenticatorLookup} interface used
+   *              to find registered {@link com.silverwrist.dynamo.iface.Authenticator Authenticator} objects.
+   * @param post The {@link com.silverwrist.dynamo.iface.PostDynamicUpdate PostDynamicUpdate} interface used
+   *             to post dynamic update events.
+   * @param cats The {@link com.silverwrist.venice.community.CategoryService CategoryService} interface used to
+   *             retrieve category objects.
+   * @param data A {@link java.util.Map Map} object containing the initial data for the community, with keys
+   *             corresponding to static fields of the
+   *             {@link com.silverwrist.venice.community.CommunityManagerOps CommunityManagerOps} object.
+   */
   CommunityImpl(CommunityOps ops, NamespaceCache nscache, SecurityReferenceMonitor srm, UserManagement users,
 		AuthenticatorLookup alook, PostDynamicUpdate post, CategoryService cats, Map data)
   {
@@ -104,6 +132,20 @@ class CommunityImpl implements VeniceCommunity
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Performs a permission check on the community's ACL, as well as the global ACL.  Returns without
+   * incident if the permission check succeeds; throws a
+   * {@link com.silverwrist.dynamo.except.DynamoSecurityException DynamoSecurityException} if it fails.
+   *
+   * @param caller The user makingt he call, to test the permission.
+   * @param perm_namespace The namespace of the permission to be tested.
+   * @param perm_name The name of the permission to be tested.
+   * @param fail_message The message to be thrown as a <CODE>DynamoSecurityException</CODE> if the test fails.
+   *                     Interpreted as a message identifier within the <CODE>CommunityMessages</CODE> resource
+   *                     bundle, with one parameter: the name of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was a database failure testing the permission.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the permission test failed.
+   */
   private final void testPermission(DynamoUser caller, String perm_namespace, String perm_name,
 				    String fail_message) throws DatabaseException, DynamoSecurityException
   {
@@ -133,6 +175,12 @@ class CommunityImpl implements VeniceCommunity
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Indicates whether some other object is "equal to" this one.
+   *
+   * @param o The reference object with which to compare.
+   * @return <CODE>true</CODE> if this object is the same as the <CODE>o</CODE> argument; <CODE>false</CODE> otherwise.
+   */
   public boolean equals(Object o)
   {
     if (o==null)
@@ -143,12 +191,24 @@ class CommunityImpl implements VeniceCommunity
 
   } // end equals
 
+  /**
+   * Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those
+   * provided by {@link java.util.Hashtable Hashtable}.
+   *
+   * @return A hash code value for this object.
+   */
   public int hashCode()
   {
     return m_id;
 
   } // end hashCode
 
+  /**
+   * Returns a string representation of the object. In general, the <CODE>toString</CODE> method returns a string
+   * that "textually represents" this object. 
+   *
+   * @return A string representation of the object.
+   */
   public String toString()
   {
     return "Community \"" + m_name + "\"";
@@ -177,7 +237,7 @@ class CommunityImpl implements VeniceCommunity
    */
 
   /**
-   * Retrieves an object from this <CODE>ObjectProvider</CODE>.
+   * Retrieves an object from the community's properties.
    *
    * @param namespace The namespace to interpret the name relative to.
    * @param name The name of the object to be retrieved.
@@ -234,6 +294,19 @@ class CommunityImpl implements VeniceCommunity
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Sets an object into the community's properties.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be set.
+   * @param value The object to set into the community's properties.
+   * @return The previous object that was set into the community's properties under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error setting the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            set this object value into this community's properties.
+   */
   public Object setObject(DynamoUser caller, String namespace, String name, Object value)
       throws DatabaseException, DynamoSecurityException
   {
@@ -259,6 +332,18 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setObject
 
+  /**
+   * Removes an object from this community's properties.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be removed.
+   * @return The previous object that was set into the community's properties under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error removing the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            remove this object value from this community's properties.
+   */
   public Object removeObject(DynamoUser caller, String namespace, String name)
       throws DatabaseException, DynamoSecurityException
   {
@@ -284,6 +369,13 @@ class CommunityImpl implements VeniceCommunity
 
   } // end removeObject
 
+  /**
+   * Returns a collection of all object namespaces that have been set into this community's properties.
+   *
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects specifying
+   *         all the object namespaces.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the namespace list.
+   */
   public Collection getNamespaces() throws DatabaseException
   {
     // call through to the database to get the list of namespace IDs
@@ -296,6 +388,15 @@ class CommunityImpl implements VeniceCommunity
 
   } // end getNamespaces
 
+  /**
+   * Returns a collection of all object names that have been set into this community's properties under
+   * a given namespace.
+   *
+   * @param namespace The namespace to look for names under.
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects
+   *         specifying all the object names for this namespace.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the object name list.
+   */
   public Collection getNamesForNamespace(String namespace) throws DatabaseException
   {
     // call through to the database to get the data for this namespace
@@ -326,66 +427,138 @@ class CommunityImpl implements VeniceCommunity
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the community ID of this community.  The community ID is set when the community is created and may
+   * not be altered.
+   *
+   * @return The community ID of this community.
+   */
   public int getCID()
   {
     return m_id;
 
   } // end getCID
 
+  /**
+   * Returns the GID of the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return The GID of the member group for this community.
+   */
   public int getMemberGID()
   {
     return m_member_gid;
 
   } // end getMemberGID
 
+  /**
+   * Returns a reference to the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return A reference to the member group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the member group.
+   */
   public DynamoGroup getMemberGroup() throws DatabaseException
   {
     return m_users.getGroup(m_member_gid);
 
   } // end getMemberGroup
 
+  /**
+   * Returns the GID of the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return The GID of the host group for this community.
+   */
   public int getHostGID()
   {
     return m_host_gid;
 
   } // end getHostGID
 
+  /**
+   * Returns a reference to the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return A reference to the host group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host group.
+   */
   public DynamoGroup getHostGroup() throws DatabaseException
   {
     return m_users.getGroup(m_host_gid);
 
   } // end getHostGroup
 
+  /**
+   * Returns the UID of the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return The UID of the host user of the community.
+   */
   public int getHostUID()
   {
     return m_host_uid;
 
   } // end getHostUID
 
+  /**
+   * Returns a reference to the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return A reference to the host user of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host user.
+   */
   public DynamoUser getHostUser() throws DatabaseException
   {
     return m_users.getUser(m_host_uid);
 
   } // end getHostUser
 
+  /**
+   * Returns a reference to the community's access control list.
+   *
+   * @return A reference to the community's access control list.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the ACL.
+   * @exception java.security.acl.AclNotFoundException If the community ACL could not be found.
+   */
   public DynamoAcl getAcl() throws DatabaseException, AclNotFoundException
   {
     return m_srm.getAcl(m_aclid);
 
   } // end getAcl
 
+  /**
+   * Returns the category ID of the community, specifying its location in the community directory.
+   *
+   * @return The category ID of the community.
+   */
   public int getCategoryID()
   {
     return m_catid;
 
   } // end getCategoryID
 
+  /**
+   * Returns the category of the community, specifying its location in the community directory.
+   *
+   * @return The category of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the category object.
+   */
   public VeniceCategory getCategory() throws DatabaseException
   {
     return m_cats.getCategory(m_catid);
 
   } // end getCategory
 
+  /**
+   * Changes the category ID of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category ID.
+   * @param catid The new category ID for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category ID.
+   */
   public synchronized void setCategoryID(DynamoUser caller, int catid)
       throws DatabaseException, DynamoSecurityException
   {
@@ -397,18 +570,41 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setCategoryID
 
+  /**
+   * Changes the category of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category.
+   * @param catid The new category for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category.
+   */
   public void setCategory(DynamoUser caller, VeniceCategory cat) throws DatabaseException, DynamoSecurityException
   {
     this.setCategoryID(caller,cat.getCategoryID());
 
   } // end setCategory
 
+  /**
+   * Returns the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @return The current visibility of the community.
+   */
   public CommunityVisibility getVisibility()
   {
     return m_visibility;
 
   } // end getVisibility
 
+  /**
+   * Sets the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @param caller The user attempting to change the community's visibility.
+   * @param vis The new visibility for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the visibility.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community visibility.
+   */
   public synchronized void setVisibility(DynamoUser caller, CommunityVisibility vis)
       throws DatabaseException, DynamoSecurityException
   {
@@ -420,6 +616,15 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setVisibility
 
+  /**
+   * Sets the name of the community.
+   *
+   * @param caller The user attempting to change the community's name.
+   * @param name The new name for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the name.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community name.
+   */
   public synchronized void setName(DynamoUser caller, String name) throws DatabaseException, DynamoSecurityException
   {
     testPermission(caller,VeniceNamespaces.COMMUNITY_PROFILE_NAMESPACE,"set.name","auth.setName");
@@ -430,12 +635,28 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setName
 
+  /**
+   * Returns the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @return The alias for the community.
+   */
   public String getAlias()
   {
     return m_alias;
 
   } // end getAlias
 
+  /**
+   * Sets the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @param caller The user attempting to change the community's alias.
+   * @param alias The new alias for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the alias.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community alias.
+   */
   public synchronized void setAlias(DynamoUser caller, String alias) throws DatabaseException, DynamoSecurityException
   {
     testPermission(caller,VeniceNamespaces.COMMUNITY_PROFILE_NAMESPACE,"set.alias","auth.setAlias");
@@ -446,18 +667,37 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setAlias
 
+  /**
+   * Returns the date and time at which this community was created.
+   *
+   * @return The creation date and time for this community.
+   */
   public java.util.Date getCreationDate()
   {
     return m_created;
 
   } // end getCreationDate
 
+  /**
+   * Returns the date and time at which this community was last accessed.
+   *
+   * @return The last access date and time for this community.
+   */
   public java.util.Date getLastAccessDate()
   {
     return m_lastaccessed;
 
   } // end getLastAccessDate
 
+  /**
+   * Sets the date and time at which this community was last accessed.
+   *
+   * @param caller The user attempting to change the community's access date/time.
+   * @param date The new access date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the access date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community access date/time.
+   */
   public synchronized void setLastAccessDate(DynamoUser caller, java.util.Date date) throws DatabaseException
   {
     m_ops.setLastAccessDate(m_id,date);
@@ -465,12 +705,26 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setLastAccessedDate
 
+  /**
+   * Returns the date and time at which this community was last updated.
+   *
+   * @return The last update date and time for this community.
+   */
   public java.util.Date getLastUpdateDate()
   {
     return m_lastupdate;
 
   } // end getLastUpdateDate
 
+  /**
+   * Sets the date and time at which this community was last updated.
+   *
+   * @param caller The user attempting to change the community's update date/time.
+   * @param date The new update date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the update date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community update date/time.
+   */
   public synchronized void setLastUpdateDate(DynamoUser caller, java.util.Date date) throws DatabaseException
   {
     m_ops.setLastUpdateDate(m_id,date);
@@ -478,6 +732,29 @@ class CommunityImpl implements VeniceCommunity
 
   } // end setLastUpdateDate
 
+  /**
+   * Grants permission to join the community to a specific user or group.  This permission may be contingent upon
+   * the user authenticating with the community in some fashion, and it may also be single-use, meaning the permission
+   * is automatically revoked whenever a user uses it to join the community.
+   *
+   * @param caller The person attempting to grant access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to grant access to.
+   * @param auth_namespace The namespace of the authenticator to use to grant access.  If both this parameter and
+   *                       <EM>auth_name</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param auth_name The name of the authenticator to use to grant access.  If both this parameter and
+   *                  <EM>auth_namespace</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param source_info The source information for the authenticator.  If <EM>auth_namespace</EM> and
+   *                    <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param auth_info The authentication information (such as a password) for the authenticator.  If
+   *                  <EM>auth_namespace</EM> and <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param single_use If this parameter is <CODE>true</CODE>, the permission will automatically be revoked after the
+   *                   first time it is successfully used by a user to join the community.
+   * @exception com.silverwrist.dynamo.except.AuthenticationException If the named authenticator is not a valid one.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access grant.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to grant
+   *            access to this community.
+   */
   public void grantAccess(DynamoUser caller, Principal subject, String auth_namespace, String auth_name,
 			  String source_info, String auth_info, boolean single_use)
       throws AuthenticationException, DatabaseException, DynamoSecurityException
@@ -509,6 +786,8 @@ class CommunityImpl implements VeniceCommunity
       auth_nsid = m_nscache.namespaceNameToId(auth_namespace);
 
     } // end if
+    else  // force-map source info and auth info to null
+      source_info = auth_info = null;
 
     // Preprocess the authentication information through the authenticator.
     String real_auth_info = auth_info;
@@ -525,6 +804,17 @@ class CommunityImpl implements VeniceCommunity
 
   } // end grantAccess
 
+  /**
+   * Revokes permission to join the community from a specific user or group.  This does not affect any user who
+   * has already joined the community.
+   *
+   * @param caller The person attempting to revoke access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to revoke access from.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access revoke.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to revoke
+   *            access to this community.
+   */
   public void revokeAccess(DynamoUser caller, Principal subject) throws DatabaseException, DynamoSecurityException
   {
     testPermission(caller,VeniceNamespaces.COMMUNITY_PERMS_NAMESPACE,"grant.revoke.access","auth.revokeAccess");
@@ -552,4 +842,61 @@ class CommunityImpl implements VeniceCommunity
 
   } // end revokeAccess
 
+  /**
+   * Tests to see what requirements must be fulfilled by a user to join this community.  Returns values as follows:
+   * <UL>
+   *   <LI>If the user is not permitted to join the community under any circumstances, this method returns
+   *     <CODE>null</CODE>.</LI>
+   *   <LI>If the user is already a member of the community, this method returns <CODE>Boolean.FALSE</CODE>.</LI>
+   *   <LI>If the user may join the community without any authentication, this method returns
+   *     <CODE>Boolean.TRUE</CODE>.</LI>
+   *   <LI>Otherwise, the method returns a {@link java.util.Set Set} of
+   *     {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey} objects, each of which specifies the
+   *     namespace and name of an authenticator which can be used to authenticate the user in order to join this
+   *     community.</LI>
+   * </UL>
+   *
+   * @param joiner The user to test atainst the current community.
+   * @return See above.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the authenticator
+   *            information for this user.
+   */
+  public Object getJoinRequirement(DynamoUser joiner) throws DatabaseException
+  {
+    // If the user is already a member, return the value that dictates that we are already a member.
+    if (m_users.getGroup(m_member_gid).isMember(joiner))
+      return Boolean.FALSE;
+
+    // The Admin user is Superman and can do anything.
+    if (joiner.equals(m_srm.getAdminUser()))
+      return Boolean.TRUE;
+
+    // Anyone with the global "join any" permission can join without authorization.
+    if (m_srm.getGlobalAcl().testPermission(joiner,VeniceNamespaces.COMMUNITY_PERMS_NAMESPACE,"join.any"))
+      return Boolean.TRUE;
+
+    // Get the database's verdict.  The return value from the low-level operation will either be a null,
+    // a Boolean object, or a Set of PropertyKey objects.
+    Object rc = m_ops.getJoinRequirement(m_id,joiner.getUID());
+    if (rc==null)
+      return null;
+    else if (rc instanceof Boolean)
+      return rc;
+    assert (rc instanceof Set);
+
+    // The output must be translated to a Set of QualifiedNameKeys by resolving the namespace IDs.
+    Set rcin = (Set)rc;
+    HashSet rcout = new HashSet();
+    Iterator it = rcin.iterator();
+    while (it.hasNext())
+    { // convert each PropertyKey to a QualifiedNameKey
+      PropertyKey k = (PropertyKey)(it.next());
+      rcout.add(new QualifiedNameKey(m_nscache.namespaceIdToName(k.getNamespaceID()),k.getName()));
+
+    } // end while
+
+    return Collections.unmodifiableSet(rcout);
+
+  } // end getJoinRequirement
+
 } // end class CommunityImpl

src/venice-base/com/silverwrist/venice/community/CommunityOps.java

@@ -69,4 +69,6 @@ abstract class CommunityOps extends OpsBase
 
   abstract java.util.Date revokeAccess(int cid, int ugid, boolean is_group) throws DatabaseException;
 
+  abstract Object getJoinRequirement(int cid, int uid) throws DatabaseException;
+
 } // end class CommunityOps

src/venice-base/com/silverwrist/venice/community/CommunityOps_mysql.java

@@ -730,4 +730,85 @@ class CommunityOps_mysql extends CommunityOps
 
   } // end revokeAccess
 
+  Object getJoinRequirement(int cid, int uid) throws DatabaseException
+  {
+    Connection conn = null;
+    PreparedStatement stmt = null;
+    ResultSet rs = null;
+    try
+    { // get a connection
+      conn = getConnection();
+
+      // first, look for an entry in the access table matching the UID itself
+      stmt = conn.prepareStatement("SELECT auth_nsid, auth_name FROM commaccess WHERE cid = ? AND ugid = ? "
+				   + "AND is_group = 0;");
+      stmt.setInt(1,cid);
+      stmt.setInt(2,uid);
+      rs = stmt.executeQuery();
+
+      // If there's a PropertyKey, save it for a later return.  If there's a "null/null," return it at once.
+      PropertyKey tmp = null;
+      if (rs.next())
+      { // OK, found an entry, interpret the NSID and name
+	int nsid = rs.getInt(1);
+	boolean nsid_null = rs.wasNull();
+	String name = rs.getString(2);
+	boolean name_null = rs.wasNull();
+	if (nsid_null && name_null)
+	  return Boolean.TRUE;
+	else
+	  tmp = new PropertyKey(nsid,name);
+
+      } // end if
+
+      SQLUtils.shutdown(rs);
+      rs = null;
+      SQLUtils.shutdown(stmt);
+
+      // Now look for an entry matching any group ID we're a member of.
+      stmt = conn.prepareStatement("SELECT a.auth_nsid, a.auth_name FROM commaccess a, groupmembers g WHERE a.cid = ? "
+				   + "AND a.ugid = g.gid AND a.is_group = 1 AND g.uid = ?;");
+      stmt.setInt(1,cid);
+      stmt.setInt(2,uid);
+      rs = stmt.executeQuery();
+
+      // Determine a return value.
+      HashSet rc = new HashSet();
+      if (tmp!=null)
+	rc.add(tmp); // add the temporary return value from the first step
+
+      while (rs.next())
+      { // scan all entries for a "null/null" and collect the rest into a Set
+	int nsid = rs.getInt(1);
+	boolean nsid_null = rs.wasNull();
+	String name = rs.getString(2);
+	boolean name_null = rs.wasNull();
+	if (nsid_null && name_null)
+	  return Boolean.TRUE;
+	else
+	  rc.add(new PropertyKey(nsid,name));
+
+      } // end while
+      
+      if (rc.size()>0)
+	return rc;  // if we found any values, return them
+
+    } // end try
+    catch (SQLException e)
+    { // translate to a general DatabaseException
+      throw generalException(e);
+
+    } // end catch
+    finally
+    { // shut everything down
+      SQLUtils.shutdown(rs);
+      SQLUtils.shutdown(stmt);
+      SQLUtils.shutdown(conn);
+
+    } // end finally
+
+    return null;  // nothing else found...
+
+  } // end getJoinRequirement
+
 } // end class CommunityOps_mysql

src/venice-base/com/silverwrist/venice/community/CommunityProxy.java

@@ -25,6 +25,12 @@ import com.silverwrist.dynamo.iface.*;
 import com.silverwrist.venice.CommunityVisibility;
 import com.silverwrist.venice.iface.*;
 
+/**
+ * A "proxy object" for communities, which is returned by property deserialization.
+ *
+ * @author Eric J. Bowersox <erbo@silcom.com>
+ * @version X
+ */
 abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 {
   /*--------------------------------------------------------------------------------
@@ -32,6 +38,9 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * The ID of the community that this object is a proxy for.
+   */
   protected int m_id;
 
   /*--------------------------------------------------------------------------------
@@ -39,6 +48,11 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Constructs a new <CODE>CommunityProxy</CODE> object.
+   *
+   * @param cid ID of the community that this object is to be a proxy for.
+   */
   CommunityProxy(int cid)
   {
     m_id = cid;
@@ -50,6 +64,12 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns a reference to the "real" {@link com.silverwrist.venice.iface.VeniceCommunity VeniceCommunity} object
+   * underlying this proxy.
+   *
+   * @return A reference to the "real" community object.
+   */
   protected abstract VeniceCommunity getRealCommunity();
 
   /*--------------------------------------------------------------------------------
@@ -57,6 +77,12 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Indicates whether some other object is "equal to" this one.
+   *
+   * @param o The reference object with which to compare.
+   * @return <CODE>true</CODE> if this object is the same as the <CODE>o</CODE> argument; <CODE>false</CODE> otherwise.
+   */
   public boolean equals(Object o)
   {
     if (o==null)
@@ -67,12 +93,24 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end equals
 
+  /**
+   * Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those
+   * provided by {@link java.util.Hashtable Hashtable}.
+   *
+   * @return A hash code value for this object.
+   */
   public int hashCode()
   {
     return m_id;
 
   } // end hashCode
 
+  /**
+   * Returns a string representation of the object. In general, the <CODE>toString</CODE> method returns a string
+   * that "textually represents" this object. 
+   *
+   * @return A string representation of the object.
+   */
   public String toString()
   {
     return "Community #" + m_id;
@@ -101,7 +139,7 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    */
 
   /**
-   * Retrieves an object from this <CODE>ObjectProvider</CODE>.
+   * Retrieves an object from the community's properties.
    *
    * @param namespace The namespace to interpret the name relative to.
    * @param name The name of the object to be retrieved.
@@ -118,6 +156,19 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Sets an object into the community's properties.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be set.
+   * @param value The object to set into the community's properties.
+   * @return The previous object that was set into the community's properties under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error setting the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            set this object value into this community's properties.
+   */
   public Object setObject(DynamoUser caller, String namespace, String name, Object value)
       throws DatabaseException, DynamoSecurityException
   {
@@ -125,6 +176,18 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end setObject
 
+  /**
+   * Removes an object from this community's properties.
+   *
+   * @param caller The user performing the operation.
+   * @param namespace The namespace to interpret the name relative to.
+   * @param name The name of the object to be removed.
+   * @return The previous object that was set into the community's properties under this namespace and name, or
+   *         <CODE>null</CODE> if there was no such object.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error removing the object value.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            remove this object value from this community's properties.
+   */
   public Object removeObject(DynamoUser caller, String namespace, String name)
       throws DatabaseException, DynamoSecurityException
   {
@@ -132,12 +195,28 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end removeObject
 
+  /**
+   * Returns a collection of all object namespaces that have been set into this community's properties.
+   *
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects specifying
+   *         all the object namespaces.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the namespace list.
+   */
   public Collection getNamespaces() throws DatabaseException
   {
     return getRealCommunity().getNamespaces();
 
   } // end getNamespaces
 
+  /**
+   * Returns a collection of all object names that have been set into this community's properties under
+   * a given namespace.
+   *
+   * @param namespace The namespace to look for names under.
+   * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects
+   *         specifying all the object names for this namespace.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the object name list.
+   */
   public Collection getNamesForNamespace(String namespace) throws DatabaseException
   {
     return getRealCommunity().getNamesForNamespace(namespace);
@@ -149,66 +228,138 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns the community ID of this community.  The community ID is set when the community is created and may
+   * not be altered.
+   *
+   * @return The community ID of this community.
+   */
   public int getCID()
   {
     return m_id;
 
   } // end getCID
 
+  /**
+   * Returns the GID of the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return The GID of the member group for this community.
+   */
   public int getMemberGID()
   {
     return getRealCommunity().getMemberGID();
 
   } // end getMemberGID
 
+  /**
+   * Returns a reference to the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return A reference to the member group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the member group.
+   */
   public DynamoGroup getMemberGroup() throws DatabaseException
   {
     return getRealCommunity().getMemberGroup();
 
   } // end getMemberGroup
 
+  /**
+   * Returns the GID of the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return The GID of the host group for this community.
+   */
   public int getHostGID()
   {
     return getRealCommunity().getHostGID();
 
   } // end getHostGID
 
+  /**
+   * Returns a reference to the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return A reference to the host group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host group.
+   */
   public DynamoGroup getHostGroup() throws DatabaseException
   {
     return getRealCommunity().getHostGroup();
 
   } // end getHostGroup
 
+  /**
+   * Returns the UID of the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return The UID of the host user of the community.
+   */
   public int getHostUID()
   {
     return getRealCommunity().getHostUID();
 
   } // end getHostUID
 
+  /**
+   * Returns a reference to the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return A reference to the host user of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host user.
+   */
   public DynamoUser getHostUser() throws DatabaseException
   {
     return getRealCommunity().getHostUser();
 
   } // end getHostUser
 
+  /**
+   * Returns a reference to the community's access control list.
+   *
+   * @return A reference to the community's access control list.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the ACL.
+   * @exception java.security.acl.AclNotFoundException If the community ACL could not be found.
+   */
   public DynamoAcl getAcl() throws DatabaseException, AclNotFoundException
   {
     return getRealCommunity().getAcl();
 
   } // end getAcl
  
+  /**
+   * Returns the category ID of the community, specifying its location in the community directory.
+   *
+   * @return The category ID of the community.
+   */
   public int getCategoryID()
   {
     return getRealCommunity().getCategoryID();
 
   } // end getCategoryID
 
+  /**
+   * Returns the category of the community, specifying its location in the community directory.
+   *
+   * @return The category of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the category object.
+   */
   public VeniceCategory getCategory() throws DatabaseException
   {
     return getRealCommunity().getCategory();
 
   } // end getCategory
 
+  /**
+   * Changes the category ID of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category ID.
+   * @param catid The new category ID for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category ID.
+   */
   public synchronized void setCategoryID(DynamoUser caller, int catid)
       throws DatabaseException, DynamoSecurityException
   {
@@ -216,18 +367,41 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end setCategoryID
 
+  /**
+   * Changes the category of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category.
+   * @param catid The new category for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category.
+   */
   public void setCategory(DynamoUser caller, VeniceCategory cat) throws DatabaseException, DynamoSecurityException
   {
     this.setCategoryID(caller,cat.getCategoryID());
 
   } // end setCategory
 
+  /**
+   * Returns the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @return The current visibility of the community.
+   */
   public CommunityVisibility getVisibility()
   {
     return getRealCommunity().getVisibility();
 
   } // end getVisibility
 
+  /**
+   * Sets the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @param caller The user attempting to change the community's visibility.
+   * @param vis The new visibility for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the visibility.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community visibility.
+   */
   public synchronized void setVisibility(DynamoUser caller, CommunityVisibility vis)
       throws DatabaseException, DynamoSecurityException
   {
@@ -235,36 +409,80 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end setVisibility
 
+  /**
+   * Sets the name of the community.
+   *
+   * @param caller The user attempting to change the community's name.
+   * @param name The new name for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the name.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community name.
+   */
   public synchronized void setName(DynamoUser caller, String name) throws DatabaseException, DynamoSecurityException
   {
     getRealCommunity().setName(caller,name);
 
   } // end setName
 
+  /**
+   * Returns the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @return The alias for the community.
+   */
   public String getAlias()
   {
     return getRealCommunity().getAlias();
 
   } // end getAlias
 
+  /**
+   * Sets the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @param caller The user attempting to change the community's alias.
+   * @param alias The new alias for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the alias.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community alias.
+   */
   public synchronized void setAlias(DynamoUser caller, String alias) throws DatabaseException, DynamoSecurityException
   {
     getRealCommunity().setAlias(caller,alias);
 
   } // end setAlias
 
+  /**
+   * Returns the date and time at which this community was created.
+   *
+   * @return The creation date and time for this community.
+   */
   public java.util.Date getCreationDate()
   {
     return getRealCommunity().getCreationDate();
 
   } // end getCreationDate
 
+  /**
+   * Returns the date and time at which this community was last accessed.
+   *
+   * @return The last access date and time for this community.
+   */
   public java.util.Date getLastAccessDate()
   {
     return getRealCommunity().getLastAccessDate();
 
   } // end getLastAccessDate
 
+  /**
+   * Sets the date and time at which this community was last accessed.
+   *
+   * @param caller The user attempting to change the community's access date/time.
+   * @param date The new access date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the access date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community access date/time.
+   */
   public synchronized void setLastAccessDate(DynamoUser caller, java.util.Date date)
       throws DatabaseException, DynamoSecurityException
   {
@@ -272,12 +490,26 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end setLastAccessedDate
 
+  /**
+   * Returns the date and time at which this community was last updated.
+   *
+   * @return The last update date and time for this community.
+   */
   public java.util.Date getLastUpdateDate()
   {
     return getRealCommunity().getLastUpdateDate();
 
   } // end getLastUpdateDate
 
+  /**
+   * Sets the date and time at which this community was last updated.
+   *
+   * @param caller The user attempting to change the community's update date/time.
+   * @param date The new update date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the update date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community update date/time.
+   */
   public synchronized void setLastUpdateDate(DynamoUser caller, java.util.Date date)
       throws DatabaseException, DynamoSecurityException
   {
@@ -285,6 +517,29 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end setLastUpdateDate
 
+  /**
+   * Grants permission to join the community to a specific user or group.  This permission may be contingent upon
+   * the user authenticating with the community in some fashion, and it may also be single-use, meaning the permission
+   * is automatically revoked whenever a user uses it to join the community.
+   *
+   * @param caller The person attempting to grant access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to grant access to.
+   * @param auth_namespace The namespace of the authenticator to use to grant access.  If both this parameter and
+   *                       <EM>auth_name</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param auth_name The name of the authenticator to use to grant access.  If both this parameter and
+   *                  <EM>auth_namespace</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param source_info The source information for the authenticator.  If <EM>auth_namespace</EM> and
+   *                    <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param auth_info The authentication information (such as a password) for the authenticator.  If
+   *                  <EM>auth_namespace</EM> and <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param single_use If this parameter is <CODE>true</CODE>, the permission will automatically be revoked after the
+   *                   first time it is successfully used by a user to join the community.
+   * @exception com.silverwrist.dynamo.except.AuthenticationException If the named authenticator is not a valid one.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access grant.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to grant
+   *            access to this community.
+   */
   public void grantAccess(DynamoUser caller, Principal subject, String auth_namespace, String auth_name,
 			  String source_info, String auth_info, boolean single_use)
       throws AuthenticationException, DatabaseException, DynamoSecurityException
@@ -293,17 +548,59 @@ abstract class CommunityProxy implements VeniceCommunity, DynamicWrapper
 
   } // end grantAccess
 
+  /**
+   * Revokes permission to join the community from a specific user or group.  This does not affect any user who
+   * has already joined the community.
+   *
+   * @param caller The person attempting to revoke access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to revoke access from.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access revoke.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to revoke
+   *            access to this community.
+   */
   public void revokeAccess(DynamoUser caller, Principal subject) throws DatabaseException, DynamoSecurityException
   {
     getRealCommunity().revokeAccess(caller,subject);
 
   } // end revokeAccess
 
+  /**
+   * Tests to see what requirements must be fulfilled by a user to join this community.  Returns values as follows:
+   * <UL>
+   *   <LI>If the user is not permitted to join the community under any circumstances, this method returns
+   *     <CODE>null</CODE>.</LI>
+   *   <LI>If the user is already a member of the community, this method returns <CODE>Boolean.FALSE</CODE>.</LI>
+   *   <LI>If the user may join the community without any authentication, this method returns
+   *     <CODE>Boolean.TRUE</CODE>.</LI>
+   *   <LI>Otherwise, the method returns a {@link java.util.Set Set} of
+   *     {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey} objects, each of which specifies the
+   *     namespace and name of an authenticator which can be used to authenticate the user in order to join this
+   *     community.</LI>
+   * </UL>
+   *
+   * @param joiner The user to test atainst the current community.
+   * @return See above.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the authenticator
+   *            information for this user.
+   */
+  public Object getJoinRequirement(DynamoUser joiner) throws DatabaseException
+  {
+    return getRealCommunity().getJoinRequirement(joiner);
+
+  } // end getJoinRequirement
+
   /*--------------------------------------------------------------------------------
    * Implementations from interface DynamicWrapper
    *--------------------------------------------------------------------------------
    */
 
+  /**
+   * Returns a reference to the "real" {@link com.silverwrist.venice.iface.VeniceCommunity VeniceCommunity} object
+   * underlying this proxy.
+   *
+   * @return A reference to the "real" community object.
+   */
   public Object unwrap()
   {
     return getRealCommunity();

src/venice-base/com/silverwrist/venice/iface/VeniceCommunity.java

@@ -30,59 +30,280 @@ import com.silverwrist.dynamo.iface.NamedObject;
 import com.silverwrist.dynamo.iface.SecureObjectStore;
 import com.silverwrist.venice.CommunityVisibility;
 
+/**
+ * The interface representing a top-level <EM>community object</EM>.  A <EM>community</EM> is the primary unit of
+ * functional organization on a Venice server; a Venice server may contain many communities.  Each community
+ * maintains its own membership list (a subset of the global membership list of the server) and also contains
+ * a list of <EM>services</EM> its members may use, each of which may control multiple resources maintained for the
+ * benefit of the community.<P>
+ * Users may join and unjoin communities at will, subject to the wishes of the community hosts.  Hosts may require
+ * that users authenticate themselves to the community prior to joining, with a password or similar mechanism.  Hosts
+ * may also add and remove members from a community at their discretion.
+ *
+ * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
+ * @version X
+ */
 public interface VeniceCommunity extends NamedObject, SecureObjectStore
 {
+  /**
+   * Returns the community ID of this community.  The community ID is set when the community is created and may
+   * not be altered.
+   *
+   * @return The community ID of this community.
+   */
   public int getCID();
 
+  /**
+   * Returns the GID of the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return The GID of the member group for this community.
+   */
   public int getMemberGID();
 
+  /**
+   * Returns a reference to the <EM>member group</EM> of this community.  The member group specifies all
+   * members of the community.
+   *
+   * @return A reference to the member group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the member group.
+   */
   public DynamoGroup getMemberGroup() throws DatabaseException;
 
+  /**
+   * Returns the GID of the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return The GID of the host group for this community.
+   */
   public int getHostGID();
 
+  /**
+   * Returns a reference to the <EM>host group</EM> of this community.  The host group specifies all
+   * hosts of the community, who generally have power to change most attributes of a community.
+   *
+   * @return A reference to the host group of this community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host group.
+   */
   public DynamoGroup getHostGroup() throws DatabaseException;
 
+  /**
+   * Returns the UID of the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return The UID of the host user of the community.
+   */
   public int getHostUID();
 
+  /**
+   * Returns a reference to the <EM>host user</EM> of this community.  The host user is the primary host of the
+   * community, who is the only one who has power to add or remove additional hosts.
+   *
+   * @return A reference to the host user of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host user.
+   */
   public DynamoUser getHostUser() throws DatabaseException;
 
+  /**
+   * Returns a reference to the community's access control list.
+   *
+   * @return A reference to the community's access control list.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the ACL.
+   * @exception java.security.acl.AclNotFoundException If the community ACL could not be found.
+   */
   public DynamoAcl getAcl() throws DatabaseException, AclNotFoundException;
 
+  /**
+   * Returns the category ID of the community, specifying its location in the community directory.
+   *
+   * @return The category ID of the community.
+   */
   public int getCategoryID();
 
+  /**
+   * Returns the category of the community, specifying its location in the community directory.
+   *
+   * @return The category of the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the category object.
+   */
   public VeniceCategory getCategory() throws DatabaseException;
 
+  /**
+   * Changes the category ID of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category ID.
+   * @param catid The new category ID for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category ID.
+   */
   public void setCategoryID(DynamoUser caller, int catid) throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Changes the category of the community, specifying its location in the community directory.
+   *
+   * @param caller The user attempting to change the category.
+   * @param catid The new category for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the category.
+   */
   public void setCategory(DynamoUser caller, VeniceCategory cat) throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Returns the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @return The current visibility of the community.
+   */
   public CommunityVisibility getVisibility();
 
+  /**
+   * Sets the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
+   *
+   * @param caller The user attempting to change the community's visibility.
+   * @param vis The new visibility for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the visibility.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community visibility.
+   */
   public void setVisibility(DynamoUser caller, CommunityVisibility vis)
       throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Sets the name of the community.
+   *
+   * @param caller The user attempting to change the community's name.
+   * @param name The new name for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the name.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community name.
+   */
   public void setName(DynamoUser caller, String name) throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Returns the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @return The alias for the community.
+   */
   public String getAlias();
 
+  /**
+   * Sets the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
+   * conform to the rules for Dynamo identifiers.
+   *
+   * @param caller The user attempting to change the community's alias.
+   * @param alias The new alias for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the alias.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community alias.
+   */
   public void setAlias(DynamoUser caller, String alias) throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Returns the date and time at which this community was created.
+   *
+   * @return The creation date and time for this community.
+   */
   public java.util.Date getCreationDate();
 
+  /**
+   * Returns the date and time at which this community was last accessed.
+   *
+   * @return The last access date and time for this community.
+   */
   public java.util.Date getLastAccessDate();
 
+  /**
+   * Sets the date and time at which this community was last accessed.
+   *
+   * @param caller The user attempting to change the community's access date/time.
+   * @param date The new access date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the access date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community access date/time.
+   */
   public void setLastAccessDate(DynamoUser caller, java.util.Date date)
       throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Returns the date and time at which this community was last updated.
+   *
+   * @return The last update date and time for this community.
+   */
   public java.util.Date getLastUpdateDate();
 
+  /**
+   * Sets the date and time at which this community was last updated.
+   *
+   * @param caller The user attempting to change the community's update date/time.
+   * @param date The new update date/time for the community.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the update date/time.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
+   *            change the community update date/time.
+   */
   public void setLastUpdateDate(DynamoUser caller, java.util.Date date)
       throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Grants permission to join the community to a specific user or group.  This permission may be contingent upon
+   * the user authenticating with the community in some fashion, and it may also be single-use, meaning the permission
+   * is automatically revoked whenever a user uses it to join the community.
+   *
+   * @param caller The person attempting to grant access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to grant access to.
+   * @param auth_namespace The namespace of the authenticator to use to grant access.  If both this parameter and
+   *                       <EM>auth_name</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param auth_name The name of the authenticator to use to grant access.  If both this parameter and
+   *                  <EM>auth_namespace</EM> are <CODE>null</CODE>, no authentication is required.
+   * @param source_info The source information for the authenticator.  If <EM>auth_namespace</EM> and
+   *                    <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param auth_info The authentication information (such as a password) for the authenticator.  If
+   *                  <EM>auth_namespace</EM> and <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
+   * @param single_use If this parameter is <CODE>true</CODE>, the permission will automatically be revoked after the
+   *                   first time it is successfully used by a user to join the community.
+   * @exception com.silverwrist.dynamo.except.AuthenticationException If the named authenticator is not a valid one.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access grant.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to grant
+   *            access to this community.
+   */
   public void grantAccess(DynamoUser caller, Principal subject, String auth_namespace, String auth_name,
 			  String source_info, String auth_info, boolean single_use)
       throws AuthenticationException, DatabaseException, DynamoSecurityException;
 
+  /**
+   * Revokes permission to join the community from a specific user or group.  This does not affect any user who
+   * has already joined the community.
+   *
+   * @param caller The person attempting to revoke access to the community.
+   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
+   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to revoke access from.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access revoke.
+   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to revoke
+   *            access to this community.
+   */
   public void revokeAccess(DynamoUser caller, Principal subject) throws DatabaseException, DynamoSecurityException;
 
+  /**
+   * Tests to see what requirements must be fulfilled by a user to join this community.  Returns values as follows:
+   * <UL>
+   *   <LI>If the user is not permitted to join the community under any circumstances, this method returns
+   *     <CODE>null</CODE>.</LI>
+   *   <LI>If the user is already a member of the community, this method returns <CODE>Boolean.FALSE</CODE>.</LI>
+   *   <LI>If the user may join the community without any authentication, this method returns
+   *     <CODE>Boolean.TRUE</CODE>.</LI>
+   *   <LI>Otherwise, the method returns a {@link java.util.Set Set} of
+   *     {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey} objects, each of which specifies the
+   *     namespace and name of an authenticator which can be used to authenticate the user in order to join this
+   *     community.</LI>
+   * </UL>
+   *
+   * @param joiner The user to test atainst the current community.
+   * @return See above.
+   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the authenticator
+   *            information for this user.
+   */
+  public Object getJoinRequirement(DynamoUser joiner) throws DatabaseException;
+
 } // end interface VeniceCommunity