ucar.nc2
Class Variable

java.lang.Object
  extended by ucar.nc2.Variable
All Implemented Interfaces:
Comparable<VariableSimpleIF>, ProxyReader, VariableIF, VariableSimpleIF
Direct Known Subclasses:
DODSVariable, Structure, VariableDS

public class Variable
extends Object
implements VariableIF, ProxyReader

A Variable is a logical container for data. It has a dataType, a set of Dimensions that define its array shape, and optionally a set of Attributes.

The data is a multidimensional array of primitive types, Strings, or Structures. Data access is done through the read() methods, which return a memory resident Array.

Immutable if setImmutable() was called.

Author:
caron
See Also:
Array, DataType

Nested Class Summary
protected static class Variable.Cache
           
 
Field Summary
protected  List<Attribute> attributes
           
protected  Variable.Cache cache
           
protected  DataType dataType
           
protected static boolean debugCaching
           
static int defaultCoordsSizeToCache
           
static int defaultSizeToCache
           
protected  List<Dimension> dimensions
           
protected  int elementSize
           
protected  Group group
           
protected  int hashCode
           
protected  boolean isMetadata
           
protected  boolean isVariableLength
           
protected  NetcdfFile ncfile
           
protected  Structure parent
           
protected  ProxyReader proxyReader
           
protected  int[] shape
           
protected  Section shapeAsSection
           
protected  String shortName
           
protected  int sizeToCache
           
protected  Object spiObject
           
 
Constructor Summary
protected Variable()
           
  Variable(NetcdfFile ncfile, Group group, Structure parent, String shortName)
          Create a Variable.
  Variable(NetcdfFile ncfile, Group group, Structure parent, String shortName, DataType dtype, String dims)
          Create a Variable.
  Variable(Variable from)
          Copy constructor.
 
Method Summary
protected  Array _read()
           
protected  Array _read(Section section)
           
 Attribute addAttribute(Attribute att)
          Add new or replace old if has same name
 Object clone()
           
 int compareTo(VariableSimpleIF o)
          Sort by name
protected  Variable copy()
           
 void createNewCache()
          Create a new data cache, use this when you dont want to share the cache.
 boolean equals(Object oo)
          Instances which have same content are equal.
protected  String extraInfo()
           
 Attribute findAttribute(String name)
          Find an Attribute by name.
 Attribute findAttributeIgnoreCase(String name)
          Find an Attribute by name, ignoring the case.
 int findDimensionIndex(String name)
          Find the index of the named Dimension in this Variable.
 List<Attribute> getAttributes()
          Returns the set of attributes for this variable.
 DataType getDataType()
          Get the data type of the Variable.
 String getDescription()
          Get the description of the Variable.
 Dimension getDimension(int i)
          Get the ith dimension.
 List<Dimension> getDimensions()
          Get the list of dimensions used by this variable.
 List<Dimension> getDimensionsAll()
          Get list of Dimensions, including parents if any.
 String getDimensionsString()
          Get the list of Dimension names, space delineated.
 int getElementSize()
          Get the number of bytes for one element of this Variable.
 EnumTypedef getEnumTypedef()
           
 String getFullName()
          Get the full, unescaped name of this Variable, starting from rootGroup.
 String getFullNameEscaped()
          Get the full, escaped name of this Variable.
 String getName()
          Deprecated. use getFullName or getShortName
 String getNameAndDimensions()
          Get the display name plus the dimensions, eg 'float name(dim1, dim2)'
 String getNameAndDimensions(boolean strict)
          Get the display name plus the dimensions, eg 'float name(dim1, dim2)'
 void getNameAndDimensions(Formatter buf, boolean useFullName, boolean strict)
          Add display name plus the dimensions to the StringBuffer
 void getNameAndDimensions(StringBuffer buf)
          Deprecated. use getNameAndDimensions(StringBuilder buf)
 void getNameAndDimensions(StringBuilder buf)
          Get the display name plus the dimensions, eg 'name(dim1, dim2)'
 void getNameAndDimensions(StringBuilder buf, boolean useFullName, boolean strict)
          Add display name plus the dimensions to the StringBuffer
 Group getParentGroup()
          Get the containing Group.
 Structure getParentStructure()
          Get the parent Variable if this is a member of a Structure, or null if its not.
 ProxyReader getProxyReader()
           
 List<Range> getRanges()
          Get shape as an List of Range objects.
 int getRank()
          Get the number of dimensions of the Variable.
