Module org.hdfgroup.object

Package hdf.object.h5

Class H5ReferenceType

Object

hdf.object.HObject

hdf.object.Datatype

hdf.object.h5.H5Datatype

hdf.object.h5.H5ReferenceType

All Implemented Interfaces:

MetaDataContainer, Serializable

public class H5ReferenceType
extends H5Datatype

This class defines HDF5 reference characteristics and APIs for a data type of H5T_STD_REF. This class provides convenient functions to access H5T_STD_REF type information.

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	H5ReferenceType.H5ReferenceData	The individual reference data for a given object.

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	inited	Flag to indicate if this dataset has been initialized
protected boolean	isDataLoaded	Flag to indicate if data values are loaded into memory.
protected Object	originalRefBuf	The data buffer that contains the raw data directly reading from file (before any data conversion).
protected ArrayList<H5ReferenceType.H5ReferenceData>	refdata	The memory buffer that holds the raw data array of the reference.
protected long	refsize	The current array size of the reference.

Fields inherited from class hdf.object.h5.H5Datatype

refdims

Fields inherited from class hdf.object.Datatype

arrayDims, baseType, CLASS_ARRAY, CLASS_BITFIELD, CLASS_CHAR, CLASS_COMPOUND, CLASS_ENUM, CLASS_FLOAT, CLASS_INTEGER, CLASS_NO_CLASS, CLASS_OPAQUE, CLASS_REFERENCE, CLASS_STRING, CLASS_TIME, CLASS_VLEN, compoundMemberNames, compoundMemberOffsets, compoundMemberTypes, datatypeClass, datatypeDescription, datatypeNATIVE, datatypeOrder, datatypeSign, datatypeSize, enumMembers, isNamed, isVariableStr, isVLEN, NATIVE, NSGN, ORDER_BE, ORDER_LE, ORDER_NONE, ORDER_VAX, SIGN_2, SIGN_NONE

Fields inherited from class hdf.object.HObject

fileFormat, linkTargetObjName, oid, SEPARATOR

Constructor Summary

Constructors

Constructor	Description
H5ReferenceType(int tclass, int tsize, int torder, int tsign)	Constructs a H5ReferenceType with specified class, size, byte order and sign.
H5ReferenceType(int tclass, int tsize, int torder, int tsign, Datatype tbase)	Constructs a H5ReferenceType with specified class, size, byte order and sign.
H5ReferenceType(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase)	Constructs a H5ReferenceType with specified class, size, byte order and sign.
H5ReferenceType(FileFormat theFile, long theSize, long nativeID)	Constructs a H5ReferenceType with a given native datatype identifier.
H5ReferenceType(FileFormat theFile, long theSize, long nativeID, Datatype pbase)	Constructs a H5ReferenceType with a given native datatype identifier.
H5ReferenceType(FileFormat theFile, String theName, String thePath)	Constructs an named HDF5 data type reference for a given file, dataset name and group path.
H5ReferenceType(FileFormat theFile, String theName, String thePath, long[] oid)	Deprecated. Not for public use in the future.

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears memory held by the reference, such as the data buffer.
void	clearData()	Clears the current data buffer in memory and forces the next read() to load the data from file.
Object	getData()	Returns the data buffer of the reference in memory.
final String	getFullReferenceName(byte[] refarr)	Get the reference datatype reference name.
final String	getObjectReferenceName(byte[] refarr)	Get the reference datatype reference name.
final H5ReferenceType.H5ReferenceData	getReferenceData(byte[] refarr)	Get the reference datatype data.
final String	getReferenceRegion(byte[] refarr, boolean showData)	Get the reference datatype region reference as string.
final long	getRefSize()	Returns the array size of the reference.
final String	getRegionDataset(byte[] refarr)	Get the reference datatype dataset region reference as string.
void	init()	Retrieves reference information from file into memory.
final boolean	isInited()	The status of initialization for this object
void	setData(Object theData)	setData() loads the reference raw data into the buffer.
void	setData(List theData)	setData() loads the reference raw data into the buffer.
final void	setRefSize(long current_size)	Sets the array size of the reference.
String	toString(String delimiter)	Returns a string representation of the data value.
String	toString(String delimiter, int maxItems)	Returns a string representation of the data value.
final void	write()	Writes the memory buffer of this reference to file.
static final boolean	zeroArrayCheck(byte[] refarr)	Checks if a reference datatype is all zero.

