模块 java.xml
包 javax.xml.catalog

类 CatalogFeatures

java.lang.Object
javax.xml.catalog.CatalogFeatures
public class CatalogFeatures extends Object
CatalogFeatures 包含功能和属性的集合。
目录功能
特征 Description 属性名称 系统属性 [1] jaxp.properties [1] 值 [2] Action
Type Value
FILES 用于查找目录文件的以分号分隔的 URI 列表。 URI 必须是绝对的，并且具有用于 URI 方案的 URL 协议处理程序。 javax.xml.catalog.files javax.xml.catalog.files javax.xml.catalog.files String URIs 读取第一个目录作为当前目录；如果在当前目录中找不到匹配项，则加载其他目录，包括委托目录（如果有）。
PREFER 指示公共标识符和系统标识符之间的首选项。默认值为公共 [3]。 javax.xml.catalog.prefer N/A N/A String system 搜索匹配项的系统条目；当外部标识符仅指定公共标识符时搜索公共条目
public 搜索匹配项的系统条目；当没有匹配的系统条目时搜索公共条目。
DEFER 表示直到需要时才读取替代目录，包括在委托条目或 nextCatalog 中指定的目录。默认值是true。 javax.xml.catalog.defer [4] javax.xml.catalog.defer javax.xml.catalog.defer String true 根据需要加载替代目录。
false 加载所有目录 [5]。
RESOLVE 确定在用尽所有指定目录后没有找到匹配条目时的操作。默认是严格的。 javax.xml.catalog.resolve [4] javax.xml.catalog.resolve javax.xml.catalog.resolve String strict 如果没有匹配项，则抛出 CatalogException。
continue 允许 XML 解析器继续，就好像没有匹配项一样。
ignore 如果没有匹配项，则告诉 XML 解析器跳过外部引用。

[1]标记为“N/A”的功能没有系统属性。

[2]该值应与本表中所列的完全一致，区分大小写。任何未指定的值都将导致 IllegalArgumentException 。

[3]目录规范在 首选属性 上定义了复杂的规则。尽管 prefer 可以是 public 或 system，但规范实际上将 system 设置为首选选项，即无论选项如何，只要找到系统条目，就会始终使用。仅当首选项是公共的且未找到系统条目时才考虑公共条目。因此建议将 prefer 属性设置为 public（默认）。

[4]尽管 OASIS Catalog 规范中的非标准属性，defer 和 resolve 被 Java Catalog API 识别为与 prefer 相同的主目录的目录条目中的属性。请注意，只会使用为主目录文件的目录条目指定的属性。

[5]如果打算共享整个目录存储，则可能需要将属性 javax.xml.catalog.defer 设置为 false 以允许预加载整个目录。

范围和顺序

可以通过目录文件、目录 API、系统属性和 jaxp.properties 设置功能和属性，首选项的顺序相同。

在目录和组条目的目录文件中指定为属性的属性应优先于任何其他设置。例如，如果 prefer 属性在目录文件中设置为 <catalog prefer="public"> ，则“prefer”属性的任何其他输入都不是必需的或将被忽略。

通过 Catalog API 设置的属性会覆盖那些可能已由系统属性和/或在 jaxp.properties 中设置的属性。在多个接口的情况下，流程中最新的优先。对于 CatalogFeatures.Feature.FILES ，这意味着通过 CatalogManager 的方法指定的 URI 将覆盖可能已通过 CatalogFeatures.Builder 输入的任何 URI。

设置时的系统属性应覆盖 jaxp.properties 中的那些。

jaxp.properties 文件通常位于 Java 安装的 conf 目录中。该文件仅由 JAXP 实现读取一次，然后将其值缓存起来以备将来使用。如果在第一次尝试读取文件时该文件不存在，则不会进一步尝试检查其是否存在。 jaxp.properties 中的任何属性值在读取后都无法更改。

可以通过其构建器创建 CatalogFeatures 实例，如以下示例代码所示：


        CatalogFeatures f = CatalogFeatures.builder()
            .with(Feature.FILES, "file:///etc/xml/catalog")
            .with(Feature.PREFER, "public")
            .with(Feature.DEFER, "true")
            .with(Feature.RESOLVE, "ignore")
            .build();

JAXP XML 处理器支持

整个 JAXP 处理器都支持目录功能，包括 SAX 和 DOM (javax.xml.parsers )、StAX 解析器 (javax.xml.stream )、模式验证 (javax.xml.validation ) 和 XML 转换 (javax.xml.transform )。可以通过定义 setProperty 或 setAttribute 接口的 JAXP 工厂或处理器来设置上述功能。例如，以下代码片段通过 javax.xml.catalog.files 属性将 URI 设置为 SAX 解析器上的目录文件： 

   SAXParserFactory spf = SAXParserFactory.newInstance();
   spf.setFeature(XMLConstants.USE_CATALOG, true); [1]
   SAXParser parser = spf.newSAXParser();
   parser.setProperty(CatalogFeatures.Feature.FILES.getPropertyName(), "file:///etc/xml/catalog");

