ncsa.hdf.object.h5
Class H5Datatype

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

All Implemented Interfaces:

java.io.Serializable, DataFormat

public class H5Datatype
extends Datatype

This class defines HDF5 data type characteristics and APIs for a data type.

This class provides several methods to convert an HDF5 dataype identifier to a dataype object, and vice versa. A dataype object is described by four basic fields: datatype class, size, byte order, and sign, while an HDF5 dataype is presented by a datetype identifier.

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

Serialized Form

Field Summary

static long

serialVersionUID

Fields inherited from class ncsa.hdf.object.Datatype

CLASS_ARRAY, CLASS_BITFIELD, CLASS_CHAR, CLASS_COMPOUND, CLASS_ENUM, CLASS_FLOAT, CLASS_INTEGER, CLASS_NO_CLASS, CLASS_OPAQUE, CLASS_REFERENCE, CLASS_STRING, CLASS_VLEN, NATIVE, NSGN, ORDER_BE, ORDER_LE, ORDER_NONE, ORDER_VAX, SIGN_2, SIGN_NONE

Fields inherited from class ncsa.hdf.object.HObject

separator

Constructor Summary

H5Datatype(FileFormat theFile, java.lang.String name, java.lang.String path)
Constructs an named HDF5 data type object for a given file, dataset name and group path.

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

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

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

Method Summary

static java.lang.Object	allocateArray(int tid, int size) Allocates an one-dimensional array of byte, short, int, long, float, double, or String to store data in memory.
void	close(int tid) Closes a datatype identifier.
static int[]	convertEnumNameToValue(int tid, java.lang.String[] in, int[] out) Converts namess in an Enumeration Datatype to values.
static java.lang.String[]	convertEnumValueToName(int tid, java.lang.Object inValues, java.lang.String[] outNames) Converts values in an Enumeration Datatype to names.
void	fromNative(int tid) Set datatype characteristics (class, size, byte order and sign) from a given datatye identifier.
java.lang.String	getDatatypeDescription() Returns a short text description of this datatype.
static java.lang.String	getDatatypeDescription(int tid) Returns a short description of a given datatype ID.
static int	getDatatypeSize(int tid) Returns the size (in bytes) of a given datatype identifier.
java.util.List	getMetadata() Retrieves the metadata such as attributes from file.
java.util.List	getMetadata(int... attrPropList)
boolean	hasAttribute() Check if the object has any attributes attached.
boolean	isUnsigned() Checks if this datatype is an unsigned integer.
static boolean	isUnsigned(int datatype) Checks if a datatype specified by the identifier is an unsigned integer.
int	open() Opens access to a named datatype.
void	removeMetadata(java.lang.Object info) Deletes an existing metadata from this data object.
int	toNative() Converts the datatype object to a native datatype.
static int	toNative(int tid) Deprecated. Not for public use in the future. Using H5.H5Tget_native_type(int) Return the HDF5 memory datatype identifier based on the HDF5 datatype identifier on disk
void	writeMetadata(java.lang.Object info) Writes a specific metadata (such as attribute) into file.

Methods inherited from class ncsa.hdf.object.Datatype

getBasetype, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, setEnumMembers

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

Field Detail

serialVersionUID

public static final long serialVersionUID

See Also:

HObject.serialVersionUID, Constant Field Values

Constructor Detail

H5Datatype

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

Constructs an named HDF5 data type object for a given file, dataset name and group path.

The datatype object represents an existing named datatype in file. For example, new H5Datatype(file, "dtype1", "/g0") constructs a datatype object that corresponds to the dataset,"dset1", at group "/g0".

Parameters:

theFile - the file that contains the dataset.

name - the name of the dataset such as "dset1".

path - the group path to the dataset such as "/g0/".

H5Datatype

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

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

H5Datatype

