/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.math3.random;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.MalformedURLException;
import java.net.URL;

import org.apache.commons.math3.exception.MathIllegalArgumentException;
import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.NullArgumentException;
import org.apache.commons.math3.exception.ZeroException;
import org.apache.commons.math3.exception.util.LocalizedFormats;

Generates values for use in simulation applications.

How values are generated is determined by the mode
property.

Supported mode values are: 

 DIGEST_MODE -- uses an empirical distribution 
 REPLAY_MODE -- replays data from valuesFileURL
 UNIFORM_MODE -- generates uniformly distributed random values with
                     mean = mu 
 EXPONENTIAL_MODE -- generates exponentially distributed random values
                        with mean = mu
 GAUSSIAN_MODE -- generates Gaussian distributed random values with
                      mean = mu and
                      standard deviation = sigma
 CONSTANT_MODE -- returns mu every time.

/**
 * Generates values for use in simulation applications.
 * <p>
 * How values are generated is determined by the <code>mode</code>
 * property.</p>
 * <p>
 * Supported <code>mode</code> values are: <ul>
 * <li> DIGEST_MODE -- uses an empirical distribution </li>
 * <li> REPLAY_MODE -- replays data from <code>valuesFileURL</code></li>
 * <li> UNIFORM_MODE -- generates uniformly distributed random values with
 *                      mean = <code>mu</code> </li>
 * <li> EXPONENTIAL_MODE -- generates exponentially distributed random values
 *                         with mean = <code>mu</code></li>
 * <li> GAUSSIAN_MODE -- generates Gaussian distributed random values with
 *                       mean = <code>mu</code> and
 *                       standard deviation = <code>sigma</code></li>
 * <li> CONSTANT_MODE -- returns <code>mu</code> every time.</li></ul></p>
 *
 *
 */
public class ValueServer {

    
Use empirical distribution.  /** Use empirical distribution.  */
    public static final int DIGEST_MODE = 0;

    
Replay data from valuesFilePath. /** Replay data from valuesFilePath. */
    public static final int REPLAY_MODE = 1;

    
Uniform random deviates with mean = μ. /** Uniform random deviates with mean = &mu;. */
    public static final int UNIFORM_MODE = 2;

    
Exponential random deviates with mean = μ. /** Exponential random deviates with mean = &mu;. */
    public static final int EXPONENTIAL_MODE = 3;

    
Gaussian random deviates with mean = μ, std dev = σ. /** Gaussian random deviates with mean = &mu;, std dev = &sigma;. */
    public static final int GAUSSIAN_MODE = 4;

    
Always return mu /** Always return mu */
    public static final int CONSTANT_MODE = 5;

    
mode determines how values are generated. /** mode determines how values are generated. */
    private int mode = 5;

    
URI to raw data values. /** URI to raw data values. */
    private URL valuesFileURL = null;

    
Mean for use with non-data-driven modes. /** Mean for use with non-data-driven modes. */
    private double mu = 0.0;

    
Standard deviation for use with GAUSSIAN_MODE. /** Standard deviation for use with GAUSSIAN_MODE. */
    private double sigma = 0.0;

    
Empirical probability distribution for use with DIGEST_MODE. /** Empirical probability distribution for use with DIGEST_MODE. */
    private EmpiricalDistribution empiricalDistribution = null;

    
File pointer for REPLAY_MODE. /** File pointer for REPLAY_MODE. */
    private BufferedReader filePointer = null;

    
RandomDataImpl to use for random data generation. /** RandomDataImpl to use for random data generation. */
    private final RandomDataGenerator randomData;

