visad.data.netcdf.in
Class View

java.lang.Object
  visad.data.netcdf.in.View

Direct Known Subclasses:

DefaultView

public abstract class View
extends Object

A convention-dependent view of a netCDF dataset.

Version:

$Revision: 1.9 $ $Date: 2006-02-13 22:30:08 $

Author:

Steven R. Emmerson

Nested Class Summary

protected class	View.DataIterator Iterates over the virtual VisAD data objects of this view.
protected class	View.Domain The convention-dependent domain of a netCDF variable.

Constructor Summary

protected	View(ucar.netcdf.Netcdf netcdf, QuantityDB quantityDB) Constructs from a netCDF dataset.
protected	View(ucar.netcdf.Netcdf netcdf, QuantityDB quantityDB, boolean charToText) Constructs from a netCDF dataset.

Method Summary

protected String	getAttributeString(String name) Returns a string-valued global attribute.
protected String	getAttributeString(ucar.netcdf.Variable var, String name) Returns a string-valued global attribute or a netCDF variable attribute.
protected static String	getConventionsString(ucar.netcdf.Netcdf netcdf) Returns the value of the global "Conventions" attribute.
protected ucar.netcdf.Variable	getCoordinateVariable(ucar.netcdf.Dimension dim) Returns the netCDF coordinate variable associated with a netCDF dimension.
VirtualData	getData(String name) Returns the virtual VisAD data object corresponding to a named netCDF variable.
protected VirtualData	getData(ucar.netcdf.Variable var) Returns the virtual VisAD data object corresponding to a netCDF variable.
protected ucar.netcdf.Dimension[]	getDimensions(ucar.netcdf.Variable var) Returns the netCDF dimensions of a netCDF variable.
protected abstract View.Domain	getDomain(ucar.netcdf.Variable var) Returns the domain of a netCDF variable.
protected Gridded1DSet	getDomainSet(ucar.netcdf.Dimension dim) Returns the VisAD Gridded1DSet corresponding to a netCDF dimension.
static View	getInstance(ucar.netcdf.Netcdf netcdf, QuantityDB db) Returns a view of a netCDF dataset.
static View	getInstance(ucar.netcdf.Netcdf netcdf, QuantityDB db, boolean charToText) Returns a view of a netCDF dataset.
protected String	getLongName(ucar.netcdf.Variable var) Returns the long name of a netCDF variable according to the variable's long_name attribute.
ucar.netcdf.Netcdf	getNetcdf() Returns the underlying netCDF dataset.
Set	getOuterDimensionNameSet() Returns the factorName object
protected SimpleSet	getRangeSet(ucar.netcdf.Variable var) Gets the representational set for the values of a netCDF variable.
protected RealType	getRealType(ucar.netcdf.Dimension dim) Returns the VisAD MathType of the domain corresponding to a netCDF dimension.
protected RealType	getRealType(ucar.netcdf.Variable var) Returns the VisAD RealType of a netCDF variable.
protected RealType	getRealTypeFromLongName(ucar.netcdf.Variable var) Returns the VisAD RealType corresponding to the long_name attribute of a netCDF variable.
protected RealType	getRealTypeFromName(ucar.netcdf.Variable var) Returns the VisAD RealType corresponding to the name of a netCDF variable.
protected ScalarType	getScalarType(ucar.netcdf.Variable var) Gets the type of the values of a netCDF variable.
protected TextType	getTextType(ucar.netcdf.Variable var) Return the VisAD TextType of a netCDF variable.
protected Unit	getUnitFromAttribute(ucar.netcdf.Variable var) Returns the unit of a netCDF variable according to the variable's unit attribute.
protected String	getUnitString(ucar.netcdf.Variable var) Returns the string value of the unit attribute of a netCDF variable.
protected ucar.netcdf.Variable	getVariable(String name) Returns the named netCDF variable.
protected visad.data.netcdf.in.Vetter	getVetter(ucar.netcdf.Variable var) Returns a value-vetter for a netCDF variable.
VirtualDataIterator	getVirtualDataIterator() Returns an iterator over the virtual VisAD data objects of this view.
boolean	isCharToText() Does this View handle text.
protected boolean	isCoordinateVariable(ucar.netcdf.Variable var) Indicates if a netCDF variable is a coordinate variable (i.e. has only one netCDF dimension and that dimension has the same name).
protected abstract boolean	isIgnorable(ucar.netcdf.Variable var) Indicates if a given variable should be ignored by the VirtualDataIterator during iteration over the virtual VisAD data objects in the netCDF dataset.
protected boolean	isLatitude(RealType type) Indicates if a VisAD RealType represents latitude.
protected boolean	isLongitude(RealType type) Indicates if a VisAD RealType represents longitude.
protected boolean	isLongitude(ucar.netcdf.Variable var) Indicates if a netCDF dimension represents longitude.
protected boolean	isNumeric(String name) Indicates if the netCDF variable with a given name is numeric.
protected boolean	isNumeric(ucar.netcdf.Variable var) Indicates if the given netCDF variable is numeric.
protected boolean	isTime(ucar.netcdf.Dimension dim) Indicates if a netCDF dimension represents time.
protected boolean	isTime(Unit unit) Indicates if a unit is a unit of time.
protected String	newName(ucar.netcdf.Variable var) Returns a name for a given variable that is slightly different that the variable's name and is guarenteed not to have been returned before.
void	setOuterDimensionNameSet(Set nameSet) Defines the names of domain components to factor out.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

