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.