BufferedDataInputStream (FITS API)

java.lang.Object
- java.io.InputStream
- - java.io.FilterInputStream
  - - java.io.BufferedInputStream
    - - nom.tam.util.BufferedDataInputStream

All Implemented Interfaces:

java.io.Closeable, java.io.DataInput, java.lang.AutoCloseable, ArrayDataInput
```
public class BufferedDataInputStream
extends java.io.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. [This has subsequently happened with the NIO package and in an ideal universe these classes would be rewritten to take advantage of NIO.]
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. Version 1.2: July 20, 2009: Added handling of very large Object arrays. Additional work is required to handle very large arrays generally.

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(java.io.InputStream o)` Use the BufferedInputStream constructor
`BufferedDataInputStream(java.io.InputStream o, int bufLength)` Use the BufferedInputStream constructor

Method Summary

Methods
Modifier and Type	Method and Description
`protected long`	`primitiveArrayRecurse(java.lang.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(java.lang.Object o)` Deprecated. See readLArray(Object) which handles large arrays properly.
`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.
`long`	`readLArray(java.lang.Object o)` Read an object.
`java.lang.String`	`readLine()` Deprecated. Use BufferedReader methods.
`long`	`readLong()` Read a long.
`int`	`readPrimitiveArray(java.lang.Object o)` Deprecated. See readLArray(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.
`java.lang.String`	`readUTF()` Read a String in the UTF format.
`int`	`skipBytes(int toSkip)`
`long`	`skipBytes(long toSkip)`
`java.lang.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(java.io.InputStream o)
```
    Use the BufferedInputStream constructor
  - BufferedDataInputStream
```
public BufferedDataInputStream(java.io.InputStream o,
                       int bufLength)
```
    Use the BufferedInputStream constructor
- Method Detail
  - read
```
public int read(byte[] obuf,
       int offset,
       int len)
         throws java.io.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 java.io.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:
    
    java.io.IOException
  - readBoolean
```
public boolean readBoolean()
                    throws java.io.IOException
```
    Read a boolean value.
    
    Specified by:
    
    readBoolean in interface java.io.DataInput
    
    Returns:
    b The value read.
    
    Throws:
    
    java.io.IOException
  - readByte
