@UnstableApi
public interface ExtractorInput extends DataReader

Known direct subclasses
DefaultExtractorInput

An ExtractorInput that wraps a DataReader.
FakeExtractorInput

A fake ExtractorInput capable of simulating various scenarios.
ForwardingExtractorInput

An overridable ExtractorInput implementation forwarding all methods to another input.

Provides data to be consumed by an Extractor.

This interface provides two modes of accessing the underlying input. See the subheadings below for more info about each mode.

  • The read()/peek() and skip() methods provide InputStream-like byte-level access operations.
  • The read/skip/peekFully() and advancePeekPosition() methods assume the user wants to read an entire block/frame/header of known length.

InputStream-like methods

The read()/peek() and skip() methods provide InputStream-like byte-level access operations. The length parameter is a maximum, and each method returns the number of bytes actually processed. This may be less than length because the end of the input was reached, or the method was interrupted, or the operation was aborted early for another reason.

Block-based methods

The read/skip/peekFully() and advancePeekPosition() methods assume the user wants to read an entire block/frame/header of known length.

These methods all have a variant that takes a boolean allowEndOfInput parameter. This parameter is intended to be set to true when the caller believes the input might be fully exhausted before the call is made (i.e. they've previously read/skipped/peeked the final block/frame/header). It's not intended to allow a partial read (i.e. greater than 0 bytes, but less than length) to succeed - this will always throw an EOFException from these methods (a partial read is assumed to indicate a malformed block/frame/header - and therefore a malformed file).

The expected behaviour of the block-based methods is therefore:

  • Already at end-of-input and allowEndOfInput=false: Throw EOFException.
  • Already at end-of-input and allowEndOfInput=true: Return false.
  • Encounter end-of-input during read/skip/peek/advance: Throw EOFException (regardless of allowEndOfInput).

Summary

Public methods
abstract void
advancePeekPosition(int length)

Advances the peek position by length bytes.
abstract boolean
advancePeekPosition(int length, boolean allowEndOfInput)

Advances the peek position by length bytes.
abstract long

Returns the length of the source stream, or LENGTH_UNSET if it is unknown.
abstract long

Returns the current peek position (byte offset) in the stream.
abstract long

Returns the current read position (byte offset) in the stream.
abstract int
peek(byte[] target, int offset, int length)

Peeks up to length bytes from the peek position.
abstract void
peekFully(byte[] target, int offset, int length)

Equivalent to peekFully(target, offset, length, false).
abstract boolean
peekFully(byte[] target, int offset, int length, boolean allowEndOfInput)

Like peek, but peeks the requested length in full.
abstract int
read(byte[] buffer, int offset, int length)

Reads up to length bytes from the input and resets the peek position.
abstract void
readFully(byte[] target, int offset, int length)

Equivalent to readFully(target, offset, length, false).
abstract boolean
readFully(byte[] target, int offset, int length, boolean allowEndOfInput)

Like read, but reads the requested length in full.
abstract void

Resets the peek position to equal the current read position.
abstract void
<E extends Throwable> setRetryPosition(long position, E e)

Called when reading fails and the required retry position is different from the last position.
abstract int
skip(int length)

Like read, except the data is skipped instead of read.
abstract void
skipFully(int length)

Like readFully, except the data is skipped instead of read.
abstract boolean
skipFully(int length, boolean allowEndOfInput)

Like readFully, except the data is skipped instead of read.

Public methods

advancePeekPosition

abstract void advancePeekPosition(int length)

Advances the peek position by length bytes. Like peekFully except the data is skipped instead of read.

Parameters
int length

The number of bytes to peek from the input.
Throws
java.io.EOFException

If the end of input was encountered.
java.io.IOException

If an error occurs peeking from the input.

advancePeekPosition

abstract boolean advancePeekPosition(int length, boolean allowEndOfInput)

Advances the peek position by length bytes. Like peekFully except the data is skipped instead of read.

Parameters
int length

The number of bytes by which to advance the peek position.
boolean allowEndOfInput

True if encountering the end of the input before advancing is allowed, and should result in false being returned. False if it should be considered an error, causing an EOFException to be thrown. See note in class Javadoc.
Returns
boolean

True if advancing the peek position was successful. False if allowEndOfInput=true and the end of the input was encountered before advancing over any data.
Throws
java.io.EOFException

If the end of input was encountered having partially advanced (i.e. having advanced by at least one byte, but fewer than length), or if the end of input was encountered before advancing and allowEndOfInput is false.
java.io.IOException

If an error occurs advancing the peek position.

getLength

abstract long getLength()

Returns the length of the source stream, or LENGTH_UNSET if it is unknown.

Returns
long

The length of the source stream, or LENGTH_UNSET.

getPeekPosition

abstract long getPeekPosition()

Returns the current peek position (byte offset) in the stream.

Returns
long

The peek position (byte offset) in the stream.

getPosition

abstract long getPosition()

Returns the current read position (byte offset) in the stream.

Returns
long

The read position (byte offset) in the stream.

peek

abstract int peek(byte[] target, int offset, int length)

Peeks up to length bytes from the peek position. The current read position is left unchanged.

This method blocks until at least one byte of data can be peeked, the end of the input is detected, or an exception is thrown.

Calling resetPeekPosition resets the peek position to equal the current read position, so the caller can peek the same data again. Reading or skipping also resets the peek position.

Parameters
byte[] target

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The maximum number of bytes to peek from the input.
Returns
int

The number of bytes peeked, or RESULT_END_OF_INPUT if the input has ended.
Throws
java.io.IOException

If an error occurs peeking from the input.

peekFully

abstract void peekFully(byte[] target, int offset, int length)

Equivalent to peekFully(target, offset, length, false).

Parameters
byte[] target

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The number of bytes to peek from the input.
Throws
java.io.EOFException

If the end of input was encountered.
java.io.IOException

If an error occurs peeking from the input.

peekFully

abstract boolean peekFully(byte[] target, int offset, int length, boolean allowEndOfInput)

Like peek, but peeks the requested length in full.

Parameters
byte[] target

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The number of bytes to peek from the input.
boolean allowEndOfInput

True if encountering the end of the input having peeked no data is allowed, and should result in false being returned. False if it should be considered an error, causing an EOFException to be thrown. See note in class Javadoc.
Returns
boolean

True if the peek was successful. False if allowEndOfInput=true and the end of the input was encountered having peeked no data.
Throws
java.io.EOFException

If the end of input was encountered having partially satisfied the peek (i.e. having peeked at least one byte, but fewer than length), or if no bytes were peeked and allowEndOfInput is false.
java.io.IOException

If an error occurs peeking from the input.

read

abstract int read(byte[] buffer, int offset, int length)

Reads up to length bytes from the input and resets the peek position.

This method blocks until at least one byte of data can be read, the end of the input is detected, or an exception is thrown.

Parameters
byte[] buffer

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The maximum number of bytes to read from the input.
Returns
int

The number of bytes read, or RESULT_END_OF_INPUT if the input has ended.
Throws
java.io.IOException

If an error occurs reading from the input.

readFully

abstract void readFully(byte[] target, int offset, int length)

Equivalent to readFully(target, offset, length, false).

Parameters
byte[] target

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The number of bytes to read from the input.
Throws
java.io.EOFException

If the end of input was encountered.
java.io.IOException

If an error occurs reading from the input.

readFully

abstract boolean readFully(byte[] target, int offset, int length, boolean allowEndOfInput)

Like read, but reads the requested length in full.

Parameters
byte[] target

A target array into which data should be written.
int offset

The offset into the target array at which to write.
int length

The number of bytes to read from the input.
boolean allowEndOfInput

True if encountering the end of the input having read no data is allowed, and should result in false being returned. False if it should be considered an error, causing an EOFException to be thrown. See note in class Javadoc.
Returns
boolean

True if the read was successful. False if allowEndOfInput=true and the end of the input was encountered having read no data.
Throws
java.io.EOFException

If the end of input was encountered having partially satisfied the read (i.e. having read at least one byte, but fewer than length), or if no bytes were read and allowEndOfInput is false.
java.io.IOException

If an error occurs reading from the input.

resetPeekPosition

abstract void resetPeekPosition()

Resets the peek position to equal the current read position.

setRetryPosition

abstract void <E extends Throwable> setRetryPosition(long position, E e)

Called when reading fails and the required retry position is different from the last position. After setting the retry position it throws the given Throwable.

Parameters
<E extends Throwable>

Type of Throwable to be thrown.
long position

The required retry position.
E e

Throwable to be thrown.
Throws
E

The given Throwable object.

skip

abstract int skip(int length)

Like read, except the data is skipped instead of read.

Parameters
int length

The maximum number of bytes to skip from the input.
Returns
int

The number of bytes skipped, or RESULT_END_OF_INPUT if the input has ended.
Throws
java.io.IOException

If an error occurs reading from the input.

skipFully

abstract void skipFully(int length)

Like readFully, except the data is skipped instead of read.

Encountering the end of input is always considered an error, and will result in an being thrown.

Parameters
int length

The number of bytes to skip from the input.
Throws
java.io.EOFException

If the end of input was encountered.
java.io.IOException

If an error occurs reading from the input.

skipFully

abstract boolean skipFully(int length, boolean allowEndOfInput)

Like readFully, except the data is skipped instead of read.

Parameters
int length

The number of bytes to skip from the input.
boolean allowEndOfInput

True if encountering the end of the input having skipped no data is allowed, and should result in false being returned. False if it should be considered an error, causing an EOFException to be thrown. See note in class Javadoc.
Returns
boolean

True if the skip was successful. False if allowEndOfInput=true and the end of the input was encountered having skipped no data.
Throws
java.io.EOFException

If the end of input was encountered having partially satisfied the skip (i.e. having skipped at least one byte, but fewer than length), or if no bytes were skipped and allowEndOfInput is false.
java.io.IOException

If an error occurs reading from the input.