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