ch.systemsx.cisd.hdf5

Interface IHDF5ReferenceWriter

All Superinterfaces:

IHDF5ReferenceReader

All Known Implementing Classes:

HDF5ReferenceWriter

public interface IHDF5ReferenceWriter
extends IHDF5ReferenceReader

An interface for writing references.

Obtain an object implementing this interface by calling IHDF5Writer.reference().

References can refer to objects or regions of datasets. This version only supports object references.

Note: References are a low-level feature and it is easy to get dangling or even wrong references by using them. If you have a choice, don't use them, but use links instead. If you have to use them, e.g. to comply with a pre-defined format definition, use them with care. The most important fact to know about references is that they don't keep an object alive. Once the last link to the object is gone, the object is gone as well. The reference will be dangling. If, at a later time, another object header is written to the same place in the file, the reference will refer to this new object, which is most likely an undesired effect (wrong reference). By default JHDF5 itself deletes existing datasets before writing new content to a dataset of the same name, which may lead to the described problem of dangling or wrong references without any explicit call to IHDF5SimpleWriter.delete(String). Thus, HDF5 files with references should always be opened for writing using the IHDF5WriterConfigurator.keepDataSetsIfTheyExist() setting.

Method Summary

Modifier and Type	Method and Description
void	createArray(java.lang.String objectPath, int size) Creates an array (of rank 1) of object references.
void	createArray(java.lang.String objectPath, int size, HDF5IntStorageFeatures features) Creates an array (of rank 1) of object references.
void	createArray(java.lang.String objectPath, long size, int blockSize) Creates an array (of rank 1) of object references.
void	createArray(java.lang.String objectPath, long size, int blockSize, HDF5IntStorageFeatures features) Creates an array (of rank 1) of object references.
void	createMDArray(java.lang.String objectPath, int[] dimensions) Creates a multi-dimensional array of object references.
void	createMDArray(java.lang.String objectPath, int[] dimensions, HDF5IntStorageFeatures features) Creates a multi-dimensional array of object references.
void	createMDArray(java.lang.String objectPath, long[] dimensions, int[] blockDimensions) Creates a multi-dimensional array of object references.
void	createMDArray(java.lang.String objectPath, long[] dimensions, int[] blockDimensions, HDF5IntStorageFeatures features) Creates a multi-dimensional array of object references.
void	setArrayAttr(java.lang.String objectPath, java.lang.String name, java.lang.String[] referencedObjectPaths) Sets a 1D object reference array attribute to referenced objects.
void	setAttr(java.lang.String objectPath, java.lang.String name, java.lang.String referencedObjectPath) Sets an object reference attribute to the referenced object.
void	setMDArrayAttr(java.lang.String objectPath, java.lang.String name, ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths) Sets an object reference array attribute to referenced objects.
void	write(java.lang.String objectPath, java.lang.String referencedObjectPath) Writes an object reference to the referenced object.
void	writeArray(java.lang.String objectPath, java.lang.String[] referencedObjectPath) Writes an array (of rank 1) of object references.
void	writeArray(java.lang.String objectPath, java.lang.String[] referencedObjectPath, HDF5IntStorageFeatures features) Writes an array (of rank 1) of object references.
void	writeArrayBlock(java.lang.String objectPath, java.lang.String[] referencedObjectPaths, long blockNumber) Writes out a block of an array (of rank 1) of object references.
void	writeArrayBlockWithOffset(java.lang.String objectPath, java.lang.String[] referencedObjectPaths, int dataSize, long offset) Writes out a block of an array (of rank 1) of object references.
void	writeMDArray(java.lang.String objectPath, ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths) Writes an array (of rank N) of object references.
void	writeMDArray(java.lang.String objectPath, ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths, HDF5IntStorageFeatures features) Writes an array (of rank N) of object references.
void	writeMDArrayBlock(java.lang.String objectPath, ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths, long[] blockNumber) Writes out a block of a multi-dimensional array of object references.
void	writeMDArrayBlockWithOffset(java.lang.String objectPath, ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths, long[] offset) Writes out a block of a multi-dimensional array of object references.
void	writeMDArrayBlockWithOffset(java.lang.String objectPath, ch.systemsx.cisd.base.mdarray.MDLongArray referencedObjectPaths, int[] blockDimensions, long[] offset, int[] memoryOffset) Writes out a block of a multi-dimensional array of object references.

Methods inherited from interface ch.systemsx.cisd.hdf5.IHDF5ReferenceReader

