Package ucar.nc2

Class Structure

  • All Implemented Interfaces:
    Comparable<VariableSimpleIF>, Iterable<Attribute>, AttributeContainer, ProxyReader, VariableSimpleIF
    Direct Known Subclasses:
    DODSStructure, Sequence, StructureDS, StructurePseudo
    public class Structure
extends Variable
    A Structure is a type of Variable that contains other Variables, like a struct in C. A Structure can be scalar or multidimensional.

    A call to structure.read() will read all of the data in a Structure, including nested structures, and returns an Array of StructureData, with all of the data in memory. If there is a nested sequence, the sequence data may be read into memory all at once, or it may be read in increments as the iteration proceeds.

    Generally, the programmer can assume that the data in one Structure are stored together, so that it is efficient to read an entire Structure, and then access the Variable data through the Arrays in the StructureData.

    • Field Detail

      • isSubset

        protected boolean isSubset

    • Constructor Detail

      • Structure

        @Deprecated
public Structure​(NetcdfFile ncfile,
                 Group group,
                 Structure parent,
                 String shortName)
        Deprecated.
        Use Structure.builder()
        Create a Structure "from scratch". Also must call 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

      • Structure

        @Deprecated
public Structure​(NetcdfFile ncfile,
                 Group group,
                 Structure parent,
                 String shortName,
                 List<Dimension> dimList)
        Deprecated.
        Use Structure.builder()
        Create a Structure "from scratch".
        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
        dimList - list of Dimensions

      • Structure

        @Deprecated
protected Structure​(Structure from)
        Deprecated.
        Use Structure.builder()
        Copy constructor.
        Parameters:
        from - copy from this

    • Method Detail

      • select

        public Structure select​(List<String> memberNames)
        Create a subset of the Structure consisting only of the given member variables
        Parameters:
        memberNames - list of Variable names, already a member
        Returns:
        Structure containing just those members

      • select

        public Structure select​(String varName)
        Create a subset of the Structure consisting only of the one member variable
        Parameters:
        varName - name of member Variable
        Returns:
        containing just that member

      • isSubset

        public boolean isSubset()
        Find if this was created from a subset() method.
        Returns:
        true if this is a subset

      • calcStructureSize

        protected int calcStructureSize()

      • isCaching

        public boolean isCaching()
        Caching is not allowed
        Overrides:
        isCaching in class Variable
        Returns:
        true is caching

      • setCaching

        public void setCaching​(boolean caching)
        Caching is not allowed
        Overrides:
        setCaching in class Variable
        Parameters:
        caching - set if caching.

      • addMemberVariable

        @Deprecated
public Variable addMemberVariable​(Variable v)
        Deprecated.
        Use Structure.builder()
        Add a member variable
        Parameters:
        v - add this variable as a member of this structure
        Returns:
        the added variable

      • setMemberVariables

        @Deprecated
public void setMemberVariables​(List<Variable> vars)
        Deprecated.
        Use Structure.builder()
        Set the list of member variables.
        Parameters:
        vars - this is the list of member variables

      • removeMemberVariable

        @Deprecated
public boolean removeMemberVariable​(Variable v)
        Deprecated.
        Use Structure.builder()
        Remove a Variable : uses the Variable name to find it.
        Parameters:
        v - remove this variable as a member of this structure
        Returns:
        true if was found and removed

      • replaceMemberVariable

        @Deprecated
public boolean replaceMemberVariable​(Variable newVar)
        Deprecated.
        Use Structure.builder()
        Replace a Variable with another that has the same name : uses the variable name to find it. If old Var is not found, just add the new one
        Parameters:
        newVar - add this variable as a member of this structure
        Returns:
        true if was found and replaced

      • setParentGroup

        @Deprecated
