ucar.nc2

Class Structure

java.lang.Object

ucar.nc2.CDMNode

ucar.nc2.Variable

ucar.nc2.Structure

All Implemented Interfaces:

java.lang.Comparable<VariableSimpleIF>, java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Structure.Builder<T extends Structure.Builder<T>> A builder of Structures.

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

Variable.Cache

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	isSubset
protected java.util.List<Variable>	members

Fields inherited from class ucar.nc2.Variable

attributes, cache, dataType, debugCaching, defaultCoordsSizeToCache, defaultSizeToCache, dimensions, elementSize, hashCode, isVariableLength, ncfile, permitCaching, proxyReader, shape, sizeToCache, spiObject

Fields inherited from class ucar.nc2.CDMNode

annotations, dodsname, group, immutable, parentstruct, shortName, sort

Constructor Summary

Constructors

Modifier	Constructor and Description
	Structure(NetcdfFile ncfile, Group group, Structure parent, java.lang.String shortName) Deprecated. Use Structure.builder()
	Structure(NetcdfFile ncfile, Group group, Structure parent, java.lang.String shortName, java.util.List<Dimension> dimList) Deprecated. Use Structure.builder()
protected	Structure(Structure.Builder<?> builder, Group parentGroup)
protected	Structure(Structure from) Deprecated. Use Structure.builder()

Method Summary

Modifier and Type	Method and Description
protected Structure.Builder<?>	addLocalFieldsToBuilder(Structure.Builder<? extends Structure.Builder<?>> b)
Variable	addMemberVariable(Variable v) Deprecated. Use Structure.builder()
static Structure.Builder<?>	builder() Get Builder for this class that allows subclassing.
void	calcElementSize() Deprecated. will be private in ver6, where Structure will be immutable.
protected int	calcStructureSize()
protected Structure	copy() Deprecated. Use toBuilder()
Variable	findVariable(java.lang.String shortName) Find the Variable member with the specified (short) name.
int	getElementSize() Get the size of one element of the Structure.
java.lang.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.
com.google.common.collect.ImmutableList<java.lang.String>	getVariableNames() Get the (short) names of the variables contained directly in this Structure.
com.google.common.collect.ImmutableList<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() Deprecated. use readStructure(0)
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) Deprecated. Use Structure.builder()
boolean	replaceMemberVariable(Variable newVar) Deprecated. Use Structure.builder()
Structure	select(java.util.List<java.lang.String> memberNames) Create a subset of the Structure consisting only of the given member variables
Structure	select(java.lang.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() Deprecated. Use Structure.builder()
void	setMemberVariables(java.util.List<Variable> vars) Deprecated. Use Structure.builder()
void	setParentGroup(Group group) Deprecated. Use Structure.builder()
Structure.Builder<?>	toBuilder() Turn into a mutable Builder.
protected void	writeCDL(java.util.Formatter buf, Indent indent, boolean useFullName, boolean strict)

Methods inherited from class ucar.nc2.Variable

_read, _read, _readScalarData, addAll, addAttribute, addLocalFieldsToBuilder, attributes, compareTo, createNewCache, equals, extraInfo, findAttribute, findAttributeDouble, findAttributeIgnoreCase, findAttributeInteger, findAttributeString, findDimensionIndex, getAttributes, getDAPName, getDAPName, getDatasetLocation, getDataType, getDescription, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getEnumTypedef, getFileTypeId, getFullName, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNetcdfFile, getParentGroup, getParentGroupOrRoot, getParentStructure, getProxyReader, getRanges, getRank, getScalarData, getShape, getShape, getShapeAll, getShapeAsSection, getSize, getSizeToCache, getSPobject, getUnitsString, hasCachedData, hashCode, invalidateCache, isCoordinateVariable, isEmpty, isImmutable, isMemberOfStructure, isMetadata, isScalar, isUnknownLength, isUnlimited, isVariableLength, lookupEnumString, read, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToByteChannel, readToStream, reallyRead, reallyRead, reduce, remove, removeAttribute, removeAttributeIgnoreCase, resetDimensions, resetShape, section, section, setCachedData, setCachedData, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setEnumTypedef, setIsScalar, setName, setProxyReader, setSizeToCache, setSPobject, setValues, setValues, slice, toString, toStringDebug, writeCDL

Methods inherited from class ucar.nc2.CDMNode

annotate, annotation, getDODSName, getFullNameEscaped, getGroup, getImmutable, getName, getShortName, getSort, localhash, setDODSName, setParentStructure, setShortName, setSort, unwrap

Methods inherited from class java.lang.Object

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

Methods inherited from interface ucar.nc2.VariableSimpleIF

getName, getShortName

Methods inherited from interface ucar.nc2.AttributeContainer

filter, findAttValueIgnoreCase, getName, hasAttribute, hasAttributeIgnoreCase, iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

members

protected java.util.List<Variable> members

isSubset

protected boolean isSubset

Constructor Detail

Structure

@Deprecated
public Structure(NetcdfFile ncfile,
                             Group group,
                             Structure parent,
                             java.lang.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,
                             java.lang.String shortName,
                             java.util.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

Structure

protected Structure(Structure.Builder<?> builder,
                    Group parentGroup)

Method Detail

select

public Structure select(java.util.List<java.lang.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(java.lang.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

@Deprecated
protected Structure copy()

Deprecated. Use toBuilder()

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

@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(java.util.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

setImmutable

@Deprecated
public Variable setImmutable()

Deprecated. Use Structure.builder()

Description copied from class: Variable

Make this immutable.

Overrides:

setImmutable in class Variable

Returns:

this

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<java.lang.String> getVariableNames()

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

findVariable

public Variable findVariable(java.lang.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 java.io.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:

java.io.IOException - on read error

readStructure

public StructureData readStructure(int index)
                            throws java.io.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:

java.io.IOException - on read error

InvalidRangeException - if index out of range

readStructure

public ArrayStructure readStructure(int start,
                                    int count)
                             throws java.io.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:

java.io.IOException - on read error

InvalidRangeException - if start, count out of range

getStructureIterator

public StructureDataIterator getStructureIterator()
                                           throws java.io.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:

java.io.IOException - on read error

See Also:

getStructureIterator(int bufferSize)

getStructureIterator

public StructureDataIterator getStructureIterator(int bufferSize)
                                           throws java.io.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:

java.io.IOException - on read error

getNameAndAttributes

public java.lang.String getNameAndAttributes()

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

Returns:

name and attributes String

writeCDL

protected void writeCDL(java.util.Formatter buf,
                        Indent indent,
                        boolean useFullName,
                        boolean strict)

Overrides:

writeCDL in class Variable

toBuilder

public Structure.Builder<?> toBuilder()

Turn into a mutable Builder. Can use toBuilder().build() to copy.

Overrides:

toBuilder in class Variable

addLocalFieldsToBuilder

protected Structure.Builder<?> addLocalFieldsToBuilder(Structure.Builder<? extends Structure.Builder<?>> b)

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"