Module  java.xml
软件包  org.xml.sax.ext

Interface EntityResolver2

  • All Superinterfaces:
    EntityResolver
    所有已知实现类：
    DefaultHandler2 

    public interface EntityResolver2
extends EntityResolver
    用于将外部实体引用映射到输入源的扩展接口，或提供缺少的外部子集。 XMLReader.setEntityResolver()方法用于向解析器提供此接口的实现。 当解析器使用此接口中的方法时，将使用EntityResolver2.resolveEntity()方法（在此界面中）， 而不是较旧的（SAX 1.0） EntityResolver.resolveEntity()方法。
    This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

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

    它支持修改实体分辨率的三类应用程序。 旧样式的应用程序不会知道这个界面; 他们将提供一个EntityResolver。 过渡模式提供了一个EntityResolver2，并且由于多态而在任何支持它的系统（解析器或其他工具）中自动获得其方法的优点。 旧样式和过渡模式应用程序都可以与任何SAX2解析器配合使用。 除了支持该特定功能的SAX2解析器之外， 新样式应用程序将无法运行。 他们会坚持feature标志的值为“true”，如果调用了原来的SAX 1.0风格的实体解析方法，它们提供的EntityResolver2实现可能会引发异常。

    从以下版本开始：
    1.5，SAX 2.0（扩展1.1 alpha）
    另请参见：
    XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

    • 方法详细信息

      • 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处理器需要知道哪些attibutes具有类型“ID”才能处理广泛使用的引用类型。

        警告：返回外部子组修改输入文档。 通过为一般实体提供定义，可以使格式错误的文档看起来形成良好。

        参数
        name - 标识文档根元素。 该名称来自DOCTYPE声明（如果可用）或实际根元素。
        baseURI - 文档的基本URI，用作选择外部子集的附加提示。 这总是一个绝对URI，除非它是null，因为XMLReader没有一个InputSource。
        结果
        描述要由解析器使用的新外部子集的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解析器调用时，这从不为空。
        publicId - 被引用的外部实体的公共标识符（按照XML规范的要求进行规范化），如果没有提供，则为null。
        baseURI - 相对于哪个相对的系统ID进行解释的URI。 这绝对是一个绝对URI，除非它是null（可能是因为XMLReader没有一个InputSource）。 该URI由XML规范定义为与“<”启动相关声明相关联的URI。
        systemId - 被引用的外部实体的系统标识符; 一个相对或绝对的URI。 当SAX2解析器调用时，这不会为空; 只有声明的实体和任何外部子集才能被这样的解析器解析。
        结果
        描述由解析器使用的新输入源的InputSource对象。 返回null指示解析器根据基本URI解析系统ID，并打开到结果URI的连接。
        异常
        SAXException - 任何SAX异常，可能包装另一个异常。
        IOException - 可能表示无法创建新的InputStream或Reader或非法URL。