public class Attribute extends Dataset implements DataFormat, CompoundDataFormat
Like a dataset, an attribute has a name, datatype and dataspace.
For more details on attributes, HDF5 User's Guide
The following code is an example of an attribute with 1D integer array of two elements.
// Example of creating a new attribute // The name of the new attribute String name = "Data range"; // Creating an unsigned 1-byte integer datatype Datatype type = new Datatype(Datatype.CLASS_INTEGER, // class 1, // size in bytes Datatype.ORDER_LE, // byte order Datatype.SIGN_NONE); // signed or unsigned // 1-D array of size two long[] dims = {2}; // The value of the attribute int[] value = {0, 255}; // Create a new attribute Attribute dataRange = new Attribute(name, type, dims); // Set the attribute value dataRange.setValue(value); // See FileFormat.writeAttribute() for how to attach an attribute to an object, @see hdf.object.FileFormat#writeAttribute(HObject, Attribute, boolean)For an atomic datatype, the value of an Attribute will be a 1D array of integers, floats and strings. For a compound datatype, it will be a 1D array of strings with field members separated by a comma. For example, "{0, 10.5}, {255, 20.0}, {512, 30.0}" is a compound attribute of {int, float} of three data points.
Datatype
,
Serialized FormModifier and Type | Field and Description |
---|---|
protected boolean[] |
isMemberSelected
The array to store flags to indicate if a member of this compound attribute
is selected for read/write.
|
protected boolean |
isScalar
Flag to indicate if the attribute data is a single scalar point
|
protected Object[] |
memberDims
The dimension sizes of each member.
|
protected String[] |
memberNames
The names of the members of the compound attribute.
|
protected int[] |
memberOrders
Array containing the total number of elements of the members of this compound
attribute.
|
protected Datatype[] |
memberTypes
The datatypes of the compound attribute's members.
|
protected int |
numberOfMembers
The number of members of the compound attribute.
|
protected HObject |
parentObject
The HObject to which this Attribute is attached
|
protected boolean |
unsignedConverted
Flag to indicate is the original unsigned C data is converted.
|
chunkSize, compression, compression_gzip_txt, convertByteToString, convertedBuf, data, datatype, dimNames, dims, filters, inited, isDataLoaded, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, startDims, storage, storage_layout
fileFormat, linkTargetObjName, oid, separator
Constructor and Description |
---|
Attribute(HObject parentObj,
String attrName,
Datatype attrType,
long[] attrDims)
Create an attribute with specified name, data type and dimension sizes.
|
Attribute(HObject parentObj,
String attrName,
Datatype attrType,
long[] attrDims,
Object attrValue)
Create an attribute with specific name and value.
|
Modifier and Type | Method and Description |
---|---|
void |
clearData()
Clears the current data buffer in memory and forces the next read() to load
the data from file.
|
void |
close(long aid)
Closes access to the object.
|
Object |
convertFromUnsignedC()
Converts the data values of this Attribute to appropriate Java integers if
they are unsigned integers.
|
Object |
convertToUnsignedC()
Converts Java integer data values of this Attribute back to unsigned C-type
integer data if they are unsigned integers.
|
Dataset |
copy(Group pgroup,
String name,
long[] dims,
Object data)
Creates a new dataset and writes the data buffer to the new dataset.
|
boolean |
equals(HObject obj)
Returns whether this Attribute is equal to the specified HObject by comparing
various properties.
|
Datatype |
getDatatype()
Returns the datatype of the data object.
|
Object |
getFillValue()
Returns the fill values for the data object.
|
int |
getMemberCount()
Returns the number of members of the compound attribute.
|
int[] |
getMemberDims(int i)
Returns the dimension sizes of the i-th member.
|
String[] |
getMemberNames()
Returns the names of the members of the compound attribute.
|
int[] |
getMemberOrders()
Returns array containing the total number of elements of the members of the
compound attribute.
|
Datatype[] |
getMemberTypes()
Returns an array of datatype objects of compound members.
|
List |
getMetadata()
Retrieves the object's metadata, such as attributes, from the file.
|
HObject |
getParentObject()
Returns the HObject to which this Attribute is currently "attached".
|
Object |
getProperty(String key)
get a property for a given key.
|
Collection<String> |
getPropertyKeys()
get all property keys.
|
int |
getSelectedMemberCount()
Returns the number of selected members of the compound attribute.
|
int[] |
getSelectedMemberOrders()
Returns array containing the total number of elements of the selected members
of the compound attribute.
|
Datatype[] |
getSelectedMemberTypes()
Returns an array of datatype objects of selected compound members.
|
boolean |
hasAttribute()
Check if the object has any attributes attached.
|
void |
init() |
boolean |
isMemberSelected(int idx)
Checks if a member of the compound attribute is selected for read/write.
|
boolean |
isScalar() |
long |
open()
Opens an existing object such as a dataset or group for access.
|
Object |
read()
Reads the data from file.
|
byte[] |
readBytes()
Reads the raw data of the dataset from file to a byte array.
|
void |
removeMetadata(Object metadata)
Deletes an existing piece of metadata from this object.
|
void |
selectMember(int idx)
Selects the i-th member for read/write.
|
void |
setAllMemberSelection(boolean selectAll)
Selects/deselects all members.
|
void |
setParentObject(HObject pObj)
Sets the HObject to which this Attribute is "attached".
|
void |
setProperty(String key,
Object value)
set a property for the attribute.
|
String |
toString(String delimiter)
Returns a string representation of the data value of the attribute.
|
String |
toString(String delimiter,
int maxItems)
Returns a string representation of the data value of the attribute.
|
void |
updateMetadata(Object metadata)
Updates an existing piece of metadata attached to this object.
|
void |
write(Object buf)
Writes a memory buffer to the object in the file.
|
void |
writeMetadata(Object metadata)
Writes a specific piece of metadata (such as an attribute) into the file.
|
byteToString, clear, convertFromUnsignedC, convertFromUnsignedC, convertToUnsignedC, convertToUnsignedC, getChunkSize, getCompression, getConvertByteToString, getData, getDimNames, getDims, getFilters, getHeight, getMaxDims, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSize, getStartDims, getStorage, getStorageLayout, getStride, getVirtualFilename, getVirtualMaps, getWidth, isInited, isString, isVirtual, setConvertByteToString, setData, stringToByte, write
debug, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, setLinkTargetObjName, setName, setPath, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getCompression, getData, getDims, getHeight, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getStartDims, getStride, getWidth, isInited, setData, write
protected HObject parentObject
protected boolean unsignedConverted
protected final boolean isScalar
protected int numberOfMembers
protected String[] memberNames
protected int[] memberOrders
For example, a compound attribute COMP has members of A, B and C as
COMP { int A; float B[5]; double C[2][3]; }memberOrders is an integer array of {1, 5, 6} to indicate that member A has one element, member B has 5 elements, and member C has 6 elements.
protected Object[] memberDims
The i-th element of the Object[] is an integer array (int[]) that contains the dimension sizes of the i-th member.
protected Datatype[] memberTypes
protected boolean[] isMemberSelected
If a member is selected, the read/write will perform on the member. Applications such as HDFView will only display the selected members of the compound attribute.
For example, if a compound attribute has four members String[] memberNames = {"X", "Y", "Z", "TIME"}; and boolean[] isMemberSelected = {true, false, false, true}; members "X" and "TIME" are selected for read and write.
public Attribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims)
The following example creates a string attribute with the name "CLASS" and value "IMAGE".
long[] attrDims = { 1 }; String attrName = "CLASS"; String[] classValue = { "IMAGE" }; Datatype attrType = new H5Datatype(Datatype.CLASS_STRING, classValue[0].length() + 1, -1, -1); Attribute attr = new Attribute(attrName, attrType, attrDims); attr.setValue(classValue);
parentObj
- the HObject to which this Attribute is attached.attrName
- the name of the attribute.attrType
- the datatype of the attribute.attrDims
- the dimension sizes of the attribute, null for scalar attributeDatatype
public Attribute(HObject parentObj, String attrName, Datatype attrType, long[] attrDims, Object attrValue)
The following example creates a string attribute with the name "CLASS" and value "IMAGE".
long[] attrDims = { 1 }; String attrName = "CLASS"; String[] classValue = { "IMAGE" }; Datatype attrType = new H5Datatype(Datatype.CLASS_STRING, classValue[0].length() + 1, -1, -1); Attribute attr = new Attribute(attrName, attrType, attrDims, classValue);
parentObj
- the HObject to which this Attribute is attached.attrName
- the name of the attribute.attrType
- the datatype of the attribute.attrDims
- the dimension sizes of the attribute, null for scalar attributeattrValue
- the value of the attribute, null if no valueDatatype
public long open()
HObject
open
in class HObject
HObject.close(long)
public void close(long aid)
HObject
Sub-classes must implement this interface because different data objects have their own ways of how the data resources are closed.
For example, H5Group.close() calls the hdf.hdf5lib.H5.H5Gclose() method and closes the group resource specified by the group id.
public void init()
init
in interface DataFormat
public HObject getParentObject()
public void setParentObject(HObject pObj)
pObj
- the new HObject to which this Attribute is "attached".public Object convertFromUnsignedC()
convertFromUnsignedC
in interface DataFormat
Dataset.convertToUnsignedC(Object)
,
Dataset.convertFromUnsignedC(Object, Object)
public Object convertToUnsignedC()
convertToUnsignedC
in interface DataFormat
Dataset.convertToUnsignedC(Object)
,
Dataset.convertToUnsignedC(Object, Object)
,
Dataset.convertFromUnsignedC(Object data_in)
public Object getFillValue()
DataFormat
getFillValue
in interface DataFormat
public void clearData()
Dataset
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.
clearData
in interface DataFormat
clearData
in class Dataset
Dataset.getData()
,
DataFormat.read()
public void setProperty(String key, Object value)
key
- the attribute Map keyvalue
- the attribute Map valuepublic Object getProperty(String key)
key
- the attribute Map keypublic Collection<String> getPropertyKeys()
public boolean isScalar()
public Object read() throws Exception, OutOfMemoryError
DataFormat
read() reads the data from file to a memory buffer and returns the memory buffer. The dataset object does not hold the memory buffer. To store the memory buffer in the dataset object, one must call getData().
By default, the whole dataset is read into memory. Users can also select a subset to read. Subsetting is done in an implicit way.
read
in interface DataFormat
Exception
- if object can not be readOutOfMemoryError
- if memory is exhaustedDataFormat.getData()
public void write(Object buf) throws Exception
DataFormat
write
in interface DataFormat
buf
- the data to writeException
- if data can not be writtenpublic int getMemberCount()
getMemberCount
in interface CompoundDataFormat
public int getSelectedMemberCount()
For example, in a compound datatype of {int A, float B, char[] C}, users can choose to retrieve only {A, C} from the attribute. In this case, getSelectedMemberCount() returns two.
getSelectedMemberCount
in interface CompoundDataFormat
public String[] getMemberNames()
For example, for a compound datatype of {int A, float B, char[] C} getMemberNames() returns ["A", "B", "C"}.
getMemberNames
in interface CompoundDataFormat
public boolean isMemberSelected(int idx)
isMemberSelected
in interface CompoundDataFormat
idx
- the index of compound member.public void selectMember(int idx)
selectMember
in interface CompoundDataFormat
idx
- the index of compound member.public void setAllMemberSelection(boolean selectAll)
setAllMemberSelection
in interface CompoundDataFormat
selectAll
- The indicator to select or deselect all members. If true, all
members are selected for read/write. If false, no member is
selected for read/write.public int[] getMemberOrders()
For example, a compound attribute COMP has members of A, B and C as
COMP { int A; float B[5]; double C[2][3]; }getMemberOrders() will return an integer array of {1, 5, 6} to indicate that member A has one element, member B has 5 elements, and member C has 6 elements.
getMemberOrders
in interface CompoundDataFormat
public int[] getSelectedMemberOrders()
For example, a compound attribute COMP has members of A, B and C as
COMP { int A; float B[5]; double C[2][3]; }If A and B are selected, getSelectedMemberOrders() returns an array of {1, 5}
getSelectedMemberOrders
in interface CompoundDataFormat
public int[] getMemberDims(int i)
For example, a compound attribute COMP has members of A, B and C as
COMP { int A; float B[5]; double C[2][3]; }getMemberDims(2) returns an array of {2, 3}, while getMemberDims(1) returns an array of {5}, and getMemberDims(0) returns null.
getMemberDims
in interface CompoundDataFormat
i
- the i-th memberpublic Datatype[] getMemberTypes()
Each member of a compound attribute has its own datatype. The datatype of a member can be atomic or other compound datatype (nested compound). The datatype objects are setup at init().
getMemberTypes
in interface CompoundDataFormat
public Datatype[] getSelectedMemberTypes()
getSelectedMemberTypes
in interface CompoundDataFormat
public List getMetadata() throws Exception
MetaDataContainer
Metadata, such as attributes, is stored in a List.
getMetadata
in interface MetaDataContainer
Exception
- if the metadata can not be retrievedpublic void writeMetadata(Object metadata) throws Exception
MetaDataContainer
writeMetadata
in interface MetaDataContainer
metadata
- the metadata to write.Exception
- if the metadata can not be writtenpublic void removeMetadata(Object metadata) throws Exception
MetaDataContainer
removeMetadata
in interface MetaDataContainer
metadata
- the metadata to delete.Exception
- if the metadata can not be removedpublic void updateMetadata(Object metadata) throws Exception
MetaDataContainer
updateMetadata
in interface MetaDataContainer
metadata
- the metadata to update.Exception
- if the metadata can not be updatedpublic boolean hasAttribute()
MetaDataContainer
hasAttribute
in interface MetaDataContainer
public final Datatype getDatatype()
DataFormat
getDatatype
in interface DataFormat
getDatatype
in class Dataset
public byte[] readBytes() throws Exception
Dataset
readBytes() reads raw data to an array of bytes instead of array of its datatype. For example, for a one-dimension 32-bit integer dataset of size 5, readBytes() returns a byte array of size 20 instead of an int array of 5.
readBytes() can be used to copy data from one dataset to another efficiently because the raw data is not converted to its native type, it saves memory space and CPU time.
public Dataset copy(Group pgroup, String name, long[] dims, Object data) throws Exception
Dataset
This function allows applications to create a new dataset for a given data buffer. For example, users can select a specific interesting part from a large image and create a new image with the selection.
The new dataset retains the datatype and dataset creation properties of this dataset.
copy
in class Dataset
pgroup
- the group which the dataset is copied to.name
- the name of the new dataset.dims
- the dimension sizes of the the new dataset.data
- the data values of the subset to be copied.Exception
- if dataset can not be copiedpublic boolean equals(HObject obj)
public String toString(String delimiter)
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.
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.public String toString(String delimiter, int maxItems)
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.
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 returnCopyright © 2018. All Rights Reserved.