EntityResolver


1   // SAX entity resolver.
2   // http://www.saxproject.org
3   // No warranty; no copyright -- use this as you will.
4   // $Id: EntityResolver.java,v 1.1.24.1 2004/05/01 08:34:39 jsuttor Exp $
5   
6   package org.xml.sax;
7   
8   import java.io.IOException  ;
9   
10  
11  /**
12   * Basic interface for resolving entities.
13   *
14   * <blockquote>
15   * <em>This module, both source code and documentation, is in the
16   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
17   * See <a HREF='http://www.saxproject.org'>http://www.saxproject.org</a>
18   * for further information.
19   * </blockquote>
20   *
21   * <p>If a SAX application needs to implement customized handling
22   * for external entities, it must implement this interface and
23   * register an instance with the SAX driver using the
24   * {@link org.xml.sax.XMLReader#setEntityResolver setEntityResolver}
25   * method.</p>
26   *
27   * <p>The XML reader will then allow the application to intercept any
28   * external entities (including the external DTD subset and external
29   * parameter entities, if any) before including them.</p>
30   *
31   * <p>Many SAX applications will not need to implement this interface,
32   * but it will be especially useful for applications that build
33   * XML documents from databases or other specialised input sources,
34   * or for applications that use URI types other than URLs.</p>
35   *
36   * <p>The following resolver would provide the application
37   * with a special character stream for the entity with the system
38   * identifier "http://www.myhost.com/today":</p>
39   *
40   * <pre>
41   * import org.xml.sax.EntityResolver;
42   * import org.xml.sax.InputSource;
43   *
44   * public class MyResolver implements EntityResolver {
45   *   public InputSource resolveEntity (String publicId, String systemId)
46   *   {
47   *     if (systemId.equals("http://www.myhost.com/today")) {
48   *              // return a special input source
49   *       MyReader reader = new MyReader();
50   *       return new InputSource(reader);
51   *     } else {
52   *              // use the default behaviour
53   *       return null;
54   *     }
55   *   }
56   * }
57   * </pre>
58   *
59   * <p>The application can also use this interface to redirect system
60   * identifiers to local URIs or to look up replacements in a catalog
61   * (possibly by using the public identifier).</p>
62   *
63   * @since SAX 1.0
64   * @author David Megginson
65   * @version 2.0.1 (sax2r2)
66   * @see org.xml.sax.XMLReader#setEntityResolver
67   * @see org.xml.sax.InputSource
68   */
69  public interface EntityResolver {
70      
71      
72      /**
73       * Allow the application to resolve external entities.
74       *
75       * <p>The parser will call this method before opening any external
76       * entity except the top-level document entity.  Such entities include
77       * the external DTD subset and external parameter entities referenced
78       * within the DTD (in either case, only if the parser reads external
79       * parameter entities), and external general entities referenced
80       * within the document element (if the parser reads external general
81       * entities).  The application may request that the parser locate
82       * the entity itself, that it use an alternative URI, or that it
83       * use data provided by the application (as a character or byte
84       * input stream).</p>
85       *
86       * <p>Application writers can use this method to redirect external
87       * system identifiers to secure and/or local URIs, to look up
88       * public identifiers in a catalogue, or to read an entity from a
89       * database or other input source (including, for example, a dialog
90       * box).  Neither XML nor SAX specifies a preferred policy for using
91       * public or system IDs to resolve resources.  However, SAX specifies
92       * how to interpret any InputSource returned by this method, and that
93       * if none is returned, then the system ID will be dereferenced as
94       * a URL.  </p>
95       *
96       * <p>If the system identifier is a URL, the SAX parser must
97       * resolve it fully before reporting it to the application.</p>
98       *
99       * @param publicId The public identifier of the external entity
100      *        being referenced, or null if none was supplied.
101      * @param systemId The system identifier of the external entity
102      *        being referenced.
103      * @return An InputSource object describing the new input source,
104      *         or null to request that the parser open a regular
105      *         URI connection to the system identifier.
106      * @exception org.xml.sax.SAXException Any SAX exception, possibly
107      *            wrapping another exception.
108      * @exception java.io.IOException A Java-specific IO exception,
109      *            possibly the result of creating a new InputStream
110      *            or Reader for the InputSource.
111      * @see org.xml.sax.InputSource
112      */
113     public abstract InputSource   resolveEntity (String   publicId,
114                            String   systemId)
115     throws SAXException  , IOException  ;
116     
117 }
118 
119 // end of EntityResolver.java
120
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags