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: 796543 $ $Date: 2009-07-21 17:32:38 -0400 (Tue, 21 Jul 2009) $
27   */
28  public class RandomAdaptor extends Random implements RandomGenerator {
29      
30      /** Serializable version identifier. */
31      private static final long serialVersionUID = 2306581345647615033L;
32  
33      /** Wrapped randomGenerator instance */
34      private RandomGenerator randomGenerator = null;
35  
36      /** 
37       * Prevent instantiation without a generator argument
38       */ 
39      @SuppressWarnings("unused")
40      private RandomAdaptor() { }
41      
42      /**
43       * Construct a RandomAdaptor wrapping the supplied RandomGenerator.
44       * 
45       * @param randomGenerator  the wrapped generator
46       */
47      public RandomAdaptor(RandomGenerator randomGenerator) {
48          this.randomGenerator = randomGenerator;
49      } 
50      
51      /**
52       * Factory method to create a <code>Random</code> using the supplied
53       * <code>RandomGenerator</code>.
54       * 
55       * @param randomGenerator  wrapped RandomGenerator instance
56       * @return a Random instance wrapping the RandomGenerator
57       */
58      public static Random createAdaptor(RandomGenerator randomGenerator) {
59          return new RandomAdaptor(randomGenerator);
60      }
61      
62      /**
63       * Returns the next pseudorandom, uniformly distributed
64       * <code>boolean</code> value from this random number generator's
65       * sequence.  
66       * 
67       * @return  the next pseudorandom, uniformly distributed
68       * <code>boolean</code> value from this random number generator's
69       * sequence
70       */
71      @Override
72      public boolean nextBoolean() {
73          return randomGenerator.nextBoolean();
74      }
75  
76       /**
77       * Generates random bytes and places them into a user-supplied 
78       * byte array.  The number of random bytes produced is equal to 
79       * the length of the byte array.
80       * 
81       * @param bytes the non-null byte array in which to put the 
82       * random bytes
83       */
84      @Override
85      public void nextBytes(byte[] bytes) {
86          randomGenerator.nextBytes(bytes);
87      }
88  
89       /**
90       * Returns the next pseudorandom, uniformly distributed 
91       * <code>double</code> value between <code>0.0</code> and
92       * <code>1.0</code> from this random number generator's sequence.  
93       *
94       * @return  the next pseudorandom, uniformly distributed 
95       *  <code>double</code> value between <code>0.0</code> and
96       *  <code>1.0</code> from this random number generator's sequence
97       */  
98      @Override
99      public double nextDouble() {
100         return randomGenerator.nextDouble();
101     }
102 
103     /**
104      * Returns the next pseudorandom, uniformly distributed <code>float</code>
105      * value between <code>0.0</code> and <code>1.0</code> from this random
106      * number generator's sequence.  
107      *
108      * @return  the next pseudorandom, uniformly distributed <code>float</code>
109      * value between <code>0.0</code> and <code>1.0</code> from this
110      * random number generator's sequence
111      */
112     @Override
113     public float nextFloat() {
114         return randomGenerator.nextFloat();
115     }
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     @Override
128     public double nextGaussian() {
129         return randomGenerator.nextGaussian();
130     }
131 
132      /**
133      * Returns the next pseudorandom, uniformly distributed <code>int</code>
134      * value from this random number generator's sequence.  
135      * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
136      * should be produced with  (approximately) equal probability. 
137      *
138      * @return the next pseudorandom, uniformly distributed <code>int</code>
139      *  value from this random number generator's sequence
140      */
141     @Override
142     public int nextInt() {
143         return randomGenerator.nextInt();
144     }
145 
146     /**
147      * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
148      * between 0 (inclusive) and the specified value (exclusive), drawn from
149      * this random number generator's sequence.   
150      *
151      * @param n the bound on the random number to be returned.  Must be
152      * positive.
153      * @return  a pseudorandom, uniformly distributed <tt>int</tt>
154      * value between 0 (inclusive) and n (exclusive).
155      * @throws IllegalArgumentException  if n is not positive.
156      */
157     @Override
158     public int nextInt(int n) {
159         return randomGenerator.nextInt(n);
160     }
161 
162     /**
163      * Returns the next pseudorandom, uniformly distributed <code>long</code>
164      * value from this random number generator's sequence.  All 
165      * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
166      * should be produced with (approximately) equal probability. 
167      *
168      * @return  the next pseudorandom, uniformly distributed <code>long</code>
169      *value from this random number generator's sequence
170      */
171     @Override
172     public long nextLong() {
173         return randomGenerator.nextLong();
174     }
175 
176     /** {@inheritDoc} */
177     public void setSeed(int seed) {
178         if (randomGenerator != null) {  // required to avoid NPE in constructor
179             randomGenerator.setSeed(seed);
180         }
181     }
182 
183     /** {@inheritDoc} */
184     public void setSeed(int[] seed) {
185         if (randomGenerator != null) {  // required to avoid NPE in constructor
186             randomGenerator.setSeed(seed);
187         }
188     }
189 
190     /** {@inheritDoc} */
191     @Override
192     public void setSeed(long seed) {
193         if (randomGenerator != null) {  // required to avoid NPE in constructor
194             randomGenerator.setSeed(seed);
195         }
196     }
197 
198 }