/*

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

/**

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

 * <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>First, if there is a security manager, 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.

     * If the default implementation of {@code checkSecurityAccess}

     * is used (that is, that method is not overriden), then this results in

     * a call to the security manager's {@code checkPermission} method

     * with a {@code SecurityPermission("clearProviderProperties."+name)}

     * permission.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to clear this provider

     *

     * @since 1.2

     */

    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

     */

    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

     */

    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

     */

    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

     */

    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

     */

    public Collection<Object> values() {

        checkInitialized();

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

    }

    /**

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

     * {@code value}.

     *

     * <p>First, if there is a security manager, 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.

     * If the default implementation of {@code checkSecurityAccess}

     * is used (that is, that method is not overriden), then this results in

     * a call to the security manager's {@code checkPermission} method

     * with a {@code SecurityPermission("putProviderProperty."+name)}

     * permission.

     *

     * @param key the property key.

     *

     * @param value the property value.

     *

     * @return the previous value of the specified property

     * ({@code key}), or null if it did not have one.

     *

     * @throws  SecurityException

     *          if a security manager exists and its {@link

     *          java.lang.SecurityManager#checkSecurityAccess} method

     *          denies access to set property values.

     *

     * @since 1.2

     */

    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);

    }

    /**

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

     * {@code value}).

     *

     * <p>First, if there is a security manager, 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. If the default implementation of

     * {@code checkSecurityAccess} is used (that is, that method is not

     * overriden), then this results in a call to the security manager's

     * {@code checkPermission} method with a

     * {@code SecurityPermission("removeProviderProperty."+name)}

     * permission.

     *

     * @param key the key for the property to be removed.

     *

     * @return the value to which the key had been mapped,

     * or null if the key did not have a mapping.

     *

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

     */

    public synchronized Object remove(Object key) {

        check("removeProviderProperty."+name);

        if (debug != null) {

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

        }

        return implRemove(key);

    }

    // let javadoc show doc from superclass

    public Object get(Object key) {

        checkInitialized();

        return super.get(key);

    }

    // let javadoc show doc from superclass

    public Enumeration<Object> keys() {

        checkInitialized();

        return super.keys();

    }

    // let javadoc show doc from superclass

    public Enumeration<Object> elements() {

        checkInitialized();

        return super.elements();

    }

    // let javadoc show doc from superclass

    public String getProperty(String key) {

        checkInitialized();

        return super.getProperty(key);

    }

    private void checkInitialized() {

        if (!initialized) {

            throw new IllegalStateException();

        }

    }

    private void check(String directive) {

        checkInitialized();

        SecurityManager security = System.getSecurityManager();

        if (security != null) {

            security.checkSecurityAccess(directive);

        }

    }

    // legacy properties changed since last call to any services method?

    private transient boolean legacyChanged;

    // serviceMap changed since last call to getServices()

    private transient boolean servicesChanged;

    // Map<String,String>

    private transient Map<String,String> legacyStrings;

    // Map<ServiceKey,Service>

    // used for services added via putService(), initialized on demand

    private transient Map<ServiceKey,Service> serviceMap;

    // Map<ServiceKey,Service>

    // used for services added via legacy methods, init on demand

    private transient Map<ServiceKey,Service> legacyMap;

    // Set<Service>

    // Unmodifiable set of all services. Initialized on demand.

    private transient Set<Service> serviceSet;

    // register the id attributes for this provider

    // this is to ensure that equals() and hashCode() do not incorrectly

    // report to different provider objects as the same

    private void putId() {

        // note: name and info may be null

        super.put("Provider.id name", String.valueOf(name));

        super.put("Provider.id version", String.valueOf(version));

        super.put("Provider.id info", String.valueOf(info));

        super.put("Provider.id className", this.getClass().getName());

    }

    private void readObject(ObjectInputStream in)

                throws IOException, ClassNotFoundException {

        Map<Object,Object> copy = new HashMap<>();

        for (Map.Entry<Object,Object> entry : super.entrySet()) {

            copy.put(entry.getKey(), entry.getValue());

        }

        defaults = null;

        in.defaultReadObject();

        implClear();

        initialized = true;

        putAll(copy);

    }

    /**

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

     * Internal method to be called AFTER the security check has been

     * performed.

     */

    private void implPutAll(Map<?,?> t) {

        for (Map.Entry<?,?> e : t.entrySet()) {

            implPut(e.getKey(), e.getValue());

        }

    }

    private Object implRemove(Object key) {

        if (key instanceof String) {

            String keyString = (String)key;

            if (keyString.startsWith("Provider.")) {

                return null;

            }

            legacyChanged = true;

            if (legacyStrings == null) {

                legacyStrings = new LinkedHashMap<String,String>();

            }

            legacyStrings.remove(keyString);

        }

        return super.remove(key);

    }

    private Object implPut(Object key, Object value) {

        if ((key instanceof String) && (value instanceof String)) {

            String keyString = (String)key;

            if (keyString.startsWith("Provider.")) {

                return null;

            }

            legacyChanged = true;

            if (legacyStrings == null) {

                legacyStrings = new LinkedHashMap<String,String>();

            }

            legacyStrings.put(keyString, (String)value);

        }

        return super.put(key, value);

    }

    private void implClear() {

        if (legacyStrings != null) {

            legacyStrings.clear();

        }

        if (legacyMap != null) {

            legacyMap.clear();

        }

        if (serviceMap != null) {

            serviceMap.clear();

        }

        legacyChanged = false;

        servicesChanged = false;

        serviceSet = null;

        super.clear();

        putId();

    }

    // used as key in the serviceMap and legacyMap HashMaps

    private static class ServiceKey {

        private final String type;

        private final String algorithm;

        private final String originalAlgorithm;

        private ServiceKey(String type, String algorithm, boolean intern) {

            this.type = type;

            this.originalAlgorithm = algorithm;

            algorithm = algorithm.toUpperCase(ENGLISH);

            this.algorithm = intern ? algorithm.intern() : algorithm;

        }

        public int hashCode() {

            return type.hashCode() + algorithm.hashCode();

        }

        public boolean equals(Object obj) {

            if (this == obj) {