gov.nasa.gsfc.spdf.cdfj

Class GenericReader

java.lang.Object

gov.nasa.gsfc.spdf.cdfj.MetaData

gov.nasa.gsfc.spdf.cdfj.GenericReader

Direct Known Subclasses:

CDFReader

public class GenericReader
extends MetaData

GenericReader extends MetaData class with methods to access variable data. Data access methods of this class do not require a detailed knowledge of the structure of CDF. Derived class CDFReader extends this class with methods to access time series.

Constructor Summary

Constructors

Constructor and Description
GenericReader(java.lang.String cdfFile) Constructs a reader for the given CDF file.
GenericReader(java.net.URL url) Constructs a reader for the given CDF URL.

Method Summary

Modifier and Type	Method and Description
double[]	asDouble0(java.lang.String varName) Returns all available values for the given scalar variable.
double[][]	asDouble1(java.lang.String varName) Returns all available values for the given variable of rank 1.
double[][][]	asDouble2(java.lang.String varName) Returns all available values for the given variable of rank 2.
double[][][][]	asDouble3(java.lang.String varName) Returns all available values for the given variable of rank 3.
java.lang.Object	get(java.lang.String varName) Returns all available values for the given variable.
java.nio.ByteBuffer	getBuffer(java.lang.String threadName) Returns data extracted by the named thread as ByteBuffer.
java.nio.ByteBuffer	getBuffer(java.lang.String varName, java.lang.String targetType, int[] recordRange, boolean preserve) Returns specified data as ByteBuffer of specified type.
java.nio.ByteBuffer	getBuffer(java.lang.String varName, java.lang.String targetType, int[] recordRange, boolean preserve, boolean useDirect) Returns specified data as ByteBuffer of specified type.
java.nio.ByteBuffer	getBuffer(java.lang.String varName, java.lang.String targetType, int[] recordRange, boolean preserve, java.nio.ByteBuffer buffer)
int	getBufferCapacity(java.lang.String varName, java.lang.String targetType, int[] recordRange)
java.lang.Object	getLong(java.lang.String varName) Returns all available values for the given long type variable.
double[]	getOneD(java.lang.String varName, boolean columnMajor) Returns one dimensional representation of the values of a numeric variable whose type is not INT8 or TT2000.
java.lang.Object	getOneDArray(java.lang.String threadName, boolean columnMajor) Returns data extracted by the named thread as a one dimensional array, organized according to specified row majority..
java.lang.Object	getOneDArray(java.lang.String varName, java.lang.String targetType, int[] recordRange, boolean preserve, boolean columnMajor) Returns specified data as a one dimensional array, organized according to specified row majority..
java.lang.Object	getRange(java.lang.String varName, int first, int last) Returns values for a range of records for the given numeric variable of rank <= 2.
double[]	getRangeForComponent(java.lang.String varName, int first, int last, int component) Returns values, in the specified record range, of the specified component of 1 dimensional * variable of numeric types other than INT8 or TT2000.
double[][]	getRangeForComponents(java.lang.String varName, int first, int last, int[] components) Returns values, in the specified record range, of specified components of 1 dimensional variable of numeric types other than INT8 or TT2000.
double[]	getRangeOneD(java.lang.String varName, int first, int last, boolean columnMajor) Returns one dimensional representation of the values for a range of records of a numeric variable whose type is not INT8 or TT2000.
java.lang.Object	getSampled(java.lang.String varName, int[] range, int stride, java.lang.String type, boolean preserve, boolean columnMajor) Returns sampled values of a numeric variable as one dimensional array of specified type and storage model.
java.lang.Object	getSampled(java.lang.String varName, int first, int last, int stride, java.lang.String type, boolean preserve) Returns sampled values of a numeric variable as one dimensional array of specified type.
java.lang.String	getSource() Returns the name of the source CDF
double[]	getVectorComponent(java.lang.String varName, int component) Returns values of the specified component of 1 dimensional variable of numeric types other than INT8 or TT2000.
double[][]	getVectorComponents(java.lang.String varName, int[] components) Returns value of the specified component of 1 dimensional variable of numeric types other than INT8 or TT2000.
boolean	isScalar(java.lang.String varName) Returns whether a variable is scalar.
boolean	isVector(java.lang.String varName) Returns whether a variable is vector.
boolean	sourceIsFile()
java.lang.String	startContainerThread(java.lang.String varName, java.lang.String targetType, int[] recordRange, boolean preserve) Starts a new thread to extract specified data.
boolean	threadFinished(java.lang.String threadName) Returns whether the named thread (started via this object) has finished.
java.lang.String	userTimeVariableName(java.lang.String varName) Returns the name of the user supplied time variable for the given variable.

