gsfc.nssdc.cdf

Class CDFData

java.lang.Object

gsfc.nssdc.cdf.CDFData

All Implemented Interfaces:

CDFConstants, CDFObject

public class CDFData
extends java.lang.Object
implements CDFObject, CDFConstants

This class acts as the glue between the Java code and the Java Native Interface (JNI) code. This class applies only to the Variable object. It handles its data. This class translates a multi-dimensional array data into a 1-dimensional (1D) array prior to sending data to the JNI code for processing. Similarly, data retrieved in 1D array from the JNI code is properly dimensioned for usage or further manipulation.

Version:

1.0, 2.0 03/18/05 Selection of current CDF and variable are done as part of operations passed to JNI. JNI call is synchronized so only one process is allowed in a JVM, due to multi-thread safety. The select method will never be called., 3.0 06/09/09 The number of dimesions returned from the get method depends on the variable dimensions and dimesional elements: e.g., 2-dim (2x1 or 1x2) will have a 2-dim, not 1-dim, object returned, while 2-dim (1x1) returns an object of a single item, not an array.

See Also:

Variable, CDFException

Field Summary

Fields inherited from interface gsfc.nssdc.cdf.CDFConstants

AHUFF_COMPRESSION, ALPHAOSF1_DECODING, ALPHAOSF1_ENCODING, ALPHAVMSd_DECODING, ALPHAVMSd_ENCODING, ALPHAVMSg_DECODING, ALPHAVMSg_ENCODING, ALPHAVMSi_DECODING, ALPHAVMSi_ENCODING, ARM_BIG_DECODING, ARM_BIG_ENCODING, ARM_LITTLE_DECODING, ARM_LITTLE_ENCODING, ATTR_, ATTR_EXISTENCE_, ATTR_EXISTS, ATTR_MAXgENTRY_, ATTR_MAXrENTRY_, ATTR_MAXzENTRY_, ATTR_NAME_, ATTR_NAME_TRUNC, ATTR_NUMBER_, ATTR_NUMgENTRIES_, ATTR_NUMrENTRIES_, ATTR_NUMzENTRIES_, ATTR_SCOPE_, BACKWARD_, BACKWARDFILEoff, BACKWARDFILEon, BAD_ALLOCATE_RECS, BAD_ARGUMENT, BAD_ATTR_NAME, BAD_ATTR_NUM, BAD_BLOCKING_FACTOR, BAD_CACHE_SIZE, BAD_CDF_EXTENSION, BAD_CDF_ID, BAD_CDF_NAME, BAD_CDFSTATUS, BAD_CHECKSUM, BAD_COMPRESSION_PARM, BAD_DATA_TYPE, BAD_DECODING, BAD_DIM_COUNT, BAD_DIM_INDEX, BAD_DIM_INTERVAL, BAD_DIM_SIZE, BAD_ENCODING, BAD_ENTRY_NUM, BAD_FNC_OR_ITEM, BAD_FORMAT, BAD_INITIAL_RECS, BAD_MAJORITY, BAD_MALLOC, BAD_NEGtoPOSfp0_MODE, BAD_NUM_DIMS, BAD_NUM_ELEMS, BAD_NUM_STRINGS, BAD_NUM_VARS, BAD_READONLY_MODE, BAD_REC_COUNT, BAD_REC_INTERVAL, BAD_REC_NUM, BAD_SCOPE, BAD_SCRATCH_DIR, BAD_SPARSEARRAYS_PARM, BAD_VAR_NAME, BAD_VAR_NUM, BAD_zMODE, BADDATE_LEAPSECOND_UPDATED, BeginUnixTimeEPOCH, BeginUnixTimeEPOCH16, BLOCKINGFACTOR_TOO_LARGE, BLOCKINGFACTOR_TOO_SMALL, BLOCKINGFACTOR_TOO_SMALL2, CANNOT_ALLOCATE_RECORDS, CANNOT_CHANGE, CANNOT_COMPRESS, CANNOT_CONVERT_WIDECHAR, CANNOT_COPY, CANNOT_INSERT_RECORDS, CANNOT_SPARSEARRAYS, CANNOT_SPARSERECORDS, CDF_, CDF_ACCESS_, CDF_ATTR_NAME_LEN, CDF_ATTR_NAME_LEN256, CDF_BYTE, CDF_CACHESIZE_, CDF_CHAR, CDF_CHECKSUM_, CDF_CLOSE_ERROR, CDF_COMPRESSION_, CDF_COPYRIGHT_, CDF_COPYRIGHT_LEN, CDF_CREATE_ERROR, CDF_DECODING_, CDF_DELETE_ERROR, CDF_DOUBLE, CDF_ENCODING_, CDF_EPOCH, CDF_EPOCH16, CDF_EXISTS, CDF_FLOAT, CDF_FORMAT_, CDF_INCREMENT_, CDF_INFO_, CDF_INT1, CDF_INT2, CDF_INT4, CDF_INT8, CDF_INTERNAL_ERROR, CDF_LEAPSECONDLASTUPDATED_, CDF_MAJORITY_, CDF_MAX_DIMS, CDF_MAX_PARMS, CDF_MIN_DIMS, CDF_NAME_, CDF_NAME_TRUNC, CDF_NEGtoPOSfp0_MODE_, CDF_NUMATTRS_, CDF_NUMgATTRS_, CDF_NUMrVARS_, CDF_NUMvATTRS_, CDF_NUMzVARS_, CDF_OK, CDF_OPEN_ERROR, CDF_PATHNAME_LEN, CDF_READ_ERROR, CDF_READONLY_MODE_, CDF_REAL4, CDF_REAL8, CDF_RELEASE_, CDF_SAVE_ERROR, CDF_SCRATCHDIR_, CDF_STATUS_, CDF_STATUSTEXT_LEN, CDF_TIME_TT2000, CDF_UCHAR, CDF_UINT1, CDF_UINT2, CDF_UINT4, CDF_VAR_NAME_LEN, CDF_VAR_NAME_LEN256, CDF_VERSION_, CDF_WARN, CDF_WRITE_ERROR, CDF_zMODE_, CDFwithSTATS_, CHECKSUM_, CHECKSUM_ERROR, CHECKSUM_NOT_ALLOWED, CLOSE_, COLUMN_MAJOR, COMPRESS_CACHESIZE_, COMPRESSION_ERROR, CONFIRM_, CORRUPTED_V2_CDF, CORRUPTED_V3_CDF, CREATE_, CURgENTRY_EXISTENCE_, CURrENTRY_EXISTENCE_, CURzENTRY_EXISTENCE_, DATATYPE_MISMATCH, DATATYPE_SIZE_, DECOMPRESSION_ERROR, DECSTATION_DECODING, DECSTATION_ENCODING, DEFAULT_BYTE_PADVALUE, DEFAULT_CHAR_PADVALUE, DEFAULT_DOUBLE_PADVALUE, DEFAULT_EPOCH_PADVALUE, DEFAULT_EPOCH16_PADVALUE, DEFAULT_FLOAT_PADVALUE, DEFAULT_INT1_PADVALUE, DEFAULT_INT2_PADVALUE, DEFAULT_INT4_PADVALUE, DEFAULT_INT8_PADVALUE, DEFAULT_REAL4_PADVALUE, DEFAULT_REAL8_PADVALUE, DEFAULT_TT2000_PADVALUE, DEFAULT_UCHAR_PADVALUE, DEFAULT_UINT1_PADVALUE, DEFAULT_UINT2_PADVALUE, DEFAULT_UINT4_PADVALUE, DELETE_, DID_NOT_COMPRESS, EMPTY_COMPRESSED_CDF, END_OF_VAR, EPOCH_STRING_LEN, EPOCH_STRING_LEN_EXTEND, EPOCH1_STRING_LEN, EPOCH1_STRING_LEN_EXTEND, EPOCH2_STRING_LEN, EPOCH2_STRING_LEN_EXTEND, EPOCH3_STRING_LEN, EPOCH3_STRING_LEN_EXTEND, EPOCH4_STRING_LEN, EPOCH4_STRING_LEN_EXTEND, EPOCHx_FORMAT_MAX, EPOCHx_STRING_MAX, FILLED_TT2000_VALUE, FORCED_PARAMETER, FUNCTION_NOT_SUPPORTED, gENTRY_, gENTRY_DATA_, gENTRY_DATASPEC_, gENTRY_DATATYPE_, gENTRY_EXISTENCE_, gENTRY_NUMELEMS_, GET_, GETCDFCHECKSUM_, GETCDFFILEBACKWARD_, GETCDFVALIDATE_, GETLEAPSECONDSENVVAR_, GLOBAL_SCOPE, GZIP_COMPRESSION, HOST_DECODING, HOST_ENCODING, HP_DECODING, HP_ENCODING, HUFF_COMPRESSION, IA64VMSd_DECODING, IA64VMSd_ENCODING, IA64VMSg_DECODING, IA64VMSg_ENCODING, IA64VMSi_DECODING, IA64VMSi_ENCODING, IBM_PC_OVERFLOW, IBMPC_DECODING, IBMPC_ENCODING, IBMRS_DECODING, IBMRS_ENCODING, ILLEGAL_EPOCH_FIELD, ILLEGAL_EPOCH_VALUE, ILLEGAL_FOR_SCOPE, ILLEGAL_IN_zMODE, ILLEGAL_ON_V1_CDF, ILLEGAL_TT2000_VALUE, IS_A_NETCDF, LIB_COPYRIGHT_, LIB_INCREMENT_, LIB_RELEASE_, LIB_subINCREMENT_, LIB_VERSION_, MAC_DECODING, MAC_ENCODING, MD5_CHECKSUM, MULTI_FILE, MULTI_FILE_FORMAT, NA_FOR_VARIABLE, NEGATIVE_FP_ZERO, NEGtoPOSfp0off, NEGtoPOSfp0on, NETWORK_DECODING, NETWORK_ENCODING, NeXT_DECODING, NeXT_ENCODING, NO_ATTR_SELECTED, NO_CDF_SELECTED, NO_CHECKSUM, NO_COMPRESSION, NO_DELETE_ACCESS, NO_ENTRY_SELECTED, NO_MORE_ACCESS, NO_PADVALUE_SPECIFIED, NO_SPARSEARRAYS, NO_SPARSERECORDS, NO_STATUS_SELECTED, NO_SUCH_ATTR, NO_SUCH_CDF, NO_SUCH_ENTRY, NO_SUCH_RECORD, NO_SUCH_VAR, NO_VAR_SELECTED, NO_VARS_IN_CDF, NO_WRITE_ACCESS, NONE_CHECKSUM, NOT_A_CDF, NOT_A_CDF_OR_NOT_SUPPORTED, NOVARY, NULL_, OPEN_, OPTIMAL_ENCODING_TREES, OTHER_CHECKSUM, PAD_SPARSERECORDS, PPC_DECODING, PPC_ENCODING, PRECEEDING_RECORDS_ALLOCATED, PREV_SPARSERECORDS, PUT_, READ_ONLY_DISTRIBUTION, READ_ONLY_MODE, READONLYoff, READONLYon, rENTRY_, rENTRY_DATA_, rENTRY_DATASPEC_, rENTRY_DATATYPE_, rENTRY_EXISTENCE_, rENTRY_NAME_, rENTRY_NUMELEMS_, rENTRY_NUMSTRINGS_, rENTRY_STRINGSDATA_, RLE_COMPRESSION, RLE_OF_ZEROs, ROW_MAJOR, rVAR_, rVAR_ALLOCATEBLOCK_, rVAR_ALLOCATEDFROM_, rVAR_ALLOCATEDTO_, rVAR_ALLOCATERECS_, rVAR_BLOCKINGFACTOR_, rVAR_CACHESIZE_, rVAR_COMPRESSION_, rVAR_DATA_, rVAR_DATASPEC_, rVAR_DATATYPE_, rVAR_DIMVARYS_, rVAR_EXISTENCE_, rVAR_HYPERDATA_, rVAR_INITIALRECS_, rVAR_MAXallocREC_, rVAR_MAXREC_, rVAR_NAME_, rVAR_nINDEXENTRIES_, rVAR_nINDEXLEVELS_, rVAR_nINDEXRECORDS_, rVAR_NUMallocRECS_, rVAR_NUMBER_, rVAR_NUMELEMS_, rVAR_NUMRECS_, rVAR_PADVALUE_, rVAR_RECORDS_, rVAR_RECORDS_RENUMBER_, rVAR_RECVARY_, rVAR_RESERVEPERCENT_, rVAR_SEQDATA_, rVAR_SEQPOS_, rVAR_SPARSEARRAYS_, rVAR_SPARSERECORDS_, rVARs_CACHESIZE_, rVARs_DIMCOUNTS_, rVARs_DIMINDICES_, rVARs_DIMINTERVALS_, rVARs_DIMSIZES_, rVARs_MAXREC_, rVARs_NUMDIMS_, rVARs_RECCOUNT_, rVARs_RECDATA_, rVARs_RECINTERVAL_, rVARs_RECNUMBER_, SAVE_, SCRATCH_CREATE_ERROR, SCRATCH_DELETE_ERROR, SCRATCH_READ_ERROR, SCRATCH_WRITE_ERROR, SELECT_, SGi_DECODING, SGi_ENCODING, SINGLE_FILE, SINGLE_FILE_FORMAT, SOME_ALREADY_ALLOCATED, STAGE_CACHESIZE_, STATUS_TEXT_, STRING_NOT_UTF8_ENCODING, STRINGDELIMITER, SUN_DECODING, SUN_ENCODING, TOO_MANY_PARMS, TOO_MANY_VARS, TRY_TO_READ_NONSTRING_DATA, TT2000_0_STRING_LEN, TT2000_1_STRING_LEN, TT2000_2_STRING_LEN, TT2000_3_STRING_LEN, TT2000_4_STRING_LEN, TT2000_CDF_MAYNEEDUPDATE, TT2000_TIME_ERROR, TT2000_USED_OUTDATED_TABLE, UNABLE_TO_PROCESS_CDF, UNKNOWN_COMPRESSION, UNKNOWN_SPARSENESS, UNSUPPORTED_OPERATION, VALIDATE_, VALIDATEFILEoff, VALIDATEFILEon, VAR_ALREADY_CLOSED, VAR_CLOSE_ERROR, VAR_CREATE_ERROR, VAR_DELETE_ERROR, VAR_EXISTS, VAR_NAME_TRUNC, VAR_OPEN_ERROR, VAR_READ_ERROR, VAR_SAVE_ERROR, VAR_WRITE_ERROR, VARIABLE_SCOPE, VARY, VAX_DECODING, VAX_ENCODING, VIRTUAL_RECORD_DATA, zENTRY_, zENTRY_DATA_, zENTRY_DATASPEC_, zENTRY_DATATYPE_, zENTRY_EXISTENCE_, zENTRY_NAME_, zENTRY_NUMELEMS_, zENTRY_NUMSTRINGS_, zENTRY_STRINGSDATA_, ZLIB_COMPRESS_ERROR, ZLIB_UNCOMPRESS_ERROR, zMODEoff, zMODEon1, zMODEon2, zVAR_, zVAR_ALLOCATEBLOCK_, zVAR_ALLOCATEDFROM_, zVAR_ALLOCATEDTO_, zVAR_ALLOCATERECS_, zVAR_BLOCKINGFACTOR_, zVAR_CACHESIZE_, zVAR_COMPRESSION_, zVAR_DATA_, zVAR_DATASPEC_, zVAR_DATATYPE_, zVAR_DIMCOUNTS_, zVAR_DIMINDICES_, zVAR_DIMINTERVALS_, zVAR_DIMSIZES_, zVAR_DIMVARYS_, zVAR_EXISTENCE_, zVAR_HYPERDATA_, zVAR_INITIALRECS_, zVAR_MAXallocREC_, zVAR_MAXREC_, zVAR_NAME_, zVAR_nINDEXENTRIES_, zVAR_nINDEXLEVELS_, zVAR_nINDEXRECORDS_, zVAR_NUMallocRECS_, zVAR_NUMBER_, zVAR_NUMDIMS_, zVAR_NUMELEMS_, zVAR_NUMRECS_, zVAR_PADVALUE_, zVAR_RECCOUNT_, zVAR_RECINTERVAL_, zVAR_RECNUMBER_, zVAR_RECORDS_, zVAR_RECORDS_RENUMBER_, zVAR_RECVARY_, zVAR_RESERVEPERCENT_, zVAR_SEQDATA_, zVAR_SEQPOS_, zVAR_SPARSEARRAYS_, zVAR_SPARSERECORDS_, zVARs_CACHESIZE_, zVARs_MAXREC_, zVARs_RECDATA_, zVARs_RECNUMBER_

