Module java.xml
Package org.xml.sax.ext

Interface EntityResolver2

所有超级接口:
EntityResolver
所有已知实现类:
DefaultHandler2
public interface EntityResolver2 extends EntityResolver
用于将外部实体引用映射到输入源或提供缺失的外部子集的扩展接口。XMLReader.setEntityResolver()方法用于向解析器提供此接口的实现。当解析器使用此接口中的方法时，将使用此接口中的EntityResolver2.resolveEntity()方法，而不是较旧的（SAX 1.0）EntityResolver.resolveEntity()方法。

如果SAX应用程序需要自定义处理此接口为外部实体定义的处理方式，则必须确保使用具有http://xml.org/sax/features/use-entity-resolver2特性标志设置为true的XMLReader（当识别到该特性时，其默认值为true）。如果该标志未被识别，或其值为false，或解析器未实现此接口，则只会使用EntityResolver方法。

这支持三种修改实体解析的应用程序类别。 旧样式 应用程序不会了解此接口；它们将提供一个EntityResolver。 过渡模式 提供一个EntityResolver2，并且由于多态性，在支持它的任何系统（解析器或其他工具）中自动获得其方法的好处。 旧样式 和 过渡模式 应用程序将与任何SAX2解析器一起工作。 新样式 应用程序将无法在不支持此特定特性的SAX2解析器上运行。它们将坚持要求特性标志的值为"true"，并且它们提供的EntityResolver2实现可能会在调用原始的SAX 1.0样式实体解析方法时抛出异常。

自从:
1.5, SAX 2.0 (扩展 1.1 alpha)
参见:

  • Method Details

    • getExternalSubset

      InputSource getExternalSubset(String name, String baseURI) throws SAXException, IOException
      允许应用程序为未明确定义外部子集的文档提供外部子集。省略外部子集的DOCTYPE声明的文档可以增补可用于验证、实体处理和属性处理（规范化、默认值和报告类型，包括ID）的声明。通过startDTD()方法报告此增补，就好像文档文本最初包含了外部子集；在报告任何内部子集数据或错误之前，将调用此回调。

      此方法还可用于没有DOCTYPE声明的文档。当遇到根元素但未看到DOCTYPE声明时，将调用此方法。如果为外部子集返回一个值，则将声明该根元素为根元素，从而使得在本来无法有效的文档的序言末尾插入一个DOCTYPE声明。在这种情况下，解析器回调的顺序在逻辑上类似于这样：

       ...来自序言的注释和PI（通常）
 startDTD ("rootName", source.getPublicId (), source.getSystemId ());
 startEntity ("[dtd]");
 ...来自外部子集的声明、注释和PI
 endEntity ("[dtd]");
 endDTD ();
 ...然后文档的其余部分（通常）
 startElement (..., "rootName", ...);

      请注意，InputSource不会进一步解析。此方法的实现可能希望调用resolveEntity()以获得诸如使用DTD实体的本地缓存等好处。此方法永远不会被不包括外部参数实体的（非验证）处理器使用。

      此方法的用途包括在与始终需要对外部实体进行不希望的网络访问的XML处理器进行交互时促进数据验证，或者出于其他原因采用“无DTD”策略。非验证动机包括强制文档包含DTD，以便一致处理属性。例如，XPath处理器需要知道哪些属性具有类型“ID”，然后才能处理一种广泛使用的引用类型。

      警告: 返回外部子集会修改输入文档。通过为一般实体提供定义，可以使格式不正确的文档看起来是格式正确的。

      参数:
      name - 标识文档根元素。此名称来自DOCTYPE声明（如果有）或实际根元素。
      baseURI - 文档的基本URI，作为选择外部子集的附加提示。除非XMLReader没有提供绝对URI，否则这始终是绝对URI。
      返回:
      描述解析器要使用的新外部子集的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由XML规范定义为与开始相关声明的“<”相关联的URI。
      systemId - 被引用的外部实体的系统标识符；可以是相对或绝对URI。当由SAX2解析器调用时，此值永远不为null；只有声明的实体和任何外部子集由这些解析器解析。
      返回:
      描述解析器要使用的新输入源的InputSource对象。返回null会指示解析器根据基本URI解析系统ID并打开到结果URI的连接。
      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。
      IOException - 可能表示无法创建新的InputStream或Reader，或非法URL。