Methods inherited from class gov.nasa.gsfc.spdf.cdfj.MetaData

existsVariable, getAttribute, getAttribute, getAttributeEntries, getAttributeEntries, getBlockingFactor, getByteOrder, getDataItemSize, getDimensions, getEffectiveDimensions, getEffectiveRank, getElementCount, getGlobalAttribute, getLastLeapSecondId, getNumber, getNumberOfElements, getNumberOfValues, getPadValue, getPadValue, getRecordRange, getTimeVariableName, getType, getVariableNames, getVariableNames, getVarys, globalAttributeEntryCount, globalAttributeNames, isCompatible, isCompatible, isCompressed, isMissingRecords, isTimeType, isTypeR, missingRecordValueIsPad, missingRecordValueIsPrevious, recordVariance, rowMajority, variableAttributeNames

Methods inherited from class java.lang.Object

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

Constructor Detail

GenericReader

public GenericReader(java.lang.String cdfFile)
              throws CDFException.ReaderError

Constructs a reader for the given CDF file.

Throws:

CDFException.ReaderError

GenericReader

public GenericReader(java.net.URL url)
              throws CDFException.ReaderError

Constructs a reader for the given CDF URL.

Throws:

CDFException.ReaderError

Method Detail

get

public final java.lang.Object get(java.lang.String varName)
                           throws CDFException.ReaderError

Returns all available values for the given variable.

Parameters:

varName - variable name

Returns:

a double array of dimension appropriate to the variable.

Type of object returned depends on the number of varying dimensions and type of the CDF variable.
For a numeric variable, a double[], double[][], double[][][], or double[][][][] object is returned for scalar, one-dimensional, two-dimensional, or three-dimensional variable, respectively.

For a character string variable, a String[] or a String[][] object is returned for a scalar or one-dimensional variable.

Throws:

CDFException.ReaderError - for numeric variables of dimension higher than 3, and for character string variables of dimension higher than 1.

See Also:

getOneD(String varName, boolean columnMajor)

getLong

public final java.lang.Object getLong(java.lang.String varName)
                               throws CDFException.ReaderError

Returns all available values for the given long type variable.

Parameters:

varName - variable name

Returns:

a long array of dimension appropriate to the variable.

Type of object returned depends on the number of varying dimensions.
For a numeric variable, a long[], long[][], long[][][], or long[][][][] object is returned for scalar, one-dimensional, two-dimensional, or three-dimensional variable, respectively.

Throws:

CDFException.ReaderError - for variables of type other than long, or dimension higher than 3.

See Also:

getOneD(String varName, boolean columnMajor)

asDouble0

public final double[] asDouble0(java.lang.String varName)
                         throws CDFException.ReaderError

Returns all available values for the given scalar variable. For variable of type long, loss of precision may occur.

Parameters:

varName - variable name

Returns:

a double array

Throws:

CDFException.ReaderError - if variable is not a scalar, or is not a numeric type

asDouble1

public final double[][] asDouble1(java.lang.String varName)
                           throws CDFException.ReaderError

Returns all available values for the given variable of rank 1. For variable of type long, loss of precision may occur.

Parameters:

varName - variable name

Returns:

a double[][]

Throws:

CDFException.ReaderError - if effective rank of variable is not 1, or the variable is not numeric.

asDouble2

public final double[][][] asDouble2(java.lang.String varName)
                             throws CDFException.ReaderError

Returns all available values for the given variable of rank 2. For variable of type long, loss of precision may occur.

Parameters:

varName - variable name

Returns:

a double[][][]

Throws:

CDFException.ReaderError - if effective rank of variable is not 2, or the variable is not numeric.

asDouble3

public final double[][][][] asDouble3(java.lang.String varName)
                               throws CDFException.ReaderError

Returns all available values for the given variable of rank 3. For variable of type long, loss of precision may occur.

Parameters:

varName - variable name

Returns:

a double[][][][]

Throws:

CDFException.ReaderError - if effective rank of variable is not 3, or the variable is not numeric.

getOneD

public final double[] getOneD(java.lang.String varName,
                              boolean columnMajor)
                       throws CDFException.ReaderError

Returns one dimensional representation of the values of a numeric variable whose type is not INT8 or TT2000.

Parameters:

varName - variable name

columnMajor - specifies whether the returned array conforms to a columnMajor storage mode, i.e. the first index of a multi dimensional array varies the fastest.

Returns:

a double[] that represents values of multi-dimensional arrays stored in a manner prescribed by the columnMajor parameter.

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types