public H5Datatype(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

H5Datatype

public H5Datatype(int nativeID)

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:

nativeID - the native datatype identifier.

See Also:

fromNative(int nativeID)

Method Detail

hasAttribute

public boolean hasAttribute()

Description copied from interface: DataFormat

Check if the object has any attributes attached.

Returns:

true if it has any attribute(s), false otherwise.

convertEnumValueToName

public static final java.lang.String[] convertEnumValueToName(int tid,
                                                              java.lang.Object inValues,
                                                              java.lang.String[] outNames)
                                                       throws HDF5Exception

Converts values in an Enumeration Datatype to names.

This method searches the identified enumeration datatype for the values appearing in inValues and returns the names corresponding to those values. If a given value is not found in the enumeration datatype, the name corresponding to that value will be set to null in the string array that is returned.

If the method fails in general, null will be returned instead of a String array. An empty inValues parameter, an outNames array with a different number of entries than the inValues array, or an invalid tid would all cause general failure.

Parameters:

tid - The identifier of the enumeration datatype.

inValues - The array of enumerations values to be converted.

outNames - The array of names to be populated. If null, the array will be created. If outNames is not null, the number of entries must be the same as the number of values in inValues.

Returns:

The string array of names if successful; otherwise return null.

Throws:

HDF5Exception - If there is an error at the HDF5 library level.

convertEnumNameToValue

public static final int[] convertEnumNameToValue(int tid,
                                                 java.lang.String[] in,
                                                 int[] out)
                                          throws HDF5Exception

Converts namess in an Enumeration Datatype to values.

This method searches the identified enumeration datatype for the names appearing in inValues and returns the values corresponding to those names.

Parameters:

tid - The identifier of the enumeration datatype.

in - The array of enumerations names to be converted.

out - The array of values to be populated.

Returns:

The int array of values if successful; otherwise return null.

Throws:

HDF5Exception - If there is an error at the HDF5 library level.

fromNative

public void fromNative(int tid)

Description copied from class: Datatype

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);

Specified by:

fromNative in class Datatype

Parameters:

tid - the datatype identifier.

toNative

@Deprecated
public static int toNative(int tid)

Deprecated. Not for public use in the future.
Using H5.H5Tget_native_type(int)

Return the HDF5 memory datatype identifier based on the HDF5 datatype identifier on disk

Parameters:

tid - the datatype identifieron disk.

Returns:

the memory datatype identifier if successful, and negative otherwise.

toNative

public int toNative()

Description copied from class: Datatype

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);
 

Specified by:

toNative in class Datatype

Returns:

the identifier of the native datatype.

allocateArray

public static java.lang.Object allocateArray(int tid,
                                             int size)
                                      throws java.lang.OutOfMemoryError

Allocates an one-dimensional array of byte, short, int, long, float, double, or String to store data in memory. For example,

 int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_INT32);
 int[] data = (int[]) allocateArray(tid, 100);
 

returns a 32-bit integer array of size 100.

Parameters:

tid - the datatype id.

size - the total number of data points of the array.

Returns:

the array object if successful; otherwise, return null.

Throws:

java.lang.OutOfMemoryError

getDatatypeSize

public static final int getDatatypeSize(int tid)

Returns the size (in bytes) of a given datatype identifier.

It basically just calls H5Tget_size(tid).

Parameters:

tid - The datatype identifier.

Returns:

The size of the datatype in bytes.

See Also:

H5.H5Tget_size(int)

getDatatypeDescription

public java.lang.String getDatatypeDescription()

Description copied from class: Datatype

Returns a short text description of this datatype.

Overrides:

getDatatypeDescription in class Datatype

Returns:

a short text description of this datatype

getDatatypeDescription

public static final java.lang.String getDatatypeDescription(int tid)

Returns a short description of a given datatype ID.

Parameters:

tid - the HDF5 datatype identifier

Returns:

a string describing the data type.

isUnsigned

public boolean isUnsigned()

Description copied from class: Datatype

Checks if this datatype is an unsigned integer.

Specified by:

isUnsigned in class Datatype

Returns:

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

isUnsigned

public static final boolean isUnsigned(int datatype)

Checks if a datatype specified by the identifier is an unsigned integer.

Parameters:

datatype - the datatype ID to be checked.

Returns:

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

open

public int open()

Opens access to a named datatype.

It calls H5.H5Topen(loc, name).

Overrides:

open in class Datatype

Returns:

the datatype identifier if successful; otherwise returns negative value.

See Also:

H5.H5Topen(int, String)

close

public void close(int tid)

Closes a datatype identifier.

It calls H5.H5close(tid).

Specified by:

close in class Datatype

Parameters:

tid - the datatype ID to close

getMetadata

public java.util.List getMetadata()
                           throws HDF5Exception

Description copied from interface: DataFormat

Retrieves the metadata such as attributes from file.

Metadata such as attributes are stored in a List.

Specified by:

getMetadata in interface DataFormat

Overrides:

getMetadata in class Datatype

Returns:

the list of metadata objects.

Throws:

HDF5Exception

getMetadata

public java.util.List getMetadata(int... attrPropList)
                           throws HDF5Exception

Throws:

HDF5Exception

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.

Specified by:

writeMetadata in interface DataFormat

Overrides:

writeMetadata in class Datatype

Parameters:

info - the metadata to write.

Throws:

java.lang.Exception

removeMetadata

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

Description copied from interface: DataFormat

Deletes an existing metadata from this data object.

Specified by:

removeMetadata in interface DataFormat

Overrides:

removeMetadata in class Datatype

Parameters:

info - the metadata to delete.

Throws:

HDF5Exception