Class FitsInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

java.io.BufferedInputStream

nom.tam.util.ArrayInputStream

nom.tam.util.FitsInputStream

All Implemented Interfaces:

Closeable, DataInput, AutoCloseable, ArrayDataInput, FitsIO, InputReader

Direct Known Subclasses:

BufferedDataInputStream

public class FitsInputStream
extends ArrayInputStream
implements ArrayDataInput

For reading FITS files through an InputStream.

Testing and timing routines are provided in the nom.tam.util.test.BufferedFileTester class.

Prior versions under the old BufferedDataInputStream:

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

Version 2.0 -- October 30, 2021: Completely overhauled, with new name and hierarchy. Performance is 2-4 times better than before (Attila Kovacs)

See Also:

• FitsInputStream
• FitsFile

Field Summary

Fields inherited from interface FitsIO

BITS_OF_1_BYTE, BITS_OF_2_BYTES, BITS_OF_3_BYTES, BITS_OF_4_BYTES, BITS_OF_5_BYTES, BITS_OF_6_BYTES, BITS_OF_7_BYTES, BYTE_1_OF_LONG_MASK, BYTE_2_OF_LONG_MASK, BYTE_3_OF_LONG_MASK, BYTE_4_OF_LONG_MASK, BYTE_MASK, BYTES_IN_BOOLEAN, BYTES_IN_BYTE, BYTES_IN_CHAR, BYTES_IN_DOUBLE, BYTES_IN_FLOAT, BYTES_IN_INTEGER, BYTES_IN_LONG, BYTES_IN_SHORT, DEFAULT_BUFFER_SIZE, HIGH_INTEGER_MASK, INTEGER_MASK, SHORT_MASK, SHORT_OF_LONG_MASK

Modifier and Type	Field	Description
static final int	BITS_OF_1_BYTE	number of bits in one byte.
static final int	BITS_OF_2_BYTES	number of bits in two byte.
static final int	BITS_OF_3_BYTES	number of bits in three byte.
static final int	BITS_OF_4_BYTES	number of bits in four byte.
static final int	BITS_OF_5_BYTES	number of bits in five byte.
static final int	BITS_OF_6_BYTES	number of bits in six byte.
static final int	BITS_OF_7_BYTES	number of bits in seven byte.
static final long	BYTE_1_OF_LONG_MASK	bit mask to get the lowest byte of a long.
static final long	BYTE_2_OF_LONG_MASK	bit mask to get the second lowest byte of a long.
static final long	BYTE_3_OF_LONG_MASK	bit mask to get the third lowest byte of a long.
static final long	BYTE_4_OF_LONG_MASK	bit mask to get the fourth lowest byte of a long.
static final int	BYTE_MASK	bit mask to get the lowest byte from an integer.
static final int	BYTES_IN_BOOLEAN	number of bytes occupied by a boolean.
static final int	BYTES_IN_BYTE	number of bytes occupied by a byte.
static final int	BYTES_IN_CHAR	number of bytes occupied by a char.
static final int	BYTES_IN_DOUBLE	number of bytes occupied by a double.
static final int	BYTES_IN_FLOAT	number of bytes occupied by a float.
static final int	BYTES_IN_INTEGER	number of bytes occupied by a integer.
static final int	BYTES_IN_LONG	number of bytes occupied by a long.
static final int	BYTES_IN_SHORT	number of bytes occupied by a short.
static final int	DEFAULT_BUFFER_SIZE	default buffer size to use unless specified otherwise.
static final long	HIGH_INTEGER_MASK	bit mask to get the highest integer from an long.
static final long	INTEGER_MASK	bit mask to get the lowest integer from an long.
static final int	SHORT_MASK	bit mask to get the lowest short of a integer.
static final long	SHORT_OF_LONG_MASK	bit mask to get the lowest short of a long.

Constructor Summary

Constructors

Constructor	Description
FitsInputStream(InputStream i)	Create a BufferedInputStream based on an input stream.
FitsInputStream(InputStream i, int bufLength)	Create a BufferedInputStream based on a input stream with a specified buffer size.

Method Summary

Modifier and Type	Method	Description
final long	nextChecksum()	(for internal use) Returns the aggregated checksum for this stream since the last call to this method, or else since instantiation.
int	read()	Reads a byte.
int	read(boolean[] b, int start, int length)	Read a segment of an array of boolean's.
int	read(byte[] b, int from, int len)	Reads up to the specified number of bytes into a buffer.
int	read(char[] c, int start, int length)	Read a segment of an array of char's.
int	read(double[] d, int start, int length)	Read a segment of an array of double's.
int	read(float[] f, int start, int length)	Read a segment of an array of float's.
int	read(int[] i, int start, int length)	Read a segment of an array of int's.
int	read(long[] l, int start, int length)	Read a segment of an array of long's.
int	read(short[] s, int start, int length)	Read a segment of an array of short's.
int	read(Boolean[] b, int start, int length)	Reads into an array of booleans, possibly including legal null values.
boolean	readBoolean()
byte	readByte()
char	readChar()
double	readDouble()
float	readFloat()
void	readFully(byte[] b)
void	readFully(byte[] b, int off, int len)
int	readInt()
final String	readLine()
long	readLong()
final int	readPrimitiveArray(Object o)	Deprecated. use ArrayInputStream.readLArray(Object) instead
short	readShort()
int	readUnsignedByte()
int	readUnsignedShort()
String	readUTF()
long	skip(long n)	Skip the number of bytes.
void	skipAllBytes(long toSkip)	Skips a number of bytes from the input.
int	skipBytes(int n)
String	toString()

