ucar.nc2
Class Structure

java.lang.Object
  ucar.nc2.Variable
      ucar.nc2.Structure

All Implemented Interfaces:

VariableIF

Direct Known Subclasses:

DODSStructure, 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.

Generally, the programmer can assume that the data in a 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.

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

Nested Class Summary

class

Structure.Iterator Iterator over type StructureData.

Nested classes/interfaces inherited from class ucar.nc2.Variable

Variable.Cache

Field Summary

protected java.util.HashMap	memberHash
protected java.util.ArrayList	memberNames
protected java.util.ArrayList	members

Fields inherited from class ucar.nc2.Variable

attributes, cache, dataType, debugCaching, defaultSizeToCache, dimensions, elementSize, group, isCoordinateAxis, isMetadata, isSection, isSlice, isVlen, ncfile, orgVar, parent, scalarIndex, sectionRanges, shape, shortName, sizeToCache, sliceDim, sliceRanges

Constructor Summary

	Structure(NetcdfFile ncfile, Group group, Structure parent, java.lang.String shortName) Constructor
protected	Structure(Structure from, boolean reparent) copy constructor;

Method Summary

void	addMemberVariable(Variable v) Add a member variable
protected void	calcElementSize()
protected int	calcStructureSize()
Variable	findVariable(java.lang.String shortName) Find the Variable member with the specified (short) name, or null if not found.
int	getElementSize() Get the size of one element of the Structure.
java.lang.String	getNameAndAttributes() Get String with name and attributes.
Structure.Iterator	getStructureIterator() Iterator over all the data in a Structure.
Structure.Iterator	getStructureIterator(int bufferSize) Get an efficient iterator over all the data in the Structure.
java.util.List	getVariableNames() Get the (short) names of the variables contained directly in this Structure.
java.util.List	getVariables() Get the variables contained directly in this Structure.
boolean	isCaching() Caching is not allowed
StructureMembers	makeStructureMembers() Make the StructureMembers object corresponding to 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.
ArrayStructure	readStructure(int start, int count) Use this when this is a one dimensional array of Structures.
boolean	removeMemberVariable(Variable v) Remove a Variable : uses the variable hashCode to find it.
boolean	replaceMemberVariable(Variable newVar) Replace a Variable with another that has the same name : uses the variable name to find it.
Variable	section(java.util.List section) Override so it returns a Structure
void	setCaching(boolean caching) Caching is not allowed
void	setMemberVariables(java.util.ArrayList<Variable> vars) Set the list of member variables.
void	setParentGroup(Group group) Set the parent group of this Structure, and all member variables.
java.lang.String	toString() String representation of Structure and nested variables.
java.lang.String	writeCDL(java.lang.String space, boolean useFullName, boolean strict) String representation of a Variable and its attributes.

Methods inherited from class ucar.nc2.Variable

_read, _read, _readMemberData, addAttribute, attributes, calcIsCoordinateVariable, equals, extraInfo, findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getCoordinateDimension, getDataType, getDescription, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getIOVar, getName, getNameAndDimensions, getNameAndDimensions, getParentGroup, getParentStructure, getRanges, getRank, getSectionRanges, getShape, getShortName, getSize, getSizeToCache, getSPobject, getUnitsString, hasCachedData, hashCode, invalidateCache, isMemberOfStructure, isMetadata, isScalar, isSection, isUnknownLength, isUnlimited, isUnsigned, isVariableLength, makeSection, makeSectionAddParents, makeSectionRanges, makeSectionWithParents, makeSlice, makeSliceRanges, read, read, read, read, readAllStructures, readAllStructuresSpec, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, remove, replaceDimension, setCachedData, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setIOVar, setIsCoordinateAxis, setName, setParentStructure, setSizeToCache, setSPobject, slice, toStringDebug

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

memberHash

protected java.util.HashMap memberHash

members

protected java.util.ArrayList members

memberNames

protected java.util.ArrayList memberNames

Constructor Detail

Structure

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

Constructor

Structure

protected Structure(Structure from,
                    boolean reparent)

copy constructor;

Parameters:

from - copy from this

reparent - : if true, reparent the members. if so, cant use 'from' anymore

Method Detail

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.

section

public Variable section(java.util.List section)
                 throws InvalidRangeException

Override so it returns a Structure

Specified by:

section in interface VariableIF

Overrides:

section in class Variable

Parameters:

section - 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

addMemberVariable

public void addMemberVariable(Variable v)

Add a member variable

setMemberVariables

public void setMemberVariables(java.util.ArrayList<Variable> vars)

Set the list of member variables.

removeMemberVariable

public boolean removeMemberVariable(Variable v)

Remove a Variable : uses the variable hashCode to find it.

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

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

getVariables

public java.util.List getVariables()

Get the variables contained directly in this Structure.

Returns:

List of type Variable.

getVariableNames

public java.util.List getVariableNames()

Get the (short) names of the variables contained directly in this Structure.

Returns:

List of type String.

findVariable

public Variable findVariable(java.lang.String shortName)

Find the Variable member with the specified (short) name, or null if not found.

makeStructureMembers

public StructureMembers makeStructureMembers()

Make the StructureMembers object corresponding to 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

protected void calcElementSize()

readStructure

public StructureData readStructure()
                            throws java.io.IOException

Use this when this is a scalar Structure. Its the same as read(), but it extracts the single StructureData out of the Array.

Throws:

java.io.IOException

readStructure

public StructureData readStructure(int index)
                            throws java.io.IOException,
                                   InvalidRangeException

Use this when this is a one dimensional array of Structures. This will read only the ith structure, and return the data as a StructureData object.

Returns:

ith StructureData

Throws:

java.io.IOException

InvalidRangeException

readStructure

public ArrayStructure readStructure(int start,
                                    int count)
                             throws java.io.IOException,
                                    InvalidRangeException

Use this when this is a one dimensional array of Structures.

Returns:

start - start + count-1 StructureData records in an ArrayStructure

Throws:

java.io.IOException

InvalidRangeException

getStructureIterator

public Structure.Iterator getStructureIterator()

Iterator over all the data in a Structure. You must fully process the data, or copy it out of the StructureData, as you iterate over it. DO NOT KEEP ANY REFERENCES to the StructureData object.

  Structure.Iterator ii = structVariable.getStructureIterator();
  while (ii.hasNext()) {
        StructureData sdata = ii.next();
      }
      

Returns:

Iterator over type StructureData

See Also:

getStructureIterator(int bufferSize)

getStructureIterator

public Structure.Iterator getStructureIterator(int bufferSize)

Get an efficient iterator over all the data in the Structure. You must fully process the data, or copy it out of the StructureData, as you iterate over it. DO NOT KEEP ANY REFERENCES to the StructureData object. 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:

  Structure.Iterator ii = structVariable.getStructureIterator(100 * 1000);
  while (ii.hasNext()) {
    StructureData sdata = ii.next();
  }
 

Parameters:

bufferSize - size in bytes to buffer

Returns:

Structure.Iterator over type StructureData

getNameAndAttributes

public java.lang.String getNameAndAttributes()

Get String with name and attributes. Used in short descriptions like tooltips.

toString

public java.lang.String toString()

String representation of Structure and nested variables.

Overrides:

toString in class Variable

writeCDL

public java.lang.String writeCDL(java.lang.String space,
                                 boolean useFullName,
                                 boolean strict)

Description copied from class: Variable

String representation of a Variable and its attributes.

Overrides:

writeCDL in class Variable

Parameters:

space - start each line with this much space

useFullName - use full name, else use short name

strict - stictly comply with ncgen syntax

Returns:

CDL representation of the Variable.