Method Summary

Methods

Modifier and Type	Method and Description
void	delete() See the description of the getName() method in this class.
void	dump() Dump data information and values, one row at a time, to the stdErr.
void	dumpData() Dumps variable data, one row at a time per record.
void	dumpDataWithFormat(java.lang.String format) Dumps variable data, one row at a time per record, with format.
java.lang.Object	getData() Returns an object that is properly dimensioned.
long[]	getDimCounts() Gets the value of the dimension counts that represents the number of elements read or write starting at the location <dimension index> for a hyper get/put function.
long[]	getDimIndices() Gets the starting dimension index within a record for a hyper get/put function.
long[]	getDimIntervals() Gets the value of the dimension intervals that represent the number of elements to skip between reads or writes for a hyper get/put function.
int[]	getDimSizes() Gets the dimension sizes of this variable.
java.lang.String	getName() CDFData implements CDFObject to enable CDFDelegate calls.
int	getnDims() Gets the dimensionality of this variable.
java.lang.Object	getRawData() Returns an object of a 1-dimensional array, which presents a sequence of raw data values retrieved and presented by JNI from a CDF file.
long	getRecCount() Gets the number of records to read or write for a hyper get/put function.
long	getRecInterval() Gets the number of records to skip for a hyper get/put function.
long	getRecStart() Gets the record number at which a hyper get/put function starts.
void	rename(java.lang.String name) See the description of the getName() method in this class.

