/*
 Copyright (C) 2007 Richard Gomes

 This file is part of JQuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://jquantlib.org/

 JQuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 . The license is also available online at
 .

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
 
 JQuantLib is based on QuantLib. http://quantlib.org/
 When applicable, the original copyright notice follows this notice.
 */

package org.jquantlib.math.randomnumbers;

import org.jquantlib.methods.montecarlo.Sample;

/**
 * This interface defines the behaviour of all RandomSequenceGenerators, making it easy to pass them as generic parameters.
 * 
 * @author Richard Gomes
 */
@Deprecated
// FIXME: code review :: possibly rename this interface ???
// FIXME:: Should this interface be kept or deleted ???
// This code is a work in progress and needs code review. [Richard Gomes]
public interface RandomSequenceGeneratorIntf {

    public Sample nextSequence() /*@ReadOnly*/;

    public Sample lastSequence() /*@ReadOnly*/;

    /**
     * Once JVM does not support unsigned fixed arithmetic, we use 64bit variables as containers for 32bit values in order to reduce
     * the complexity and performance overhead of certain fixed arithmetic operations.
     * 

     * From the user's perspective, it's easier to understand that a certain long variable contains 
     * values from 0 to 2^32 than understand that a certain int variable contains negative values that should be 
     * converted to it's two's complement and extended to a long variable before use.
     * 
     * @see Bug 4504839
     * @see Java and Unsigned Types
     * @see Two's complement
     * 
     * @return an array of unsigned 32bit wide numbers encapsulated in a 64bit containers
     */
    public /*@UnsignedInt*/ long[] nextInt32Sequence() /*@ReadOnly*/;

    public /*@NonNegative*/ int dimension() /* @ReadOnly */;

}