/*
 * Copyright (c) 1998, 2017, 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;

This class defines the Service Provider Interface (SPI) for the SecureRandom class. 

All the abstract methods in this class must be implemented by each
service provider who wishes to supply the implementation
of a cryptographically strong pseudo-random number generator.
Implementation Requirements:
 If the SecureRandomSpi(SecureRandomParameters) constructor is overridden in an implementation, it will always be called whenever a SecureRandom is instantiated. Precisely, if an object is instantiated with one of SecureRandom's getInstance methods without a SecureRandomParameters parameter, the constructor will be called with a null argument and the implementation is responsible for creating its own SecureRandomParameters parameter for use when engineGetParameters() is called. If an object is instantiated with one of SecureRandom's getInstance methods with a SecureRandomParameters argument, the constructor will be called with that argument. The engineGetParameters() method must not return null. 
 Otherwise, if the SecureRandomSpi(SecureRandomParameters) constructor is not overridden in an implementation, the SecureRandomSpi() constructor must be overridden and it will be called if an object is instantiated with one of SecureRandom's getInstance methods without a SecureRandomParameters argument. Calling one of SecureRandom's getInstance methods with a SecureRandomParameters argument will never return an instance of this implementation. The engineGetParameters() method must return null. 
 See SecureRandom for additional details on thread safety. By default, a SecureRandomSpi implementation is considered to be not safe for use by multiple concurrent threads and SecureRandom will synchronize access to each of the applicable engine methods (see SecureRandom for the list of methods). However, if a SecureRandomSpi implementation is thread-safe, the 
service provider attribute "ThreadSafe" should be set to "true" during
its registration, as follows:
put("SecureRandom.AlgName ThreadSafe", "true");

or
putService(new Service(this, "SecureRandom", "AlgName", className,
         null, Map.of("ThreadSafe", "true")));
 SecureRandom will call the applicable engine methods without any synchronization.
Since:
1.2/**
 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
 * for the {@link SecureRandom} class.
 * <p>
 * All the abstract methods in this class must be implemented by each
 * service provider who wishes to supply the implementation
 * of a cryptographically strong pseudo-random number generator.
 *
 * @implSpec
 * If the {@link #SecureRandomSpi(SecureRandomParameters)}
 * constructor is overridden in an implementation, it will always be called
 * whenever a {@code SecureRandom} is instantiated. Precisely, if an object is
 * instantiated with one of {@code SecureRandom}'s {@code getInstance} methods
 * <em>without</em> a {@link SecureRandomParameters} parameter,
 * the constructor will be called with a {@code null} argument and the
 * implementation is responsible for creating its own
 * {@code SecureRandomParameters} parameter for use when
 * {@link #engineGetParameters()} is called. If an object
 * is instantiated with one of {@code SecureRandom}'s {@code getInstance}
 * methods <em>with</em> a {@code SecureRandomParameters} argument,
 * the constructor will be called with that argument. The
 * {@link #engineGetParameters()} method must not return {@code null}.
 * <p>
 * Otherwise, if the {@code SecureRandomSpi(SecureRandomParameters)}
 * constructor is not overridden in an implementation, the
 * {@link #SecureRandomSpi()} constructor must be overridden and it will be
 * called if an object is instantiated with one of {@code SecureRandom}'s
 * {@code getInstance} methods <em>without</em> a
 * {@code SecureRandomParameters} argument. Calling one of
 * {@code SecureRandom}'s {@code getInstance} methods <em>with</em>
 * a {@code SecureRandomParameters} argument will never
 * return an instance of this implementation. The
 * {@link #engineGetParameters()} method must return {@code null}.
 * <p>
 * See {@link SecureRandom} for additional details on thread safety. By
 * default, a {@code SecureRandomSpi} implementation is considered to be
 * not safe for use by multiple concurrent threads and {@code SecureRandom}
 * will synchronize access to each of the applicable engine methods
 * (see {@link SecureRandom} for the list of methods). However, if a
 * {@code SecureRandomSpi} implementation is thread-safe, the <a href=
 * "{@docRoot}/../specs/security/standard-names.html#service-attributes">
 * service provider attribute</a> "ThreadSafe" should be set to "true" during
 * its registration, as follows:
 * <blockquote><pre>
 * put("SecureRandom.AlgName ThreadSafe", "true");</pre>
 * </blockquote>
 * or
 * <blockquote><pre>
 * putService(new Service(this, "SecureRandom", "AlgName", className,
 *          null, Map.of("ThreadSafe", "true")));</pre>
 * </blockquote>
 * {@code SecureRandom} will call the applicable engine methods
 * without any synchronization.
 *
 * @since 1.2
 */

public abstract class SecureRandomSpi implements java.io.Serializable {

