With a PermissionCollection, you can: *
When it is desirable to group together a number of Permission objects * of the same type, the {@code newPermissionCollection} 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} 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} * 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). * *
The PermissionCollection returned by the * {@code Permission.newPermissionCollection} * 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} method adds a * permission to the appropriate collection. * *
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} method on the permission's class * to see if it requires a special PermissionCollection. If * {@code newPermissionCollection} * 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. * *
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} method are
* not fail-fast. 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.
* @see #elementsAsStream()
*/
public abstract Enumeration The collection should not be modified (see {@link #add}) during the
* execution of the terminal stream operation. Otherwise, the result of the
* terminal stream operation is undefined.
*
* @implSpec
* The default implementation creates a stream whose source is derived from
* the enumeration returned from a call to {@link #elements()}.
*
* @return a stream of all the Permissions.
* @since 9
*/
public Stream By default, the object is not readonly. It can be set to
* readonly by a call to {@code setReadOnly}.
*
* @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:
*
* super.toString() (
* // enumerate all the Permission
* // objects and call toString() on them,
* // one per line..
* )
*
* {@code super.toString} is a call to the {@code toString}
* 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