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.util.Random;
20  
21  /**
22   * Extension of <code>java.util.Random</code> wrapping a
23   * {@link RandomGenerator}.   
24   *
25   * @since 1.1
26   * @version $Revision: 628614 $ $Date: 2008-02-17 21:47:53 -0700 (Sun, 17 Feb 2008) $
27   */
28  public class RandomAdaptor extends Random implements RandomGenerator {
29      
30      /** Serializable version identifier */
31      private static final long serialVersionUID = 2570805822599485047L;
32  
33      /** Wrapped randomGenerator instance */
34      private RandomGenerator randomGenerator = null;
35      
36      /** 
37       * Prevent instantiation without a generator argument
38       */ 
39      private RandomAdaptor() { }
40      
41      /**
42       * Construct a RandomAdaptor wrapping the supplied RandomGenerator.
43       * 
44       * @param randomGenerator  the wrapped generator
45       */
46      public RandomAdaptor(RandomGenerator randomGenerator) {
47          this.randomGenerator = randomGenerator;
48      } 
49      
50      /**
51       * Factory method to create a <code>Random</code> using the supplied
52       * <code>RandomGenerator</code>.
53       * 
54       * @param randomGenerator  wrapped RandomGenerator instance
55       * @return a Random instance wrapping the RandomGenerator
56       */
57      public static Random createAdaptor(RandomGenerator randomGenerator) {
58          return new RandomAdaptor(randomGenerator);
59      }
60      
61      /**
62       * Returns the next pseudorandom, uniformly distributed
63       * <code>boolean</code> value from this random number generator's
64       * sequence.  
65       * 
66       * @return  the next pseudorandom, uniformly distributed
67       * <code>boolean</code> value from this random number generator's
68       * sequence
69       */
70      public boolean nextBoolean() {
71          return randomGenerator.nextBoolean();
72      }
73  
74       /**
75       * Generates random bytes and places them into a user-supplied 
76       * byte array.  The number of random bytes produced is equal to 
77       * the length of the byte array.
78       * 
79       * @param bytes the non-null byte array in which to put the 
80       * random bytes
81       */
82      public void nextBytes(byte[] bytes) {
83          randomGenerator.nextBytes(bytes);
84      }
85  
86       /**
87       * Returns the next pseudorandom, uniformly distributed 
88       * <code>double</code> value between <code>0.0</code> and
89       * <code>1.0</code> from this random number generator's sequence.  
90       *
91       * @return  the next pseudorandom, uniformly distributed 
92       *  <code>double</code> value between <code>0.0</code> and
93       *  <code>1.0</code> from this random number generator's sequence
94       */  
95      public double nextDouble() {
96          return randomGenerator.nextDouble();
97      }
98  
99      /**
100      * Returns the next pseudorandom, uniformly distributed <code>float</code>
101      * value between <code>0.0</code> and <code>1.0</code> from this random
102      * number generator's sequence.  
103      *
104      * @return  the next pseudorandom, uniformly distributed <code>float</code>
105      * value between <code>0.0</code> and <code>1.0</code> from this
106      * random number generator's sequence
107      */
108     public float nextFloat() {
109         return randomGenerator.nextFloat();
110     }
111 
112     /**
113      * Returns the next pseudorandom, Gaussian ("normally") distributed
114      * <code>double</code> value with mean <code>0.0</code> and standard
115      * deviation <code>1.0</code> from this random number generator's sequence.
116      * 
117      * @return  the next pseudorandom, Gaussian ("normally") distributed
118      * <code>double</code> value with mean <code>0.0</code> and
119      * standard deviation <code>1.0</code> from this random number
120      *  generator's sequence
121      */
122     public double nextGaussian() {
123         return randomGenerator.nextGaussian();
124     }
125 
126      /**
127      * Returns the next pseudorandom, uniformly distributed <code>int</code>
128      * value from this random number generator's sequence.  
129      * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
130      * should be produced with  (approximately) equal probability. 
131      *
132      * @return the next pseudorandom, uniformly distributed <code>int</code>
133      *  value from this random number generator's sequence
134      */
135     public int nextInt() {
136         return randomGenerator.nextInt();
137     }
138 
139     /**
140      * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
141      * between 0 (inclusive) and the specified value (exclusive), drawn from
142      * this random number generator's sequence.   
143      *
144      * @param n the bound on the random number to be returned.  Must be
145      * positive.
146      * @return  a pseudorandom, uniformly distributed <tt>int</tt>
147      * value between 0 (inclusive) and n (exclusive).
148      * @throws IllegalArgumentException  if n is not positive.
149      */
150     public int nextInt(int n) {
151         return randomGenerator.nextInt(n);
152     }
153 
154     /**
155      * Returns the next pseudorandom, uniformly distributed <code>long</code>
156      * value from this random number generator's sequence.  All 
157      * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
158      * should be produced with (approximately) equal probability. 
159      *
160      * @return  the next pseudorandom, uniformly distributed <code>long</code>
161      *value from this random number generator's sequence
162      */
163     public long nextLong() {
164         return randomGenerator.nextLong();
165     }
166 
167     /**
168      * Sets the seed of the underyling random number generator using a 
169      * <code>long</code> seed.  Sequences of values generated starting with the
170      * same seeds should be identical.
171      *
172      * @param seed the seed value
173      */
174     public void setSeed(long seed) {
175         if (randomGenerator != null) {  // required to avoid NPE in constructor
176             randomGenerator.setSeed(seed);
177         }
178     }
179 }