com.pacbio.secondary.vis.io.hdf.file.hdf5

Class HDF5File

java.lang.Object

com.pacbio.secondary.vis.io.hdf.file.hdf5.HDF5File

Direct Known Subclasses:

BaseH5FileBase, CMPH5FileBase

public class HDF5File
extends java.lang.Object

Base class for accessing HDF5 files

Author:

mmilletti

Field Summary

Fields

Modifier and Type	Field and Description
protected H5File	hdf_file_format
protected H5Group	hdf_file_root_group
protected javax.swing.tree.DefaultMutableTreeNode	hdf_file_root_node
static int	MAX_NUM_CACHED_OBJECTS
static int	MAX_NUM_CACHED_OBJECTS_KINETOGRAM

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HDF5File(java.io.File file, int access, int num_cached_objects)

Method Summary

Methods

Modifier and Type	Method and Description
protected H5ScalarDS	createEmptyDataset(java.lang.String name, H5Group pGroup, H5Datatype data_type, long[] dims, long[] chunks) Creates empty scalar dataset of specific type.
H5ScalarDS	createFilledDataset(java.lang.String name, H5Group pGroup, H5Datatype data_type, long[] dims, long[] chunks, java.lang.Object data) Creates scalar dataset of specific type.
H5Group	createGroup(java.lang.String group_name, H5Group parent) Creates a new group under a parent group
void	dispose() this method must be called after using the file
protected java.util.List<?>	getAllAttributes(DataFormat data) returns all attributes in dataset or group
protected java.util.List<H5ScalarDS>	getAllChildDatasets(H5Group parent_group) Searches a parent group for all child datasets
protected java.util.List<H5Group>	getAllChildGroups(H5Group parent_group) Searches a parent group for all child groups
protected float[]	getAttributeFloatValues(DataFormat data, java.lang.String target_attribute_name) Returns array of floating point values from single named attribute
protected long[]	getAttributeLongValues(DataFormat data, java.lang.String target_attribute_name) Returns array of longs from single named attribute Use when HObject element has either int, uint or long attribute with multiple values
protected java.lang.String[]	getAttributeStringValues(DataFormat data, java.lang.String target_attribute_name) Returns array of strings from single named attribute Use when HObject element has a String attribute with multiple values
protected H5ScalarDS	getChildDataset(H5Group parent_group, java.lang.String child_dataset_name) Searches a parent group for a named child dataset
protected H5Group	getChildGroup(H5Group parent_group, java.lang.String child_group_name) Searches a parent group for a named child group
H5ScalarDS	getDataset(java.lang.String dataset_path) Searches for a dataset by fully qualified path
protected HDF5ChunkInfo	getDatasetChunkInfo(H5ScalarDS dataset) Gets chunking info, if chunking was used, of this datasets
HDF5HyperslabInfo	getDatasetHyperslabInfo(H5ScalarDS dataset) This method returns the default hyperslab selection parameters of the dataset.
boolean	getDataStreamFromDataset(H5ScalarDS dataset, long start_row, long end_row, StreamingDataConsumer consumer) Main method for random access streaming of data.
H5File	getFileHandle()
java.lang.String	getFilePath()
protected java.lang.Object	getGroup(java.lang.String group_path) Searches for a group by fully qualified path
protected java.lang.Object	getNamedRootObject(java.lang.String named_object) Searches for a named H5Group or H5ScalarDS object located on the root of the hdf5 hierarchy
protected UCharMatrixArray	getUCharDataChunk(H5ScalarDS dataset, HDF5HyperslabInfo info) Reads a chunk of UChar data from a dataset.
protected UIntMatrixArray	getUIntDataChunk(H5ScalarDS dataset, HDF5HyperslabInfo info) Reads a chunk of UInt data from a dataset.
protected java.lang.Object	readDatasetHyperslab(H5ScalarDS dataset, HDF5HyperslabInfo info) Reads the data from file to a memory buffer and returns the memory buffer.
protected java.lang.Object	readUnsignedDatasetHyperslab(H5ScalarDS dataset, HDF5HyperslabInfo info) A convenient but not memory-efficient method to read a hyperslab of unsigned integers.
protected void	testPrintDatasetInfo(H5ScalarDS dataset) test only method, dumps dataset info
java.lang.String	toString()
void	writeChunkToDataset(H5ScalarDS dataset, HDF5HyperslabInfo info, java.lang.Object data) Writes a block of data to the selected dataset.
boolean	writeStringAttribute(HObject h_object, java.lang.String attribute_name, java.lang.String value) Creates a new String attribute in the specified group or dataset and writes the passed in value.
boolean	writeUIntAttribute(HObject h_object, java.lang.String attribute_name, long value) Creates a new UInt attribute in the specified group or dataset and writes the passed in value

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

hdf_file_format

protected H5File hdf_file_format

hdf_file_root_node

protected javax.swing.tree.DefaultMutableTreeNode hdf_file_root_node

hdf_file_root_group

protected H5Group hdf_file_root_group

MAX_NUM_CACHED_OBJECTS

