thredds.catalog

Class InvCatalogFactory

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 "https://www.unidata.ucar.edu/thredds"
• the current 1.0/1.1 spec, namespace "https://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0"

The schemas are read from a local resource, see XMLEntityResolver

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.

Method Summary

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

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

Throws:

java.io.IOException

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