See Also:

get(String varName)

getRange

public final java.lang.Object getRange(java.lang.String varName,
                                       int first,
                                       int last)
                                throws CDFException.ReaderError

Returns values for a range of records for the given numeric variable of rank <= 2.

Parameters:

varName - variable name

first - first record of range

last - last record of range

Returns:

a double array of dimension appropriate to the variable.

Type of object returned depends on the number of varying dimensions and type of the CDF variable.
For a numeric variable, a double[], double[][], double[][][] object is returned for scalar, one-dimensional, or two-dimensional variable, respectively.

Throws:

CDFException.ReaderError - for non-numeric variables, or variables whose effective rank > 2

See Also:

getRangeOneD(String varName, int first, int last, boolean columnMajor)

getRangeOneD

public final double[] getRangeOneD(java.lang.String varName,
                                   int first,
                                   int last,
                                   boolean columnMajor)
                            throws CDFException.ReaderError

Returns one dimensional representation of the values for a range of records of a numeric variable whose type is not INT8 or TT2000.

Parameters:

varName - variable name

first - first record of range

last - last record of range

columnMajor - specifies whether the returned array conforms to a columnMajor storage mode, i.e. the first index of a multi dimensional array varies the fastest.

Returns:

a double[] that represents values of multi-dimensional arrays stored in a manner prescribed by the columnMajor parameter.

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types

See Also:

getRange(String varName, int first, int last)

getVectorComponent

public final double[] getVectorComponent(java.lang.String varName,
                                         int component)
                                  throws CDFException.ReaderError

Returns values of the specified component of 1 dimensional variable of numeric types other than INT8 or TT2000.

Parameters:

varName - variable name

component - component

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types, and if the variable's effective rank is not 1.

See Also:

get(String varName)

getVectorComponents

public final double[][] getVectorComponents(java.lang.String varName,
                                            int[] components)
                                     throws java.lang.Throwable

Returns value of the specified component of 1 dimensional variable of numeric types other than INT8 or TT2000.

Parameters:

varName - variable name

components - array containg components to be extracted

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types, and if the variable's effective rank is not 1.

java.lang.Throwable

See Also:

get(String varName)

getRangeForComponent

public final double[] getRangeForComponent(java.lang.String varName,
                                           int first,
                                           int last,
                                           int component)
                                    throws CDFException.ReaderError

Returns values, in the specified record range, of the specified component of 1 dimensional * variable of numeric types other than INT8 or TT2000.

Parameters:

varName - variable name

first - first record of range

last - last record of range

component - component

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types, and if the variable's effective rank is not 1.

See Also:

getRange(String varName, int first, int last)

getRangeForComponents

public final double[][] getRangeForComponents(java.lang.String varName,
                                              int first,
                                              int last,
                                              int[] components)
                                       throws CDFException.ReaderError

Returns values, in the specified record range, of specified components of 1 dimensional variable of numeric types other than INT8 or TT2000.

Parameters:

varName - variable name

first - first record of range

last - last record of range

components - components

Throws:

CDFException.ReaderError - for character, INT8 or TT2000 types, and if the variable's effective rank is not 1.

See Also:

getRange(String varName, int first, int last)

startContainerThread

public final java.lang.String startContainerThread(java.lang.String varName,
                                                   java.lang.String targetType,
                                                   int[] recordRange,
                                                   boolean preserve)
                                            throws CDFException.ReaderError

Starts a new thread to extract specified data.

Parameters:

varName - variable name

targetType - desired type of extracted data - one of the following: long, double, float, int, short, byte or string

recordRange -

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

Returns:

Name of the thread. Methods to ascertain the availability and to retrieve require this name.

Throws:

CDFException.ReaderError

See Also:

threadFinished(String threadName), getOneDArray(String threadName, boolean columnMajor), getBuffer(String threadName)

threadFinished

public final boolean threadFinished(java.lang.String threadName)
                             throws CDFException.ReaderError

Returns whether the named thread (started via this object) has finished.

Throws:

CDFException.ReaderError

getBuffer

public final java.nio.ByteBuffer getBuffer(java.lang.String threadName)
                                    throws java.lang.Throwable

Returns data extracted by the named thread as ByteBuffer. After this method returns the ByteBuffer, threadName is forgotten.

Throws:

java.lang.Throwable

getOneDArray

public final java.lang.Object getOneDArray(java.lang.String threadName,
                                           boolean columnMajor)
                                    throws CDFException.ReaderError

Returns data extracted by the named thread as a one dimensional array, organized according to specified row majority..

Throws:

CDFException.ReaderError

getBuffer

