001: /* Copyright 2000 - 2001 Quadcap Software. All rights reserved.
002: *
003: * This software is distributed under the Quadcap Free Software License.
004: * This software may be used or modified for any purpose, personal or
005: * commercial. Open Source redistributions are permitted. Commercial
006: * redistribution of larger works derived from, or works which bundle
007: * this software requires a "Commercial Redistribution License"; see
008: * http://www.quadcap.com/purchase.
009: *
010: * Redistributions qualify as "Open Source" under one of the following terms:
011: *
012: * Redistributions are made at no charge beyond the reasonable cost of
013: * materials and delivery.
014: *
015: * Redistributions are accompanied by a copy of the Source Code or by an
016: * irrevocable offer to provide a copy of the Source Code for up to three
017: * years at the cost of materials and delivery. Such redistributions
018: * must allow further use, modification, and redistribution of the Source
019: * Code under substantially the same terms as this license.
020: *
021: * Redistributions of source code must retain the copyright notices as they
022: * appear in each source code file, these license terms, and the
023: * disclaimer/limitation of liability set forth as paragraph 6 below.
024: *
025: * Redistributions in binary form must reproduce this Copyright Notice,
026: * these license terms, and the disclaimer/limitation of liability set
027: * forth as paragraph 6 below, in the documentation and/or other materials
028: * provided with the distribution.
029: *
030: * The Software is provided on an "AS IS" basis. No warranty is
031: * provided that the Software is free of defects, or fit for a
032: * particular purpose.
033: *
034: * Limitation of Liability. Quadcap Software shall not be liable
035: * for any damages suffered by the Licensee or any third party resulting
036: * from use of the Software.
037: */
038:
039: // SAX entity resolver.
040: // No warranty; no copyright -- use this as you will.
041: // $Id: EntityResolver.java,v 1.3 2001/01/06 06:11:01 stan Exp $
042: package org.xml.sax;
043:
044: import java.io.IOException;
045:
046: /**
047: * Basic interface for resolving entities.
048: *
049: * <p>If a SAX application needs to implement customized handling
050: * for external entities, it must implement this interface and
051: * register an instance with the SAX parser using the parser's
052: * setEntityResolver method.</p>
053: *
054: * <p>The parser will then allow the application to intercept any
055: * external entities (including the external DTD subset and external
056: * parameter entities, if any) before including them.</p>
057: *
058: * <p>Many SAX applications will not need to implement this interface,
059: * but it will be especially useful for applications that build
060: * XML documents from databases or other specialised input sources,
061: * or for applications that use URI types other than URLs.</p>
062: *
063: * <p>The following resolver would provide the application
064: * with a special character stream for the entity with the system
065: * identifier "http://www.myhost.com/today":</p>
066: *
067: * <pre>
068: * import org.xml.sax.EntityResolver;
069: * import org.xml.sax.InputSource;
070: *
071: * public class MyResolver implements EntityResolver {
072: * public InputSource resolveEntity (String publicId, String systemId)
073: * {
074: * if (systemId.equals("http://www.myhost.com/today")) {
075: * // return a special input source
076: * MyReader reader = new MyReader();
077: * return new InputSource(reader);
078: * } else {
079: * // use the default behaviour
080: * return null;
081: * }
082: * }
083: * }
084: * </pre>
085: *
086: * <p>The application can also use this interface to redirect system
087: * identifiers to local URIs or to look up replacements in a catalog
088: * (possibly by using the public identifier).</p>
089: *
090: * <p>The HandlerBase class implements the default behaviour for
091: * this interface, which is simply always to return null (to request
092: * that the parser use the default system identifier).</p>
093: *
094: * @author David Megginson (ak117@freenet.carleton.ca)
095: * @version 1.0
096: * @see org.xml.sax.Parser#setEntityResolver
097: * @see org.xml.sax.InputSource
098: * @see org.xml.sax.HandlerBase
099: */
100: public interface EntityResolver {
101:
102: /**
103: * Allow the application to resolve external entities.
104: *
105: * <p>The Parser will call this method before opening any external
106: * entity except the top-level document entity (including the
107: * external DTD subset, external entities referenced within the
108: * DTD, and external entities referenced within the document
109: * element): the application may request that the parser resolve
110: * the entity itself, that it use an alternative URI, or that it
111: * use an entirely different input source.</p>
112: *
113: * <p>Application writers can use this method to redirect external
114: * system identifiers to secure and/or local URIs, to look up
115: * public identifiers in a catalogue, or to read an entity from a
116: * database or other input source (including, for example, a dialog
117: * box).</p>
118: *
119: * <p>If the system identifier is a URL, the SAX parser must
120: * resolve it fully before reporting it to the application.</p>
121: *
122: * @param publicId The public identifier of the external entity
123: * being referenced, or null if none was supplied.
124: * @param systemId The system identifier of the external entity
125: * being referenced.
126: * @return An InputSource object describing the new input source,
127: * or null to request that the parser open a regular
128: * URI connection to the system identifier.
129: * @exception org.xml.sax.SAXException Any SAX exception, possibly
130: * wrapping another exception.
131: * @exception java.io.IOException A Java-specific IO exception,
132: * possibly the result of creating a new InputStream
133: * or Reader for the InputSource.
134: * @see org.xml.sax.InputSource
135: */
136: public abstract InputSource resolveEntity(String publicId,
137: String systemId) throws SAXException, IOException;
138:
139: }
|