Class Datatype

java.lang.Object
ncsa.hdf.object.HObject
ncsa.hdf.object.Datatype
All Implemented Interfaces:
Serializable, DataFormat

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 datatype. "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. The values of the CLASS member are not identical to HDF5 values for a datatype class

Version:
1.1 9/4/2007
Author:
Peter X. Cao
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Datatype
    The base datatype of every element of the array (for CLASS_ARRAY datatype).
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    protected int
    The class of the datatype.
    protected int
    The byte order of the datatype.
    protected int
    The sign of the datatype.
    protected int
    The size (in bytes) of the datatype.
    protected long[]
     
    protected String
    The (name, value) pairs of enum members
    static final int
    The default definition for datatype size, order, and sign.
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
    static final int
    See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}

    Fields inherited from class ncsa.hdf.object.HObject

    fileFormat, linkTargetObjName, oid, separator
  • Constructor Summary

    Constructors
    Constructor
    Description
    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.
    Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase)
    Constructs a Datatype with specified class, size, byte order and sign.
    Datatype(FileFormat theFile, String name, String path)
    Constructs a named datatype with a given file, name and path.
    Datatype(FileFormat theFile, String name, String path, long[] oid)
    Deprecated.
    Not for public use in the future.
    Using Datatype(FileFormat, String, String)
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    Returns the datatype of array element for ARRAY datatype.
    int
    Returns the class of the datatype.
    Returns a short text description of this datatype.
    int
    Returns the byte order of the datatype.
    int
    Returns the sign (SIGN_NONE, SIGN_2 or NSGN) of an integer datatype.
    int
    Returns the size of the datatype in bytes.
    final String
    Returns the "name=value" pairs of enum members for enum datatype.
    Retrieves the metadata such as attributes from file.
    abstract boolean
    Checks if this datatype is an unsigned integer.
    int
    Opens access to this named datatype.
    void
    Deletes an existing metadata from this data object.
    final void
    Sets the (name, value) pairs of enum members for enum datatype.
    abstract int
    Converts the datatype object to a native datatype.
    void
    Updates an existing metadata from this data object.
    void
    Writes a specific metadata (such as attribute) into file.

    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 Details

    • NATIVE

      public static final int NATIVE
      The default definition for datatype size, order, and sign.
      See Also:
    • CLASS_NO_CLASS

      public static final int CLASS_NO_CLASS
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_INTEGER

      public static final int CLASS_INTEGER
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_FLOAT

      public static final int CLASS_FLOAT
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_CHAR

      public static final int CLASS_CHAR
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_STRING

      public static final int CLASS_STRING
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_BITFIELD

      public static final int CLASS_BITFIELD
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_OPAQUE

      public static final int CLASS_OPAQUE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_COMPOUND

      public static final int CLASS_COMPOUND
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_REFERENCE

      public static final int CLASS_REFERENCE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_ENUM

      public static final int CLASS_ENUM
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_VLEN

      public static final int CLASS_VLEN
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_ARRAY

      public static final int CLASS_ARRAY
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • CLASS_TIME

      public static final int CLASS_TIME
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • ORDER_LE

      public static final int ORDER_LE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • ORDER_BE

      public static final int ORDER_BE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • ORDER_VAX

      public static final int ORDER_VAX
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • ORDER_NONE

      public static final int ORDER_NONE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • SIGN_NONE

      public static final int SIGN_NONE
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • SIGN_2

      public static final int SIGN_2
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • NSGN

      public static final int NSGN
      See {@link <a href="http://hdfgroup.org/HDF5/doc/UG/index.html">HDF5 User's Guide}
      See Also:
    • 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 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 Details

    • Datatype

      public Datatype(FileFormat theFile, String name, 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, String name, 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 tclass, int tsize, int torder, int tsign, Datatype tbase)
      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
      tbase - the base datatype of the new datatype
    • 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:
  • Method Details

    • 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 integer, 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(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 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 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:
    • 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 List getMetadata() throws 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:
      Exception
    • writeMetadata

      public void writeMetadata(Object info) throws 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:
      Exception
    • removeMetadata

      public void removeMetadata(Object info) throws Exception
      Description copied from interface: DataFormat
      Deletes an existing metadata from this data object.
      Parameters:
      info - the metadata to delete.
      Throws:
      Exception
    • updateMetadata

      public void updateMetadata(Object info) throws Exception
      Description copied from interface: DataFormat
      Updates an existing metadata from this data object.
      Parameters:
      info - the metadata to update.
      Throws:
      Exception