protected  Array getScalarData()
           
 int[] getShape()
          Get the shape: length of Variable in each dimension.
 int getShape(int index)
          Get the size of the ith dimension
 int[] getShapeAll()
           
 Section getShapeAsSection()
          Get shape as a Section object.
 String getShortName()
          Get the short name of this Variable.
 long getSize()
          Get the total number of elements in the Variable.
 int getSizeToCache()
          If total data size is less than SizeToCache in bytes, then cache.
 Object getSPobject()
          Should not be public.
 String getUnitsString()
          Get the Unit String for the Variable.
 boolean hasCachedData()
          Has data been read and cached.
 int hashCode()
          Override Object.hashCode() to implement equals.
 void invalidateCache()
          Invalidate the data cache
 boolean isCaching()
          Will this Variable be cached when read.
 boolean isCoordinateVariable()
          Calculate if this is a classic coordinate variable: has same name as its first dimension.
 boolean isImmutable()
          Is this Variable immutable
 boolean isMemberOfStructure()
          Is this variable a member of a Structure?.
 boolean isMetadata()
          Is this variable metadata?.
 boolean isScalar()
          Whether this is a scalar Variable (rank == 0).
 boolean isUnknownLength()
          Deprecated. use isVariableLength()
 boolean isUnlimited()
          Can this variable's size grow?.
 boolean isUnsigned()
          Is this Variable unsigned?.
 boolean isVariableLength()
          Does this variable have a variable length dimension? If so, it has as one of its dimensions Dimension.VLEN.
 String lookupEnumString(int val)
          Lookup the enum string for this value.
 Array read()
          Read all the data for this Variable and return a memory resident Array.
 Array read(int[] origin, int[] shape)
          Read a section of the data for this Variable and return a memory resident Array.
 Array read(List<Range> ranges)
          Read a section of the data for this Variable from the netcdf file and return a memory resident Array.
 Array read(Section section)
          Read a section of the data for this Variable from the netcdf file and return a memory resident Array.
 Array read(String sectionSpec)
          Read data section specified by a "section selector", and return a memory resident Array.
 byte readScalarByte()
          Get the value as a byte for a scalar Variable.
 double readScalarDouble()
          Get the value as a double for a scalar Variable.
 float readScalarFloat()
          Get the value as a float for a scalar Variable.
 int readScalarInt()
          Get the value as a int for a scalar Variable.
 long readScalarLong()
          Get the value as a long for a scalar Variable.
 short readScalarShort()
          Get the value as a short for a scalar Variable.
 String readScalarString()
          Get the value as a String for a scalar Variable.
 long readToByteChannel(Section section, WritableByteChannel wbc)
           
 Array reallyRead(Variable client, CancelTask cancelTask)
          public by accident, do not call directly.
 Array reallyRead(Variable client, Section section, CancelTask cancelTask)
          public by accident, do not call directly.
 boolean remove(Attribute a)
          Remove an Attribute : uses the attribute hashCode to find it.
 boolean removeAttribute(String attName)
          Remove an Attribute by name.
 boolean removeAttributeIgnoreCase(String attName)
          Remove an Attribute by name, ignoring case
 void resetDimensions()
          Reset the dimension array.
 void resetShape()
          Use when dimensions have changed, to recalculate the shape.
 Variable section(List<Range> ranges)
          Create a new Variable that is a logical subsection of this Variable.
 Variable section(Section subsection)
          Create a new Variable that is a logical subsection of this Variable.
 void setCachedData(Array cacheData)
           
 void setCachedData(Array cacheData, boolean isMetadata)
          Set the data cache
 void setCaching(boolean caching)
          Set whether to cache or not.
 void setDataType(DataType dataType)
          Set the data type
 void setDimension(int idx, Dimension dim)
          Replace a dimension with an equivalent one.
 void setDimensions(List<Dimension> dims)
          Set the shape with a list of Dimensions.
 void setDimensions(String dimString)
          Set the dimensions using the dimensions names.
 void setDimensionsAnonymous(int[] shape)
          Set the dimensions using all anonymous (unshared) dimensions
 void setElementSize(int elementSize)
          Set the element size.
 void setEnumTypedef(EnumTypedef enumTypedef)
          Public by accident.
 Variable setImmutable()
          Make this immutable.
 void setIsScalar()
          Set this Variable to be a scalar
 String setName(String shortName)
          Set the short name, converting to valid CDM object name if needed.
 void setParentGroup(Group group)
          Set the parent group.
 void setParentStructure(Structure parent)
          Set the parent structure.
 void setProxyReader(ProxyReader proxyReader)
           
 void setSizeToCache(int sizeToCache)
          Set the sizeToCache.
 void setSPobject(Object spiObject)
          Should not be public.
 void setValues(int npts, double start, double incr)
          Generate the list of values from a starting value and an increment.
 void setValues(List<String> values)
          Set the data values from a list of Strings.
 Variable slice(int dim, int value)
          Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value.
 String toString()
          CDL representation of Variable, not strict.
 String toStringDebug()
          String representation of Variable and its attributes.
