InvCatalogFactory (NetCDF-Java 4.2 Public and Private API)

java.lang.Object
- thredds.catalog.InvCatalogFactory

public class InvCatalogFactory
extends java.lang.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 "http://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

Author:: John Caron

Field Summary

Fields
Modifier and Type	Field and Description
`static boolean`	`debugDBurl`
`static boolean`	`debugOpen`
`static boolean`	`debugURL`
`static boolean`	`debugVersion`
`static boolean`	`debugXML`
`static boolean`	`debugXMLopen`
`static boolean`	`showCatalogXML`
`static boolean`	`showParsedXML`
`static boolean`	`showStackTrace`

Constructor Summary

Constructors
Constructor and Description

InvCatalogFactory(java.lang.String name, boolean validate)
Constructor.

Constructors
Constructor and Description
`InvCatalogFactory(java.lang.String name, boolean validate)` Constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`appendErr(java.lang.String err)` append an error message.
`void`	`appendFatalErr(java.lang.String err)` append a fatal error message
`void`	`appendWarning(java.lang.String err)` append a warning message
`InvCatalogConvertIF`	`getCatalogConverter(java.lang.String namespace)` Find the InvCatalogConvertIF registered for this namespace.
`java.util.List<PathAliasReplacement>`	`getDataRootLocationAliasExpanders()`
`static InvCatalogConvertIF`	`getDefaultConverter()`
`static InvCatalogFactory`	`getDefaultFactory(boolean validate)` Get new Factory for reading and writing catalogs.
`MetadataConverterIF`	`getMetadataConverter(java.lang.String key)` Find the MetadataConverterIF registered for this key
`java.lang.String`	`getName()` An InvCatalogFactory may have a name, in case you need to manage several of them.
`static void`	`main(java.lang.String[] args)` testing
`InvCatalogImpl`	`readXML(org.jdom.Document jdomDoc, java.net.URI uri)` Create an InvCatalog from a JDOM document.
`InvCatalogImpl`	`readXML(java.io.InputStream docIs, java.net.URI uri)` Create an InvCatalog from an InputStream.
`InvCatalogImpl`	`readXML(java.lang.String uriString)` Create an InvCatalog from an XML document at a named URL.
`InvCatalogImpl`	`readXML(java.io.StringReader catAsStringReader, java.net.URI baseUri)` Create an InvCatalog by reading catalog XML from a StringReader.
`InvCatalogImpl`	`readXML(java.lang.String catAsString, java.net.URI baseUri)` Create an InvCatalog by reading catalog XML from a String.
`InvCatalogImpl`	`readXML(java.net.URI uri)` Read an InvCatalog from an a URI.
`void`	`readXMLasynch(java.lang.String uriString, CatalogSetCallback callback)` This allows the possibility of reading a catalog in another thread.
`void`	`registerCatalogConverter(java.lang.String namespace, InvCatalogConvertIF converter)` Register converters for creating InvCatalogs from specific catalog XML namespaces.
`void`	`registerMetadataConverter(java.lang.String key, MetadataConverterIF converter)` Register metadata converters for reading metadata objects of a certain type or namespace.
`void`	`setDataRootLocationAliasExpanders(java.util.List<PathAliasReplacement> dataRootLocAliasExpanders)`
`java.lang.String`	`writeXML(InvCatalogImpl catalog)` Write the catalog as an XML document to a String.
`void`	`writeXML(InvCatalogImpl catalog, java.io.OutputStream os)` Write the InvCatalogImpl to the OutputStream as a InvCatalog 1.0 document.
`void`	`writeXML(InvCatalogImpl catalog, java.io.OutputStream os, boolean raw)` Write the InvCatalogImpl to the OutputStream as a InvCatalog 1.0 document.
`void`	`writeXML(InvCatalogImpl catalog, java.lang.String filename)` Write the catalog as an XML document to the specified filename.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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(java.lang.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 seperate InvCatalogFactory for each thread.
    
    Parameters:
    validate - : do XML validation or not.
    
    Returns:
    default factory
  - getDefaultConverter
```
public static InvCatalogConvertIF getDefaultConverter()
```
  - getName
```
public java.lang.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(java.util.List<PathAliasReplacement> dataRootLocAliasExpanders)
```
  - getDataRootLocationAliasExpanders
```
public java.util.List<PathAliasReplacement> getDataRootLocationAliasExpanders()
```
  - registerCatalogConverter
```
public void registerCatalogConverter(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String uriString)
```
    Create an InvCatalog from an XML document at a named URL. 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.
    
    Returns:
    an InvCatalogImpl object
  - readXML
```
public InvCatalogImpl readXML(java.net.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 reletive references.
    
    Returns:
    an InvCatalogImpl object
  - readXML
```
public InvCatalogImpl readXML(java.lang.String catAsString,
                     java.net.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 reletive references.
    
    Returns:
    an InvCatalogImpl object
  - readXML
```
public InvCatalogImpl readXML(java.io.StringReader catAsStringReader,
                     java.net.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 reletive references.
    
    Returns:
    an InvCatalogImpl object
  - readXML
```
public InvCatalogImpl readXML(java.io.InputStream docIs,
                     java.net.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 reletive references.
    
    Returns:
    an InvCatalogImpl object
  - readXML
```
public InvCatalogImpl readXML(org.jdom.Document jdomDoc,
                     java.net.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 reletive references.
    
    Returns:
    an InvCatalogImpl object
  - writeXML
```
public void writeXML(InvCatalogImpl catalog,
            java.io.OutputStream os,
            boolean raw)
              throws java.io.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:
    
    java.io.IOException - when the OutputStream can't be written
    
    java.lang.IllegalStateException - when the factory doesn't know how to write a 1.0 document.
  - writeXML
```
public void writeXML(InvCatalogImpl catalog,
            java.io.OutputStream os)
              throws java.io.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:
    
    java.io.IOException - when the OutputStream can't be written
    
    java.lang.IllegalStateException - when the factory doesn't know how to write a 1.0 document.
  - writeXML
```
public void writeXML(InvCatalogImpl catalog,
            java.lang.String filename)
              throws java.io.IOException
```
    Write the catalog as an XML document to the specified filename.
    
    Parameters:
    catalog - write this catalog
    filename - write to this filename
    
    Throws:
    
    java.io.IOException - on an error.
  - writeXML
```
public java.lang.String writeXML(InvCatalogImpl catalog)
                          throws java.io.IOException
```
    Write the catalog as an XML document to a String.
    
    Parameters:
    catalog - write this catalog
    
    Returns:
    string containing XML representation
    
    Throws:
    
    java.io.IOException - on write error
  - appendErr
```
public void appendErr(java.lang.String err)
```
    append an error message. Used by the InvCatalogConvertIF
    
    Parameters:
    err - append this error message
  - appendFatalErr
```
public void appendFatalErr(java.lang.String err)
```
    append a fatal error message
    
    Parameters:
    err - append this error message
  - appendWarning
```
public void appendWarning(java.lang.String err)
```
    append a warning message
    
    Parameters:
    err - append this error message
  - getMetadataConverter
```
public MetadataConverterIF getMetadataConverter(java.lang.String key)
```
    Find the MetadataConverterIF registered for this key
    
    Parameters:
    key - search on this key
    
    Returns:
    MetadataConverterIF else null
  - main
```
public static void main(java.lang.String[] args)
                 throws java.lang.Exception
```
    testing
    
    Throws:
    
    java.lang.Exception

Class InvCatalogFactory

Example of normal use:

To write out a catalog to XML:

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

debugURL

debugOpen

debugVersion

showParsedXML

showStackTrace

debugXML

debugDBurl

debugXMLopen

showCatalogXML

Constructor Detail

InvCatalogFactory

Method Detail

getDefaultFactory

getDefaultConverter

getName

setDataRootLocationAliasExpanders

getDataRootLocationAliasExpanders

registerCatalogConverter

getCatalogConverter

registerMetadataConverter

readXMLasynch

readXML

readXML

readXML

readXML

readXML

readXML

writeXML

writeXML

writeXML

writeXML

appendErr

appendFatalErr

appendWarning

getMetadataConverter

main