Module org.hdfgroup.object

Package hdf.object

Class CompoundDS

Object

hdf.object.HObject

hdf.object.Dataset

hdf.object.CompoundDS

All Implemented Interfaces:

CompoundDataFormat, DataFormat, Serializable

Direct Known Subclasses:

H4CompoundAttribute, H4Vdata, H5CompoundAttr, H5CompoundDS

public abstract class CompoundDS
extends Dataset
implements CompoundDataFormat

A CompoundDS is a dataset with compound datatype. A compound datatype is an aggregation of one or more datatypes. Each member of a compound type has a name which is unique within that type, and a datatype of that member in a compound datum. Compound datatypes can be nested, i.e. members of a compound datatype can be some other compound datatype. For more details on compound datatypes, See HDF5 Datatypes in HDF5 User Guide Since Java cannot handle C-structured compound data, data in a compound dataset is loaded in to an Java List. Each element of the list is a data array that corresponds to a compound field. The data is read/written by compound field. For example, if compound dataset "comp" has the following nested structure, and member datatypes

 comp --> m01 (int)
 comp --> m02 (float)
 comp --> nest1 --> m11 (char)
 comp --> nest1 --> m12 (String)
 comp --> nest1 --> nest2 --> m21 (long)
 comp --> nest1 --> nest2 --> m22 (double)
 

The data object is a Java list of six arrays: {int[], float[], char[], Stirng[], long[] and double[]}.

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected List<String>	flatNameList	A list of names of all fields including nested fields.
protected List<Datatype>	flatTypeList	A list of datatypes of all fields including nested fields.
protected boolean[]	isMemberSelected	The array to store flags to indicate if a member of this compound dataset is selected for read/write.
protected Object[]	memberDims	The dimension sizes of each member.
protected String[]	memberNames	The names of members of the compound dataset.
protected int[]	memberOrders	Returns array containing the total number of elements of the members of this compound dataset.
protected Datatype[]	memberTypes	The datatypes of compound members.
protected int	numberOfMembers	The number of members of the compound dataset.
static final String	SEPARATOR	A single character to separate the names of nested compound fields.

Fields inherited from class hdf.object.Dataset

chunkSize, compression, COMPRESSION_GZIP_TXT, convertByteToString, convertedBuf, data, datatype, dimNames, dims, filters, inited, isDataLoaded, isImage, isNULL, isScalar, isText, maxDims, nPoints, originalBuf, rank, selectedDims, selectedIndex, selectedStride, space_type, startDims, storage, storageLayout

Fields inherited from class hdf.object.HObject

fileFormat, linkTargetObjName, oid

Constructor Summary

Constructors

Constructor	Description
CompoundDS(FileFormat theFile, String theName, String thePath)	Constructs a CompoundDS object with the given file, dataset name and path.
CompoundDS(FileFormat theFile, String dsName, String dsPath, long[] oid)	Deprecated. Not for public use in the future. Using CompoundDS(FileFormat, String, String)

Method Summary

Modifier and Type	Method	Description
protected Object	convertByteMember(Datatype dtype, byte[] byteData)	Routine to convert datatypes that are read in as byte arrays to regular types.
protected Object	convertCompoundByteMembers(Datatype dtype, byte[] data)	Given an array of bytes representing a compound Datatype, converts each of its members into Objects and returns the results.
Dataset	copy(Group pgroup, String name, long[] dims, Object data)	Deprecated. Not implemented for compound dataset.
Object	getFillValue()	Returns the fill values for the data object.
final int	getMemberCount()	Returns the number of members of the compound dataset.
final int[]	getMemberDims(int i)	Returns the dimension sizes of the i-th member.
final String[]	getMemberNames()	Returns the names of the members of the compound dataset.
final int[]	getMemberOrders()	Returns array containing the total number of elements of the members of the compound dataset.
final Datatype[]	getMemberTypes()	Returns an array of datatype objects of compound members.
final int	getSelectedMemberCount()	Returns the number of selected members of the compound dataset.
final String[]	getSelectedMemberNames()	Returns an array of the names of the selected members of the compound dataset.
final int[]	getSelectedMemberOrders()	Returns array containing the total number of elements of the selected members of the compound dataset.
final Datatype[]	getSelectedMemberTypes()	Returns an array of datatype objects of selected compound members.
final boolean	isMemberSelected(int idx)	Checks if a member of the compound dataset is selected for read/write.
protected void	resetSelection()	Resets selection of dataspace
final void	selectMember(int idx)	Selects the i-th member for read/write.
final void	setAllMemberSelection(boolean selectAll)	Selects/deselects all members.

