Module org.hdfgroup.object

Package hdf.object

Class Dataset

Object

hdf.object.HObject

hdf.object.Dataset

All Implemented Interfaces:

DataFormat, Serializable

Direct Known Subclasses:

CompoundDS, ScalarDS

public abstract class Dataset
extends HObject
implements DataFormat

The abstract class provides general APIs to create and manipulate dataset/attribute objects, and retrieve dataset/attribute properties, datatype and dimension sizes. This class provides two convenient functions, read()/write(), to read/write data values. Reading/writing data may take many library calls if we use the library APIs directly. The read() and write functions hide all the details of these calls from users. For more details on dataset and attributes, See HDF5 Datasets in HDF5 User Guide HDF5 Attributes in HDF5 User Guide

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

• ScalarDS
• CompoundDS
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected long[]	chunkSize	The array of dimension sizes for a chunk.
protected StringBuilder	compression	The compression information.
static final String	COMPRESSION_GZIP_TXT	The compression information default prefix.
protected boolean	convertByteToString	Flag to indicate if the byte[] array is converted to strings
protected Object	convertedBuf	The array that holds the converted data of unsigned C-type integers.
protected Object	data	The memory buffer that holds the raw data array of the dataset.
protected Datatype	datatype	The datatype object of the dataset.
protected String[]	dimNames	Array of strings that represent the dimension names.
protected long[]	dims	The current dimension sizes of the dataset
protected StringBuilder	filters	The filters information.
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 boolean	isImage	True if this dataset is an image.
protected boolean	isNULL	Flag to indicate if the dataspace is NULL
protected boolean	isScalar	Flag to indicate if the data is a single scalar point
protected boolean	isText	True if this dataset is ASCII text.
protected long[]	maxDims	The max dimension sizes of the dataset
protected long	nPoints	The number of data points in the memory buffer.
protected Object	originalBuf	The data buffer that contains the raw data directly reading from file (before any data conversion).
protected int	rank	The number of dimensions of the dataset.
protected long[]	selectedDims	Array that contains the number of data points selected (for read/write) in each dimension.
protected final int[]	selectedIndex	Array that contains the indices of the dimensions selected for display.
protected long[]	selectedStride	The number of elements to move from the start location in each dimension.
protected int	space_type	The type of space for the dataset.
protected long[]	startDims	The starting position of each dimension of a selected subset.
protected StringBuilder	storage	The storage information.
protected StringBuilder	storageLayout	The storage layout information.

Fields inherited from class hdf.object.HObject