getArrayAttr, getArrayAttr, getArrayNaturalBlocks, getArrayNaturalBlocks, getAttr, getAttr, getMDArrayAttr, getMDArrayAttr, getMDArrayNaturalBlocks, getMDArrayNaturalBlocks, read, read, readArray, readArray, readArrayBlock, readArrayBlock, readArrayBlockWithOffset, readArrayBlockWithOffset, readMDArray, readMDArray, readMDArrayBlock, readMDArrayBlock, readMDArrayBlockWithOffset, readMDArrayBlockWithOffset, resolvePath

Method Detail

setAttr

void setAttr(java.lang.String objectPath,
             java.lang.String name,
             java.lang.String referencedObjectPath)

Sets an object reference attribute to the referenced object.

Both the object referenced with objectPath and referencedObjectPath must exist, that is it need to have been written before by one of the write() or create() methods.

Parameters:

objectPath - The name of the object to add the attribute to.

name - The name of the attribute.

referencedObjectPath - The path of the object to reference.

setArrayAttr

void setArrayAttr(java.lang.String objectPath,
                  java.lang.String name,
                  java.lang.String[] referencedObjectPaths)

Sets a 1D object reference array attribute to referenced objects.

Both the object referenced with objectPath and all referencedObjectPaths must exist, that is it need to have been written before by one of the write() or create() methods.

Parameters:

objectPath - The name of the object to add the attribute to.

name - The name of the attribute.

referencedObjectPaths - The paths of the objects to reference.

setMDArrayAttr

void setMDArrayAttr(java.lang.String objectPath,
                    java.lang.String name,
                    ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths)

Sets an object reference array attribute to referenced objects.

Both the object referenced with objectPath and all referencedObjectPaths must exist, that is it need to have been written before by one of the write() or create() methods.

Parameters:

objectPath - The name of the object to add the attribute to.

name - The name of the attribute.

referencedObjectPaths - The paths of the objects to reference.

write

void write(java.lang.String objectPath,
           java.lang.String referencedObjectPath)

Writes an object reference to the referenced object.

The object referenced with referencedObjectPath must exist, that is it need to have been written before by one of the write() or create() methods.

Parameters:

objectPath - The name of the object to write.

referencedObjectPath - The path of the object to reference.

writeArray

void writeArray(java.lang.String objectPath,
                java.lang.String[] referencedObjectPath)

Writes an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPath - The names of the object to write.

writeArray

void writeArray(java.lang.String objectPath,
                java.lang.String[] referencedObjectPath,
                HDF5IntStorageFeatures features)

Writes an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPath - The names of the object to write.

features - The storage features of the data set.

createArray

void createArray(java.lang.String objectPath,
                 int size)

Creates an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

size - The size of the array to create. This will be the total size for non-extendable data sets and the size of one chunk for extendable (chunked) data sets. For extendable data sets the initial size of the array will be 0, see IHDF5WriterConfigurator.dontUseExtendableDataTypes().

createArray

void createArray(java.lang.String objectPath,
                 long size,
                 int blockSize)

Creates an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

size - The size of the array to create. When using extendable data sets ((see IHDF5WriterConfigurator.dontUseExtendableDataTypes())), then no data set smaller than this size can be created, however data sets may be larger.

blockSize - The size of one block (for block-wise IO). Ignored if no extendable data sets are used (see IHDF5WriterConfigurator.dontUseExtendableDataTypes()).

createArray

void createArray(java.lang.String objectPath,
                 int size,
                 HDF5IntStorageFeatures features)

Creates an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

size - The size of the array to create. This will be the total size for non-extendable data sets and the size of one chunk for extendable (chunked) data sets. For extendable data sets the initial size of the array will be 0, see HDF5IntStorageFeatures.

features - The storage features of the data set.

createArray

void createArray(java.lang.String objectPath,
                 long size,
                 int blockSize,
                 HDF5IntStorageFeatures features)

Creates an array (of rank 1) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

size - The size of the array to create. When using extendable data sets ((see IHDF5WriterConfigurator.dontUseExtendableDataTypes())), then no data set smaller than this size can be created, however data sets may be larger.

blockSize - The size of one block (for block-wise IO). Ignored if no extendable data sets are used (see IHDF5WriterConfigurator.dontUseExtendableDataTypes()) and features is HDF5IntStorageFeature.INTNO_COMPRESSION.

features - The storage features of the data set.

