/*

 * reserved comment block

 * DO NOT REMOVE OR ALTER!

 */

// Catalog.java - Represents OASIS Open Catalog files.

/*

 * Copyright 2001-2004 The Apache Software Foundation or its licensors,

 * as applicable.

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

package com.sun.org.apache.xml.internal.resolver;

import com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl;

import java.io.IOException;

import java.io.FileNotFoundException;

import java.io.InputStream;

import java.io.UnsupportedEncodingException;

import java.io.DataInputStream;

import java.util.Enumeration;

import java.util.Hashtable;

import java.util.Vector;

import java.net.URL;

import java.net.MalformedURLException;

import javax.xml.parsers.SAXParserFactory;

import com.sun.org.apache.xml.internal.resolver.CatalogManager;

import com.sun.org.apache.xml.internal.resolver.helpers.PublicId;

import com.sun.org.apache.xml.internal.resolver.readers.CatalogReader;

import com.sun.org.apache.xml.internal.resolver.readers.SAXCatalogReader;

import com.sun.org.apache.xml.internal.resolver.readers.TR9401CatalogReader;

import com.sun.org.apache.xml.internal.resolver.readers.OASISXMLCatalogReader;

import com.sun.org.apache.xml.internal.resolver.helpers.FileURL;

/**

 * Represents OASIS Open Catalog files.

 *

 * <p>This class implements the semantics of OASIS Open Catalog files

 * (defined by

 * <a href="http://www.oasis-open.org/html/a401.htm">OASIS Technical

 * Resolution 9401:1997 (Amendment 2 to TR 9401)</a>).</p>

 *

 * <p>The primary purpose of the Catalog is to associate resources in the

 * document with local system identifiers. Some entities

 * (document types, XML entities, and notations) have names and all of them

 * can have either public or system identifiers or both. (In XML, only a

 * notation can have a public identifier without a system identifier, but

 * the methods implemented in this class obey the Catalog semantics

 * from the SGML

 * days when system identifiers were optional.)</p>

 *

 * <p>The system identifiers returned by the resolution methods in this

 * class are valid, i.e. usable by, and in fact constructed by, the

 * <tt>java.net.URL</tt> class. Unfortunately, this class seems to behave in

 * somewhat non-standard ways and the system identifiers returned may

 * not be directly usable in a browser or filesystem context.

 *

 * <p>This class recognizes all of the Catalog entries defined in

 * TR9401:1997:</p>

 *

 * <ul>

 * <li><b>BASE</b>

 * changes the base URI for resolving relative system identifiers. The

 * initial base URI is the URI of the location of the catalog (which is,

 * in turn, relative to the location of the current working directory

 * at startup, as returned by the <tt>user.dir</tt> system property).</li>

 * <li><b>CATALOG</b>

 * processes other catalog files. An included catalog occurs logically

 * at the end of the including catalog.</li>

 * <li><b>DELEGATE_PUBLIC</b>

 * specifies alternate catalogs for some public identifiers. The delegated

 * catalogs are not loaded until they are needed, but they are cached

 * once loaded.</li>

 * <li><b>DELEGATE_SYSTEM</b>

 * specifies alternate catalogs for some system identifiers. The delegated

 * catalogs are not loaded until they are needed, but they are cached

 * once loaded.</li>

 * <li><b>DELEGATE_URI</b>

 * specifies alternate catalogs for some URIs. The delegated

 * catalogs are not loaded until they are needed, but they are cached

 * once loaded.</li>

 * <li><b>REWRITE_SYSTEM</b>

 * specifies alternate prefix for a system identifier.</li>

 * <li><b>REWRITE_URI</b>

 * specifies alternate prefix for a URI.</li>

 * <li><b>SYSTEM_SUFFIX</b>

 * maps any system identifier that ends with a particular suffix to another

 * system identifier.</li>

 * <li><b>URI_SUFFIX</b>

 * maps any URI that ends with a particular suffix to another URI.</li>

 * <li><b>DOCTYPE</b>

 * associates the names of root elements with URIs. (In other words, an XML

 * processor might infer the doctype of an XML document that does not include

 * a doctype declaration by looking for the DOCTYPE entry in the

 * catalog which matches the name of the root element of the document.)</li>

 * <li><b>DOCUMENT</b>

 * provides a default document.</li>

 * <li><b>DTDDECL</b>

 * recognized and silently ignored. Not relevant for XML.</li>

 * <li><b>ENTITY</b>

 * associates entity names with URIs.</li>

 * <li><b>LINKTYPE</b>

 * recognized and silently ignored. Not relevant for XML.</li>

 * <li><b>NOTATION</b>

 * associates notation names with URIs.</li>

 * <li><b>OVERRIDE</b>

 * changes the override behavior. Initial behavior is set by the

 * system property <tt>xml.catalog.override</tt>. The default initial

 * behavior is 'YES', that is, entries in the catalog override

 * system identifiers specified in the document.</li>

 * <li><b>PUBLIC</b>

 * maps a public identifier to a system identifier.</li>

 * <li><b>SGMLDECL</b>

 * recognized and silently ignored. Not relevant for XML.</li>

 * <li><b>SYSTEM</b>

 * maps a system identifier to another system identifier.</li>

 * <li><b>URI</b>

 * maps a URI to another URI.</li>

 * </ul>

 *

 * <p>Note that BASE entries are treated as described by RFC2396. In

 * particular, this has the counter-intuitive property that after a BASE

 * entry identifing "http://example.com/a/b/c" as the base URI,

 * the relative URI "foo" is resolved to the absolute URI

 * "http://example.com/a/b/foo". You must provide the trailing slash if

 * you do not want the final component of the path to be discarded as a

 * filename would in a URI for a resource: "http://example.com/a/b/c/".

 * </p>

 *

 * <p>Note that subordinate catalogs (all catalogs except the first,

 * including CATALOG and DELEGATE* catalogs) are only loaded if and when

 * they are required.</p>

 *

 * <p>This class relies on classes which implement the CatalogReader

 * interface to actually load catalog files. This allows the catalog

 * semantics to be implemented for TR9401 text-based catalogs, XML

 * catalogs, or any number of other storage formats.</p>

 *

 * <p>Additional catalogs may also be loaded with the

 * {@link #parseCatalog} method.</p>

 * </dd>

 * </dl>

 *

 * <p><b>Change Log:</b></p>

 * <dl>

 * <dt>2.0</dt>

 * <dd><p>Rewrite to use CatalogReaders.</p></dd>

 * <dt>1.1</dt>

 * <dd><p>Allow quoted components in <tt>xml.catalog.files</tt>

 * so that URLs containing colons can be used on Unix.

 * The string passed to <tt>xml.catalog.files</tt> can now have the form:</p>

 * <pre>

 * unquoted-path-with-no-sep-chars:"double-quoted path with or without sep chars":'single-quoted path with or without sep chars'

 * </pre>

 * <p>(Where ":" is the separater character in this example.)</p>

 * <p>If an unquoted path contains an embedded double or single quote

 * character, no special processig is performed on that character. No

 * path can contain separater characters, double, and single quotes

 * simultaneously.</p>

 * <p>Fix bug in calculation of BASE entries: if

 * a catalog contains multiple BASE entries, each is relative to the preceding

 * base, not the default base URI of the catalog.</p>

 * </dd>

 * <dt>1.0.1</dt>

 * <dd><p>Fixed a bug in the calculation of the list of subordinate catalogs.

 * This bug caused an infinite loop where parsing would alternately process

 * two catalogs indefinitely.</p>

 * </dd>

 * </dl>

 *

 * @see CatalogReader

 * @see CatalogEntry

 *

 * @author Norman Walsh

 * <a href="mailto:Norman.Walsh@Sun.COM">Norman.Walsh@Sun.COM</a>

 *

 * @version 1.0

 *

 * <p>Derived from public domain code originally published by Arbortext,

 * Inc.</p>

 */

