Save This Page
Home » openjdk-7 » java » security » [javadoc | source]
    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        *
  105        * @param permission the Permission object to add.
  106        *
  107        * @exception SecurityException -  if this PermissionCollection object
  108        *                                 has been marked readonly
  109        * @exception IllegalArgumentException - if this PermissionCollection
  110        *                object is a homogeneous collection and the permission
  111        *                is not of the correct type.
  112        */
  113       public abstract void add(Permission permission);
  114   
  115       /**
  116        * Checks to see if the specified permission is implied by
  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){
  190                   // ignore
  191               }
  192           }
  193           sb.append(")\n");
  194           return sb.toString();
  195       }
  196   }

Save This Page
Home » openjdk-7 » java » security » [javadoc | source]