Cursor Class Reference

Main Page Classes

Public Member Functions | List of all members
Cursor Class Reference

## Public Member Functions
| Cursor (Product product) throws CodaException
void | close () throws CodaException
| Cursor (Cursor cursor)
void | gotoPath (String path) throws CodaException
void | gotoFirstRecordField () throws CodaException
void | gotoRecordFieldByIndex (int index) throws CodaException
void | gotoRecordFieldByName (String name) throws CodaException
void | gotoNextRecordField () throws CodaException
void | gotoAvailableUnionField () throws CodaException
void | gotoFirstArrayElement () throws CodaException
void | gotoArrayElement (int[] subs) throws CodaException
void | gotoArrayElementByIndex (int index) throws CodaException
void | gotoNextArrayElement () throws CodaException
void | gotoAttributes () throws CodaException
void | gotoParent () throws CodaException
void | gotoRoot () throws CodaException
void | useBaseTypeOfSpecialType () throws CodaException
boolean | hasAsciiContent () throws CodaException
boolean | hasAttributes () throws CodaException
int | getStringLength () throws CodaException
long | getBitSize () throws CodaException
long | getByteSize () throws CodaException
int | getNumElements () throws CodaException
Product | getProduct () throws CodaException
int | getDepth () throws CodaException
int | getIndex () throws CodaException
long | getFileBitOffset () throws CodaException
long | getFileByteOffset () throws CodaException
FormatEnum | getFormat () throws CodaException
TypeClassEnum | getTypeClass () throws CodaException
NativeTypeEnum | getReadType () throws CodaException
SpecialTypeEnum | getSpecialType () throws CodaException
Type | getType () throws CodaException
int | getRecordFieldIndexFromName (String name) throws CodaException
int | getRecordFieldAvailableStatus (int index) throws CodaException
int | getAvailableUnionFieldIndex () throws CodaException
int[] | getArrayDim () throws CodaException
byte | readInt8 () throws CodaException
byte | readUint8 () throws CodaException
short | readInt16 () throws CodaException
short | readUint16 () throws CodaException
int | readInt32 () throws CodaException
long | readUint32 () throws CodaException
long | readInt64 () throws CodaException
long | readUint64 () throws CodaException
float | readFloat () throws CodaException
double | readDouble () throws CodaException
char | readChar () throws CodaException
String | readString () throws CodaException
byte[] | readBits (long bit_offset, long bit_length) throws CodaException
byte[] | readBytes (long offset, long length) throws CodaException
byte[] | readInt8Array (ArrayOrderingEnum array_ordering) throws CodaException
byte[] | readUint8Array (ArrayOrderingEnum array_ordering) throws CodaException
short[] | readInt16Array (ArrayOrderingEnum array_ordering) throws CodaException
short[] | readUint16Array (ArrayOrderingEnum array_ordering) throws CodaException
int[] | readInt32Array (ArrayOrderingEnum array_ordering) throws CodaException
int[] | readUint32Array (ArrayOrderingEnum array_ordering) throws CodaException
long[] | readInt64Array (ArrayOrderingEnum array_ordering) throws CodaException
long[] | readUint64Array (ArrayOrderingEnum array_ordering) throws CodaException
float[] | readFloatArray (ArrayOrderingEnum array_ordering) throws CodaException
double[] | readDoubleArray (ArrayOrderingEnum array_ordering) throws CodaException
char[] | readCharArray (ArrayOrderingEnum array_ordering) throws CodaException
byte[] | readInt8PartialArray (int offset, int length) throws CodaException
byte[] | readUint8PartialArray (int offset, int length) throws CodaException
short[] | readInt16PartialArray (int offset, int length) throws CodaException
short[] | readUint16PartialArray (int offset, int length) throws CodaException
int[] | readInt32PartialArray (int offset, int length) throws CodaException
int[] | readUint32PartialArray (int offset, int length) throws CodaException
long[] | readInt64PartialArray (int offset, int length) throws CodaException
long[] | readUint64PartialArray (int offset, int length) throws CodaException
float[] | readFloatPartialArray (int offset, int length) throws CodaException
double[] | readDoublePartialArray (int offset, int length) throws CodaException
char[] | readCharPartialArray (int offset, int length) throws CodaException
double | readComplexDoublePair () throws CodaException
double[] | readComplexDoublePairsArray (ArrayOrderingEnum array_ordering) throws CodaException

