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