[1] 请注意，此语句不是必需的，因为 USE_CATALOG 的默认值为真。

JAXP 处理器对目录的支持取决于USE_CATALOG 特性和有效目录文件的存在。仅当该特性为真并且通过 javax.xml.catalog.files 属性指定有效目录文件时，JAXP 处理器才会使用目录。如果 USE_CATALOG 设置为 false，或者没有指定目录文件，它将不会尝试使用目录。

JAXP 处理器将遵守 CatalogFeatures 的默认设置。例如，由于 javax.xml.catalog.resolve 属性的默认值为 strict，因此在找不到匹配条目时，处理器将默认报告异常。

JAXP 处理器优先考虑用户指定的自定义解析器。如果注册了这样的解析器，它将在 CatalogResolver 上使用。但是，如果它返回 null，处理器将继续使用 CatalogResolver 进行解析。如果它返回空源，则 CatalogResolver 将不会进行任何尝试。

目录支持可用于支持解析器的 JAXP 库中的任何进程。下表列出了所有此类进程。

具有目录支持的流程

具有目录支持的流程
Process 目录条目类型 示例
DTD 和外部实体 公共、系统 
  The following DTD reference:
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

  Can be resolved using the following Catalog entry:
  <public publicId="-//W3C//DTD XHTML 1.0 Strict//EN" uri="catalog/xhtml1-strict.dtd"/>
  or
  <systemSuffix systemIdSuffix="html1-strict.dtd" uri="catalog/xhtml1-strict.dtd"/>
XInclude uri 
  The following XInclude element:
  <xi:include href="https://openjdk.org/xml/disclaimer.xml"/>

  can be resolved using a URI entry:
  <uri name="https://openjdk.org/xml/disclaimer.xml" uri="file:///pathto/local/disclaimer.xml"/>
  or
  <uriSuffix uriSuffix="disclaimer.xml" uri="file:///pathto/local/disclaimer.xml"/>
XSD导入 uri 
  The following import element:
  <xsd:import namespace="https://openjdk.org/xsd/XSDImport_person"
        schemaLocation="https://openjdk.org/xsd/XSDImport_person.xsd"/>

  can be resolved using a URI entry:
  <uri name="https://openjdk.org/xsd/XSDImport_person.xsd" uri="file:///pathto/local/XSDImport_person.xsd"/>
  or
  <uriSuffix uriSuffix="XSDImport_person.xsd" uri="file:///pathto/local/XSDImport_person.xsd"/>
  or
  <uriSuffix uriSuffix="https://openjdk.org/xsd/XSDImport_person" uri="file:///pathto/local/XSDImport_person.xsd"/>
XSD包括 uri 
  The following include element:
  <xsd:include schemaLocation="https://openjdk.org/xsd/XSDInclude_person.xsd"/>

  can be resolved using a URI entry:
  <uri name="https://openjdk.org/xsd/XSDInclude_person.xsd" uri="file:///pathto/local/XSDInclude_person.xsd"/>
  or
  <uriSuffix uriSuffix="XSDInclude_person.xsd" uri="file:///pathto/local/XSDInclude_person.xsd"/>
XSL 导入和包含 uri 
  The following include element:
  <xsl:include href="https://openjdk.org/xsl/include.xsl"/>

  can be resolved using a URI entry:
  <uri name="https://openjdk.org/xsl/include.xsl" uri="file:///pathto/local/include.xsl"/>
  or
  <uriSuffix uriSuffix="include.xsl" uri="file:///pathto/local/include.xsl"/>
XSL文档函数 uri 
  The document in the following element:
  <xsl:variable name="dummy" select="document('https://openjdk.org/xsl/list.xml')"/>

  can be resolved using a URI entry:
  <uri name="https://openjdk.org/xsl/list.xml" uri="file:///pathto/local/list.xml"/>
  or
  <uriSuffix uriSuffix="list.xml" uri="file:///pathto/local/list.xml"/>
自从：
9

  • 方法详情

    • defaults

      public static CatalogFeatures  defaults()
      返回具有默认设置的 CatalogFeatures 实例。
      返回：
      默认的 CatalogFeatures 实例

    • get

      public String  get(CatalogFeatures.Feature  cf)
      返回指定特征的值。
      参数：
      cf - 目录功能的类型
      返回：
      特征值

    • builder

      public static CatalogFeatures.Builder  builder()
      返回用于创建 CatalogFeatures 对象的构建器实例。
      返回：
      构建器的一个实例