Package ucar.nc2.internal.ncml

Class NcmlReader

  • public class NcmlReader
extends Object
    Read NcML and create NetcdfDataset.Builder, using builders and immutable objects.

    This is an internal class, users should usually call NetcdfDatasets.openDataset(String)

    • Constructor Detail

      • NcmlReader

        public NcmlReader()

    • Method Detail

      • setDebugFlags

        public static void setDebugFlags​(DebugFlags debugFlag)

      • parseEnhanceMode

        public static Set<NetcdfDataset.Enhance> parseEnhanceMode​(String enhanceMode)
        Retrieve the set of Enhancements that is associated with the given NcML string.

        String Enhancements
        All ConvertEnums, ConvertUnsigned, ApplyScaleOffset, ConvertMissing, CoordSystems
        None <empty>
        ConvertEnums ConvertEnums
        ConvertUnsigned ConvertUnsigned
        ApplyScaleOffset ApplyScaleOffset
        ConvertMissing ConvertMissing
        CoordSystems CoordSystems
        IncompleteCoordSystems CoordSystems
        true Alias for "All"
        ScaleMissingDefer Alias for "None"
        AllDefer ConvertEnums, CoordSystems
        ScaleMissing ConvertUnsigned, ApplyScaleOffset, ConvertMissing
        Parameters:
        enhanceMode - a string from the above table.
        Returns:
        the set corresponding to enhanceMode, or null if there is no correspondence.

      • wrapNcml

        public static void wrapNcml​(NetcdfDataset.Builder ncDataset,
                            String ncmlLocation,
                            CancelTask cancelTask)
                     throws IOException
        Use NCML to modify the dataset, getting NcML from a URL. Used by CoordSysFactory.
        Parameters:
        ncDataset - modify this dataset
        ncmlLocation - URL location of NcML
        cancelTask - allow user to cancel task; may be null
        Throws:
        IOException - on read error

      • wrapNcmlResource

        public static void wrapNcmlResource​(NetcdfDataset.Builder 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

      • mergeNcml

        public static NetcdfDataset.Builder mergeNcml​(NetcdfFile ref,
                                              @Nullable
                                              org.jdom2.Element ncmlElem)
                                       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
        ncmlElem - 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.Builder readNcml​(Reader r,
                                             String ncmlLocation,
                                             CancelTask cancelTask)
                                      throws IOException
        Read NcML doc from a Reader, and construct a NetcdfDataset.Builder. This is an internal method, users should use NetcdfDatasets.openNcmlDataset(Reader, String, CancelTask)
        Parameters:
        r - the Reader containing the NcML document
        ncmlLocation - the URL location string of the NcML document, used to resolve relative 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.Builder
        Throws:
        IOException - on read error, or bad referencedDatasetUri URI

      • readNcml

        public static NetcdfDataset.Builder 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

      • getLocationFromNcml

        public static String getLocationFromNcml​(String ncml)
        Find the location attribute in a NcML string
        Parameters:
        ncml - the NcML as a string
        Returns:
        the resulting location attribute, or null if not found or if the NcML cannot be read

      • 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