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 }