Module java.base
Package java.security

# Class PermissionCollection

java.lang.Object
java.security.PermissionCollection

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `Permissions`

public abstract class PermissionCollection extends Object implements Serializable
Abstract class representing a collection of Permission objects.

With a `PermissionCollection`, you can:

- add a permission to the collection using the `add` method.
- check to see if a particular permission is implied in the collection, using the `implies` method.
- enumerate all the permissions, using the `elements` method.

When it is desirable to group together a number of `Permission` objects of the same type, the `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 `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 `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 collection returned by the `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 `PermissionCollection` objects. That is, its members are each a homogeneous `PermissionCollection`. For example, a `Permission` object might have a `FilePermissionCollection` for all the `FilePermission` objects, a `SocketPermissionCollection` for all the `SocketPermission` objects, and so on. Its `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 `newPermissionCollection` method on the permission's class to see if it requires a special `PermissionCollection`. If `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 `elements` method are not fail-fast. Modifications to a collection should not be performed while enumerating over that collection.

Since:
  1.2
See Also:
  - `Permission`
  - `Permissions`
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PermissionCollection()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `add(Permission permission)`
  Adds a permission object to the current collection of permission objects.
  `abstract Enumeration<Permission>`
  `elements()`
  Returns an enumeration of all the Permission objects in the collection.
  `Stream<Permission>`
  `elementsAsStream()`
  Returns a stream of all the Permission objects in the collection.
  `abstract boolean`
  `implies(Permission permission)`
  Checks to see if the specified permission is implied by the collection of `Permission` objects held in this `PermissionCollection`.
  `boolean`
  `isReadOnly()`
  Returns `true` if this `PermissionCollection` object is marked as readonly.
  `void`
  `setReadOnly()`
  Marks this `PermissionCollection` object as "readonly".
  `String`
  `toString()`
  Returns a string describing this `PermissionCollection` object, providing information about all the permissions it contains.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### PermissionCollection

    public PermissionCollection()
    Constructor for subclasses to call.

- ## Method Details

  - ### add

    public abstract void add(Permission permission)
    Adds a permission object to the current collection of permission objects.
    Parameters:
      `permission` - the Permission object to add.
    Throws:
      `SecurityException` - if this `PermissionCollection` object has been marked readonly
      `IllegalArgumentException` - if this `PermissionCollection` object is a homogeneous collection and the permission is not of the correct type.

  - ### implies

    public abstract boolean implies(Permission permission)
    Checks to see if the specified permission is implied by the collection of `Permission` objects held in this `PermissionCollection`.
    Parameters:
      `permission` - the `Permission` object to compare.
    Returns:
      `true` if "permission" is implied by the permissions in the collection, `false` if not.

  - ### elements

    public abstract Enumeration<Permission> elements()
    Returns an enumeration of all the Permission objects in the collection.
    Returns:
      an enumeration of all the Permissions.
    See Also:
      - `elementsAsStream()`

  - ### elementsAsStream

    public Stream<Permission> elementsAsStream()
    Returns a stream of all the Permission objects in the collection.

    The collection should not be modified (see `add(java.security.Permission)`) during the execution of the terminal stream operation. Otherwise, the result of the terminal stream operation is undefined.

    Implementation Requirements:
      The default implementation creates a stream whose source is derived from the enumeration returned from a call to `elements()`.
    Returns:
      a stream of all the Permissions.
    Since:
      9

  - ### setReadOnly

    public void setReadOnly()
    Marks this `PermissionCollection` object as "readonly". After a `PermissionCollection` object is marked as readonly, no new `Permission` objects can be added to it using `add`.

  - ### isReadOnly

    public boolean isReadOnly()
    Returns `true` if this `PermissionCollection` object is marked as readonly. If it is readonly, no new `Permission` objects can be added to it using `add`.

    By default, the object is not readonly. It can be set to readonly by a call to `setReadOnly`.

    Returns:
      `true` if this `PermissionCollection` object is marked as readonly, `false` otherwise.

  - ### toString

    public String toString()
    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..
         )

    `super.toString` is a call to the `toString` method of this object's superclass, which is `Object`. The result is this collection's type name followed by this object's hashcode, thus enabling clients to differentiate different `PermissionCollection` objects, even if they contain the same permissions.
    Overrides:
      `toString` in class `Object`
    Returns:
      information about this `PermissionCollection` object, as described above.