Package ucar.nc2

Class Variable

    • Field Detail

      • permitCaching

        public static boolean permitCaching
        Globally permit or prohibit caching. For use during testing and debugging.

        A true value for this field does not indicate whether a Variable is caching, only that it's permitted to cache.

      • defaultSizeToCache

        public static int defaultSizeToCache

      • defaultCoordsSizeToCache

        public static int defaultCoordsSizeToCache

      • debugCaching

        protected static boolean debugCaching

      • hashCode

        protected int hashCode

      • spiObject

        protected Object spiObject

      • shape

        protected int[] shape

      • isVariableLength

        protected boolean isVariableLength

      • elementSize

        protected int elementSize

      • sizeToCache

        protected int sizeToCache

    • Constructor Detail

      • Variable

        @Deprecated
protected Variable()
        Deprecated.
        Use Variable.builder()

      • Variable

        @Deprecated
public Variable​(NetcdfFile ncfile,
                Group group,
                Structure parent,
                String shortName)
        Deprecated.
        Use Variable.builder()
        Create a Variable. Also must call setDataType() and setDimensions()
        Parameters:
        ncfile - the containing NetcdfFile.
        group - the containing group; if null, use rootGroup
        parent - parent Structure, may be null
        shortName - variable shortName, must be unique within the Group

      • Variable

        @Deprecated
public Variable​(NetcdfFile ncfile,
                Group group,
                Structure parent,
                String shortName,
                DataType dtype,
                String dims)
        Deprecated.
        Use Variable.builder()
        Create a Variable. Also must call setDataType() and setDimensions()
        Parameters:
        ncfile - the containing NetcdfFile.
        group - the containing group; if null, use rootGroup
        parent - parent Structure, may be null
        shortName - variable shortName, must be unique within the Group
        dtype - the Variable's DataType
        dims - space delimited list of dimension names. may be null or "" for scalars.

      • Variable

        @Deprecated
public Variable​(NetcdfFile ncfile,
                Group group,
                Structure parent,
                String shortName,
                DataType dtype,
                List<Dimension> dims)
        Deprecated.
        Use Variable.builder()
        Create a Variable. Also must call setDataType() and setDimensions()
        Parameters:
        ncfile - the containing NetcdfFile.
        group - the containing group; if null, use rootGroup
        parent - parent Structure, may be null
        shortName - variable shortName, must be unique within the Group
        dtype - the Variable's DataType
        dims - dimension names.

      • Variable

        @Deprecated
public Variable​(Variable from)
        Deprecated.
        Use Variable.builder()
        Copy constructor. The returned Variable is mutable. It shares the cache object and the iosp Object, attributes and dimensions with the original. Does not share the proxyReader. Use for section, slice, "logical views" of original variable.
        Parameters:
        from - copy from this Variable.

    • Method Detail

      • getDAPName

        @Deprecated
public static String getDAPName​(Variable v)
        Deprecated.
        Will be moved to opendap package in 6.

      • getShape

        public int[] getShape()
        Get the shape: length of Variable in each dimension. A scalar (rank 0) will have an int[0] shape.
        Specified by:
        getShape in interface VariableSimpleIF
        Returns:
        int array whose length is the rank of this Variable and whose values equal the length of that Dimension.

      • getShape

        public int getShape​(int index)
        Get the size of the ith dimension
        Parameters:
        index - which dimension
        Returns:
        size of the ith dimension

      • getSize

        public long getSize()
        Get the total number of elements in the Variable. If this is an unlimited Variable, will use the current number of elements. If this is a Sequence, will return 1. If variable length, will skip vlen dimensions
        Returns:
        total number of elements in the Variable.

      • getElementSize

        public int getElementSize()
        Get the number of bytes for one element of this Variable. For Variables of primitive type, this is equal to getDataType().getSize(). Variables of String type don't know their size, so what they return is undefined. Variables of Structure type return the total number of bytes for all the members of one Structure, plus possibly some extra padding, depending on the underlying format. Variables of Sequence type return the number of bytes of one element.
        Returns:
        total number of bytes for the Variable

      • getRank

        public int getRank()
        Get the number of dimensions of the Variable, aka the rank.
        Specified by:
        getRank in interface VariableSimpleIF
        Returns:
        Variable rank

      • getParentGroupOrRoot

        @Deprecated