protected  void writeCDL(Formatter buf, String indent, boolean useFullName, boolean strict)
           
 String writeCDL(String indent, boolean useFullName, boolean strict)
          CDL representation of a Variable.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

defaultSizeToCache

public static final int defaultSizeToCache
See Also:
Constant Field Values

defaultCoordsSizeToCache

public static final int defaultCoordsSizeToCache
See Also:
Constant Field Values

debugCaching

protected static boolean debugCaching

ncfile

protected NetcdfFile ncfile

group

protected Group group

shortName

protected String shortName

shape

protected int[] shape

shapeAsSection

protected Section shapeAsSection

dataType

protected DataType dataType

elementSize

protected int elementSize

dimensions

protected List<Dimension> dimensions

attributes

protected List<Attribute> attributes

isVariableLength

protected boolean isVariableLength

isMetadata

protected boolean isMetadata

cache

protected Variable.Cache cache

sizeToCache

protected int sizeToCache

parent

protected Structure parent

proxyReader

protected ProxyReader proxyReader

hashCode

protected int hashCode

spiObject

protected Object spiObject
Constructor Detail

Variable

protected Variable()

Variable

public Variable(NetcdfFile ncfile,
                Group group,
                Structure parent,
                String shortName)
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

public Variable(NetcdfFile ncfile,
                Group group,
                Structure parent,
                String shortName,
                DataType dtype,
                String dims)
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

public Variable(Variable from)
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

getName

public String getName()
Deprecated. use getFullName or getShortName

Get the variable name.

Specified by:
getName in interface VariableSimpleIF
Returns:
full unescaped name

getFullName

public String getFullName()
Get the full, unescaped name of this Variable, starting from rootGroup. The name is unique within the entire NetcdfFile.

Specified by:
getFullName in interface VariableIF
Returns:
full, unescaped name

getFullNameEscaped

public String getFullNameEscaped()
Get the full, escaped name of this Variable. Use for NetcdfFile.findVariable().

Specified by:
getFullNameEscaped in interface VariableIF
Returns:
full, escaped name
See Also:
"http://www.unidata.ucar.edu/software/netcdf-java/CDM/Identifiers.html"

getShortName

public String getShortName()
Get the short name of this Variable. The name is unique within its parent group.

Specified by:
getShortName in interface VariableIF
Specified by:
getShortName in interface VariableSimpleIF
Returns:
short name of the data Variable

getDataType

public DataType getDataType()
Get the data type of the Variable.

Specified by:
getDataType in interface VariableIF
Specified by:
getDataType in interface VariableSimpleIF
Returns:
Variable's data type

getShape

public int[] getShape()
Get the shape: length of Variable in each dimension.

Specified by:
getShape in interface VariableIF
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

Specified by:
getSize in interface VariableIF
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 dont 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.

Specified by:
getElementSize in interface VariableIF
Returns:
total number of bytes for the Variable

getRank

public int getRank()
Get the number of dimensions of the Variable.

Specified by:
getRank in interface VariableIF
Specified by:
getRank in interface VariableSimpleIF
Returns:
the rank