View

protected View(ucar.netcdf.Netcdf netcdf,
               QuantityDB quantityDB)

Constructs from a netCDF dataset.

Parameters:

netcdf - The netCDF dataset.

quantityDB - The quantity database to use to map netCDF variables to VisAD Quantity-s.

Throws:

NullPointerException - if either argument is null.

View

protected View(ucar.netcdf.Netcdf netcdf,
               QuantityDB quantityDB,
               boolean charToText)

Constructs from a netCDF dataset.

Parameters:

netcdf - The netCDF dataset.

quantityDB - The quantity database to use to map netCDF variables to VisAD Quantity-s.

charToText - Specifies whether the View should map char variables to VisAD Text objects

Throws:

NullPointerException - if either argument is null.

Method Detail

getInstance

public static View getInstance(ucar.netcdf.Netcdf netcdf,
                               QuantityDB db)

Returns a view of a netCDF dataset. The exact view returned depends on the netCDF dataset.

Parameters:

netcdf - The netCDF dataset.

db - A quantity database to be used to map netCDF variables to VisAD Quantitys.

Returns:

A view of the dataset.

getInstance

public static View getInstance(ucar.netcdf.Netcdf netcdf,
                               QuantityDB db,
                               boolean charToText)

Returns a view of a netCDF dataset. The exact view returned depends on the netCDF dataset.

Parameters:

netcdf - The netCDF dataset.

db - A quantity database to be used to map netCDF variables to VisAD Quantitys.

charToText - Specifies whether the View should map char variables to VisAD Text objects

Returns:

A view of the dataset.

isCharToText

public boolean isCharToText()

Does this View handle text.

Returns:

true if text is handled

getNetcdf

public ucar.netcdf.Netcdf getNetcdf()

Returns the underlying netCDF dataset.

Returns:

The netCDF dataset.

getConventionsString

protected static String getConventionsString(ucar.netcdf.Netcdf netcdf)

Returns the value of the global "Conventions" attribute. If the attribute doesn't exist or is invalid, then null is returned. If the attribute exists but is not string-valued, then an error message is printed to System.err and null is returned.

Parameters:

netcdf - The netCDF dataset.

Returns:

The value of the attribute.

getVariable

protected ucar.netcdf.Variable getVariable(String name)

Returns the named netCDF variable. Returns null if the variable doesn't exist.

Parameters:

name - The name of the netCDF variable.

Returns:

The named netCDF variable or null.

Throws:

NullPointerException - if the name is null.

isNumeric

protected boolean isNumeric(String name)

Indicates if the netCDF variable with a given name is numeric.

Parameters:

name - The name of the netCDF variable.

Returns:

true if and only if the variable exists has numeric values.

isNumeric

protected boolean isNumeric(ucar.netcdf.Variable var)

Indicates if the given netCDF variable is numeric.

Parameters:

var - The netCDF variable.

Returns:

true if and only if the variable is numeric.

Throws:

NullPointerException - if the argument is null.

isLongitude

protected boolean isLongitude(ucar.netcdf.Variable var)
                       throws VisADException

Indicates if a netCDF dimension represents longitude. This method uses getRealType(Variable) and isLongitude(RealType).

