ucar.nc2
Class Structure

java.lang.Object
  extended by ucar.nc2.Variable
      extended by ucar.nc2.Structure
All Implemented Interfaces:
Comparable<VariableSimpleIF>, ProxyReader, VariableIF, 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, ot 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.

Author:
caron

Nested Class Summary
 
Nested classes/interfaces inherited from class ucar.nc2.Variable
Variable.Cache
 
Field Summary
protected static int defaultBufferSize
           
protected  boolean isSubset
           
protected static org.slf4j.Logger log
           
protected  HashMap<String,Variable> memberHash
           
protected  List<Variable> members
           
 
Fields inherited from class ucar.nc2.Variable
attributes, cache, dataType, debugCaching, defaultCoordsSizeToCache, defaultSizeToCache, dimensions, elementSize, group, hashCode, isMetadata, isVariableLength, ncfile, parent, proxyReader, shape, shapeAsSection, shortName, sizeToCache, spiObject
 
Constructor Summary
  Structure(NetcdfFile ncfile, Group group, Structure parent, String shortName)
           
protected Structure(Structure from)
          Copy constructor.
 
Method Summary
 Variable addMemberVariable(Variable v)
          Add a member variable
 void calcElementSize()
          Force recalculation of size of one element of this structure - equals the sum of sizes of its members.
protected  int calcStructureSize()
           
protected  Variable copy()
           
 Variable findVariable(String shortName)
          Find the Variable member with the specified (short) name.
 int getElementSize()
          Get the size of one element of the Structure.
 String getNameAndAttributes()
          Get String with name and attributes.
 int getNumberOfMemberVariables()
          Get the number of variables contained directly in this Structure.
 StructureDataIterator getStructureIterator()
          Iterator over all the data in a Structure.
 StructureDataIterator getStructureIterator(int bufferSize)
          Get an efficient iterator over all the data in the Structure.
 List<String> getVariableNames()
          Get the (short) names of the variables contained directly in this Structure.
 List<Variable> getVariables()
          Get the variables contained directly in this Structure.
 boolean isCaching()
          Caching is not allowed
 boolean isSubset()
          Find if this was created from a subset() method.
 StructureMembers makeStructureMembers()
          Create a StructureMembers object that describes this Structure.
 StructureData readStructure()
          Use this when this is a scalar Structure.
 StructureData readStructure(int index)
          Use this when this is a one dimensional array of Structures, or you are doing the index calculation yourself for a multidimension array.
 ArrayStructure readStructure(int start, int count)
          For rank 1 array of Structures, read count Structures and return the data as an ArrayStructure.
 boolean removeMemberVariable(Variable v)
          Remove a Variable : uses the Variable name to find it.
 boolean replaceMemberVariable(Variable newVar)
          Replace a Variable with another that has the same name : uses the variable name to find it.
 Structure select(List<String> memberNames)
          Create a subset of the Structure consisting only of the given member variables
 Structure select(String varName)
          Create a subset of the Structure consisting only of the one member variable
 void setCaching(boolean caching)
          Caching is not allowed
 Variable setImmutable()
          Make this immutable.
 void setMemberVariables(List<Variable> vars)
          Set the list of member variables.
 void setParentGroup(Group group)
          Set the parent group of this Structure, and all member variables.
protected  void writeCDL(Formatter buf, String indent, boolean useFullName, boolean strict)
           
 
Methods inherited from class ucar.nc2.Variable
_read, _read, addAttribute, clone, compareTo, createNewCache, equals, extraInfo, findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getDataType, getDescription, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getEnumTypedef, getFullName, getFullNameEscaped, getName, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getParentGroup, getParentStructure, getProxyReader, getRanges, getRank, getScalarData, getShape, getShape, getShapeAll, getShapeAsSection, getShortName, getSize, getSizeToCache, getSPobject, getUnitsString, hasCachedData, hashCode, invalidateCache, isCoordinateVariable, isImmutable, isMemberOfStructure, isMetadata, isScalar, isUnknownLength, isUnlimited, isUnsigned, isVariableLength, lookupEnumString, read, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToByteChannel, reallyRead, reallyRead, remove, removeAttribute, removeAttributeIgnoreCase, resetDimensions, resetShape, section, section, setCachedData, setCachedData, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setEnumTypedef, setIsScalar, setName, setParentStructure, setProxyReader, setSizeToCache, setSPobject, setValues, setValues, slice, toString, toStringDebug, writeCDL
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

log

protected static org.slf4j.Logger log

defaultBufferSize

protected static int defaultBufferSize

members

protected List<Variable> members

memberHash

protected HashMap<String,Variable> memberHash

isSubset

protected boolean isSubset
Constructor Detail

Structure

public Structure(NetcdfFile ncfile,
                 Group group,
                 Structure parent,
                 String shortName)

Structure

protected Structure(Structure from)
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

copy

protected Variable copy()
Overrides:
copy in class Variable

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

public Variable addMemberVariable(Variable v)
Add a member variable

Parameters:
v - add this variable as a member of this structure
Returns:
the added variable

setMemberVariables

public void setMemberVariables(List<Variable> vars)
Set the list of member variables.

Parameters:
vars - this is the list of member variables

removeMemberVariable

public boolean removeMemberVariable(Variable v)
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

public boolean replaceMemberVariable(Variable newVar)
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

public void setParentGroup(Group group)
Set the parent group of this Structure, and all member variables.

Overrides:
setParentGroup in class Variable
Parameters:
group - set to this value

setImmutable

public Variable setImmutable()
Description copied from class: Variable
Make this immutable.

Overrides:
setImmutable in class Variable
Returns:
this

getVariables

public List<Variable> getVariables()
Get the variables contained directly in this Structure.

Returns:
List of type Variable.

getNumberOfMemberVariables

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

Returns:
number of member variables

getVariableNames

public List<String> getVariableNames()
Get the (short) names of the variables contained directly in this Structure.

Returns:
List of type String.

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.

Specified by:
getElementSize in interface VariableIF
Overrides:
getElementSize in class Variable
Returns:
size (in bytes)

calcElementSize

public void calcElementSize()
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

public StructureData readStructure()
                            throws IOException
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

writeCDL

protected void writeCDL(Formatter buf,
                        String indent,
                        boolean useFullName,
                        boolean strict)
Overrides:
writeCDL in class Variable


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.