src/share/classes/java/security/PermissionCollection.java

Print this page


   1 /*
   2  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.security;
  27 
  28 import java.util.*;
  29 
  30 /**
  31  * Abstract class representing a collection of Permission objects.
  32  *
  33  * <p>With a PermissionCollection, you can:
  34  * <UL>
  35  * <LI> add a permission to the collection using the <code>add</code> method.
  36  * <LI> check to see if a particular permission is implied in the
  37  *      collection, using the <code>implies</code> method.
  38  * <LI> enumerate all the permissions, using the <code>elements</code> method.
  39  * </UL>
  40  * <P>
  41  *
  42  * <p>When it is desirable to group together a number of Permission objects
  43  * of the same type, the <code>newPermissionCollection</code> method on that
  44  * particular type of Permission object should first be called. The default
  45  * behavior (from the Permission class) is to simply return null.
  46  * Subclasses of class Permission override the method if they need to store
  47  * their permissions in a particular PermissionCollection object in order
  48  * to provide the correct semantics when the
  49  * <code>PermissionCollection.implies</code> method is called.
  50  * If a non-null value is returned, that PermissionCollection must be used.
  51  * If null is returned, then the caller of <code>newPermissionCollection</code>
  52  * is free to store permissions of the
  53  * given type in any PermissionCollection they choose
  54  * (one that uses a Hashtable, one that uses a Vector, etc).
  55  *
  56  * <p>The PermissionCollection returned by the
  57  * <code>Permission.newPermissionCollection</code>
  58  * method is a homogeneous collection, which stores only Permission objects
  59  * for a given Permission type.  A PermissionCollection may also be
  60  * heterogeneous.  For example, Permissions is a PermissionCollection
  61  * subclass that represents a collection of PermissionCollections.
  62  * That is, its members are each a homogeneous PermissionCollection.
  63  * For example, a Permissions object might have a FilePermissionCollection
  64  * for all the FilePermission objects, a SocketPermissionCollection for all the
  65  * SocketPermission objects, and so on. Its <code>add</code> method adds a
  66  * permission to the appropriate collection.
  67  *
  68  * <p>Whenever a permission is added to a heterogeneous PermissionCollection
  69  * such as Permissions, and the PermissionCollection doesn't yet contain a
  70  * PermissionCollection of the specified permission's type, the
  71  * PermissionCollection should call
  72  * the <code>newPermissionCollection</code> method on the permission's class
  73  * to see if it requires a special PermissionCollection. If
  74  * <code>newPermissionCollection</code>
  75  * returns null, the PermissionCollection
  76  * is free to store the permission in any type of PermissionCollection it
  77  * desires (one using a Hashtable, one using a Vector, etc.). For example,
  78  * the Permissions object uses a default PermissionCollection implementation
  79  * that stores the permission objects in a Hashtable.
  80  *
  81  * <p> Subclass implementations of PermissionCollection should assume
  82  * that they may be called simultaneously from multiple threads,
  83  * and therefore should be synchronized properly.  Furthermore,
  84  * Enumerations returned via the <code>elements</code> method are
  85  * not <em>fail-fast</em>.  Modifications to a collection should not be
  86  * performed while enumerating over that collection.
  87  *
  88  * @see Permission
  89  * @see Permissions
  90  *
  91  *
  92  * @author Roland Schemers
  93  */
  94 
  95 public abstract class PermissionCollection implements java.io.Serializable {
  96 
  97     private static final long serialVersionUID = -6727011328946861783L;
  98 
  99     // when set, add will throw an exception.
 100     private volatile boolean readOnly;
 101 
 102     /**
 103      * Adds a permission object to the current collection of permission objects.
 104      *


 117      * the collection of Permission objects held in this PermissionCollection.
 118      *
 119      * @param permission the Permission object to compare.
 120      *
 121      * @return true if "permission" is implied by the  permissions in
 122      * the collection, false if not.
 123      */
 124     public abstract boolean implies(Permission permission);
 125 
 126     /**
 127      * Returns an enumeration of all the Permission objects in the collection.
 128      *
 129      * @return an enumeration of all the Permissions.
 130      */
 131     public abstract Enumeration<Permission> elements();
 132 
 133     /**
 134      * Marks this PermissionCollection object as "readonly". After
 135      * a PermissionCollection object
 136      * is marked as readonly, no new Permission objects can be added to it
 137      * using <code>add</code>.
 138      */
 139     public void setReadOnly() {
 140         readOnly = true;
 141     }
 142 
 143     /**
 144      * Returns true if this PermissionCollection object is marked as readonly.
 145      * If it is readonly, no new Permission objects can be added to it
 146      * using <code>add</code>.
 147      *
 148      * <p>By default, the object is <i>not</i> readonly. It can be set to
 149      * readonly by a call to <code>setReadOnly</code>.
 150      *
 151      * @return true if this PermissionCollection object is marked as readonly,
 152      * false otherwise.
 153      */
 154     public boolean isReadOnly() {
 155         return readOnly;
 156     }
 157 
 158     /**
 159      * Returns a string describing this PermissionCollection object,
 160      * providing information about all the permissions it contains.
 161      * The format is:
 162      * <pre>
 163      * super.toString() (
 164      *   // enumerate all the Permission
 165      *   // objects and call toString() on them,
 166      *   // one per line..
 167      * )</pre>
 168      *
 169      * <code>super.toString</code> is a call to the <code>toString</code>
 170      * method of this
 171      * object's superclass, which is Object. The result is
 172      * this PermissionCollection's type name followed by this object's
 173      * hashcode, thus enabling clients to differentiate different
 174      * PermissionCollections object, even if they contain the same permissions.
 175      *
 176      * @return information about this PermissionCollection object,
 177      *         as described above.
 178      *
 179      */
 180     public String toString() {
 181         Enumeration<Permission> enum_ = elements();
 182         StringBuilder sb = new StringBuilder();
 183         sb.append(super.toString()+" (\n");
 184         while (enum_.hasMoreElements()) {
 185             try {
 186                 sb.append(" ");
 187                 sb.append(enum_.nextElement().toString());
 188                 sb.append("\n");
 189             } catch (NoSuchElementException e){
   1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.security;
  27 
  28 import java.util.*;
  29 
  30 /**
  31  * Abstract class representing a collection of Permission objects.
  32  *
  33  * <p>With a PermissionCollection, you can:
  34  * <UL>
  35  * <LI> add a permission to the collection using the {@code add} method.
  36  * <LI> check to see if a particular permission is implied in the
  37  *      collection, using the {@code implies} method.
  38  * <LI> enumerate all the permissions, using the {@code elements} method.
  39  * </UL>
  40  * <P>
  41  *
  42  * <p>When it is desirable to group together a number of Permission objects
  43  * of the same type, the {@code newPermissionCollection} method on that
  44  * particular type of Permission object should first be called. The default
  45  * behavior (from the Permission class) is to simply return null.
  46  * Subclasses of class Permission override the method if they need to store
  47  * their permissions in a particular PermissionCollection object in order
  48  * to provide the correct semantics when the
  49  * {@code PermissionCollection.implies} method is called.
  50  * If a non-null value is returned, that PermissionCollection must be used.
  51  * If null is returned, then the caller of {@code newPermissionCollection}
  52  * is free to store permissions of the
  53  * given type in any PermissionCollection they choose
  54  * (one that uses a Hashtable, one that uses a Vector, etc).
  55  *
  56  * <p>The PermissionCollection returned by the
  57  * {@code Permission.newPermissionCollection}
  58  * method is a homogeneous collection, which stores only Permission objects
  59  * for a given Permission type.  A PermissionCollection may also be
  60  * heterogeneous.  For example, Permissions is a PermissionCollection
  61  * subclass that represents a collection of PermissionCollections.
  62  * That is, its members are each a homogeneous PermissionCollection.
  63  * For example, a Permissions object might have a FilePermissionCollection
  64  * for all the FilePermission objects, a SocketPermissionCollection for all the
  65  * SocketPermission objects, and so on. Its {@code add} method adds a
  66  * permission to the appropriate collection.
  67  *
  68  * <p>Whenever a permission is added to a heterogeneous PermissionCollection
  69  * such as Permissions, and the PermissionCollection doesn't yet contain a
  70  * PermissionCollection of the specified permission's type, the
  71  * PermissionCollection should call
  72  * the {@code newPermissionCollection} method on the permission's class
  73  * to see if it requires a special PermissionCollection. If
  74  * {@code newPermissionCollection}
  75  * returns null, the PermissionCollection
  76  * is free to store the permission in any type of PermissionCollection it
  77  * desires (one using a Hashtable, one using a Vector, etc.). For example,
  78  * the Permissions object uses a default PermissionCollection implementation
  79  * that stores the permission objects in a Hashtable.
  80  *
  81  * <p> Subclass implementations of PermissionCollection should assume
  82  * that they may be called simultaneously from multiple threads,
  83  * and therefore should be synchronized properly.  Furthermore,
  84  * Enumerations returned via the {@code elements} method are
  85  * not <em>fail-fast</em>.  Modifications to a collection should not be
  86  * performed while enumerating over that collection.
  87  *
  88  * @see Permission
  89  * @see Permissions
  90  *
  91  *
  92  * @author Roland Schemers
  93  */
  94 
  95 public abstract class PermissionCollection implements java.io.Serializable {
  96 
  97     private static final long serialVersionUID = -6727011328946861783L;
  98 
  99     // when set, add will throw an exception.
 100     private volatile boolean readOnly;
 101 
 102     /**
 103      * Adds a permission object to the current collection of permission objects.
 104      *


 117      * the collection of Permission objects held in this PermissionCollection.
 118      *
 119      * @param permission the Permission object to compare.
 120      *
 121      * @return true if "permission" is implied by the  permissions in
 122      * the collection, false if not.
 123      */
 124     public abstract boolean implies(Permission permission);
 125 
 126     /**
 127      * Returns an enumeration of all the Permission objects in the collection.
 128      *
 129      * @return an enumeration of all the Permissions.
 130      */
 131     public abstract Enumeration<Permission> elements();
 132 
 133     /**
 134      * Marks this PermissionCollection object as "readonly". After
 135      * a PermissionCollection object
 136      * is marked as readonly, no new Permission objects can be added to it
 137      * using {@code add}.
 138      */
 139     public void setReadOnly() {
 140         readOnly = true;
 141     }
 142 
 143     /**
 144      * Returns true if this PermissionCollection object is marked as readonly.
 145      * If it is readonly, no new Permission objects can be added to it
 146      * using {@code add}.
 147      *
 148      * <p>By default, the object is <i>not</i> readonly. It can be set to
 149      * readonly by a call to {@code setReadOnly}.
 150      *
 151      * @return true if this PermissionCollection object is marked as readonly,
 152      * false otherwise.
 153      */
 154     public boolean isReadOnly() {
 155         return readOnly;
 156     }
 157 
 158     /**
 159      * Returns a string describing this PermissionCollection object,
 160      * providing information about all the permissions it contains.
 161      * The format is:
 162      * <pre>
 163      * super.toString() (
 164      *   // enumerate all the Permission
 165      *   // objects and call toString() on them,
 166      *   // one per line..
 167      * )</pre>
 168      *
 169      * {@code super.toString} is a call to the {@code toString}
 170      * method of this
 171      * object's superclass, which is Object. The result is
 172      * this PermissionCollection's type name followed by this object's
 173      * hashcode, thus enabling clients to differentiate different
 174      * PermissionCollections object, even if they contain the same permissions.
 175      *
 176      * @return information about this PermissionCollection object,
 177      *         as described above.
 178      *
 179      */
 180     public String toString() {
 181         Enumeration<Permission> enum_ = elements();
 182         StringBuilder sb = new StringBuilder();
 183         sb.append(super.toString()+" (\n");
 184         while (enum_.hasMoreElements()) {
 185             try {
 186                 sb.append(" ");
 187                 sb.append(enum_.nextElement().toString());
 188                 sb.append("\n");
 189             } catch (NoSuchElementException e){