ByteSource

public interface ByteSource extends Closeable

saker.util.io.ByteSource

java.io.Closeable

java.lang.AutoCloseable

ByteSourceInputStream, DataInputByteSource, DataInputUnsyncByteArrayInputStream, DynamicFilterByteSource, InputStreamByteSource, LimitInputStream, ObjectInputByteSource, ReadWriteBufferOutputStream, UnsyncBufferedInputStream, UnsyncByteArrayInputStream

Interface for handling byte stream input.

Byte source is similar to InputStream, but is defined as an interface for allowing stream operations over RMI. RMI solutions can create proxy objects for network transferred objects only for interfaces, therefore it was necessary to declare such an interface that is usable for this use-case.

This interface works in similar ways as the InputStream class, but is designed to be RMI compatible. The interface also contains extra method(s) for more efficient implementations of common use-cases (like writeTo(ByteSink)).

To convert between InputStream and ByteSource objects use the static methods declared in this interface.

Byte source implementations are not thread-safe by default.

ByteSink

Methods

public default void	close() Closes this stream and releases any system resources associated with it.
public default int	read() Reads a single byte from this byte source.
public default ByteArrayRegion	read(int count) Reads a given number of bytes from this byte source.
public int	read(ByteRegion buffer) Reads bytes from this byte source and writes them to the argument buffer.
public static int	redirectReadCall(ByteSource proxy, ByteRegion buffer) RMI redirection method when read(ByteRegion) is called.
public default long	skip(long n) Skips over a number of bytes in this byte source.
public static InputStream	toInputStream(ByteSource src) Converts the argument ByteSource to an InputStream.
public static ByteSource	valueOf(InputStream is) Converts the argument InputStream to a ByteSource.
public static ByteSource	valueOf(ObjectInput is) Converts the argument ObjectInput to a ByteSource.
public default long	writeTo(ByteSink out) Writes the remaining bytes in this byte source to the specified byte sink.

@RMIExceptionRethrow(RemoteIOException.class)

public default void close() throws IOException

Overridden from: Closeable

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable.close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

IOExceptionif an I/O error occurs

@RMIExceptionRethrow(RemoteIOException.class)

public default int read() throws IOException

Reads a single byte from this byte source.

This method works similarly to InputStream.read().

An unsigned single byte or negative if no more bytes available.

IOExceptionIn case of I/O error.

@RMIExceptionRethrow(RemoteIOException.class)

public default ByteArrayRegion read(int count) throws IOException

Reads a given number of bytes from this byte source.

This method reads at most the specified number of bytes from this byte source and returns it as a byte array region. The resulting buffer may contain less than the requested number of bytes. This doesn't mean that the end of the stream has been reached, but only that reading more bytes will most likely block.

If a byte array of zero length is returned, that means that the end of the stream is reached (or the requested count was less or equal to 0).

It is recommended that the number of bytes to read is not too large, so a buffer allocated for that size will not cause OutOfMemoryError.

countThe number of bytes to read.

The bytes read from the stream.

IOExceptionIn case of I/O error.

@RMIRedirect(method = "redirectReadCall")

public abstract int read(@RMIWrap(RMIByteRegionWrapper.class)ByteRegion buffer) throws IOException, NullPointerException

Reads bytes from this byte source and writes them to the argument buffer.

The number of bytes read is based on the buffer length.

This method works similarly to InputStream.read(byte[], int, int).

RMI method calls to this method is redirected to redirectReadCall(ByteSource, ByteRegion).

bufferThe buffer to read the bytes to.

The number of bytes read and put into the buffer. Negative result means that the end of the byte source has been reached.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the argument is null.

public static int redirectReadCall(ByteSource proxy, ByteRegion buffer) throws IOException, NullPointerException

RMI redirection method when read(ByteRegion) is called.

This method is used to improve the performance of the associated method. If read(ByteRegion) is called directly it can cost multiple ByteRegion.put(int, ByteArrayRegion) calls to fill the buffer, and thus result in lesser performance than only a single call.

This redirection method will call read(int) instead with an appropriate byte number count which is determined based on a default maximum (currently 64MB) and the length of the argument buffer.

During the operation of this method a temporary buffer will be allocated that has at most the above size, and which is discarded after this method ends. This method redirection servers as a tradeoff between memory and network calls. We deem that it is acceptable, as another allocation of the same (or smaller) size of the argument buffer should not hinder or crash the running JVM, but multiple network calls can decrease performance more.

If users are trying to read more bytes than the abot 64MB default limit, then they will need to call the read(ByteRegion) method multiple times. This is not a problem as they must expect that the reading method may not read the argument buffer fully.

proxyThe byte source proxy object.

bufferThe byte buffer to read the bytes to.

The number of bytes read.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the buffer is null.

read(ByteRegion)

@RMIExceptionRethrow(RemoteIOException.class)

public default long skip(long n) throws IOException

Skips over a number of bytes in this byte source.

This method will discard given amount of bytes from this byte source. This works the same way as calling read() n times.

This method works similarly to InputStream.skip(long).

This method may skip over 0 bytes even if there are still bytes available from this source. It may be recommended that in order to skip an exact amount of bytes, that external mechanisms are used to ensure valid operation.

nThe number of bytes to skip over.

The number of bytes actually skipped.

IOExceptionIn case of I/O error.

StreamUtils.skipSourceExactly(ByteSource, long)

public static InputStream toInputStream(ByteSource src)

Converts the argument ByteSource to an InputStream.

If the argument is already an InputStream, then it will be returned without modification.

Else it will be wrapped into a forwarding InputStream.

Closing the result will close the argument too.

srcThe byte source.

The input stream that usese the passed byte source argument, or null if the argument is null.

public static ByteSource valueOf(InputStream is)

Converts the argument InputStream to a ByteSource.

If the argument is already a ByteSource, then it will be returned without modification.

Else it will be wrapped into a forwarding ByteSource.

Closing the result will close the argument too.

isThe input stream.

The byte sink that uses the passed input stream argument, or null if the argument is null.

public static ByteSource valueOf(ObjectInput is)

Converts the argument ObjectInput to a ByteSource.

If the argument is already a ByteSource, then it will be returned without modification.

Else it will be wrapped into a forwarding ByteSource.

Closing the result will close the argument too.

isThe object input.

The byte sink that uses the passed input argument, or null if the argument is null.

@RMIExceptionRethrow(RemoteIOException.class)

public default long writeTo(ByteSink out) throws IOException, NullPointerException

Writes the remaining bytes in this byte source to the specified byte sink.

This method will take the remaining bytes in this byte source and write it to the specified byte sink. It is expected that after this method finishes, reading from this byte source will not return any bytes.

outThe byte sink to write the bytes to.

The number of bytes actually written to the sink. Always zero or greater.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the argument is null.