ucar.nc2.ncml

Class NcMLReader

java.lang.Object

ucar.nc2.ncml.NcMLReader

public class NcMLReader
extends Object

Read NcML and create NetcdfDataset.

See Also:

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

Constructor Summary

Constructors

Constructor and Description
NcMLReader()

Method Summary

Modifier and Type	Method and Description
static void	main(String[] arg)
static NetcdfDataset	mergeNcML(NetcdfFile ref, org.jdom2.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.jdom2.Element parentElem) Use NCML to directly modify the dataset
static Array	readAttributeValues(org.jdom2.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.jdom2.Element netcdfElem, CancelTask cancelTask) Read NcML from a JDOM Document, and construct a NetcdfDataset.
static NetcdfDataset	readNcML(String ncmlLocation, org.jdom2.Element netcdfElem, String referencedDatasetUri, CancelTask cancelTask) Read NcML from a JDOM Document, and pass in the name of the dataset.
static NetcdfDataset	readNcML(String ncmlLocation, String referencedDatasetUri, CancelTask cancelTask) Read an NcML file from a URL location, and construct a 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 equivalent NetcdfFile to a physical file, using Netcdf-3 file format.
static void	writeNcMLToFile(InputStream ncml, String fileOutName, NetcdfFileWriter.Version version, ucar.nc2.write.Nc4Chunking chunker) Read an NcML 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

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.jdom2.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.jdom2.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.jdom2.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

readNcML

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

Read NcML from a JDOM Document, and pass in the name of the dataset. Used to augment datasetScan with NcML

Parameters:

ncmlLocation - the URL location string of the NcML document, used as a unique name for caching purposes.

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

referencedDatasetUri - the URL location string of the underlying dataset, which overrides anything in netcdfElem. prepend with "file:" to eliminate reletive resolving against ncmlLocation

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

Returns:

the resulting NetcdfDataset

Throws:

IOException - on read error, or bad referencedDatasetUri URI

readAttributeValues

public static Array readAttributeValues(org.jdom2.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(InputStream ncml,
                                   String fileOutName)
                            throws IOException

Read an NcML and write an equivalent 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:

FileWriter2

writeNcMLToFile

public static void writeNcMLToFile(InputStream ncml,
                                   String fileOutName,
                                   NetcdfFileWriter.Version version,
                                   ucar.nc2.write.Nc4Chunking chunker)
                            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

version - kind of netcdf file

chunker - optional chunking (netcdf4 only)

Throws:

IOException

main

public static void main(String[] arg)