ncsa.hdf.object
Class Datatype

java.lang.Object
  ncsa.hdf.object.HObject
      ncsa.hdf.object.Datatype

All Implemented Interfaces:

java.io.Serializable, DataFormat

Direct Known Subclasses:

FitsDatatype, H4Datatype, H5Datatype, NC2Datatype

public abstract class Datatype
extends HObject

Datatype is an abstract class that defines datatype characteristics and APIs for a data type.

A datatype has four basic characteristics: class, size, byte order and sign. These charactertics are defeined in the HDF5 User's Guide.

These charactertics apply to all the sub-classes. The sub-classes may have different ways to describe a datatype. We here define the native datatype to the datatype used by the sub-class. For example, H5Datatype uses a datatype identifier (hid_t) to specify a datatype. NC2Datatype uses ucar.nc2.DataType object to describe its dataype. "Native" here is different from the "native" definition in the HDF5 library.

Two functions, toNative() and fromNative(), are defined to convert the general charactertics to/form the native datatype. Sub-classes must implement these functions so that the conversion will be done correctly.

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

Serialized Form

Field Summary

static int	CLASS_ARRAY See HDF5 User's Guide
static int	CLASS_BITFIELD See HDF5 User's Guide
static int	CLASS_CHAR See HDF5 User's Guide
static int	CLASS_COMPOUND See HDF5 User's Guide
static int	CLASS_ENUM See HDF5 User's Guide
static int	CLASS_FLOAT See HDF5 User's Guide
static int	CLASS_INTEGER See HDF5 User's Guide
static int	CLASS_NO_CLASS See HDF5 User's Guide
static int	CLASS_OPAQUE See HDF5 User's Guide
static int	CLASS_REFERENCE See HDF5 User's Guide
static int	CLASS_STRING See HDF5 User's Guide
static int	CLASS_VLEN See HDF5 User's Guide
static int	NATIVE The default definition for datatype size, order, and sign.
static int	NSGN See HDF5 User's Guide
static int	ORDER_BE See HDF5 User's Guide
static int	ORDER_LE See HDF5 User's Guide
static int	ORDER_NONE See HDF5 User's Guide
static int	ORDER_VAX See HDF5 User's Guide
static int	SIGN_2 See HDF5 User's Guide
static int	SIGN_NONE See HDF5 User's Guide

Fields inherited from class ncsa.hdf.object.HObject

separator, serialVersionUID

Constructor Summary

Datatype(FileFormat theFile, java.lang.String name, java.lang.String path)
Constructs a named datatype with a given file, name and path.

Datatype(FileFormat theFile, java.lang.String name, java.lang.String path, long[] oid)
Deprecated. Not for public use in the future.
Using Datatype(FileFormat, String, String)

Datatype(int type)
Constructs a Datatype with a given native datatype identifier.

Datatype(int tclass, int tsize, int torder, int tsign)
Constructs a Datatype with specified class, size, byte order and sign.

Method Summary

abstract void	close(int id) Closes a datatype identifier.
abstract void	fromNative(int nativeID) Set datatype characteristics (class, size, byte order and sign) from a given datatye identifier.
Datatype	getBasetype() Returns the datatype of array element for ARRAY datatype.
int	getDatatypeClass() Returns the class of the datatype.
java.lang.String	getDatatypeDescription() Returns a short text description of this datatype.
int	getDatatypeOrder() Returns the byte order of the datatype.
int	getDatatypeSign() Returns the sign (SIGN_NONE, SIGN_2 or NSGN) of an integer datatype.
int	getDatatypeSize() Returns the size of the datatype in bytes.
java.lang.String	getEnumMembers() Returns the "name=value" pairs of enum members for enum datatype.
java.util.List	getMetadata() Retrieves the metadata such as attributes from file.
abstract boolean	isUnsigned() Checks if this datatype is an unsigned integer.
int	open() Opens access to this named datatype.
void	removeMetadata(java.lang.Object info) Deletes an existing metadata from this data object.
void	setEnumMembers(java.lang.String enumStr) Sets the (name, value) pairs of enum members for enum datatype.
abstract int	toNative() Converts the datatype object to a native datatype.
void	writeMetadata(java.lang.Object info) Writes a specific metadata (such as attribute) into file.

Methods inherited from class ncsa.hdf.object.HObject

equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, setLinkTargetObjName, setName, setPath, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface ncsa.hdf.object.DataFormat

