Class Datatype
- java.lang.Object
-
- ncsa.hdf.object.HObject
-
- ncsa.hdf.object.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
-
-
Field Summary
Fields Modifier and Type Field Description protected Datatype
baseType
The base datatype of every element of the array (for CLASS_ARRAY datatype).static int
CLASS_ARRAY
See {@link HDF5 User's Guide}static int
CLASS_BITFIELD
See {@link HDF5 User's Guide}static int
CLASS_CHAR
See {@link HDF5 User's Guide}static int
CLASS_COMPOUND
See {@link HDF5 User's Guide}static int
CLASS_ENUM
See {@link HDF5 User's Guide}static int
CLASS_FLOAT
See {@link HDF5 User's Guide}static int
CLASS_INTEGER
See {@link HDF5 User's Guide}static int
CLASS_NO_CLASS
See {@link HDF5 User's Guide}static int
CLASS_OPAQUE
See {@link HDF5 User's Guide}static int
CLASS_REFERENCE
See {@link HDF5 User's Guide}static int
CLASS_STRING
See {@link HDF5 User's Guide}static int
CLASS_TIME
See {@link HDF5 User's Guide}static int
CLASS_VLEN
See {@link 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 membersstatic int
NATIVE
The default definition for datatype size, order, and sign.static int
NSGN
See {@link HDF5 User's Guide}static int
ORDER_BE
See {@link HDF5 User's Guide}static int
ORDER_LE
See {@link HDF5 User's Guide}static int
ORDER_NONE
See {@link HDF5 User's Guide}static int
ORDER_VAX
See {@link HDF5 User's Guide}static int
SIGN_2
See {@link HDF5 User's Guide}static int
SIGN_NONE
See {@link 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, 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.
UsingDatatype(FileFormat, String, String)
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods 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.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
updateMetadata(java.lang.Object info)
Updates an existing metadata from this data object.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 {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_INTEGER
public static final int CLASS_INTEGER
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_FLOAT
public static final int CLASS_FLOAT
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_CHAR
public static final int CLASS_CHAR
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_STRING
public static final int CLASS_STRING
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_BITFIELD
public static final int CLASS_BITFIELD
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_OPAQUE
public static final int CLASS_OPAQUE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_COMPOUND
public static final int CLASS_COMPOUND
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_REFERENCE
public static final int CLASS_REFERENCE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_ENUM
public static final int CLASS_ENUM
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_VLEN
public static final int CLASS_VLEN
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_ARRAY
public static final int CLASS_ARRAY
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
CLASS_TIME
public static final int CLASS_TIME
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
ORDER_LE
public static final int ORDER_LE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
ORDER_BE
public static final int ORDER_BE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
ORDER_VAX
public static final int ORDER_VAX
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
ORDER_NONE
public static final int ORDER_NONE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
SIGN_NONE
public static final int SIGN_NONE
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
SIGN_2
public static final int SIGN_2
See {@link HDF5 User's Guide}- See Also:
- Constant Field Values
-
NSGN
public static final int NSGN
See {@link 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.
UsingDatatype(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.
- to create unsigned native integer
H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE); - to create 16-bit signed integer with big endian
H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE); - to create native float
H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1); - 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_NONEtsign
- the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN
- to create unsigned native integer
-
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.
- to create unsigned native integer
H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE); - to create 16-bit signed integer with big endian
H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE); - to create native float
H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1); - 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_NONEtsign
- the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGNtbase
- the base datatype of the new datatype
- to create unsigned native integer
-
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 toint 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 classHObject
- 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.
-
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
-
-