Methods inherited from class java.lang.Object

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

Method Detail

getData

public java.lang.Object getData()

Returns an object that is properly dimensioned. The returned object can be casted in an application for usage or further manipulation.

The following example retrieves the Temperature data. The user should know how the data was stored before casting the generic object to a variable.

    Variable var = cdf.getVariable("Temperature");
    CDFData data = var.getHyperDataObject (recNum, 
                                           recCount, 
                                           recInterval, 
                                           dimIndicies, 
                                           dimSizes, 
                                           dimCounts);
    long[][] temperature = (long [][]) data.getData(); 
 

Returns:

a generic Object that is properly dimensioned

getRawData

public java.lang.Object getRawData()

Returns an object of a 1-dimensional array, which presents a sequence of raw data values retrieved and presented by JNI from a CDF file. The data stream may or may not reflect how the data is stored in the file, depending the file majority. It is up to the calling application to decipher the data stream. Note: for column-major CDF files, the sequence of the returned data stream is reordered so data can be properly assigned into Java's arrays. Normally, getData method should be called so the retrieved data are properly dimensioned.

The following example retrieves the 2-D Temperature data. The user should know how to organize the data, e.g., number of records, row/column major, data type, data value sequence, etc.

    Variable var = cdf.getVariable("Temperature");
    CDFData data = var.getHyperDataObject (recNum,
                                           recCount,
                                           recInterval,
                                           dimIndicies,
                                           dimSizes,
                                           dimCounts);
    long[] temperature = (long []) data.getRawData();
 

