/*

 * Copyright (c) 1996, 2014, 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.io.*;

import java.util.*;

import static java.util.Locale.ENGLISH;

import java.lang.ref.*;

import java.lang.reflect.*;

import java.util.function.BiConsumer;

import java.util.function.BiFunction;

import java.util.function.Function;

/**

 * This class represents a "provider" for the

 * Java Security API, where a provider implements some or all parts of

 * Java Security. Services that a provider may implement include:

 *

 * <ul>

 *

 * <li>Algorithms (such as DSA, RSA, MD5 or SHA-1).

 *

 * <li>Key generation, conversion, and management facilities (such as for

 * algorithm-specific keys).

 *

 *</ul>

 *

 * <p>Each provider has a name and a version number, and is configured

 * in each runtime it is installed in.

 *

 * <p>See <a href =

 * "../../../technotes/guides/security/crypto/CryptoSpec.html#Provider">The Provider Class</a>

 * in the "Java Cryptography Architecture API Specification & Reference"

 * for information about how a particular type of provider, the

 * cryptographic service provider, works and is installed. However,

 * please note that a provider can be used to implement any security

 * service in Java that uses a pluggable architecture with a choice

 * of implementations that fit underneath.

 *

 * <p>Some provider implementations may encounter unrecoverable internal

 * errors during their operation, for example a failure to communicate with a

 * security token. A {@link ProviderException} should be used to indicate

 * such errors.

 *

 * <p>The service type {@code Provider} is reserved for use by the

 * security framework. Services of this type cannot be added, removed,

 * or modified by applications.

 * The following attributes are automatically placed in each Provider object:

 * <table cellspacing=4>

 * <caption><b>Attributes Automatically Placed in a Provider Object</b></caption>

 * <tr><th>Name</th><th>Value</th>

 * <tr><td>{@code Provider.id name}</td>

  *    <td>{@code String.valueOf(provider.getName())}</td>

 * <tr><td>{@code Provider.id version}</td>

 *     <td>{@code String.valueOf(provider.getVersion())}</td>

 * <tr><td>{@code Provider.id info}</td>

       <td>{@code String.valueOf(provider.getInfo())}</td>

 * <tr><td>{@code Provider.id className}</td>

 *     <td>{@code provider.getClass().getName()}</td>

 * </table>

 *

 * @author Benjamin Renaud

 * @author Andreas Sterbenz

 */

public abstract class Provider extends Properties {

    // Declare serialVersionUID to be compatible with JDK1.1

    static final long serialVersionUID = -4298000515446427739L;

    private static final sun.security.util.Debug debug =

        sun.security.util.Debug.getInstance

        ("provider", "Provider");

    /**

     * The provider name.

     *

     * @serial

     */

    private String name;

    /**

     * A description of the provider and its services.

     *

     * @serial

     */

    private String info;

    /**

     * The provider version number.

     *

     * @serial

     */

    private double version;

    private transient Set<Map.Entry<Object,Object>> entrySet = null;

    private transient int entrySetCallCount = 0;

    private transient boolean initialized;

    /**

     * Constructs a provider with the specified name, version number,

     * and information.

     *

     * @param name the provider name.

     *

     * @param version the provider version number.

     *

     * @param info a description of the provider and its services.

     */

    protected Provider(String name, double version, String info) {

        this.name = name;

        this.version = version;

        this.info = info;

        putId();

        initialized = true;

    }

    /**

     * Returns the name of this provider.

     *

     * @return the name of this provider.

     */

    public String getName() {

        return name;

    }

    /**

     * Returns the version number for this provider.

     *

     * @return the version number for this provider.

     */

    public double getVersion() {

        return version;

    }

    /**

     * Returns a human-readable description of the provider and its

     * services.  This may return an HTML page, with relevant links.

     *

     * @return a description of the provider and its services.

     */

    public String getInfo() {

        return info;

    }

    /**

     * Returns a string with the name and the version number

     * of this provider.

     *

     * @return the string with the name and the version number

     * for this provider.

     */

    public String toString() {

        return name + " version " + version;

    }

    /*

     * override the following methods to ensure that provider

     * information can only be changed if the caller has the appropriate

     * permissions.

     */

    /**

     * Clears this provider so that it no longer contains the properties

     * used to look up facilities implemented by the provider.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "clearProviderProperties."+name}

     * (where {@code name} is the provider name) to see if it's ok to clear

     * this provider.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to clear this provider

     *

     * @since 1.2

     */

    @Override

    public synchronized void clear() {

        check("clearProviderProperties."+name);

        if (debug != null) {

            debug.println("Remove " + name + " provider properties");

        }

        implClear();

    }

    /**

     * Reads a property list (key and element pairs) from the input stream.

     *

     * @param inStream   the input stream.

     * @exception  IOException  if an error occurred when reading from the

     *               input stream.

     * @see java.util.Properties#load

     */

    @Override

    public synchronized void load(InputStream inStream) throws IOException {

        check("putProviderProperty."+name);

        if (debug != null) {

            debug.println("Load " + name + " provider properties");

        }

        Properties tempProperties = new Properties();

        tempProperties.load(inStream);

        implPutAll(tempProperties);

    }

    /**

     * Copies all of the mappings from the specified Map to this provider.

     * These mappings will replace any properties that this provider had

     * for any of the keys currently in the specified Map.

     *

     * @since 1.2

     */

    @Override