Methods inherited from class hdf.object.h5.H5Datatype

allocateArray, bigDecimalToByte, bigDecimalToByte, byteToBigDecimal, byteToBigDecimal, close, convertBigDecimalToByte, convertByteToBigDecimal, convertEnumNameToValue, convertEnumValueToName, createCompoundFieldType, createNative, descReferenceObject, descRegionDataset, extractCompoundInfo, fromNative, getDatatypeSize, getDescription, getMetadata, getMetadata, getNativeStrPad, getReferenceType, getToken, hasAttribute, isRefObj, isRegRef, isStdRef, isText, isUnsigned, open, removeMetadata, setFullname, setName, toNative, typeObjectRef, updateMetadata, writeMetadata

Methods inherited from class hdf.object.Datatype

getArrayDims, getCompoundMemberNames, getCompoundMemberOffsets, getCompoundMemberTypes, getDatatypeBase, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, getEnumMembersAsString, isArray, isBitField, isChar, isCompound, isEnum, isFloat, isInteger, isNamed, isOpaque, isRef, isString, isUnsigned, isVarStr, isVLEN, setEnumMembers, toString

Methods inherited from class hdf.object.HObject

createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, setLinkTargetObjName, setPath

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

refdata

protected transient ArrayList<H5ReferenceType.H5ReferenceData> refdata

The memory buffer that holds the raw data array of the reference.

isDataLoaded

protected boolean isDataLoaded

Flag to indicate if data values are loaded into memory.

inited

protected boolean inited

Flag to indicate if this dataset has been initialized

refsize

protected long refsize

The current array size of the reference.

originalRefBuf

protected transient Object originalRefBuf

The data buffer that contains the raw data directly reading from file (before any data conversion).

Constructor Details

H5ReferenceType

public H5ReferenceType(FileFormat theFile,
 String theName,
 String thePath)

Constructs an named HDF5 data type reference for a given file, dataset name and group path. The datatype object represents an existing named datatype in file. For example,

 new H5ReferenceType(file, "dset1", "/g0")
 

constructs a datatype object that corresponds to the dataset,"dset1", at group "/g0".

Parameters:

theFile - the file that contains the datatype.

theName - the name of the dataset such as "dset1".

thePath - the group path to the dataset such as "/g0/".

H5ReferenceType

@Deprecated
public H5ReferenceType(FileFormat theFile,
 String theName,
 String thePath,
 long[] oid)

Deprecated.

Not for public use in the future.
Using H5ReferenceType(FileFormat, String, String)

Parameters:

theFile - the file that contains the datatype.

theName - the name of the dataset such as "dset1".

thePath - the group path to the dataset such as "/g0/".

oid - the oid of the dataset.

H5ReferenceType

public H5ReferenceType(int tclass,
 int tsize,
 int torder,
 int tsign)
                throws Exception

Constructs a H5ReferenceType with specified class, size, byte order and sign.

Parameters:

tclass - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.

tsize - the size must be multiples H5T_STD_REF.

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

H5ReferenceType

public H5ReferenceType(int tclass,
 int tsize,
 int torder,
 int tsign,
 Datatype tbase)
                throws Exception

Constructs a H5ReferenceType with specified class, size, byte order and sign.

Parameters:

tclass - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.

tsize - the size must be multiples H5T_STD_REF.

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

H5ReferenceType

public H5ReferenceType(int tclass,
 int tsize,
 int torder,
 int tsign,
 Datatype tbase,
 Datatype pbase)
                throws Exception

Constructs a H5ReferenceType with specified class, size, byte order and sign.

Parameters:

tclass - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.

tsize - the size must be multiples H5T_STD_REF.

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

H5ReferenceType

public H5ReferenceType(FileFormat theFile,
 long theSize,
 long nativeID)
                throws Exception

Constructs a H5ReferenceType with a given native datatype identifier.

Parameters:

theFile - the file that contains the datatype.

theSize - the size must be multiples H5T_STD_REF.

nativeID - the native datatype identifier.

Throws:

Exception - if there is an error

See Also:

• H5Datatype.fromNative(long nativeID)

H5ReferenceType

public H5ReferenceType(FileFormat theFile,
 long theSize,
 long nativeID,
 Datatype pbase)
                throws Exception

Constructs a H5ReferenceType with a given native datatype identifier.