Returns:

a generic Object that is properly dimensioned

getnDims

public int getnDims()

Gets the dimensionality of this variable.

    Variable var = cdf.getVariable("Temperature");
    CDFData data = var.getHyperDataObject (recNum,
                                           recCount,
                                           recInterval,
                                           dimIndicies,
                                           dimSizes,
                                           dimCounts);
    long[][] temperature = (long [][]) data.getData();
    nDims = data.getnDims();   // Gives the dimenionality of temperature
 

Returns:

the dimensionality of this variable

getDimSizes

public int[] getDimSizes()

Gets the dimension sizes of this variable. For example, 3 X 10 (3 rows and 10 columns) two-dimentional array is returned as an one-dimensional integer array, containing 3 in the first element and 10 in the second element.

Returns:

the dimension sizes of this variable

getRecStart

public long getRecStart()

Gets the record number at which a hyper get/put function starts.

Returns:

the starting record number for a hyper get/put function

getRecCount

public long getRecCount()

Gets the number of records to read or write for a hyper get/put function.

Returns:

the number of records involved for a hyper get/put function involves

getRecInterval

public long getRecInterval()

Gets the number of records to skip for a hyper get/put function. The record interval of 1 represents every record. The value of 2 represents every other record, the value of 3 represents every third record and so on.

