1 /*

     2  * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.

     3  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

     4  *

     5  *

     6  *

     7  *

     8  *

     9  *

    10  *

    11  *

    12  *

    13  *

    14  *

    15  *

    16  *

    17  *

    18  *

    19  *

    20  *

    21  *

    22  *

    23  *

    24  */

    25 // package java.util;

    26 

    27 import java.math.BigInteger;

    28 import java.util.stream.DoubleStream;

    29 import java.util.stream.IntStream;

    30 import java.util.stream.LongStream;

    31 

    32 /**

    33  * The {@code StreamableRng} interface augments the {@code Rng} interface

    34  * to provide methods that return streams of {@code Rng} objects.

    35  * Ideally, such a stream of objects would have the property that the

    36  * behavior of each object is statistically independent of all the others.

    37  * In practice, one may have to settle for some approximation to this property.

    38  *

    39  * A generator that implements interface {@link java.util.SplittableRng}

    40  * may choose to use its {@code splits} method to implement the {@code rngs}

    41  * method required by this interface.

    42  *

    43  * A generator that implements interface {@link java.util.JumpableRng}

    44  * may choose to use its {@code jumps} method to implement the {@code rngs}

    45  * method required by this interface.

    46  *

    47  * A generator that implements interface {@link java.util.LeapableRng}

    48  * may choose to use its {@code leaps} method to implement the {@code rngs}

    49  * method required by this interface.

    50  *

    51  * <p>An implementation of the {@code StreamableRng} interface must provide

    52  * concrete definitions for the methods {@code nextInt()}, {@code nextLong},

    53  * {@code period()}, and {@code rngs()}.

    54  * Default implementations are provided for all other methods.

    55  *

    56  * <p>Objects that implement {@code java.util.StreamableRng} are typically

    57  * not cryptographically secure.  Consider instead using

    58  * {@link java.security.SecureRandom} to get a cryptographically

    59  * secure pseudo-random number generator for use by

    60  * security-sensitive applications.

    61  *

    62  * @author  Guy Steele

    63  * @since   1.9

    64  */

    65 

    66 import java.util.stream.Stream;

    67 

    68 interface StreamableRng extends Rng {

    69     /**

    70      * Returns an effectively unlimited stream of objects, each of

    71      * which implements the {@code Rng} interface.  Ideally the

    72      * generators in the stream will appear to be statistically

    73      * independent.  The new generators should be of the same kind

    74      * as this generator.

    75      *

    76      * @implNote It is permitted to implement this method in a manner

    77      * equivalent to {@code rngs(Long.MAX_VALUE)}.

    78      *

    79      * @return a stream of objects that implement the {@code Rng} interface

    80      */

    81     Stream<Rng> rngs();

    82 

    83     /**

    84      * Returns an effectively unlimited stream of objects, each of

    85      * which implements the {@code Rng} interface.  Ideally the

    86      * generators in the stream will appear to be statistically

    87      * independent.  The new generators should be of the same kind

    88      * as this generator.

    89      *

    90      * @implNote The default implementation calls {@code rngs()} and

    91      * then limits its length to {@code streamSize}.

    92      *

    93      * @param streamSize the number of generators to generate

    94      * @return a stream of objects that implement the {@code Rng} interface

    95      * @throws IllegalArgumentException if {@code streamSize} is

    96      *         less than zero

    97      */

    98     default Stream<Rng> rngs(long streamSize) {

    99 	RngSupport.checkStreamSize(streamSize);

   100         return rngs().limit(streamSize);

   101     }

   102 }