/*
 * 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.Request;
import com.silverwrist.dynamo.iface.SecureObjectStore;
import com.silverwrist.venice.CommunityVisibility;
import com.silverwrist.venice.except.CommunityServiceException;

/**
 * The interface representing a top-level <EM>community object</EM>.  A <EM>community</EM> is the primary unit of
 * functional organization on a Venice server; a Venice server may contain many communities.  Each community
 * maintains its own membership list (a subset of the global membership list of the server) and also contains
 * a list of <EM>services</EM> its members may use, each of which may control multiple resources maintained for the
 * benefit of the community.<P>
 * Users may join and unjoin communities at will, subject to the wishes of the community hosts.  Hosts may require
 * that users authenticate themselves to the community prior to joining, with a password or similar mechanism.  Hosts
 * may also add and remove members from a community at their discretion.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface VeniceCommunity extends NamedObject, SecureObjectStore
{
  /**
   * Returns the community ID of this community.  The community ID is set when the community is created and may
   * not be altered.
   *
   * @return The community ID of this community.
   */
  public int getCID();

  /**
   * Returns the GID of the <EM>member group</EM> of this community.  The member group specifies all
   * members of the community.
   *
   * @return The GID of the member group for this community.
   */
  public int getMemberGID();

  /**
   * Returns a reference to the <EM>member group</EM> of this community.  The member group specifies all
   * members of the community.
   *
   * @return A reference to the member group of this community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the member group.
   */
  public DynamoGroup getMemberGroup() throws DatabaseException;

  /**
   * Returns the GID of the <EM>host group</EM> of this community.  The host group specifies all
   * hosts of the community, who generally have power to change most attributes of a community.
   *
   * @return The GID of the host group for this community.
   */
  public int getHostGID();

  /**
   * Returns a reference to the <EM>host group</EM> of this community.  The host group specifies all
   * hosts of the community, who generally have power to change most attributes of a community.
   *
   * @return A reference to the host group of this community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host group.
   */
  public DynamoGroup getHostGroup() throws DatabaseException;

  /**
   * Returns the UID of the <EM>host user</EM> of this community.  The host user is the primary host of the
   * community, who is the only one who has power to add or remove additional hosts.
   *
   * @return The UID of the host user of the community.
   */
  public int getHostUID();

  /**
   * Returns a reference to the <EM>host user</EM> of this community.  The host user is the primary host of the
   * community, who is the only one who has power to add or remove additional hosts.
   *
   * @return A reference to the host user of the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the host user.
   */
  public DynamoUser getHostUser() throws DatabaseException;

  /**
   * Returns a reference to the community's access control list.
   *
   * @return A reference to the community's access control list.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the ACL.
   * @exception java.security.acl.AclNotFoundException If the community ACL could not be found.
   */
  public DynamoAcl getAcl() throws DatabaseException, AclNotFoundException;

  /**
   * Returns the category ID of the community, specifying its location in the community directory.
   *
   * @return The category ID of the community.
   */
  public int getCategoryID();

  /**
   * Returns the category of the community, specifying its location in the community directory.
   *
   * @return The category of the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error getting the category object.
   */
  public VeniceCategory getCategory() throws DatabaseException;

  /**
   * Changes the category ID of the community, specifying its location in the community directory.
   *
   * @param caller The user attempting to change the category ID.
   * @param catid The new category ID for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the category ID.
   */
  public void setCategoryID(DynamoUser caller, int catid) throws DatabaseException, DynamoSecurityException;

  /**
   * Changes the category of the community, specifying its location in the community directory.
   *
   * @param caller The user attempting to change the category.
   * @param catid The new category for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the category.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the category.
   */
  public void setCategory(DynamoUser caller, VeniceCategory cat) throws DatabaseException, DynamoSecurityException;

  /**
   * Returns the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
   *
   * @return The current visibility of the community.
   */
  public CommunityVisibility getVisibility();

  /**
   * Sets the current {@link com.silverwrist.venice.CommunityVisibility visibility} of the community.
   *
   * @param caller The user attempting to change the community's visibility.
   * @param vis The new visibility for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the visibility.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the community visibility.
   */
  public void setVisibility(DynamoUser caller, CommunityVisibility vis)
      throws DatabaseException, DynamoSecurityException;

  /**
   * Sets the name of the community.
   *
   * @param caller The user attempting to change the community's name.
   * @param name The new name for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the name.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the community name.
   */
  public void setName(DynamoUser caller, String name) throws DatabaseException, DynamoSecurityException;

  /**
   * Returns the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
   * conform to the rules for Dynamo identifiers.
   *
   * @return The alias for the community.
   */
  public String getAlias();

  /**
   * Sets the <EM>alias</EM> of the community.  The alias is a unique identifier for the community that must
   * conform to the rules for Dynamo identifiers.
   *
   * @param caller The user attempting to change the community's alias.
   * @param alias The new alias for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the alias.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the community alias.
   */
  public void setAlias(DynamoUser caller, String alias) throws DatabaseException, DynamoSecurityException;

  /**
   * Returns the date and time at which this community was created.
   *
   * @return The creation date and time for this community.
   */
  public java.util.Date getCreationDate();

  /**
   * Returns the date and time at which this community was last accessed.
   *
   * @return The last access date and time for this community.
   */
  public java.util.Date getLastAccessDate();

  /**
   * Sets the date and time at which this community was last accessed.
   *
   * @param caller The user attempting to change the community's access date/time.
   * @param date The new access date/time for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the access date/time.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the community access date/time.
   */
  public void setLastAccessDate(DynamoUser caller, java.util.Date date)
      throws DatabaseException, DynamoSecurityException;

  /**
   * Returns the date and time at which this community was last updated.
   *
   * @return The last update date and time for this community.
   */
  public java.util.Date getLastUpdateDate();

  /**
   * Sets the date and time at which this community was last updated.
   *
   * @param caller The user attempting to change the community's update date/time.
   * @param date The new update date/time for the community.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error resetting the update date/time.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to
   *            change the community update date/time.
   */
  public void setLastUpdateDate(DynamoUser caller, java.util.Date date)
      throws DatabaseException, DynamoSecurityException;

  /**
   * Grants permission to join the community to a specific user or group.  This permission may be contingent upon
   * the user authenticating with the community in some fashion, and it may also be single-use, meaning the permission
   * is automatically revoked whenever a user uses it to join the community.
   *
   * @param caller The person attempting to grant access to the community.
   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to grant access to.
   * @param auth_namespace The namespace of the authenticator to use to grant access.  If both this parameter and
   *                       <EM>auth_name</EM> are <CODE>null</CODE>, no authentication is required.
   * @param auth_name The name of the authenticator to use to grant access.  If both this parameter and
   *                  <EM>auth_namespace</EM> are <CODE>null</CODE>, no authentication is required.
   * @param source_info The source information for the authenticator.  If <EM>auth_namespace</EM> and
   *                    <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
   * @param auth_info The authentication information (such as a password) for the authenticator.  If
   *                  <EM>auth_namespace</EM> and <EM>auth_name</EM> are <CODE>null</CODE>, this parameter is ignored.
   * @param single_use If this parameter is <CODE>true</CODE>, the permission will automatically be revoked after the
   *                   first time it is successfully used by a user to join the community.
   * @exception com.silverwrist.dynamo.except.AuthenticationException If the named authenticator is not a valid one.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access grant.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to grant
   *            access to this community.
   */
  public void grantAccess(DynamoUser caller, Principal subject, String auth_namespace, String auth_name,
			  String source_info, String auth_info, boolean single_use)
      throws AuthenticationException, DatabaseException, DynamoSecurityException;

  /**
   * Revokes permission to join the community from a specific user or group.  This does not affect any user who
   * has already joined the community.
   *
   * @param caller The person attempting to revoke access to the community.
   * @param subject The {@link com.silverwrist.dynamo.iface.DynamoUser user} or
   *                {@link com.silverwrist.dynamo.iface.DynamoGroup group} that we want to revoke access from.
   * @exception com.silverwrist.dynamo.except.DatabaseException If there was an error registering the access revoke.
   * @exception com.silverwrist.dynamo.except.DynamoSecurityException If the specified user is not permitted to revoke
   *            access to this community.
   */
  public void revokeAccess(DynamoUser caller, Principal subject) throws DatabaseException, DynamoSecurityException;

  /**
   * Tests to see what requirements must be fulfilled by a user to join this community.  Returns values as follows:
   * <UL>
   *   <LI>If the user is not permitted to join the community under any circumstances, this method returns
   *     <CODE>null</CODE>.</LI>
   *   <LI>If the user is already a member of the community, this method returns <CODE>Boolean.FALSE</CODE>.</LI>
   *   <LI>If the user may join the community without any authentication, this method returns
   *     <CODE>Boolean.TRUE</CODE>.</LI>
   *   <LI>Otherwise, the method returns a {@link java.util.Set Set} of
   *     {@link com.silverwrist.dynamo.util.QualifiedNameKey QualifiedNameKey} objects, each of which specifies the
   *     namespace and name of an authenticator which can be used to authenticate the user in order to join this
   *     community.</LI>
   * </UL>
   *
   * @param joiner The user to test 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 void unjoin(DynamoUser unjoiner) throws DatabaseException, DynamoSecurityException;

  public boolean isAdministrator(DynamoUser user);

  public List getServices() throws DatabaseException;

  public boolean isUsingService(String namespace, String name) throws DatabaseException;

  public void addService(DynamoUser caller, Request req, String namespace, String name)
      throws DatabaseException, DynamoSecurityException, CommunityServiceException;

  public void removeService(DynamoUser caller, Request req, String namespace, String name)
      throws DatabaseException, DynamoSecurityException, CommunityServiceException;

  public void setMenuVariables(MenuRenderObject menu) throws DatabaseException;

} // end interface VeniceCommunity
