diff --git a/build.xml b/build.xml index 3ae8812..5adc767 100644 --- a/build.xml +++ b/build.xml @@ -429,7 +429,8 @@ + packagenames="com.silverwrist.util.*,com.silverwrist.dynamo.*,com.silverwrist.venice.*" + windowtitle="Venice Web Communities System"> @@ -438,6 +439,12 @@ + + + + + + diff --git a/conf/venice-db-init-mysql.sql b/conf/venice-db-init-mysql.sql index d933ae8..4eede05 100644 --- a/conf/venice-db-init-mysql.sql +++ b/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,7 +739,13 @@ 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, 15, 'remove.property'); + (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); INSERT INTO acedata (aceid, perm_nsid, perm_name) VALUES @@ -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 diff --git a/src/baseutil/com/silverwrist/util/Country.java b/src/baseutil/com/silverwrist/util/Country.java index 72e4016..f192dc1 100644 --- a/src/baseutil/com/silverwrist/util/Country.java +++ b/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 java.util.Hashtable. + * provided by {@link java.util.Hashtable Hashtable}. * * @return A hash code value for this object. */ diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/DynamicWrapper.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/DynamicWrapper.java index cfeb83f..35e3a62 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/DynamicWrapper.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/DynamicWrapper.java @@ -11,14 +11,26 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @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 diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/ObjectStore.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/ObjectStore.java index c92abce..ee867b2 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/ObjectStore.java +++ b/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 java.util.Collection containing String objects specifying all the - * object names for this namespace. + * @return A {@link java.util.Collection Collection} containing {@link java.lang.String String} objects specifying + * all the object names for this namespace. */ public Collection getNamesForNamespace(String namespace); diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/SecureObjectStore.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/SecureObjectStore.java index 7993060..5ebaff9 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/SecureObjectStore.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/SecureObjectStore.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * 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 <erbo@silcom.com> + * @version X + */ public interface SecureObjectStore extends ObjectProvider { + /** + * Sets an object into this SecureObjectStore. + * + * @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 SecureObjectStore. + * @return The previous object that was set into the SecureObjectStore under this namespace and name, or + * null 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 SecureObjectStore. + */ public Object setObject(DynamoUser caller, String namespace, String name, Object value) throws DatabaseException, DynamoSecurityException; + /** + * Removes an object from this SecureObjectStore. + * + * @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 SecureObjectStore under this namespace and name, or + * null 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 SecureObjectStore. + */ 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 SecureObjectStore. + * + * @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 SecureObjectStore 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 diff --git a/src/venice-base/com/silverwrist/venice/CommunityVisibility.java b/src/venice-base/com/silverwrist/venice/CommunityVisibility.java index 167134a..c218f96 100644 --- a/src/venice-base/com/silverwrist/venice/CommunityVisibility.java +++ b/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 CommunityVisibility to be created. + */ private CommunityVisibility(String name) { super(name); @@ -47,24 +70,48 @@ public final class CommunityVisibility extends Enum *-------------------------------------------------------------------------------- */ + /** + * Gets a CommunityVisibility by name. + * + * @param name The name of the CommunityVisibility to get; may be null. + * @return The CommunityVisibility object, or null if the CommunityVisibility + * does not exist. + */ public static CommunityVisibility getEnum(String name) { return (CommunityVisibility)getEnum(CommunityVisibility.class,name); } // end getEnum + /** + * Gets the Map of CommunityVisibility objects by name. + * + * @return The CommunityVisibility object Map. + */ public static Map getEnumMap() { return getEnumMap(CommunityVisibility.class); } // end getEnumMap + /** + * Gets the List of CommunityVisibility objects, in the order in which the objects are + * listed in the code above. + * + * @return The CommunityVisibility object List. + */ public static List getEnumList() { return getEnumList(CommunityVisibility.class); } // end getEnumList + /** + * Gets an iterator over all CommunityVisibility objects, in the order in which the objects are listed + * in the code above. + * + * @return The CommunityVisibility object iterator. + */ public static Iterator iterator() { return iterator(CommunityVisibility.class); diff --git a/src/venice-base/com/silverwrist/venice/community/CommunityImpl.java b/src/venice-base/com/silverwrist/venice/community/CommunityImpl.java index b717a73..fc4db57 100644 --- a/src/venice-base/com/silverwrist/venice/community/CommunityImpl.java +++ b/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 DynamoSecurityException if the test fails. + * Interpreted as a message identifier within the CommunityMessages 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 true if this object is the same as the o argument; false 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 toString 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 ObjectProvider. + * 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 + * null 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 + * null 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 member group 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 member group 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 host group 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 host group 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 host user 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 host user 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 alias 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 alias 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 + * auth_name are null, no authentication is required. + * @param auth_name The name of the authenticator to use to grant access. If both this parameter and + * auth_namespace are null, no authentication is required. + * @param source_info The source information for the authenticator. If auth_namespace and + * auth_name are null, this parameter is ignored. + * @param auth_info The authentication information (such as a password) for the authenticator. If + * auth_namespace and auth_name are null, this parameter is ignored. + * @param single_use If this parameter is true, 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: + * + * + * @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 diff --git a/src/venice-base/com/silverwrist/venice/community/CommunityOps.java b/src/venice-base/com/silverwrist/venice/community/CommunityOps.java index 3afddfc..ad6b37c 100644 --- a/src/venice-base/com/silverwrist/venice/community/CommunityOps.java +++ b/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 diff --git a/src/venice-base/com/silverwrist/venice/community/CommunityOps_mysql.java b/src/venice-base/com/silverwrist/venice/community/CommunityOps_mysql.java index e94e508..6be5dc0 100644 --- a/src/venice-base/com/silverwrist/venice/community/CommunityOps_mysql.java +++ b/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 diff --git a/src/venice-base/com/silverwrist/venice/community/CommunityProxy.java b/src/venice-base/com/silverwrist/venice/community/CommunityProxy.java index e7d6324..bc4a10b 100644 --- a/src/venice-base/com/silverwrist/venice/community/CommunityProxy.java +++ b/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 CommunityProxy 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 true if this object is the same as the o argument; false 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 toString 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 ObjectProvider. + * 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 + * null 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 + * null 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 member group 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 member group 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 host group 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 host group 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 host user 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 host user 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 alias 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 alias 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 + * auth_name are null, no authentication is required. + * @param auth_name The name of the authenticator to use to grant access. If both this parameter and + * auth_namespace are null, no authentication is required. + * @param source_info The source information for the authenticator. If auth_namespace and + * auth_name are null, this parameter is ignored. + * @param auth_info The authentication information (such as a password) for the authenticator. If + * auth_namespace and auth_name are null, this parameter is ignored. + * @param single_use If this parameter is true, 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: + * + * + * @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(); diff --git a/src/venice-base/com/silverwrist/venice/iface/VeniceCommunity.java b/src/venice-base/com/silverwrist/venice/iface/VeniceCommunity.java index 4e3474f..d32630f 100644 --- a/src/venice-base/com/silverwrist/venice/iface/VeniceCommunity.java +++ b/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 community object. A community 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 services its members may use, each of which may control multiple resources maintained for the + * benefit of the community.

+ * 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 <erbo@silcom.com> + * @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 member group 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 member group 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 host group 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 host group 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 host user 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 host user 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 alias 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 alias 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 + * auth_name are null, no authentication is required. + * @param auth_name The name of the authenticator to use to grant access. If both this parameter and + * auth_namespace are null, no authentication is required. + * @param source_info The source information for the authenticator. If auth_namespace and + * auth_name are null, this parameter is ignored. + * @param auth_info The authentication information (such as a password) for the authenticator. If + * auth_namespace and auth_name are null, this parameter is ignored. + * @param single_use If this parameter is true, 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: + *

+ * + * @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