| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
|
| <!--NewPage-->
|
| <HTML>
|
| <HEAD>
|
| <!-- Generated by javadoc on Thu Nov 22 17:13:00 EST 2007 -->
|
| <TITLE>
|
| Xalan-Java 2.7.1: Interface EntityResolver2
|
| </TITLE>
|
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style">
|
| </HEAD>
|
| <BODY BGCOLOR="white">
|
|
|
| <!-- ========== START OF NAVBAR ========== -->
|
| <A NAME="navbar_top"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
|
| <TR>
|
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
|
| <TR ALIGN="center" VALIGN="top">
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
|
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/EntityResolver2.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
| </TR>
|
| </TABLE>
|
| </TD>
|
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
| </EM>
|
| </TD>
|
| </TR>
|
|
|
| <TR>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../../org/xml/sax/ext/DeclHandler.html"><B>PREV CLASS</B></A>
|
| <A HREF="../../../../org/xml/sax/ext/LexicalHandler.html"><B>NEXT CLASS</B></A></FONT></TD>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../../index.html" TARGET="_top"><B>FRAMES</B></A>
|
| <A HREF="EntityResolver2.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
|
| </TR>
|
| <TR>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| SUMMARY: INNER | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD>
|
| </TR>
|
| </TABLE>
|
| <!-- =========== END OF NAVBAR =========== -->
|
|
|
| <HR>
|
| <!-- ======== START OF CLASS DATA ======== -->
|
| <H2>
|
| <FONT SIZE="-1">
|
| org.xml.sax.ext</FONT>
|
| <BR>
|
| Interface EntityResolver2</H2>
|
| <DL>
|
| <DT><B>All Known Implementing Classes:</B> <DD><A HREF="../../../../org/xml/sax/ext/DefaultHandler2.html">DefaultHandler2</A></DD>
|
| </DL>
|
| <HR>
|
| <DL>
|
| <DT>public interface <B>EntityResolver2</B><DT>extends <A HREF="../../../../org/xml/sax/EntityResolver.html">EntityResolver</A></DL>
|
|
|
| <P>
|
| Extended interface for mapping external entity references to input |
| sources, or providing a missing external subset. The |
| <A HREF="../../../../org/xml/sax/XMLReader.html#setEntityResolver(org.xml.sax.EntityResolver)">XMLReader.setEntityResolver()</A> method |
| is used to provide implementations of this interface to parsers. |
| When a parser uses the methods in this interface, the |
| <A HREF="../../../../org/xml/sax/ext/EntityResolver2.html#resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)">EntityResolver2.resolveEntity()</A> |
| method (in this interface) is used <em>instead of</em> the older (SAX 1.0) |
| <A HREF="../../../../org/xml/sax/EntityResolver.html#resolveEntity(java.lang.String, java.lang.String)">EntityResolver.resolveEntity()</A> method. |
| |
| <blockquote> |
| <em>This module, both source code and documentation, is in the |
| Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> |
| </blockquote> |
| |
| <p>If a SAX application requires the customized handling which this |
| interface defines for external entities, it must ensure that it uses |
| an XMLReader with the |
| <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag |
| set to <em>true</em> (which is its default value when the feature is |
| recognized). If that flag is unrecognized, or its value is false, |
| or the resolver does not implement this interface, then only the |
| <A HREF="../../../../org/xml/sax/EntityResolver.html"><CODE>EntityResolver</CODE></A> method will be used. |
| </p> |
| |
| <p>That supports three categories of application that modify entity |
| resolution. <em>Old Style</em> applications won't know about this interface; |
| they will provide an EntityResolver. |
| <em>Transitional Mode</em> provide an EntityResolver2 and automatically |
| get the benefit of its methods in any systems (parsers or other tools) |
| supporting it, due to polymorphism. |
| Both <em>Old Style</em> and <em>Transitional Mode</em> applications will |
| work with any SAX2 parser. |
| <em>New style</em> applications will fail to run except on SAX2 parsers |
| that support this particular feature. |
| They will insist that feature flag have a value of "true", and the |
| EntityResolver2 implementation they provide might throw an exception |
| if the original SAX 1.0 style entity resolution method is invoked. |
| </p>
|
| <P>
|
| <DL>
|
| <DT><B>Since: </B><DD>SAX 2.0 (extensions 1.1 alpha)</DD>
|
| <DT><B>See Also: </B><DD><A HREF="../../../../org/xml/sax/XMLReader.html#setEntityResolver(org.xml.sax.EntityResolver)"><CODE>XMLReader.setEntityResolver(org.xml.sax.EntityResolver)</CODE></A></DL>
|
| <HR>
|
|
|
| <P>
|
| <!-- ======== INNER CLASS SUMMARY ======== -->
|
|
|
|
|
| <!-- =========== FIELD SUMMARY =========== -->
|
|
|
|
|
| <!-- ======== CONSTRUCTOR SUMMARY ======== -->
|
|
|
|
|
| <!-- ========== METHOD SUMMARY =========== -->
|
|
|
| <A NAME="method_summary"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=2><FONT SIZE="+2">
|
| <B>Method Summary</B></FONT></TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> <A HREF="../../../../org/xml/sax/InputSource.html">InputSource</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../../org/xml/sax/ext/EntityResolver2.html#getExternalSubset(java.lang.String, java.lang.String)">getExternalSubset</A></B>(java.lang.String name, |
| java.lang.String baseURI)</CODE>
|
|
|
| <BR>
|
| Allows applications to provide an external subset for documents |
| that don't explicitly define one.</TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
|
| <CODE> <A HREF="../../../../org/xml/sax/InputSource.html">InputSource</A></CODE></FONT></TD>
|
| <TD><CODE><B><A HREF="../../../../org/xml/sax/ext/EntityResolver2.html#resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)">resolveEntity</A></B>(java.lang.String name, |
| java.lang.String publicId, |
| java.lang.String baseURI, |
| java.lang.String systemId)</CODE>
|
|
|
| <BR>
|
| Allows applications to map references to external entities into input |
| sources, or tell the parser it should use conventional URI resolution.</TD>
|
| </TR>
|
| </TABLE>
|
| <A NAME="methods_inherited_from_class_org.xml.sax.EntityResolver"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
|
| <TD><B>Methods inherited from interface org.xml.sax.<A HREF="../../../../org/xml/sax/EntityResolver.html">EntityResolver</A></B></TD>
|
| </TR>
|
| <TR BGCOLOR="white" CLASS="TableRowColor">
|
| <TD><CODE><A HREF="../../../../org/xml/sax/EntityResolver.html#resolveEntity(java.lang.String, java.lang.String)">resolveEntity</A></CODE></TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <P>
|
|
|
| <!-- ============ FIELD DETAIL =========== -->
|
|
|
|
|
| <!-- ========= CONSTRUCTOR DETAIL ======== -->
|
|
|
|
|
| <!-- ============ METHOD DETAIL ========== -->
|
|
|
| <A NAME="method_detail"><!-- --></A> |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
|
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
|
| <TD COLSPAN=1><FONT SIZE="+2">
|
| <B>Method Detail</B></FONT></TD>
|
| </TR>
|
| </TABLE>
|
|
|
| <A NAME="getExternalSubset(java.lang.String, java.lang.String)"><!-- --></A><H3>
|
| getExternalSubset</H3>
|
| <PRE>
|
| public <A HREF="../../../../org/xml/sax/InputSource.html">InputSource</A> <B>getExternalSubset</B>(java.lang.String name, |
| java.lang.String baseURI) |
| throws <A HREF="../../../../org/xml/sax/SAXException.html">SAXException</A>, |
| java.io.IOException</PRE>
|
| <DL>
|
| <DD>Allows applications to provide an external subset for documents |
| that don't explicitly define one. Documents with DOCTYPE declarations |
| that omit an external subset can thus augment the declarations |
| available for validation, entity processing, and attribute processing |
| (normalization, defaulting, and reporting types including ID). |
| This augmentation is reported |
| through the <A HREF="../../../../org/xml/sax/ext/LexicalHandler.html#startDTD(java.lang.String, java.lang.String, java.lang.String)">startDTD()</A> method as if |
| the document text had originally included the external subset; |
| this callback is made before any internal subset data or errors |
| are reported.</p> |
| |
| <p>This method can also be used with documents that have no DOCTYPE |
| declaration. When the root element is encountered, |
| but no DOCTYPE declaration has been seen, this method is |
| invoked. If it returns a value for the external subset, that root |
| element is declared to be the root element, giving the effect of |
| splicing a DOCTYPE declaration at the end the prolog of a document |
| that could not otherwise be valid. The sequence of parser callbacks |
| in that case logically resembles this:</p> |
| |
| <pre> |
| ... comments and PIs from the prolog (as usual) |
| startDTD ("rootName", source.getPublicId (), source.getSystemId ()); |
| startEntity ("[dtd]"); |
| ... declarations, comments, and PIs from the external subset |
| endEntity ("[dtd]"); |
| endDTD (); |
| ... then the rest of the document (as usual) |
| startElement (..., "rootName", ...); |
| </pre> |
| |
| <p>Note that the InputSource gets no further resolution. |
| Implementations of this method may wish to invoke |
| <A HREF="../../../../org/xml/sax/ext/EntityResolver2.html#resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)">resolveEntity()</A> to gain benefits such as use |
| of local caches of DTD entities. Also, this method will never be |
| used by a (non-validating) processor that is not including external |
| parameter entities. </p> |
| |
| <p>Uses for this method include facilitating data validation when |
| interoperating with XML processors that would always require |
| undesirable network accesses for external entities, or which for |
| other reasons adopt a "no DTDs" policy. |
| Non-validation motives include forcing documents to include DTDs so |
| that attributes are handled consistently. |
| For example, an XPath processor needs to know which attibutes have |
| type "ID" before it can process a widely used type of reference.</p> |
| |
| <p><strong>Warning:</strong> Returning an external subset modifies |
| the input document. By providing definitions for general entities, |
| it can make a malformed document appear to be well formed. |
| </p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>name</CODE> - Identifies the document root element. This name comes |
| from a DOCTYPE declaration (where available) or from the actual |
| root element.<DD><CODE>baseURI</CODE> - The document's base URI, serving as an additional |
| hint for selecting the external subset. This is always an absolute |
| URI, unless it is null because the XMLReader was given an InputSource |
| without one.<DT><B>Returns:</B><DD>An InputSource object describing the new external subset |
| to be used by the parser, or null to indicate that no external |
| subset is provided.<DT><B>Throws:</B><DD><A HREF="../../../../org/xml/sax/SAXException.html">SAXException</A> - Any SAX exception, possibly wrapping |
| another exception.<DD>java.io.IOException - Probably indicating a failure to create |
| a new InputStream or Reader, or an illegal URL.</DL>
|
| </DD>
|
| </DL>
|
| <HR>
|
|
|
| <A NAME="resolveEntity(java.lang.String, java.lang.String, java.lang.String, java.lang.String)"><!-- --></A><H3>
|
| resolveEntity</H3>
|
| <PRE>
|
| public <A HREF="../../../../org/xml/sax/InputSource.html">InputSource</A> <B>resolveEntity</B>(java.lang.String name, |
| java.lang.String publicId, |
| java.lang.String baseURI, |
| java.lang.String systemId) |
| throws <A HREF="../../../../org/xml/sax/SAXException.html">SAXException</A>, |
| java.io.IOException</PRE>
|
| <DL>
|
| <DD>Allows applications to map references to external entities into input |
| sources, or tell the parser it should use conventional URI resolution. |
| This method is only called for external entities which have been |
| properly declared. |
| This method provides more flexibility than the <A HREF="../../../../org/xml/sax/EntityResolver.html"><CODE>EntityResolver</CODE></A> |
| interface, supporting implementations of more complex catalogue |
| schemes such as the one defined by the <a href= |
| "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html" |
| >OASIS XML Catalogs</a> specification.</p> |
| |
| <p>Parsers configured to use this resolver method will call it |
| to determine the input source to use for any external entity |
| being included because of a reference in the XML text. |
| That excludes the document entity, and any external entity returned |
| by <A HREF="../../../../org/xml/sax/ext/EntityResolver2.html#getExternalSubset(java.lang.String, java.lang.String)">getExternalSubset()</A>. |
| When a (non-validating) processor is configured not to include |
| a class of entities (parameter or general) through use of feature |
| flags, this method is not invoked for such entities. </p> |
| |
| <p>Note that the entity naming scheme used here is the same one |
| used in the <A HREF="../../../../org/xml/sax/ext/LexicalHandler.html"><CODE>LexicalHandler</CODE></A>, or in the <A HREF="../../../../org/xml/sax/ContentHandler.html#skippedEntity(java.lang.String)">ContentHandler.skippedEntity()</A> |
| method. </p><DD><DL>
|
| <DT><B>Parameters:</B><DD><CODE>name</CODE> - Identifies the external entity being resolved. |
| Either "[dtd]" for the external subset, or a name starting |
| with "%" to indicate a parameter entity, or else the name of |
| a general entity. This is never null when invoked by a SAX2 |
| parser.<DD><CODE>publicId</CODE> - The public identifier of the external entity being |
| referenced (normalized as required by the XML specification), or |
| null if none was supplied.<DD><CODE>baseURI</CODE> - The URI with respect to which relative systemIDs |
| are interpreted. This is always an absolute URI, unless it is |
| null (likely because the XMLReader was given an InputSource without |
| one). This URI is defined by the XML specification to be the one |
| associated with the "<" starting the relevant declaration.<DD><CODE>systemId</CODE> - The system identifier of the external entity |
| being referenced; either a relative or absolute URI. |
| This is never null when invoked by a SAX2 parser; only declared |
| entities, and any external subset, are resolved by such parsers.<DT><B>Returns:</B><DD>An InputSource object describing the new input source to |
| be used by the parser. Returning null directs the parser to |
| resolve the system ID against the base URI and open a connection |
| to resulting URI.<DT><B>Throws:</B><DD><A HREF="../../../../org/xml/sax/SAXException.html">SAXException</A> - Any SAX exception, possibly wrapping |
| another exception.<DD>java.io.IOException - Probably indicating a failure to create |
| a new InputStream or Reader, or an illegal URL.</DL>
|
| </DD>
|
| </DL>
|
| <!-- ========= END OF CLASS DATA ========= -->
|
| <HR>
|
|
|
| <!-- ========== START OF NAVBAR ========== -->
|
| <A NAME="navbar_bottom"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
|
| <TR>
|
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
|
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
|
| <TR ALIGN="center" VALIGN="top">
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
|
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/EntityResolver2.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
|
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
|
| </TR>
|
| </TABLE>
|
| </TD>
|
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
|
| </EM>
|
| </TD>
|
| </TR>
|
|
|
| <TR>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../../org/xml/sax/ext/DeclHandler.html"><B>PREV CLASS</B></A>
|
| <A HREF="../../../../org/xml/sax/ext/LexicalHandler.html"><B>NEXT CLASS</B></A></FONT></TD>
|
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
|
| <A HREF="../../../../index.html" TARGET="_top"><B>FRAMES</B></A>
|
| <A HREF="EntityResolver2.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
|
| </TR>
|
| <TR>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| SUMMARY: INNER | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD>
|
| <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
|
| DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD>
|
| </TR>
|
| </TABLE>
|
| <!-- =========== END OF NAVBAR =========== -->
|
|
|
| <HR>
|
| Copyright © 2006 Apache XML Project. All Rights Reserved.
|
| </BODY>
|
| </HTML>
|