getParentGroup

public Group getParentGroup()
Get the containing Group.

Specified by:
getParentGroup in interface VariableIF
Returns:
the containing Group.

isMetadata

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

Specified by:
isMetadata in interface VariableIF
Returns:
true if Variable values need to be included in NcML

isScalar

public boolean isScalar()
Whether this is a scalar Variable (rank == 0).

Specified by:
isScalar in interface VariableIF
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.

Specified by:
isVariableLength in interface VariableIF
Returns:
true if Variable has a variable length dimension?

isUnsigned

public boolean isUnsigned()
Is this Variable unsigned?. Only meaningful for byte, short, int, long types. Looks for attribute "_Unsigned", case insensitive

Specified by:
isUnsigned in interface VariableIF
Returns:
true if Variable is unsigned

isUnlimited

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

Specified by:
isUnlimited in interface VariableIF
Returns:
boolean true iff this variable can grow

getDimensions

public List<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 VariableIF
Specified by:
getDimensions in interface VariableSimpleIF
Returns:
List, immutable

getDimension

public Dimension getDimension(int i)
Get the ith dimension.

Specified by:
getDimension in interface VariableIF
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.

Specified by:
findDimensionIndex in interface VariableIF
Parameters:
name - the name of the dimension
Returns:
the index of the named Dimension, or -1 if not found.

getAttributes

public List<Attribute> getAttributes()
Returns the set of attributes for this variable.

Specified by:
getAttributes in interface VariableIF
Specified by:
getAttributes in interface VariableSimpleIF
Returns:
List, not a copy, but may be immutable

findAttribute

public Attribute findAttribute(String name)
Find an Attribute by name.

Specified by:
findAttribute in interface VariableIF
Parameters:
name - the name of the attribute
Returns:
the attribute, or null if not found

findAttributeIgnoreCase

public Attribute findAttributeIgnoreCase(String name)
Find an Attribute by name, ignoring the case.

Specified by:
findAttributeIgnoreCase in interface VariableIF
Specified by:
findAttributeIgnoreCase in interface VariableSimpleIF
Parameters:
name - the name of the attribute
Returns:
the attribute, or null if not found

getDescription

public String getDescription()
Get the description of the Variable. Default is to use "long_name" attribute value. If not exist, look for "description", "title", or "standard_name" attribute value (in that order).

Specified by:
getDescription in interface VariableIF
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 "units" attribute value

Specified by:
getUnitsString in interface VariableIF
Specified by:
getUnitsString in interface VariableSimpleIF
Returns:
unit string, or null if not found.

getRanges

public List<Range> getRanges()
Get shape as an List of Range objects. The List is immutable.

Specified by:
getRanges in interface VariableIF
Returns:
List of Ranges, one for each Dimension.

getShapeAsSection

public Section getShapeAsSection()
Get shape as a Section object.

Specified by:
getShapeAsSection in interface VariableIF
Returns:
Section containing List, one for each Dimension.

getProxyReader

public ProxyReader getProxyReader()

setProxyReader

public void setProxyReader(ProxyReader proxyReader)

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.

Specified by:
section in interface VariableIF
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

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

copy

protected Variable copy()

lookupEnumString

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

public void setEnumTypedef(EnumTypedef enumTypedef)
Public by accident.

Parameters:
enumTypedef - set the EnumTypedef, only use if getDataType.isEnum()

getEnumTypedef

public EnumTypedef getEnumTypedef()

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]);

Specified by:
read in interface VariableIF
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(String sectionSpec)
           throws IOException,
                  InvalidRangeException
Read data section specified by a "section selector", and return a memory resident Array. Uses Fortran 90 array section syntax.

Specified by:
read in interface VariableIF
Parameters:
sectionSpec - specification string, eg "1:2,10,:,1:100:10". May optionally have ().
Returns:
the requested data in a memory-resident Array
Throws:
IOException
InvalidRangeException
See Also:
for sectionSpec syntax

read

public Array read(List<Range> ranges)
           throws IOException,
                  InvalidRangeException
Read a section of the data for this Variable from the netcdf file and return a memory resident Array.

