RateLimitInputStream (spiceJ: Core 0.0.9 API)

java.lang.Object
- java.io.InputStream
- - at.borkowski.spicej.streams.RateLimitInputStream

All Implemented Interfaces:

RateShaper, Closeable, AutoCloseable
```
public class RateLimitInputStream
extends InputStream
implements RateShaper
```
Provides an InputStream with a limited rate of bytes. A stream has two blocking modes: blocking and non-blocking. If the stream is in non-blocking mode, any call that would cause the stream to block (ie. all read calls when no data is available) throw a WouldBlockException. A stream has two boring modes: boring and non-boring. The boring flag modifies he behavior of read(byte[], int, int) and read(byte[]). According to InputStream, they method read between 1 and n bytes, where n is the size of the effective buffer. If the RateLimitInputStream is in boring mode, the methods block until all actually available bytes have been read, even if many ticks must be waited for the data to become available according to the set rate. In non-boring mode, the methods do not block and read only data which can be read immediately (except for the first byte which, according to the definition of InputStream, causes blocking for all read methods). Note that blocking and boring are two different concept even though they seem similar. Non-blocking will cause methods to throw exceptions, where non-boring only means that read methods exit sooner in certain situations than in boring mode. Streams are non-boring by default.

Constructor Summary

Constructors
Constructor and Description
`RateLimitInputStream(InputStream real, TickSource tickSource, int byteRate, int prescale)` Constructs a byte-rate-limited `InputStream`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`available()` This method complies with `InputStream.available()` and imposes stronger postconditions.
`void`	`close()`
`InputStream`	`getBaseStream()` Returns the underlying `InputStream`.
`int`	`getByteRate()` Returns the bytes per tick (after prescaling) for this rate shaper.
`int`	`getPrescale()` Returns the current prescale value (ie.
`TickSource`	`getTickSource()` Returns the `TickSource` this stream uses.
`void`	`mark(int readlimit)`
`boolean`	`markSupported()`
`int`	`read()` Reads one byte from the stream.
`int`	`read(byte[] b)` Behaves the same as:
`int`	`read(byte[] b, int off, int len)` This method complies with `InputStream.read(byte[], int, int)` and imposes stronger postconditions.
`void`	`reset()`
`void`	`setBoring(boolean boring)` Sets the boring flag.
`void`	`setByteRate(int bytesPerTick)` Sets a new byte rate per tick (after prescaling) for this rate shaper.
`void`	`setNonBlocking(boolean nonBlocking)` Sets the non-blocking flag.
`void`	`setPrescale(int prescale)` Sets a new prescale value (ie.

Methods inherited from class java.io.InputStream
skip

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - RateLimitInputStream
```
public RateLimitInputStream(InputStream real,
                            TickSource tickSource,
                            int byteRate,
                            int prescale)
```
    Constructs a byte-rate-limited InputStream. The rate is given using two numbers: bytes per tick, and a prescale. The prescale divides the incoming ticks by a constant number. A prescale of 1 means that each tick coming from the tick source is counting towards the rate, a prescale of 2 means every second, and so on. The prescale can be used to achieve low byte rates, ie. rates below 1 byte per tick. For example, a rate of 1 byte per tick and a prescale of 4 means that one byte is read after 4 ticks coming from the tick source.
    
    Parameters:
    
    real - The actual InputStream to read from
    
    tickSource - The tick source
    
    byteRate - The rate, ie. the limit of how many bytes per tick (after prescaling) should be readable from this stream
    
    prescale - The prescaling, ie. the frequency of ticks to actually consider for rating.
- Method Detail
  - setByteRate
```
public void setByteRate(int bytesPerTick)
```
    Description copied from interface: RateShaper
    
    Sets a new byte rate per tick (after prescaling) for this rate shaper.
    
    Specified by:
    
    setByteRate in interface RateShaper
    
    Parameters:
    
    bytesPerTick - the new byte rate per tick (after prescaling)
  - getByteRate
```
public int getByteRate()
```
    Description copied from interface: RateShaper
    
    Returns the bytes per tick (after prescaling) for this rate shaper.
    
    Specified by:
    
    getByteRate in interface RateShaper
    
    Returns:
    
    the current byte rate
  - read
```
public int read()
         throws IOException
```
    Reads one byte from the stream. This method blocks if there is no byte available from the underlying InputStream or a rate block has been encountered, regardless of the stream's boring flag.
    
    Specified by:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b,
                int off,
                int len)
         throws IOException
```
    This method complies with InputStream.read(byte[], int, int) and imposes stronger postconditions. Reads up to len bytes from the stream. This method blocks for the first byte reagrdless of the stream's boring flag. For all subsequent bytes, the behavior depends on the boring flag:
    - In boring mode, the stream blocks until all bytes actually available from the underlying InputStream (reported by InputStream.available()) have been read, even if this means waiting for the next tick.
    - In non-boring mode, the stream does not block for the first byte's subsequent bytes. This means that if a rate limitation is in place (ie. the rate has been reached for the current tick), this method does not attempt to read the bytes (the number of actually read bytes is returned conforming with InputStream.read(byte[], int, int).
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b)
         throws IOException
```
    Behaves the same as:
```
 read(b, 0, b.length);
 
```
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - available
```
public int available()
              throws IOException
```
    This method complies with InputStream.available() and imposes stronger postconditions. The returned value is the number of bytes available for immediate reading. If there is no rate limitation in place (ie. the rate has not been reached for the current tick), the InputStream.available() method of the underlying InputStream is called. If a rate limitation is in place, the number of bytes readable in the current tick is returned.
    
    Overrides:
    
    available in class InputStream
    
    Throws:
    
    IOException
  - close
```
public void close()
           throws IOException
```
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class InputStream
    
    Throws:
    
    IOException
  - mark
```
public void mark(int readlimit)
```
    Overrides:
    
    mark in class InputStream
  - markSupported
```
public boolean markSupported()
```
    Overrides:
    
    markSupported in class InputStream
  - reset
```
public void reset()
           throws IOException
```
    Overrides:
    
    reset in class InputStream
    
    Throws:
    
    IOException
  - setBoring
```
public void setBoring(boolean boring)
```
    Sets the boring flag.
    
    Parameters:
    
    boring - whether the stream should be in boring mode (see RateLimitInputStream(InputStream, TickSource, int, int) ).
  - setNonBlocking
```
public void setNonBlocking(boolean nonBlocking)
```
    Sets the non-blocking flag.
    
    Parameters:
    
    nonBlocking - whether the stream should be in non-blocking mode (see RateLimitInputStream).
  - getBaseStream
```
public InputStream getBaseStream()
```
    Returns the underlying InputStream.
    
    Returns:
    
    the underlying stream
  - getTickSource
```
public TickSource getTickSource()
```
    Returns the TickSource this stream uses.
    
    Returns:
    
    the used tick source
  - getPrescale
```
public int getPrescale()
```
    Description copied from interface: RateShaper
    
    Returns the current prescale value (ie. one of how many ticks is actually counting towards the things per tick notion).
    
    Specified by:
    
    getPrescale in interface RateShaper
    
    Returns:
    
    the current prescale value
  - setPrescale
```
public void setPrescale(int prescale)
```
    Description copied from interface: RateShaper
    
    Sets a new prescale value (ie. one of how many ticks is actually counting towards the things per tick notion).
    
    Specified by:
    
    setPrescale in interface RateShaper
    
    Parameters:
    
    prescale - the new prescale

Class RateLimitInputStream

Constructor Summary

Method Summary

Methods inherited from class java.io.InputStream

Methods inherited from class java.lang.Object

Constructor Detail

RateLimitInputStream

Method Detail

setByteRate

getByteRate

read

read

read

available

close

mark

markSupported

reset

setBoring

setNonBlocking

getBaseStream

getTickSource

getPrescale

setPrescale