154 lines
5.2 KiB
Java
154 lines
5.2 KiB
Java
package it.cavallium.stream;
|
|
|
|
import java.io.Closeable;
|
|
import java.io.DataInput;
|
|
import java.nio.charset.Charset;
|
|
|
|
import org.jetbrains.annotations.NotNull;
|
|
|
|
/**
|
|
* A data input stream lets an application read primitive Java data
|
|
* types from an underlying input stream in a machine-independent
|
|
* way. An application uses a data output stream to write data that
|
|
* can later be read by a data input stream.
|
|
* <p>
|
|
* DataInputStream is not necessarily safe for multithreaded access.
|
|
* Thread safety is optional and is the responsibility of users of
|
|
* methods in this class.
|
|
*
|
|
* @author Arthur van Hoff
|
|
* @see java.io.DataOutputStream
|
|
* @since 1.0
|
|
*/
|
|
public interface SafeDataInput extends Closeable, DataInput {
|
|
|
|
/**
|
|
* Reads some number of bytes from the contained input stream and
|
|
* stores them into the buffer array {@code b}. The number of
|
|
* bytes actually read is returned as an integer. This method blocks
|
|
* until input data is available, end of file is detected, or an
|
|
* exception is thrown.
|
|
*
|
|
* <p>If {@code b} is null, a {@code NullPointerException} is
|
|
* thrown. If the length of {@code b} is zero, then no bytes are
|
|
* read and {@code 0} is returned; otherwise, there is an attempt
|
|
* to read at least one byte. If no byte is available because the
|
|
* stream is at end of file, the value {@code -1} is returned;
|
|
* otherwise, at least one byte is read and stored into {@code b}.
|
|
*
|
|
* <p>The first byte read is stored into element {@code b[0]}, the
|
|
* next one into {@code b[1]}, and so on. The number of bytes read
|
|
* is, at most, equal to the length of {@code b}. Let {@code k}
|
|
* be the number of bytes actually read; these bytes will be stored in
|
|
* elements {@code b[0]} through {@code b[k-1]}, leaving
|
|
* elements {@code b[k]} through {@code b[b.length-1]}
|
|
* unaffected.
|
|
*
|
|
* <p>The {@code read(b)} method has the same effect as:
|
|
* <blockquote><pre>
|
|
* read(b, 0, b.length)
|
|
* </pre></blockquote>
|
|
*
|
|
* @param b the buffer into which the data is read.
|
|
* @return the total number of bytes read into the buffer, or
|
|
* {@code -1} if there is no more data because the end
|
|
* of the stream has been reached.
|
|
* @see SafeFilterInputStream#in
|
|
* @see java.io.InputStream#read(byte[], int, int)
|
|
*/
|
|
int read(byte[] b);
|
|
|
|
/**
|
|
* Reads up to {@code len} bytes of data from the contained
|
|
* input stream into an array of bytes. An attempt is made to read
|
|
* as many as {@code len} bytes, but a smaller number may be read,
|
|
* possibly zero. The number of bytes actually read is returned as an
|
|
* integer.
|
|
*
|
|
* <p> This method blocks until input data is available, end of file is
|
|
* detected, or an exception is thrown.
|
|
*
|
|
* <p> If {@code len} is zero, then no bytes are read and
|
|
* {@code 0} is returned; otherwise, there is an attempt to read at
|
|
* least one byte. If no byte is available because the stream is at end of
|
|
* file, the value {@code -1} is returned; otherwise, at least one
|
|
* byte is read and stored into {@code b}.
|
|
*
|
|
* <p> The first byte read is stored into element {@code b[off]}, the
|
|
* next one into {@code b[off+1]}, and so on. The number of bytes read
|
|
* is, at most, equal to {@code len}. Let <i>k</i> be the number of
|
|
* bytes actually read; these bytes will be stored in elements
|
|
* {@code b[off]} through {@code b[off+}<i>k</i>{@code -1]},
|
|
* leaving elements {@code b[off+}<i>k</i>{@code ]} through
|
|
* {@code b[off+len-1]} unaffected.
|
|
*
|
|
* <p> In every case, elements {@code b[0]} through
|
|
* {@code b[off]} and elements {@code b[off+len]} through
|
|
* {@code b[b.length-1]} are unaffected.
|
|
*
|
|
* @param b the buffer into which the data is read.
|
|
* @param off the start offset in the destination array {@code b}
|
|
* @param len the maximum number of bytes read.
|
|
* @return the total number of bytes read into the buffer, or
|
|
* {@code -1} if there is no more data because the end
|
|
* of the stream has been reached.
|
|
* @throws NullPointerException If {@code b} is {@code null}.
|
|
* @throws IndexOutOfBoundsException If {@code off} is negative,
|
|
* {@code len} is negative, or {@code len} is greater than
|
|
* {@code b.length - off}
|
|
* @see SafeFilterInputStream#in
|
|
* @see java.io.InputStream#read(byte[], int, int)
|
|
*/
|
|
int read(byte[] b, int off, int len);
|
|
|
|
void readFully(byte @NotNull [] b);
|
|
|
|
void readFully(byte @NotNull [] b, int off, int len);
|
|
|
|
int skipBytes(int n);
|
|
|
|
boolean readBoolean();
|
|
|
|
byte readByte();
|
|
|
|
int readUnsignedByte();
|
|
|
|
short readShort();
|
|
|
|
int readUnsignedShort();
|
|
|
|
char readChar();
|
|
|
|
int readInt();
|
|
|
|
long readLong();
|
|
|
|
/**
|
|
* See the general contract of the {@code readInt52}
|
|
* method of {@code DataInput}.
|
|
* <p>
|
|
* Bytes
|
|
* for this operation are read from the contained
|
|
* input stream.
|
|
*
|
|
* @return the next seven bytes of this input stream, interpreted as a
|
|
* {@code Int52}.
|
|
* @see SafeFilterInputStream#in
|
|
*/
|
|
long readInt52();
|
|
|
|
float readFloat();
|
|
|
|
double readDouble();
|
|
|
|
@Deprecated
|
|
String readLine();
|
|
|
|
@Deprecated
|
|
@NotNull String readUTF();
|
|
|
|
@NotNull String readShortText(Charset charset);
|
|
|
|
@NotNull String readMediumText(Charset charset);
|
|
}
|