ucar.nc2.dataset
Class VariableDS

java.lang.Object
  ucar.nc2.Variable
      ucar.nc2.dataset.VariableDS

All Implemented Interfaces:

java.lang.Comparable<VariableSimpleIF>, Enhancements, EnhanceScaleMissing, VariableEnhanced, ProxyReader, VariableIF, VariableSimpleIF

Direct Known Subclasses:

CoordinateAxis

public class VariableDS
extends Variable
implements VariableEnhanced, EnhanceScaleMissing

An wrapper around a Variable, creating an "enhanced" Variable. The original Variable is used for the I/O. There are several distinct uses:

1. 1) handle scale/offset/missing values/enum conversion; this can change DataType and data values
2. 2) container for coordinate system information
3. 3) NcML modifications to underlying Variable

Author:

caron

See Also:

NetcdfDataset

Field Summary

Fields inherited from class ucar.nc2.Variable

defaultCoordsSizeToCache, defaultSizeToCache

Constructor Summary

VariableDS(Group group, Structure parent, java.lang.String shortName, Variable orgVar)
Make a new VariableDS, delegate data reading to the original variable, but otherwise dont take any info from it.

VariableDS(Group g, Variable orgVar, boolean enhance)
Wrap the given Variable, making it into a VariableDS.

VariableDS(NetcdfDataset ds, Group group, Structure parentStructure, java.lang.String shortName, DataType dataType, java.lang.String dims, java.lang.String units, java.lang.String desc)
Constructor when there's no underlying variable.

Method Summary

void	addCoordinateSystem(CoordinateSystem p0) Add a CoordinateSystem to the dataset.
void	clearCoordinateSystems() Remove coordinate system info.
Array	convertScaleOffsetMissing(Array data) Convert data if hasScaleOffset, using scale and offset.
double	convertScaleOffsetMissing(byte value) Convert this byte value to a double, using scale/offset/missing value if applicable
double	convertScaleOffsetMissing(double value) Convert this double value using scale/offset/missing value if applicable
double	convertScaleOffsetMissing(int value) Convert this int value to a double, using scale/offset/missing value if applicable
double	convertScaleOffsetMissing(long value) Convert this long value to a double, using scale/offset/missing value if applicable
double	convertScaleOffsetMissing(short value) Convert this short value to a double, using scale/offset/missing value if applicable
void	enhance(java.util.Set<NetcdfDataset.Enhance> mode) DO NOT USE DIRECTLY.
java.util.List<CoordinateSystem>	getCoordinateSystems() Get the list of Coordinate Systems for this Variable.
java.lang.String	getDescription() Get the description of the Variable.
java.util.EnumSet<NetcdfDataset.Enhance>	getEnhanceMode() Get the enhancement mode
Array	getMissingDataArray(int[] shape) Return Array with missing data
DataType	getOriginalDataType() When this wraps another Variable, get the original Variable's DataType.
java.lang.String	getOriginalName() When this wraps another Variable, get the original Variable's name.
Variable	getOriginalVariable() A VariableDS usually wraps another Variable.
java.lang.String	getUnitsString() Get the Unit String for the Variable.
boolean	getUseNaNs() get whether to use NaNs for missing float/double values (for efficiency)
double	getValidMax() return the maximum value in the valid range
double	getValidMin() return the minimum value in the valid range
boolean	hasCachedDataRecurse()
boolean	hasFillValue() true if Variable has _FillValue attribute
boolean	hasInvalidData() true if Variable has valid_range, valid_min or valid_max attributes
boolean	hasMissing() true if Variable has missing data values
boolean	hasMissingValue() true if Variable has missing_value attribute
boolean	hasScaleOffset() true if Variable data will be converted using scale and offet
boolean	isFillValue(double p0) return true if val equals the _FillValue
boolean	isInvalidData(double p0) return true if val is outside the valid range
boolean	isMissing(double val) true if val is a missing data value.
boolean	isMissingFast(double val) true if val is a missing data value.
boolean	isMissingValue(double p0) return true if val equals a missing_value
java.lang.String	lookupEnumString(int val) Lookup the enum string for this value.
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.
void	removeCoordinateSystem(CoordinateSystem p0) Remove a CoordinateSystem from the dataset.
void	setFillValueIsMissing(boolean p0) set if _FillValue is considered isMissing(); better set in constructor if possible
void	setInvalidDataIsMissing(boolean p0) set if valid_range is considered isMissing(); better set in constructor if possible
void	setMissingDataIsMissing(boolean p0) set if missing_data is considered isMissing(); better set in constructor if possible
void	setName(java.lang.String newName) Set the short name
void	setOriginalVariable(Variable orgVar) Set the Variable to wrap.
void	setUnitsString(java.lang.String units) Set the Unit String for this Variable.
void	setUseNaNs(boolean useNaNs) set whether to use NaNs for missing float/double values, for efficiency
void	showScaleMissingProxy(java.util.Formatter f) public for debugging
java.lang.String	toStringDebug() String representation of Variable and its attributes.

