001// SAX entity resolver.
002// No warranty; no copyright -- use this as you will.
003// $Id: EntityResolver.java,v 1.1 2001/03/05 21:40:05 jstrachan Exp $
004
005package org.xml.sax;
006
007import java.io.IOException;
008
009
010/**
011 * Basic interface for resolving entities.
012 *
013 * <blockquote>
014 * <em>This module, both source code and documentation, is in the
015 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
016 * </blockquote>
017 *
018 * <p>If a SAX application needs to implement customized handling
019 * for external entities, it must implement this interface and
020 * register an instance with the SAX driver using the
021 * {@link org.xml.sax.XMLReader#setEntityResolver setEntityResolver}
022 * method.</p>
023 *
024 * <p>The XML reader will then allow the application to intercept any
025 * external entities (including the external DTD subset and external
026 * parameter entities, if any) before including them.</p>
027 *
028 * <p>Many SAX applications will not need to implement this interface,
029 * but it will be especially useful for applications that build
030 * XML documents from databases or other specialised input sources,
031 * or for applications that use URI types other than URLs.</p>
032 *
033 * <p>The following resolver would provide the application
034 * with a special character stream for the entity with the system
035 * identifier "http://www.myhost.com/today":</p>
036 *
037 * <pre>
038 * import org.xml.sax.EntityResolver;
039 * import org.xml.sax.InputSource;
040 *
041 * public class MyResolver implements EntityResolver {
042 *   public InputSource resolveEntity (String publicId, String systemId)
043 *   {
044 *     if (systemId.equals("http://www.myhost.com/today")) {
045 *              // return a special input source
046 *       MyReader reader = new MyReader();
047 *       return new InputSource(reader);
048 *     } else {
049 *              // use the default behaviour
050 *       return null;
051 *     }
052 *   }
053 * }
054 * </pre>
055 *
056 * <p>The application can also use this interface to redirect system
057 * identifiers to local URIs or to look up replacements in a catalog
058 * (possibly by using the public identifier).</p>
059 *
060 * @since SAX 1.0
061 * @author David Megginson, 
062 *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
063 * @version 2.0
064 * @see org.xml.sax.Parser#setEntityResolver
065 * @see org.xml.sax.InputSource
066 */
067public interface EntityResolver {
068    
069    
070    /**
071     * Allow the application to resolve external entities.
072     *
073     * <p>The Parser will call this method before opening any external
074     * entity except the top-level document entity (including the
075     * external DTD subset, external entities referenced within the
076     * DTD, and external entities referenced within the document
077     * element): the application may request that the parser resolve
078     * the entity itself, that it use an alternative URI, or that it
079     * use an entirely different input source.</p>
080     *
081     * <p>Application writers can use this method to redirect external
082     * system identifiers to secure and/or local URIs, to look up
083     * public identifiers in a catalogue, or to read an entity from a
084     * database or other input source (including, for example, a dialog
085     * box).</p>
086     *
087     * <p>If the system identifier is a URL, the SAX parser must
088     * resolve it fully before reporting it to the application.</p>
089     *
090     * @param publicId The public identifier of the external entity
091     *        being referenced, or null if none was supplied.
092     * @param systemId The system identifier of the external entity
093     *        being referenced.
094     * @return An InputSource object describing the new input source,
095     *         or null to request that the parser open a regular
096     *         URI connection to the system identifier.
097     * @exception org.xml.sax.SAXException Any SAX exception, possibly
098     *            wrapping another exception.
099     * @exception java.io.IOException A Java-specific IO exception,
100     *            possibly the result of creating a new InputStream
101     *            or Reader for the InputSource.
102     * @see org.xml.sax.InputSource
103     */
104    public abstract InputSource resolveEntity (String publicId,
105                                               String systemId)
106        throws SAXException, IOException;
107    
108}
109
110// end of EntityResolver.java