## Detailed Description

CODA Cursor class.

After you have opened a product file (by constructing a Product instance) you will want to access data from this product and retrieve metadata for the data elements. In order to do this, CODA provides the concept of a 'cursor'. A cursor can be thought of as something that keeps track of a position in the product file and it also stores some extra (type) information about the data element it is currently pointing to. Cursors will start their useful life at the 'root' of a product, i.e., pointing to the entire product, with a type that accurately describes the entire product. From there you can navigate the cursor to the specific data element(s) you want *to access. Note that cursors are used for all products that can be opened with CODA. This includes files in ascii, binary, XML, netCDF, HDF4, or HDF5 format.

The Cursor class is the Java representation of the cursor concept and contains the various methods available for manipulating cursors in CODA.

## Constructor & Destructor Documentation

## ◆ Cursor() [1/2]

Cursor | ( | Product | product | ) | throws CodaException

Construct a Cursor instance to point to an entire Product.

Parameters

  product | A Product instance.

Exceptions

  CodaException | If an error occurred.

## ◆ Cursor() [2/2]

Cursor | ( | Cursor | cursor | ) |

Parameters

  cursor |

## Member Function Documentation

## ◆ close()

void close | ( |  | ) | throws CodaException

Closes an open cursor. The Cursor instance will be invalid after calling this method and should no longer be used.

Exceptions

  CodaException | If an error occurred.

## ◆ getArrayDim()

int[] getArrayDim | ( |  | ) | throws CodaException

Retrieve the dimensions of the data array that the cursor points to.

Returns
  The dimensions array.

Exceptions

  CodaException | If an error occurred.

## ◆ getAvailableUnionFieldIndex()

int getAvailableUnionFieldIndex | ( |  | ) | throws CodaException

Determines which union record field is available in the product.

Returns
  The index of the available record field.

Exceptions

  CodaException | If an error occurred.

## ◆ getBitSize()

long getBitSize | ( |  | ) | throws CodaException

Get the bit size for the data at the current cursor position.

Returns
  The bit size.

Exceptions

  CodaException | If an error occurred.

## ◆ getByteSize()

long getByteSize | ( |  | ) | throws CodaException

Get the byte size for the data at the current cursor position.

Returns
  The byte size.

Exceptions

  CodaException | If an error occurred.

## ◆ getDepth()

int getDepth | ( |  | ) | throws CodaException

Retrieve the current hierarchical depth of the cursor.

Returns
  The cursor depth.

Exceptions

  CodaException | If an error occurred.

## ◆ getFileBitOffset()

long getFileBitOffset | ( |  | ) | throws CodaException

Retrieve the file offset in bits of the data element that the cursor points to.

Returns
  The file offset in bits.

Exceptions

  CodaException | If an error occurred.

## ◆ getFileByteOffset()

long getFileByteOffset | ( |  | ) | throws CodaException

Retrieve the file offset in bytes of the data element that the cursor points to.

Returns
  The (possibly rounded) file offset in bytes.

Exceptions

  CodaException | If an error occurred.

## ◆ getFormat()

FormatEnum getFormat | ( |  | ) | throws CodaException

Retrieve the storage format of the data element that the cursor points to.

Returns
  The format.

Exceptions

  CodaException | If an error occurred.

## ◆ getIndex()

int getIndex | ( |  | ) | throws CodaException

Retrieve the array element or field index of the data element that the cursor points to.

Returns
  The index.

Exceptions

  CodaException | If an error occurred.

## ◆ getNumElements()

int getNumElements | ( |  | ) | throws CodaException

Gives the number of elements of the data that is pointed to by the cursor.

Returns
  Number of elements of the data in the product.

Exceptions

  CodaException | If an error occurred.

## ◆ getProduct()

Product getProduct | ( |  | ) | throws CodaException

Retrieve the Product that was used to initialize this cursor.

Returns
  The originating Product instance.

Exceptions

  CodaException | If an error occurred.

## ◆ getReadType()

NativeTypeEnum getReadType | ( |  | ) | throws CodaException

Get the best native type for reading data at the current cursor position.

Returns
  The read type.

Exceptions

  CodaException | If an error occurred.

