cvs commit: xml-xalan/java/src/trax URIResolver.java

[sb...@locus.apache.org]

sboag       00/08/04 13:39:32

  Modified:    java/src/trax URIResolver.java
  Log:
  Another take on URIResolver
  
  Revision  Changes    Path
  1.2       +34 -29    xml-xalan/java/src/trax/URIResolver.java
  
  Index: URIResolver.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/trax/URIResolver.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- URIResolver.java	2000/06/20 16:30:17	1.1
  +++ URIResolver.java	2000/08/04 20:39:31	1.2
  @@ -4,52 +4,57 @@
   // Software Foundation.  All rights reserved.
   package trax;
   
  -import java.io.IOException;
  +//import java.io.IOException;
   import org.xml.sax.InputSource;
  +import org.xml.sax.XMLReader;
   import org.w3c.dom.Node;
   
  +
  +
   /**
  - * An interface that can be called by the processor to for turning the
  + * <p><i>This version of URIResolver reflects the proposal made by Michael Kay to revise
  + * the interface as defined in TRAX 0.6.</i></p>
  + *
  + * <p>An interface that can be called by the processor to for turning the
    * URIs used in document() and xsl:import etc into an InputSource or a 
  - * Node if the processor supports the "http://xml.org/trax/features/dom/input" feature.
  + * Node if the processor supports the "http://xml.org/trax/features/dom/input" feature.</p>
  + *
  + * Node that the URIResolver is stateful (it remembers the most recent URI) so separate
  + * instances must be used in each thread.
  + * 
    * 
  - * <h3>Open issues:</h3>
  - * <dl>
 *    <dt><h4>resolveURItoDOMTree</h4></dt>
  - *    <dd>Surely it's the URIResolver that
  - *    knows it wants to supply a DOM node to satisfy the URI, how is the processor
  - *    supposed to know this? Perhaps it would be better to have
  - *    URIResolver.getURItype() which returns "inputSource" or "DOM Node", and the
  - *    processor then calls resolveURI() or resolveURItoNode() as appropriate?
  - *    (It's still not a very pretty design, it doesn't extend nicely to return
  - *    another source of SAX events, e.g. an SQL query).</dd>
  - * </dl>
 * 
    * @version Alpha
    * @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
    */
  + 
   public interface URIResolver
   {
     /**
      * This will be called by the processor when it encounters 
  -   * an xsl:include, xsl:import, or document() function.
  +   * an xsl:include, xsl:import, or document() function, if it needs 
  +   * a DOM tree. The URIResolver must be prepared to return either a
  +   * DOM tree, or a SAX InputSource, or both. This method must not be called
  +   * unless setURI() has been called first.
      * 
  -   * @param base The base URI that should be used.
  -   * @param uri Value from an xsl:import or xsl:include's href attribute, 
  -   * or a URI specified in the document() function.
  -   * @returns a InputSource that can be used to process the resource.
  +   * @param inputSource The value returned from the EntityResolver.
  +   * @returns a DOM node that represents the resolution of the URI 
  +   * to a tree, if the
  +   * URI resolver is capable of returning a DOM Node; or null otherwise.
      */
  -  public InputSource resolveURI (String base, String uri)
  -    throws TransformException, IOException;
  +  public Node getDOMNode (InputSource inputSource) 
  +    throws TransformException;
   
     /**
  -   * This will be called by the processor when it encounters 
  -   * an xsl:include, xsl:import, or document() function, if it needs 
  -   * a DOM tree.
  +   * This method returns the SAX2 parser to use with the InputSource 
  +   * obtained from this URI.
  +   * It may return null if any SAX2-conformant XML parser can be used,
  +   * or if getInputSource() will also return null. The parser must 
  +   * be free for use (i.e.
  +   * not currently in use for another parse().
      * 
  -   * @param base The base URI that should be used.
  -   * @param uri Value from an xsl:import or xsl:include's href attribute, 
  -   * or a URI specified in the document() function.
  -   * @returns a DOM node that represents the resolution of the URI to a tree.
  +   * @param inputSource The value returned from the EntityResolver.
  +   * @returns a SAX2 parser to use with the InputSource.
      */
  -  public Node resolveURIToDOMTree (String base, String uri)
  -    throws TransformException, IOException;
  +  public XMLReader getXMLReader(InputSource inputSource) 
  +    throws TransformException;
   }