/*
 * 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) 2001 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.venice.security;

import java.util.List;
import com.silverwrist.venice.except.AccessError;

/**
 * Defines a service interface for a <EM>security monitor</EM>.  A security monitor is specific to a
 * particular type of object within Venice, and defines the security scope used to deal with that
 * object, the roles used, lists of roles, default role values, and permissions that may be tested.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface SecurityMonitor
{
  /**
   * Tests a specified permission within this security monitor.  If the supplied security level is less
   * than the defined security level for this permission, an exception is thrown.
   *
   * @param symbol The programmatic symbol of the permission to test.
   * @param level The security level to supply for the test.
   * @param errormsg The error message to be thrown if the test fails.  May be <CODE>null</CODE>, in
   *                 which case the security monitor will throw an appropriate default, if applicable.
   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
   *         if the specified permission was not defined within this security monitor.
   * @exception com.silverwrist.venice.except.AccessError If the specified permission was defined but
   *            not satisfied.
   * @see #testPermission(java.lang.String,int)
   */
  public abstract boolean testPermission(String symbol, int level, String errormsg) throws AccessError;

  /**
   * Tests a specified permission within this security monitor.  If the supplied security level is greater
   * than or equal to the defined security level for this permission, <CODE>true</CODE> is returned.
   *
   * @param symbol The programmatic symbol of the permission to test.
   * @param level The security level to supply for the test.
   * @return <CODE>true</CODE> if the specified permission was defined and satisfied; <CODE>false</CODE>
   *         if the specified permission was not defined within this security monitor, or was defined but
   *         not satisfied.
   * @see #testPermission(java.lang.String,int,java.lang.String)
   */
  public abstract boolean testPermission(String symbol, int level);

  /**
   * Determines whether this <CODE>SecurityMonitor</CODE> defines the specified permission symbol.
   *
   * @param symbol The programmatic symbol of the permission to look up.
   * @param no_follow If this is <CODE>true</CODE>, we look only in this <CODE>SecurityMonitor</CODE>
   *                  for the specified permission, and not in any "parent" <CODE>SecurityMonitor</CODE>
   *                  objects.
   * @return <CODE>true</CODE> if this is a defined permission symbol, <CODE>false</CODE> if not.
   */
  public abstract boolean permissionDefined(String symbol, boolean no_follow);

  /**
   * Returns a defined list of roles for this <CODE>SecurityMonitor</CODE>.
   *
   * @param symbol The programmatic symbol of the role list to look up.
   * @return The associated role list, or <CODE>null</CODE> if the role list name was not defined.
   * @see Role
   */
  public abstract List getRoleList(String symbol);

  /**
   * Returns a defined role for this <CODE>SecurityMonitor</CODE>.
   *
   * @param symbol The programmatic symbol of the role to look up.
   * @return The associated role, or <CODE>null</CODE> if the role name was not defined.
   * @see Role
   */
  public abstract Role getRole(String symbol);

  /**
   * Returns the defined role that has the given level.
   *
   * @param level The level value to look up.
   * @return The associated role, or <CODE>null</CODE> if no such role could be found.
   * @see Role
   */
  public abstract Role getRoleForLevel(int level);

  /**
   * Returns a defined default role for this <CODE>SecurityMonitor</CODE>.
   *
   * @param symbol The programmatic symbol of the default role to look up.
   * @return The associated role, or <CODE>null</CODE> if the default role name was not defined.
   * @see Role
   */
  public abstract Role getDefaultRole(String symbol);

  /**
   * Returns the <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
   *
   * @return The <CODE>ScopeInfo</CODE> associated with this <CODE>SecurityMonitor</CODE>.
   * @see ScopeInfo
   */
  public abstract ScopeInfo getScopeInfo();

  /**
   * Returns the identifier for this <CODE>SecurityMonitor</CODE>.
   *
   * @return The identifier for this <CODE>SecurityMonitor</CODE>.
   */
  public abstract String getID();

} // end interface SecurityMonitor
