001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.math.random;
018    
019    
020    /**
021     * Interface extracted from <code>java.util.Random</code>.  This interface is
022     * implemented by {@link AbstractRandomGenerator}.  
023     *
024     * @since 1.1
025     * @version $Revision: 796543 $ $Date: 2009-07-21 17:32:38 -0400 (Tue, 21 Jul 2009) $
026     */
027    public interface RandomGenerator {
028        
029        /**
030         * Sets the seed of the underyling random number generator using an
031         * <code>int</code> seed.
032         * <p>Sequences of values generated starting with the same seeds
033         * should be identical.
034         * </p>
035         * @param seed the seed value
036         */
037        void setSeed(int seed);
038    
039        /**
040         * Sets the seed of the underyling random number generator using an
041         * <code>int</code> array seed.
042         * <p>Sequences of values generated starting with the same seeds
043         * should be identical.
044         * </p>
045         * @param seed the seed value
046         */
047        void setSeed(int[] seed);
048        
049        /**
050         * Sets the seed of the underyling random number generator using a
051         * <code>long</code> seed.
052         * <p>Sequences of values generated starting with the same seeds
053         * should be identical.
054         * </p>
055         * @param seed the seed value
056         */
057        void setSeed(long seed);
058        
059        /**
060         * Generates random bytes and places them into a user-supplied 
061         * byte array.  The number of random bytes produced is equal to 
062         * the length of the byte array.
063         * 
064         * @param bytes the non-null byte array in which to put the 
065         * random bytes
066         */
067        void nextBytes(byte[] bytes);
068        
069        /**
070         * Returns the next pseudorandom, uniformly distributed <code>int</code>
071         * value from this random number generator's sequence.  
072         * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
073         * should be produced with  (approximately) equal probability. 
074         *
075         * @return the next pseudorandom, uniformly distributed <code>int</code>
076         *  value from this random number generator's sequence
077         */
078        int nextInt();
079        
080        /**
081         * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
082         * between 0 (inclusive) and the specified value (exclusive), drawn from
083         * this random number generator's sequence.   
084         *
085         * @param n the bound on the random number to be returned.  Must be
086         * positive.
087         * @return  a pseudorandom, uniformly distributed <tt>int</tt>
088         * value between 0 (inclusive) and n (exclusive).
089         * @throws IllegalArgumentException  if n is not positive.
090         */
091        int nextInt(int n);
092        
093        /**
094         * Returns the next pseudorandom, uniformly distributed <code>long</code>
095         * value from this random number generator's sequence.  All 
096         * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
097         * should be produced with (approximately) equal probability. 
098         *
099         * @return  the next pseudorandom, uniformly distributed <code>long</code>
100         *value from this random number generator's sequence
101         */
102        long nextLong();
103        
104        /**
105         * Returns the next pseudorandom, uniformly distributed
106         * <code>boolean</code> value from this random number generator's
107         * sequence.  
108         * 
109         * @return  the next pseudorandom, uniformly distributed
110         * <code>boolean</code> value from this random number generator's
111         * sequence
112         */
113        boolean nextBoolean();
114        
115        /**
116         * Returns the next pseudorandom, uniformly distributed <code>float</code>
117         * value between <code>0.0</code> and <code>1.0</code> from this random
118         * number generator's sequence.  
119         *
120         * @return  the next pseudorandom, uniformly distributed <code>float</code>
121         * value between <code>0.0</code> and <code>1.0</code> from this
122         * random number generator's sequence
123         */
124        float nextFloat();
125        
126        /**
127         * Returns the next pseudorandom, uniformly distributed 
128         * <code>double</code> value between <code>0.0</code> and
129         * <code>1.0</code> from this random number generator's sequence.  
130         *
131         * @return  the next pseudorandom, uniformly distributed 
132         *  <code>double</code> value between <code>0.0</code> and
133         *  <code>1.0</code> from this random number generator's sequence
134         */  
135        double nextDouble();
136        
137        /**
138         * Returns the next pseudorandom, Gaussian ("normally") distributed
139         * <code>double</code> value with mean <code>0.0</code> and standard
140         * deviation <code>1.0</code> from this random number generator's sequence.
141         * 
142         * @return  the next pseudorandom, Gaussian ("normally") distributed
143         * <code>double</code> value with mean <code>0.0</code> and
144         * standard deviation <code>1.0</code> from this random number
145         *  generator's sequence
146         */
147        double nextGaussian();
148    }