Module org.hdfgroup.object
Package hdf.object

Class Datatype

Object
hdf.object.HObject
hdf.object.Datatype
All Implemented Interfaces:
MetaDataContainer, Serializable
Direct Known Subclasses:
FitsDatatype, H4Datatype, H5Datatype, NC2Datatype
public abstract class Datatype
extends HObject
implements MetaDataContainer
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 characteristics are defined in the HDF5 User's Guide.

These characteristics 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, createNative() and fromNative(), are defined to convert the general characteristics to/from 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:
Serialized Form

  • Field Details

  • Constructor Details

    • Datatype

      public Datatype​(FileFormat theFile, String typeName, String typePath)
      Constructs a named datatype with a given file, name and path.
      Parameters:
      theFile - the HDF file.
      typeName - the name of the datatype, e.g "12-bit Integer".
      typePath - the full group path of the datatype, e.g. "/datatypes/".

    • Datatype

      @Deprecated public Datatype​(FileFormat theFile, String typeName, String typePath, long[] oid)
      Deprecated.
      Not for public use in the future.
      Using Datatype(FileFormat, String, String)
      Parameters:
      theFile - the HDF file.
      typeName - the name of the datatype, e.g "12-bit Integer".
      typePath - the full group path of the datatype, e.g. "/datatypes/".
      oid - the oidof the datatype.

    • Datatype

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

      The following is a list of a few examples of Datatype.

      1. to create unsigned native integer
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value.
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      Throws:
      Exception - if there is an error

    • Datatype

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

      The following is a list of a few examples of Datatype.

      1. to create unsigned native integer
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value.
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      tbase - the base datatype of the new datatype
      Throws:
      Exception - if there is an error

    • Datatype

      public Datatype​(FileFormat theFile, int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase) throws Exception
      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few examples of Datatype.

      1. to create unsigned native integer
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      Parameters:
      theFile - the HDF file.
      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. Valid values are NATIVE or a positive value.
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      tbase - the base datatype of the new datatype
      pbase - the parent datatype of the new datatype
      Throws:
      Exception - if there is an error

    • Datatype

      public Datatype​(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase) throws Exception
      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few examples of Datatype.

      1. to create unsigned native integer
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        Datatype type = new Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        Datatype type = new Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value.
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      tbase - the base datatype of the new datatype
      pbase - the parent datatype of the new datatype
      Throws:
      Exception - if there is an error

    • Datatype

      public Datatype​(FileFormat theFile, long tid) throws Exception
      Constructs a Datatype with a given native datatype identifier.

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

       long 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:
      theFile - the HDF file.
      tid - the native datatype identifier.
      Throws:
      Exception - if there is an error
      See Also:
      fromNative(long tid)

    • Datatype

      public Datatype​(FileFormat theFile, long tid, Datatype pbase) throws Exception
      Constructs a Datatype with a given native datatype identifier.

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

       long 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:
      theFile - the HDF file.
      tid - the native datatype identifier.
      pbase - the parent datatype of the new datatype
      Throws:
      Exception - if there is an error
      See Also:
      fromNative(long tid)

  • Method Details

    • open

      public long open()
      Opens access to this named datatype. Sub-classes 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(long)

    • close

      public abstract void close​(long id)
      Closes a datatype identifier.

      Sub-classes must replace this default implementation.

      Specified by:
      close in class HObject
      Parameters:
      id - the datatype identifier to close.

    • 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 long 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) of an integer datatype.
      Returns:
      the sign of the datatype.

    • getDatatypeBase

      public Datatype getDatatypeBase()
      Returns the base datatype for this datatype.

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

      Returns:
      the datatype of the contained basetype.

    • setEnumMembers

      public final void setEnumMembers​(String enumStr)
      Sets the (key, value) pairs of enum members for enum datatype.

      For Example,

      setEnumMembers("-40=lowTemp, 90=highTemp")
      sets the key of enum member lowTemp to -40 and highTemp to 90.
      setEnumMembers("lowTemp, highTemp")
      sets enum members to defaults, i.e. 0=lowTemp and 1=highTemp
      setEnumMembers("10=lowTemp, highTemp")
      sets enum member lowTemp to 10 and highTemp to 11.
      Parameters:
      enumStr - the (key, value) pairs of enum members

    • getEnumMembers

      public final Map<String,​String> getEnumMembers()
      Returns the Map<String,String> pairs of enum members for enum datatype.
      Returns:
      enumStr Map<String,String%gt; pairs of enum members

    • getEnumMembersAsString

      public final String getEnumMembersAsString()
      Returns the HashMap pairs of enum members for enum datatype.

      For Example,

      getEnumMembersAsString()
      returns "10=lowTemp, 40=highTemp"
      Returns:
      enumStr the (key, value) pairs of enum members

    • getArrayDims

      public final long[] getArrayDims()
      Returns the dimensions of an Array Datatype.
      Returns:
      dims the dimensions of the Array Datatype

    • getCompoundMemberNames

      public final List<String> getCompoundMemberNames()

    • getCompoundMemberTypes

      public final List<Datatype> getCompoundMemberTypes()

    • createNative

      public abstract long createNative()
      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.createNative();
      The "tid" will be the HDF5 datatype id of a 64-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​(long nativeID)
      Set datatype characteristics (class, size, byte order and sign) from a given datatype identifier.

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

      For example, if the type identifier is a 64-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.

    • getDescription

      public String getDescription()
      Returns a short text description of this datatype.
      Returns:
      a short text description of this datatype

    • isUnsigned

      public boolean isUnsigned()
      Checks if this datatype is unsigned.
      Returns:
      true if the datatype is unsigned; otherwise, returns false.

    • isText

      public abstract boolean isText()

    • isInteger

      public boolean isInteger()
      Checks if this datatype is an integer type.
      Returns:
      true if the datatype is integer; false otherwise

    • isFloat

      public boolean isFloat()
      Checks if this datatype is a floating-point type.
      Returns:
      true if the datatype is floating-point; false otherwise

    • isNamed

      public boolean isNamed()
      Checks if this datatype is a named type.
      Returns:
      true if the datatype is named; false otherwise

    • isVarStr

      public boolean isVarStr()
      Checks if this datatype is a variable-length string type.
      Returns:
      true if the datatype is variable-length string; false otherwise

    • isVLEN

      public boolean isVLEN()
      Checks if this datatype is a variable-length type.
      Returns:
      true if the datatype is variable-length; false otherwise

    • isCompound

      public boolean isCompound()
      Checks if this datatype is an compound type.
      Returns:
      true if the datatype is compound; false otherwise

    • isArray

      public boolean isArray()
      Checks if this datatype is an array type.
      Returns:
      true if the datatype is array; false otherwise

    • isString

      public boolean isString()
      Checks if this datatype is a string type.
      Returns:
      true if the datatype is string; false otherwise

    • isChar

      public boolean isChar()
      Checks if this datatype is a character type.
      Returns:
      true if the datatype is character; false otherwise

    • isRef

      public boolean isRef()
      Checks if this datatype is a reference type.
      Returns:
      true if the datatype is reference; false otherwise

    • isEnum

      public boolean isEnum()
      Checks if this datatype is a enum type.
      Returns:
      true if the datatype is enum; false otherwise

    • isOpaque

      public boolean isOpaque()
      Checks if this datatype is a opaque type.
      Returns:
      true if the datatype is opaque; false otherwise

    • isBitField

      public boolean isBitField()
      Checks if this datatype is a bitfield type.
      Returns:
      true if the datatype is bitfield; false otherwise

    • getMetadata

      public List getMetadata() throws Exception
      Description copied from interface: MetaDataContainer
      Retrieves the object's metadata, such as attributes, from the file.

      Metadata, such as attributes, is stored in a List.

      Specified by:
      getMetadata in interface MetaDataContainer
      Returns:
      the list of metadata objects.
      Throws:
      Exception - if the metadata can not be retrieved

    • writeMetadata

      public void writeMetadata​(Object info) throws Exception
      Description copied from interface: MetaDataContainer
      Writes a specific piece of metadata (such as an attribute) into the file. If an HDF(4&5) attribute exists in the file, this method updates its value. If the attribute does not exist in the file, it creates the attribute in the 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 the file, one needs to get the instance of the attribute by getMetadata(), change its values, then use writeMetadata() to write the value.
      Specified by:
      writeMetadata in interface MetaDataContainer
      Parameters:
      info - the metadata to write.
      Throws:
      Exception - if the metadata can not be written

    • removeMetadata

      public void removeMetadata​(Object info) throws Exception
      Description copied from interface: MetaDataContainer
      Deletes an existing piece of metadata from this object.
      Specified by:
      removeMetadata in interface MetaDataContainer
      Parameters:
      info - the metadata to delete.
      Throws:
      Exception - if the metadata can not be removed

    • updateMetadata

      public void updateMetadata​(Object info) throws Exception
      Description copied from interface: MetaDataContainer
      Updates an existing piece of metadata attached to this object.
      Specified by:
      updateMetadata in interface MetaDataContainer
      Parameters:
      info - the metadata to update.
      Throws:
      Exception - if the metadata can not be updated

    • toString

      public String toString()
      Description copied from class: HObject
      Returns the name of the object.

      This method overwrites the toString() method in the Java Object class (the root class of all Java objects) so that it returns the name of the HObject instead of the name of the class.

      For example, toString() returns "Raster Image #2" instead of "hdf.object.h4.H4SDS".

      Overrides:
      toString in class HObject
      Returns:
      The name of the object.