    // Data generation modes ======================================

    
Creates new ValueServer /** Creates new ValueServer */
    public ValueServer() {
        randomData = new RandomDataGenerator();
    }

    
Construct a ValueServer instance using a RandomDataImpl as its source
of random data.
Params:
randomData – the RandomDataImpl instance used to source random data
Since:
3.0
Deprecated:
use ValueServer(RandomGenerator)/**
     * Construct a ValueServer instance using a RandomDataImpl as its source
     * of random data.
     *
     * @param randomData the RandomDataImpl instance used to source random data
     * @since 3.0
     * @deprecated use {@link #ValueServer(RandomGenerator)}
     */
    @Deprecated
    public ValueServer(RandomDataImpl randomData) {
        this.randomData = randomData.getDelegate();
    }

    
Construct a ValueServer instance using a RandomGenerator as its source
of random data.
Params:
generator – source of random data
Since:
3.1/**
     * Construct a ValueServer instance using a RandomGenerator as its source
     * of random data.
     *
     * @since 3.1
     * @param generator source of random data
     */
    public ValueServer(RandomGenerator generator) {
        this.randomData = new RandomDataGenerator(generator);
    }

    
Returns the next generated value, generated according
to the mode value (see MODE constants).
Throws:
IOException – in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException – if mode is not recognized
MathIllegalArgumentException – if the underlying random generator thwrows one
Returns:
generated value/**
     * Returns the next generated value, generated according
     * to the mode value (see MODE constants).
     *
     * @return generated value
     * @throws IOException in REPLAY_MODE if a file I/O error occurs
     * @throws MathIllegalStateException if mode is not recognized
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    public double getNext() throws IOException, MathIllegalStateException, MathIllegalArgumentException {
        switch (mode) {
            case DIGEST_MODE: return getNextDigest();
            case REPLAY_MODE: return getNextReplay();
            case UNIFORM_MODE: return getNextUniform();
            case EXPONENTIAL_MODE: return getNextExponential();
            case GAUSSIAN_MODE: return getNextGaussian();
            case CONSTANT_MODE: return mu;
            default: throw new MathIllegalStateException(
                    LocalizedFormats.UNKNOWN_MODE,
                    mode,
                    "DIGEST_MODE",   DIGEST_MODE,   "REPLAY_MODE",      REPLAY_MODE,
                    "UNIFORM_MODE",  UNIFORM_MODE,  "EXPONENTIAL_MODE", EXPONENTIAL_MODE,
                    "GAUSSIAN_MODE", GAUSSIAN_MODE, "CONSTANT_MODE",    CONSTANT_MODE);
        }
    }

    
Fills the input array with values generated using getNext() repeatedly.
Params:
values – array to be filled
Throws:
IOException – in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException – if mode is not recognized
MathIllegalArgumentException – if the underlying random generator thwrows one/**
     * Fills the input array with values generated using getNext() repeatedly.
     *
     * @param values array to be filled
     * @throws IOException in REPLAY_MODE if a file I/O error occurs
     * @throws MathIllegalStateException if mode is not recognized
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    public void fill(double[] values)
        throws IOException, MathIllegalStateException, MathIllegalArgumentException {
        for (int i = 0; i < values.length; i++) {
            values[i] = getNext();
        }
    }

    
Returns an array of length length with values generated
using getNext() repeatedly.
Params:
length – length of output array
Throws:
IOException – in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException – if mode is not recognized
MathIllegalArgumentException – if the underlying random generator thwrows one
Returns:
array of generated values/**
     * Returns an array of length <code>length</code> with values generated
     * using getNext() repeatedly.
     *
     * @param length length of output array
     * @return array of generated values
     * @throws IOException in REPLAY_MODE if a file I/O error occurs
     * @throws MathIllegalStateException if mode is not recognized
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    public double[] fill(int length)
        throws IOException, MathIllegalStateException, MathIllegalArgumentException {
        double[] out = new double[length];
        for (int i = 0; i < length; i++) {
            out[i] = getNext();
        }
        return out;
    }

    
Computes the empirical distribution using values from the file
in valuesFileURL, using the default number of bins.

valuesFileURL must exist and be
readable by *this at runtime.

This method must be called before using getNext()
with mode = DIGEST_MODE
Throws:
IOException – if an I/O error occurs reading the input file
NullArgumentException – if the valuesFileURL has not been set
ZeroException – if URL contains no data/**
     * Computes the empirical distribution using values from the file
     * in <code>valuesFileURL</code>, using the default number of bins.
     * <p>
     * <code>valuesFileURL</code> must exist and be
     * readable by *this at runtime.</p>
     * <p>
     * This method must be called before using <code>getNext()</code>
     * with <code>mode = DIGEST_MODE</code></p>
     *
     * @throws IOException if an I/O error occurs reading the input file
     * @throws NullArgumentException if the {@code valuesFileURL} has not been set
     * @throws ZeroException if URL contains no data
     */
    public void computeDistribution() throws IOException, ZeroException, NullArgumentException {
        computeDistribution(EmpiricalDistribution.DEFAULT_BIN_COUNT);
    }

    
Computes the empirical distribution using values from the file
in valuesFileURL and binCount bins.

valuesFileURL must exist and be readable by this process
at runtime.

This method must be called before using getNext()
with mode = DIGEST_MODE
Params:
binCount – the number of bins used in computing the empirical
distribution
Throws:
NullArgumentException – if the valuesFileURL has not been set
IOException – if an error occurs reading the input file
ZeroException – if URL contains no data/**
     * Computes the empirical distribution using values from the file
     * in <code>valuesFileURL</code> and <code>binCount</code> bins.
     * <p>
     * <code>valuesFileURL</code> must exist and be readable by this process
     * at runtime.</p>
     * <p>
     * This method must be called before using <code>getNext()</code>
     * with <code>mode = DIGEST_MODE</code></p>
     *
     * @param binCount the number of bins used in computing the empirical
     * distribution
     * @throws NullArgumentException if the {@code valuesFileURL} has not been set
     * @throws IOException if an error occurs reading the input file
     * @throws ZeroException if URL contains no data
     */
    public void computeDistribution(int binCount) throws NullArgumentException, IOException, ZeroException {
        empiricalDistribution = new EmpiricalDistribution(binCount, randomData.getRandomGenerator());
        empiricalDistribution.load(valuesFileURL);
        mu = empiricalDistribution.getSampleStats().getMean();
        sigma = empiricalDistribution.getSampleStats().getStandardDeviation();
    }

    
Returns the data generation mode. See the class javadoc for description of the valid values of this property. 
Returns:
Value of property mode./**
     * Returns the data generation mode. See {@link ValueServer the class javadoc}
     * for description of the valid values of this property.
     *
     * @return Value of property mode.
     */
    public int getMode() {
        return mode;
    }

    
Sets the data generation mode.
Params:
mode – New value of the data generation mode./**
     * Sets the data generation mode.
     *
     * @param mode New value of the data generation mode.
     */
    public void setMode(int mode) {
        this.mode = mode;
    }

    
Returns the URL for the file used to build the empirical distribution when using DIGEST_MODE. 
Returns:
Values file URL./**
     * Returns the URL for the file used to build the empirical distribution
     * when using {@link #DIGEST_MODE}.
     *
     * @return Values file URL.
     */
    public URL getValuesFileURL() {
        return valuesFileURL;
    }

    
Sets the values file URL using a string URL representation. 
Params:
url – String representation for new valuesFileURL.
Throws:
MalformedURLException – if url is not well formed/**
     * Sets the {@link #getValuesFileURL() values file URL} using a string
     * URL representation.
     *
     * @param url String representation for new valuesFileURL.
     * @throws MalformedURLException if url is not well formed
     */
    public void setValuesFileURL(String url) throws MalformedURLException {
        this.valuesFileURL = new URL(url);
    }

    
Sets the the values file URL. 
The values file must be an ASCII text file containing one
valid numeric entry per line.
Params:
url – URL of the values file./**
     * Sets the the {@link #getValuesFileURL() values file URL}.
     *
     * <p>The values file <i>must</i> be an ASCII text file containing one
     * valid numeric entry per line.</p>
     *
     * @param url URL of the values file.
     */
    public void setValuesFileURL(URL url) {
        this.valuesFileURL = url;
    }

    
Returns the EmpiricalDistribution used when operating in 0. 
Returns:
EmpircalDistribution built by computeDistribution()/**
     * Returns the {@link EmpiricalDistribution} used when operating in {@value #DIGEST_MODE}.
     *
     * @return EmpircalDistribution built by {@link #computeDistribution()}
     */
    public EmpiricalDistribution getEmpiricalDistribution() {
        return empiricalDistribution;
    }

    
Resets REPLAY_MODE file pointer to the beginning of the valuesFileURL.
Throws:
IOException – if an error occurs opening the file
NullPointerException – if the valuesFileURL has not been set./**
     * Resets REPLAY_MODE file pointer to the beginning of the <code>valuesFileURL</code>.
     *
     * @throws IOException if an error occurs opening the file
     * @throws NullPointerException if the {@code valuesFileURL} has not been set.
     */
    public void resetReplayFile() throws IOException {
        if (filePointer != null) {
            try {
                filePointer.close();
                filePointer = null;
            } catch (IOException ex) { //NOPMD
                // ignore
            }
        }
        filePointer = new BufferedReader(new InputStreamReader(valuesFileURL.openStream(), "UTF-8"));
    }

    
Closes valuesFileURL after use in REPLAY_MODE. 
Throws:
IOException – if an error occurs closing the file/**
     * Closes {@code valuesFileURL} after use in REPLAY_MODE.
     *
     * @throws IOException if an error occurs closing the file
     */
    public void closeReplayFile() throws IOException {
        if (filePointer != null) {
            filePointer.close();
            filePointer = null;
        }
    }

    
Returns the mean used when operating in GAUSSIAN_MODE, EXPONENTIAL_MODE or UNIFORM_MODE. When operating in CONSTANT_MODE, this is the constant value always returned. Calling computeDistribution() sets this value to the overall mean of the values in the values file. 
Returns:
Mean used in data generation./**
     * Returns the mean used when operating in {@link #GAUSSIAN_MODE}, {@link #EXPONENTIAL_MODE}
     * or {@link #UNIFORM_MODE}.  When operating in {@link #CONSTANT_MODE}, this is the constant
     * value always returned.  Calling {@link #computeDistribution()} sets this value to the
     * overall mean of the values in the {@link #getValuesFileURL() values file}.
     *
     * @return Mean used in data generation.
     */
    public double getMu() {
        return mu;
    }

    
Sets the mean used in data generation. Note that calling this method after computeDistribution() has been called will have no effect on data generated in DIGEST_MODE. 
Params:
mu – new Mean value./**
     * Sets the {@link #getMu() mean} used in data generation.  Note that calling this method
     * after {@link #computeDistribution()} has been called will have no effect on data
     * generated in {@link #DIGEST_MODE}.
     *
     * @param mu new Mean value.
     */
    public void setMu(double mu) {
        this.mu = mu;
    }

    
Returns the standard deviation used when operating in GAUSSIAN_MODE. Calling computeDistribution() sets this value to the overall standard deviation of the values in the values file. This property has no effect when the data generation mode is not GAUSSIAN_MODE. 
Returns:
Standard deviation used when operating in GAUSSIAN_MODE./**
     * Returns the standard deviation used when operating in {@link #GAUSSIAN_MODE}.
     * Calling {@link #computeDistribution()} sets this value to the overall standard
     * deviation of the values in the {@link #getValuesFileURL() values file}.  This
     * property has no effect when the data generation mode is not
     * {@link #GAUSSIAN_MODE}.
     *
     * @return Standard deviation used when operating in {@link #GAUSSIAN_MODE}.
     */
    public double getSigma() {
        return sigma;
    }

    
Sets the standard deviation used in GAUSSIAN_MODE. 
Params:
sigma – New standard deviation./**
     * Sets the {@link #getSigma() standard deviation} used in {@link #GAUSSIAN_MODE}.
     *
     * @param sigma New standard deviation.
     */
    public void setSigma(double sigma) {
        this.sigma = sigma;
    }

    
Reseeds the random data generator.
Params:
seed – Value with which to reseed the RandomDataImpl used to generate random data./**
     * Reseeds the random data generator.
     *
     * @param seed Value with which to reseed the {@link RandomDataImpl}
     * used to generate random data.
     */
    public void reSeed(long seed) {
        randomData.reSeed(seed);
    }

