home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / security / PermissionCollection.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  6.2 KB  |  172 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)PermissionCollection.java    1.22 98/06/29
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. import java.util.*;
  18.  
  19. /**
  20.  * Abstract class representing a collection of Permission objects.
  21.  *
  22.  * <p>With a PermissionCollection, you can:
  23.  * <UL>
  24.  * <LI> add a permission to the collection using the <code>add</code> method.
  25.  * <LI> check to see if a particular permission is implied in the
  26.  *      collection, using the <code>implies</code> method.
  27.  * <LI> enumerate all the permissions, using the <code>elements</code> method.
  28.  * </UL>
  29.  * <P>
  30.  *
  31.  * <p>When it is desirable to group together a number of Permission objects of the
  32.  * same type, the <code>newPermissionCollection</code> method on that particular
  33.  * type of Permission object should first be called. The default behavior (from the
  34.  * Permission class) is to simply return null. Subclasses of class Permission
  35.  * override the method if they need to store their permissions in a particular
  36.  * PermissionCollection object in order to provide the correct semantics
  37.  * when the <code>PermissionCollection.implies</code> method is called.
  38.  * If a non-null value is returned, that PermissionCollection must be used.
  39.  * If null is returned, then the caller of <code>newPermissionCollection</code>
  40.  * is free to store permissions of the
  41.  * given type in any PermissionCollection they choose (one that uses a Hashtable,
  42.  * one that uses a Vector, etc).
  43.  *
  44.  * <p>The PermissionCollection returned by the
  45.  * <code>Permission.newPermissionCollection</code>
  46.  * method is a homogeneous collection, which stores only Permission objects
  47.  * for a given Permission type.  A PermissionCollection may also be heterogenous.
  48.  * For example, Permissions is a PermissionCollection subclass that represents a
  49.  * collection of PermissionCollections. That is, its members are each a homogeneous
  50.  * PermissionCollection. For example, a Permissions object might have a
  51.  * FilePermissionCollection
  52.  * for all the FilePermission objects, a SocketPermissionCollection for all the
  53.  * SocketPermission objects, and so on. Its <code>add</code> method adds a permission
  54.  * to the appropriate collection.
  55.  *
  56.  * <p>Whenever a permission is added to a heterogeneous PermissionCollection such
  57.  * as Permissions, and the PermissionCollection doesn't yet contain a
  58.  * PermissionCollection of the specified permission's type, the
  59.  * PermissionCollection should call
  60.  * the <code>newPermissionCollection</code> method on the permission's class
  61.  * to see if it requires a special PermissionCollection. If
  62.  * <code>newPermissionCollection</code>
  63.  * returns null, the PermissionCollection
  64.  * is free to store the permission in any type of PermissionCollection it desires
  65.  * (one using a Hastable, one using a Vector, etc.). For example,
  66.  * the Permissions object uses a default PermissionCollection implementation
  67.  * that stores the permission objects in a Hashtable.
  68.  *
  69.  * @see Permission
  70.  * @see Permissions
  71.  *
  72.  * @version 1.22 99/03/26
  73.  *
  74.  * @author Roland Schemers
  75.  */
  76.  
  77. public abstract class PermissionCollection implements java.io.Serializable {
  78.  
  79.     // when set, add will throw an exception.
  80.     private boolean readOnly;
  81.  
  82.     /**
  83.      * Adds a permission object to the current collection of permission objects.
  84.      *
  85.      * @param permission the Permission object to add.
  86.      */
  87.  
  88.     public abstract void add(Permission permission);
  89.  
  90.     /**
  91.      * Checks to see if the specified permission is implied by
  92.      * the collection of Permission objects held in this PermissionCollection.
  93.      *
  94.      * @param permission the Permission object to compare.
  95.      *
  96.      * @return true if "permission" is implied by the  permissions in
  97.      * the collection, false if not.
  98.      */
  99.     public abstract boolean implies(Permission permission);
  100.  
  101.     /**
  102.      * Returns an enumeration of all the Permission objects in the collection.
  103.      *
  104.      * @return an enumeration of all the Permissions.
  105.      */
  106.     public abstract Enumeration elements();
  107.  
  108.     /**
  109.      * Marks this PermissionCollection object as "readonly". After
  110.      * a PermissionCollection object
  111.      * is marked as readonly, no new Permission objects can be added to it
  112.      * using <code>addPermission</code>.
  113.      */
  114.     public void setReadOnly() {
  115.     readOnly = true;
  116.     }
  117.  
  118.     /**
  119.      * Returns true if this PermissionCollection object is marked as readonly. If it
  120.      * is readonly, no new Permission objects can be added to it
  121.      * using <code>addPermission</code>.
  122.      *
  123.      * <p>By default, the object is <i>not</i> readonly. It can be set to readonly
  124.      * by a call to <code>setReadOnly</code>.
  125.      *
  126.      * @return true if this PermissionCollection object is marked as readonly, false
  127.      * otherwise.
  128.      */
  129.     public boolean isReadOnly() {
  130.     return readOnly;
  131.     }
  132.  
  133.     /**
  134.      * Returns a string describing this PermissionCollection object,
  135.      * providing information about all the permissions it contains.
  136.      * The format is:
  137.      * <pre>
  138.      * super.toString() (
  139.      *   // enumerate all the Permission
  140.      *   // objects and call toString() on them,
  141.      *   // one per line..
  142.      * )</pre>
  143.      *
  144.      * <code>super.toString</code> is a call to the <code>toString</code>
  145.      * method of this
  146.      * object's superclass, which is Object. The result is
  147.      * this PermissionCollection's type name followed by this object's
  148.      * hashcode, thus enabling clients to differentiate different
  149.      * PermissionCollections object, even if they contain the same permissions.
  150.      *
  151.      * @return information about this PermissionCollection object,
  152.      *         as described above.
  153.      *
  154.      */
  155.     public String toString() {
  156.     Enumeration enum = elements();
  157.     StringBuffer sb = new StringBuffer();
  158.     sb.append(super.toString()+" (\n");
  159.     while (enum.hasMoreElements()) {
  160.         try {
  161.         sb.append(" ");
  162.         sb.append(enum.nextElement().toString());
  163.         sb.append("\n");
  164.         } catch (NoSuchElementException e){
  165.         // ignore
  166.         }
  167.     }
  168.     sb.append(")\n");
  169.     return sb.toString();
  170.     }
  171. }
  172.