Package thredds.catalog

Class InvCatalogFactory

  • public class InvCatalogFactory
extends Object
    Reads an XML document and constructs thredds.catalog object.

    Example of normal use:

     InvCatalogFactory factory = new InvCatalogFactory("default", validate);
 InvCatalogImpl catalog = (InvCatalogImpl) factory.readXML(catalogURI);
 StringBuilder buff = new StringBuilder();
 if (!catalog.check(buff)) {
   javax.swing.JOptionPane.showMessageDialog(this, "Invalid catalog <" + catalogURI + ">\n" + buff.toString());
 }

    To write out a catalog to XML:

     // write out catalog to String
 try {
   System.out.println("\Catalog in XML=\n" + factory.writeXML( catalog));
 } catch (IOException e) {
   e.printStackTrace();
 }
 
    
 // write out catalog to a file
 if (!factory.writeXML( catalog, filename))
 System.out.println("Catalog failed to write to file=" + filename);
 
    
 // write out catalog to a stream, catch exceptions
 try {
 BufferedOutputStream os = new BufferedOutputStream (new FileOutputStream(filename));
 factory.writeXML( catalog, os);
 os.close();
 } catch (IOException e) {
 e.printStackTrace();
 }

    Implementation details: Uses JDOM to read XML documents. Uses a pluggable InvCatalogConvertIF to transform the JDOM tree to the thredds.catalog objects. The converters are registered based on the namespace used. We are supporting:

    • the older "0.6" spec, namespace "https://www.unidata.ucar.edu/thredds"
    • the current 1.0/1.1 spec, namespace "http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0"
    The schemas are read from a local resource, see XMLEntityResolver

    • Field Detail

      • debugURL

        public static boolean debugURL

      • debugOpen

        public static boolean debugOpen

      • debugVersion

        public static boolean debugVersion

      • showParsedXML

        public static boolean showParsedXML

      • showStackTrace

        public static boolean showStackTrace

      • debugXML

        public static boolean debugXML

      • debugDBurl

        public static boolean debugDBurl

      • debugXMLopen

        public static boolean debugXMLopen

      • showCatalogXML

        public static boolean showCatalogXML

    • Constructor Detail

      • InvCatalogFactory

        public InvCatalogFactory​(String name,
                         boolean validate)
        Constructor. Can use this to read as many catalogs as you want, but only use in single thread.
        Parameters:
        name - : optional name to keep track of factories
        validate - : do XML validation or not.

    • Method Detail

      • getDefaultFactory

        public static InvCatalogFactory getDefaultFactory​(boolean validate)
        Get new Factory for reading and writing catalogs. For multithreading, get separate InvCatalogFactory for each thread.
        Parameters:
        validate - : do XML validation or not.
        Returns:
        default factory

      • getName

        public String getName()
        An InvCatalogFactory may have a name, in case you need to manage several of them.
        Returns:
        name of factory

      • setDataRootLocationAliasExpanders

        public void setDataRootLocationAliasExpanders​(List<PathAliasReplacement> dataRootLocAliasExpanders)

      • registerCatalogConverter

        public void registerCatalogConverter​(String namespace,
                                     InvCatalogConvertIF converter)
        Register converters for creating InvCatalogs from specific catalog XML namespaces. This allows the user to add to or override the way catalogs are made.
        Parameters:
        namespace - : namespace of catalog; acts as the version
        converter - : use this factory for this version

      • getCatalogConverter

        public InvCatalogConvertIF getCatalogConverter​(String namespace)
        Find the InvCatalogConvertIF registered for this namespace.
        Parameters:
        namespace - : find InvCatalogConvertIF for this namespace
        Returns:
        the InvCatalogConvertIF registered for this namespace, or null

      • registerMetadataConverter

        public void registerMetadataConverter​(String key,
                                      MetadataConverterIF converter)
        Register metadata converters for reading metadata objects of a certain type or namespace. This allows allows extensible metadata processing.
        Parameters:
        key - : namespace or metadata type string
        converter - : use this MetadataConverterIF for the given key
        See Also:
        InvMetadata

      • readXMLasynch

        public void readXMLasynch​(String uriString,
                          CatalogSetCallback callback)
        This allows the possibility of reading a catalog in another thread. The default implementation does not do that, but a subclass may override and implement. If the catalog is read successfully, it is passed on to the callback.
        Parameters:
        uriString - : read this catalog.
        callback - : call this if successfully read.
        See Also:
        CatalogSetCallback

      • readXML

        public InvCatalogImpl readXML​(String uriString)
        Create an InvCatalog from an XML document at a named URI. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        uriString - : the URI name that the XML doc is at. May start with a "file:"
        Returns:
        an InvCatalogImpl object

      • readXML

        public InvCatalogImpl readXML​(URI uri)
        Read an InvCatalog from an a URI. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        uri - : the URI of the document, used for resolving relative references.
        Returns:
        an InvCatalogImpl object

      • readXML

        public InvCatalogImpl readXML​(String catAsString,
                              URI baseUri)
        Create an InvCatalog by reading catalog XML from a String. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        catAsString - : the String from which to read the catalog.
        baseUri - : the base URI of the document, used for resolving relative references.
        Returns:
        an InvCatalogImpl object

      • readXML

        public InvCatalogImpl readXML​(StringReader catAsStringReader,
                              URI baseUri)
        Create an InvCatalog by reading catalog XML from a StringReader. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        catAsStringReader - : the StreamReader from which to read the catalog.
        baseUri - : the base URI of the document, used for resolving relative references.
        Returns:
        an InvCatalogImpl object

      • readXML

        public InvCatalogImpl readXML​(InputStream docIs,
                              URI uri)
        Create an InvCatalog from an InputStream. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        docIs - : the InputStream to read from
        uri - : the URI of the document, used for resolving relative references.
        Returns:
        an InvCatalogImpl object

      • readXML

        public InvCatalogImpl readXML​(org.jdom2.Document jdomDoc,
                              URI uri)
        Create an InvCatalog from a JDOM document. Failures and exceptions are handled by causing validate() to fail. Therefore, be sure to call validate() before trying to use the InvCatalog object.
        Parameters:
        jdomDoc - a parsed JDOM Document
        uri - : the URI of the document, used for resolving relative references.
        Returns:
        an InvCatalogImpl object

      • writeXML

        public void writeXML​(InvCatalogImpl catalog,
                     OutputStream os,
                     boolean raw)
              throws IOException
        Write the InvCatalogImpl to the OutputStream as a InvCatalog 1.0 document.
        Parameters:
        catalog - - the catalog to be written
        os - - the OutputStream to write to
        raw - if true, write raw, vs converted
        Throws:
        IOException - when the OutputStream can't be written
        IllegalStateException - when the factory doesn't know how to write a 1.0 document.

      • writeXML

        public void writeXML​(InvCatalogImpl catalog,
                     OutputStream os)
              throws IOException
        Write the InvCatalogImpl to the OutputStream as a InvCatalog 1.0 document.
        Parameters:
        catalog - - the catalog to be written
        os - - the OutputStream to write to
        Throws:
        IOException - when the OutputStream can't be written
        IllegalStateException - when the factory doesn't know how to write a 1.0 document.

      • writeXML

        public String writeXML​(InvCatalogImpl catalog)
                throws IOException
        Write the catalog as an XML document to a String.
        Parameters:
        catalog - write this catalog
        Returns:
        string containing XML representation
        Throws:
        IOException - on write error

      • appendErr

        public void appendErr​(String err)
        append an error message. Used by the InvCatalogConvertIF
        Parameters:
        err - append this error message

      • appendFatalErr

        public void appendFatalErr​(String err)
        append a fatal error message
        Parameters:
        err - append this error message

      • appendWarning

        public void appendWarning​(String err)
        append a warning message
        Parameters:
        err - append this error message

      • getMetadataConverter

        public MetadataConverterIF getMetadataConverter​(String key)
        Find the MetadataConverterIF registered for this key
        Parameters:
        key - search on this key
        Returns:
        MetadataConverterIF else null