public Group getParentGroupOrRoot()
        Deprecated.
        Will go away in ver6, shouldn't be needed when builders are used.
        Get the parent group, or if null, the root group.

      • isMetadata

        public boolean isMetadata()
        Is this variable metadata?. True if its values need to be included explicitly in NcML output.
        Returns:
        true if Variable values need to be included in NcML

      • isScalar

        public boolean isScalar()
        Whether this is a scalar Variable (rank == 0).
        Returns:
        true if Variable has rank 0

      • isVariableLength

        public boolean isVariableLength()
        Does this variable have a variable length dimension? If so, it has as one of its dimensions Dimension.VLEN.
        Returns:
        true if Variable has a variable length dimension?

      • isUnlimited

        public boolean isUnlimited()
        Can this variable's size grow?. This is equivalent to saying at least one of its dimensions is unlimited.
        Returns:
        boolean true iff this variable can grow

      • getDimensions

        public com.google.common.collect.ImmutableList<Dimension> getDimensions()
        Get the list of dimensions used by this variable. The most slowly varying (leftmost for Java and C programmers) dimension is first. For scalar variables, the list is empty.
        Specified by:
        getDimensions in interface VariableSimpleIF
        Returns:
        List, will be ImmutableList in ver 6.

      • getDimension

        public Dimension getDimension​(int i)
        Get the ith dimension.
        Parameters:
        i - index of the dimension.
        Returns:
        requested Dimension, or null if i is out of bounds.

      • getDimensionsString

        public String getDimensionsString()
        Get the list of Dimension names, space delineated.
        Returns:
        Dimension names, space delineated

      • findDimensionIndex

        public int findDimensionIndex​(String name)
        Find the index of the named Dimension in this Variable.
        Parameters:
        name - the name of the dimension
        Returns:
        the index of the named Dimension, or -1 if not found.

      • getDescription

        public String getDescription()
        Get the description of the Variable. Default is to use CDM.LONG_NAME attribute value. If not exist, look for "description", "title", or "standard_name" attribute value (in that order).
        Specified by:
        getDescription in interface VariableSimpleIF
        Returns:
        description, or null if not found.

      • getUnitsString

        public String getUnitsString()
        Get the Unit String for the Variable. Looks for the CDM.UNITS attribute value
        Specified by:
        getUnitsString in interface VariableSimpleIF
        Returns:
        unit string, or null if not found.

      • getRanges

        public com.google.common.collect.ImmutableList<Range> getRanges()
        Get shape as a List of Range objects. The List is immutable.
        Returns:
        List of Ranges, one for each Dimension.

      • getShapeAsSection

        public Section getShapeAsSection()
        Get shape as a Section object.
        Returns:
        Section containing List, one for each Dimension.

      • setProxyReader

        @Deprecated
public void setProxyReader​(ProxyReader proxyReader)
        Deprecated.
        Use Variable.builder()

      • section

        public Variable section​(List<Range> ranges)
                 throws InvalidRangeException
        Create a new Variable that is a logical subsection of this Variable. No data is read until a read method is called on it.
        Parameters:
        ranges - List of type ucar.ma2.Range, with size equal to getRank(). Each Range corresponds to a Dimension, and specifies the section of data to read in that Dimension. A Range object may be null, which means use the entire dimension.
        Returns:
        a new Variable which is a logical section of this Variable.
        Throws:
        InvalidRangeException - if shape and range list don't match

      • section

        public Variable section​(Section subsection)
                 throws InvalidRangeException
        Create a new Variable that is a logical subsection of this Variable. No data is read until a read method is called on it.
        Parameters:
        subsection - Section of this variable. Each Range in the section corresponds to a Dimension, and specifies the section of data to read in that Dimension. A Range object may be null, which means use the entire dimension.
        Returns:
        a new Variable which is a logical section of this Variable.
        Throws:
        InvalidRangeException - if section not compatible with shape

      • slice

        public Variable slice​(int dim,
                      int value)
               throws InvalidRangeException
        Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value. This reduces rank by 1. No data is read until a read method is called on it.
        Parameters:
        dim - which dimension to fix
        value - at what index value
        Returns:
        a new Variable which is a logical slice of this Variable.
        Throws:
        InvalidRangeException - if dimension or value is illegal

      • reduce

        public Variable reduce​(List<Dimension> dims)
        Create a new Variable that is a logical view of this Variable, by eliminating the specified dimension(s) of length 1. No data is read until a read method is called on it.
        Parameters:
        dims - list of dimensions of length 1 to reduce
        Returns:
        a new Variable which is a logical slice of this Variable.

      • getNetcdfFile

        @Nullable