Methods inherited from class hdf.object.Dataset

byteToString, clear, clearData, convertFromUnsignedC, convertFromUnsignedC, convertToUnsignedC, convertToUnsignedC, getChunkSize, getCompression, getConvertByteToString, getData, getDatatype, getDepth, getDimNames, getDims, getFilters, getHeight, getMaxDims, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSize, getSpaceType, getStartDims, getStorage, getStorageLayout, getStride, getVirtualFilename, getVirtualMaps, getWidth, isInited, isNULL, isScalar, isString, isVirtual, readBytes, refreshData, setConvertByteToString, setData, stringToByte, toString, toString, toString, write

Methods inherited from class hdf.object.HObject

close, createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, open, setFullname, setLinkTargetObjName, setName, setPath, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface hdf.object.DataFormat

clearData, convertFromUnsignedC, convertToUnsignedC, getCompression, getData, getDatatype, getDepth, getDims, getHeight, getOriginalClass, getRank, getSelectedDims, getSelectedIndex, getSpaceType, getStartDims, getStride, getWidth, init, isInited, read, refreshData, setData, write, write

Field Details

SEPARATOR

public static final String SEPARATOR

A single character to separate the names of nested compound fields. An extended ASCII character, 0x95, is used to avoid common characters in compound names.

See Also:

• Constant Field Values

numberOfMembers

protected int numberOfMembers

The number of members of the compound dataset.

memberNames

protected String[] memberNames

The names of members of the compound dataset.

memberOrders

protected int[] memberOrders

Returns array containing the total number of elements of the members of this compound dataset. For example, a compound dataset 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.

memberDims

protected transient Object[] memberDims

The dimension sizes of each member. The i-th element of the Object[] is an integer array (int[]) that contains the dimension sizes of the i-th member.

memberTypes

protected Datatype[] memberTypes

The datatypes of compound members.

isMemberSelected

protected boolean[] isMemberSelected

The array to store flags to indicate if a member of this compound dataset is selected for read/write. 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 dataset.

 For example, if a compound dataset 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.
 

flatNameList

protected List<String> flatNameList

A list of names of all fields including nested fields. The nested names are separated by CompoundDS.SEPARATOR. For example, if compound dataset "A" has the following nested structure,

 A --> m01
 A --> m02
 A --> nest1 --> m11
 A --> nest1 --> m12
 A --> nest1 --> nest2 --> m21
 A --> nest1 --> nest2 --> m22
 i.e.
 A = { m01, m02, nest1{m11, m12, nest2{ m21, m22}}}
 

