1 /*

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

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package java.util;

    26 

    27 import java.util.Rng;

    28 import java.util.RngSupport;

    29 import java.util.stream.Stream;

    30 

    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 public interface StreamableRng extends Rng {

    67     /**

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

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

    70      * generators in the stream will appear to be statistically

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

    72      * as this generator.

    73      *

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

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

    76      *

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

    78      */

    79     Stream<Rng> rngs();

    80 

    81     /**

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

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

    84      * generators in the stream will appear to be statistically

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

    86      * as this generator.

    87      *

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

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

    90      *

    91      * @param streamSize the number of generators to generate

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

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

    94      *         less than zero

    95      */

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

    97 	RngSupport.checkStreamSize(streamSize);

    98         return rngs().limit(streamSize);

    99     }

   100 }