public NetcdfFile getNetcdfFile()
        Get the NetcdfFile that this variable is contained in. May be null.

      • getFileTypeId

        @Nullable
public String getFileTypeId()

      • lookupEnumString

        @Nullable
public String lookupEnumString​(int val)
        Lookup the enum string for this value. Can only be called on enum types, where dataType.isEnum() is true.
        Parameters:
        val - the integer value of this enum
        Returns:
        the String value

      • setEnumTypedef

        @Deprecated
public void setEnumTypedef​(EnumTypedef enumTypedef)
        Deprecated.
        Use Variable.builder()
        Public by accident.
        Parameters:
        enumTypedef - set the EnumTypedef, only use if getDataType.isEnum()

      • getEnumTypedef

        public EnumTypedef getEnumTypedef()
        Get the EnumTypedef, only use if getDataType.isEnum()
        Returns:
        enumTypedef or null if !getDataType.isEnum()

      • read

        public Array read​(int[] origin,
                  int[] shape)
           throws IOException,
                  InvalidRangeException
        Read a section of the data for this Variable and return a memory resident Array. The Array has the same element type as the Variable, and the requested shape. Note that this does not do rank reduction, so the returned Array has the same rank as the Variable. Use Array.reduce() for rank reduction.

        assert(origin[ii] + shape[ii]*stride[ii] <= Variable.shape[ii]);

        Parameters:
        origin - int array specifying the starting index. If null, assume all zeroes.
        shape - int array specifying the extents in each dimension. This becomes the shape of the returned Array.
        Returns:
        the requested data in a memory-resident Array
        Throws:
        IOException
        InvalidRangeException

      • read

        public Array read​(Section section)
           throws IOException,
                  InvalidRangeException
        Read a section of the data for this Variable from the netcdf file and return a memory resident Array. The Array has the same element type as the Variable, and the requested shape. Note that this does not do rank reduction, so the returned Array has the same rank as the Variable. Use Array.reduce() for rank reduction.

        If the Variable is a member of an array of Structures, this returns only the variable's data in the first Structure, so that the Array shape is the same as the Variable. To read the data in all structures, use ncfile.readSectionSpec().

        Note this only allows you to specify a subset of this variable. If the variable is nested in an array of structures and you want to subset that, use NetcdfFile.read(String sectionSpec, boolean flatten);

        Parameters:
        section - list of Range specifying the section of data to read. Must be null or same rank as variable. If list is null, assume all data. Each Range corresponds to a Dimension. If the Range object is null, it means use the entire dimension.
        Returns:
        the requested data in a memory-resident Array
        Throws:
        IOException - if error
        InvalidRangeException - if section is invalid

      • read

        public Array read()
           throws IOException
        Read all the data for this Variable and return a memory resident Array. The Array has the same element type and shape as the Variable.

        If the Variable is a member of an array of Structures, this returns only the variable's data in the first Structure, so that the Array shape is the same as the Variable. To read the data in all structures, use ncfile.readSection().

        Returns:
        the requested data in a memory-resident Array.
        Throws:
        IOException

      • readScalarString

        public String readScalarString()
                        throws IOException
        Get the value as a String for a scalar Variable. May also be one-dimensional of length 1. May also be one-dimensional of type CHAR, which wil be turned into a scalar String.
        Throws:
        IOException - if theres an IO Error
        UnsupportedOperationException - if not a scalar or one-dimensional.
        ClassCastException - if data type not DataType.STRING or DataType.CHAR.

      • getParentGroup

        public Group getParentGroup()
        Get its containing Group. Not deprecated. LOOK if you relied on Group being set during construction, use getParentGroupOrRoot().
        Overrides:
        getParentGroup in class CDMNode
        Returns:
        parent Group

      • getParentStructure

        @Nullable