Methods inherited from class ArrayInputStream

readArrayFully, readImage, readLArray

Modifier and Type	Method	Description
void	readArrayFully(Object o)	See ArrayDataInput.readArrayFully(Object) for a contract of this method.
void	readImage(Object o)	Like ArrayInputStream.readArrayFully(Object) but strictly for numerical types only.
long	readLArray(Object o)	See ArrayDataInput.readLArray(Object) for a contract of this method.

Methods inherited from class BufferedInputStream

available, close, mark, markSupported, reset, transferTo

Methods inherited from class FilterInputStream

read

Methods inherited from class InputStream

nullInputStream, readAllBytes, readNBytes, readNBytes, skipNBytes

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ArrayDataInput

mark, markSupported, read, read, read, read, read, read, read, read, read, readArray, readArrayFully, readImage, readLArray, reset, skipAllBytes

Modifier and Type	Method	Description
void	mark(int readlimit)	See the general contract of the mark method of InputStream.
default boolean	markSupported()	See the general contract of the markSupported method of InputStream.
default int	read(boolean[] buf)	Read an array of boolean's.
int	read(byte[] buf)	Read an array of byte's.
default int	read(char[] buf)	Read an array of char's.
default int	read(double[] buf)	Read an array of double's.
default int	read(float[] buf)	Read an array of float's.
default int	read(int[] buf)	Read an array of int's.
default int	read(long[] buf)	Read a segment of an array of long's.
default int	read(short[] buf)	Read an array of short's.
default int	read(Boolean[] buf)	Read an array of booleans, possibly including legal null values.
default int	readArray(Object o)	Deprecated. Use ArrayDataInput.readLArray(Object) instead.
default void	readArrayFully(Object o)	Reads a Java array from the input, populating all elements, or else throwing and EOFException.
default void	readImage(Object o)	Like ArrayDataInput.readArrayFully(Object) but strictly for numerical types only.
long	readLArray(Object o)	Reads a Java array from the input, translating it from its binary representation to Java data format.
void	reset()	See the general contract of the reset method of InputStream.
default void	skipAllBytes(int toSkip)	Deprecated. This call is handled by ArrayDataInput.skipAllBytes(long), without the need for a separate implementation.

Methods inherited from interface FitsIO

close

Modifier and Type	Method	Description
void	close()

Constructor Details

FitsInputStream

public FitsInputStream(InputStream i,
 int bufLength)

Create a BufferedInputStream based on a input stream with a specified buffer size.

Parameters:

i - the input stream to use for reading.

bufLength - the buffer length to use.

FitsInputStream

public FitsInputStream(InputStream i)

Create a BufferedInputStream based on an input stream.

Parameters:

i - the input stream to use for reading.

Method Details

read

public int read()
         throws IOException

Description copied from interface: InputReader

Reads a byte. See the general contract of FilterInputStream.read().

Specified by:

read in interface InputReader

Overrides:

read in class BufferedInputStream

Returns:

the (unsigned) byte value or -1 if there is nothing left to read.

Throws:

IOException - if there was an underlying IO error

See Also:

• FilterInputStream.read()

read

public int read(byte[] b,
 int from,
 int len)
         throws IOException

Description copied from interface: InputReader

Reads up to the specified number of bytes into a buffer. See the general contract of DataInputStream.read(byte[], int, int).

Specified by:

read in interface InputReader

Overrides:

read in class BufferedInputStream

Parameters:

b - the buffer

from - the starting buffer index

len - the number of bytes to read.

Returns:

the number of bytes actually read, or -1 if there is nothing left to read.

Throws:

IOException - if there was an underlying IO error

See Also:

• DataInputStream.read(byte[], int, int)

nextChecksum

public final long nextChecksum()

(for internal use) Returns the aggregated checksum for this stream since the last call to this method, or else since instantiation. Checksums for a block of data thus may be obtained by calling this method both before and after reading the data block -- the first call resets the checksum and the block checksum is returned on the second call. The checksummed block must be a multiple of 2880 bytes (the FITS block size) for the result to be valid.

Returns:

the aggregated checksum since the last call to this method, or else since instantiation, on an integer number of FITS blocks read in the meantime.

Since:

1.18.1

readFully

public void readFully(byte[] b)
               throws IOException

