org.jscience.io.fits
Class FitsFile

java.lang.Object
  extended by org.jscience.io.fits.FitsFile
Direct Known Subclasses:
InputStreamFitsFile, RandomAccessFitsFile

public class FitsFile
extends java.lang.Object

**************************************************************************** Represents an entire fits file. This particular class is mostly useful for FITS files created in memory. It allows access to the component HDUs, and it has a method for writing the file.

Subclasses like InputStreamFitsFile and RandomAccessFitsFile provide the functionality to read from a FITS data source. The HDU access methods in this class allow you to read only part of a FITS file in order to minimize memory usage and I/O, even though only the subclasses can take advantage of them.

*****************************************************************************


Field Summary
static int BLOCK_SIZE
          ****************************************** The number of bytes in a single FITS block - 2880 according to the FITS standard ********************************************
static int DATA_NOT_NEEDED
          *************************************************************************** Specifies that the data need not be read, and that the ability to read the data later need not be preserved
protected  java.util.List hdus
          an ordered list of the HDUs which have been read
protected  java.util.Map index
          a collection of the HDUs indexed by EXTNAME
protected  boolean isComplete
          a flag indicating whether all the HDUs have been read
static int NEED_DATA_LATER
          ************************************************************************** specifies that the data need not be read before returning the HDU, but that the ability to read the data later should be preserved
static int NEED_DATA_NOW
          *************************************************************************** Specifies that the data part of an HDU should be read before returning an HDU *****************************************************************************
 
Constructor Summary
FitsFile()
          *********************************************************************** Create a new empty FITS file with no HDUs (not even the primary one).
 
Method Summary
 void add(FitsHDU hdu)
          *********************************************************************** add an HDU to this file
static FitsFile createEmpty()
          ************************************************************************* factory method to create a new empty FITS file.
 FitsHDU getHDU(int number)
          *********************************************************************** returns one of the HDUs in this file.
 FitsHDU getHDU(int number, int when)
          *********************************************************************** return a given HDU structure, specifying a hint about whether to read the HDU data.
 FitsHDU getHDU(java.lang.String name)
          *********************************************************************** return an HDU structure with the corresponding EXTNAME.
 boolean isComplete()
          *********************************************************************** returns true if all HDUs in this file have been found.
 void write(java.io.OutputStream stream)
          *********************************************************************** write the file to an output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BLOCK_SIZE

public static final int BLOCK_SIZE
****************************************** The number of bytes in a single FITS block - 2880 according to the FITS standard ********************************************

See Also:
Constant Field Values

NEED_DATA_NOW

public static final int NEED_DATA_NOW
*************************************************************************** Specifies that the data part of an HDU should be read before returning an HDU *****************************************************************************

See Also:
Constant Field Values

NEED_DATA_LATER

public static final int NEED_DATA_LATER
************************************************************************** specifies that the data need not be read before returning the HDU, but that the ability to read the data later should be preserved. ****************************************************************************

See Also:
Constant Field Values

DATA_NOT_NEEDED

public static final int DATA_NOT_NEEDED
*************************************************************************** Specifies that the data need not be read, and that the ability to read the data later need not be preserved. ****************************************************************************

See Also:
Constant Field Values

hdus

protected java.util.List hdus
an ordered list of the HDUs which have been read


index

protected java.util.Map index
a collection of the HDUs indexed by EXTNAME


isComplete

protected boolean isComplete
a flag indicating whether all the HDUs have been read

Constructor Detail

FitsFile

public FitsFile()
*********************************************************************** Create a new empty FITS file with no HDUs (not even the primary one). Use createEmpty() to make an empty file with a default primary HDU. ************************************************************************

Method Detail

isComplete

public boolean isComplete()
*********************************************************************** returns true if all HDUs in this file have been found. This class always returns true, but subclasses may return other values.

Returns:
the value of isComplete. ************************************************************************

add

public void add(FitsHDU hdu)
*********************************************************************** add an HDU to this file

Parameters:
hdu - the HDU to be added to this file. ************************************************************************

getHDU

public FitsHDU getHDU(int number)
               throws java.io.IOException
*********************************************************************** returns one of the HDUs in this file.

Parameters:
number - the index of the HDU. The primary HDU is "0".
Returns:
The object representing the specified HDU.
Throws:
java.io.IOException - if there was trouble reading the specified HDU from a file. ************************************************************************

getHDU

public FitsHDU getHDU(java.lang.String name)
               throws java.io.IOException
*********************************************************************** return an HDU structure with the corresponding EXTNAME. If multiple HDUs have the specified EXTNAME, then it is undefined which one will be returned.

Parameters:
name - the value of the EXTNAME keyword in the desired HDU
Returns:
The named HDU.
Throws:
java.io.IOException - if there was trouble reading the specified HDU from a file. ************************************************************************

getHDU

public FitsHDU getHDU(int number,
                      int when)
               throws java.io.IOException
*********************************************************************** return a given HDU structure, specifying a hint about whether to read the HDU data. A FitsHDU class holds the entire data content of the HDU in memory. So this method allows you to save memory and the time it takes to read the HDU contents if all you are interested in is the header keywords. Note that only certain types of FITS files (in particular RandomAccessFitsFile) can take advantage of the hint. The header keywords are always read.

Parameters:
number - the index of the HDU with zero being the primary HDU.
when - the code indicating when the data will be needed. It must have one of the values: NEED_DATA_NOW, NEED_DATA_LATER, or DATA_NOT_NEEDED.
Returns:
The named HDU.
Throws:
java.io.IOException - if there was trouble reading the specified HDU from a file.

************************************************************************


write

public void write(java.io.OutputStream stream)
           throws java.io.IOException
*********************************************************************** write the file to an output stream.

Parameters:
stream - The output stream where the file will be written.
Throws:
java.io.IOException - is there was trouble writing the file. ************************************************************************

createEmpty

public static FitsFile createEmpty()
                            throws FitsException
************************************************************************* factory method to create a new empty FITS file.

Throws:
FitsException - if there was trouble creating the file, although this is unlikely to ever happen. **************************************************************************