Package nom.tam.fits.header

Class FitsKey

java.lang.Object
nom.tam.fits.header.FitsKey
All Implemented Interfaces:
Serializable, IFitsHeader
Direct Known Subclasses:
FitsHeaderImpl
public class FitsKey extends Object implements IFitsHeader, Serializable

A concrete implementation of standardized FITS header keywords. Users may instantiate this class or extend it to define commonly used keywords for their applications, and benefit for the extra checks they afford, and to avoid typos when using these.

FITS keywords must be composed of uppper-case 'A'-'Z', digits, underscore ('_') and hyphen ('-') characters. Additionally, lower case 'n' may be used as a place-holder for a numerical index, and the keyword name may end with a lower-case 'a' to indicate that it may be used for/with alternate WCS coordinate systems. (We also allow '/' because some STScI keywords use it even though it violates the FITS standard.)

Since:
1.19
See Also:

  • Constructor Details

    • FitsKey

      public FitsKey(String headerName, IFitsHeader.SOURCE status, IFitsHeader.HDU hdu, IFitsHeader.VALUE valueType, String comment) throws IllegalArgumentException
      Creates a new standardized FITS keyword with the specific usage constraints. The keyword must be composed of uppper-case 'A'-'Z', digits, underscore ('_') and hyphen ('-') characters. Additionally, lower case 'n' may be used as a place-holder for a numerical index, and the keyword name may end with a lower-case 'a' to indicate that it may be used for/with alternate WCS coordinate systems. (We also allow '/' because some STScI keywords use it even though it violates the FITS standard.)
      Parameters:
      headerName - The keyword as it will appear in the FITS headers, usually a string with up to 8 characters, containing uppper case letters (A-Z), digits (0-9), and/or underscore (_) or hyphen (-) characters for standard FITS keywords.
      status - The convention that defines this keyword
      hdu - the type of HDU this keyword may appear in
      valueType - the type of value that may be associated with this keyword
      comment - the standard comment to include with this keyword
      Throws:
      IllegalArgumentException - if the keyword name is invalid.

    • FitsKey

      public FitsKey(String headerName, IFitsHeader.HDU hdu, IFitsHeader.VALUE valueType, String comment) throws IllegalArgumentException
      Creates a new standardized user-defined FITS keyword. The keyword will have source set to IFitsHeader.SOURCE.UNKNOWN. The keyword must be composed of uppper-case 'A'-'Z', digits, underscore ('_') and hyphen ('-') characters. Additionally, lower case 'n' may be used as a place-holder for a numerical index, and the keyword name may end with a lower-case 'a' to indicate that it may be used for/with alternate WCS coordinate systems. (We also allow '/' because some STScI keywords use it even though it violates the FITS standard.)
      Parameters:
      headerName - The keyword as it will appear in the FITS headers, usually a string with up to 8 characters, containing uppper case letters (A-Z), digits (0-9), and/or underscore (_) or hyphen (-) characters for standard FITS keywords.
      hdu - the type of HDU this keyword may appear in
      valueType - the type of value that may be associated with this keyword
      comment - the standard comment to include with this keyword
      Throws:
      IllegalArgumentException - if the keyword name is invalid.
      Since:
      1.19

    • FitsKey

      public FitsKey(String headerName, IFitsHeader.VALUE valueType, String comment) throws IllegalArgumentException
      Creates a new standardized user-defined FITS keyword. The keyword will have source set to IFitsHeader.SOURCE.UNKNOWN and HDY type to IFitsHeader.HDU.ANY. The keyword must be composed of uppper-case 'A'-'Z', digits, underscore ('_') and hyphen ('-') characters. Additionally, lower case 'n' may be used as a place-holder for a numerical index, and the keyword name may end with a lower-case 'a' to indicate that it may be used for/with alternate WCS coordinate systems. (We also allow '/' because some STScI keywords use it even though it violates the FITS standard.)
      Parameters:
      headerName - The keyword as it will appear in the FITS headers, usually a string with up to 8 characters, containing uppper case letters (A-Z), digits (0-9), and/or underscore (_) or hyphen (-) characters for standard FITS keywords.
      valueType - the type of value that may be associated with this keyword
      comment - the standard comment to include with this keyword
      Throws:
      IllegalArgumentException - if the keyword name is invalid.
      Since:
      1.19

  • Method Details

    • impl

      public final FitsKey impl()
      Description copied from interface: IFitsHeader
      (primarily for internal use) Returns the concrete implementation of this header entry, which provides implementation of access methods.
      Specified by:
      impl in interface IFitsHeader
      Returns:
      the implementation of this keyword, which provides the actual access methods. Implementations of this interface should simply return themselves.

    • comment

      public String comment()
      Description copied from interface: IFitsHeader
      Returns the comment associated to this FITS header entry. The comment is entirely optional, and it may not be appear in full (or at all) in the FITS header. Comments should thus never contain essential information. Their purpose is only to provide non-essential extra information for human use.
      Specified by:
      comment in interface IFitsHeader
      Returns:
      the associated standard comment.
      See Also:

    • hdu

      public IFitsHeader.HDU hdu()
      Description copied from interface: IFitsHeader
      Returns the type of HDU(s) in which this header entry may be used.
      Specified by:
      hdu in interface IFitsHeader
      Returns:
      the HDU type(s) that this keyword may support.

    • key

      public String key()
      Description copied from interface: IFitsHeader

      Returns the FITS header keyword (or keyword template) for this header entry. Standard FITS keywords are limited to 8 characters, and contain only epper-case letters, numbers, hyphen, and underscore characters. Lower-case 'n' characters may be included as placeholders for indexing conventions that must be filled before the keyword may be used in headers and/or header cards.

      Specified by:
      key in interface IFitsHeader
      Returns:
      the FITS header keyword for this entry. The returned keyword may include an indexing pattern (lower-case 'n' characters), which may need to be filled via IFitsHeader.n(int...) before the keyword may be used to construct header cards or be used in FITS headers. (Alternative coordinate markers, via lower case 'a' at the end of the keyword definition, are stripped and should not be included in the returned keyword name pattern.)
      See Also:

    • status

      public IFitsHeader.SOURCE status()
      Description copied from interface: IFitsHeader
      Returns the standard convention, which defines this FITS header entry
      Specified by:
      status in interface IFitsHeader
      Returns:
      the standard or convention that specifies this FITS heacer keyword

    • valueType

      public IFitsHeader.VALUE valueType()
      Description copied from interface: IFitsHeader
      The type(s) of value(s) this FITS header entry might take.
      Specified by:
      valueType in interface IFitsHeader
      Returns:
      the value type(s) for this FITS header entry

    • isCommentStyleKey

      public static boolean isCommentStyleKey(String key)
      (for internal use) Checks if a keywords is known to be a comment-style keyword. That is, it checks if the key argument matches any IFitsHeader constructed via this implementation with a valueType argument that was null, or if the key is empty.
      Parameters:
      key - the keyword to check
      Returns:
      true if the key is empty or if it matches any known IFitsHeader keywords implemented through this class that have valueType of null. Otherwise false.
      Since:
      1.17