Specified by:

readFully in interface DataInput

Throws:

IOException

readFully

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

Specified by:

readFully in interface ArrayDataInput

Specified by:

readFully in interface DataInput

Throws:

IOException

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of boolean's.

Specified by:

read in interface ArrayDataInput

Parameters:

b - array of boolean's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

public int read(Boolean[] b,
 int start,
 int length)
         throws IOException

Description copied from interface: ArrayDataInput

Reads into an array of booleans, possibly including legal null values. The method has a default implementation, calls DataInput.readBoolean() element by element. Classes that implement this interface might want to replace that with a more efficient block read implementation and/or to add the desired translation for null values.

Specified by:

read in interface ArrayDataInput

Parameters:

b - array of boolean's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of char's.

Specified by:

read in interface ArrayDataInput

Parameters:

c - array of char's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of short's.

Specified by:

read in interface ArrayDataInput

Parameters:

s - array of short's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of int's.

Specified by:

read in interface ArrayDataInput

Parameters:

i - array of int's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of long's.

Specified by:

read in interface ArrayDataInput

Parameters:

l - array of long's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of float's.

Specified by:

read in interface ArrayDataInput

Parameters:

f - array of float's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read.

Throws:

IOException - if one of the underlying read operations failed

read

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

Description copied from interface: ArrayDataInput

Read a segment of an array of double's.

Specified by:

read in interface ArrayDataInput

Parameters:

d - array of double's.

start - start index in the array

length - number of array elements to read

Returns:

number of bytes read, or -1 if at the end of file/stream

Throws:

IOException - if one of the underlying read operations failed

readPrimitiveArray

@Deprecated
public final int readPrimitiveArray(Object o)
                             throws IOException

Deprecated.

use ArrayInputStream.readLArray(Object) instead

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.

Returns:

number of bytes read.

Throws:

IOException - if the underlying read operation fails

skip

public long skip(long n)
          throws IOException

Description copied from interface: ArrayDataInput

Skip the number of bytes. This differs from the skip method in that it will throw an EOF if a forward skip cannot be fully accomplished... (However that isn't supposed to happen with a random access file, so there is probably no operational difference).

Specified by:

skip in interface ArrayDataInput

Overrides:

skip in class BufferedInputStream

Parameters:

n - the number of bytes to skip. Negative arguments are generally allowed, and subclass implementations may support it or else return 0 when a negative distance is specified.

Returns:

the number of bytes actually skipped

Throws:

IOException - if the underlying stream failed

See Also:

• InputStream.skip(long)
• ArrayDataInput.skipAllBytes(long)

skipBytes

public int skipBytes(int n)
              throws IOException

Specified by:

skipBytes in interface DataInput

Throws:

IOException

skipAllBytes

public void skipAllBytes(long toSkip)
                  throws EOFException,
IOException

Description copied from interface: ArrayDataInput

Skips a number of bytes from the input. This differs from the ArrayDataInput.skip(long) method in that it will throw an EOF if the skip cannot be fully accomplished as requested...

Specified by:

skipAllBytes in interface ArrayDataInput

Parameters:

toSkip - the number of bytes to skip forward. Subclass implementations may support negative valued arguments for a backward skip also.

Throws:

EOFException - if the end (or beginning) of the stream was reached before skipping the required number of bytes. This does not happen typically with forward skips on random access files, where positioning beyond the EOF is generally allowed for writing.

IOException - if there was an underlying IO failure.

See Also:

• ArrayDataInput.skip(long)

readBoolean

public boolean readBoolean()
                    throws IOException

Specified by:

readBoolean in interface DataInput

Throws:

IOException

readUnsignedByte

public int readUnsignedByte()
                     throws IOException

Specified by:

readUnsignedByte in interface DataInput

Throws:

IOException

readByte

public byte readByte()
              throws IOException

Specified by:

readByte in interface DataInput

Throws:

IOException

readChar

public char readChar()
              throws IOException

Specified by:

readChar in interface DataInput

Throws:

IOException

readUnsignedShort

public int readUnsignedShort()
                      throws IOException

Specified by:

readUnsignedShort in interface DataInput

Throws:

IOException

readShort

public short readShort()
                throws IOException

Specified by:

readShort in interface DataInput

Throws:

IOException

readInt

public int readInt()
            throws IOException

Specified by:

readInt in interface DataInput

Throws:

IOException

readLong

public long readLong()
              throws IOException

Specified by:

readLong in interface DataInput

Throws:

IOException

readFloat

public float readFloat()
                throws IOException

Specified by:

readFloat in interface DataInput

Throws:

IOException

readDouble

public double readDouble()
                  throws IOException

Specified by:

readDouble in interface DataInput

Throws:

IOException

readUTF

public String readUTF()
               throws IOException

Specified by:

readUTF in interface DataInput

Throws:

IOException

readLine

public final String readLine()
                      throws IOException

Specified by:

readLine in interface DataInput

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object