uk.ac.starlink.fits

Class AbstractFitsTableWriter

java.lang.Object

uk.ac.starlink.table.StreamStarTableWriter

uk.ac.starlink.fits.AbstractFitsTableWriter

All Implemented Interfaces:

MultiStarTableWriter, StarTableWriter

Direct Known Subclasses:

ColFitsTableWriter, FitsTableWriter, HduFitsTableWriter, HealpixFitsTableWriter, VariableFitsTableWriter, VOTableFitsTableWriter

public abstract class AbstractFitsTableWriter
extends StreamStarTableWriter
implements MultiStarTableWriter

Abstract table writer superclass designed for writing FITS tables.

A couple of Auxiliary metadata items of the ColumnInfo metadata from written tables are respected:

• Tables.NULL_VALUE_INFO: sets the value of TNULLn "magic" blank value for integer columns
• Tables.UBYTE_FLAG_INFO: if set to Boolean.TRUE and if the column has content class Short or short[], the data will be written as unsigned bytes (TFORMn='B') not 16-bit signed integers (TFORMn='I').
• BintableStarTable.LONGOFF_INFO: if this is set to a string representation of an integer value, and the column has content class String or String[], then the data will be written as long integers (TFORMn='K') with the given offset (TZEROn=...). This option supports round-tripping of offset long values (typically representing unsigned longs) which are converted to strings on read.

Since:

27 Jun 2006

Author:

Mark Taylor

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractFitsTableWriter(String formatName) Constructor.

Method Summary

Modifier and Type	Method and Description
protected abstract FitsTableSerializer	createSerializer(StarTable table) Provides a suitable serializer for a given table.
boolean	getAllowSignedByte() Returns a flag indicating how Byte-valued columns are written.
boolean	getAllowZeroLengthString() Indicates whether zero-length string columns may be output.
FitsTableSerializerConfig	getConfig() Returns the configuration details for writing FITS files.
static String	getCurrentDate() Returns an ISO-8601 data string representing the time at which this method is called.
String	getFormatName() Gives the name of the format which is written by this writer.
protected List<CardImage>	getMetadataCards() Adds some standard metadata header cards to a FITS table header.
String	getMimeType() Returns "application/fits".
byte	getPadCharacter() Returns the byte value with which under-length string (character array) values will be padded.
WideFits	getWide() Indicates the convention in use for representing over-wide tables.
boolean	getWriteDate() Indicates whether a datestamp is written to output FITS files.
void	setAllowSignedByte(boolean allowSignedByte) Configures how Byte-valued columns are written.
void	setAllowZeroLengthString(boolean allowZeroLengthString) Sets whether zero-length string columns may be written.
void	setFormatName(String formatName) Sets the declared format name.
void	setPadCharacter(byte padChar) Sets the byte value with which under-length string (character array) values should be padded.
void	setWide(WideFits wide) Sets the convention for representing over-wide (>999 column) tables.
void	setWriteDate(boolean writeDate) Configures whether a datestamp is written to output FITS files.
void	writePrimaryHDU(OutputStream out) Writes the primary HDU.
void	writeStarTable(StarTable table, OutputStream out) Writes a single table.
void	writeStarTables(TableSequence tableSeq, OutputStream out) Writes tables.
void	writeStarTables(TableSequence tableSeq, String location, StarTableOutput sto) Invokes writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream).
void	writeTableHDU(StarTable table, FitsTableSerializer fitser, OutputStream out) Writes a data HDU.

Methods inherited from class uk.ac.starlink.table.StreamStarTableWriter

writeStarTable, writeStarTable

Methods inherited from class java.lang.Object

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

Methods inherited from interface uk.ac.starlink.table.StarTableWriter

looksLikeFile, writeStarTable

Constructor Detail

AbstractFitsTableWriter

protected AbstractFitsTableWriter(String formatName)

Constructor.

Parameters:

formatName - format name

Method Detail

getFormatName

public String getFormatName()

Description copied from interface: StarTableWriter

Gives the name of the format which is written by this writer. Matching against this string may be used by callers to identify or select this writer from a list.

Specified by:

getFormatName in interface StarTableWriter

Returns:

a short string identifying the output format of this writer

setFormatName

public void setFormatName(String formatName)

Sets the declared format name.

Parameters:

formatName - format name

getMimeType

public String getMimeType()

Returns "application/fits".

Specified by:

getMimeType in interface StarTableWriter

Returns:

MIME type

writeStarTable

public void writeStarTable(StarTable table,
                           OutputStream out)
                    throws IOException

Writes a single table. Invokes writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream).

Specified by:

writeStarTable in interface StarTableWriter

Parameters:

table - the table to write

out - the output stream to which startab should be written

Throws:

TableFormatException - if this table cannot be written to a stream

IOException - if there is some I/O error

writeStarTables

public void writeStarTables(TableSequence tableSeq,
                            OutputStream out)
                     throws IOException

Writes tables. Calls writePrimaryHDU(java.io.OutputStream) to write the primary HDU. Subclasses which want to put something related to the input tables into the primary HDU will need to override this method (writeStarTables).

Specified by:

writeStarTables in interface MultiStarTableWriter

Parameters:

tableSeq - sequence of tables to write

out - destination stream

Throws:

IOException

writeStarTables

public void writeStarTables(TableSequence tableSeq,
                            String location,
                            StarTableOutput sto)
                     throws IOException

Invokes writeStarTables(uk.ac.starlink.table.TableSequence, java.io.OutputStream).

Specified by:

writeStarTables in interface MultiStarTableWriter

Parameters:

tableSeq - sequence of tables to write

location - destination for tables

sto - StarTableOutput instance

Throws:

IOException

writePrimaryHDU

public void writePrimaryHDU(OutputStream out)
                     throws IOException

Writes the primary HDU. This cannot contain a table since BINTABLE HDUs can only be extensions. The AbstractFitsTableWriter implementation writes a minimal, data-less HDU.

Parameters:

out - destination stream

Throws:

IOException

writeTableHDU

public void writeTableHDU(StarTable table,
                          FitsTableSerializer fitser,
                          OutputStream out)
                   throws IOException

Writes a data HDU.

Parameters:

table - the table to be written into the HDU

fitser - fits serializer initalised from table

out - destination stream

Throws:

IOException

getConfig

public FitsTableSerializerConfig getConfig()

Returns the configuration details for writing FITS files. Its content can be controlled using single-config-item mutator methods (which may also be labelled as ConfigMethods) on this class. This covers things that are generally orthogonal to the type of serialization, so may be set for any kind of FITS output, which is why it makes sense to manage them in the AbstractFitsTableWriter abstract superclass.

Returns:

object representing the FITS serialization options currently configured for this writer

createSerializer

protected abstract FitsTableSerializer createSerializer(StarTable table)
                                                 throws IOException

Provides a suitable serializer for a given table. Note this should throw an IOException if it can be determined that the submitted table cannot be written by this writer, for instance if it has too many columns.

Parameters:

table - table to serialize

Returns:

FITS serializer

Throws:

IOException - if the table can't be written

getMetadataCards

protected List<CardImage> getMetadataCards()

Adds some standard metadata header cards to a FITS table header. This includes date stamp, STIL version, etc.

Returns:

list of cards giving write-specific metadata

setWriteDate

@ConfigMethod(property="date",
              doc="<p>If true, the DATE-HDU header is filled in with the current date; otherwise it is not included.</p>")
public void setWriteDate(boolean writeDate)

Configures whether a datestamp is written to output FITS files.

Parameters:

writeDate - true to include DATE-HDU, false to omit it

getWriteDate

public boolean getWriteDate()

Indicates whether a datestamp is written to output FITS files.

Returns:

true to include DATE-HDU, false to omit it

setAllowSignedByte

public void setAllowSignedByte(boolean allowSignedByte)

Configures how Byte-valued columns are written. This is a bit fiddly, since java bytes are signed, but FITS 8-bit integers are unsigned. If true, they are written as FITS unsigned 8-bit integers with an offset, as discussed in the FITS standard (TFORMn='B', TZERO=-128). If false, they are written as FITS signed 16-bit integers.

Parameters:

allowSignedByte - true to write offset bytes, false to write shorts

getAllowSignedByte

public boolean getAllowSignedByte()

Returns a flag indicating how Byte-valued columns are written.

Returns:

true to write offset bytes, false to write shorts

setAllowZeroLengthString

public void setAllowZeroLengthString(boolean allowZeroLengthString)

Sets whether zero-length string columns may be written. Such columns (TFORMn='0A') are explicitly permitted by the FITS standard, but they can cause crashes because of divide-by-zero errors when encountered by some versions of CFITSIO (v3.50 and earlier), so FITS writing code may wish to avoid them. If this is set false, then A repeat values will always be >=1.

Parameters:

allowZeroLengthString - false to prevent zero-length string columns

getAllowZeroLengthString

public boolean getAllowZeroLengthString()

Indicates whether zero-length string columns may be output.

Returns:

false if zero-length string columns are avoided

setWide

public void setWide(WideFits wide)

Sets the convention for representing over-wide (>999 column) tables.

Parameters:

wide - wide-table representation policy, null to avoid wide tables

getWide

public WideFits getWide()

Indicates the convention in use for representing over-wide tables.

Returns:

wide-table representation policy, null for no wide tables

setPadCharacter

public void setPadCharacter(byte padChar)

Sets the byte value with which under-length string (character array) values should be padded. This should normally be one of 0x00 (ASCII NUL) or 0x20 (space). The function of an ASCII NUL is to terminate the string early, as described in Section 7.3.3.1 of the FITS 4.0 standard; space characters pad it to its declared length with whitespace. Other values in the range 0x21-0x7E are permitted but probably not sensible.

Parameters:

padChar - character data padding byte

getPadCharacter

public byte getPadCharacter()

Returns the byte value with which under-length string (character array) values will be padded. This will normally be one of 0x00 (ASCII NUL) or 0x20 (space).

Returns:

character data padding byte

getCurrentDate

public static String getCurrentDate()

Returns an ISO-8601 data string representing the time at which this method is called.

Returns:

date string