View Javadoc

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