public static final int MAX_NUM_CACHED_OBJECTS

See Also:

Constant Field Values

MAX_NUM_CACHED_OBJECTS_KINETOGRAM

public static final int MAX_NUM_CACHED_OBJECTS_KINETOGRAM

See Also:

Constant Field Values

Constructor Detail

HDF5File

protected HDF5File(java.io.File file,
        int access,
        int num_cached_objects)
            throws HDF5ExceptionEx

Parameters:

file - name of HDF5 file

access - mode: FileFormat.READ, FileFormat.WRITE, FileFormat.CREATE

Throws:

java.io.FileNotFoundException

HDF5ExceptionEx

Method Detail

getNamedRootObject

protected java.lang.Object getNamedRootObject(java.lang.String named_object)

Searches for a named H5Group or H5ScalarDS object located on the root of the hdf5 hierarchy

Parameters:

named_object - name of object to find

Returns:

Returns either a H5Group or H5ScalarDS object. Null if object is not found

getGroup

protected java.lang.Object getGroup(java.lang.String group_path)

Searches for a group by fully qualified path

Parameters:

group_path - full path to group to search for

Returns:

the group if found, null otherwise

getDataset

public H5ScalarDS getDataset(java.lang.String dataset_path)

Searches for a dataset by fully qualified path

Parameters:

dataset_path - full path to dataset to search for

Returns:

the dataset if found, null otherwise

getChildGroup

protected H5Group getChildGroup(H5Group parent_group,
                    java.lang.String child_group_name)

Searches a parent group for a named child group

Parameters:

parent_group - the group to search for desired object

child_group_name - the name of child group to retrieve

Returns:

the child group if found, null otherwise

getChildDataset

protected H5ScalarDS getChildDataset(H5Group parent_group,
                         java.lang.String child_dataset_name)

Searches a parent group for a named child dataset

Parameters:

parent_group - the group to search for desired object

child_dataset_name - the name of child dataset to retrieve

Returns:

the child dataset if found, null otherwise

getAllChildGroups

protected java.util.List<H5Group> getAllChildGroups(H5Group parent_group)

Searches a parent group for all child groups

Parameters:

parent_group - the group to search for desired objects

Returns:

a list of all the groups found, null otherwise

getAllChildDatasets

protected java.util.List<H5ScalarDS> getAllChildDatasets(H5Group parent_group)

Searches a parent group for all child datasets

Parameters:

parent_group - the group to search for desired objects

Returns:

a list of all the datasets found, null otherwise

getAllAttributes

protected java.util.List<?> getAllAttributes(DataFormat data)

returns all attributes in dataset or group

Parameters:

data - element to search for

Returns:

list of all attributes

getAttributeStringValues

protected java.lang.String[] getAttributeStringValues(DataFormat data,
                                          java.lang.String target_attribute_name)

Returns array of strings from single named attribute Use when HObject element has a String attribute with multiple values

Parameters:

target_attribute_name - name of attribute to get values from

data - element to search for

Returns:

array of strings for this attribute

getAttributeLongValues

protected long[] getAttributeLongValues(DataFormat data,
                            java.lang.String target_attribute_name)

Returns array of longs from single named attribute Use when HObject element has either int, uint or long attribute with multiple values

Parameters:

target_attribute_name - name of attribute to get values from

data - element to search for

Returns:

array of longs for this attribute

getAttributeFloatValues

protected float[] getAttributeFloatValues(DataFormat data,
                              java.lang.String target_attribute_name)

Returns array of floating point values from single named attribute

Parameters:

target_attribute_name - name of attribute to get values from

data - element to search for

Returns:

array of floats for this attribute

getDatasetHyperslabInfo

public HDF5HyperslabInfo getDatasetHyperslabInfo(H5ScalarDS dataset)

This method returns the default hyperslab selection parameters of the dataset. If a non-default selection has already been done, calling this method will reset it to defaults.

Parameters:

dataset -

Returns:

default hdf5 dataset hyperslab info: start, selected, stride, dataset dimensions

getDataStreamFromDataset

public boolean getDataStreamFromDataset(H5ScalarDS dataset,
                               long start_row,
                               long end_row,
                               StreamingDataConsumer consumer)

Main method for random access streaming of data. Works in conjunction with a StreamingDataConsumer instance. The consumer class essentially provides a sink for asynchronous calls (callback). The startStreamingData() method is called by the library at the start of the transfer. The consumer receives all available info about the selected data, e.g. total rows, columns, and number of chunks. The consumer has a chance to preallocate any resource if so desired. Num_Chunks is calculated by the hdf.io library automatically based on dataset dimensions, data types and optimal io block transfer size. Total_rows is the actual number of rows that will be sent (may not be same as requested if start/stop are out of bounds, may be 0 if no data was found). For every new chunk, the consumer receives the data in its processStreamingDataChunk() method. After the transfer is completed, the consumer's doneStreamingData(0 method is called.

Parameters:

dataset -

start_row - 0-based index of first data row to retrieve

end_row - 0-based index of last data row to retrieve