Methods inherited from class ucar.nc2.Variable

addAttribute, compareTo, createNewCache, equals, findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getDataType, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getElementSize, getEnumTypedef, getName, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameEscaped, getParentGroup, getParentStructure, getProxyReader, getRanges, getRank, getShape, getShape, getShapeAll, getShapeAsSection, getShortName, getSize, getSizeToCache, getSPobject, hasCachedData, hashCode, invalidateCache, isCaching, isCoordinateVariable, isImmutable, isMemberOfStructure, isMetadata, isScalar, isUnknownLength, isUnlimited, isUnsigned, isVariableLength, read, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToByteChannel, remove, removeAttribute, removeAttributeIgnoreCase, resetDimensions, resetShape, section, section, setCachedData, setCachedData, setCaching, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setEnumTypedef, setImmutable, setIsScalar, setParentGroup, setParentStructure, setProxyReader, setSizeToCache, setSPobject, slice, toString, writeCDL

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface ucar.nc2.VariableIF

findAttribute, findAttributeIgnoreCase, findDimensionIndex, getAttributes, getDataType, getDimension, getDimensions, getDimensionsAll, getElementSize, getName, getNameAndDimensions, getNameEscaped, getParentGroup, getParentStructure, getRanges, getRank, getShape, getShapeAsSection, getShortName, getSize, isCoordinateVariable, isMemberOfStructure, isMetadata, isScalar, isUnlimited, isUnsigned, isVariableLength, read, read, read, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, section

Methods inherited from interface java.lang.Comparable

compareTo

Constructor Detail

VariableDS

public VariableDS(NetcdfDataset ds,
                  Group group,
                  Structure parentStructure,
                  java.lang.String shortName,
                  DataType dataType,
                  java.lang.String dims,
                  java.lang.String units,
                  java.lang.String desc)

Constructor when there's no underlying variable. You must also set the values by doing one of:

1. set the values with setCachedData()
2. set a proxy reader with setProxyReader()

Otherwise, it is assumed to have constant values (using the fill value)

Parameters:

ds - the containing dataset

group - the containing group

parentStructure - the containing Structure (may be null)

shortName - the (short) name

dataType - the data type

dims - list of dimension names, these must already exist in the Group; empty String = scalar

units - String value of units, may be null

desc - String value of description, may be null

VariableDS

public VariableDS(Group group,
                  Structure parent,
                  java.lang.String shortName,
                  Variable orgVar)

Make a new VariableDS, delegate data reading to the original variable, but otherwise dont take any info from it. This is used by NcML explicit mode.

Parameters:

group - the containing group; may not be null

parent - parent Structure, may be null

shortName - variable shortName, must be unique within the Group

orgVar - the original Variable to wrap. The original Variable is not modified. Must not be a Structure, use StructureDS instead.

VariableDS

public VariableDS(Group g,
                  Variable orgVar,
                  boolean enhance)

Wrap the given Variable, making it into a VariableDS. Delegate data reading to the original variable. Take all metadata from original variable. Does not share cache, iosp.

Parameters:

g - logical container, if null use orgVar's group

orgVar - the original Variable to wrap. The original Variable is not modified. Must not be a Structure, use StructureDS instead.

enhance - if true, use NetcdfDataset.defaultEnhanceMode to define what enhancements are made. Note that this can change DataType and data values. You can also call enhance() later. If orgVar is VariableDS, then enhance is inherited from there, and this parameter is ignored.

Method Detail

clearCoordinateSystems

public void clearCoordinateSystems()

Remove coordinate system info.

Specified by:

clearCoordinateSystems in interface VariableEnhanced

enhance

public void enhance(java.util.Set<NetcdfDataset.Enhance> mode)

DO NOT USE DIRECTLY. public by accident. Calculate scale/offset/missing value info. This may change the DataType.

Specified by:

enhance in interface VariableEnhanced

getEnhanceMode

public java.util.EnumSet<NetcdfDataset.Enhance> getEnhanceMode()

Get the enhancement mode

Returns:

the enhancement mode

addCoordinateSystem

public void addCoordinateSystem(CoordinateSystem p0)

Description copied from interface: Enhancements

Add a CoordinateSystem to the dataset.

Specified by:

addCoordinateSystem in interface Enhancements

Parameters:

p0 - add this Coordinate System

removeCoordinateSystem

public void removeCoordinateSystem(CoordinateSystem p0)

