Class Variable


  • public class Variable
    extends java.lang.Object
    Provides the metadata and record data for a CDF variable.

    At construction time, a map of where the records are stored is constructed, but the record data itself is not read unless or until one of the read methods is called.

    This interface does not currently support data reading in such a flexible way as the official CDF interface. You can read a record's worth of data at a time using either readRawRecord (which should be fairly efficient) or readShapedRecord (which may have to copy and possibly re-order the array, and may not be so efficient).

    Since:
    20 Jun 2013
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object createRawValueArray()
      Creates a workspace array suitable for use with this variable's reading methods.
      DataType getDataType()
      Returns the data type of this variable.
      VariableDescriptorRecord getDescriptor()
      Returns the VariableDescriptorRecord on which this Variable instance is based.
      java.lang.String getName()
      Returns this variable's name.
      int getNum()
      Returns the index number within the CDF of this variable.
      int getRecordCount()
      Returns the upper limit of records that may have values.
      boolean getRecordVariance()
      Indicates whether this variable has a value which is fixed for all records or can vary per record.
      Shaper getShaper()
      Returns an object that knows about the array dimensions of the data values.
      java.lang.String getSummary()
      Returns a short text string describing the type, shape and variance of this variable.
      boolean hasRecord​(int irec)
      Indicates whether a real distinct file-based record exists for the given index.
      boolean isZVariable()
      Indicates whether this variable is a zVariable or rVariable.
      void readRawRecord​(int irec, java.lang.Object rawValueArray)
      Reads the data from a single record into a supplied raw value array.
      java.lang.Object readShapedRecord​(int irec, boolean rowMajor, java.lang.Object rawValueArrayWorkspace)
      Reads the data from a single record and returns it as an object of a suitable type for this variable.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Variable

        public Variable​(VariableDescriptorRecord vdr,
                        CdfInfo cdfInfo,
                        RecordFactory recFact)
                 throws java.io.IOException
        Constructor.
        Parameters:
        vdr - variable descriptor record for the variable
        cdfInfo - global CDF information
        recFact - record factory
        Throws:
        java.io.IOException
    • Method Detail

      • getName

        public java.lang.String getName()
        Returns this variable's name.
        Returns:
        variable name
      • getNum

        public int getNum()
        Returns the index number within the CDF of this variable.
        Returns:
        variable num
      • isZVariable

        public boolean isZVariable()
        Indicates whether this variable is a zVariable or rVariable.
        Returns:
        true for zVariable, false for rVariable
      • getRecordCount

        public int getRecordCount()
        Returns the upper limit of records that may have values. The actual number of records may be lower than this in case of sparsity.
        Returns:
        maximum record count
      • getDataType

        public DataType getDataType()
        Returns the data type of this variable.
        Returns:
        data type
      • getShaper

        public Shaper getShaper()
        Returns an object that knows about the array dimensions of the data values.
        Returns:
        shaper
      • getRecordVariance

        public boolean getRecordVariance()
        Indicates whether this variable has a value which is fixed for all records or can vary per record.
        Returns:
        false for fixed, true for varying
      • getSummary

        public java.lang.String getSummary()
        Returns a short text string describing the type, shape and variance of this variable.
        Returns:
        text summary of variable characteristics
      • getDescriptor

        public VariableDescriptorRecord getDescriptor()
        Returns the VariableDescriptorRecord on which this Variable instance is based.
        Returns:
        variable descriptor record (rVDR or zVDR)
      • createRawValueArray

        public java.lang.Object createRawValueArray()
        Creates a workspace array suitable for use with this variable's reading methods. The returned array is a 1-dimensional array of a primitive type or of String.
        Returns:
        workspace array for data reading
      • hasRecord

        public boolean hasRecord​(int irec)
                          throws java.io.IOException
        Indicates whether a real distinct file-based record exists for the given index. Reading a record will give you a result in any case, but if this returns false it will be some kind of fixed or default value.
        Parameters:
        irec - record index
        Returns:
        true iff a file-based record exists for irec
        Throws:
        java.io.IOException
      • readRawRecord

        public void readRawRecord​(int irec,
                                  java.lang.Object rawValueArray)
                           throws java.io.IOException
        Reads the data from a single record into a supplied raw value array. The values are read into the supplied array in the order in which they are stored in the data stream, that is depending on the row/column majority of the CDF.

        The raw value array is as obtained from createRawValueArray().

        Parameters:
        irec - record index
        rawValueArray - workspace array, as created by the createRawValueArray method
        Throws:
        java.io.IOException
      • readShapedRecord

        public java.lang.Object readShapedRecord​(int irec,
                                                 boolean rowMajor,
                                                 java.lang.Object rawValueArrayWorkspace)
                                          throws java.io.IOException
        Reads the data from a single record and returns it as an object of a suitable type for this variable. If the variable type a scalar, then the return value will be one of the primitive wrapper types (Integer etc), otherwise it will be an array of primitive or String values. If the majority of the stored data does not match the rowMajor argument, the array elements will be rordered appropriately. If some of the dimension variances are false, the values will be duplicated accordingly. The Shaper returned from the getShaper() method can provide more information on the return value from this method.

        The workspace is as obtained from createRawValueArray().

        Parameters:
        irec - record index
        rowMajor - required majority of output array; true for row major, false for column major; only has an effect for dimensionality >=2
        rawValueArrayWorkspace - workspace array, as created by the createRawValueArray method
        Returns:
        a new object containing the shaped result (not the same object as rawValueArray
        Throws:
        java.io.IOException