Parameters:

var - A netCDF dimension.

Returns:

true if an only if dim represents longitude.

Throws:

VisADException - Couldn't create necessary VisAD object.

isLongitude

protected boolean isLongitude(RealType type)

Indicates if a VisAD RealType represents longitude.

Parameters:

type - A VisAD RealType. May be null.

Returns:

true if an only if the VisAD RealType represents longitude.

isLatitude

protected boolean isLatitude(RealType type)

Indicates if a VisAD RealType represents latitude.

Parameters:

type - A VisAD RealType. May be null.

Returns:

true if an only if the VisAD RealType represents latitude.

getRealType

protected RealType getRealType(ucar.netcdf.Dimension dim)
                        throws TypeException

Returns the VisAD MathType of the domain corresponding to a netCDF dimension.

This implementation supports coordinate variables and uses getCoordinateVariable(Dimension) and getRealType(Variable).

Parameters:

dim - A netCDF dimension.

Returns:

The VisAD MathType of the domain corresponding to dim. Won't be null.

Throws:

TypeException - if a corresponding RealType needed to be created but couldn't.

getRealType

protected RealType getRealType(ucar.netcdf.Variable var)
                        throws TypeException

Returns the VisAD RealType of a netCDF variable.

This implementation returns the value of getRealTypeFromLongName(Variable) if that is non-null; otherwise, the value of getRealTypeFromName(Variable) is returned.

Parameters:

var - The netCDF variable.

Returns:

The corresponding VisAD RealType.

Throws:

NullPointerException - if the argument is null.

TypeException - if a corresponding RealType needed to be created but couldn't.

getRealTypeFromLongName

protected RealType getRealTypeFromLongName(ucar.netcdf.Variable var)

Returns the VisAD RealType corresponding to the long_name attribute of a netCDF variable. If the unit attribute of the variable is incompatible with the unit of the long_name attribute, then a new RealType is created whose default unit is that of the attribute.

This implementation first checks if the variable has a long_name attribute via getLongName(Variable), if it doesn't, then null is returned; otherwise, the long name is used to query the quantity database. If the quantity database doesn't contain a match, then null is returned; otherwise, the variable's unit attribute -- obtained via getUnitFromAttribute(Variable) -- is checked. If the unit attribute doesn't exist, then the RealType is returned; otherwise, the unit attribute is compared against the default unit of the RealType. If the two are convertible, then the RealType is returned; otherwise, an attempt is made to create a new RealType with a slightly different name than the variable's but with the same unit as the variable's and that RealType is returned.

Parameters:

var - The netCDF variable.

Returns:

The corresponding VisAD RealType or null if no corresponding type was found or could be created.

getRealTypeFromName

protected RealType getRealTypeFromName(ucar.netcdf.Variable var)
                                throws TypeException

Returns the VisAD RealType corresponding to the name of a netCDF variable. null is never returned.

This implementation first obtains the variable's unit via getUnitFromAttribute(Variable). It then queries the quantity database for a match to the variable's name. If a match is found, then variable's unit is checked. If the unit is null, then the RealType from the database is returned; otherwise, the unit is checked against the default unit of the obtained RealType. If the two units are convertible, then the RealType is returned; otherwise, a new RealType is created that has a slightly different name than the variable's but with the variable's unit and that RealType is returned. If the quantity database doesn't contain a match, then the variable's unit is checked. If it's null, then the value of RealType.getRealType(String) -- when given the variable's name -- is returned; otherwise, the return value of RealType.getRealType(String, Unit) -- when invoked with the variable's name and unit -- is checked. If it's non-null, then that RealType is returned; otherwise, a new RealType is created that has a slightly different name than the variable's but with the variable's unit and that RealType is returned.

Parameters:

var - The netCDF variable.

Returns:

The corresponding VisAD RealType.

Throws:

TypeException - if a corresponding RealType needed to be created but couldn't.

newName

protected String newName(ucar.netcdf.Variable var)

Returns a name for a given variable that is slightly different that the variable's name and is guarenteed not to have been returned before.

Parameters:

var - The netCDF variable.

Returns:

A new and unique name based on the variable.

getScalarType

protected ScalarType getScalarType(ucar.netcdf.Variable var)
                            throws TypeException,
                                   VisADException

