libjava/classpath/java/security/PermissionCollection.java

   1 /* PermissionCollection.java -- A collection of permission objects
   2    Copyright (C) 1998, 2001, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.security;
  39
  40 import gnu.java.lang.CPStringBuilder;
  41
  42 import java.io.Serializable;
  43 import java.util.Enumeration;
  44
  45 /**
  46  * This class models a group of Java permissions.  It has convenient
  47  * methods for determining whether or not a given permission is implied
  48  * by any of the permissions in this collection.
  49  *
  50  * <p>Some care must be taken in storing permissions.  First, a collection of
  51  * the appropriate type must be created.  This is done by calling the
  52  * <code>newPermissionCollection</code> method on an object of the
  53  * permission class you wish to add to the collection.  If this method
  54  * returns <code>null</code>, any type of <code>PermissionCollection</code>
  55  * can be used to store permissions of that type.  However, if a
  56  * <code>PermissionCollection</code> collection object is returned, that
  57  * type must be used.
  58  *
  59  * <p>A <code>PermissionCollection</code> returned by the
  60  * <code>newPermissionCollection</code> method in a subclass of
  61  * <code>Permission</code> is a homogeneous collection.  It only will
  62  * hold permissions of one specified type - instances of the class that
  63  * created it.  Not all <code>PermissionCollection</code> subclasses
  64  * have to hold permissions of only one type however.  For example,
  65  * the <code>Permissions</code> class holds permissions of many types.
  66  *
  67  * <p>Since the <code>newPermissionCollection</code> in <code>Permission</code>
  68  * itself returns <code>null</code>, by default a permission can be stored
  69  * in any type of collection unless it overrides that method to create its
  70  * own collection type.
  71  *
  72  * @author Aaron M. Renn (arenn@urbanophile.com)
  73  * @author Eric Blake (ebb9@email.byu.edu)
  74  * @see Permission
  75  * @see Permissions
  76  * @since 1.1
  77  * @status updated to 1.4
  78  */
  79 public abstract class PermissionCollection implements Serializable
  80 {
  81   /**
  82    * Compatible with JDK 1.1+.
  83    */
  84   private static final long serialVersionUID = -6727011328946861783L;
  85
  86   /**
  87    * Indicates whether or not this collection is read only.
  88    *
  89    * @serial if the collection is read-only
  90    */
  91   private boolean readOnly;
  92
  93   /**
  94    * Create a new collection.
  95    */
  96   public PermissionCollection()
  97   {
  98   }
  99
 100   /**
 101    * This method adds a new <code>Permission</code> object to the collection.
 102    *
 103    * @param perm the <code>Permission</code> to add
 104    *
 105    * @throws SecurityException if the collection is marked read only
 106    * @throws IllegalArgumentException if perm is of the wrong type
 107    */
 108   public abstract void add(Permission perm);
 109
 110   /**
 111    * This method tests whether the specified <code>Permission</code> object is
 112    * implied by this collection of <code>Permission</code> objects.
 113    *
 114    * @param perm the <code>Permission</code> object to test
 115    * @return true if the collection implies perm
 116    */
 117   public abstract boolean implies(Permission perm);
 118
 119   /**
 120    * This method returns an <code>Enumeration</code> of all the objects in
 121    * this collection.
 122    *
 123    * @return an <code>Enumeration</code> of this collection's objects
 124    */
 125   public abstract Enumeration<Permission> elements();
 126
 127   /**
 128    * This method sets this <code>PermissionCollection</code> object to be
 129    * read only.  No further permissions can be added to it after calling this
 130    * method.
 131    */
 132   public void setReadOnly()
 133   {
 134     readOnly = true;
 135   }
 136
 137   /**
 138    * This method tests whether or not this <code>PermissionCollection</code>
 139    * object is read only.
 140    *
 141    * @return true if this collection is read only
 142    */
 143   public boolean isReadOnly()
 144   {
 145     return readOnly;
 146   }
 147
 148   /**
 149    * This method returns a <code>String</code> representation of this
 150    * collection.  It is formed by:
 151    * <pre>
 152    * super.toString()" (\n"
 153    *   // enumerate all permissions, one per line
 154    * ")\n"
 155    * </pre>
 156    *
 157    * @return a <code>String</code> representing this object
 158    */
 159   public String toString()
 160   {
 161     CPStringBuilder sb = new CPStringBuilder(super.toString());
 162
 163     sb.append(" (\n");
 164     Enumeration<Permission> e = elements();
 165     while (e.hasMoreElements())
 166       sb.append(' ').append(e.nextElement()).append('\n');
 167     return sb.append(")\n").toString();
 168   }
 169 } // class PermissionCollection