Package nom.tam.fits

Class Data

java.lang.Object
nom.tam.fits.Data
All Implemented Interfaces:
FitsElement
Direct Known Subclasses:
AbstractTableData, ImageData, RandomGroupsData, UndefinedData
public abstract class Data extends Object implements FitsElement
The data segment of an HDU.

This is the object which contains the actual data for the HDU.

  • For images and primary data this is a simple (but possibly multi-dimensional) primitive array. When group data is supported it will be a possibly multidimensional array of group objects.
  • For ASCII data it is a two dimensional Object array where each of the constituent objects is a primitive array of length 1.
  • For Binary data it is a two dimensional Object array where each of the constituent objects is a primitive array of arbitrary (more or less) dimensionality.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected long
    dataSize
    Deprecated.
    Will be removed.
    protected long
    fileOffset
    Deprecated.
    Will be private.
    protected RandomAccess
    input
    Deprecated.
    Will be private.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Data()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    calcChecksum()
    Computes and returns the FITS checksum for this data, for example to compare against the stored DATASUM in the FITS header (e.g.
    void
    detach()
    Detaches this data object from the input (if any), such as a file or stream, but not before loading data from the previously assigned input into memory.
    protected void
    ensureData()
    Makes sure that data that may have been deferred earlier from a random access input is now loaded into memory.
    protected abstract void
    fillHeader(Header head)
    Describe the structure of this data object in the supplied header.
    protected abstract Object
    getCurrentData()
    Returns the data content that is currently in memory.
    Object
    getData()
    Returns the underlying Java representation of the data contained in this HDU's data segment.
    long
    getFileOffset()
    Returns the byte offset at which this element starts ina file.
    final Object
    getKernel()
    Same as getData().
    protected final RandomAccess
    getRandomAccessInput()
    Returns the random accessible input from which this data can be read, if any.
    long
    getSize()
    Returns the size of this elements in the FITS representation.
    protected abstract long
    getTrueSize()
    Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.
    boolean
    isDeferred()
    Checks if the data should be assumed to be in deferred read mode.
    boolean
    isEmpty()
    Checks if the data content is currently empty, i.e.
    protected abstract void
    loadData(ArrayDataInput in)
    Load data from the current position of the input into memory.
    void
    read(ArrayDataInput in)
    Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.
    boolean
    reset()
    Reset the input stream to point to the beginning of this element
    void
    rewrite()
    Rewrite the contents of the element in place.
    boolean
    rewriteable()
    Checks if we can write this element back to its source.
    protected void
    setFileOffset(ArrayDataInput o)
    Record the information necessary for eading the data content at a later time (deferred reading).
    abstract BasicHDU<?>
    toHDU()
    Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
    abstract void
    write(ArrayDataOutput o)
    Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • Data

      public Data()

  • Method Details

    • getRandomAccessInput

      protected final RandomAccess getRandomAccessInput()
      Returns the random accessible input from which this data can be read, if any.
      Returns:
      the random access input from which we can read the data when needed, or null if this data object is not associated to an input, or it is not random accessible.

    • fillHeader

      protected abstract void fillHeader(Header head) throws FitsException
      Describe the structure of this data object in the supplied header.
      Parameters:
      head - header to fill with the data from the current data object
      Throws:
      FitsException - if the operation fails

    • isDeferred

      public boolean isDeferred()
      Checks if the data should be assumed to be in deferred read mode.
      Returns:
      true if it is set for deferred reading at a later time, or else false if this data is currently loaded into RAM. #see detach()
      Since:
      1.17

    • isEmpty

      public boolean isEmpty()
      Checks if the data content is currently empty, i.e. no actual data is currently stored in memory.
      Returns:
      true if there is no actual data in memory, otherwise false
      Since:
      1.18
      See Also:

    • calcChecksum

      public long calcChecksum() throws FitsException
      Computes and returns the FITS checksum for this data, for example to compare against the stored DATASUM in the FITS header (e.g. via BasicHDU.getStoredDatasum()). This method always computes the checksum from data in memory. As such it will fully load deferred read mode data into RAM to perform the calculation, and use the standard padding to complete the FITS block for the calculation. As such the checksum may differ from that of the file if the file uses a non-standard padding. Hence, for verifying data integrity as stored in a file BasicHDU.verifyDataIntegrity() or BasicHDU.verifyIntegrity() should be preferred.
      Returns:
      the computed FITS checksum from the data (fully loaded in memory).
      Throws:
      FitsException - if there was an error while calculating the checksum
      Since:
      1.17
      See Also:

    • getData

      public Object getData() throws FitsException
      Returns the underlying Java representation of the data contained in this HDU's data segment. Typically it will return a Java array of some kind.
      Returns:
      the underlying Java representation of the data core object, such as a multi-dimensional Java array.
      Throws:
      FitsException - if the data could not be gathered.
      See Also:

    • getCurrentData

      protected abstract Object getCurrentData()
      Returns the data content that is currently in memory. In case of a data object in deferred read state (that is its prescription has been parsed from the header, but no data content was loaded yet from a random accessible input), this call may return null or an object representing empty data.
      Returns:
      The current data content in memory.
      Since:
      1.18
      See Also:

    • getFileOffset

      public long getFileOffset()
      Description copied from interface: FitsElement
      Returns the byte offset at which this element starts ina file. If the element was not obtained from an input, then 0 is returned.
      Specified by:
      getFileOffset in interface FitsElement
      Returns:
      the byte at which this element begins. This is only available if the data is originally read from a random access medium. Otherwise 0 is returned.

    • getKernel

      public final Object getKernel() throws FitsException
      Same as getData().
      Returns:
      The data content as represented by a Java object..
      Throws:
      FitsException - if the data could not be gathered .

    • getSize

      public long getSize()
      Description copied from interface: FitsElement
      Returns the size of this elements in the FITS representation. This may include padding if the element (such as a header or data segment) is expected to complete a FITS block of 2880 bytes.
      Specified by:
      getSize in interface FitsElement
      Returns:
      The size of this element in bytes, or 0 if the element is empty or invalid.

    • getTrueSize

      protected abstract long getTrueSize()
      Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.
      Returns:
      the calculated byte size for the data.

    • loadData

      protected abstract void loadData(ArrayDataInput in) throws IOException, FitsException

      Load data from the current position of the input into memory. This may be triggered immediately when calling read(ArrayDataInput) if called on a non random accessible input, or else later when data is accessed via ensureData(), for example as a result of a getData() call. This method will not be called unless there is actual data of non-zero size to be read.

      Implementations should create appropriate data structures and populate them from the specified input.

      Parameters:
      in - The input from which to load data
      Throws:
      IOException - if the data could not be loaded from the input.
      FitsException - if the data is garbled.
      Since:
      1.18
      See Also:

    • ensureData

      protected void ensureData() throws FitsException
      Makes sure that data that may have been deferred earlier from a random access input is now loaded into memory.
      Throws:
      FitsException - if the deferred data could not be loaded.
      Since:
      1.18
      See Also:

    • read

      public void read(ArrayDataInput in) throws PaddingException, FitsException

      Reads the data or skips over it for reading later, depending on whether reading from a stream or a random acessible input, respectively.

      In case the argument is a an instance of RandomAccess input (such as a FitsFile, the call will simply note where in the file the data segment can be found for reading at a later point, only when the data content is accessed. This 'deferred' reading behavior make it possible to process large HDUs even with small amount of RAM, and can result in a significant performance boost when inspectring large FITS files, or using only select content from large FITS files.

      Specified by:
      read in interface FitsElement
      Parameters:
      in - The input data stream
      Throws:
      PaddingException - if there is missing padding between the end of the data segment and the enf-of-file.
      FitsException - if the data appears to be corrupted.
      See Also:

    • reset

      public boolean reset()
      Description copied from interface: FitsElement
      Reset the input stream to point to the beginning of this element
      Specified by:
      reset in interface FitsElement
      Returns:
      True if the reset succeeded.

    • rewrite

      public void rewrite() throws FitsException
      Description copied from interface: FitsElement
      Rewrite the contents of the element in place. The data must have been originally read from a random access device, and the size of the element may not have changed.
      Specified by:
      rewrite in interface FitsElement
      Throws:
      FitsException - if the rewrite was unsuccessful.

    • rewriteable

      public boolean rewriteable()
      Description copied from interface: FitsElement
      Checks if we can write this element back to its source. An element can only be written back if it is associated to a random accessible input and the current size FITS within the old block size.
      Specified by:
      rewriteable in interface FitsElement
      Returns:
      true if this element can be rewritten?

    • detach

      public void detach() throws FitsException
      Detaches this data object from the input (if any), such as a file or stream, but not before loading data from the previously assigned input into memory.
      Throws:
      FitsException - if there was an issue loading the data from the previous input (if any)
      Since:
      1.18
      See Also:

    • setFileOffset

      protected void setFileOffset(ArrayDataInput o)
      Record the information necessary for eading the data content at a later time (deferred reading).
      Parameters:
      o - reread information.
      See Also:

    • write

      public abstract void write(ArrayDataOutput o) throws FitsException
      Description copied from interface: FitsElement
      Writes the contents of the element to a data sink, adding padding as necessary if the element (such as a header or data segment) is expected to complete the FITS block of 2880 bytes.
      Specified by:
      write in interface FitsElement
      Parameters:
      o - The data sink.
      Throws:
      FitsException - if the write was unsuccessful.

    • toHDU

      public abstract BasicHDU<?> toHDU() throws FitsException
      Returns an approprotae HDU object that encapsulates this FITS data, and contains the minimal mandatory header description for that data.
      Returns:
      a HDU object ocntaining the data and its minimal required header description
      Throws:
      FitsException - If the data cannot be converted to an HDU for some reason.