    private static final long serialVersionUID = -2991854161009191830L;

    
Constructor without a parameter.
/**
     * Constructor without a parameter.
     */
    public SecureRandomSpi() {
        // ignored
    }

    
Constructor with a parameter.
Params:
params – the SecureRandomParameters object. This argument can be null.
Throws:
IllegalArgumentException – if params is unrecognizable or unsupported by this SecureRandom
Since:
9/**
     * Constructor with a parameter.
     *
     * @param params the {@link SecureRandomParameters} object.
     *               This argument can be {@code null}.
     * @throws IllegalArgumentException if {@code params} is
     *         unrecognizable or unsupported by this {@code SecureRandom}
     *
     * @since 9
     */
    protected SecureRandomSpi(SecureRandomParameters params) {
        // ignored
    }

    
Reseeds this random object with the given seed. The seed supplements,
rather than replaces, the existing seed. Thus, repeated calls
are guaranteed never to reduce randomness.
Params:
seed – the seed./**
     * Reseeds this random object with the given seed. The seed supplements,
     * rather than replaces, the existing seed. Thus, repeated calls
     * are guaranteed never to reduce randomness.
     *
     * @param seed the seed.
     */
    protected abstract void engineSetSeed(byte[] seed);

    
Generates a user-specified number of random bytes.
 Some random number generators can only generate a limited amount of random bytes per invocation. If the size of bytes is greater than this limit, the implementation should invoke its generation process multiple times to completely fill the buffer before returning from this method. 
Params:
bytes – the array to be filled in with random bytes./**
     * Generates a user-specified number of random bytes.
     * <p>
     * Some random number generators can only generate a limited amount
     * of random bytes per invocation. If the size of {@code bytes}
     * is greater than this limit, the implementation should invoke
     * its generation process multiple times to completely fill the
     * buffer before returning from this method.
     *
     * @param bytes the array to be filled in with random bytes.
     */
    protected abstract void engineNextBytes(byte[] bytes);

    
Generates a user-specified number of random bytes with
additional parameters.
 Some random number generators can only generate a limited amount of random bytes per invocation. If the size of bytes is greater than this limit, the implementation should invoke its generation process multiple times to completely fill the buffer before returning from this method. 
Params:
bytes – the array to be filled in with random bytes
params – additional parameters
Throws:
UnsupportedOperationException – if the implementation
        has not overridden this method
IllegalArgumentException – if params is null, illegal or unsupported by this SecureRandom
Implementation Requirements:
The default implementation throws an UnsupportedOperationException.
Since:
9/**
     * Generates a user-specified number of random bytes with
     * additional parameters.
     * <p>
     * Some random number generators can only generate a limited amount
     * of random bytes per invocation. If the size of {@code bytes}
     * is greater than this limit, the implementation should invoke
     * its generation process multiple times to completely fill the
     * buffer before returning from this method.
     *
     * @implSpec The default implementation throws
     * an {@link UnsupportedOperationException}.
     *
     * @param bytes the array to be filled in with random bytes
     * @param params additional parameters
     * @throws UnsupportedOperationException if the implementation
     *         has not overridden this method
     * @throws IllegalArgumentException if {@code params} is {@code null},
     *         illegal or unsupported by this {@code SecureRandom}
     *
     * @since 9
     */
    protected void engineNextBytes(
            byte[] bytes, SecureRandomParameters params) {
        throw new UnsupportedOperationException();
    }

    
Returns the given number of seed bytes.  This call may be used to
seed other random number generators.
Params:
numBytes – the number of seed bytes to generate.
Returns:
the seed bytes./**
     * Returns the given number of seed bytes.  This call may be used to
     * seed other random number generators.
     *
     * @param numBytes the number of seed bytes to generate.
     *
     * @return the seed bytes.
     */
    protected abstract byte[] engineGenerateSeed(int numBytes);

    
Reseeds this random object with entropy input read from its
entropy source with additional parameters.
 If this method is called by SecureRandom.reseed(), params will be null. 

Do not override this method if the implementation does not
support reseeding.
Params:
params – extra parameters, can be null.
Throws:
UnsupportedOperationException – if the implementation
        has not overridden this method
IllegalArgumentException – if params is illegal or unsupported by this SecureRandom
Implementation Requirements:
The default implementation throws an UnsupportedOperationException.
Since:
9/**
     * Reseeds this random object with entropy input read from its
     * entropy source with additional parameters.
     * <p>
     * If this method is called by {@link SecureRandom#reseed()},
     * {@code params} will be {@code null}.
     * <p>
     * Do not override this method if the implementation does not
     * support reseeding.
     *
     * @implSpec The default implementation throws
     *           an {@link UnsupportedOperationException}.
     *
     * @param params extra parameters, can be {@code null}.
     * @throws UnsupportedOperationException if the implementation
     *         has not overridden this method
     * @throws IllegalArgumentException if {@code params} is
     *         illegal or unsupported by this {@code SecureRandom}
     *
     * @since 9
     */
    protected void engineReseed(SecureRandomParameters params) {
        throw new UnsupportedOperationException();
    }

    
Returns the effective SecureRandomParameters for this SecureRandom instance. 
Implementation Requirements:
The default implementation returns null.
Returns:
the effective SecureRandomParameters parameters, or null if no parameters were used.
Since:
9/**
     * Returns the effective {@link SecureRandomParameters} for this
     * {@code SecureRandom} instance.
     *
     * @implSpec The default implementation returns {@code null}.
     *
     * @return the effective {@link SecureRandomParameters} parameters,
     * or {@code null} if no parameters were used.
     *
     * @since 9
     */
    protected SecureRandomParameters engineGetParameters() {
        return null;
    }

    
Returns a Human-readable string representation of this SecureRandom. 
Returns:
the string representation/**
     * Returns a Human-readable string representation of this
     * {@code SecureRandom}.
     *
     * @return the string representation
     */
    @Override
    public String toString() {
        return getClass().getSimpleName();
    }
}