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  import java.io.Serializable;
20  
21  /**
22   * Interface extracted from <code>java.util.Random</code>.  This interface is
23   * implemented by {@link AbstractRandomGenerator}.  
24   *
25   * @since 1.1
26   * @version $Revision: 628614 $ $Date: 2008-02-17 21:47:53 -0700 (Sun, 17 Feb 2008) $
27   */
28  public interface RandomGenerator extends Serializable {
29      
30      /**
31       * Sets the seed of the underyling random number generator using a 
32       * <code>long</code> seed.  Sequences of values generated starting with the
33       * same seeds should be identical.
34       *
35       * @param seed the seed value
36       */
37      void setSeed(long seed);
38      
39      /**
40       * Generates random bytes and places them into a user-supplied 
41       * byte array.  The number of random bytes produced is equal to 
42       * the length of the byte array.
43       * 
44       * @param bytes the non-null byte array in which to put the 
45       * random bytes
46       */
47      void nextBytes(byte[] bytes);
48      
49      /**
50       * Returns the next pseudorandom, uniformly distributed <code>int</code>
51       * value from this random number generator's sequence.  
52       * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
53       * should be produced with  (approximately) equal probability. 
54       *
55       * @return the next pseudorandom, uniformly distributed <code>int</code>
56       *  value from this random number generator's sequence
57       */
58      int nextInt();
59      
60      /**
61       * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
62       * between 0 (inclusive) and the specified value (exclusive), drawn from
63       * this random number generator's sequence.   
64       *
65       * @param n the bound on the random number to be returned.  Must be
66       * positive.
67       * @return  a pseudorandom, uniformly distributed <tt>int</tt>
68       * value between 0 (inclusive) and n (exclusive).
69       * @throws IllegalArgumentException  if n is not positive.
70       */
71      int nextInt(int n);
72      
73      /**
74       * Returns the next pseudorandom, uniformly distributed <code>long</code>
75       * value from this random number generator's sequence.  All 
76       * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
77       * should be produced with (approximately) equal probability. 
78       *
79       * @return  the next pseudorandom, uniformly distributed <code>long</code>
80       *value from this random number generator's sequence
81       */
82      long nextLong();
83      
84      /**
85       * Returns the next pseudorandom, uniformly distributed
86       * <code>boolean</code> value from this random number generator's
87       * sequence.  
88       * 
89       * @return  the next pseudorandom, uniformly distributed
90       * <code>boolean</code> value from this random number generator's
91       * sequence
92       */
93      boolean nextBoolean();
94      
95      /**
96       * Returns the next pseudorandom, uniformly distributed <code>float</code>
97       * value between <code>0.0</code> and <code>1.0</code> from this random
98       * number generator's sequence.  
99       *
100      * @return  the next pseudorandom, uniformly distributed <code>float</code>
101      * value between <code>0.0</code> and <code>1.0</code> from this
102      * random number generator's sequence
103      */
104     float nextFloat();
105     
106     /**
107      * Returns the next pseudorandom, uniformly distributed 
108      * <code>double</code> value between <code>0.0</code> and
109      * <code>1.0</code> from this random number generator's sequence.  
110      *
111      * @return  the next pseudorandom, uniformly distributed 
112      *  <code>double</code> value between <code>0.0</code> and
113      *  <code>1.0</code> from this random number generator's sequence
114      */  
115     double nextDouble();
116     
117     /**
118      * Returns the next pseudorandom, Gaussian ("normally") distributed
119      * <code>double</code> value with mean <code>0.0</code> and standard
120      * deviation <code>1.0</code> from this random number generator's sequence.
121      * 
122      * @return  the next pseudorandom, Gaussian ("normally") distributed
123      * <code>double</code> value with mean <code>0.0</code> and
124      * standard deviation <code>1.0</code> from this random number
125      *  generator's sequence
126      */
127     double nextGaussian();
128 }