ojluni/src/main/java/java/security/PermissionCollection.java - platform/libcore.git - Git at Google

 /*
  * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */

 package java.security;

 import java.util.*;

 /**
  * Abstract class representing a collection of Permission objects.
  *
  * <p>With a PermissionCollection, you can:
  * <UL>
  * <LI> add a permission to the collection using the <code>add</code> method.
  * <LI> check to see if a particular permission is implied in the
  *      collection, using the <code>implies</code> method.
  * <LI> enumerate all the permissions, using the <code>elements</code> method.
  * </UL>
  * <P>
  *
  * <p>When it is desirable to group together a number of Permission objects
  * of the same type, the <code>newPermissionCollection</code> method on that
  * particular type of Permission object should first be called. The default
  * behavior (from the Permission class) is to simply return null.
  * Subclasses of class Permission override the method if they need to store
  * their permissions in a particular PermissionCollection object in order
  * to provide the correct semantics when the
  * <code>PermissionCollection.implies</code> method is called.
  * If a non-null value is returned, that PermissionCollection must be used.
  * If null is returned, then the caller of <code>newPermissionCollection</code>
  * is free to store permissions of the
  * given type in any PermissionCollection they choose
  * (one that uses a Hashtable, one that uses a Vector, etc).
  *
  * <p>The PermissionCollection returned by the
  * <code>Permission.newPermissionCollection</code>
  * method is a homogeneous collection, which stores only Permission objects
  * for a given Permission type.  A PermissionCollection may also be
  * heterogeneous.  For example, Permissions is a PermissionCollection
  * subclass that represents a collection of PermissionCollections.
  * That is, its members are each a homogeneous PermissionCollection.
  * For example, a Permissions object might have a FilePermissionCollection
  * for all the FilePermission objects, a SocketPermissionCollection for all the
  * SocketPermission objects, and so on. Its <code>add</code> method adds a
  * permission to the appropriate collection.
  *
  * <p>Whenever a permission is added to a heterogeneous PermissionCollection
  * such as Permissions, and the PermissionCollection doesn't yet contain a
  * PermissionCollection of the specified permission's type, the
  * PermissionCollection should call
  * the <code>newPermissionCollection</code> method on the permission's class
  * to see if it requires a special PermissionCollection. If
  * <code>newPermissionCollection</code>
  * returns null, the PermissionCollection
  * is free to store the permission in any type of PermissionCollection it
  * desires (one using a Hashtable, one using a Vector, etc.). For example,
  * the Permissions object uses a default PermissionCollection implementation
  * that stores the permission objects in a Hashtable.
  *
  * <p> Subclass implementations of PermissionCollection should assume
  * that they may be called simultaneously from multiple threads,
  * and therefore should be synchronized properly.  Furthermore,
  * Enumerations returned via the <code>elements</code> method are
  * not <em>fail-fast</em>.  Modifications to a collection should not be
  * performed while enumerating over that collection.
  *
  * @see Permission
  * @see Permissions
  *
  *
  * @author Roland Schemers
  */

 public abstract class PermissionCollection implements java.io.Serializable {

     private static final long serialVersionUID = -6727011328946861783L;

     // when set, add will throw an exception.
     private volatile boolean readOnly;

     /**
      * Adds a permission object to the current collection of permission objects.
      *
      * @param permission the Permission object to add.
      *
      * @exception SecurityException -  if this PermissionCollection object
      *                                 has been marked readonly
      * @exception IllegalArgumentException - if this PermissionCollection
      *                object is a homogeneous collection and the permission
      *                is not of the correct type.
      */
     public abstract void add(Permission permission);

     /**
      * Checks to see if the specified permission is implied by
      * the collection of Permission objects held in this PermissionCollection.
      *
      * @param permission the Permission object to compare.
      *
      * @return true if "permission" is implied by the  permissions in
      * the collection, false if not.
      */
     public abstract boolean implies(Permission permission);

     /**
      * Returns an enumeration of all the Permission objects in the collection.
      *
      * @return an enumeration of all the Permissions.
      */
     public abstract Enumeration<Permission> elements();

     /**
      * Marks this PermissionCollection object as "readonly". After
      * a PermissionCollection object
      * is marked as readonly, no new Permission objects can be added to it
      * using <code>add</code>.
      */
     public void setReadOnly() {
         readOnly = true;
     }

     /**
      * Returns true if this PermissionCollection object is marked as readonly.
      * If it is readonly, no new Permission objects can be added to it
      * using <code>add</code>.
      *
      * <p>By default, the object is <i>not</i> readonly. It can be set to
      * readonly by a call to <code>setReadOnly</code>.
      *
      * @return true if this PermissionCollection object is marked as readonly,
      * false otherwise.
      */
     public boolean isReadOnly() {
         return readOnly;
     }

     /**
      * Returns a string describing this PermissionCollection object,
      * providing information about all the permissions it contains.
      * The format is:
      * <pre>
      * super.toString() (
      *   // enumerate all the Permission
      *   // objects and call toString() on them,
      *   // one per line..
      * )</pre>
      *
      * <code>super.toString</code> is a call to the <code>toString</code>
      * method of this
      * object's superclass, which is Object. The result is
      * this PermissionCollection's type name followed by this object's
      * hashcode, thus enabling clients to differentiate different
      * PermissionCollections object, even if they contain the same permissions.
      *
      * @return information about this PermissionCollection object,
      *         as described above.
      *
      */
     public String toString() {
         Enumeration<Permission> enum_ = elements();
         StringBuilder sb = new StringBuilder();
         sb.append(super.toString()+" (\n");
         while (enum_.hasMoreElements()) {
             try {
                 sb.append(" ");
                 sb.append(enum_.nextElement().toString());
                 sb.append("\n");
             } catch (NoSuchElementException e){
                 // ignore
             }
         }
         sb.append(")\n");
         return sb.toString();
     }
 }
	/*
	* Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.security;

	import java.util.*;

	/**
	* Abstract class representing a collection of Permission objects.
	*
	* <p>With a PermissionCollection, you can:
	* <UL>
	* <LI> add a permission to the collection using the <code>add</code> method.
	* <LI> check to see if a particular permission is implied in the
	* collection, using the <code>implies</code> method.
	* <LI> enumerate all the permissions, using the <code>elements</code> method.
	* </UL>
	* <P>
	*
	* <p>When it is desirable to group together a number of Permission objects
	* of the same type, the <code>newPermissionCollection</code> method on that
	* particular type of Permission object should first be called. The default
	* behavior (from the Permission class) is to simply return null.
	* Subclasses of class Permission override the method if they need to store
	* their permissions in a particular PermissionCollection object in order
	* to provide the correct semantics when the
	* <code>PermissionCollection.implies</code> method is called.
	* If a non-null value is returned, that PermissionCollection must be used.
	* If null is returned, then the caller of <code>newPermissionCollection</code>
	* is free to store permissions of the
	* given type in any PermissionCollection they choose
	* (one that uses a Hashtable, one that uses a Vector, etc).
	*
	* <p>The PermissionCollection returned by the
	* <code>Permission.newPermissionCollection</code>
	* method is a homogeneous collection, which stores only Permission objects
	* for a given Permission type. A PermissionCollection may also be
	* heterogeneous. For example, Permissions is a PermissionCollection
	* subclass that represents a collection of PermissionCollections.
	* That is, its members are each a homogeneous PermissionCollection.
	* For example, a Permissions object might have a FilePermissionCollection
	* for all the FilePermission objects, a SocketPermissionCollection for all the
	* SocketPermission objects, and so on. Its <code>add</code> method adds a
	* permission to the appropriate collection.
	*
	* <p>Whenever a permission is added to a heterogeneous PermissionCollection
	* such as Permissions, and the PermissionCollection doesn't yet contain a
	* PermissionCollection of the specified permission's type, the
	* PermissionCollection should call
	* the <code>newPermissionCollection</code> method on the permission's class
	* to see if it requires a special PermissionCollection. If
	* <code>newPermissionCollection</code>
	* returns null, the PermissionCollection
	* is free to store the permission in any type of PermissionCollection it
	* desires (one using a Hashtable, one using a Vector, etc.). For example,
	* the Permissions object uses a default PermissionCollection implementation
	* that stores the permission objects in a Hashtable.
	*
	* <p> Subclass implementations of PermissionCollection should assume
	* that they may be called simultaneously from multiple threads,
	* and therefore should be synchronized properly. Furthermore,
	* Enumerations returned via the <code>elements</code> method are
	* not <em>fail-fast</em>. Modifications to a collection should not be
	* performed while enumerating over that collection.
	*
	* @see Permission
	* @see Permissions
	*
	*
	* @author Roland Schemers
	*/

	public abstract class PermissionCollection implements java.io.Serializable {

	private static final long serialVersionUID = -6727011328946861783L;

	// when set, add will throw an exception.
	private volatile boolean readOnly;

	/**
	* Adds a permission object to the current collection of permission objects.
	*
	* @param permission the Permission object to add.
	*
	* @exception SecurityException - if this PermissionCollection object
	* has been marked readonly
	* @exception IllegalArgumentException - if this PermissionCollection
	* object is a homogeneous collection and the permission
	* is not of the correct type.
	*/
	public abstract void add(Permission permission);

	/**
	* Checks to see if the specified permission is implied by
	* the collection of Permission objects held in this PermissionCollection.
	*
	* @param permission the Permission object to compare.
	*
	* @return true if "permission" is implied by the permissions in
	* the collection, false if not.
	*/
	public abstract boolean implies(Permission permission);

	/**
	* Returns an enumeration of all the Permission objects in the collection.
	*
	* @return an enumeration of all the Permissions.
	*/
	public abstract Enumeration<Permission> elements();

	/**
	* Marks this PermissionCollection object as "readonly". After
	* a PermissionCollection object
	* is marked as readonly, no new Permission objects can be added to it
	* using <code>add</code>.
	*/
	public void setReadOnly() {
	readOnly = true;
	}

	/**
	* Returns true if this PermissionCollection object is marked as readonly.
	* If it is readonly, no new Permission objects can be added to it
	* using <code>add</code>.
	*
	* <p>By default, the object is <i>not</i> readonly. It can be set to
	* readonly by a call to <code>setReadOnly</code>.
	*
	* @return true if this PermissionCollection object is marked as readonly,
	* false otherwise.
	*/
	public boolean isReadOnly() {
	return readOnly;
	}

	/**
	* Returns a string describing this PermissionCollection object,
	* providing information about all the permissions it contains.
	* The format is:
	* <pre>
	* super.toString() (
	* // enumerate all the Permission
	* // objects and call toString() on them,
	* // one per line..
	* )</pre>
	*
	* <code>super.toString</code> is a call to the <code>toString</code>
	* method of this
	* object's superclass, which is Object. The result is
	* this PermissionCollection's type name followed by this object's
	* hashcode, thus enabling clients to differentiate different
	* PermissionCollections object, even if they contain the same permissions.
	*
	* @return information about this PermissionCollection object,
	* as described above.
	*
	*/
	public String toString() {
	Enumeration<Permission> enum_ = elements();
	StringBuilder sb = new StringBuilder();
	sb.append(super.toString()+" (\n");
	while (enum_.hasMoreElements()) {
	try {
	sb.append(" ");
	sb.append(enum_.nextElement().toString());
	sb.append("\n");
	} catch (NoSuchElementException e){
	// ignore
	}
	}
	sb.append(")\n");
	return sb.toString();
	}
	}