286N/A * reserved comment block 286N/A * DO NOT REMOVE OR ALTER! 286N/A * Copyright 2001-2004 The Apache Software Foundation or its licensors, 286N/A * Licensed under the Apache License, Version 2.0 (the "License"); 286N/A * you may not use this file except in compliance with the License. 286N/A * You may obtain a copy of the License at 286N/A * Unless required by applicable law or agreed to in writing, software 286N/A * distributed under the License is distributed on an "AS IS" BASIS, 286N/A * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 286N/A * See the License for the specific language governing permissions and 286N/A * limitations under the License. 286N/A * A DOM-based CatalogReader. 286N/A * <p>This class is used to read XML Catalogs using the DOM. This reader 286N/A * has an advantage over the SAX-based reader that it can analyze the 286N/A * DOM tree rather than simply a series of SAX events. It has the disadvantage 286N/A * that it requires all of the code necessary to build and walk a DOM 286N/A * <p>Since the choice of CatalogReaders (in the InputStream case) can only 286N/A * be made on the basis of MIME type, the following problem occurs: only 286N/A * one CatalogReader can exist for all XML mime types. In order to get 286N/A * around this problem, the DOMCatalogReader relies on a set of external 286N/A * CatalogParsers to actually build the catalog.</p> 286N/A * <p>The selection of CatalogParsers is made on the basis of the QName 286N/A * of the root element of the document.</p> 286N/A * @see SAXCatalogReader 286N/A * @see TextCatalogReader 286N/A * @see DOMCatalogParser 286N/A * <a href="mailto:Norman.Walsh@Sun.COM">Norman.Walsh@Sun.COM</a> 286N/A * Mapping table from QNames to CatalogParser classes. 286N/A * <p>Each key in this hash table has the form "elementname" 286N/A * or "{namespaceuri}elementname". The former is used if the 286N/A * namespace URI is null.</p> 286N/A * Add a new parser to the reader. 286N/A * <p>This method associates the specified parserClass with the 286N/A * @param namespaceURI The namespace URI. <em>Not</em> the prefix. 286N/A * @param rootElement The name of the root element. 286N/A * @param parserClass The name of the parserClass to instantiate 286N/A * for this kind of catalog. 286N/A * Get the name of the parser class for a given catalog type. 286N/A * <p>This method returns the parserClass associated with the 286N/A * @param namespaceURI The namespace URI. <em>Not</em> the prefix. 286N/A * @param rootElement The name of the root element. 286N/A * @return The parser class. 286N/A * Null constructor; something for subclasses to call. 286N/A * Read a catalog from an input stream. 286N/A * <p>This class reads a catalog from an input stream:</p> 286N/A * <li>Based on the QName of the root element, it determines which 286N/A * parser to instantiate for this catalog.</li> 286N/A * <li>It constructs a DOM Document from the catalog and</li> 286N/A * <li>For each child of the root node, it calls the parser's 286N/A * parseCatalogEntry method. This method is expected to make 286N/A * appropriate calls back into the catalog to add entries for the 286N/A * entries in the catalog. It is free to do this in whatever manner 286N/A * is appropriate (perhaps using just the node passed in, perhaps 286N/A * wandering arbitrarily throughout the tree).</li> 286N/A * @param catalog The catalog for which this reader is called. 286N/A * @param is The input stream that is to be read. 286N/A * @throws IOException if the URL cannot be read. 286N/A * @throws UnknownCatalogFormatException if the catalog format is 286N/A * @throws UnparseableCatalogException if the catalog cannot be parsed. 286N/A * (For example, if it is supposed to be XML and isn't well-formed or 286N/A * if the parser class cannot be instantiated.) 286N/A * Read the catalog behind the specified URL. 286N/A * @see #readCatalog(Catalog, InputStream) 286N/A * @param catalog The catalog for which we are reading. 286N/A * @param fileUrl The URL of the document that should be read. 286N/A * @throws MalformedURLException if the specified URL cannot be 286N/A * turned into a URL object. 286N/A * @throws IOException if the URL cannot be read. 286N/A * @throws UnknownCatalogFormatException if the catalog format is 286N/A * @throws UnparseableCatalogException if the catalog cannot be parsed. 286N/A * (For example, if it is supposed to be XML and isn't well-formed.)