Parameters:
ranges - list of Range specifying the section of data to read.
Returns:
the requested data in a memory-resident Array
Throws:
IOException - if error
InvalidRangeException - if ranges is invalid
See Also:
read(Section)

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 readAllStructures().

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

Specified by:
read in interface VariableIF
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 readAllStructures().

Specified by:
read in interface VariableIF
Returns:
the requested data in a memory-resident Array.
Throws:
IOException

readScalarByte

public byte readScalarByte()
                    throws IOException
Get the value as a byte for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarByte in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.
ForbiddenConversionException - if data type not convertible to byte

readScalarShort

public short readScalarShort()
                      throws IOException
Get the value as a short for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarShort in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.
ForbiddenConversionException - if data type not convertible to short

readScalarInt

public int readScalarInt()
                  throws IOException
Get the value as a int for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarInt in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.
ForbiddenConversionException - if data type not convertible to int

readScalarLong

public long readScalarLong()
                    throws IOException
Get the value as a long for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarLong in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable
ForbiddenConversionException - if data type not convertible to long

readScalarFloat

public float readScalarFloat()
                      throws IOException
Get the value as a float for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarFloat in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.
ForbiddenConversionException - if data type not convertible to float

readScalarDouble

public double readScalarDouble()
                        throws IOException
Get the value as a double for a scalar Variable. May also be one-dimensional of length 1.

Specified by:
readScalarDouble in interface VariableIF
Throws:
IOException - if theres an IO Error
UnsupportedOperationException - if not a scalar Variable or one-dimensional of length 1.
ForbiddenConversionException - if data type not convertible to double

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.

Specified by:
readScalarString in interface VariableIF
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.

getScalarData

protected Array getScalarData()
                       throws IOException
Throws:
IOException

_read

protected Array _read()
               throws IOException
Throws:
IOException

reallyRead

public Array reallyRead(Variable client,
                        CancelTask cancelTask)
                 throws IOException
public by accident, do not call directly.

Specified by:
reallyRead in interface ProxyReader
Parameters:
client - the client Variable
cancelTask - user may cancel
Returns:
Array
Throws:
IOException - on error

_read

protected Array _read(Section section)
               throws IOException,
                      InvalidRangeException
Throws:
IOException
InvalidRangeException

reallyRead

public Array reallyRead(Variable client,
                        Section section,
                        CancelTask cancelTask)
                 throws IOException,
                        InvalidRangeException
public by accident, do not call directly.

Specified by:
reallyRead in interface ProxyReader
Parameters:
client - the client Variable
section - the section of data to read.
cancelTask - user may cancel
Returns:
Array
Throws:
IOException - on error
InvalidRangeException - if section has incorrect rank or illegal shape.

readToByteChannel

public long readToByteChannel(Section section,
                              WritableByteChannel wbc)
                       throws IOException,
                              InvalidRangeException
Throws:
IOException
InvalidRangeException

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

public void getNameAndDimensions(StringBuilder buf)
Get the display name plus the dimensions, eg 'name(dim1, dim2)'

Parameters:
buf - add info to this StringBuilder

getNameAndDimensions

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

public void getNameAndDimensions(StringBuilder buf,
                                 boolean useFullName,
                                 boolean strict)
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 StringBuffer

Specified by:
getNameAndDimensions in interface VariableIF
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

toString

public String toString()
CDL representation of Variable, not strict.

Overrides:
toString in class Object

writeCDL

public String writeCDL(String indent,
                       boolean useFullName,
                       boolean strict)
CDL representation of a Variable.

Parameters:
indent - start each line with this much space
useFullName - use full name, else use short name
strict - strictly comply with ncgen syntax
Returns:
CDL representation of the Variable.

writeCDL

protected void writeCDL(Formatter buf,
                        String indent,
                        boolean useFullName,
                        boolean strict)

toStringDebug

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

Specified by:
toStringDebug in interface VariableIF

extraInfo

protected String extraInfo()

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

compareTo

public int compareTo(VariableSimpleIF o)
Sort by name

Specified by:
compareTo in interface Comparable<VariableSimpleIF>

setDataType

public void setDataType(DataType dataType)
Set the data type

Parameters:
dataType - set to this value

setName

public String setName(String shortName)
Set the short name, converting to valid CDM object name if needed.