public class Catalog {

  /** The BASE Catalog Entry type. */

  public static final int BASE     = CatalogEntry.addEntryType("BASE", 1);

  /** The CATALOG Catalog Entry type. */

  public static final int CATALOG  = CatalogEntry.addEntryType("CATALOG", 1);

  /** The DOCUMENT Catalog Entry type. */

  public static final int DOCUMENT = CatalogEntry.addEntryType("DOCUMENT", 1);

  /** The OVERRIDE Catalog Entry type. */

  public static final int OVERRIDE = CatalogEntry.addEntryType("OVERRIDE", 1);

  /** The SGMLDECL Catalog Entry type. */

  public static final int SGMLDECL = CatalogEntry.addEntryType("SGMLDECL", 1);

  /** The DELEGATE_PUBLIC Catalog Entry type. */

  public static final int DELEGATE_PUBLIC = CatalogEntry.addEntryType("DELEGATE_PUBLIC", 2);

  /** The DELEGATE_SYSTEM Catalog Entry type. */

  public static final int DELEGATE_SYSTEM = CatalogEntry.addEntryType("DELEGATE_SYSTEM", 2);

  /** The DELEGATE_URI Catalog Entry type. */

  public static final int DELEGATE_URI = CatalogEntry.addEntryType("DELEGATE_URI", 2);