public Structure getParentStructure()
        Get its parent structure, or null if not in structure Not deprecated.
        Overrides:
        getParentStructure in class CDMNode
        Returns:
        parent structure

      • isMemberOfStructure

        public boolean isMemberOfStructure()
        Test for presence of parent Structure. Not deprecated.
        Overrides:
        isMemberOfStructure in class CDMNode
        Returns:
        true iff struct != null

      • getFullName

        public String getFullName()
        Get the full name of this Variable. Certain characters are backslash escaped (see NetcdfFiles.getFullName(Variable)) Not deprecated.
        Specified by:
        getFullName in interface VariableSimpleIF
        Overrides:
        getFullName in class CDMNode
        Returns:
        full name with backslash escapes

      • getNameAndDimensions

        public String getNameAndDimensions()
        Get the display name plus the dimensions, eg 'float name(dim1, dim2)'
        Returns:
        display name plus the dimensions

      • getNameAndDimensions

        public String getNameAndDimensions​(boolean strict)
        Get the display name plus the dimensions, eg 'float name(dim1, dim2)'
        Parameters:
        strict - strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escaping
        Returns:
        display name plus the dimensions

      • getNameAndDimensions

        @Deprecated
public void getNameAndDimensions​(StringBuilder buf)
        Deprecated.
        use CDLWriter
        Get the display name plus the dimensions, eg 'name(dim1, dim2)'
        Parameters:
        buf - add info to this StringBuilder

      • getNameAndDimensions

        @Deprecated
public void getNameAndDimensions​(StringBuffer buf)
        Deprecated.
        use getNameAndDimensions(StringBuilder buf)
        Get the display name plus the dimensions, eg 'name(dim1, dim2)'
        Parameters:
        buf - add info to this StringBuffer

      • getNameAndDimensions

        @Deprecated
public void getNameAndDimensions​(StringBuilder buf,
                                 boolean useFullName,
                                 boolean strict)
        Deprecated.
        use CDLWriter
        Add display name plus the dimensions to the StringBuffer
        Parameters:
        buf - add info to this
        useFullName - use full name else short name. strict = true implies short name
        strict - strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escaping

      • getNameAndDimensions

        public void getNameAndDimensions​(Formatter buf,
                                 boolean useFullName,
                                 boolean strict)
        Add display name plus the dimensions to the Formatter
        Parameters:
        buf - add info to this
        useFullName - use full name else short name. strict = true implies short name
        strict - strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escaping

      • writeCDL

        @Deprecated
public String writeCDL​(boolean useFullName,
                       boolean strict)
        Deprecated.
        use CDLWriter
        CDL representation of a Variable.
        Parameters:
        useFullName - use full name, else use short name
        strict - strictly comply with ncgen syntax
        Returns:
        CDL representation of the Variable.

      • writeCDL

        @Deprecated
protected void writeCDL​(Formatter buf,
                        Indent indent,
                        boolean useFullName,
                        boolean strict)
        Deprecated.
        use CDLWriter

      • toStringDebug

        public String toStringDebug()
        String representation of Variable and its attributes.

      • extraInfo

        protected String extraInfo()

      • getDatasetLocation

        public String getDatasetLocation()
        The location of the dataset this belongs to. Labeling purposes only.

      • equals

        public boolean equals​(Object oo)
        Instances which have same content are equal.
        Overrides:
        equals in class Object

      • hashCode

        public int hashCode()
        Override Object.hashCode() to implement equals.
        Overrides:
        hashCode in class Object

      • setDataType

        @Deprecated
public void setDataType​(DataType dataType)
        Deprecated.
        Use Variable.builder()
        Set the data type
        Parameters:
        dataType - set to this value

      • setName

        @Deprecated
public String setName​(String shortName)
        Deprecated.
        Use Variable.builder()
        Set the short name, converting to valid CDM object name if needed.
        Parameters:
        shortName - set to this value
        Returns:
        valid CDM object name

      • setParentGroup

        @Deprecated
public void setParentGroup​(Group group)
        Deprecated.
        Use Variable.builder()
        Set the parent group.
        Overrides:
        setParentGroup in class CDMNode
        Parameters:
        group - set to this value

      • setElementSize

        @Deprecated