Gets the type of the values of a netCDF variable.

This implementation returns the value of #getRealType(Variable)} or getTextType(Variable) -- depending on the value of isNumeric(Variable).

Parameters:

var - A netCDF variable.

Throws:

TypeException - if a corresponding RealType needed to be created but couldn't.

VisADException - if a VisAD object can't be created.

getTextType

protected TextType getTextType(ucar.netcdf.Variable var)
                        throws VisADException

Return the VisAD TextType of a netCDF variable.

Parameters:

var - The netCDF variable.

Returns:

The VisAD TextType of var.

Throws:

VisADException - if a VisAD object couldn't be created.

IllegalArgumentException - if the netCDF variable is not textual.

getRangeSet

protected SimpleSet getRangeSet(ucar.netcdf.Variable var)
                         throws TypeException,
                                VisADException

Gets the representational set for the values of a netCDF variable. If the variable isn't numeric, then null is returned.

This implementation uses getRealType(Variable), getVetter(Variable), and getUnitFromAttribute(Variable).

Parameters:

var - A netCDF variable.

Returns:

The VisAD representational set for the values of the variable or null.

Throws:

TypeException - if a corresponding RealType needed to be created but couldn't.

VisADException - Couldn't create necessary VisAD object.

getAttributeString

protected String getAttributeString(String name)

Returns a string-valued global attribute. If the attribute doesn't exist or is invalid, then null is returned. If the attribute exists but is not string-valued, then an error message is printed to System.err and null is returned.

This implementation uses getAttributeString(Variable, String).

Parameters:

name - The name of the attribute.

Returns:

The string value of the attribute or null.

getAttributeString

protected String getAttributeString(ucar.netcdf.Variable var,
                                    String name)

Returns a string-valued global attribute or a netCDF variable attribute. If the attribute doesn't exist or is invalid, then null is returned. If the attribute exists but is not string-valued, then an error message is printed to System.err and null is returned.

Parameters:

var - A netCDF variable or null to indicate a global attribute.

name - The name of the attribute.

Returns:

The string value of the attribute or null.

getLongName

protected String getLongName(ucar.netcdf.Variable var)

Returns the long name of a netCDF variable according to the variable's long_name attribute. If the attribute doesn't exist, then null is returned.

This method uses getAttributeString(Variable, String).

Parameters:

var - A netCDF variable.

Returns:

The long name of var or null.

Throws:

ClassCastException - if the attribute exists but its value isn't a String.

getUnitString

protected String getUnitString(ucar.netcdf.Variable var)

Returns the string value of the unit attribute of a netCDF variable. Returns null if the unit attribute is missing or invalid.

This method uses getAttributeString(Variable, String) -- first with the name "units" and then with the name "unit".

Parameters:

var - A netCDF variable.

Returns:

The unit of the values of var or null.

getUnitFromAttribute

protected Unit getUnitFromAttribute(ucar.netcdf.Variable var)

Returns the unit of a netCDF variable according to the variable's unit attribute. Returns null if the unit attribute is missing or invalid. If a unit specification exists but can't be decoded, then a warning message is printed to System.err.

This method uses getUnitString(Variable).

Parameters:

var - A netCDF variable.

Returns:

The unit of the values of var or null.

getVetter

protected visad.data.netcdf.in.Vetter getVetter(ucar.netcdf.Variable var)

Returns a value-vetter for a netCDF variable.

Parameters:

var - A netCDF variable.

Returns:

A value-vetter for the variable.

getDomainSet

protected Gridded1DSet getDomainSet(ucar.netcdf.Dimension dim)
                             throws VisADException,
                                    IOException

Returns the VisAD Gridded1DSet corresponding to a netCDF dimension.

This implementation supports coordinate variables, longitude, and the discovery of an arithmetic progression. It uses isLongitude(Variable), getRealType(Dimension), and getUnitFromAttribute(Variable).

Parameters:

dim - A netCDF dimension.

Returns:

The VisAD GriddedSet corresponding to the dimension.

Throws:

VisADException - if a VisAD object couldn't be created.

IOException - if a netCDF read-error occurs.

ClassCastException - if the dimension has a coordinate variable of improper type.

getCoordinateVariable

protected ucar.netcdf.Variable getCoordinateVariable(ucar.netcdf.Dimension dim)