  /** The DOCTYPE Catalog Entry type. */

  public static final int DOCTYPE  = CatalogEntry.addEntryType("DOCTYPE", 2);

  /** The DTDDECL Catalog Entry type. */

  public static final int DTDDECL  = CatalogEntry.addEntryType("DTDDECL", 2);

  /** The ENTITY Catalog Entry type. */

  public static final int ENTITY   = CatalogEntry.addEntryType("ENTITY", 2);

  /** The LINKTYPE Catalog Entry type. */

  public static final int LINKTYPE = CatalogEntry.addEntryType("LINKTYPE", 2);

  /** The NOTATION Catalog Entry type. */

  public static final int NOTATION = CatalogEntry.addEntryType("NOTATION", 2);

  /** The PUBLIC Catalog Entry type. */

  public static final int PUBLIC   = CatalogEntry.addEntryType("PUBLIC", 2);

  /** The SYSTEM Catalog Entry type. */

  public static final int SYSTEM   = CatalogEntry.addEntryType("SYSTEM", 2);

  /** The URI Catalog Entry type. */

  public static final int URI      = CatalogEntry.addEntryType("URI", 2);

  /** The REWRITE_SYSTEM Catalog Entry type. */

  public static final int REWRITE_SYSTEM = CatalogEntry.addEntryType("REWRITE_SYSTEM", 2);

  /** The REWRITE_URI Catalog Entry type. */

  public static final int REWRITE_URI = CatalogEntry.addEntryType("REWRITE_URI", 2);

  /** The SYSTEM_SUFFIX Catalog Entry type. */

  public static final int SYSTEM_SUFFIX = CatalogEntry.addEntryType("SYSTEM_SUFFIX", 2);

  /** The URI_SUFFIX Catalog Entry type. */

  public static final int URI_SUFFIX = CatalogEntry.addEntryType("URI_SUFFIX", 2);

  /**

   * The base URI for relative system identifiers in the catalog.

   * This may be changed by BASE entries in the catalog.

   */

  protected URL base;

  /** The base URI of the Catalog file currently being parsed. */

  protected URL catalogCwd;

  /** The catalog entries currently known to the system. */

  protected Vector catalogEntries = new Vector();

  /** The default initial override setting. */

  protected boolean default_override = true;

  /** The catalog manager in use for this instance. */

  protected CatalogManager catalogManager = CatalogManager.getStaticManager();

  /**

   * A vector of catalog files to be loaded.

   *

   * <p>This list is initially established by

   * <code>loadSystemCatalogs</code> when

   * it parses the system catalog list, but CATALOG entries may

   * contribute to it during the course of parsing.</p>

   *

   * @see #loadSystemCatalogs

   * @see #localCatalogFiles

   */

  protected Vector catalogFiles = new Vector();

