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