Description copied from interface: Enhancements

Remove a CoordinateSystem from the dataset.

Specified by:

removeCoordinateSystem in interface Enhancements

Parameters:

p0 - remove this coordinate system

getCoordinateSystems

public java.util.List<CoordinateSystem> getCoordinateSystems()

Description copied from interface: Enhancements

Get the list of Coordinate Systems for this Variable.

Specified by:

getCoordinateSystems in interface Enhancements

Returns:

list of type CoordinateSystem; may be empty but not null.

getDescription

public java.lang.String getDescription()

Description copied from class: Variable

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 Enhancements

Specified by:

getDescription in interface VariableIF

Specified by:

getDescription in interface VariableSimpleIF

Overrides:

getDescription in class Variable

Returns:

description, or null if not found.

getUnitsString

public java.lang.String getUnitsString()

Description copied from class: Variable

Get the Unit String for the Variable. Looks for the "units" attribute value

Specified by:

getUnitsString in interface Enhancements

Specified by:

getUnitsString in interface VariableIF

Specified by:

getUnitsString in interface VariableSimpleIF

Overrides:

getUnitsString in class Variable

Returns:

unit string, or null if not found.

setUnitsString

public void setUnitsString(java.lang.String units)

Description copied from interface: VariableEnhanced

Set the Unit String for this Variable. Default is to use the "units" attribute.

Specified by:

setUnitsString in interface VariableEnhanced

Parameters:

units - unit string

convertScaleOffsetMissing

public Array convertScaleOffsetMissing(Array data)

Description copied from interface: EnhanceScaleMissing

Convert data if hasScaleOffset, using scale and offset. Also if useNaNs = true, return NaN if value is missing data.

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

Parameters:

data - convert this

Returns:

converted data.

getValidMax

public double getValidMax()

Description copied from interface: EnhanceScaleMissing

return the maximum value in the valid range

Specified by:

getValidMax in interface EnhanceScaleMissing

getValidMin

public double getValidMin()

Description copied from interface: EnhanceScaleMissing

return the minimum value in the valid range

Specified by:

getValidMin in interface EnhanceScaleMissing

hasFillValue

public boolean hasFillValue()

Description copied from interface: EnhanceScaleMissing

true if Variable has _FillValue attribute

Specified by:

hasFillValue in interface EnhanceScaleMissing

hasInvalidData

public boolean hasInvalidData()

Description copied from interface: EnhanceScaleMissing

true if Variable has valid_range, valid_min or valid_max attributes

Specified by:

hasInvalidData in interface EnhanceScaleMissing

hasMissing

public boolean hasMissing()

Description copied from interface: EnhanceScaleMissing

true if Variable has missing data values

Specified by:

hasMissing in interface EnhanceScaleMissing

Returns:

true if Variable has missing data values

hasMissingValue

public boolean hasMissingValue()

Description copied from interface: EnhanceScaleMissing

true if Variable has missing_value attribute

Specified by:

hasMissingValue in interface EnhanceScaleMissing

hasScaleOffset

public boolean hasScaleOffset()

Description copied from interface: EnhanceScaleMissing

true if Variable data will be converted using scale and offet

Specified by:

hasScaleOffset in interface EnhanceScaleMissing

isFillValue

public boolean isFillValue(double p0)

Description copied from interface: EnhanceScaleMissing

return true if val equals the _FillValue

Specified by:

isFillValue in interface EnhanceScaleMissing

isInvalidData

public boolean isInvalidData(double p0)

Description copied from interface: EnhanceScaleMissing

return true if val is outside the valid range

Specified by:

isInvalidData in interface EnhanceScaleMissing

isMissing

public boolean isMissing(double val)

Description copied from interface: EnhanceScaleMissing

true if val is a missing data value.

Specified by:

isMissing in interface EnhanceScaleMissing

Parameters:

val - unpacked value

Returns:

true if this value is a misssing value

isMissingFast

public boolean isMissingFast(double val)

Description copied from interface: EnhanceScaleMissing

true if val is a missing data value. if useNaNs is true (default) and the variable is of type float or double, then assume that missing values have been set to NaN, which speeds up the test considerably.

Specified by:

isMissingFast in interface EnhanceScaleMissing

Parameters:

val - unpacked value

Returns:

true if this value is a misssing value

isMissingValue

public boolean isMissingValue(double p0)

Description copied from interface: EnhanceScaleMissing

return true if val equals a missing_value

Specified by:

isMissingValue in interface EnhanceScaleMissing

setFillValueIsMissing

public void setFillValueIsMissing(boolean p0)

Description copied from interface: EnhanceScaleMissing

set if _FillValue is considered isMissing(); better set in constructor if possible