```
public byte readByte()
              throws java.io.IOException
```
    Read a byte value in the range -128 to 127.
    
    Specified by:
    
    readByte in interface java.io.DataInput
    
    Returns:
    The byte value as a byte (see read() to return the value as an integer.
    
    Throws:
    
    java.io.IOException
  - readUnsignedByte
```
public int readUnsignedByte()
                     throws java.io.IOException
```
    Read a byte value in the range 0-255.
    
    Specified by:
    
    readUnsignedByte in interface java.io.DataInput
    
    Returns:
    The byte value as an integer.
    
    Throws:
    
    java.io.IOException
  - readInt
```
public int readInt()
            throws java.io.IOException
```
    Read an integer.
    
    Specified by:
    
    readInt in interface java.io.DataInput
    
    Returns:
    The integer value.
    
    Throws:
    
    java.io.IOException
  - readShort
```
public short readShort()
                throws java.io.IOException
```
    Read a 2-byte value as a short (-32788 to 32767)
    
    Specified by:
    
    readShort in interface java.io.DataInput
    
    Returns:
    The short value.
    
    Throws:
    
    java.io.IOException
  - readUnsignedShort
```
public int readUnsignedShort()
                      throws java.io.IOException
```
    Read a 2-byte value in the range 0-65536.
    
    Specified by:
    
    readUnsignedShort in interface java.io.DataInput
    
    Returns:
    the value as an integer.
    
    Throws:
    
    java.io.IOException
  - readChar
```
public char readChar()
              throws java.io.IOException
```
    Read a 2-byte value as a character.
    
    Specified by:
    
    readChar in interface java.io.DataInput
    
    Returns:
    The character read.
    
    Throws:
    
    java.io.IOException
  - readLong
```
public long readLong()
              throws java.io.IOException
```
    Read a long.
    
    Specified by:
    
    readLong in interface java.io.DataInput
    
    Returns:
    The value read.
    
    Throws:
    
    java.io.IOException
  - readFloat
```
public float readFloat()
                throws java.io.IOException
```
    Read a 4 byte real number.
    
    Specified by:
    
    readFloat in interface java.io.DataInput
    
    Returns:
    The value as a float.
    
    Throws:
    
    java.io.IOException
  - readDouble
```
public double readDouble()
                  throws java.io.IOException
```
    Read an 8 byte real number.
    
    Specified by:
    
    readDouble in interface java.io.DataInput
    
    Returns:
    The value as a double.
    
    Throws:
    
    java.io.IOException
  - readFully
```
public void readFully(byte[] b)
               throws java.io.IOException
```
    Read a buffer and signal an EOF if the buffer cannot be fully read.
    
    Specified by:
    
    readFully in interface java.io.DataInput
    
    Parameters:
    b - The buffer to be read.
    
    Throws:
    
    java.io.IOException
  - readFully
```
public void readFully(byte[] b,
             int off,
             int len)
               throws java.io.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 java.io.DataInput
    
    Parameters:
    b - The input buffer.
    off - The requested offset into the buffer.
    len - The number of bytes requested.
    
    Throws:
    
    java.io.IOException
  - skipBytes
```
public int skipBytes(int toSkip)
              throws java.io.IOException
```
    Specified by:
    
    skipBytes in interface java.io.DataInput
    
    Throws:
    
    java.io.IOException
  - skipBytes
```
public long skipBytes(long toSkip)
               throws java.io.IOException
```
    Specified by:
    
    skipBytes in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - readUTF
```
public java.lang.String readUTF()
                         throws java.io.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 java.io.DataInput
    
    Returns:
    The String that was read.
    
    Throws:
    
    java.io.IOException
  - readLine
```
public java.lang.String readLine()
                          throws java.io.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. This was used for a long time, but more recently we noted that this doesn't work. We now use a simple method that largely ignores character encodings and only uses the "\n" as the line separator. This method is slow regardless. In the current version
    
    Specified by:
    
    readLine in interface java.io.DataInput
    
    Returns:
    The String read.
    
    Throws:
    
    java.io.IOException
  - readPrimitiveArray
```
public int readPrimitiveArray(java.lang.Object o)
                       throws java.io.IOException
```
    Deprecated. See readLArray(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:
    
    java.io.IOException
  - readArray
```
public int readArray(java.lang.Object o)
              throws java.io.IOException
```
    Deprecated. See readLArray(Object) which handles large arrays properly.
    
    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.
    
    Returns:
    The number of bytes read.
    
    Throws:
    
    java.io.IOException
  - readLArray
```
public long readLArray(java.lang.Object o)
                throws java.io.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:
    
    readLArray in interface ArrayDataInput
    
    Parameters:
    o - The object to be read. This object should be a primitive (possibly multi-dimensional) array.
    
    Returns:
    The number of bytes read.
    
    Throws:
    
    java.io.IOException
  - primitiveArrayRecurse
```
protected long primitiveArrayRecurse(java.lang.Object o)
                              throws java.io.IOException
```
    Read recursively over a multi-dimensional array.
    
    Returns:
    The number of bytes read.
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(boolean[] b)
         throws java.io.IOException
```
    Read a boolean array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(boolean[] b,
       int start,
       int len)
         throws java.io.IOException
```
    Read a boolean array.
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(short[] s)
         throws java.io.IOException
```
    Read a short array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(short[] s,
       int start,
       int len)
         throws java.io.IOException
```
    Read a short array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(char[] c)
         throws java.io.IOException
```
    Read a character array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(char[] c,
       int start,
       int len)
         throws java.io.IOException
```
    Read a character array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(int[] i)
         throws java.io.IOException
```
    Read an integer array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(int[] i,
       int start,
       int len)
         throws java.io.IOException
```
    Read an integer array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(long[] l)
         throws java.io.IOException
```
    Read a long array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(long[] l,
       int start,
       int len)
         throws java.io.IOException
```
    Read a long array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(float[] f)
         throws java.io.IOException
```
    Read a float array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(float[] f,
       int start,
       int len)
         throws java.io.IOException
```
    Read a float array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(double[] d)
         throws java.io.IOException
```
    Read a double array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - read
```
public int read(double[] d,
       int start,
       int len)
         throws java.io.IOException
```
    Read a double array
    
    Specified by:
    
    read in interface ArrayDataInput
    
    Throws:
    
    java.io.IOException
  - toString
```
public java.lang.String toString()
```
    Represent the stream as a string
    
    Overrides:
    
    toString in class java.lang.Object

Class BufferedDataInputStream

Field Summary

Fields inherited from class java.io.BufferedInputStream

Fields inherited from class java.io.FilterInputStream

Constructor Summary

Method Summary

Methods inherited from class java.io.BufferedInputStream

Methods inherited from class java.io.FilterInputStream

Methods inherited from class java.lang.Object

Methods inherited from interface nom.tam.util.ArrayDataInput

Constructor Detail

BufferedDataInputStream

BufferedDataInputStream

Method Detail

read

readBoolean

readByte

readUnsignedByte

readInt

readShort

readUnsignedShort

readChar

readLong

readFloat

readDouble

readFully

readFully

skipBytes

skipBytes

readUTF

readLine

readPrimitiveArray

readArray

readLArray

primitiveArrayRecurse

read

read

read

read

read

read

read

read

read

read

read

read

read

read

toString