Class Datatype

  • All Implemented Interfaces:
    java.io.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:
    Serialized Form
    • 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

        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:
        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 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​(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
      • updateMetadata

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