View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.random;
17  
18  /**
19   * Interface extracted from <code>java.util.Random</code>.  This interface is
20   * implemented by {@link AbstractRandomGenerator}.  
21   *
22   * @since 1.1
23   * @version $Revision:$ $Date$
24   */
25  public interface RandomGenerator {
26      
27      /**
28       * Sets the seed of the underyling random number generator using a 
29       * <code>long</code> seed.  Sequences of values generated starting with the
30       * same seeds should be identical.
31       *
32       * @param seed the seed value
33       */
34      void setSeed(long seed);
35      
36      /**
37       * Generates random bytes and places them into a user-supplied 
38       * byte array.  The number of random bytes produced is equal to 
39       * the length of the byte array.
40       * 
41       * @param bytes the non-null byte array in which to put the 
42       * random bytes
43       */
44      void nextBytes(byte[] bytes);
45      
46      /**
47       * Returns the next pseudorandom, uniformly distributed <code>int</code>
48       * value from this random number generator's sequence.  
49       * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
50       * should be produced with  (approximately) equal probability. 
51       *
52       * @return the next pseudorandom, uniformly distributed <code>int</code>
53       *  value from this random number generator's sequence
54       */
55      int nextInt();
56      
57      /**
58       * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
59       * between 0 (inclusive) and the specified value (exclusive), drawn from
60       * this random number generator's sequence.   
61       *
62       * @param n the bound on the random number to be returned.  Must be
63       * positive.
64       * @return  a pseudorandom, uniformly distributed <tt>int</tt>
65       * value between 0 (inclusive) and n (exclusive).
66       * @throws IllegalArgumentException  if n is not positive.
67       */
68      int nextInt(int n);
69      
70      /**
71       * Returns the next pseudorandom, uniformly distributed <code>long</code>
72       * value from this random number generator's sequence.  All 
73       * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
74       * should be produced with (approximately) equal probability. 
75       *
76       * @return  the next pseudorandom, uniformly distributed <code>long</code>
77       *value from this random number generator's sequence
78       */
79      long nextLong();
80      
81      /**
82       * Returns the next pseudorandom, uniformly distributed
83       * <code>boolean</code> value from this random number generator's
84       * sequence.  
85       * 
86       * @return  the next pseudorandom, uniformly distributed
87       * <code>boolean</code> value from this random number generator's
88       * sequence
89       */
90      boolean nextBoolean();
91      
92      /**
93       * Returns the next pseudorandom, uniformly distributed <code>float</code>
94       * value between <code>0.0</code> and <code>1.0</code> from this random
95       * number generator's sequence.  
96       *
97       * @return  the next pseudorandom, uniformly distributed <code>float</code>
98       * value between <code>0.0</code> and <code>1.0</code> from this
99       * random number generator's sequence
100      */
101     float nextFloat();
102     
103     /**
104      * Returns the next pseudorandom, uniformly distributed 
105      * <code>double</code> value between <code>0.0</code> and
106      * <code>1.0</code> from this random number generator's sequence.  
107      *
108      * @return  the next pseudorandom, uniformly distributed 
109      *  <code>double</code> value between <code>0.0</code> and
110      *  <code>1.0</code> from this random number generator's sequence
111      */  
112     double nextDouble();
113     
114     /**
115      * Returns the next pseudorandom, Gaussian ("normally") distributed
116      * <code>double</code> value with mean <code>0.0</code> and standard
117      * deviation <code>1.0</code> from this random number generator's sequence.
118      * 
119      * @return  the next pseudorandom, Gaussian ("normally") distributed
120      * <code>double</code> value with mean <code>0.0</code> and
121      * standard deviation <code>1.0</code> from this random number
122      *  generator's sequence
123      */
124     double nextGaussian();
125 }