Parameters:
shortName - set to this value
Returns:
valid CDM object name

setParentGroup

public void setParentGroup(Group group)
Set the parent group.

Parameters:
group - set to this value

setElementSize

public void setElementSize(int elementSize)
Set the element size. Usually elementSize is determined by the dataType, use this only for exceptional cases.

Parameters:
elementSize - set to this value

addAttribute

public Attribute addAttribute(Attribute att)
Add new or replace old if has same name

Parameters:
att - add this Attribute
Returns:
the added attribute

remove

public boolean remove(Attribute a)
Remove an Attribute : uses the attribute hashCode to find it.

Parameters:
a - remove this attribute
Returns:
true if was found and removed

removeAttribute

public boolean removeAttribute(String attName)
Remove an Attribute by name.

Parameters:
attName - if exists, remove this attribute
Returns:
true if was found and removed

removeAttributeIgnoreCase

public boolean removeAttributeIgnoreCase(String attName)
Remove an Attribute by name, ignoring case

Parameters:
attName - if exists, remove this attribute
Returns:
true if was found and removed

setDimensions

public void setDimensions(List<Dimension> dims)
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

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


setDimensions

public void setDimensions(String dimString)
Set the dimensions using the dimensions names. The dimension is searched for recursively in the parent groups.

Parameters:
dimString - : whitespace seperated list of dimension names, or '*' for Dimension.UNKNOWN. null or empty String is a scalar.

resetDimensions

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


setDimensionsAnonymous

public void setDimensionsAnonymous(int[] shape)
                            throws InvalidRangeException
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

public void setIsScalar()
Set this Variable to be a scalar


setDimension

public void setDimension(int idx,
                         Dimension dim)
Replace a dimension with an equivalent one.

Parameters:
idx - index into dimension array
dim - to set

setImmutable

public Variable setImmutable()
Make this immutable.

Returns:
this

isImmutable

public boolean isImmutable()
Is this Variable immutable

Returns:
if immutable

getSPobject

public Object getSPobject()
Should not be public.

Returns:
the IOSP object

setSPobject

public void setSPobject(Object spiObject)
Should not be public.

Parameters:
spiObject - the IOSP object

getSizeToCache

public int getSizeToCache()
If total data size is less than SizeToCache in bytes, then cache.

Returns:
size at which caching happens

setSizeToCache

public void setSizeToCache(int sizeToCache)
Set the sizeToCache. If not set, use defaults

Parameters:
sizeToCache - size at which caching happens. < 0 means use defaults

setCaching

public void setCaching(boolean caching)
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.

Returns:
true is caching

invalidateCache

public void invalidateCache()
Invalidate the data cache


setCachedData

public void setCachedData(Array cacheData)

setCachedData

public void setCachedData(Array cacheData,
                          boolean isMetadata)
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

public void setValues(int npts,
                      double start,
                      double incr)
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

setValues

public void setValues(List<String> values)
               throws IllegalArgumentException
Set the data values from a list of Strings.

Parameters:
values - list of Strings
Throws:
IllegalArgumentException - if values array not correct size, or values wont parse to the correct type

isMemberOfStructure

public boolean isMemberOfStructure()
Is this variable a member of a Structure?.

Specified by:
isMemberOfStructure in interface VariableIF

getParentStructure

public Structure getParentStructure()
Get the parent Variable if this is a member of a Structure, or null if its not.

Specified by:
getParentStructure in interface VariableIF

setParentStructure

public void setParentStructure(Structure parent)
Set the parent structure.

Parameters:
parent - set to this value

getDimensionsAll

public List<Dimension> getDimensionsAll()
Get list of Dimensions, including parents if any.

Specified by:
getDimensionsAll in interface VariableIF
Returns:
array of Dimension, rank of v plus all parents.

getShapeAll

public int[] getShapeAll()

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.

Specified by:
isCoordinateVariable in interface VariableIF
Returns:
true if a coordinate variable.

clone

public Object clone()
             throws CloneNotSupportedException
Overrides:
clone in class Object
Throws:
CloneNotSupportedException

isUnknownLength

public boolean isUnknownLength()
Deprecated. use isVariableLength()

Returns:
isVariableLength()


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