public void setElementSize​(int elementSize)
        Deprecated.
        Use Variable.builder()
        Set the element size. Usually elementSize is determined by the dataType, use this only for exceptional cases.
        Parameters:
        elementSize - set to this value

      • findAttributeString

        public String findAttributeString​(String attName,
                                  String defaultValue)
        Find a String-valued Attribute by name (ignore case), return the String value of the Attribute.
        Specified by:
        findAttributeString in interface AttributeContainer
        Returns:
        the attribute value, or defaultValue if not found

      • isEmpty

        public boolean isEmpty()
        Deprecated.
        Use attributes()
        Description copied from interface: AttributeContainer
        True is there are no attributes in the container.
        Specified by:
        isEmpty in interface AttributeContainer

      • findAttributeDouble

        @Deprecated
public double findAttributeDouble​(String attName,
                                  double defaultValue)
        Deprecated.
        Use attributes()
        Description copied from interface: AttributeContainer
        Find a Numeric Attribute by name (ignore case), return the double value of the Attribute.
        Specified by:
        findAttributeDouble in interface AttributeContainer
        Returns:
        the attribute value, or defaultValue if not found

      • findAttributeInteger

        @Deprecated
public int findAttributeInteger​(String attName,
                                int defaultValue)
        Deprecated.
        Use attributes()
        Description copied from interface: AttributeContainer
        Find a Numeric Attribute by name (ignore case), return the integer value of the Attribute.
        Specified by:
        findAttributeInteger in interface AttributeContainer
        Returns:
        the attribute value, or defaultValue if not found

      • remove

        @Deprecated
public boolean remove​(Attribute a)
        Deprecated.
        Use Variable.builder()
        Description copied from interface: AttributeContainer
        Remove an Attribute : uses the attribute hashCode to find it.
        Specified by:
        remove in interface AttributeContainer
        Parameters:
        a - remove this attribute
        Returns:
        true if was found and removed

      • removeAttribute

        @Deprecated
public boolean removeAttribute​(String attName)
        Deprecated.
        Use Variable.builder()
        Description copied from interface: AttributeContainer
        Remove an Attribute by name.
        Specified by:
        removeAttribute in interface AttributeContainer
        Parameters:
        attName - if exists, remove this attribute
        Returns:
        true if was found and removed

      • removeAttributeIgnoreCase

        @Deprecated
public boolean removeAttributeIgnoreCase​(String attName)
        Deprecated.
        Use Variable.builder()
        Description copied from interface: AttributeContainer
        Remove an Attribute by name, ignoring case
        Specified by:
        removeAttributeIgnoreCase in interface AttributeContainer
        Parameters:
        attName - if exists, remove this attribute
        Returns:
        true if was found and removed

      • setDimensions

        @Deprecated
public void setDimensions​(List<Dimension> dims)
        Deprecated.
        Use Variable.builder()
        Set the shape with a list of Dimensions. The Dimensions may be shared or not. Dimensions are in order, slowest varying first. Send a null for a scalar. Technically you can use Dimensions from any group; pragmatically you should only use Dimensions contained in the Variable's parent groups.
        Parameters:
        dims - list of type ucar.nc2.Dimension

      • resetShape

        @Deprecated
public void resetShape()
        Deprecated.
        Use Variable.builder()
        Use when dimensions have changed, to recalculate the shape.

      • setDimensions

        @Deprecated
public void setDimensions​(String dimString)
        Deprecated.
        Use Variable.builder()
        Set the dimensions using the dimensions names. The dimension is searched for recursively in the parent groups.
        Parameters:
        dimString - : whitespace separated list of dimension names, or '*' for Dimension.UNKNOWN, or number for anon dimension. null or empty String is a scalar.

      • resetDimensions

        @Deprecated
public void resetDimensions()
        Deprecated.
        Use Variable.builder()
        Reset the dimension array. Anonymous dimensions are left alone. Shared dimensions are searched for recursively in the parent groups.

      • setDimensionsAnonymous

        @Deprecated