    public synchronized void putAll(Map<?,?> t) {

        check("putProviderProperty."+name);

        if (debug != null) {

            debug.println("Put all " + name + " provider properties");

        }

        implPutAll(t);

    }

    /**

     * Returns an unmodifiable Set view of the property entries contained

     * in this Provider.

     *

     * @see   java.util.Map.Entry

     * @since 1.2

     */

    @Override

    public synchronized Set<Map.Entry<Object,Object>> entrySet() {

        checkInitialized();

        if (entrySet == null) {

            if (entrySetCallCount++ == 0)  // Initial call

                entrySet = Collections.unmodifiableMap(this).entrySet();

            else

                return super.entrySet();   // Recursive call

        }

        // This exception will be thrown if the implementation of

        // Collections.unmodifiableMap.entrySet() is changed such that it

        // no longer calls entrySet() on the backing Map.  (Provider's

        // entrySet implementation depends on this "implementation detail",

        // which is unlikely to change.

        if (entrySetCallCount != 2)

            throw new RuntimeException("Internal error.");

        return entrySet;

    }

    /**

     * Returns an unmodifiable Set view of the property keys contained in

     * this provider.

     *

     * @since 1.2

     */

    @Override

    public Set<Object> keySet() {

        checkInitialized();

        return Collections.unmodifiableSet(super.keySet());

    }

    /**

     * Returns an unmodifiable Collection view of the property values

     * contained in this provider.

     *

     * @since 1.2

     */

    @Override

    public Collection<Object> values() {

        checkInitialized();

        return Collections.unmodifiableCollection(super.values());

    }

    /**

     * Sets the {@code key} property to have the specified

     * {@code value}.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "putProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to set this

     * provider's property values.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.2

     */

    @Override

    public synchronized Object put(Object key, Object value) {

        check("putProviderProperty."+name);

        if (debug != null) {

            debug.println("Set " + name + " provider property [" +

                          key + "/" + value +"]");

        }

        return implPut(key, value);

    }

    /**

     * If the specified key is not already associated with a value (or is mapped

     * to {@code null}) associates it with the given value and returns

     * {@code null}, else returns the current value.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "putProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to set this

     * provider's property values.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.8

     */

    @Override

    public synchronized Object putIfAbsent(Object key, Object value) {

        check("putProviderProperty."+name);

        if (debug != null) {

            debug.println("Set " + name + " provider property [" +

                          key + "/" + value +"]");

        }

        return implPutIfAbsent(key, value);

    }

    /**

     * Removes the {@code key} property (and its corresponding

     * {@code value}).

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "removeProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to remove this

     * provider's properties.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to remove this provider's properties.

     *

     * @since 1.2

     */

    @Override

    public synchronized Object remove(Object key) {

        check("removeProviderProperty."+name);

        if (debug != null) {

            debug.println("Remove " + name + " provider property " + key);

        }

        return implRemove(key);

    }

    /**

     * Removes the entry for the specified key only if it is currently

     * mapped to the specified value.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "removeProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to remove this

     * provider's properties.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to remove this provider's properties.

     *

     * @since 1.8

     */

    @Override

    public synchronized boolean remove(Object key, Object value) {

        check("removeProviderProperty."+name);

        if (debug != null) {

            debug.println("Remove " + name + " provider property " + key);

        }

        return implRemove(key, value);

    }

    /**

     * Replaces the entry for the specified key only if currently

     * mapped to the specified value.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "putProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to set this

     * provider's property values.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.8

     */

    @Override

    public synchronized boolean replace(Object key, Object oldValue,

            Object newValue) {

        check("putProviderProperty." + name);

        if (debug != null) {

            debug.println("Replace " + name + " provider property " + key);

        }

        return implReplace(key, oldValue, newValue);

    }

    /**

     * Replaces the entry for the specified key only if it is

     * currently mapped to some value.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "putProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to set this

     * provider's property values.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.8

     */

    @Override

    public synchronized Object replace(Object key, Object value) {

        check("putProviderProperty." + name);

        if (debug != null) {

            debug.println("Replace " + name + " provider property " + key);

        }

        return implReplace(key, value);

    }

    /**

     * Replaces each entry's value with the result of invoking the given

     * function on that entry, in the order entries are returned by an entry

     * set iterator, until all entries have been processed or the function

     * throws an exception.

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the string {@code "putProviderProperty."+name},

     * where {@code name} is the provider name, to see if it's ok to set this

     * provider's property values.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.8

     */

    @Override

    public synchronized void replaceAll(BiFunction<? super Object, ? super Object, ? extends Object> function) {

        check("putProviderProperty." + name);

        if (debug != null) {

            debug.println("ReplaceAll " + name + " provider property ");

        }

        implReplaceAll(function);

    }

    /**

     * Attempts to compute a mapping for the specified key and its

     * current mapped value (or {@code null} if there is no current

     * mapping).

     *

     * <p>If a security manager is enabled, its {@code checkSecurityAccess}

     * method is called with the strings {@code "putProviderProperty."+name}

     * and {@code "removeProviderProperty."+name}, where {@code name} is the

     * provider name, to see if it's ok to set this provider's property values

     * and remove this provider's properties.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values or remove properties.

     *

     * @since 1.8

     */

    @Override

    public synchronized Object compute(Object key,

        BiFunction<? super Object, ? super Object, ? extends Object> remappingFunction) {

        check("putProviderProperty." + name);

        check("removeProviderProperty" + name);

        if (debug != null) {

            debug.println("Compute " + name + " provider property " + key);

        }

        return implCompute(key, remappingFunction);