    //------------- private methods ---------------------------------

    
Gets a random value in DIGEST_MODE.

Preconditions: 

Before this method is called, computeDistribution()
must have completed successfully; otherwise an
IllegalStateException will be thrown

Throws:
MathIllegalStateException – if digest has not been initialized
Returns:
next random value from the empirical distribution digest/**
     * Gets a random value in DIGEST_MODE.
     * <p>
     * <strong>Preconditions</strong>: <ul>
     * <li>Before this method is called, <code>computeDistribution()</code>
     * must have completed successfully; otherwise an
     * <code>IllegalStateException</code> will be thrown</li></ul></p>
     *
     * @return next random value from the empirical distribution digest
     * @throws MathIllegalStateException if digest has not been initialized
     */
    private double getNextDigest() throws MathIllegalStateException {
        if ((empiricalDistribution == null) ||
            (empiricalDistribution.getBinStats().size() == 0)) {
            throw new MathIllegalStateException(LocalizedFormats.DIGEST_NOT_INITIALIZED);
        }
        return empiricalDistribution.getNextValue();
    }

    
Gets next sequential value from the valuesFileURL.

Throws an IOException if the read fails.

This method will open the valuesFileURL if there is no
replay file open.

The valuesFileURL will be closed and reopened to wrap around
from EOF to BOF if EOF is encountered. EOFException (which is a kind of
IOException) may still be thrown if the valuesFileURL is
empty.
Throws:
IOException – if there is a problem reading from the file
MathIllegalStateException – if URL contains no data
NumberFormatException – if an invalid numeric string is
  encountered in the file
Returns:
next value from the replay file/**
     * Gets next sequential value from the <code>valuesFileURL</code>.
     * <p>
     * Throws an IOException if the read fails.</p>
     * <p>
     * This method will open the <code>valuesFileURL</code> if there is no
     * replay file open.</p>
     * <p>
     * The <code>valuesFileURL</code> will be closed and reopened to wrap around
     * from EOF to BOF if EOF is encountered. EOFException (which is a kind of
     * IOException) may still be thrown if the <code>valuesFileURL</code> is
     * empty.</p>
     *
     * @return next value from the replay file
     * @throws IOException if there is a problem reading from the file
     * @throws MathIllegalStateException if URL contains no data
     * @throws NumberFormatException if an invalid numeric string is
     *   encountered in the file
     */
    private double getNextReplay() throws IOException, MathIllegalStateException {
        String str = null;
        if (filePointer == null) {
            resetReplayFile();
        }
        if ((str = filePointer.readLine()) == null) {
            // we have probably reached end of file, wrap around from EOF to BOF
            closeReplayFile();
            resetReplayFile();
            if ((str = filePointer.readLine()) == null) {
                throw new MathIllegalStateException(LocalizedFormats.URL_CONTAINS_NO_DATA,
                                                    valuesFileURL);
            }
        }
        return Double.parseDouble(str);
    }

    
Gets a uniformly distributed random value with mean = mu.
Throws:
MathIllegalArgumentException – if the underlying random generator thwrows one
Returns:
random uniform value/**
     * Gets a uniformly distributed random value with mean = mu.
     *
     * @return random uniform value
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    private double getNextUniform() throws MathIllegalArgumentException {
        return randomData.nextUniform(0, 2 * mu);
    }

    
Gets an exponentially distributed random value with mean = mu.
Throws:
MathIllegalArgumentException – if the underlying random generator thwrows one
Returns:
random exponential value/**
     * Gets an exponentially distributed random value with mean = mu.
     *
     * @return random exponential value
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    private double getNextExponential() throws MathIllegalArgumentException {
        return randomData.nextExponential(mu);
    }

    
Gets a Gaussian distributed random value with mean = mu
and standard deviation = sigma.
Throws:
MathIllegalArgumentException – if the underlying random generator thwrows one
Returns:
random Gaussian value/**
     * Gets a Gaussian distributed random value with mean = mu
     * and standard deviation = sigma.
     *
     * @return random Gaussian value
     * @throws MathIllegalArgumentException if the underlying random generator thwrows one
     */
    private double getNextGaussian() throws MathIllegalArgumentException {
        return randomData.nextGaussian(mu, sigma);
    }

}