ucar.nc2.ncml
Class NcMLReader

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

public class NcMLReader
extends Object

Read NcML and create NetcdfDataset.

Author:

caron

See Also:

http://www.unidata.ucar.edu/software/netcdf/ncml/

Field Summary

static org.jdom.Namespace

ncNS

Constructor Summary

NcMLReader()

Method Summary

static void	main(String[] arg)
static NetcdfDataset	mergeNcML(NetcdfFile ref, org.jdom.Element parentElem) Use NCML to modify the referenced dataset, create a new dataset with the merged info Used to wrap each dataset of an aggregation before its aggregated
static NetcdfDataset	mergeNcMLdirect(NetcdfDataset targetDS, org.jdom.Element parentElem) Use NCML to directly modify the dataset
static Array	readAttributeValues(org.jdom.Element s) Parse the values element
static NetcdfDataset	readNcML(InputStream ins, CancelTask cancelTask) Read NcML doc from an InputStream, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(Reader r, CancelTask cancelTask) Read NcML doc from a Reader, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(Reader r, String ncmlLocation, CancelTask cancelTask) Read NcML doc from a Reader, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(String ncmlLocation, CancelTask cancelTask) Read an NcML file from a URL location, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(String ncmlLocation, org.jdom.Element netcdfElem, CancelTask cancelTask) Read NcML from a JDOM Document, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(String ncmlLocation, String referencedDatasetUri, CancelTask cancelTask) Read an NcML file from a URL location, and construct a NetcdfDataset.
void	readNetcdf(String ncmlLocation, NetcdfDataset targetDS, NetcdfFile refds, org.jdom.Element netcdfElem, CancelTask cancelTask) parse a netcdf JDOM Element, and add contents to the targetDS NetcdfDataset.
static void	setDebugFlags(DebugFlags debugFlag)
static void	wrapNcML(NetcdfDataset ncDataset, String ncmlLocation, CancelTask cancelTask) Use NCML to modify the dataset, getting NcML from a URL
static void	wrapNcMLresource(NetcdfDataset ncDataset, String ncmlResourceLocation, CancelTask cancelTask) Use NCML to modify a dataset, getting the NcML document as a resource stream.
static void	writeNcMLToFile(InputStream ncml, String fileOutName) Read an NcML and write an equivilent NetcdfFile to a physical file, using Netcdf-3 file format.
static void	writeNcMLToFile(String ncmlLocation, 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,
                                    String ncmlResourceLocation,
                                    CancelTask cancelTask)
                             throws IOException

Use NCML to modify a dataset, getting the NcML document as a resource stream. Uses ClassLoader.getResourceAsStream(ncmlResourceLocation), so the NcML can be inside of a jar file, for example.

Parameters:

ncDataset - modify this dataset

ncmlResourceLocation - resource location of NcML

cancelTask - allow user to cancel task; may be null

Throws:

IOException - on read error

wrapNcML

public static void wrapNcML(NetcdfDataset ncDataset,
                            String ncmlLocation,
                            CancelTask cancelTask)
                     throws 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:

IOException - on read error

mergeNcML

public static NetcdfDataset mergeNcML(NetcdfFile ref,
                                      org.jdom.Element parentElem)
                               throws IOException

Use NCML to modify the referenced dataset, create a new dataset with the merged info Used to wrap each dataset of an aggregation before its aggregated

Parameters:

ref - referenced dataset

parentElem - parent element - usually the aggregation element of the ncml

Returns:

new dataset with the merged info

Throws:

IOException - on read error

mergeNcMLdirect

public static NetcdfDataset mergeNcMLdirect(NetcdfDataset targetDS,
                                            org.jdom.Element parentElem)
                                     throws IOException

Use NCML to directly modify the dataset

Parameters:

targetDS - referenced dataset

parentElem - parent element - usually the aggregation element of the ncml

Returns:

new dataset with the merged info

Throws:

IOException - on read error

readNcML

public static NetcdfDataset readNcML(String ncmlLocation,
                                     CancelTask cancelTask)
                              throws IOException

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNcML

public static NetcdfDataset readNcML(String ncmlLocation,
                                     String referencedDatasetUri,
                                     CancelTask cancelTask)
                              throws IOException

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 URI as the location of the referenced dataset.

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNcML

public static NetcdfDataset readNcML(InputStream ins,
                                     CancelTask cancelTask)
                              throws IOException

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNcML

public static NetcdfDataset readNcML(Reader r,
                                     CancelTask cancelTask)
                              throws IOException

Read NcML doc from a Reader, and construct a NetcdfDataset.

Parameters:

r - the Reader containing the NcML document

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNcML

public static NetcdfDataset readNcML(Reader r,
                                     String ncmlLocation,
                                     CancelTask cancelTask)
                              throws IOException

Read NcML doc from a Reader, and construct a NetcdfDataset. eg: NcMLReader.readNcML(new StringReader(ncml), location, null);

Parameters:

r - the Reader containing the NcML document

ncmlLocation - the URL location string of the NcML document, used to resolve reletive path of the referenced dataset, or may be just a unique name for caching purposes.

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNcML

public static NetcdfDataset readNcML(String ncmlLocation,
                                     org.jdom.Element netcdfElem,
                                     CancelTask cancelTask)
                              throws IOException

Read NcML from a JDOM Document, and construct a NetcdfDataset.

Parameters:

ncmlLocation - the URL location string of the NcML document, used to resolve reletive path of the referenced dataset, or may be just a unique name for caching purposes.

netcdfElem - the JDOM Document's root (netcdf) element

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readNetcdf

public void readNetcdf(String ncmlLocation,
                       NetcdfDataset targetDS,
                       NetcdfFile refds,
                       org.jdom.Element netcdfElem,
                       CancelTask cancelTask)
                throws IOException

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

This is a bit tricky, because it handles several cases When targetDS == refds, we are just modifying targetDS. When targetDS != 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.

targetDS - add the info to this one, never null

refds - the referenced dataset; may equal newds, never null

netcdfElem - JDOM netcdf element

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

Throws:

IOException - on read error

readAttributeValues

public static Array readAttributeValues(org.jdom.Element s)
                                 throws IllegalArgumentException

Parse the values element

Parameters:

s - JDOM element to parse

Returns:

Array with parsed values

Throws:

IllegalArgumentException - if string values not parsable to specified data type

writeNcMLToFile

public static void writeNcMLToFile(String ncmlLocation,
                                   String fileOutName)
                            throws 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:

IOException - on write error

See Also:

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

writeNcMLToFile

public static void writeNcMLToFile(InputStream ncml,
                                   String fileOutName)
                            throws 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:

IOException - on error

See Also:

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

main

public static void main(String[] arg)