public void setDimensionsAnonymous​(int[] shape)
                            throws InvalidRangeException
        Deprecated.
        Use Variable.builder()
        Set the dimensions using all anonymous (unshared) dimensions
        Parameters:
        shape - defines the dimension lengths. must be > 0, or -1 for VLEN
        Throws:
        InvalidRangeException - if any shape < 1

      • setIsScalar

        @Deprecated
public void setIsScalar()
        Deprecated.
        Use Variable.builder()
        Set this Variable to be a scalar

      • setDimension

        @Deprecated
public void setDimension​(int idx,
                         Dimension dim)
        Deprecated.
        Use Variable.builder()
        Replace a dimension with an equivalent one.
        Parameters:
        idx - index into dimension array
        dim - to set

      • isImmutable

        @Deprecated
public boolean isImmutable()
        Deprecated.
        Use Variable.builder()
        Is this Variable immutable
        Returns:
        if immutable

      • getSPobject

        public Object getSPobject()
        Get immutable service provider opaque object.

      • setSPobject

        @Deprecated
public void setSPobject​(Object spiObject)
        Deprecated.
        Do not use.

      • getSizeToCache

        public int getSizeToCache()
        If total data size is less than SizeToCache in bytes, then cache.
        Returns:
        size at which caching happens

      • setSizeToCache

        @Deprecated
public void setSizeToCache​(int sizeToCache)
        Deprecated.
        Use Variable.builder()
        Set the sizeToCache. If not set, use defaults
        Parameters:
        sizeToCache - size at which caching happens. < 0 means use defaults

      • setCaching

        @Deprecated
public void setCaching​(boolean caching)
        Deprecated.
        Use Variable.builder()
        Set whether to cache or not. Implies that the entire array will be stored, once read. Normally this is set automatically based on size of data.
        Parameters:
        caching - set if caching.

      • isCaching

        public boolean isCaching()
        Will this Variable be cached when read. Set externally, or calculated based on total size < sizeToCache.

        This will always return false if caching isn't permitted.

        Returns:
        true is caching

      • invalidateCache

        @Deprecated
public void invalidateCache()
        Deprecated.
        Use Variable.builder()
        Note that standalone Ncml caches data values set in the Ncml. So one cannot invalidate those caches.

      • setCachedData

        @Deprecated
public void setCachedData​(Array cacheData)
        Deprecated.
        Use Variable.builder()

      • setCachedData

        @Deprecated
public void setCachedData​(Array cacheData,
                          boolean isMetadata)
        Deprecated.
        Use Variable.builder()
        Set the data cache
        Parameters:
        cacheData - cache this Array
        isMetadata - : synthesized data, set true if must be saved in NcML output (ie data not actually in the file).

      • createNewCache

        public void createNewCache()
        Create a new data cache, use this when you dont want to share the cache.

      • hasCachedData

        public boolean hasCachedData()
        Has data been read and cached. Use only on a Variable, not a subclass.
        Returns:
        true if data is read and cached

      • setValues

        @Deprecated
public void setValues​(int npts,
                      double start,
                      double incr)
        Deprecated.
        Use Variable.builder()
        Generate the list of values from a starting value and an increment. Will reshape to variable if needed.
        Parameters:
        npts - number of values, must = v.getSize()
        start - starting value
        incr - increment

      • getDimensionsAll

        @Deprecated
public List<Dimension> getDimensionsAll()
        Deprecated.
        use Dimensions.makeDimensionsAll(Variable);
        Get list of Dimensions, including parents if any.
        Returns:
        array of Dimension, rank of v plus all parents.

      • getShapeAll

        @Deprecated
public int[] getShapeAll()
        Deprecated.
        use Dimensions.makeDimensionsAll(Variable);

      • isCoordinateVariable

        public boolean isCoordinateVariable()
        Calculate if this is a classic coordinate variable: has same name as its first dimension. If type char, must be 2D, else must be 1D.
        Returns:
        true if a coordinate variable.

      • toBuilder

        public Variable.Builder<?> toBuilder()
        Turn into a mutable Builder. Can use toBuilder().build() to copy.

      • builder

        public static Variable.Builder<?> builder()
        Get Builder for this class that allows subclassing.
        See Also:
        "https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"

      • isUnknownLength

        public boolean isUnknownLength()
        Deprecated.
        use isVariableLength()
        Returns:
        isVariableLength()