Package nom.tam.util.type

Class ElementType<B extends Buffer>

java.lang.Object
nom.tam.util.type.ElementType<B>
Type Parameters:
B - the generic type of data buffer
Direct Known Subclasses:
PrimitiveType
public abstract class ElementType<B extends Buffer> extends Object
A base data element type in a FITS image or table column, with associated functions.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ElementType<Buffer>
    BOOLEAN
    The FITS representation of a boolean value in binary tables
    static final ElementType<ByteBuffer>
    BYTE
    The FITS representation of a single (signed) byte value in images and binary tables
    static final ElementType<ByteBuffer>
    CHAR
    The FITS representation of a Java char value in binary tables
    static final int
    COPY_BLOCK_SIZE
    Deprecated.
    (for internal use) It's visibility may be reduced to the package level in the future.
    static final ElementType<DoubleBuffer>
    DOUBLE
    The FITS representation of a 64-bit double precison floating-point value in images and binary tables
    static final ElementType<FloatBuffer>
    FLOAT
    The FITS representation of a 32-bit single precison floating-point value in images and binary tables
    static final ElementType<IntBuffer>
    INT
    The FITS representation of a 32-bit sined integer value in images and binary tables
    static final ElementType<LongBuffer>
    LONG
    The FITS representation of a 64-bit sined integer value in images and binary tables
    static final ElementType<ShortBuffer>
    SHORT
    The FITS representation of a 16-bit sined integer value in images and binary tables
    static final ElementType<Buffer>
    STRING
    The FITS representation of an ASCII string in binary tables
    static final ElementType<Buffer>
    UNKNOWN
    Anything else for which we do not have a supported FITS representation

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    appendBuffer(B buffer, B dataToAppend)
    Appends data from one buffer to another.
    void
    appendToByteBuffer(ByteBuffer byteBuffer, B dataToAppend)
    Appends data from one buffer to a byte buffer.
    B
    asTypedBuffer(ByteBuffer buffer)
    Returns a typed view of a byte buffer, suitable for transacting elements of this type directly.
    int
    bitPix()
    Returns the integer BITPIX value to set in FITS headers for image HDUs of this element type.
    Class<B>
    bufferClass()
    Returns the class of buffer that can be used to serialize or deserialize elements of this type.
    ByteBuffer
    convertToByteBuffer(Object array)
    Serializes a 1D Java array containing Java native elements into a buffer using the appropriate FITS representation
    static ElementType<Buffer>
    forBitpix(int bitPix)
    Returns the FITS element type that matches the specified BITPIX value exactly.
    static <B extends Buffer>
    ElementType<B>
    forBuffer(B b)
    Returns the FITS element type that can transact with the specified buffer type directly.
    static <B extends Buffer>
    ElementType<B>
    forClass(Class<?> clazz)
    Returns the FITS element type for a given Java type
    static ElementType<Buffer>
    forDataID(char type)
    Returns the Fits element type for a given Java array type letter.
    static ElementType<Buffer>
    forNearestBitpix(int bitPix)
    Returns the FITS element type that is nearest to the specified BITPIX value.
    final void
    getArray(B buffer, Object array)
    Gets all elements of an array from a buffer
    final void
    getArray(B buffer, Object array, int length)
    Gets elements of an array from a buffer, starting at the beginning of the array.
    void
    getArray(B buffer, Object array, int offset, int length)
    Gets elements of an array from a buffer, starting at the specified array index.
    final boolean
    individualSize()
    Deprecated.
    Use isVariableSize() instead.
    boolean
    is(ElementType<? extends Buffer> other)
    Checks if this element type is the same as another.
    boolean
    isVariableSize()
    Checks if this type of element has a variable size, rather than a fixed size
    Object
    newArray(int length)
    Creates a new 1D Java array for storing elements of this type.
    final B
    newBuffer(int length)
    Creates a new new buffer of the specified size for this type of elements
    final B
    newBuffer(long length)
    Currently the same as newBuffer(int), but in the future it may be used to implement large memory mapped buffers....
    Class<?>
    primitiveClass()
    Returns the Java primitive type corresponding to this element, if any
    final void
    putArray(B buffer, Object array)
    Puts all elements from an array into the given buffer
    final void
    putArray(B buffer, Object array, int length)
    Puts elements from an array into the given buffer, starting at the beginning of the array
    void
    putArray(B buffer, Object array, int offset, int length)
    Puts elements from an array into the given buffer, starting at the specified array index.
    int
    size()
    Returns the number of bytes per elements
    int
    size(Object instance)
    Returns the size of an element, provided it matches our element type.
    B
    sliceBuffer(B buffer)
    Returns a new typed buffer that starts at the the current position of the supplied typed buffer.
    char
    type()
    Returns the Java letter-code for this FITS element type.
    B
    wrap(Object array)
    Returns a buffer for this element type by wrapping a suitable 1D array as its backing store.
    Class<?>
    wrapperClass()
    Returns the boxed Java type for this type of element.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • COPY_BLOCK_SIZE

      public static final int COPY_BLOCK_SIZE
      Deprecated.
      (for internal use) It's visibility may be reduced to the package level in the future.
      Number of bytes to copy as a block
      See Also:

    • BOOLEAN

      public static final ElementType<Buffer> BOOLEAN
      The FITS representation of a boolean value in binary tables

    • BYTE

      public static final ElementType<ByteBuffer> BYTE
      The FITS representation of a single (signed) byte value in images and binary tables

    • CHAR

      public static final ElementType<ByteBuffer> CHAR
      The FITS representation of a Java char value in binary tables

    • DOUBLE

      public static final ElementType<DoubleBuffer> DOUBLE
      The FITS representation of a 64-bit double precison floating-point value in images and binary tables

    • FLOAT

      public static final ElementType<FloatBuffer> FLOAT
      The FITS representation of a 32-bit single precison floating-point value in images and binary tables

    • INT

      public static final ElementType<IntBuffer> INT
      The FITS representation of a 32-bit sined integer value in images and binary tables

    • LONG

      public static final ElementType<LongBuffer> LONG
      The FITS representation of a 64-bit sined integer value in images and binary tables

    • SHORT

      public static final ElementType<ShortBuffer> SHORT
      The FITS representation of a 16-bit sined integer value in images and binary tables

    • STRING

      public static final ElementType<Buffer> STRING
      The FITS representation of an ASCII string in binary tables

    • UNKNOWN

      public static final ElementType<Buffer> UNKNOWN
      Anything else for which we do not have a supported FITS representation

  • Method Details

    • appendBuffer

      public void appendBuffer(B buffer, B dataToAppend)
      Appends data from one buffer to another.
      Parameters:
      buffer - the destination buffer
      dataToAppend - the buffer containing the data segment to append.

    • appendToByteBuffer

      public void appendToByteBuffer(ByteBuffer byteBuffer, B dataToAppend)
      Appends data from one buffer to a byte buffer.
      Parameters:
      byteBuffer - the destination buffer
      dataToAppend - the buffer containing the data segment to append.

    • asTypedBuffer

      public B asTypedBuffer(ByteBuffer buffer)
      Returns a typed view of a byte buffer, suitable for transacting elements of this type directly.
      Parameters:
      buffer - a byte buffer
      Returns:
      the typed view of the byte buffer

    • bitPix

      public int bitPix()
      Returns the integer BITPIX value to set in FITS headers for image HDUs of this element type.
      Returns:
      The BITPIX value that FITS uses to specify images of this element type.

    • bufferClass

      public Class<B> bufferClass()
      Returns the class of buffer that can be used to serialize or deserialize elements of this type.
      Returns:
      The class of buffer that can transact elements of this type.
      See Also:

    • convertToByteBuffer

      public ByteBuffer convertToByteBuffer(Object array)
      Serializes a 1D Java array containing Java native elements into a buffer using the appropriate FITS representation
      Parameters:
      array - the 1D Java array of elements for this type
      Returns:
      The FITS serialized representation as a buffer of bytes.

    • getArray

      public final void getArray(B buffer, Object array)
      Gets all elements of an array from a buffer
      Parameters:
      buffer - the typed buffer from which to retrieve elements
      array - the 1D array of matching type
      See Also:

    • getArray

      public final void getArray(B buffer, Object array, int length)
      Gets elements of an array from a buffer, starting at the beginning of the array.
      Parameters:
      buffer - the typed buffer from which to retrieve elements
      array - the 1D array of matching type
      length - the number of elements to fretrieve
      See Also:

    • getArray

      public void getArray(B buffer, Object array, int offset, int length)
      Gets elements of an array from a buffer, starting at the specified array index.
      Parameters:
      buffer - the typed buffer from which to retrieve elements
      array - the 1D array of matching type
      offset - the array index of the first element to retrieve
      length - the number of elements to fretrieve
      See Also:

    • isVariableSize

      public boolean isVariableSize()
      Checks if this type of element has a variable size, rather than a fixed size
      Returns:
      true if this element may appear with different sizes in the FITS binary stream. Otherwise false if it is always the same fixed size.
      See Also:

    • individualSize

      @Deprecated public final boolean individualSize()
      Deprecated.
      Use isVariableSize() instead.
      Returns:
      true if this type of element comes in all sizes, and the particular size of an obejct of this element type is specific to its instance. Or, false for fixed-sized elements.

    • is

      public boolean is(ElementType<? extends Buffer> other)
      Checks if this element type is the same as another.
      Parameters:
      other - Another element type
      Returns:
      true if both element types are the same, otherwise false.

    • newArray

      public Object newArray(int length)
      Creates a new 1D Java array for storing elements of this type.
      Parameters:
      length - the number of elements to store in the array
      Returns:
      the Java array suitable for storing the elements, or null if the operation is not supported or possible.
      See Also:

    • newBuffer

      public final B newBuffer(int length)
      Creates a new new buffer of the specified size for this type of elements
      Parameters:
      length - the number of elements in the buffer
      Returns:
      a new buffer of the specified size for this type of elements
      See Also:

    • newBuffer

      public final B newBuffer(long length) throws IllegalArgumentException
      Currently the same as newBuffer(int), but in the future it may be used to implement large memory mapped buffers....
      Parameters:
      length - the number of elements in the buffer
      Returns:
      a new buffer of the specified size for this type of elements, or null if the argument is beyond the supported range
      Throws:
      IllegalArgumentException - if the length is larger than what can be supported.
      See Also:

    • primitiveClass

      public Class<?> primitiveClass()
      Returns the Java primitive type corresponding to this element, if any
      Returns:
      the Java primitive type that corresponds to this element, or null if there is no primitive type equivalent to this FITS element type.
      See Also:

    • putArray

      public final void putArray(B buffer, Object array)
      Puts all elements from an array into the given buffer
      Parameters:
      buffer - the typed buffer in which to put elements
      array - the 1D array of matching type
      Since:
      1.18
      See Also:

    • putArray

      public final void putArray(B buffer, Object array, int length)
      Puts elements from an array into the given buffer, starting at the beginning of the array
      Parameters:
      buffer - the typed buffer in which to put elements
      array - the 1D array of matching type
      length - the number of elements to put into the buffer
      Since:
      1.18
      See Also:

    • putArray

      public void putArray(B buffer, Object array, int offset, int length)
      Puts elements from an array into the given buffer, starting at the specified array index.
      Parameters:
      buffer - the typed buffer in which to put elements
      array - the 1D array of matching type
      offset - the array index of the first element to put into the buffer
      length - the number of elements to put into the buffer
      Since:
      1.18
      See Also:

    • size

      public int size()
      Returns the number of bytes per elements
      Returns:
      the number of bytes each element of this type occupies in FITS binary representation
      See Also:

    • size

      public int size(Object instance)
      Returns the size of an element, provided it matches our element type.
      Parameters:
      instance - the object to calculate the size
      Returns:
      size() if the object is a primitive or boxed java type that matches this element type, or 0 if the object is null.
      Throws:
      IllegalArgumentException - if the object is not of the type expected by this class.
      See Also:

    • sliceBuffer

      public B sliceBuffer(B buffer)
      Returns a new typed buffer that starts at the the current position of the supplied typed buffer. See Buffer.slice() for the contract on slices.
      Parameters:
      buffer - the buffer from which to create the new slice
      Returns:
      A new buffer of the same type as the argument, that begins at the current position of the original buffer, or null if the slicing is not possuble or not implemented.
      See Also:

    • type

      public char type()
      Returns the Java letter-code for this FITS element type. For example Java long would be type 'J' since 1D long[] arrays report as [J by Java.
      Returns:
      the boxed Java type for this FITS element type.
      See Also:

    • wrap

      public B wrap(Object array)
      Returns a buffer for this element type by wrapping a suitable 1D array as its backing store.
      Parameters:
      array - the matching 1D array for this type to serve as the backing store of the buffer. Changes to the array will be visible through the buffer and vice versa.
      Returns:
      A new buffer for this type of element that uses the specified array as its backing store.

    • wrapperClass

      public Class<?> wrapperClass()
      Returns the boxed Java type for this type of element.
      Returns:
      the boxed Java type that corresponds to this type of element.
      See Also:

    • forDataID

      public static ElementType<Buffer> forDataID(char type)
      Returns the Fits element type for a given Java array type letter. For example LONG is returned for 'J' since Java denotes long[] arrays as [J in shorthand.
      Parameters:
      type - the letter code used for denoting java arrays of a given type in shorthand
      Returns:
      the matching FITS element type.
      See Also:

    • forClass

      public static <B extends Buffer> ElementType<B> forClass(Class<?> clazz)
      Returns the FITS element type for a given Java type
      Type Parameters:
      B - The generic type of buffer for the FITS element type
      Parameters:
      clazz - The Java primitive or boxed type for the corresponding element, or else the buffer class that it uses.
      Returns:
      The matching FITS element type.
      See Also:

    • forBuffer

      public static <B extends Buffer> ElementType<B> forBuffer(B b)
      Returns the FITS element type that can transact with the specified buffer type directly.
      Type Parameters:
      B - the generic type of buffer
      Parameters:
      b - a typed buffer instance
      Returns:
      the FITS element type that goes with the specified typed buffer
      See Also:

    • forBitpix

      public static ElementType<Buffer> forBitpix(int bitPix)
      Returns the FITS element type that matches the specified BITPIX value exactly.
      Parameters:
      bitPix - the BITPIX value that FITS uses to specify the element type for images.
      Returns:
      The matching FITS element type, or null if there is no matching FITS element type.
      See Also:

    • forNearestBitpix

      public static ElementType<Buffer> forNearestBitpix(int bitPix)
      Returns the FITS element type that is nearest to the specified BITPIX value. This method can be used to guess what the element type may be when the BITPIX value is not strictly to specification in the FITS header.
      Parameters:
      bitPix - the BITPIX value that FITS uses to specify the element type for images.
      Returns:
      The FITS element type that is closest to the specified value, or UNKNOWN if the specified values is not near any known BITPIX type.
      See Also: