ucar.nc2.ncml
Class NcMLReader

java.lang.Object
  ucar.nc2.ncml.NcMLReader

public class NcMLReader
extends java.lang.Object

Read NcML and create NetcdfDataset. Note that this is thread-safe.

Version:

$Revision: 63 $ $Date: 2006-07-12 15:50:51 -0600 (Wed, 12 Jul 2006) $

Author:

caron

See Also:

NetcdfFile

Field Summary

static org.jdom.Namespace

ncNS

Constructor Summary

NcMLReader()

Method Summary

protected void	addAttribute(java.lang.Object parent, Attribute att)
protected Attribute	findAttribute(java.lang.Object parent, java.lang.String name)
static void	main(java.lang.String[] arg)
static org.jdom.Element	readAggregation(java.lang.String filename) Read an Aggregation element from a filename and return the root element.
protected void	readAtt(java.lang.Object parent, java.lang.Object refParent, org.jdom.Element attElem) Read an NcML attribute element.
protected void	readDim(Group g, Group refg, org.jdom.Element dimElem) Read an NcML dimension element.
protected void	readGroup(NetcdfDataset newds, NetcdfDataset refds, Group parent, Group refParent, org.jdom.Element groupElem) Read the NcML group element, and nested elements.
static NetcdfDataset	readNcML(java.io.InputStream ins, CancelTask cancelTask) Read NcML doc from an InputStream, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(java.lang.String ncmlLocation, CancelTask cancelTask) Read an NcML file from a URL location, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(java.lang.String ncmlLocation, org.jdom.Element netcdfElem, CancelTask cancelTask) Read NcML a JDOM Element, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(java.lang.String ncmlLocation, java.lang.String referencedDatasetUri, CancelTask cancelTask) Read an NcML file from a URL location, and construct a NetcdfDataset.
void	readNetcdf(java.lang.String ncmlLocation, NetcdfDataset newds, NetcdfDataset refds, org.jdom.Element netcdfElem, CancelTask cancelTask) parse a netcdf JDOM Element, and add contents to the newds NetcdfDataset.
protected void	readValues(NetcdfDataset ds, Variable v, org.jdom.Element varElem, org.jdom.Element valuesElem)
protected void	readVariable(NetcdfDataset ds, Group g, Group refg, org.jdom.Element varElem) Read the NcML variable element, and nested elements.
protected void	readVariableNested(NetcdfDataset ds, Structure parentS, Structure refStruct, org.jdom.Element varElem) Read the NcML variable element, and nested elements.
protected Variable	readVariableNew(NetcdfDataset ds, Group g, Structure parentS, org.jdom.Element varElem) Read a NcML variable element, and nested elements, when it creates a new Variable.
static void	setDebugFlags(DebugFlags debugFlag)
static void	transferDataset(NetcdfFile src, NetcdfDataset target, ReplaceVariableCheck replaceCheck) Copy contents of "from" to "to", as long as "to" doesnt already have an elements of that name.
static void	transferGroupAttributes(Group src, Group target)
static void	wrapNcML(NetcdfDataset ncDataset, java.lang.String ncmlLocation, CancelTask cancelTask) Use NCML to modify the dataset, getting NcML from a URL
static void	wrapNcMLresource(NetcdfDataset ncDataset, java.lang.String ncmlResourceLocation, CancelTask cancelTask) Use NCML to modify a dataset, getting NcML as a resource stream
static void	writeNcMLToFile(java.io.InputStream ncml, java.lang.String fileOutName) Read an NcML and write an equivilent NetcdfFile to a physical file, using Netcdf-3 file format.
static void	writeNcMLToFile(java.lang.String ncmlLocation, java.lang.String fileOutName) Read an NcML file and write an equivilent NetcdfFile to a physical file, using Netcdf-3 file format.

Methods inherited from class java.lang.Object

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

Field Detail

ncNS

public static final org.jdom.Namespace ncNS

Constructor Detail

NcMLReader

public NcMLReader()

Method Detail

setDebugFlags

public static void setDebugFlags(DebugFlags debugFlag)

wrapNcMLresource

public static void wrapNcMLresource(NetcdfDataset ncDataset,
                                    java.lang.String ncmlResourceLocation,
                                    CancelTask cancelTask)
                             throws java.io.IOException

Use NCML to modify a dataset, getting NcML as a resource stream

Parameters:

ncDataset - modify this dataset

ncmlResourceLocation - resource location of NcML

cancelTask - allow user to cancel task; may be null

Throws:

java.io.IOException

wrapNcML

public static void wrapNcML(NetcdfDataset ncDataset,
                            java.lang.String ncmlLocation,
                            CancelTask cancelTask)
                     throws java.io.IOException

Use NCML to modify the dataset, getting NcML from a URL

Parameters:

ncDataset - modify this dataset

ncmlLocation - URL location of NcML

cancelTask - allow user to cancel task; may be null

Throws:

java.io.IOException

readNcML

public static NetcdfDataset readNcML(java.lang.String ncmlLocation,
                                     CancelTask cancelTask)
                              throws java.io.IOException,
                                     java.net.MalformedURLException

Read an NcML file from a URL location, and construct a NetcdfDataset.

Parameters:

ncmlLocation - the URL location string of the NcML document

cancelTask - allow user to cancel the task; may be null

Throws:

java.io.IOException

java.net.MalformedURLException

readNcML

public static NetcdfDataset readNcML(java.lang.String ncmlLocation,
                                     java.lang.String referencedDatasetUri,
                                     CancelTask cancelTask)
                              throws java.io.IOException,
                                     java.net.MalformedURLException

Read an NcML file from a URL location, and construct a NetcdfDataset.

Parameters:

ncmlLocation - the URL location string of the NcML document

referencedDatasetUri - if null (usual case) get this from NcML, otherwise use this as the location.

cancelTask - allow user to cancel the task; may be null

Throws:

java.io.IOException

java.net.MalformedURLException

readNcML

public static NetcdfDataset readNcML(java.io.InputStream ins,
                                     CancelTask cancelTask)
                              throws java.io.IOException,
                                     java.net.MalformedURLException

Read NcML doc from an InputStream, and construct a NetcdfDataset.

Parameters:

ins - the InputStream containing the NcML document

cancelTask - allow user to cancel the task; may be null

Throws:

java.io.IOException

java.net.MalformedURLException

readNcML

public static NetcdfDataset readNcML(java.lang.String ncmlLocation,
                                     org.jdom.Element netcdfElem,
                                     CancelTask cancelTask)
                              throws java.io.IOException,
                                     java.net.MalformedURLException

Read NcML a JDOM Element, and construct a NetcdfDataset.

Parameters:

ncmlLocation - the location of the NcML, or may be just a unique name for caching purposes.

netcdfElem - the NcML as a JDOM element

cancelTask - allow user to cancel the task; may be null

Throws:

java.io.IOException

java.net.MalformedURLException

readAggregation

public static org.jdom.Element readAggregation(java.lang.String filename)
                                        throws java.io.IOException

Read an Aggregation element from a filename and return the root element. used for persistence

Parameters:

filename - the file location

Throws:

java.io.IOException

readNetcdf

public void readNetcdf(java.lang.String ncmlLocation,
                       NetcdfDataset newds,
                       NetcdfDataset refds,
                       org.jdom.Element netcdfElem,
                       CancelTask cancelTask)
                throws java.io.IOException

parse a netcdf JDOM Element, and add contents to the newds NetcdfDataset.

This is a bit tricky, because it handles several cases When newds == refds, we are just modifying newds. When newds != refds, we keep them seperate, and copy from refds to newds.

The user may be defining new elements or modifying old ones. The only way to tell is by seeing if the elements already exist.

Parameters:

ncmlLocation - NcML URL location, or may be just a unique name for caching purposes.

newds - add the info to this one

refds - the referenced datset; may equal newds

netcdfElem - JDOM netcdf element

cancelTask - allow user to cancel the task; may be null

Throws:

java.io.IOException

readAtt

protected void readAtt(java.lang.Object parent,
                       java.lang.Object refParent,
                       org.jdom.Element attElem)

Read an NcML attribute element.

Parameters:

parent - Group or Variable

refParent - Group or Variable in reference dataset

attElem - ncml attribute element

findAttribute

protected Attribute findAttribute(java.lang.Object parent,
                                  java.lang.String name)

addAttribute

protected void addAttribute(java.lang.Object parent,
                            Attribute att)

readDim

protected void readDim(Group g,
                       Group refg,
                       org.jdom.Element dimElem)

Read an NcML dimension element.

Parameters:

g - put dimension into this group

refg - parent Group in referenced dataset

dimElem - ncml dimension element

readGroup

protected void readGroup(NetcdfDataset newds,
                         NetcdfDataset refds,
                         Group parent,
                         Group refParent,
                         org.jdom.Element groupElem)

Read the NcML group element, and nested elements.

Parameters:

newds - new dataset

refds - referenced dataset

parent - Group

refParent - parent Group in referenced dataset

groupElem - ncml group element

readVariable

protected void readVariable(NetcdfDataset ds,
                            Group g,
                            Group refg,
                            org.jdom.Element varElem)

Read the NcML variable element, and nested elements.

Parameters:

g - parent Group

refg - referenced dataset parent Group - may be same (modify) or different (explicit)

varElem - ncml variable element

readVariableNew

protected Variable readVariableNew(NetcdfDataset ds,
                                   Group g,
                                   Structure parentS,
                                   org.jdom.Element varElem)

Read a NcML variable element, and nested elements, when it creates a new Variable.

Parameters:

g - parent Group

parentS - parent Structure

varElem - ncml variable element

Returns:

return new Variable

readVariableNested

protected void readVariableNested(NetcdfDataset ds,
                                  Structure parentS,
                                  Structure refStruct,
                                  org.jdom.Element varElem)

Read the NcML variable element, and nested elements.

Parameters:

parentS - parent Structure

varElem - ncml variable element

readValues

protected void readValues(NetcdfDataset ds,
                          Variable v,
                          org.jdom.Element varElem,
                          org.jdom.Element valuesElem)

transferDataset

public static void transferDataset(NetcdfFile src,
                                   NetcdfDataset target,
                                   ReplaceVariableCheck replaceCheck)

Copy contents of "from" to "to", as long as "to" doesnt already have an elements of that name.

protected void addElements(NetcdfFile from, NetcdfDataset ds) {

// transfer everything from existing file into this dataset // that doesnt already exist Iterator iterDim = from.getDimensions().iterator(); while (iterDim.hasNext()) { Dimension d = (Dimension) iterDim.next(); if (!ds.dimensions().contains(d)) { ds.dimensions().add( d); } }

Iterator iterVar = from.getVariables().iterator(); while (iterVar.hasNext()) { Variable v = (Variable) iterVar.next(); if (!ds.variables().contains(v)) { ds.variables().add( v); if (debugAgg) System.out.println(" copy var "+v.getName()); } }

Iterator iterAtt = from.getGlobalAttributes().iterator(); while (iterAtt.hasNext()) { ucar.nc2.Attribute a = (ucar.nc2.Attribute) iterAtt.next(); if (!ds.globalAttributes().contains(a)) ds.globalAttributes().add( a); } }

/** Copy contents of "src" to "target". Dimensions and Variables are replaced with equivalent elements, but unlimited dimensions are not allowed. Attribute doesnt have to be replaced because its immutable, so its copied over.

Parameters:

src -

target -

replaceCheck - if null, only add if a Variable of the same name doesnt already exist, otherwise

transferGroupAttributes

public static void transferGroupAttributes(Group src,
                                           Group target)

writeNcMLToFile

public static void writeNcMLToFile(java.lang.String ncmlLocation,
                                   java.lang.String fileOutName)
                            throws java.io.IOException

Read an NcML file and write an equivilent NetcdfFile to a physical file, using Netcdf-3 file format.

Parameters:

ncmlLocation - read this NcML file

fileOutName - write to this local file

Throws:

java.io.IOException

See Also:

FileWriter.writeToFile(ucar.nc2.NetcdfFile, java.lang.String)

writeNcMLToFile

public static void writeNcMLToFile(java.io.InputStream ncml,
                                   java.lang.String fileOutName)
                            throws java.io.IOException

Read an NcML and write an equivilent NetcdfFile to a physical file, using Netcdf-3 file format. The NcML may have a referenced dataset in the location URL, in which case the underlying data (modified by the NcML is written to the new file. If the NcML does not have a referenced dataset, then the new file is filled with fill values, like ncgen.

Parameters:

ncml - read NcML from this input stream

fileOutName - write to this local file

Throws:

java.io.IOException

See Also:

FileWriter.writeToFile(ucar.nc2.NetcdfFile, java.lang.String)

main

public static void main(java.lang.String[] arg)