The flatNameList of compound dataset "A" will be {m01, m02, nest1[m11, nest1[m12, nest1[nest2[m21, nest1[nest2[m22}

flatTypeList

protected List<Datatype> flatTypeList

A list of datatypes of all fields including nested fields.

Constructor Details

CompoundDS

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

Constructs a CompoundDS object with the given file, dataset name and path. The dataset object represents an existing dataset in the file. For example, new CompoundDS(file, "dset1", "/g0/") constructs a dataset object that corresponds to the dataset, "dset1", at group "/g0/". This object is usually constructed at FileFormat.open(), which loads the file structure and object information into memory. It is rarely used elsewhere.

Parameters:

theFile - the file that contains the data object.

theName - the name of the data object, e.g. "dset".

thePath - the full path of the data object, e.g. "/arrays/".

CompoundDS

@Deprecated
public CompoundDS(FileFormat theFile,
 String dsName,
 String dsPath,
 long[] oid)

Deprecated.

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

Parameters:

theFile - the file that contains the data object.

dsName - the name of the data object, e.g. "dset".

dsPath - the full path of the data object, e.g. "/arrays/".

oid - the oid of the data object.

Method Details

resetSelection

protected void resetSelection()

Resets selection of dataspace

Overrides:

resetSelection in class Dataset

getMemberCount

public final int getMemberCount()

Returns the number of members of the compound dataset.

Specified by:

getMemberCount in interface CompoundDataFormat

Returns:

the number of members of the compound dataset.

getSelectedMemberCount

public final int getSelectedMemberCount()

Returns the number of selected members of the compound dataset. Selected members are the compound fields which are selected for read/write. For example, in a compound datatype of {int A, float B, char[] C}, users can choose to retrieve only {A, C} from the dataset. In this case, getSelectedMemberCount() returns two.

Specified by:

getSelectedMemberCount in interface CompoundDataFormat

Returns:

the number of selected members.

getMemberNames

public final String[] getMemberNames()

Returns the names of the members of the compound dataset. The names of compound members are stored in an array of Strings. For example, for a compound datatype of {int A, float B, char[] C} getMemberNames() returns ["A", "B", "C"}.

Specified by:

getMemberNames in interface CompoundDataFormat

Returns:

the names of compound members.

getSelectedMemberNames

public final String[] getSelectedMemberNames()

Returns an array of the names of the selected members of the compound dataset.

Specified by:

getSelectedMemberNames in interface CompoundDataFormat

Returns:

an array of the names of the selected members of the compound dataset.

isMemberSelected

public final boolean isMemberSelected(int idx)

Checks if a member of the compound dataset is selected for read/write.

Specified by:

isMemberSelected in interface CompoundDataFormat

Parameters:

idx - the index of compound member.

Returns:

true if the i-th memeber is selected; otherwise returns false.

selectMember

public final void selectMember(int idx)

Selects the i-th member for read/write.

Specified by:

selectMember in interface CompoundDataFormat

Parameters:

idx - the index of compound member.

setAllMemberSelection

public final void setAllMemberSelection(boolean selectAll)

Selects/deselects all members.

Specified by:

setAllMemberSelection in interface CompoundDataFormat

Parameters:

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.

getMemberOrders

public final int[] getMemberOrders()

Returns array containing the total number of elements of the members of the compound dataset. For example, a compound dataset 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.

Specified by:

getMemberOrders in interface CompoundDataFormat

Returns:

the array containing the total number of elements of the members of compound.

getSelectedMemberOrders

public final int[] getSelectedMemberOrders()

Returns array containing the total number of elements of the selected members of the compound dataset. For example, a compound dataset 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}

Specified by:

getSelectedMemberOrders in interface CompoundDataFormat

Returns:

array containing the total number of elements of the selected members of compound.

getMemberDims

public final int[] getMemberDims(int i)

Returns the dimension sizes of the i-th member. For example, a compound dataset 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.

Specified by:

getMemberDims in interface CompoundDataFormat

Parameters:

i - the i-th member

Returns:

the dimension sizes of the i-th member, null if the compound member is not an array.

getMemberTypes

public final Datatype[] getMemberTypes()

Returns an array of datatype objects of compound members. Each member of a compound dataset has its own datatype. The datatype of a member can be atomic or other compound datatype (nested compound). Sub-classes set up the datatype objects at init().

Specified by:

getMemberTypes in interface CompoundDataFormat

Returns:

the array of datatype objects of the compound members.

getSelectedMemberTypes

public final Datatype[] getSelectedMemberTypes()

Returns an array of datatype objects of selected compound members.

Specified by:

getSelectedMemberTypes in interface CompoundDataFormat

Returns:

an array of datatype objects of selected compound members.

getFillValue

public Object getFillValue()

Returns the fill values for the data object.

Specified by:

getFillValue in interface DataFormat

Returns:

the fill values for the data object.

copy

@Deprecated
public Dataset copy(Group pgroup,
 String name,
 long[] dims,
 Object data)
             throws Exception

Deprecated.

Not implemented for compound dataset.

Description copied from class: Dataset

Creates a new dataset and writes the data buffer to the new 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.

Specified by:

copy in class Dataset

Parameters:

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.

Returns:

the new dataset.

Throws:

Exception - if dataset can not be copied

convertByteMember

protected Object convertByteMember(Datatype dtype,
 byte[] byteData)

Routine to convert datatypes that are read in as byte arrays to regular types.

Parameters:

dtype - the datatype to convert to

byteData - the bytes to convert

Returns:

the converted object

convertCompoundByteMembers

protected Object convertCompoundByteMembers(Datatype dtype,
 byte[] data)

Given an array of bytes representing a compound Datatype, converts each of its members into Objects and returns the results.

Parameters:

dtype - The compound datatype to convert

data - The byte array representing the data of the compound Datatype

Returns:

The converted types of the bytes