Returns:

the value of record interval

getDimIndices

public long[] getDimIndices()

Gets the starting dimension index within a record for a hyper get/put function. Dimension index indicates where the data search started from within a record. Let's say a record is comprised of a 2x5 two-dimensional array (2 rows and 5 columns). If the index returned from this method has a value of {1,0}, then the data search was performed starting at the first element of the second row. Similarly, the value of {0,0} represents that the data search search was performed starting at the first element of the first record.

Returns:

the dimension index for this variable

getDimCounts

public long[] getDimCounts()

Gets the value of the dimension counts that represents the number of elements read or write starting at the location <dimension index> for a hyper get/put function.

Returns:

the dimension counts for this variable

getDimIntervals

public long[] getDimIntervals()

Gets the value of the dimension intervals that represent the number of elements to skip between reads or writes for a hyper get/put function. The value of 1 represents every element. The value of 2 represents every other element, and the value of 3 represents every third element and so on.

Returns:

the dimension intervals for this variable

dumpData

public void dumpData()

Dumps variable data, one row at a time per record. This is a generic utility for dumping data to a screen. Data can be scalar or 1-dimensional or multi-dimensional array of any data type. This method dumps the data without using format.

The following example retrieves the first record, comprised of 3x5 (3 rows and 5 columns) array, into a generic object and dumps its contents to screen one row at a time. In this case three rows will be displayed on a screen, each row containing 5 elements.

     CDFData data;
     long[] dimIndices   = {0,0};
     long[] dimIntervals = {3,5};
     long[] dimSizes     = {1,1}; 
     data = var.getHyperDataObject(0L,         // record start
                                   1,          // record counts 
                                   1,          // record interval
                                   dimIndices,
                                   dimSizes,
                                   dimIntervals);
     data.dumpData();
 