fileFormat, linkTargetObjName, oid, SEPARATOR

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
static final String[]	byteToString(byte[] bytes, int length)	Converts an array of bytes into an array of Strings for a fixed string dataset.
void	clear()	Clears memory held by the dataset, 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.
static Object	convertFromUnsignedC(Object dataIN)	Deprecated. Not for public use in the future.
static Object	convertFromUnsignedC(Object dataIN, Object dataOUT)	Converts one-dimension array of unsigned C-type integers to a new array of appropriate Java integer in memory.
static Object	convertToUnsignedC(Object dataIN)	Deprecated. Not for public use in the future.
static Object	convertToUnsignedC(Object dataIN, Object dataOUT)	Converts the array of converted unsigned integers back to unsigned C-type integer data in memory.
abstract Dataset	copy(Group pgroup, String name, long[] dims, Object data)	Creates a new dataset and writes the data buffer to the new dataset.
final long[]	getChunkSize()	Returns the array that contains the dimension sizes of the chunk of the dataset.
final String	getCompression()	Returns the string representation of compression information.
final boolean	getConvertByteToString()	Returns the flag that indicates if a byte array is converted to a string array.
Object	getData()	Returns the data buffer of the dataset in memory.
Datatype	getDatatype()	Returns the datatype of the data object.
final long	getDepth()	Returns the dimension size of the frame axis.
final String[]	getDimNames()	Returns the array of strings that represent the dimension names.
final long[]	getDims()	Returns the array that contains the dimension sizes of the dataset.
final String	getFilters()	Returns the string representation of filter information.
final long	getHeight()	Returns the dimension size of the vertical axis.
final long[]	getMaxDims()	Returns the array that contains the max dimension sizes of the dataset.
final Class	getOriginalClass()	Get Class of the original data buffer if converted.
final int	getRank()	Returns the rank (number of dimensions) of the dataset.
final long[]	getSelectedDims()	Returns the dimension sizes of the selected subset.
final int[]	getSelectedIndex()	Returns the indices of display order.
long	getSize(long tid)	Returns the size in bytes of a given datatype.
final int	getSpaceType()	Returns the type of space for the dataset.
final long[]	getStartDims()	Returns the starting position of a selected subset.
final String	getStorage()	Returns the string representation of storage information.
final String	getStorageLayout()	Returns the string representation of storage layout information.
final long[]	getStride()	Returns the selectedStride of the selected dataset.
String	getVirtualFilename(int index)	Gets the source file name at index if dataset is virtual.
int	getVirtualMaps()	Gets the number of source files if dataset is virtual.
final long	getWidth()	Returns the dimension size of the horizontal axis.
final boolean	isInited()	The status of initialization for this object
boolean	isNULL()	Check if dataset's dataspace is a NULL
boolean	isScalar()	Check if dataset is a single scalar point
boolean	isString(long tid)	Checks if a given datatype is a string.
boolean	isVirtual()	Checks if dataset is virtual.
abstract byte[]	readBytes()	Reads the raw data of the dataset from file to a byte array.
Object	refreshData()	Refreshes the current object in the file.
protected void	resetSelection()	Resets selection of dataspace
final void	setConvertByteToString(boolean b)	Sets the flag that indicates if a byte array is converted to a string array.
final void	setData(Object d)	Not for public use in the future.
static final byte[]	stringToByte(String[] strings, int length)	Converts a string array into an array of bytes for a fixed string dataset.
protected String	toString(Object theData, Datatype theType, String delimiter, int count)	Returns a string representation of the dataset object.
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 dataset to file.

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

convertFromUnsignedC, convertToUnsignedC, getFillValue, init, read, write

Field Details

data

protected transient Object data

The memory buffer that holds the raw data array of the dataset.

space_type

protected int space_type

The type of space for the dataset.

rank

protected int rank

The number of dimensions of the dataset.

dims

protected long[] dims

The current dimension sizes of the dataset

maxDims

protected long[] maxDims

The max dimension sizes of the dataset

selectedDims

protected long[] selectedDims

Array that contains the number of data points selected (for read/write) in each dimension. The selected size must be less than or equal to the current dimension size. A subset of a rectangle selection is defined by the starting position and selected sizes. For example, if a 4 X 5 dataset is as follows:

     0,  1,  2,  3,  4
    10, 11, 12, 13, 14
    20, 21, 22, 23, 24
    30, 31, 32, 33, 34
 long[] dims = {4, 5};
 long[] startDims = {1, 2};
 long[] selectedDims = {3, 3};
 then the following subset is selected by the startDims and selectedDims above:
     12, 13, 14
     22, 23, 24
     32, 33, 34
 

startDims

protected long[] startDims

The starting position of each dimension of a selected subset. With both the starting position and selected sizes, the subset of a rectangle selection is fully defined.

selectedIndex

protected final int[] selectedIndex

Array that contains the indices of the dimensions selected for display. selectedIndex[] is provided for two purposes:

1. selectedIndex[] is used to indicate the order of dimensions for display, i.e. selectedIndex[0] = row, selectedIndex[1] = column and selectedIndex[2] = depth. For example, for a four dimension dataset, if selectedIndex[] is {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index.
2. selectedIndex[] is also used to select dimensions for display for datasets with three or more dimensions. We assume that applications such as HDFView can only display data up to three dimensions (a 2D spreadsheet/image with a third dimension that the 2D spreadsheet/image is cut from). For datasets with more than three dimensions, we need selectedIndex[] to store which three dimensions are chosen for display. For example, for a four dimension dataset, if selectedIndex[] = {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index. dim[0] is not selected. Its location is fixed at 0 by default.

selectedStride

protected long[] selectedStride

The number of elements to move from the start location in each dimension. For example, if selectedStride[0] = 2, every other data point is selected along dim[0].

chunkSize

protected long[] chunkSize

The array of dimension sizes for a chunk.

compression

protected StringBuilder compression

The compression information.

COMPRESSION_GZIP_TXT

public static final String COMPRESSION_GZIP_TXT

The compression information default prefix.

See Also:

• Constant Field Values

filters

protected StringBuilder filters

The filters information.

storageLayout

protected StringBuilder storageLayout

The storage layout information.

storage

protected StringBuilder storage

The storage information.

datatype

protected Datatype datatype

The datatype object of the dataset.

dimNames

protected String[] dimNames

Array of strings that represent the dimension names. It is null if dimension names do not exist.

convertByteToString

protected boolean convertByteToString

Flag to indicate if the byte[] array is converted to strings

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

nPoints

protected long nPoints

The number of data points in the memory buffer.

isNULL

protected boolean isNULL

Flag to indicate if the dataspace is NULL

isScalar

protected boolean isScalar

Flag to indicate if the data is a single scalar point

isImage

protected boolean isImage

True if this dataset is an image.

isText

protected boolean isText

True if this dataset is ASCII text.

originalBuf

protected transient Object originalBuf

The data buffer that contains the raw data directly reading from file (before any data conversion).

convertedBuf

protected transient Object convertedBuf

The array that holds the converted data of unsigned C-type integers. For example, Suppose that the original data is an array of unsigned 16-bit short integers. Since Java does not support unsigned integer, the data is converted to an array of 32-bit singed integer. In that case, the converted buffer is the array of 32-bit singed integer.

Constructor Details

Dataset

public Dataset(FileFormat theFile,
 String dsName,
 String dsPath)

Constructs a Dataset object with a given file, name and path.

Parameters:

theFile - the file that contains the dataset.

dsName - the name of the Dataset, e.g. "dset1".

dsPath - the full group path of this Dataset, e.g. "/arrays/".

Dataset

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

Deprecated.

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

Parameters:

theFile - the file that contains the dataset.

dsName - the name of the Dataset, e.g. "dset1".

dsPath - the full group path of this Dataset, e.g. "/arrays/".

oid - the oid of this Dataset.

Method Details

clear

public void clear()

Clears memory held by the dataset, such as the data buffer.

getSpaceType

public final int getSpaceType()

Returns the type of space for the dataset.

Specified by:

getSpaceType in interface DataFormat

Returns:

the type of space for the dataset.

getRank

public final int getRank()

Returns the rank (number of dimensions) of the dataset.

Specified by:

getRank in interface DataFormat

Returns:

the number of dimensions of the dataset.

getDims

public final long[] getDims()

Returns the array that contains the dimension sizes of the dataset.

Specified by:

getDims in interface DataFormat

Returns:

the dimension sizes of the dataset.

getMaxDims

public final long[] getMaxDims()

Returns the array that contains the max dimension sizes of the dataset.

Returns:

the max dimension sizes of the dataset.

getSelectedDims

public final long[] getSelectedDims()

Returns the dimension sizes of the selected subset. The SelectedDims is the number of data points of the selected subset. Applications can use this array to change the size of selected subset. The selected size must be less than or equal to the current dimension size. Combined with the starting position, selected sizes and stride, the subset of a rectangle selection is fully defined. For example, if a 4 X 5 dataset is as follows:

     0,  1,  2,  3,  4
    10, 11, 12, 13, 14
    20, 21, 22, 23, 24
    30, 31, 32, 33, 34
 long[] dims = {4, 5};
 long[] startDims = {1, 2};
 long[] selectedDims = {3, 3};
 long[] selectedStride = {1, 1};
 then the following subset is selected by the startDims and selectedDims
     12, 13, 14
     22, 23, 24
     32, 33, 34
 

Specified by:

getSelectedDims in interface DataFormat

Returns:

the dimension sizes of the selected subset.

getStartDims

public final long[] getStartDims()

Returns the starting position of a selected subset. Applications can use this array to change the starting position of a selection. Combined with the selected dimensions, selected sizes and stride, the subset of a rectangle selection is fully defined. For example, if a 4 X 5 dataset is as follows:

     0,  1,  2,  3,  4
    10, 11, 12, 13, 14
    20, 21, 22, 23, 24
    30, 31, 32, 33, 34
 long[] dims = {4, 5};
 long[] startDims = {1, 2};
 long[] selectedDims = {3, 3};
 long[] selectedStride = {1, 1};
 then the following subset is selected by the startDims and selectedDims
     12, 13, 14
     22, 23, 24
     32, 33, 34
 

Specified by:

getStartDims in interface DataFormat

Returns:

the starting position of a selected subset.

getStride

public final long[] getStride()

Returns the selectedStride of the selected dataset. Applications can use this array to change how many elements to move in each dimension. Combined with the starting position and selected sizes, the subset of a rectangle selection is defined. For example, if a 4 X 5 dataset is as follows:

     0,  1,  2,  3,  4
    10, 11, 12, 13, 14
    20, 21, 22, 23, 24
    30, 31, 32, 33, 34
 long[] dims = {4, 5};
 long[] startDims = {0, 0};
 long[] selectedDims = {2, 2};
 long[] selectedStride = {2, 3};
 then the following subset is selected by the startDims and selectedDims
     0,   3
     20, 23
 

Specified by:

getStride in interface DataFormat

Returns:

the selectedStride of the selected dataset.

setConvertByteToString

public final void setConvertByteToString(boolean b)

Sets the flag that indicates if a byte array is converted to a string array. In a string dataset, the raw data from file is stored in a byte array. By default, this byte array is converted to an array of strings. For a large dataset (e.g. more than one million strings), the conversion takes a long time and requires a lot of memory space to store the strings. In some applications, such a conversion can be delayed. For example, A GUI application may convert only the part of the strings that is visible to the users, not the entire data array. setConvertByteToString(boolean b) allows users to set the flag so that applications can choose to perform the byte-to-string conversion or not. If the flag is set to false, the getData() returns an array of byte instead of an array of strings.

Parameters:

b - convert bytes to strings if b is true; otherwise, if false, do not convert bytes to strings.

getConvertByteToString

public final boolean getConvertByteToString()

Returns the flag that indicates if a byte array is converted to a string array.

Returns:

true if byte array is converted to string; otherwise, returns false if there is no conversion.

readBytes

public abstract byte[] readBytes()
                          throws Exception

Reads the raw data of the dataset from file to a byte array. 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.

Returns:

the byte array of the raw data.

Throws:

Exception - if data can not be read

write

public final void write()
                 throws Exception

Writes the memory buffer of this dataset to file.

Specified by:

write in interface DataFormat

Throws:

Exception - if buffer can not be written

copy

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

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.

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

isInited

public final boolean isInited()

The status of initialization for this object

Specified by:

isInited in interface DataFormat

Returns:

true if the data has been initialized

resetSelection

protected void resetSelection()

Resets selection of dataspace

getData

public Object getData()
               throws Exception,
OutOfMemoryError

Returns the data buffer of the dataset 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 dataset is read into memory. Users can also select a subset to read. Subsetting is done in an implicit way. How to Select a Subset A selection is specified by three arrays: start, stride and count.

1. start: offset of a selection
2. stride: determines how many elements to move in each dimension
3. count: number of elements to select in each dimension

getStartDims(), getStride() and getSelectedDims() returns the start, stride and count arrays respectively. Applications can make a selection by changing the values of the arrays. The following example shows how to make a subset. In the example, the dataset is a 4-dimensional array of [200][100][50][10], i.e. dims[0]=200; dims[1]=100; dims[2]=50; dims[3]=10;
We want to select every other data point in dims[1] and dims[2]

 int rank = dataset.getRank(); // number of dimensions of the dataset
 long[] dims = dataset.getDims(); // the dimension sizes of the dataset
 long[] selected = dataset.getSelectedDims(); // the selected size of the dataet
 long[] start = dataset.getStartDims(); // the offset of the selection
 long[] stride = dataset.getStride(); // the stride of the dataset
 int[] selectedIndex = dataset.getSelectedIndex(); // the selected dimensions for display

 // select dim1 and dim2 as 2D data for display,and slice through dim0
 selectedIndex[0] = 1;
 selectedIndex[1] = 2;
 selectedIndex[1] = 0;

 // reset the selection arrays
 for (int i = 0; i < rank; i++) {
     start[i] = 0;
     selected[i] = 1;
     stride[i] = 1;
 }

 // set stride to 2 on dim1 and dim2 so that every other data point is
 // selected.
 stride[1] = 2;
 stride[2] = 2;

 // set the selection size of dim1 and dim2
 selected[1] = dims[1] / stride[1];
 selected[2] = dims[1] / stride[2];

 // when dataset.getData() is called, the selection above will be used since
 // the dimension arrays are passed by reference. Changes of these arrays
 // outside the dataset object directly change the values of these array
 // in the dataset object.
 

For ScalarDS, the memory data buffer is a one-dimensional array of byte, short, int, float, double or String type based on the datatype of the dataset. For CompoundDS, the memory data object is an java.util.List object. Each element of the list is a data array that corresponds to a 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)
 

getData() returns a list of six arrays: {int[], float[], char[], String[], long[] and double[]}.

Specified by:

getData in interface DataFormat

Returns:

the memory buffer of the dataset.

Throws:

Exception - if object can not be read

OutOfMemoryError - if memory is exhausted

setData

public final void setData(Object d)

Not for public use in the future. setData() is not safe to use because it changes memory buffer of the dataset object. Dataset operations such as write/read will fail if the buffer type or size is changed.

Specified by:

setData in interface DataFormat

Parameters:

d - the object data -must be an array of Objects

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.

Specified by:

clearData in interface DataFormat

See Also:

• getData()
• DataFormat.read()

refreshData

public Object refreshData()

Refreshes the current object in the 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 a clear and read to re-read the object from the file. For example, when the selection is changed, we need to re-read the data.

Specified by:

refreshData in interface DataFormat

Returns:

the updated data

See Also:

• getData()
• DataFormat.read()

getHeight

public final long getHeight()

Returns the dimension size of the vertical axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in a 2D table or 2D image. The display order is specified by the index array of selectedIndex as follow:

selectedIndex[0] -- height

The vertical axis

selectedIndex[1] -- width

The horizontal axis

selectedIndex[2] -- depth

The depth axis is used for 3 or more dimensional datasets.

Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=50.

 int[] selectedIndex = dataset.getSelectedIndex();
 selectedIndex[0] = 0;
 selectedIndex[1] = 1;
 

Specified by:

getHeight in interface DataFormat

Returns:

the size of dimension of the vertical axis.

See Also:

• getSelectedIndex()
• getWidth()

getWidth

public final long getWidth()

Returns the dimension size of the horizontal axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in 2D Table or 2D Image. The display order is specified by the index array of selectedIndex as follow:

selectedIndex[0] -- height

The vertical axis

selectedIndex[1] -- width

The horizontal axis

selectedIndex[2] -- depth

The depth axis, which is used for 3 or more dimension datasets.

Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=100.

 int[] selectedIndex = dataset.getSelectedIndex();
 selectedIndex[0] = 0;
 selectedIndex[1] = 1;
 

Specified by:

getWidth in interface DataFormat

Returns:

the size of dimension of the horizontal axis.

See Also:

• getSelectedIndex()
• getHeight()

getDepth

public final long getDepth()

Returns the dimension size of the frame axis. This function is used by GUI applications such as HDFView. GUI applications display a dataset in 2D Table or 2D Image. The display order is specified by the index array of selectedIndex as follow:

selectedIndex[0] -- height

The vertical axis

selectedIndex[1] -- width

The horizontal axis

selectedIndex[2] -- depth

The depth axis, which is used for 3 or more dimension datasets.

Applications can use getSelectedIndex() to access and change the display order. For example, in a 2D dataset of 200x50 (dim0=200, dim1=50), the following code will set the height=200 and width=100.

 int[] selectedIndex = dataset.getSelectedIndex();
 selectedIndex[0] = 0;
 selectedIndex[1] = 1;
 

Specified by:

getDepth in interface DataFormat

Returns:

the size of dimension of the frame axis.

See Also:

• getSelectedIndex()
• getHeight()

getSelectedIndex

public final int[] getSelectedIndex()

Returns the indices of display order. selectedIndex[] is provided for two purposes:

1. selectedIndex[] is used to indicate the order of dimensions for display. selectedIndex[0] is for the row, selectedIndex[1] is for the column and selectedIndex[2] for the depth. For example, for a four dimension dataset, if selectedIndex[] = {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index.
2. selectedIndex[] is also used to select dimensions for display for datasets with three or more dimensions. We assume that applications such as HDFView can only display data values up to three dimensions (2D spreadsheet/image with a third dimension which the 2D spreadsheet/image is selected from). For datasets with more than three dimensions, we need selectedIndex[] to tell applications which three dimensions are chosen for display.
   For example, for a four dimension dataset, if selectedIndex[] = {1, 2, 3}, then dim[1] is selected as row index, dim[2] is selected as column index and dim[3] is selected as depth index. dim[0] is not selected. Its location is fixed at 0 by default.

Specified by:

getSelectedIndex in interface DataFormat

Returns:

the array of the indices of display order.

getCompression

public final String getCompression()

Returns the string representation of compression information. For example, "SZIP: Pixels per block = 8: H5Z_FILTER_CONFIG_DECODE_ENABLED".

Specified by:

getCompression in interface DataFormat

Returns:

the string representation of compression information.

getFilters

public final String getFilters()

Returns the string representation of filter information.

Returns:

the string representation of filter information.

getStorageLayout

public final String getStorageLayout()

Returns the string representation of storage layout information.

Returns:

the string representation of storage layout information.

getStorage

public final String getStorage()

Returns the string representation of storage information.

Returns:

the string representation of storage information.

getChunkSize

public final long[] getChunkSize()

Returns the array that contains the dimension sizes of the chunk of the dataset. Returns null if the dataset is not chunked.

Returns:

the array of chunk sizes or returns null if the dataset is not chunked.

getDatatype

public Datatype getDatatype()

Returns the datatype of the data object.

Specified by:

getDatatype in interface DataFormat

Returns:

the datatype of the data object.

convertFromUnsignedC

@Deprecated
public static Object convertFromUnsignedC(Object dataIN)

Deprecated.

Not for public use in the future.
Using convertFromUnsignedC(Object, Object)

Parameters:

dataIN - the object data

Returns:

the converted object

convertFromUnsignedC

public static Object convertFromUnsignedC(Object dataIN,
 Object dataOUT)

Converts one-dimension array of unsigned C-type integers to a new array of appropriate Java integer in memory. Since Java does not support unsigned integer, values of unsigned C-type integers must be converted into its appropriate Java integer. Otherwise, the data value will not displayed correctly. For example, if an unsigned C byte, x = 200, is stored into an Java byte y, y will be -56 instead of the correct value of 200. Unsigned C integers are upgrade to Java integers according to the following table:

Mapping Unsigned C Integers to Java Integers

Unsigned C Integer	JAVA Integer
unsigned byte	signed short
unsigned short	signed int
unsigned int	signed long
unsigned long	signed long

NOTE: this conversion cannot deal with unsigned 64-bit integers. Therefore, the values of unsigned 64-bit datasets may be wrong in Java applications. If memory data of unsigned integers is converted by convertFromUnsignedC(), convertToUnsignedC() must be called to convert the data back to unsigned C before data is written into file.

Parameters:

dataIN - the input 1D array of the unsigned C-type integers.

dataOUT - the output converted (or upgraded) 1D array of Java integers.

Returns:

the upgraded 1D array of Java integers.

See Also:

• convertToUnsignedC(Object, Object)

convertToUnsignedC

@Deprecated
public static Object convertToUnsignedC(Object dataIN)

Deprecated.

Not for public use in the future.
Using convertToUnsignedC(Object, Object)

Parameters:

dataIN - the input 1D array of the unsigned C-type integers.

Returns:

the upgraded 1D array of Java integers.

convertToUnsignedC

public static Object convertToUnsignedC(Object dataIN,
 Object dataOUT)

Converts the array of converted unsigned integers back to unsigned C-type integer data in memory. If memory data of unsigned integers is converted by convertFromUnsignedC(), convertToUnsignedC() must be called to convert the data back to unsigned C before data is written into file.

Parameters:

dataIN - the input array of the Java integer.

dataOUT - the output array of the unsigned C-type integer.

Returns:

the converted data of unsigned C-type integer array.

See Also:

• convertFromUnsignedC(Object, Object)

byteToString

public static final String[] byteToString(byte[] bytes,
 int length)

Converts an array of bytes into an array of Strings for a fixed string dataset. A C-string is an array of chars while an Java String is an object. When a string dataset is read into a Java application, the data is stored in an array of Java bytes. byteToString() is used to convert the array of bytes into an array of Java strings so that applications can display and modify the data content. For example, the content of a two element C string dataset is {"ABC", "abc"}. Java applications will read the data into a byte array of {65, 66, 67, 97, 98, 99). byteToString(bytes, 3) returns an array of Java String of strs[0]="ABC", and strs[1]="abc". If memory data of strings is converted to Java Strings, stringToByte() must be called to convert the memory data back to byte array before data is written to file.

Parameters:

bytes - the array of bytes to convert.

length - the length of string.

Returns:

the array of Java String.

See Also:

• stringToByte(String[], int)

stringToByte

public static final byte[] stringToByte(String[] strings,
 int length)

Converts a string array into an array of bytes for a fixed string dataset. If memory data of strings is converted to Java Strings, stringToByte() must be called to convert the memory data back to byte array before data is written to file.

Parameters:

strings - the array of string.

length - the length of string.

Returns:

the array of bytes.

See Also:

• byteToString(byte[] bytes, int length)

getDimNames

public final String[] getDimNames()

Returns the array of strings that represent the dimension names. Returns null if there is no dimension name. Some datasets have pre-defined names for each dimension such as "Latitude" and "Longitude". getDimNames() returns these pre-defined names.

Returns:

the names of dimensions, or null if there is no dimension name.

isString

public boolean isString(long tid)

Checks if a given datatype is a string. Sub-classes must replace this default implementation.

Parameters:

tid - The data type identifier.

Returns:

true if the datatype is a string; otherwise returns false.

getSize

public long getSize(long tid)

Returns the size in bytes of a given datatype. Sub-classes must replace this default implementation.

Parameters:

tid - The data type identifier.

Returns:

The size of the datatype

getOriginalClass

public final Class getOriginalClass()

Get Class of the original data buffer if converted.

Specified by:

getOriginalClass in interface DataFormat

Returns:

the Class of originalBuf

isNULL

public boolean isNULL()

Check if dataset's dataspace is a NULL

Returns:

true if the dataspace is a NULL; otherwise, returns false.

isScalar

public boolean isScalar()

Check if dataset is a single scalar point

Returns:

true if the data is a single scalar point; otherwise, returns false.

isVirtual

public boolean isVirtual()

Checks if dataset is virtual. Sub-classes must replace this default implementation.

Returns:

true if the dataset is virtual; otherwise returns false.

getVirtualFilename

public String getVirtualFilename(int index)

Gets the source file name at index if dataset is virtual. Sub-classes must replace this default implementation.

Parameters:

index - index of the source file name if dataset is virtual.

Returns:

filename if the dataset is virtual; otherwise returns null.

getVirtualMaps

public int getVirtualMaps()

Gets the number of source files if dataset is virtual. Sub-classes must replace this default implementation.

Returns:

the list size if the dataset is virtual; otherwise returns negative.

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. 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.

maxItems - The maximum number of Array values to return

Returns:

the string representation of the data values.

toString

protected String toString(Object theData,
 Datatype theType,
 String delimiter,
 int count)

Returns a string representation of the dataset object.

Parameters:

theData - The Object data

theType - The type of the data in the Object

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.

count - The maximum number of Array values to return

Returns:

the string representation of the dataset object.