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 18package java.util; 19 20 21import java.io.Serializable; 22 23/** 24 * This class provides methods that return pseudo-random values. 25 * 26 * <p>It is dangerous to seed {@code Random} with the current time because 27 * that value is more predictable to an attacker than the default seed. 28 * 29 * <p>This class is thread-safe. 30 * 31 * @see java.security.SecureRandom 32 */ 33public class Random implements Serializable { 34 35 private static final long serialVersionUID = 3905348978240129619L; 36 37 private static final long multiplier = 0x5deece66dL; 38 39 /** 40 * The boolean value indicating if the second Gaussian number is available. 41 * 42 * @serial 43 */ 44 private boolean haveNextNextGaussian; 45 46 /** 47 * @serial It is associated with the internal state of this generator. 48 */ 49 private long seed; 50 51 /** 52 * The second Gaussian generated number. 53 * 54 * @serial 55 */ 56 private double nextNextGaussian; 57 58 /** 59 * Constructs a random generator with an initial state that is 60 * unlikely to be duplicated by a subsequent instantiation. 61 * 62 * <p>The initial state (that is, the seed) is <i>partially</i> based 63 * on the current time of day in milliseconds. 64 */ 65 public Random() { 66 // Note: Using identityHashCode() to be hermetic wrt subclasses. 67 setSeed(System.currentTimeMillis() + System.identityHashCode(this)); 68 } 69 70 /** 71 * Construct a random generator with the given {@code seed} as the 72 * initial state. Equivalent to {@code Random r = new Random(); r.setSeed(seed);}. 73 * 74 * <p>This constructor is mainly useful for <i>predictability</i> in tests. 75 * The default constructor is likely to provide better randomness. 76 */ 77 public Random(long seed) { 78 setSeed(seed); 79 } 80 81 /** 82 * Returns a pseudo-random uniformly distributed {@code int} value of 83 * the number of bits specified by the argument {@code bits} as 84 * described by Donald E. Knuth in <i>The Art of Computer Programming, 85 * Volume 2: Seminumerical Algorithms</i>, section 3.2.1. 86 * 87 * <p>Most applications will want to use one of this class' convenience methods instead. 88 */ 89 protected synchronized int next(int bits) { 90 seed = (seed * multiplier + 0xbL) & ((1L << 48) - 1); 91 return (int) (seed >>> (48 - bits)); 92 } 93 94 /** 95 * Returns a pseudo-random uniformly distributed {@code boolean}. 96 */ 97 public boolean nextBoolean() { 98 return next(1) != 0; 99 } 100 101 /** 102 * Fills {@code buf} with random bytes. 103 */ 104 public void nextBytes(byte[] buf) { 105 int rand = 0, count = 0, loop = 0; 106 while (count < buf.length) { 107 if (loop == 0) { 108 rand = nextInt(); 109 loop = 3; 110 } else { 111 loop--; 112 } 113 buf[count++] = (byte) rand; 114 rand >>= 8; 115 } 116 } 117 118 /** 119 * Returns a pseudo-random uniformly distributed {@code double} 120 * in the half-open range [0.0, 1.0). 121 */ 122 public double nextDouble() { 123 return ((((long) next(26) << 27) + next(27)) / (double) (1L << 53)); 124 } 125 126 /** 127 * Returns a pseudo-random uniformly distributed {@code float} 128 * in the half-open range [0.0, 1.0). 129 */ 130 public float nextFloat() { 131 return (next(24) / 16777216f); 132 } 133 134 /** 135 * Returns a pseudo-random (approximately) normally distributed 136 * {@code double} with mean 0.0 and standard deviation 1.0. 137 * This method uses the <i>polar method</i> of G. E. P. Box, M. 138 * E. Muller, and G. Marsaglia, as described by Donald E. Knuth in <i>The 139 * Art of Computer Programming, Volume 2: Seminumerical Algorithms</i>, 140 * section 3.4.1, subsection C, algorithm P. 141 */ 142 public synchronized double nextGaussian() { 143 if (haveNextNextGaussian) { 144 haveNextNextGaussian = false; 145 return nextNextGaussian; 146 } 147 148 double v1, v2, s; 149 do { 150 v1 = 2 * nextDouble() - 1; 151 v2 = 2 * nextDouble() - 1; 152 s = v1 * v1 + v2 * v2; 153 } while (s >= 1 || s == 0); 154 155 // The specification says this uses StrictMath. 156 double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s) / s); 157 nextNextGaussian = v2 * multiplier; 158 haveNextNextGaussian = true; 159 return v1 * multiplier; 160 } 161 162 /** 163 * Returns a pseudo-random uniformly distributed {@code int}. 164 */ 165 public int nextInt() { 166 return next(32); 167 } 168 169 /** 170 * Returns a pseudo-random uniformly distributed {@code int} 171 * in the half-open range [0, n). 172 */ 173 public int nextInt(int n) { 174 if (n > 0) { 175 if ((n & -n) == n) { 176 return (int) ((n * (long) next(31)) >> 31); 177 } 178 int bits, val; 179 do { 180 bits = next(31); 181 val = bits % n; 182 } while (bits - val + (n - 1) < 0); 183 return val; 184 } 185 throw new IllegalArgumentException(); 186 } 187 188 /** 189 * Returns a pseudo-random uniformly distributed {@code long}. 190 */ 191 public long nextLong() { 192 return ((long) next(32) << 32) + next(32); 193 } 194 195 /** 196 * Modifies the seed using a linear congruential formula presented in <i>The 197 * Art of Computer Programming, Volume 2</i>, Section 3.2.1. 198 */ 199 public synchronized void setSeed(long seed) { 200 this.seed = (seed ^ multiplier) & ((1L << 48) - 1); 201 haveNextNextGaussian = false; 202 } 203} 204