consumer - the instance of streamingdataconsumer that will receive data in chunks

Returns:

false if an error occurred or arguments are invalid

getUIntDataChunk

protected UIntMatrixArray getUIntDataChunk(H5ScalarDS dataset,
                               HDF5HyperslabInfo info)

Reads a chunk of UInt data from a dataset. Returns a memory-space-saving unsigned integer array wrapper

See Also:

ncsa.hdf.object.ScalarDS.convertFromUnsignedC()

getUCharDataChunk

protected UCharMatrixArray getUCharDataChunk(H5ScalarDS dataset,
                                 HDF5HyperslabInfo info)

Reads a chunk of UChar data from a dataset. Returns a memory-space-saving unsigned char array wrapper

See Also:

ncsa.hdf.object.ScalarDS.convertFromUnsignedC()

createGroup

public H5Group createGroup(java.lang.String group_name,
                  H5Group parent)

Creates a new group under a parent group

Parameters:

group_name - name of new group

parent - Parent group where the new group will be created. Null if new group should be created on root

Returns:

the new group

createFilledDataset

public H5ScalarDS createFilledDataset(java.lang.String name,
                             H5Group pGroup,
                             H5Datatype data_type,
                             long[] dims,
                             long[] chunks,
                             java.lang.Object data)

Creates scalar dataset of specific type. Data will be written at once at the same time

Parameters:

name - name of new dataset

pGroup - parent group

data_type - data type for dataset

dims - dimensions of dataset

chunks - chuinking info

data - data to write

Returns:

new dataset

createEmptyDataset

protected H5ScalarDS createEmptyDataset(java.lang.String name,
                            H5Group pGroup,
                            H5Datatype data_type,
                            long[] dims,
                            long[] chunks)

Creates empty scalar dataset of specific type. Data will be added after creation using hyperslabs method.

Parameters:

name - name of new dataset

pGroup - parent group

data_type - data type for dataset

dims - dimensions of dataset

chunks - chunking info

Returns:

new dataset

writeUIntAttribute

public boolean writeUIntAttribute(HObject h_object,
                         java.lang.String attribute_name,
                         long value)

Creates a new UInt attribute in the specified group or dataset and writes the passed in value

Parameters:

h_object - group or dataset to write to

attribute_name - name of new attribute

value - the value of the attribute

Returns:

true if successful, false otherwise

writeStringAttribute

public boolean writeStringAttribute(HObject h_object,
                           java.lang.String attribute_name,
                           java.lang.String value)

Creates a new String attribute in the specified group or dataset and writes the passed in value. *

Parameters:

h_object - group or dataset to write to

attribute_name - name of new attribute

value - the value of the attribute

Returns:

true if successful, false otherwise

writeChunkToDataset

public void writeChunkToDataset(H5ScalarDS dataset,
                       HDF5HyperslabInfo info,
                       java.lang.Object data)

Writes a block of data to the selected dataset. Data can be written at once or in chunks by using the HDF5HyperslabInfo parameter.

Parameters:

dataset - to write to

info - hyperslab to write to disk

data - chunk of data to be written

readDatasetHyperslab

protected java.lang.Object readDatasetHyperslab(H5ScalarDS dataset,
                                    HDF5HyperslabInfo info)

Reads the data from file to a memory buffer and returns the memory buffer. The dataset object does not hold the memory buffer. The selected data subset (hyperslab) is specified by the three arrays inside HDF5HyperslabInfo: start, stride and sel. start: offset of a selection stride: determining how many elements to move in each dimension sel: number of elements to select in each dimension For ScalarDS, the memory data buffer is an one-dimensional array of byte, short, int, float, double or String type based on the datatype of the dataset.

Parameters:

dataset - scalar dataset to read data from

info - requested data subset

Returns:

1D array

readUnsignedDatasetHyperslab

protected java.lang.Object readUnsignedDatasetHyperslab(H5ScalarDS dataset,
                                            HDF5HyperslabInfo info)

A convenient but not memory-efficient method to read a hyperslab of unsigned integers. Each 4-byte unsigned-int is converted to an 8-byte long (Java does not support unsigned data types). No conversion is made if dataset is not unsigned data type

Parameters:

dataset - scalar dataset to read data from

info - requested data subset

Returns:

converted 1D array

See Also:

readDatasetHyperslab(H5ScalarDS dataset, HDF5HyperslabInfo info)

dispose

public void dispose()

this method must be called after using the file

getFilePath

public java.lang.String getFilePath()

Returns:

getFileHandle

public H5File getFileHandle()

Returns:

the H5File object used to open the file, equivalent to a file handle

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getDatasetChunkInfo

protected HDF5ChunkInfo getDatasetChunkInfo(H5ScalarDS dataset)

Gets chunking info, if chunking was used, of this datasets

Parameters:

dataset -

Returns:

hdf5 chunk info: rank, chunk size, dataset dimensions. Null if datasets has no chunking

testPrintDatasetInfo

protected void testPrintDatasetInfo(H5ScalarDS dataset)

test only method, dumps dataset info

Parameters:

dataset -