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:
  H4Datatype, H5Datatype

    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

Fields
`protected Datatype` `baseType` The base datatype of every element of the array (for CLASS_ARRAY datatype).
`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
`protected int` `datatypeClass` The class of the datatype.
`protected int` `datatypeOrder` The byte order of the datatype.
`protected int` `datatypeSign` The sign of the datatype.
`protected int` `datatypeSize` The size (in bytes) of the datatype.
`protected long[]` `dims`
`protected java.lang.String` `enumMembers` The (name, value) pairs of enum members
`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

`linkTargetObjName, oid, separator`

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`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

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

### Methods inherited from class java.lang.Object

`clone, equals, finalize, 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

#### datatypeClass

    protected int datatypeClass

The class of the datatype.

#### datatypeSize

    protected int datatypeSize

The size (in bytes) of the datatype.

#### datatypeOrder

    protected int datatypeOrder

The byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, and ORDER_VAX.

#### datatypeSign

    protected int datatypeSign

The sign of the datatype.

#### enumMembers

    protected java.lang.String enumMembers

The (name, value) pairs of enum members

#### baseType

    protected Datatype baseType

The base datatype of every element of the array (for CLASS_ARRAY datatype).

#### dims

    protected long[] dims

### 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`