FakeExtractorInput

Artifact: androidx.media3:media3-test-utils

View Source

---

Kotlin |Java

@UnstableApi
public final class FakeExtractorInput implements ExtractorInput

---

A fake ExtractorInput capable of simulating various scenarios.

Read, skip and peek errors can be simulated using setSimulateIOErrors. When enabled each read and skip will throw a SimulatedIOException unless one has already been thrown from the current position. Each peek will throw SimulatedIOException unless one has already been thrown from the current peek position. When a SimulatedIOException is thrown the read position is left unchanged and the peek position is reset back to the read position.

Partial reads and skips can be simulated using setSimulatePartialReads. When enabled, read and skip calls will only read or skip a single byte unless a partial read or skip has already been performed that had the same target position. For example, a first read request for 10 bytes will be partially satisfied by reading a single byte and advancing the position to 1. If the following read request attempts to read 9 bytes then it will be fully satisfied, since it has the same target position of 10.

Unknown data length can be simulated using setSimulateUnknownLength. When enabled getLength will return LENGTH_UNSET rather than the length of the data.

Summary

Nested types
public final class FakeExtractorInput.Builder Builder of FakeExtractorInput instances.
public final class FakeExtractorInput.SimulatedIOException extends IOException Thrown when simulating an IOException.

Public methods
void	advancePeekPosition(int length) Advances the peek position by length bytes.
boolean	advancePeekPosition(int length, boolean allowEndOfInput) Advances the peek position by length bytes.
long	getLength() Returns the length of the source stream, or LENGTH_UNSET if it is unknown.
long	getPeekPosition() Returns the current peek position (byte offset) in the stream.
long	getPosition() Returns the current read position (byte offset) in the stream.
int	peek(byte[] target, int offset, int length) Peeks up to length bytes from the peek position.
void	peekFully(byte[] target, int offset, int length) Equivalent to peekFully(target, offset, length, false).
boolean	peekFully(byte[] target, int offset, int length, boolean allowEndOfInput) Like peek, but peeks the requested length in full.
int	read(byte[] buffer, int offset, int length) Reads up to length bytes from the input and resets the peek position.
void	readFully(byte[] target, int offset, int length) Equivalent to readFully(target, offset, length, false).
boolean	readFully(byte[] target, int offset, int length, boolean allowEndOfInput) Like read, but reads the requested length in full.
void	reset() Resets the input to its initial state.
void	resetPeekPosition() Resets the peek position to equal the current read position.
void	setPosition(int position) Sets the read and peek positions.
void	<E extends Throwable> setRetryPosition(long position, E e) Called when reading fails and the required retry position is different from the last position.
int	skip(int length) Like read, except the data is skipped instead of read.
void	skipFully(int length) Like readFully, except the data is skipped instead of read.
boolean	skipFully(int length, boolean allowEndOfInput) Like readFully, except the data is skipped instead of read.

Public methods

advancePeekPosition

public 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

public 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

public 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

public long getPeekPosition()

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

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

getPosition

public long getPosition()

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

Returns
long	The read position (byte offset) in the stream.

peek

public 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

public 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

public 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

public 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

public 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

public 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.

reset

public void reset()

Resets the input to its initial state.

resetPeekPosition

public void resetPeekPosition()

Resets the peek position to equal the current read position.

setPosition

public void setPosition(int position)

Sets the read and peek positions.

Parameters
int position	The position to set.

setRetryPosition

public 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.
androidx.media3.test.utils.FakeExtractorInput

skip

public 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

public 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

public 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.