320 lines
16 KiB
Java
320 lines
16 KiB
Java
/*
|
|
* 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 <http://www.mozilla.org/MPL/>.
|
|
*
|
|
* 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 <erbo@silcom.com>,
|
|
* 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 java.util.List;
|
|
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 <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 <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 <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 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);
|
|
|
|
public List getServices() throws DatabaseException;
|
|
|
|
} // end interface VeniceCommunity
|