Parameters:

theFile - the file that contains the datatype.

theSize - the size is the number of H5ReferenceData data structs.

nativeID - the native datatype identifier.

pbase - the parent datatype of the new datatype

Throws:

Exception - if there is an error

See Also:

• H5Datatype.fromNative(long nativeID)

Method Details

clear

public void clear()

Clears memory held by the reference, such as the data buffer.

Specified by:

clear in interface MetaDataContainer

Overrides:

clear in class H5Datatype

write

public final void write()
                 throws Exception

Writes the memory buffer of this reference to file.

Throws:

Exception - if buffer can not be written

isInited

public final boolean isInited()

The status of initialization for this object

Returns:

true if the data has been initialized

setData

public void setData(List theData)

setData() loads the reference raw data into the buffer. This buffer will be accessed to get the reference strings and data. Once the references are destroyed, the refdata can only be used to retrieve existing data.

Parameters:

theData - the data to write.

setData

public void setData(Object theData)

setData() loads the reference raw data into the buffer. This buffer will be accessed to get the reference strings and data. Once the references are destroyed, the refdata can only be used to retrieve existing data.

Parameters:

theData - the data to write.

getData

public Object getData()
               throws Exception,
OutOfMemoryError

Returns the data buffer of the reference in memory. If data is already loaded into memory, returns the data; otherwise, calls read() to read data from file into a memory buffer and returns the memory buffer. By default, the whole reference is read into memory.

Returns:

the memory buffer of the reference.

Throws:

Exception - if object can not be read

OutOfMemoryError - if memory is exhausted

clearData

public void clearData()

Clears the current data buffer in memory and forces the next read() to load the data from file. The function read() loads data from file into memory only if the data is not read. If data is already in memory, read() just returns the memory buffer. Sometimes we want to force read() to re-read data from file. For example, when the selection is changed, we need to re-read the data.

See Also:

• getData()

getRefSize

public final long getRefSize()

Returns the array size of the reference.

Returns:

the array size of the reference.

setRefSize

public final void setRefSize(long current_size)

Sets the array size of the reference.

Parameters:

current_size - the array size of the current reference.

init

public void init()

Retrieves reference information from file into memory.

zeroArrayCheck

public static final boolean zeroArrayCheck(byte[] refarr)

Checks if a reference datatype is all zero.

Parameters:

refarr - the reference datatype data to be checked.

Returns:

true is the reference datatype data is all zero; otherwise returns false.

getObjectReferenceName

public final String getObjectReferenceName(byte[] refarr)

Get the reference datatype reference name.

Parameters:

refarr - the reference datatype data to be queried.

Returns:

the reference datatype name string, null otherwise.

getFullReferenceName

public final String getFullReferenceName(byte[] refarr)

Get the reference datatype reference name.

Parameters:

refarr - the reference datatype data to be queried.

Returns:

the reference datatype name string, null otherwise.

getRegionDataset

public final String getRegionDataset(byte[] refarr)

Get the reference datatype dataset region reference as string.

Parameters:

refarr - the reference datatype data to be queried.

Returns:

the reference datatype name string, null otherwise.

getReferenceData

public final H5ReferenceType.H5ReferenceData getReferenceData(byte[] refarr)

Get the reference datatype data.

Parameters:

refarr - the reference datatype data to be queried.

Returns:

the reference datatype data.

getReferenceRegion

public final String getReferenceRegion(byte[] refarr,
 boolean showData)

Get the reference datatype region reference as string.

Parameters:

refarr - the reference datatype data to be queried.

showData - show the reference region dims

Returns:

the reference datatype name string, null otherwise.

toString

public String toString(String delimiter)

Returns a string representation of the data value. For example, "0, 255". For a compound datatype, it will be a 1D array of strings with field members separated by the delimiter. For example, "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int, float} of three data points.

Parameters:

delimiter - The delimiter used to separate individual data points. It can be a comma, semicolon, tab or space. For example, toString(",") will separate data by commas.

Returns:

the string representation of the data values.

toString

public String toString(String delimiter,
 int maxItems)

Returns a string representation of the data value.

Parameters:

delimiter - The delimiter used to separate individual data points. It can be a comma, semicolon, tab or space. For example, toString(",") will separate data by commas.

maxItems - The maximum number of Array values to return

Returns:

the string representation of the data values.