ucar.nc2.ncml
Class NcMLReader

java.lang.Object
  extended by 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)


Copyright © 1999-2011 UCAR/Unidata. All Rights Reserved.