libjava/java/security/PermissionCollection.java

   1 /* PermissionCollection.java -- A collection of permission objects
   2    Copyright (C) 1998 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 As a special exception, if you link this library with other files to
  22 produce an executable, this library does not by itself cause the
  23 resulting executable to be covered by the GNU General Public License.
  24 This exception does not however invalidate any other reasons why the
  25 executable file might be covered by the GNU General Public License. */
  26
  27
  28 package java.security;
  29
  30 import java.io.Serializable;
  31 import java.util.Enumeration;
  32
  33 /**
  34   * This class models a group of Java permissions.  It has convenient
  35   * methods for determining whether or not a given permission is implied
  36   * by any of the permissions in this collection.
  37   * <p>
  38   * Some care must be taken in storing permissions.  First, a collection of
  39   * the appropriate type must be created.  This is done by calling the
  40   * <code>newPermissionCollection</code> method on an object of the
  41   * permission class you wish to add to the collection.  If this method
  42   * returns <code>null</code>, any type of <code>PermissionCollection</code>
  43   * can be used to store permissions of that type.  However, if a
  44   * <code>PermissionCollection</code> collection object is returned, that
  45   * type must be used.
  46   * <p>
  47   * The <code>PermissionCollection</code>'s returned
  48   * by the <code>newPermissionCollection</code> instance in a subclass of
  49   * <code>Permission</code> is a homogeneous collection.  It only will
  50   * hold permissions of one specified type - instances of the class that
  51   * created it.  Not all <code>PermissionCollection</code> subclasses
  52   * have to hold permissions of only one type however.  For example,
  53   * the <code>Permissions</code> class holds permissions of many types.
  54   * <p>
  55   * Since the <code>newPermissionCollection</code> in <code>Permission</code>
  56   * itself returns <code>null</code>, by default a permission can be stored
  57   * in any type of collection unless it overrides that method to create its
  58   * own collection type.
  59   *
  60   * @version 0.0
  61   *
  62   * @author Aaron M. Renn (arenn@urbanophile.com)
  63   */
  64 public abstract class PermissionCollection extends Object implements Serializable
  65 {
  66
  67 /*************************************************************************/
  68
  69 /*
  70  * Class Variables
  71  */
  72
  73 public static final String linesep = null;
  74
  75 static
  76 {
  77   String linesep = System.getProperty("line.separator");
  78   if (linesep == null);
  79     linesep = "\n";
  80 }
  81
  82 /*************************************************************************/
  83
  84 /*
  85  * Instance Variables
  86  */
  87
  88 /**
  89   * Indicates whether or not this collection is read only.
  90   */
  91 private boolean readOnly;
  92
  93 /*************************************************************************/
  94
  95 /*
  96  * Constructors
  97  */
  98
  99 /**
 100   * This method initializes a new instance of <code>PermissionCollection</code>.
 101   * This is provided only as a default constructor and does nothing in this
 102   * class.
 103   */
 104 public
 105 PermissionCollection()
 106 {
 107   ;
 108 }
 109
 110 /*************************************************************************/
 111
 112 /*
 113  * Instance Methods
 114  */
 115
 116 /**
 117   * This method tests whether or not this <code>PermissionCollection</code>
 118   * object is read only.
 119   *
 120   * @return <code>true</code> if this collection is read only, <code>false</code> otherwise
 121   */
 122 public boolean
 123 isReadOnly()
 124 {
 125   return(readOnly);
 126 }
 127
 128 /*************************************************************************/
 129
 130 /**
 131   * This method sets this <code>PermissionCollection</code> object to be
 132   * read only.  No further permissions can be added to it after calling this
 133   * method.
 134   */
 135 public void
 136 setReadOnly()
 137 {
 138   readOnly = true;
 139 }
 140
 141 /*************************************************************************/
 142
 143 /**
 144   * This method adds a new <code>Permission</code> object to the collection.
 145   *
 146   * @param perm The <code>Permission</code> to add.
 147   *
 148   * @exception SecurityException If the collection is marked read only.
 149   * @exception IllegalArgumentException If a permission of the specified type cannot be added
 150   */
 151 public abstract void
 152 add(Permission perm) throws SecurityException, IllegalArgumentException;
 153
 154 /*************************************************************************/
 155
 156 /**
 157   * This method returns an <code>Enumeration</code> of all the objects in
 158   * this collection.
 159   *
 160   * @return An <code>Enumeration</code> of this collection's objects.
 161   */
 162 public abstract Enumeration
 163 elements();
 164
 165 /*************************************************************************/
 166
 167 /**
 168   * This method tests whether the specified <code>Permission</code> object is
 169   * implied by this collection of <code>Permission</code> objects.
 170   *
 171   * @param perm The <code>Permission</code> object to test.
 172   *
 173   * @return <code>true</code> if the specified <code>Permission</code> is implied by this collection, <code>false</code> otherwise.
 174   */
 175 public abstract boolean
 176 implies(Permission perm);
 177
 178 /*************************************************************************/
 179
 180 /**
 181   * This method returns a <code>String</code> representation of this
 182   * collection.  It will print the class name and has code in the same
 183   * manner as <code>Object.toString()</code> then print a listing of all
 184   * the <code>Permission</code> objects contained.
 185   *
 186   * @return A <code>String</code> representing this object.
 187   */
 188 public String
 189 toString()
 190 {
 191   StringBuffer sb = new StringBuffer("");
 192
 193   sb.append(super.toString() + " (" + linesep);
 194   Enumeration e = elements();
 195   while (e.hasMoreElements())
 196     {
 197       Object obj = e.nextElement();
 198       if (obj instanceof Permission)
 199         sb.append(((Permission)obj).toString() + linesep);
 200     }
 201
 202   sb.append(")" + linesep);
 203   return(sb.toString());
 204 }
 205
 206 } // class PermissionCollection
 207