  /**

   * A vector of catalog files constructed during processing of

   * CATALOG entries in the current catalog.

   *

   * <p>This two-level system is actually necessary to correctly implement

   * the semantics of the CATALOG entry. If one catalog file includes

   * another with a CATALOG entry, the included catalog logically

   * occurs <i>at the end</i> of the including catalog, and after any

   * preceding CATALOG entries. In other words, the CATALOG entry

   * cannot insert anything into the middle of a catalog file.</p>

   *

   * <p>When processing reaches the end of each catalog files, any

   * elements on this vector are added to the front of the

   * <code>catalogFiles</code> vector.</p>

   *

   * @see #catalogFiles

   */

  protected Vector localCatalogFiles = new Vector();

  /**

   * A vector of Catalogs.

   *

   * <p>The semantics of Catalog resolution are such that each

   * catalog is effectively a list of Catalogs (in other words,

   * a recursive list of Catalog instances).</p>

   *

   * <p>Catalogs that are processed as the result of CATALOG or

   * DELEGATE* entries are subordinate to the catalog that contained

   * them, but they may in turn have subordinate catalogs.</p>

   *

   * <p>Catalogs are only loaded when they are needed, so this vector

   * initially contains a list of Catalog filenames (URLs). If, during

   * processing, one of these catalogs has to be loaded, the resulting

   * Catalog object is placed in the vector, effectively caching it

   * for the next query.</p>

   */

  protected Vector catalogs = new Vector();

  /**

   * A vector of DELEGATE* Catalog entries constructed during

   * processing of the Catalog.

   *

   * <p>This two-level system has two purposes; first, it allows

   * us to sort the DELEGATE* entries by the length of the partial

   * public identifier so that a linear search encounters them in

   * the correct order and second, it puts them all at the end of

   * the Catalog.</p>

   *

   * <p>When processing reaches the end of each catalog file, any

   * elements on this vector are added to the end of the

   * <code>catalogEntries</code> vector. This assures that matching

   * PUBLIC keywords are encountered before DELEGATE* entries.</p>

   */

  protected Vector localDelegate = new Vector();

  /**

   * A hash of CatalogReaders.

   *

   * <p>This hash maps MIME types to elements in the readerArr

   * vector. This allows the Catalog to quickly locate the reader

   * for a particular MIME type.</p>

   */

  protected Hashtable readerMap = new Hashtable();

  /**

   * A vector of CatalogReaders.

   *

   * <p>This vector contains all of the readers in the order that they

   * were added. In the event that a catalog is read from a file, where

   * the MIME type is unknown, each reader is attempted in turn until

   * one succeeds.</p>

   */

  protected Vector readerArr = new Vector();

  /**

   * Constructs an empty Catalog.

   *

   * <p>The constructor interrogates the relevant system properties

   * using the default (static) CatalogManager

   * and initializes the catalog data structures.</p>

   */

  public Catalog() {

    // nop;

  }

  /**

   * Constructs an empty Catalog with a specific CatalogManager.

   *

   * <p>The constructor interrogates the relevant system properties

   * using the specified Catalog Manager

   * and initializes the catalog data structures.</p>

   */

  public Catalog(CatalogManager manager) {

    catalogManager = manager;

  }

  /**

   * Return the CatalogManager used by this catalog.

   *

   */

  public CatalogManager getCatalogManager() {

    return catalogManager;

  }

  /**

   * Establish the CatalogManager used by this catalog.

   *

   */

  public void setCatalogManager(CatalogManager manager) {

    catalogManager = manager;

  }

  /**

   * Setup readers.

   */

  public void setupReaders() {

    SAXParserFactory spf = catalogManager.useServicesMechanism() ?

                    SAXParserFactory.newInstance() : new SAXParserFactoryImpl();

    spf.setNamespaceAware(true);

    spf.setValidating(false);

    SAXCatalogReader saxReader = new SAXCatalogReader(spf);

    saxReader.setCatalogParser(null, "XMLCatalog",

                               "com.sun.org.apache.xml.internal.resolver.readers.XCatalogReader");

    saxReader.setCatalogParser(OASISXMLCatalogReader.namespaceName,

                               "catalog",

                               "com.sun.org.apache.xml.internal.resolver.readers.OASISXMLCatalogReader");

    addReader("application/xml", saxReader);

    TR9401CatalogReader textReader = new TR9401CatalogReader();

    addReader("text/plain", textReader);

  }

