Class Data
- All Implemented Interfaces:
FitsElement
- Direct Known Subclasses:
AbstractTableData
,ImageData
,RandomGroupsData
,UndefinedData
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
FieldsModifier and TypeFieldDescriptionprotected long
Deprecated.Will be removed.protected long
Deprecated.Will be private.protected RandomAccess
Deprecated.Will be private. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionlong
Computes and returns the FITS checksum for this data, for example to compare against the storedDATASUM
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
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
Returns the data content that is currently in memory.getData()
Returns the underlying Java representation of the data contained in this HDU's data segment.long
Returns the byte offset at which this element starts ina file.final Object
Same asgetData()
.protected final RandomAccess
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
Returns the calculated byte size of the data, regardless of whether the data is currently in memory or not.boolean
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
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 elementvoid
rewrite()
Rewrite the contents of the element in place.boolean
Checks if we can write this element back to its source.protected void
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
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.
-
Field Details
-
fileOffset
Deprecated.Will be private. Access viagetFileOffset()
The starting location of the data when last read -
dataSize
Deprecated.Will be removed. UsegetTrueSize()
instead. The size of the data when last read -
input
Deprecated.Will be private. UsegetRandomAccessInput()
instead. The input stream used.
-
-
Constructor Details
-
Data
public Data()
-
-
Method Details
-
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
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 elsefalse
if this data is currently loaded into RAM. #seedetach()
- 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, otherwisefalse
- Since:
- 1.18
- See Also:
-
calcChecksum
Computes and returns the FITS checksum for this data, for example to compare against the storedDATASUM
in the FITS header (e.g. viaBasicHDU.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 fileBasicHDU.verifyDataIntegrity()
orBasicHDU.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
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
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 returnnull
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 interfaceFitsElement
- 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
Same asgetData()
.- 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 interfaceFitsElement
- 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
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 viaensureData()
, for example as a result of agetData()
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
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
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 aFitsFile
, 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 interfaceFitsElement
- 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 interfaceFitsElement
- Returns:
- True if the reset succeeded.
-
rewrite
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 interfaceFitsElement
- 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 interfaceFitsElement
- Returns:
true
if this element can be rewritten?
-
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.- Throws:
FitsException
- if there was an issue loading the data from the previous input (if any)- Since:
- 1.18
- See Also:
-
setFileOffset
Record the information necessary for eading the data content at a later time (deferred reading).- Parameters:
o
- reread information.- See Also:
-
write
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 interfaceFitsElement
- Parameters:
o
- The data sink.- Throws:
FitsException
- if the write was unsuccessful.
-
toHDU
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.
-