writeArrayBlock

void writeArrayBlock(java.lang.String objectPath,
                     java.lang.String[] referencedObjectPaths,
                     long blockNumber)

Writes out a block of an array (of rank 1) of object references. The data set needs to have been created by createArray(String, long, int, HDF5IntStorageFeatures) beforehand.

Note: For best performance, the block size in this method should be chosen to be equal to the blockSize argument of the createArray(String, long, int, HDF5IntStorageFeatures) call that was used to create the data set.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The paths of the referenced objects to write. The length defines the block size. Must not be null or of length 0.

blockNumber - The number of the block to write.

writeArrayBlockWithOffset

void writeArrayBlockWithOffset(java.lang.String objectPath,
                               java.lang.String[] referencedObjectPaths,
                               int dataSize,
                               long offset)

Writes out a block of an array (of rank 1) of object references. The data set needs to have been created by createArray(String, long, int, HDF5IntStorageFeatures) beforehand.

Note: For best performance, the block size in this method should be chosen to be equal to the blockSize argument of the createArray(String, long, int, HDF5IntStorageFeatures) call that was used to create the data set.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The paths of the referenced objects to write. The length defines the block size. Must not be null or of length 0.

dataSize - The (real) size of data (needs to be <= data.length )

offset - The offset in the data set to start writing to.

writeMDArray

void writeMDArray(java.lang.String objectPath,
                  ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths)

Writes an array (of rank N) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The names of the object to write.

writeMDArray

void writeMDArray(java.lang.String objectPath,
                  ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths,
                  HDF5IntStorageFeatures features)

Writes an array (of rank N) of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The names of the object to write.

features - The storage features of the data set.

createMDArray

void createMDArray(java.lang.String objectPath,
                   int[] dimensions)

Creates a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

dimensions - The dimensions of the array to create. This will be the total dimensions for non-extendable data sets and the dimensions of one chunk (extent along each axis) for extendable (chunked) data sets. For extendable data sets the initial size of the array along each axis will be 0, see IHDF5WriterConfigurator.dontUseExtendableDataTypes().

createMDArray

void createMDArray(java.lang.String objectPath,
                   long[] dimensions,
                   int[] blockDimensions)

Creates a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

dimensions - The dimensions of the array.

blockDimensions - The dimensions of one block (chunk) of the array.

createMDArray

void createMDArray(java.lang.String objectPath,
                   int[] dimensions,
                   HDF5IntStorageFeatures features)

Creates a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

dimensions - The dimensions of the array to create. This will be the total dimensions for non-extendable data sets and the dimensions of one chunk (extent along each axis) for extendable (chunked) data sets. For extendable data sets the initial size of the array along each axis will be 0, see IHDF5WriterConfigurator.dontUseExtendableDataTypes().

features - The storage features of the data set.

createMDArray

void createMDArray(java.lang.String objectPath,
                   long[] dimensions,
                   int[] blockDimensions,
                   HDF5IntStorageFeatures features)

Creates a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

dimensions - The dimensions of the array.

blockDimensions - The dimensions of one block (chunk) of the array.

features - The storage features of the data set.

writeMDArrayBlock

void writeMDArrayBlock(java.lang.String objectPath,
                       ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths,
                       long[] blockNumber)

Writes out a block of a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The paths of the object references to write. Must not be null. All columns need to have the same length.

blockNumber - The block number in each dimension (offset: multiply with the extend in the according dimension).

writeMDArrayBlockWithOffset

void writeMDArrayBlockWithOffset(java.lang.String objectPath,
                                 ch.systemsx.cisd.base.mdarray.MDArray<java.lang.String> referencedObjectPaths,
                                 long[] offset)

Writes out a block of a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The paths of the object references to write. Must not be null.

offset - The offset in the data set to start writing to in each dimension.

writeMDArrayBlockWithOffset

void writeMDArrayBlockWithOffset(java.lang.String objectPath,
                                 ch.systemsx.cisd.base.mdarray.MDLongArray referencedObjectPaths,
                                 int[] blockDimensions,
                                 long[] offset,
                                 int[] memoryOffset)

Writes out a block of a multi-dimensional array of object references.

Parameters:

objectPath - The name (including path information) of the data set object in the file.

referencedObjectPaths - The paths of the object references to write. Must not be null.

blockDimensions - The dimensions of the block to write to the data set.

offset - The offset of the block in the data set to start writing to in each dimension.

memoryOffset - The offset of the block in the data array.