dumpDataWithFormat

public void dumpDataWithFormat(java.lang.String format)

Dumps variable data, one row at a time per record, with format. This is a generic * utility for dumping data to a screen. Data can be scalar or 1-dimensional or multi-dimensional array of any data type. The format is only applicable to variables of numerical data type. the format comes from variable's FORMAT attribute entry. Note: The FORMAT might be in original C or Fortran format form. This format is mainly used for floating point data. The following example retrieves the first record, comprised of 3x5 (3 rows and 5 columns) array, into a generic object and dumps its contents to screen one row at a time. In this case three rows will be displayed on a screen, each row containing 5 elements.

     CDFData data;
     String format = (String) var.getEntryData("FORMAT");
     long[] dimIndices   = {0,0};
     long[] dimIntervals = {3,5};
     long[] dimSizes     = {1,1}; 
     data = var.getHyperDataObject(0L,         // record start
                                   1,          // record counts 
                                   1,          // record interval
                                   dimIndices,
                                   dimSizes,
                                   dimIntervals);
     data.dumpDataWithFormat(format);
 

Parameters:

format - A string format

dump

public void dump()

Dump data information and values, one row at a time, to the stdErr. This method is provided for debugging purposes only. The information is printed in the following manner: <VAR_TYPE>/<VAR_#Elements> nDims:[sizes] recStart/recCount/recInterval/dimIndices/dimsSizes/dimIntervals/dataArraySignature <values row-by-row>

getName

public java.lang.String getName()

CDFData implements CDFObject to enable CDFDelegate calls. CDFObject specifies the following three methods: getName(), rename(String), and delete(). Since CDFData implements CDFObject, it must have the methods defined in CDFObject. That's why this method is here; it doesn't do anything.

Specified by:

getName in interface CDFObject

Returns:

the name of the current object

rename

public void rename(java.lang.String name)
            throws CDFException

See the description of the getName() method in this class.

Specified by:

rename in interface CDFObject

Parameters:

name - the new object name

Throws:

CDFException - No exception is thrown since this method is a placeholder

delete

public void delete()
            throws CDFException

See the description of the getName() method in this class.

Specified by:

delete in interface CDFObject

Throws:

CDFException - No exception is thrown since this method is a placeholder