Package hdf.object

Class Datatype

  • All Implemented Interfaces:
    MetaDataContainer, Serializable
    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

    • Constructor Detail

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

      • Datatype

        public Datatype​(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:
        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 Detail

      • 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

      • 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

      • 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.