/* * The contents of this file are subject to the Mozilla Public License Version 1.1 * (the "License"); you may not use this file except in compliance with the License. * You may obtain a copy of the License at . * * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT * WARRANTY OF ANY KIND, either express or implied. See the License for the specific * language governing rights and limitations under the License. * * The Original Code is the Venice Web Communities System. * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are * Copyright (C) 2003 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ package com.silverwrist.venice.iface; import java.security.Principal; import java.security.acl.AclNotFoundException; import java.util.Date; import com.silverwrist.dynamo.except.AuthenticationException; import com.silverwrist.dynamo.except.DatabaseException; import com.silverwrist.dynamo.except.DynamoSecurityException; import com.silverwrist.dynamo.iface.DynamoAcl; import com.silverwrist.dynamo.iface.DynamoGroup; import com.silverwrist.dynamo.iface.DynamoUser; 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 against 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; public boolean join(DynamoUser joiner, String auth_namespace, String auth_name, String source_info, String auth_info) throws DatabaseException, DynamoSecurityException; public boolean join(DynamoUser joiner) throws DatabaseException, DynamoSecurityException; public boolean isAdministrator(DynamoUser user); } // end interface VeniceCommunity