public final java.nio.ByteBuffer getBuffer(java.lang.String varName,
                                           java.lang.String targetType,
                                           int[] recordRange,
                                           boolean preserve)
                                    throws CDFException.ReaderError

Returns specified data as ByteBuffer of specified type. Order of the ByteBuffer is 'native'. Data is organized according to storage model of the variable returned by rowMajority(). A DirectBuffer is allocated.

Parameters:

varName - variable name

targetType - desired type of extracted data

recordRange -

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

Throws:

CDFException.ReaderError

getBuffer

public final java.nio.ByteBuffer getBuffer(java.lang.String varName,
                                           java.lang.String targetType,
                                           int[] recordRange,
                                           boolean preserve,
                                           boolean useDirect)
                                    throws CDFException.ReaderError

Returns specified data as ByteBuffer of specified type. Order of the ByteBuffer is 'native'. Data is organized according to storage model of the variable returned by rowMajority().

Parameters:

varName - variable name

targetType - desired type of extracted data

recordRange -

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

useDirect - specifies whether a DirectBuffer should be used. if set to false, an array backed buffer will be allocated.

Throws:

CDFException.ReaderError

getOneDArray

public final java.lang.Object getOneDArray(java.lang.String varName,
                                           java.lang.String targetType,
                                           int[] recordRange,
                                           boolean preserve,
                                           boolean columnMajor)
                                    throws CDFException.ReaderError

Returns specified data as a one dimensional array, organized according to specified row majority..

Parameters:

varName - variable name

targetType - desired type of extracted data

recordRange -

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

columnMajor - specifies whether the returned array conforms to a columnMajor storage mode, i.e. the first index of a multi dimensional array varies the fastest.

Throws:

CDFException.ReaderError

sourceIsFile

public final boolean sourceIsFile()

getSource

public final java.lang.String getSource()

Returns the name of the source CDF

isScalar

public final boolean isScalar(java.lang.String varName)
                       throws CDFException.ReaderError

Returns whether a variable is scalar.

Throws:

CDFException.ReaderError

isVector

public final boolean isVector(java.lang.String varName)
                       throws CDFException.ReaderError

Returns whether a variable is vector.

Throws:

CDFException.ReaderError

userTimeVariableName

public java.lang.String userTimeVariableName(java.lang.String varName)
                                      throws CDFException.ReaderError

Returns the name of the user supplied time variable for the given variable. For CDF that does not conform to ISTP specification for identifying time variable associated with a variable, applications need to override this method via a subclass. Default implementation assumes ISTP compliance, and returns null.

Specified by:

userTimeVariableName in class MetaData

Parameters:

varName - variable name

Returns:

String user supplied name, or null if none

Throws:

CDFException.ReaderError - if variable does not exist

getSampled

public java.lang.Object getSampled(java.lang.String varName,
                                   int[] range,
                                   int stride,
                                   java.lang.String type,
                                   boolean preserve,
                                   boolean columnMajor)
                            throws CDFException.ReaderError

Returns sampled values of a numeric variable as one dimensional array of specified type and storage model.

Parameters:

varName - variable name

stride - array of length 1 where value specifies stride

type - desired type of extracted data - one of the following: "long", "double", "float", "int", "short", or "byte"

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

columnMajor - specifies whether the returned array conforms to a columnMajor storage mode, i.e. the first index of a multi dimensional array varies the fastest.

Throws:

CDFException.ReaderError

getSampled

public java.lang.Object getSampled(java.lang.String varName,
                                   int first,
                                   int last,
                                   int stride,
                                   java.lang.String type,
                                   boolean preserve)
                            throws CDFException.ReaderError

Returns sampled values of a numeric variable as one dimensional array of specified type. Data for records is organized according to the storage model of the variable (as returned by rowMajority()).

Parameters:

varName - variable name

stride - array of length 1 where value specifies stride

type - desired type of extracted data - one of the following: "long", "double", "float", "int", "short", or "byte"

preserve - specifies whether the target must preserve precision. if false, possible loss of precision is deemed acceptable.

Throws:

CDFException.ReaderError

getBufferCapacity

public final int getBufferCapacity(java.lang.String varName,
                                   java.lang.String targetType,
                                   int[] recordRange)
                            throws CDFException.ReaderError

Throws:

CDFException.ReaderError

getBuffer

public final java.nio.ByteBuffer getBuffer(java.lang.String varName,
                                           java.lang.String targetType,
                                           int[] recordRange,
                                           boolean preserve,
                                           java.nio.ByteBuffer buffer)
                                    throws CDFException.ReaderError

Throws:

CDFException.ReaderError