public void setParentGroup​(Group group)
        Deprecated.
        Use Structure.builder()
        Set the parent group of this Structure, and all member variables.
        Overrides:
        setParentGroup in class Variable
        Parameters:
        group - set to this value

      • getVariables

        public com.google.common.collect.ImmutableList<Variable> getVariables()
        Get the variables contained directly in this Structure.

      • getNumberOfMemberVariables

        public int getNumberOfMemberVariables()
        Get the number of variables contained directly in this Structure.

      • getVariableNames

        public com.google.common.collect.ImmutableList<String> getVariableNames()
        Get the (short) names of the variables contained directly in this Structure.

      • findVariable

        public Variable findVariable​(String shortName)
        Find the Variable member with the specified (short) name.
        Parameters:
        shortName - name of the member variable.
        Returns:
        the Variable member with the specified (short) name, or null if not found.

      • makeStructureMembers

        public StructureMembers makeStructureMembers()
        Create a StructureMembers object that describes this Structure. CAUTION: Do not use for iterating over a StructureData or ArrayStructure - get the StructureMembers object directly from the StructureData or ArrayStructure.
        Returns:
        a StructureMembers object that describes this Structure.

      • getElementSize

        public int getElementSize()
        Get the size of one element of the Structure.
        Overrides:
        getElementSize in class Variable
        Returns:
        size (in bytes)

      • calcElementSize

        @Deprecated
public void calcElementSize()
        Deprecated.
        will be private in ver6, where Structure will be immutable.
        Force recalculation of size of one element of this structure - equals the sum of sizes of its members. This is used only by low level classes like IOSPs.

      • readStructure

        @Deprecated
public StructureData readStructure()
                            throws IOException
        Deprecated.
        use readStructure(0)
        Use this when this is a scalar Structure. Its the same as read(), but it extracts the single StructureData out of the Array.
        Returns:
        StructureData for a scalar
        Throws:
        IOException - on read error

      • readStructure

        public StructureData readStructure​(int index)
                            throws IOException,
                                   InvalidRangeException
        Use this when this is a one dimensional array of Structures, or you are doing the index calculation yourself for a multidimension array. This will read only the ith structure, and return the data as a StructureData object.
        Parameters:
        index - index into 1D array
        Returns:
        ith StructureData
        Throws:
        IOException - on read error
        InvalidRangeException - if index out of range

      • readStructure

        public ArrayStructure readStructure​(int start,
                                    int count)
                             throws IOException,
                                    InvalidRangeException
        For rank 1 array of Structures, read count Structures and return the data as an ArrayStructure. Use only when this is a one dimensional array of Structures.
        Parameters:
        start - start at this index
        count - return this many StructureData
        Returns:
        the StructureData recordsfrom start to start+count-1
        Throws:
        IOException - on read error
        InvalidRangeException - if start, count out of range

      • getStructureIterator

        public StructureDataIterator getStructureIterator()
                                           throws IOException
        Iterator over all the data in a Structure. 
         StructureDataIterator ii = structVariable.getStructureIterator();
 while (ii.hasNext()) {
   StructureData sdata = ii.next();
 }
        Returns:
        StructureDataIterator over type StructureData
        Throws:
        IOException - on read error
        See Also:
        getStructureIterator(int bufferSize)

      • getStructureIterator

        public StructureDataIterator getStructureIterator​(int bufferSize)
                                           throws IOException
        Get an efficient iterator over all the data in the Structure. This is the efficient way to get all the data, it can be much faster than reading one record at a time, and is optimized for large datasets. This is accomplished by buffering bufferSize amount of data at once. 
         Example:

  StructureDataIterator ii = structVariable.getStructureIterator(100 * 1000);
  while (ii.hasNext()) {
    StructureData sdata = ii.next();
  }
        Parameters:
        bufferSize - size in bytes to buffer, set < 0 to use default size
        Returns:
        StructureDataIterator over type StructureData
        Throws:
        IOException - on read error

      • getNameAndAttributes

        public String getNameAndAttributes()
        Get String with name and attributes. Used in short descriptions like tooltips.
        Returns:
        name and attributes String

      • builder

        public static Structure.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"