Specified by:

setFillValueIsMissing in interface EnhanceScaleMissing

setInvalidDataIsMissing

public void setInvalidDataIsMissing(boolean p0)

Description copied from interface: EnhanceScaleMissing

set if valid_range is considered isMissing(); better set in constructor if possible

Specified by:

setInvalidDataIsMissing in interface EnhanceScaleMissing

setMissingDataIsMissing

public void setMissingDataIsMissing(boolean p0)

Description copied from interface: EnhanceScaleMissing

set if missing_data is considered isMissing(); better set in constructor if possible

Specified by:

setMissingDataIsMissing in interface EnhanceScaleMissing

setUseNaNs

public void setUseNaNs(boolean useNaNs)

Description copied from interface: EnhanceScaleMissing

set whether to use NaNs for missing float/double values, for efficiency

Specified by:

setUseNaNs in interface EnhanceScaleMissing

getUseNaNs

public boolean getUseNaNs()

Description copied from interface: EnhanceScaleMissing

get whether to use NaNs for missing float/double values (for efficiency)

Specified by:

getUseNaNs in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(byte value)

Description copied from interface: EnhanceScaleMissing

Convert this byte value to a double, using scale/offset/missing value if applicable

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(short value)

Description copied from interface: EnhanceScaleMissing

Convert this short value to a double, using scale/offset/missing value if applicable

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(int value)

Description copied from interface: EnhanceScaleMissing

Convert this int value to a double, using scale/offset/missing value if applicable

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(long value)

Description copied from interface: EnhanceScaleMissing

Convert this long value to a double, using scale/offset/missing value if applicable

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

convertScaleOffsetMissing

public double convertScaleOffsetMissing(double value)

Description copied from interface: EnhanceScaleMissing

Convert this double value using scale/offset/missing value if applicable

Specified by:

convertScaleOffsetMissing in interface EnhanceScaleMissing

getOriginalVariable

public Variable getOriginalVariable()

A VariableDS usually wraps another Variable.

Specified by:

getOriginalVariable in interface VariableEnhanced

Returns:

original Variable or null

setOriginalVariable

public void setOriginalVariable(Variable orgVar)

Set the Variable to wrap. Used by NcML explicit mode.

Specified by:

setOriginalVariable in interface VariableEnhanced

Parameters:

orgVar - original Variable, must not be a Structure

getOriginalDataType

public DataType getOriginalDataType()

When this wraps another Variable, get the original Variable's DataType.

Returns:

original Variable's DataType, or current data type if it doesnt wrap anothe rvariable

getOriginalName

public java.lang.String getOriginalName()

When this wraps another Variable, get the original Variable's name.

Specified by:

getOriginalName in interface VariableEnhanced

Returns:

original Variable's name

lookupEnumString

public java.lang.String lookupEnumString(int val)

Description copied from class: Variable

Lookup the enum string for this value. Can only be called on enum types, where dataType.isEnum() is true.

Overrides:

lookupEnumString in class Variable

Parameters:

val - the integer value of this enum

Returns:

the String value

setName

public void setName(java.lang.String newName)

Description copied from class: Variable

Set the short name

Overrides:

setName in class Variable

Parameters:

newName - set to this value

toStringDebug

public java.lang.String toStringDebug()

Description copied from class: Variable

String representation of Variable and its attributes.

Specified by:

toStringDebug in interface VariableIF

Overrides:

toStringDebug in class Variable

hasCachedDataRecurse

public boolean hasCachedDataRecurse()

reallyRead

public Array reallyRead(Variable client,
                        CancelTask cancelTask)
                 throws java.io.IOException

Description copied from class: Variable

public by accident, do not call directly.

Specified by:

reallyRead in interface ProxyReader

Overrides:

reallyRead in class Variable

Parameters:

client - the client Variable

cancelTask - user may cancel

Returns:

Array

Throws:

java.io.IOException - on error

reallyRead

public Array reallyRead(Variable client,
                        Section section,
                        CancelTask cancelTask)
                 throws java.io.IOException,
                        InvalidRangeException

Description copied from class: Variable

public by accident, do not call directly.

Specified by:

reallyRead in interface ProxyReader

Overrides:

reallyRead in class Variable

Parameters:

client - the client Variable

section - the section of data to read.

cancelTask - user may cancel

Returns:

Array

Throws:

java.io.IOException - on error

InvalidRangeException - if section has incorrect rank or illegal shape.

getMissingDataArray

public Array getMissingDataArray(int[] shape)

Return Array with missing data

Parameters:

shape - of this shape

Returns:

Array with given shape

showScaleMissingProxy

public void showScaleMissingProxy(java.util.Formatter f)

public for debugging

Parameters:

f - put info here