## ◆ getRecordFieldAvailableStatus()

int getRecordFieldAvailableStatus | ( | int | index | ) | throws CodaException

Determines whether a record field is available in the product.

Parameters

  index | Index of the field (0 <= index < number of fields).

Returns
  The available status.

Exceptions

  CodaException | If an error occurred.

## ◆ getRecordFieldIndexFromName()

int getRecordFieldIndexFromName | ( | String | name | ) | throws CodaException

Get the field index from a field name for the record at the current cursor position.

Parameters

  name | Name of the record field.

Returns
  The field index (0 <= index < number of fields).

Exceptions

  CodaException | If an error occurred.

## ◆ getSpecialType()

SpecialTypeEnum getSpecialType | ( |  | ) | throws CodaException

Retrieve the special type of the data element that the cursor points to.

Returns
  The special type.

Exceptions

  CodaException | If an error occurred.

## ◆ getStringLength()

int getStringLength | ( |  | ) | throws CodaException

Get the length in bytes of a string data type.

Returns
  The string length.

Exceptions

  CodaException | If an error occurred.

## ◆ getType()

Type getType | ( |  | ) | throws CodaException

Retrieve the CODA type of the data element that the cursor points to.

Returns
  A Type instance.

Exceptions

  CodaException | If an error occurred.

## ◆ getTypeClass()

TypeClassEnum getTypeClass | ( |  | ) | throws CodaException

Retrieve the type class of the data element that the cursor points to.

Returns
  The type class.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoArrayElement()

void gotoArrayElement | ( | int[] | subs | ) | throws CodaException

Moves the cursor to point to an array element via an array of subscripts.

Parameters

  subs | Array of subscripts that identifies the data array element ((0, 0, ..., 0) <= subs < data array dimensions)

Exceptions

  CodaException | If an error occurred.

## ◆ gotoArrayElementByIndex()

void gotoArrayElementByIndex | ( | int | index | ) | throws CodaException

Moves the cursor to point to an array element via an index.

Parameters

  index | Index of the array element (0 <= index < number of elements)

Exceptions

  CodaException | If an error occurred.

## ◆ gotoAttributes()

void gotoAttributes | ( |  | ) | throws CodaException

Moves the cursor to point to a (virtual) record containing the attributes of the current data element.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoAvailableUnionField()

void gotoAvailableUnionField | ( |  | ) | throws CodaException

Moves the cursor to point to the available union field.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoFirstArrayElement()

void gotoFirstArrayElement | ( |  | ) | throws CodaException

Exceptions

  CodaException | If an error occurred.

## ◆ gotoFirstRecordField()

void gotoFirstRecordField | ( |  | ) | throws CodaException

Moves the cursor to point to the first field of a record.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoNextArrayElement()

void gotoNextArrayElement | ( |  | ) | throws CodaException

Moves the cursor to point to the next element of an array.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoNextRecordField()

void gotoNextRecordField | ( |  | ) | throws CodaException

Moves the cursor to point to the next field of a record.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoParent()

void gotoParent | ( |  | ) | throws CodaException

Moves the cursor one level up in the hierarchy.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoPath()

void gotoPath | ( | String | path | ) | throws CodaException

Moves the cursor to point to the given path.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoRecordFieldByIndex()

void gotoRecordFieldByIndex | ( | int | index | ) | throws CodaException

Moves the cursor to point to the field at position index of a record.

Parameters

  index | Index of the field (0 <= index < number of fields).

Exceptions

  CodaException | If an error occurred.

## ◆ gotoRecordFieldByName()

void gotoRecordFieldByName | ( | String | name | ) | throws CodaException

Moves the cursor to point to the field of a record that has fieldname name.

Parameters

  name | Fieldname of the field.

Exceptions

  CodaException | If an error occurred.

## ◆ gotoRoot()

void gotoRoot | ( |  | ) | throws CodaException

Moves the cursor to the root of the product.

Exceptions

  CodaException | If an error occurred.

## ◆ hasAsciiContent()

boolean hasAsciiContent | ( |  | ) | throws CodaException

Determine wether data at the current cursor position is stored as ascii data.

Returns
  The ascii content status.

Exceptions

  CodaException | If an error occurred.

## ◆ hasAttributes()

boolean hasAttributes | ( |  | ) | throws CodaException