Returns the netCDF coordinate variable associated with a netCDF dimension. If no such variable exists, then null is returned.

This implementation uses isNumeric(Variable).

Parameters:

dim - A netCDF dimension.

Returns:

The netCDF coordinate variable associated with the dimension or null if there is no coordinate variable.

setOuterDimensionNameSet

public void setOuterDimensionNameSet(Set nameSet)

Defines the names of domain components to factor out. This only works if this names correspond to the outermost dimension. The list of names may be changed after calling this.

The Set should contain only String(s).

Typically, a TreeSet will be used. For example:

TreeSet ts = new TreeSet(); ts.add("myParameter"); view.setOuterDimensionNameSet(ts);

Parameters:

nameSet - A Set containing the names (as Strings) of the dimensions to factor out.

getOuterDimensionNameSet

public Set getOuterDimensionNameSet()

Returns the factorName object

Returns:

The Set of factorNames.

isTime

protected boolean isTime(ucar.netcdf.Dimension dim)
                  throws VisADException,
                         IOException

Indicates if a netCDF dimension represents time.

This implementation supports coordinate variables and uses getRealType(Dimension).

If setOuterDimensionNameSet() has been called, this list of names will also logically be considered factorable.

Parameters:

dim - A netCDF dimension.

Returns:

true if and only if the dimension represents time.

Throws:

VisADException - Couldn't create necessary VisAD object.

IOException - I/O failure.

isTime

protected boolean isTime(Unit unit)

Indicates if a unit is a unit of time.

Parameters:

unit - A unit.

Returns:

true if and only if the unit is a unit of time.

getDimensions

protected ucar.netcdf.Dimension[] getDimensions(ucar.netcdf.Variable var)

Returns the netCDF dimensions of a netCDF variable.

Parameters:

var - A netCDF variable.

Returns:

The dimensions of var in netCDF order.

isCoordinateVariable

protected boolean isCoordinateVariable(ucar.netcdf.Variable var)

Indicates if a netCDF variable is a coordinate variable (i.e. has only one netCDF dimension and that dimension has the same name).

This implementation uses isNumeric(Variable).

Parameters:

var - A netCDF variable.

Returns:

true if and only if var is a coordinate variable.

getVirtualDataIterator

public VirtualDataIterator getVirtualDataIterator()

Returns an iterator over the virtual VisAD data objects of this view.

Returns:

An iterator over the virtual VisAD data objects of the view.

isIgnorable

protected abstract boolean isIgnorable(ucar.netcdf.Variable var)

Indicates if a given variable should be ignored by the VirtualDataIterator during iteration over the virtual VisAD data objects in the netCDF dataset.

Returns:

true if and only if the variable should be ignored.

getDomain

protected abstract View.Domain getDomain(ucar.netcdf.Variable var)
                                  throws TypeException,
                                         IOException

Returns the domain of a netCDF variable.

Parameters:

var - A netCDF variable.

Returns:

The domain of the netCDF variable.

Throws:

IllegalArgumentException - if the rank of the variable is zero.

TypeException - if a RealType needed to be created but couldn't.

IOException - if a netCDF read-error occurs.

getData

public VirtualData getData(String name)
                    throws TypeException,
                           VisADException,
                           IOException

Returns the virtual VisAD data object corresponding to a named netCDF variable.

This implementation uses getData(Variable).

Parameters:

name - The name of the netCDF variable.

Returns:

The corresponding virtual VisAD data object.

Throws:

NullPointerException - if the argument is null.

IllegalArgumentException - if the netCDF variable doesn't exist.

TypeException - if a RealType needed to be created but couldn't.

VisADException - if a VisAD object couldn't be created.

IOException - if a netCDF read-error occurs.

getData

protected VirtualData getData(ucar.netcdf.Variable var)
                       throws TypeException,
                              VisADException,
                              IOException

Returns the virtual VisAD data object corresponding to a netCDF variable.

This implementation uses getRealType(Variable), getRangeSet(Variable), getUnitFromAttribute(Variable), getVetter(Variable), and getDomain(Variable).

Parameters:

var - The netCDF variable.

Returns:

The corresponding virtual VisAD data object.

Throws:

NullPointerException - if the argument is null.

TypeException - if a RealType needed to be created but couldn't.

VisADException - if a VisAD object couldn't be created.

IOException - if a netCDF read-error occurs.