thredds.catalog
Class InvCatalogFactory

java.lang.Object
  extended by thredds.catalog.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 schemas are read from a local resource, see XMLEntityResolver

Author:
John Caron

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

getDataRootLocationAliasExpanders

public List<PathAliasReplacement> getDataRootLocationAliasExpanders()

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 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(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(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 reletive 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 reletive 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 reletive references.
Returns:
an InvCatalogImpl object

readXML

public InvCatalogImpl readXML(org.jdom.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 reletive 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 void writeXML(InvCatalogImpl catalog,
                     String filename)
              throws IOException
Write the catalog as an XML document to the specified filename.

Parameters:
catalog - write this catalog
filename - write to this filename
Throws:
IOException - on an error.

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

main

public static void main(String[] args)
                 throws Exception
testing

Throws:
Exception


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