Determine wether data at the current cursor position has attributes.

Returns
  Whether attributes are present.

Exceptions

  CodaException | If an error occurred.

## ◆ readBits()

byte[] readBits | ( | long | bit_offset,
|  | long | bit_length
| ) |  | throws CodaException

Read a specified amount of bits.

Parameters

  bit_offset | The offset relative to the current cursor position from where the bits should be read.
  bit_length | The number of bits to read.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readBytes()

byte[] readBytes | ( | long | offset,
|  | long | length
| ) |  | throws CodaException

Read a specified amount of bytes.

Parameters

  offset | The offset relative to the current cursor position from where the bytes should be read.
  length | The number of bytes to read.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readChar()

char readChar | ( |  | ) | throws CodaException

Retrieve data as type `char` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readCharArray()

char[] readCharArray | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `char` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readCharPartialArray()

char[] readCharPartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `char` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readComplexDoublePair()

double readComplexDoublePair | ( |  | ) | throws CodaException

Retrieve complex data as type `double` from the product file.

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readComplexDoublePairsArray()

double[] readComplexDoublePairsArray | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve an array of complex data as type `double` from the product file.

Parameters

  array_ordering | Specifies array storage ordering for the return array. Must be ArrayOrderingEnum.coda_array_ordering_c or ArrayOrderingEnum.coda_array_ordering_fortran.

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readDouble()

double readDouble | ( |  | ) | throws CodaException

Retrieve data as type `double` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readDoubleArray()

double[] readDoubleArray | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `double` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readDoublePartialArray()

double[] readDoublePartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `double` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readFloat()

float readFloat | ( |  | ) | throws CodaException

Retrieve data as type `float` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readFloatArray()

float[] readFloatArray | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `float` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readFloatPartialArray()

float[] readFloatPartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `float` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt16()

short readInt16 | ( |  | ) | throws CodaException

Retrieve data as type `int16` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt16Array()

short[] readInt16Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `int16` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt16PartialArray()

short[] readInt16PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `int16` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt32()

int readInt32 | ( |  | ) | throws CodaException

Retrieve data as type `int32` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt32Array()

int[] readInt32Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `int32` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt32PartialArray()

int[] readInt32PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `int32` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt64()

long readInt64 | ( |  | ) | throws CodaException

Retrieve data as type `int64` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt64Array()

long[] readInt64Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `int64` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt64PartialArray()

long[] readInt64PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `int64` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt8()

byte readInt8 | ( |  | ) | throws CodaException

Retrieve data as type `int8` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt8Array()

byte[] readInt8Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `int8` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readInt8PartialArray()

byte[] readInt8PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `int8` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readString()

String readString | ( |  | ) | throws CodaException

Retrieve text data as a Java string.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint16()

short readUint16 | ( |  | ) | throws CodaException

Retrieve data as type `uint16` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint16Array()

short[] readUint16Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `uint16` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint16PartialArray()

short[] readUint16PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `uint16` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint32()

long readUint32 | ( |  | ) | throws CodaException

Retrieve data as type `uint32` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint32Array()

int[] readUint32Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `uint32` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint32PartialArray()

int[] readUint32PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `uint32` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint64()

long readUint64 | ( |  | ) | throws CodaException

Retrieve data as type `uint64` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint64Array()

long[] readUint64Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `uint64` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint64PartialArray()

long[] readUint64PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `uint64` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint8()

byte readUint8 | ( |  | ) | throws CodaException

Retrieve data as type `uint8` from the product file.

Returns
  The value that was read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint8Array()

byte[] readUint8Array | ( | ArrayOrderingEnum | array_ordering | ) | throws CodaException

Retrieve a data array as type `uint8` from the product file.

Parameters

  array_ordering |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ readUint8PartialArray()

byte[] readUint8PartialArray | ( | int | offset,
|  | int | length
| ) |  | throws CodaException

Retrieve a partial data array as type `uint8` from the product file.

Parameters

  offset |
  length |

Returns
  The values read from the product.

Exceptions

  CodaException | If an error occurred.

## ◆ useBaseTypeOfSpecialType()

void useBaseTypeOfSpecialType | ( |  | ) | throws CodaException

Reinterpret the current special data type using the base type of the special type.

Exceptions

  CodaException | If an error occurred.