hasAttribute

Field Detail

NATIVE

public static final int NATIVE

The default definition for datatype size, order, and sign.

See Also:

Constant Field Values

CLASS_NO_CLASS

public static final int CLASS_NO_CLASS

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_INTEGER

public static final int CLASS_INTEGER

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_FLOAT

public static final int CLASS_FLOAT

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_CHAR

public static final int CLASS_CHAR

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_STRING

public static final int CLASS_STRING

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_BITFIELD

public static final int CLASS_BITFIELD

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_OPAQUE

public static final int CLASS_OPAQUE

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_COMPOUND

public static final int CLASS_COMPOUND

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_REFERENCE

public static final int CLASS_REFERENCE

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_ENUM

public static final int CLASS_ENUM

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_VLEN

public static final int CLASS_VLEN

See HDF5 User's Guide

See Also:

Constant Field Values

CLASS_ARRAY

public static final int CLASS_ARRAY

See HDF5 User's Guide

See Also:

Constant Field Values

ORDER_LE

public static final int ORDER_LE

See HDF5 User's Guide

See Also:

Constant Field Values

ORDER_BE

public static final int ORDER_BE

See HDF5 User's Guide

See Also:

Constant Field Values

ORDER_VAX

public static final int ORDER_VAX

See HDF5 User's Guide

See Also:

Constant Field Values

ORDER_NONE

public static final int ORDER_NONE

See HDF5 User's Guide

See Also:

Constant Field Values

SIGN_NONE

public static final int SIGN_NONE

See HDF5 User's Guide

See Also:

Constant Field Values

SIGN_2

public static final int SIGN_2

See HDF5 User's Guide

See Also:

Constant Field Values

NSGN

public static final int NSGN

See HDF5 User's Guide

See Also:

Constant Field Values

Constructor Detail

Datatype

public Datatype(FileFormat theFile,
                java.lang.String name,
                java.lang.String path)

Constructs a named datatype with a given file, name and path.

Parameters:

theFile - the HDF file.

name - the name of the datatype, e.g "12-bit Integer".

path - the full group path of the datatype, e.g. "/datatypes/".

Datatype

@Deprecated
public Datatype(FileFormat theFile,
                           java.lang.String name,
                           java.lang.String path,
                           long[] oid)

Deprecated. Not for public use in the future.
Using Datatype(FileFormat, String, String)

Datatype

public Datatype(int tclass,
                int tsize,
                int torder,
                int tsign)

Constructs a Datatype with specified class, size, byte order and sign.

The following is a list of a few example of H5Datatype.

1. to create unsigned native integer
   H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE);
2. to create 16-bit signed integer with big endian
   H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE);
3. to create native float
   H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1);
4. to create 64-bit double
   H5Datatype type = new H5Dataype(CLASS_FLOAT, 8, NATIVE, -1);

Parameters:

tclass - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.

tsize - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4.

torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX and ORDER_NONE

tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN

Datatype

public Datatype(int type)

Constructs a Datatype with a given native datatype identifier.

For example, if the datatype identifier is a 32-bit unsigned integer created from HDF5,

 int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
 Datatype dtype = new Datatype(tid);
 

will construct a datatype equivalent to new Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);

Parameters:

type - the native datatype identifier.

See Also:

fromNative(int nativeID)

Method Detail

getDatatypeClass

public int getDatatypeClass()

Returns the class of the datatype. Valid values are:

• CLASS_NO_CLASS
• CLASS_INTEGER
• CLASS_FLOAT
• CLASS_CHAR
• CLASS_STRING
• CLASS_BITFIELD
• CLASS_OPAQUE
• CLASS_COMPOUND
• CLASS_REFERENCE
• CLASS_ENUM
• CLASS_VLEN
• CLASS_ARRAY

Returns:

the class of the datatype.

getDatatypeSize

public int getDatatypeSize()

Returns the size of the datatype in bytes. For example, for a 32-bit integer, the size is 4 (bytes).

Returns:

the size of the datatype.

getDatatypeOrder

public int getDatatypeOrder()

Returns the byte order of the datatype. Valid values are

• ORDER_LE
• ORDER_BE
• ORDER_VAX
• ORDER_NONE

Returns:

the byte order of the datatype.

getDatatypeSign

public int getDatatypeSign()

Returns the sign (SIGN_NONE, SIGN_2 or NSGN) of an integer datatype.

Returns:

the sign of the datatype.

getBasetype

public Datatype getBasetype()

Returns the datatype of array element for ARRAY datatype.

For example, a dataset set of ARRAY of inteter, The datatype of the dataset is ARRAY. The datatype of the base type is integer.

Returns:

the the datatype of array element for ARRAY datatype.

setEnumMembers

public final void setEnumMembers(java.lang.String enumStr)

Sets the (name, value) pairs of enum members for enum datatype.

For Example,

setEnumMembers("lowTemp=-40, highTemp=90")

sets the value of enum member lowTemp to -40 and highTemp to 90.

setEnumMembers("lowTemp, highTemp")

sets enum members to defaults, i.e. lowTemp=0 and highTemp=1

setEnumMembers("lowTemp=10, highTemp")

sets enum member lowTemp to 10 and highTemp to 11.

Parameters:

enumStr - the (name, value) pairs of enum members

getEnumMembers

public final java.lang.String getEnumMembers()

Returns the "name=value" pairs of enum members for enum datatype.

For Example,

setEnumMembers("lowTemp=-40, highTemp=90")

sets the value of enum member lowTemp to -40 and highTemp to 90.

setEnumMembers("lowTemp, highTemp")

sets enum members to defaults, i.e. lowTemp=0 and highTemp=1

setEnumMembers("lowTemp=10, highTemp")

sets enum member lowTemp to 10 and highTemp to 11.

Returns:

enumStr the (name, value) pairs of enum members

toNative

public abstract int toNative()

Converts the datatype object to a native datatype. Subclasses must implement it so that this datatype will be converted accordingly. Use close() to close the native identifier; otherwise, the datatype will be left open.

For example, a HDF5 datatype created from

 H5Dataype dtype = new H5Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
 int tid = dtype.toNative();
 

There "tid" will be the HDF5 datatype id of a 32-bit unsigned integer, which is equivalent to

 int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
 

Returns:

the identifier of the native datatype.

fromNative

public abstract void fromNative(int nativeID)

Set datatype characteristics (class, size, byte order and sign) from a given datatye identifier.

Sub-classes must implement it so that this datatype will be converted accordingly.

For example, if the type identifier is a 32-bit unsigned integer created from HDF5,

 H5Datatype dtype = new H5Datatype();
 dtype.fromNative(HDF5Constants.H5T_NATIVE_UNINT32);
 

Where dtype is equivalent to
new H5Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);

Parameters:

nativeID - the datatype identifier.

getDatatypeDescription

public java.lang.String getDatatypeDescription()

Returns a short text description of this datatype.

Returns:

a short text description of this datatype

isUnsigned

public abstract boolean isUnsigned()

Checks if this datatype is an unsigned integer.

Returns:

true if the datatype is an unsigned integer; otherwise, returns false.

open

public int open()

Opens access to this named datatype. Sub-clases must replace this default implementation. For example, in H5Datatype, open() function H5.H5Topen(loc_id, name) to get the datatype identifier.

Specified by:

open in class HObject

Returns:

the datatype identifier if successful; otherwise returns negative value.

See Also:

HObject.close(int)

close

public abstract void close(int id)

Closes a datatype identifier.

Sub-clases must replace this default implementation.

Specified by:

close in class HObject

Parameters:

id - the datatype identifier to close.

getMetadata

public java.util.List getMetadata()
                           throws java.lang.Exception

Description copied from interface: DataFormat

Retrieves the metadata such as attributes from file.

Metadata such as attributes are stored in a List.

Returns:

the list of metadata objects.

Throws:

java.lang.Exception

writeMetadata

public void writeMetadata(java.lang.Object info)
                   throws java.lang.Exception

Description copied from interface: DataFormat

Writes a specific metadata (such as attribute) into file.

If an HDF(4&5) attribute exists in file, the method updates its value. If the attribute does not exists in file, it creates the attribute in file and attaches it to the object. It will fail to write a new attribute to the object where an attribute with the same name already exists. To update the value of an existing attribute in file, one needs to get the instance of the attribute by getMetadata(), change its values, and use writeMetadata() to write the value.

Parameters:

info - the metadata to write.

Throws:

java.lang.Exception

removeMetadata

public void removeMetadata(java.lang.Object info)
                    throws java.lang.Exception

Description copied from interface: DataFormat

Deletes an existing metadata from this data object.

Parameters:

info - the metadata to delete.

Throws:

java.lang.Exception