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:

• Constant Field Values

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:

• getArray(Buffer, Object, int, int)
• putArray(Buffer, Object, int, int)

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(Buffer, Object, int)
• getArray(Buffer, Object, int, int)
• putArray(Buffer, Object)

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(Buffer, Object)
• getArray(Buffer, Object, int, int)
• putArray(Buffer, Object, int)

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:

• getArray(Buffer, Object)
• putArray(Buffer, Object, int, int)

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:

• size()

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(int)

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:

• newArray(int)
• newBuffer(long)

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:

• newBuffer(int)

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:

• wrapperClass()
• type()

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(Buffer, Object, int)
• putArray(Buffer, Object, int, int)
• getArray(Buffer, Object)

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(Buffer, Object)
• putArray(Buffer, Object, int, int)
• getArray(Buffer, Object, int)

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:

• putArray(Buffer, Object)
• getArray(Buffer, Object, int, int)

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:

• isVariableSize()

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:

• size()

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:

• Buffer.slice()

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:

• primitiveClass()
• wrapperClass()
• forDataID(char)

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:

• primitiveClass()
• type()

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:

• type()

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:

• primitiveClass()
• wrapperClass()
• bufferClass()
• forBuffer(Buffer)

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:

• forClass(Class)

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(int)
• bitPix()

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:

• forBitpix(int)
• bitPix()