home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / Acl.java < prev    next >
Text File  |  1998-01-23  |  10KB  |  252 lines
  1. /*
  2.  * @(#)Acl.java    1.12 97/01/30
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.security.acl;
  24.  
  25. import java.util.Enumeration;
  26. import java.security.Principal;
  27.  
  28. /**
  29.  * Interface representing an Access Control List (ACL).  An Access
  30.  * Control List is a data structure used to guard access to
  31.  * resources.<p>
  32.  *
  33.  * An ACL can be thought of as a data structure with multiple ACL
  34.  * entries.  Each ACL entry, of interface type AclEntry, contains a
  35.  * set of permissions associated with a particular principal. (A
  36.  * principal represents an entity such as an individual user or a
  37.  * group). Additionally, each ACL entry is specified as being either
  38.  * positive or negative. If positive, the permissions are to be
  39.  * granted to the associated principal. If negative, the permissions
  40.  * are to be denied.<p>
  41.  *
  42.  * The ACL Entries in each ACL observe the following rules:<p>
  43.  *
  44.  * <ul> <li>Each principal can have at most one positive ACL entry and
  45.  * one negative entry; that is, multiple positive or negative ACL
  46.  * entries are not allowed for any principal.  Each entry specifies
  47.  * the set of permissions that are to be granted (if positive) or
  48.  * denied (if negative). <p>
  49.  * 
  50.  * <li>If there is no entry for a particular principal, then the
  51.  * principal is considered to have a null (empty) permission set.<p>
  52.  *
  53.  * <li>If there is a positive entry that grants a principal a
  54.  * particular permission, and a negative entry that denies the
  55.  * principal the same permission, the result is as though the
  56.  * permission was never granted or denied. <p>
  57.  *
  58.  * <li>Individual permissions always override permissions of the
  59.  * group(s) to which the individual belongs. That is, individual
  60.  * negative permissions (specific denial of permissions) override the
  61.  * groups' positive permissions. And individual positive permissions
  62.  * override the groups' negative permissions.<p>
  63.  *
  64.  * </ul>
  65.  *
  66.  * The <code> java.security.acl </code> package provides the
  67.  * interfaces to the ACL and related data structures (ACL entries,
  68.  * groups, permissions, etc.), and the <code> sun.security.acl </code>
  69.  * classes provide a default implementation of the interfaces. For
  70.  * example, <code> java.security.acl.Acl </code> provides the
  71.  * interface to an ACL and the <code> sun.security.acl.AclImpl </code>
  72.  * class provides the default implementation of the interface.<p>
  73.  * 
  74.  * The <code> java.security.acl.Acl </code> interface extends the
  75.  * <code> java.security.acl.Owner </code> interface. The Owner
  76.  * interface is used to maintain a list of owners for each ACL.  Only
  77.  * owners are allowed to modify an ACL. For example, only an owner can
  78.  * call the ACL's <code>addEntry</code> method to add a new ACL entry 
  79.  * to the ACL.
  80.  * 
  81.  * @see java.security.acl.AclEntry
  82.  * @see java.security.acl.Owner
  83.  * @see java.security.acl.Acl#getPermissions
  84.  * 
  85.  * @version 1.12, 97/11/25
  86.  * @author Satish Dharmaraj 
  87.  */
  88.  
  89. public interface Acl extends Owner {
  90.  
  91.     /**
  92.      * Sets the name of this ACL.
  93.      *
  94.      * @param caller the principal invoking this method. It must be an
  95.      * owner of this ACL.
  96.      *
  97.      * @param name the name to be given to this ACL.
  98.      *
  99.      * @exception NotOwnerException if the caller principal
  100.      * is not an owner of this ACL.  
  101.      */
  102.     public void setName(Principal caller, String name)
  103.       throws NotOwnerException;
  104.  
  105.     /**
  106.      * Returns the name of this ACL. 
  107.      *
  108.      * @return the name of this ACL.
  109.      */
  110.     public String getName();
  111.  
  112.     /**
  113.      * Adds an ACL entry to this ACL. An entry associates a principal
  114.      * (e.g., an individual or a group) with a set of
  115.      * permissions. Each principal can have at most one positive ACL
  116.      * entry (specifying permissions to be granted to the principal)
  117.      * and one negative ACL entry (specifying permissions to be
  118.      * denied). If there is already an ACL entry of the same type
  119.      * (negative or positive) already in the ACL, false is returned.
  120.      * 
  121.      * @param caller the principal invoking this method. It must be an
  122.      * owner of this ACL.
  123.      *
  124.      * @param entry the ACL entry to be added to this ACL.
  125.      *
  126.      * @return true on success, false if an entry of the same type
  127.      * (positive or negative) for the same principal is already
  128.      * present in this ACL.
  129.      *
  130.      * @exception NotOwnerException if the caller principal
  131.      *  is not an owner of this ACL.  
  132.      */
  133.     public boolean addEntry(Principal caller, AclEntry entry)
  134.       throws NotOwnerException;
  135.  
  136.     /**
  137.      * Removes an ACL entry from this ACL.
  138.      * 
  139.      * @param caller the principal invoking this method. It must be an
  140.      * owner of this ACL.
  141.      *  
  142.      * @param entry the ACL entry to be removed from this ACL.
  143.      * 
  144.      * @return true on success, false if the entry is not part of this ACL.
  145.      * 
  146.      * @exception NotOwnerException if the caller principal is not
  147.      * an owner of this Acl.
  148.      */
  149.     public boolean removeEntry(Principal caller, AclEntry entry)
  150.           throws NotOwnerException;
  151.  
  152.     /**
  153.      * Returns an enumeration for the set of allowed permissions for the 
  154.      * specified principal (representing an entity such as an individual or 
  155.      * a group). This set of allowed permissions is calculated as
  156.      * follows:<p>
  157.      *
  158.      * <ul>
  159.      *  
  160.      * <li>If there is no entry in this Access Control List for the 
  161.      * specified principal, an empty permission set is returned.<p>
  162.      * 
  163.      * <li>Otherwise, the principal's group permission sets are determined.
  164.      * (A principal can belong to one or more groups, where a group is a 
  165.      * group of principals, represented by the Group interface.)
  166.      * The group positive permission set is the union of all 
  167.      * the positive permissions of each group that the principal belongs to.
  168.      * The group negative permission set is the union of all 
  169.      * the negative permissions of each group that the principal belongs to.
  170.      * If there is a specific permission that occurs in both 
  171.      * the positive permission set and the negative permission set, 
  172.      * it is removed from both.<p>
  173.      *
  174.      * The individual positive and negative permission sets are also 
  175.      * determined. The positive permission set contains the permissions 
  176.      * specified in the positive ACL entry (if any) for the principal. 
  177.      * Similarly, the negative permission set contains the permissions
  178.      * specified in the negative ACL entry (if any) for the principal. 
  179.      * The individual positive (or negative) permission set is considered 
  180.      * to be null if there is not a positive (negative) ACL entry for the
  181.      * principal in this ACL.<p>
  182.      *
  183.      * The set of permissions granted to the principal is then calculated 
  184.      * using the simple rule that individual permissions always override 
  185.      * the group permissions. That is, the principal's individual negative
  186.      * permission set (specific denial of permissions) overrides the group 
  187.      * positive permission set, and the principal's individual positive 
  188.      * permission set overrides the group negative permission set. 
  189.      * 
  190.      * </ul>
  191.      *
  192.      * @param user the principal whose permission set is to be returned.
  193.      * 
  194.      * @return the permission set specifying the permissions the principal 
  195.      * is allowed. 
  196.      */
  197.     public Enumeration getPermissions(Principal user);
  198.  
  199.     /**
  200.      * Returns an enumeration of the entries in this ACL. Each element in 
  201.      * the enumeration is of type AclEntry.
  202.      * 
  203.      * @return an enumeration of the entries in this ACL.
  204.      */
  205.     public Enumeration entries();
  206.  
  207.     /**
  208.      * Checks whether or not the specified principal has the specified 
  209.      * permission. If it does, true is returned, otherwise false is returned.
  210.      * 
  211.      * More specifically, this method checks whether the passed permission
  212.      * is a member of the allowed permission set of the specified principal.
  213.      * The allowed permission set is determined by the same algorithm as is 
  214.      * used by the <code>getPermissions</code> method.
  215.      * 
  216.      * @param principal the principal, assumed to be a valid authenticated 
  217.      * Principal.
  218.      * 
  219.      * @param permission the permission to be checked for.
  220.      * 
  221.      * @return true if the principal has the specified permission, false 
  222.      * otherwise.
  223.      * 
  224.      * @see #getPermissions
  225.      */
  226.     public boolean checkPermission(Principal principal, Permission permission);
  227.  
  228.     /**
  229.      * Returns a string representation of the 
  230.      * ACL contents.
  231.      * 
  232.      * @return a string representation of the ACL contents.
  233.      */
  234.     public String toString();
  235. }
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.