  /**

   * Add a new CatalogReader to the Catalog.

   *

   * <p>This method allows you to add a new CatalogReader to the

   * catalog. The reader will be associated with the specified mimeType.

   * You can only have one reader per mimeType.</p>

   *

   * <p>In the absence of a mimeType (e.g., when reading a catalog

   * directly from a file on the local system), the readers are attempted

   * in the order that you add them to the Catalog.</p>

   *

   * <p>Note that subordinate catalogs (created by CATALOG or

   * DELEGATE* entries) get a copy of the set of readers present in

   * the primary catalog when they are created. Readers added subsequently

   * will not be available. For this reason, it is best to add all

   * of the readers before the first call to parse a catalog.</p>

   *

   * @param mimeType The MIME type associated with this reader.

   * @param reader The CatalogReader to use.

   */

  public void addReader(String mimeType, CatalogReader reader) {

    if (readerMap.containsKey(mimeType)) {

      Integer pos = (Integer) readerMap.get(mimeType);

      readerArr.set(pos.intValue(), reader);

    } else {

      readerArr.add(reader);

      Integer pos = new Integer(readerArr.size()-1);

      readerMap.put(mimeType, pos);

    }

  }

  /**

   * Copies the reader list from the current Catalog to a new Catalog.

   *

   * <p>This method is used internally when constructing a new catalog.

   * It copies the current reader associations over to the new catalog.

   * </p>

   *

   * @param newCatalog The new Catalog.

   */

  protected void copyReaders(Catalog newCatalog) {

    // Have to copy the readers in the right order...convert hash to arr

    Vector mapArr = new Vector(readerMap.size());

    // Pad the mapArr out to the right length

    for (int count = 0; count < readerMap.size(); count++) {

      mapArr.add(null);

    }

    Enumeration en = readerMap.keys();

    while (en.hasMoreElements()) {

      String mimeType = (String) en.nextElement();

      Integer pos = (Integer) readerMap.get(mimeType);

      mapArr.set(pos.intValue(), mimeType);

    }

    for (int count = 0; count < mapArr.size(); count++) {

      String mimeType = (String) mapArr.get(count);

      Integer pos = (Integer) readerMap.get(mimeType);

      newCatalog.addReader(mimeType,

                           (CatalogReader)

                           readerArr.get(pos.intValue()));

    }

  }

  /**

   * Create a new Catalog object.

   *

   * <p>This method constructs a new instance of the running Catalog

   * class (which might be a subtype of com.sun.org.apache.xml.internal.resolver.Catalog).

   * All new catalogs are managed by the same CatalogManager.

   * </p>

   *

   * <p>N.B. All Catalog subtypes should call newCatalog() to construct

   * a new Catalog. Do not simply use "new Subclass()" since that will

   * confuse future subclasses.</p>

   */

  protected Catalog newCatalog() {

    String catalogClass = this.getClass().getName();

    try {

      Catalog c = (Catalog) (Class.forName(catalogClass).newInstance());

      c.setCatalogManager(catalogManager);

      copyReaders(c);

      return c;

    } catch (ClassNotFoundException cnfe) {

      catalogManager.debug.message(1, "Class Not Found Exception: " + catalogClass);

    } catch (IllegalAccessException iae) {

      catalogManager.debug.message(1, "Illegal Access Exception: " + catalogClass);

    } catch (InstantiationException ie) {

      catalogManager.debug.message(1, "Instantiation Exception: " + catalogClass);

    } catch (ClassCastException cce) {

      catalogManager.debug.message(1, "Class Cast Exception: " + catalogClass);

    } catch (Exception e) {

      catalogManager.debug.message(1, "Other Exception: " + catalogClass);

    }

    Catalog c = new Catalog();

    c.setCatalogManager(catalogManager);

    copyReaders(c);

    return c;

  }

  /**

   * Returns the current base URI.