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