nom.tam.util

Class BufferedDataInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

java.io.BufferedInputStream

nom.tam.util.BufferedDataInputStream

All Implemented Interfaces:

Closeable, DataInput, AutoCloseable, ArrayDataInput

public class BufferedDataInputStream
extends BufferedInputStream
implements ArrayDataInput

This class is intended for high performance I/O in scientific applications. It combines the functionality of the BufferedInputStream and the DataInputStream as well as more efficient handling of arrays. This minimizes the number of method calls that are required to read data. Informal tests of this method show that it can be as much as 10 times faster than using a DataInputStream layered on a BufferedInputStream for writing large arrays. The performance gain on scalars or small arrays will be less but there should probably never be substantial degradation of performance.

Many new read calls are added to allow efficient reading off array data. The read(Object o) call provides for reading a primitive array of arbitrary type or dimensionality. There are also reads for each type of one dimensional array.

Note that there is substantial duplication of code to minimize method invocations. E.g., the floating point read routines read the data as integer values and then convert to float. However the integer code is duplicated rather than invoked. There has been considerable effort expended to ensure that these routines are efficient, but they could easily be superceded if an efficient underlying I/O package were ever delivered as part of the basic Java libraries.

Testing and timing routines are provided in the nom.tam.util.test.BufferedFileTester class. Version 1.1: October 12, 2000: Fixed handling of EOF to return partially read arrays when EOF is detected.

Field Summary

Fields inherited from class java.io.BufferedInputStream

buf, count, marklimit, markpos, pos

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor and Description
BufferedDataInputStream(InputStream o) Use the BufferedInputStream constructor
BufferedDataInputStream(InputStream o, int bufLength) Use the BufferedInputStream constructor

Method Summary

Modifier and Type	Method and Description
protected int	primitiveArrayRecurse(Object o) Read recursively over a multi-dimensional array.
int	read(boolean[] b) Read a boolean array
int	read(boolean[] b, int start, int len) Read a boolean array.
int	read(byte[] obuf, int offset, int len) Read a byte array.
int	read(char[] c) Read a character array
int	read(char[] c, int start, int len) Read a character array
int	read(double[] d) Read a double array
int	read(double[] d, int start, int len) Read a double array
int	read(float[] f) Read a float array
int	read(float[] f, int start, int len) Read a float array
int	read(int[] i) Read an integer array
int	read(int[] i, int start, int len) Read an integer array
int	read(long[] l) Read a long array
int	read(long[] l, int start, int len) Read a long array
int	read(short[] s) Read a short array
int	read(short[] s, int start, int len) Read a short array
int	readArray(Object o) Read an object.
boolean	readBoolean() Read a boolean value.
byte	readByte() Read a byte value in the range -128 to 127.
char	readChar() Read a 2-byte value as a character.
double	readDouble() Read an 8 byte real number.
float	readFloat() Read a 4 byte real number.
void	readFully(byte[] b) Read a buffer and signal an EOF if the buffer cannot be fully read.
void	readFully(byte[] b, int off, int len) Read a buffer and signal an EOF if the requested elements cannot be read.
int	readInt() Read an integer.
String	readLine() Deprecated. Use BufferedReader methods.
long	readLong() Read a long.
int	readPrimitiveArray(Object o) Deprecated. See readArray(Object o).
short	readShort() Read a 2-byte value as a short (-32788 to 32767)
int	readUnsignedByte() Read a byte value in the range 0-255.
int	readUnsignedShort() Read a 2-byte value in the range 0-65536.
String	readUTF() Read a String in the UTF format.
int	skipBytes(int toSkip) Skip the requested number of bytes.
String	toString() Represent the stream as a string

Methods inherited from class java.io.BufferedInputStream

available, close, mark, markSupported, read, reset, skip

Methods inherited from class java.io.FilterInputStream

read

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface nom.tam.util.ArrayDataInput

close, read, skip

Constructor Detail

BufferedDataInputStream

public BufferedDataInputStream(InputStream o)

Use the BufferedInputStream constructor

BufferedDataInputStream

public BufferedDataInputStream(InputStream o,
                               int bufLength)

Use the BufferedInputStream constructor

Method Detail

read

public int read(byte[] obuf,
                int offset,
                int len)
         throws IOException

Read a byte array. This is the only method for reading arrays in the fundamental I/O classes.

Specified by:

read in interface ArrayDataInput

Overrides:

read in class BufferedInputStream

Parameters:

obuf - The byte array.

offset - The starting offset into the array.

len - The number of bytes to read.

Returns:

The actual number of bytes read.

Throws:

IOException

readBoolean

public boolean readBoolean()
                    throws IOException

Read a boolean value.

Specified by:

readBoolean in interface DataInput

Returns:

b The value read.

Throws:

IOException

readByte

public byte readByte()
              throws IOException

Read a byte value in the range -128 to 127.

Specified by:

readByte in interface DataInput

Returns:

The byte value as a byte (see read() to return the value as an integer.

Throws:

IOException

readUnsignedByte

public int readUnsignedByte()
                     throws IOException

Read a byte value in the range 0-255.

Specified by:

readUnsignedByte in interface DataInput

Returns:

The byte value as an integer.

Throws:

IOException

readInt

public int readInt()
            throws IOException

Read an integer.

Specified by:

readInt in interface DataInput

Returns:

The integer value.

Throws:

IOException

readShort

public short readShort()
                throws IOException

Read a 2-byte value as a short (-32788 to 32767)

Specified by:

readShort in interface DataInput

Returns:

The short value.

Throws:

IOException

readUnsignedShort

public int readUnsignedShort()
                      throws IOException

Read a 2-byte value in the range 0-65536.

Specified by:

readUnsignedShort in interface DataInput

Returns:

the value as an integer.

Throws:

IOException

readChar

public char readChar()
              throws IOException

Read a 2-byte value as a character.

Specified by:

readChar in interface DataInput

Returns:

The character read.

Throws:

IOException

readLong

public long readLong()
              throws IOException

Read a long.

Specified by:

readLong in interface DataInput

Returns:

The value read.

Throws:

IOException

readFloat

public float readFloat()
                throws IOException

Read a 4 byte real number.

Specified by:

readFloat in interface DataInput

Returns:

The value as a float.

Throws:

IOException

readDouble

public double readDouble()
                  throws IOException

Read an 8 byte real number.

Specified by:

readDouble in interface DataInput

Returns:

The value as a double.

Throws:

IOException

readFully

public void readFully(byte[] b)
               throws IOException

Read a buffer and signal an EOF if the buffer cannot be fully read.

Specified by:

readFully in interface DataInput

Parameters:

b - The buffer to be read.

Throws:

IOException

readFully

public void readFully(byte[] b,
                      int off,
                      int len)
               throws IOException

Read a buffer and signal an EOF if the requested elements cannot be read. This differs from read(b,off,len) since that call will not signal and end of file unless no bytes can be read. However both of these routines will attempt to fill their buffers completely.

Specified by:

readFully in interface DataInput

Parameters:

b - The input buffer.

off - The requested offset into the buffer.

len - The number of bytes requested.

Throws:

IOException

skipBytes

public int skipBytes(int toSkip)
              throws IOException

Skip the requested number of bytes. This differs from the skip call in that it takes an integer argument and will throw an end of file if the full number of bytes cannot be skipped.

Specified by:

skipBytes in interface DataInput

Parameters:

toSkip - The number of bytes to skip.

Throws:

IOException

readUTF

public String readUTF()
               throws IOException

Read a String in the UTF format. The implementation of this is very inefficient and use of this class is not recommended for applications which will use this routine heavily.

Specified by:

readUTF in interface DataInput

Returns:

The String that was read.

Throws:

IOException

readLine

public String readLine()
                throws IOException

Deprecated. Use BufferedReader methods.

Emulate the deprecated DataInputStream.readLine() method. Originally we used the method itself, but Alan Brighton suggested using a BufferedReader to eliminate the deprecation warning... Note that the implementation of this routine is very slow and this class should probably not be used if this method is called heavily.

Specified by:

readLine in interface DataInput

Returns:

The String read.

Throws:

IOException

readPrimitiveArray

public int readPrimitiveArray(Object o)
                       throws IOException

Deprecated. See readArray(Object o).

This routine provides efficient reading of arrays of any primitive type. It is an error to invoke this method with an object that is not an array of some primitive type. Note that there is no corresponding capability to writePrimitiveArray in BufferedDataOutputStream to read in an array of Strings.

Parameters:

o - The object to be read. It must be an array of a primitive type, or an array of Object's.

Throws:

IOException

readArray

public int readArray(Object o)
              throws IOException

Read an object. An EOF will be signaled if the object cannot be fully read. The getPrimitiveArrayCount() method may then be used to get a minimum number of bytes read.

Specified by:

readArray in interface ArrayDataInput

Parameters:

o - The object to be read. This object should be a primitive (possibly multi-dimensional) array.

Throws:

IOException

primitiveArrayRecurse

protected int primitiveArrayRecurse(Object o)
                             throws IOException

Read recursively over a multi-dimensional array.

Returns:

The number of bytes read.

Throws:

IOException

read

public int read(boolean[] b)
         throws IOException

Read a boolean array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(boolean[] b,
                int start,
                int len)
         throws IOException

Read a boolean array.

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(short[] s)
         throws IOException

Read a short array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(short[] s,
                int start,
                int len)
         throws IOException

Read a short array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(char[] c)
         throws IOException

Read a character array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(char[] c,
                int start,
                int len)
         throws IOException

Read a character array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(int[] i)
         throws IOException

Read an integer array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(int[] i,
                int start,
                int len)
         throws IOException

Read an integer array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(long[] l)
         throws IOException

Read a long array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(long[] l,
                int start,
                int len)
         throws IOException

Read a long array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(float[] f)
         throws IOException

Read a float array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(float[] f,
                int start,
                int len)
         throws IOException

Read a float array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(double[] d)
         throws IOException

Read a double array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

read

public int read(double[] d,
                int start,
                int len)
         throws IOException

Read a double array

Specified by:

read in interface ArrayDataInput

Throws:

IOException

toString

public String toString()

Represent the stream as a string

Overrides:

toString in class Object