/*

 * Copyright (c) 1997, 2015, 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.*;

import java.util.stream.Stream;

import java.util.stream.StreamSupport;

/**

 * 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} method.

 * <LI> check to see if a particular permission is implied in the

 *      collection, using the {@code implies} method.

 * <LI> enumerate all the permissions, using the {@code elements} method.

 * </UL>

 *

 * <p>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).

 *

 * <p>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.

 *

 * <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} 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.

 *

 * <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} 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

 * @since 1.2

 */

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<Permission> elements();

    /**

     * Returns a stream of all the Permission objects in the collection.

     *

     * <p> 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<Permission> elementsAsStream() {

        int characteristics = isReadOnly()

                ? Spliterator.NONNULL | Spliterator.IMMUTABLE

                : Spliterator.NONNULL;

        return StreamSupport.stream(

                Spliterators.spliteratorUnknownSize(

                        elements().asIterator(), characteristics),

                false);

    }

    /**

     * 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}.

     */

    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}.

     *

     * <p>By default, the object is <i>not</i> 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:

     * <pre>

     * super.toString() (

     *   // enumerate all the Permission

     *   // objects and call toString() on them,

     *   // one per line..

     * )</pre>

     *

     * {@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<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();

    }

}