|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectucar.nc2.Variable
public class Variable
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.
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 |
---|
public static final int defaultSizeToCache
public static final int defaultCoordsSizeToCache
protected static boolean debugCaching
protected NetcdfFile ncfile
protected Group group
protected String shortName
protected int[] shape
protected Section shapeAsSection
protected DataType dataType
protected int elementSize
protected List<Dimension> dimensions
protected List<Attribute> attributes
protected boolean isVariableLength
protected boolean isMetadata
protected Variable.Cache cache
protected int sizeToCache
protected Structure parent
protected ProxyReader proxyReader
protected int hashCode
protected Object spiObject
Constructor Detail |
---|
protected Variable()
public Variable(NetcdfFile ncfile, Group group, Structure parent, String shortName)
ncfile
- the containing NetcdfFile.group
- the containing group; if null, use rootGroupparent
- parent Structure, may be nullshortName
- variable shortName, must be unique within the Grouppublic Variable(NetcdfFile ncfile, Group group, Structure parent, String shortName, DataType dtype, String dims)
ncfile
- the containing NetcdfFile.group
- the containing group; if null, use rootGroupparent
- parent Structure, may be nullshortName
- variable shortName, must be unique within the Groupdtype
- the Variable's DataTypedims
- space delimited list of dimension names. may be null or "" for scalars.public Variable(Variable from)
from
- copy from this Variable.Method Detail |
---|
public String getName()
getName
in interface VariableSimpleIF
public String getFullName()
getFullName
in interface VariableIF
public String getFullNameEscaped()
getFullNameEscaped
in interface VariableIF
public String getShortName()
getShortName
in interface VariableIF
getShortName
in interface VariableSimpleIF
public DataType getDataType()
getDataType
in interface VariableIF
getDataType
in interface VariableSimpleIF
public int[] getShape()
getShape
in interface VariableIF
getShape
in interface VariableSimpleIF
public int getShape(int index)
index
- which dimension
public long getSize()
getSize
in interface VariableIF
public int getElementSize()
getElementSize
in interface VariableIF
public int getRank()
getRank
in interface VariableIF
getRank
in interface VariableSimpleIF
public Group getParentGroup()
getParentGroup
in interface VariableIF
public boolean isMetadata()
isMetadata
in interface VariableIF
public boolean isScalar()
isScalar
in interface VariableIF
public boolean isVariableLength()
isVariableLength
in interface VariableIF
public boolean isUnsigned()
isUnsigned
in interface VariableIF
public boolean isUnlimited()
isUnlimited
in interface VariableIF
public List<Dimension> getDimensions()
getDimensions
in interface VariableIF
getDimensions
in interface VariableSimpleIF
public Dimension getDimension(int i)
getDimension
in interface VariableIF
i
- index of the dimension.
public String getDimensionsString()
public int findDimensionIndex(String name)
findDimensionIndex
in interface VariableIF
name
- the name of the dimension
public List<Attribute> getAttributes()
getAttributes
in interface VariableIF
getAttributes
in interface VariableSimpleIF
public Attribute findAttribute(String name)
findAttribute
in interface VariableIF
name
- the name of the attribute
public Attribute findAttributeIgnoreCase(String name)
findAttributeIgnoreCase
in interface VariableIF
findAttributeIgnoreCase
in interface VariableSimpleIF
name
- the name of the attribute
public String getDescription()
getDescription
in interface VariableIF
getDescription
in interface VariableSimpleIF
public String getUnitsString()
getUnitsString
in interface VariableIF
getUnitsString
in interface VariableSimpleIF
public List<Range> getRanges()
getRanges
in interface VariableIF
public Section getShapeAsSection()
getShapeAsSection
in interface VariableIF
public ProxyReader getProxyReader()
public void setProxyReader(ProxyReader proxyReader)
public Variable section(List<Range> ranges) throws InvalidRangeException
section
in interface VariableIF
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.
InvalidRangeException
public Variable section(Section subsection) throws InvalidRangeException
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.
InvalidRangeException
- if section not compatible with shapepublic Variable slice(int dim, int value) throws InvalidRangeException
dim
- which dimension to fixvalue
- at what index value
InvalidRangeException
- if dimension or value is illegalprotected Variable copy()
public String lookupEnumString(int val)
val
- the integer value of this enum
public void setEnumTypedef(EnumTypedef enumTypedef)
enumTypedef
- set the EnumTypedef, only use if getDataType.isEnum()public EnumTypedef getEnumTypedef()
public Array read(int[] origin, int[] shape) throws IOException, InvalidRangeException
assert(origin[ii] + shape[ii]*stride[ii] <= Variable.shape[ii]);
read
in interface VariableIF
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.
IOException
InvalidRangeException
public Array read(String sectionSpec) throws IOException, InvalidRangeException
read
in interface VariableIF
sectionSpec
- specification string, eg "1:2,10,:,1:100:10". May optionally have ().
IOException
InvalidRangeException
for sectionSpec syntax
public Array read(List<Range> ranges) throws IOException, InvalidRangeException
ranges
- list of Range specifying the section of data to read.
IOException
- if error
InvalidRangeException
- if ranges is invalidread(Section)
public Array read(Section section) throws IOException, InvalidRangeException
read
in interface VariableIF
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.
IOException
- if error
InvalidRangeException
- if section is invalidpublic Array read() throws IOException
read
in interface VariableIF
IOException
public byte readScalarByte() throws IOException
readScalarByte
in interface VariableIF
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 bytepublic short readScalarShort() throws IOException
readScalarShort
in interface VariableIF
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 shortpublic int readScalarInt() throws IOException
readScalarInt
in interface VariableIF
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 intpublic long readScalarLong() throws IOException
readScalarLong
in interface VariableIF
IOException
- if theres an IO Error
UnsupportedOperationException
- if not a scalar Variable
ForbiddenConversionException
- if data type not convertible to longpublic float readScalarFloat() throws IOException
readScalarFloat
in interface VariableIF
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 floatpublic double readScalarDouble() throws IOException
readScalarDouble
in interface VariableIF
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 doublepublic String readScalarString() throws IOException
readScalarString
in interface VariableIF
IOException
- if theres an IO Error
UnsupportedOperationException
- if not a scalar or one-dimensional.
ClassCastException
- if data type not DataType.STRING or DataType.CHAR.protected Array getScalarData() throws IOException
IOException
protected Array _read() throws IOException
IOException
public Array reallyRead(Variable client, CancelTask cancelTask) throws IOException
reallyRead
in interface ProxyReader
client
- the client VariablecancelTask
- user may cancel
IOException
- on errorprotected Array _read(Section section) throws IOException, InvalidRangeException
IOException
InvalidRangeException
public Array reallyRead(Variable client, Section section, CancelTask cancelTask) throws IOException, InvalidRangeException
reallyRead
in interface ProxyReader
client
- the client Variablesection
- the section of data to read.cancelTask
- user may cancel
IOException
- on error
InvalidRangeException
- if section has incorrect rank or illegal shape.public long readToByteChannel(Section section, WritableByteChannel wbc) throws IOException, InvalidRangeException
IOException
InvalidRangeException
public String getNameAndDimensions()
public String getNameAndDimensions(boolean strict)
strict
- strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escaping
public void getNameAndDimensions(StringBuilder buf)
buf
- add info to this StringBuilderpublic void getNameAndDimensions(StringBuffer buf)
buf
- add info to this StringBufferpublic void getNameAndDimensions(StringBuilder buf, boolean useFullName, boolean strict)
buf
- add info to thisuseFullName
- use full name else short name. strict = true implies short namestrict
- strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escapingpublic void getNameAndDimensions(Formatter buf, boolean useFullName, boolean strict)
getNameAndDimensions
in interface VariableIF
buf
- add info to thisuseFullName
- use full name else short name. strict = true implies short namestrict
- strictly comply with ncgen syntax, with name escaping. otherwise, get extra info, no escapingpublic String toString()
toString
in class Object
public String writeCDL(String indent, boolean useFullName, boolean strict)
indent
- start each line with this much spaceuseFullName
- use full name, else use short namestrict
- strictly comply with ncgen syntax
protected void writeCDL(Formatter buf, String indent, boolean useFullName, boolean strict)
public String toStringDebug()
toStringDebug
in interface VariableIF
protected String extraInfo()
public boolean equals(Object oo)
equals
in class Object
public int hashCode()
hashCode
in class Object
public int compareTo(VariableSimpleIF o)
compareTo
in interface Comparable<VariableSimpleIF>
public void setDataType(DataType dataType)
dataType
- set to this valuepublic String setName(String shortName)
shortName
- set to this value
public void setParentGroup(Group group)
group
- set to this valuepublic void setElementSize(int elementSize)
elementSize
- set to this valuepublic Attribute addAttribute(Attribute att)
att
- add this Attribute
public boolean remove(Attribute a)
a
- remove this attribute
public boolean removeAttribute(String attName)
attName
- if exists, remove this attribute
public boolean removeAttributeIgnoreCase(String attName)
attName
- if exists, remove this attribute
public void setDimensions(List<Dimension> dims)
dims
- list of type ucar.nc2.Dimensionpublic void resetShape()
public void setDimensions(String dimString)
dimString
- : whitespace seperated list of dimension names, or '*' for Dimension.UNKNOWN. null or empty String is a scalar.public void resetDimensions()
public void setDimensionsAnonymous(int[] shape) throws InvalidRangeException
shape
- defines the dimension lengths. must be > 0, or -1 for VLEN
InvalidRangeException
- if any shape < 1public void setIsScalar()
public void setDimension(int idx, Dimension dim)
idx
- index into dimension arraydim
- to setpublic Variable setImmutable()
public boolean isImmutable()
public Object getSPobject()
public void setSPobject(Object spiObject)
spiObject
- the IOSP objectpublic int getSizeToCache()
public void setSizeToCache(int sizeToCache)
sizeToCache
- size at which caching happens. < 0 means use defaultspublic void setCaching(boolean caching)
caching
- set if caching.public boolean isCaching()
public void invalidateCache()
public void setCachedData(Array cacheData)
public void setCachedData(Array cacheData, boolean isMetadata)
cacheData
- cache this ArrayisMetadata
- : synthesized data, set true if must be saved in NcML output (ie data not actually in the file).public void createNewCache()
public boolean hasCachedData()
public void setValues(int npts, double start, double incr)
npts
- number of values, must = v.getSize()start
- starting valueincr
- incrementpublic void setValues(List<String> values) throws IllegalArgumentException
values
- list of Strings
IllegalArgumentException
- if values array not correct size, or values wont parse to the correct typepublic boolean isMemberOfStructure()
isMemberOfStructure
in interface VariableIF
public Structure getParentStructure()
getParentStructure
in interface VariableIF
public void setParentStructure(Structure parent)
parent
- set to this valuepublic List<Dimension> getDimensionsAll()
getDimensionsAll
in interface VariableIF
public int[] getShapeAll()
public boolean isCoordinateVariable()
isCoordinateVariable
in interface VariableIF
public Object clone() throws CloneNotSupportedException
clone
in class Object
CloneNotSupportedException
public boolean isUnknownLength()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |