JavaTM 2 Platform
Standard Ed. 5.0

org.xml.sax.ext
接口 EntityResolver2

所有超级接口:
EntityResolver
所有已知实现类:
DefaultHandler2

public interface EntityResolver2
extends EntityResolver

扩展的接口,用于将外部实体引用映射到输入源,或用于提供缺少的外部子集。使用 XMLReader.setEntityResolver() 方法将此接口的实现提供给解析器。当解析器使用此接口中的方法时,将使用 EntityResolver2.resolveEntity() 方法(在此接口中)而不是 旧的 (SAX 1.0) EntityResolver.resolveEntity() 方法。

此模块(包括源代码和文档)在公共域中,同时 没有担保

如果 SAX 应用程序需要此接口为外部实体定义的自定义处理,则必须确保使用 XMLReader,并将 http://xml.org/sax/features/use-entity-resolver2)功能标志设置为 true(识别该功能时,是其默认值)。如果该标志不可识别,或其值为 false,或解析器不能实现此接口,那么仅使用 EntityResolver 方法。

它支持修改实体解析的三种类别的应用程序。旧式 应用程序不知道此接口;它们将提供 EntityResolver。由于多态性,转换模式 提供了 EntityResolver2,并自动获取在任何支持它的系统(解析器或其他工具)中方法的优点。旧式转换模式 应用程序将与任何 SAX2 解析器一起工作。新式 应用程序将运行失败,在支持此特定功能的 SAX2 分析器上运行除外。它们强调功能标志应有值 "true",如果调用原始 SAX 1.0 式实体解析方法,则它们提供的 EntityResolver2 实现可能会抛出异常。

从以下版本开始:
SAX 2.0 (extensions 1.1 alpha)
另请参见:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

方法摘要
 InputSource getExternalSubset(String name, String baseURI)
          允许应用程序为不能显式定义外部子集的文档提供外部子集。
 InputSource resolveEntity(String name, String publicId, String baseURI, String systemId)
          允许应用程序把对外部实体的引用映射到输入源,或告知解析器它应使用常规 URI 解析。
 
从接口 org.xml.sax.EntityResolver 继承的方法
resolveEntity
 

方法详细信息

getExternalSubset

InputSource getExternalSubset(String name,
                              String baseURI)
                              throws SAXException,
                                     IOException
允许应用程序为不能显式定义外部子集的文档提供外部子集。这样,具有 DOCTYPE 声明的忽略外部子集的文档可以增加可供验证、实体处理和属性处理(标准化、默认和报告包括 ID 的类型)使用的声明。通过 startDTD() 方法报告此增加,就像文档文本最初就包括外部子集一样;在报告任何内部子集数据或错误之前进行此回调。

此方法也可以与没有 DOCTYPE 声明的文档一起使用。当遇到根元素,但没有看到任何 DOCTYPE 声明时,调用此方法。如果返回该外部子集的一个值,则声明该根元素为根元素,条件是以其他方式在文档序言结尾衔接 DOCTYPE 声明无效。在该情况下,解析器回调序列逻辑上类似以下内容:

 ... 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", ...);
 

注意,InputSource 不能获得进一步的解析。此方法的实现可能要调用 resolveEntity() 以获得一些优点,如使用 DTD 实体的本地缓存。另外,不包括外部参数实体的(非验证)处理器永不使用此方法。

与 XML 处理器进行互操作时,此方法的使用包括简化数据验证,该处理器总是需要对外部实体的不合需要的网络访问,或者由于其他原因采用“非 DTD”策略。非验证目的包括强制文档去包括 DTD,以便能一致地处理属性。例如,XPath 处理器在它能够处理广泛使用的引用类型之前需要知道哪一个属性具有类型 "ID"。

警告:返回外部子集能修改输入文档。通过为常规实体提供定义,能使格式错误的文档看起来格式良好。

参数:
name - 标识文档根元素。此名称来自 DOCTYPE 声明(如果可用),或来自实际的根元素。
baseURI - 文档的基 URI,充当选择外部子集的附加提示。这总是一个绝对 URI,除非由于向 XMLReader 提供了一个不带 URI 的 InputSource 而使它为 null 时。
返回:
描述解析器使用的新外部子集的 InputSource 对象,或指示不提供任何外部子集的 null。
抛出:
SAXException - 任何 SAX 异常,可能包装另外的异常。
IOException - 可能指示创建新的 InputStream 或 Reader 失败,或非法 URL。

resolveEntity

InputSource resolveEntity(String name,
                          String publicId,
                          String baseURI,
                          String systemId)
                          throws SAXException,
                                 IOException
允许应用程序把对外部实体的引用映射到输入源,或告知解析器它应使用常规 URI 解析。仅对已正确声明的外部实体调用此方法。此方法提供比 EntityResolver 接口更多的灵活性,支持更复杂的目录方案(例如 OASIS XML Catalogs 规范定义的目录方案)的实现。

配置为使用此解析器方法的解析器将调用它,以确定用于由于 XML 文本中的引用而包括在内的任何外部实体的输入源。它排除文档实体和 getExternalSubset() 返回的任何外部实体。当通过使用功能标志将(非验证的)处理器配置为不包括实体(参数或常规)的类时,不为此类实体调用此方法。

注意,这里使用的实体命名方案与 LexicalHandler 中或 ContentHandler.skippedEntity() 方法中使用的相同。

参数:
name - 标识正被解析的外部实体。外部子集的 "[dtd]",或者以 "%" 开头用来指示参数实体的名称,或者常规实体的名称。在由 SAX2 解析器调用时,它永不能为 null。
publicId - 被引用的外部实体的公共标识符(按照 XML 规范的要求标准化),如果不提供任何内容,则为 null。
baseURI - 关于解释哪个相对 systemID 的 URI。这总是一个绝对 URI,除非它为 null(可能因为向 XMLReader 提供了一个不带 URI 的 InputSource)。XML 规范定义了此 URI,它是与开始相关声明的 "<" 相关联的 URI。
systemId - 引用的外部实体的系统标识符;相对 URI 或绝对 URI。由 SAX2 解析器调用时,它从不能为 null;此类解析器仅解析声明的实体和任何外部子集。
返回:
描述解析器使用的新输入源的 InputSource 对象。返回 null 指示解析器基于基 URI 解析系统 ID,并打开到产生的 URI 的连接。
抛出:
SAXException - 任何 SAX 异常,可能包装另外的异常。
IOException - 可能指示创建新的 InputStream 或 Reader 失败,或非法 URL。

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策