Module java.xml

module java.xml
定义了用于XML处理（JAXP）的Java API。

JAXP API

JAXP包括一组基于多种XML技术和标准构建的API，这些API对于XML处理至关重要。其中包括用于：

工厂和处理器

工厂是每个API的入口点，提供方法允许应用程序在创建处理器之前以编程方式设置JAXP属性。 配置部分提供了更多关于此的详细信息。工厂还支持JAXP查找机制，应用程序可以部署第三方实现以替代JDK实现。

处理器是解析器（或读取器）、序列化器（或写入器）、验证器和转换器的聚合体，控制并执行各自领域的处理。它们在各自相关的包中定义。例如，在parsers包中，有代表DOM和SAX处理器的DocumentBuilder和SAXParser。

处理器通过其对应的工厂进行配置和实例化。例如，DocumentBuilder和SAXParser分别使用DocumentBuilderFactory和SAXParserFactory构建。

配置

当首次调用JAXP工厂时，它会执行配置过程以确定要使用的实现及其后续行为。在配置期间，工厂会检查诸如JAXP属性、系统属性和JAXP配置文件等配置源，并根据属性优先级设置值。以下定义了术语和过程。

JAXP属性

JAXP属性是应用于XML处理器的配置设置。它们可用于控制和自定义处理器的行为。根据正在使用的JAXP API，JAXP属性可能被称为属性、特性或功能。

系统属性

一些JAXP属性具有相应的系统属性，允许在运行时、命令行或JAXP配置文件中设置这些属性。例如，系统属性javax.xml.catalog.resolve可用于设置CatalogFeatures的RESOLVE属性。

系统属性读取的确切时间未指定。为确保所需值得到正确应用，应用程序应确保在创建第一个JAXP工厂之前适当设置系统属性，并在此后不进行修改。

配置文件

JAXP支持使用配置文件指定要加载的JAXP工厂的实现类，以及设置JAXP属性。

配置文件是JavaProperties文件，包含各种API或进程定义的系统属性及其值之间的映射。以下配置文件条目演示了设置javax.xml.parsers.DocumentBuilderFactory和CatalogFeatures.RESOLVE属性：

   javax.xml.parsers.DocumentBuilderFactory=packagename.DocumentBuilderFactoryImpl
   javax.xml.catalog.resolve=strict

jaxp.properties文件

默认情况下，JAXP会查找位于${java.home}/conf目录中的配置文件jaxp.properties；如果文件存在，则加载指定的属性以自定义XML工厂和处理器的行为。

jaxp.properties文件在初始化JAXP实现期间仅读取一次，并缓存在内存中。如果访问或读取文件时出现错误，则配置过程将继续进行，就好像文件不存在一样。

用户定义的配置文件

除了jaxp.properties文件外，系统属性java.xml.config.file可以设置以指定配置文件的位置。如果在配置文件中包含了java.xml.config.file属性，则它将被忽略。

当指定了java.xml.config.file时，将读取配置文件，并包含的属性将覆盖在jaxp.properties文件中定义的相同属性。如果在初始化JAXP实现时未设置java.xml.config.file，则不会进一步尝试检查其是否存在。

java.xml.config.file值必须包含有效的配置文件路径名。如果路径名不是绝对路径，则将被视为相对于JVM的工作目录。如果读取配置文件时出现错误，则配置过程将继续进行，就好像未设置java.xml.config.file属性一样。实现可以选择发出警告消息。

属性优先级

JAXP属性可以通过多种方式设置，包括API方法、系统属性和JAXP配置文件。如果未明确设置，它们将使用默认值进行初始化，或者在启用FEATURE_SECURE_PROCESSING（FSP）时使用更严格的值。属性的配置优先级顺序如下，从高到低：

  • 工厂或处理器的API

  • 系统属性

  • 用户定义的配置文件

  • 默认JAXP配置文件jaxp.properties

  • JAXP属性的默认值。如果FSP为true，则默认值将设置为安全处理XML。

以CatalogFeatures的RESOLVE属性为例，以下说明了这些规则的应用：

  • 使用工厂或处理器API指定的属性具有最高优先级。以下代码有效地将RESOLVE属性设置为strict，而不考虑其他配置源中的设置。

       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
   dbf.setAttribute(CatalogFeatures.Feature.RESOLVE.getPropertyName(), "strict");

  • 如果在工厂中未设置属性，如上述代码中，系统属性设置将生效。

        // 在以下示例中，将整个应用程序的RESOLVE属性设置为'continue'
    java -Djavax.xml.catalog.resolve=continue myApp

  • 如果在工厂中未设置属性，或使用系统属性，则配置文件中的设置将生效。以下条目将属性设置为'continue'。

        javax.xml.catalog.resolve=continue

  • 如果未在任何地方设置属性，则将解析为其默认值'strict'。

JAXP查找机制

JAXP定义了有序的查找过程，以确定要加载的JAXP工厂的实现类。支持该机制的工厂在下表中列出，以及在过程中要使用的方法、系统属性和系统默认方法。
JAXP 工厂
工厂 方法 系统属性 系统默认
数据类型工厂 newInstance() javax.xml.datatype.DatatypeFactory newDefaultInstance()
文档构建工厂 newInstance() javax.xml.parsers.DocumentBuilderFactory newDefaultInstance()
SAX解析器工厂 newInstance() javax.xml.parsers.SAXParserFactory newDefaultInstance()
XML事件工厂 newFactory() javax.xml.stream.XMLEventFactory newDefaultFactory()
XML输入工厂 newFactory() javax.xml.stream.XMLInputFactory newDefaultFactory()
XML输出工厂 newFactory() javax.xml.stream.XMLOutputFactory newDefaultFactory()
转换器工厂 newInstance() javax.xml.transform.TransformerFactory newDefaultInstance()
模式工厂 newInstance(schemaLanguage) javax.xml.validation.SchemaFactory:schemaLanguage[1] newDefaultInstance()
XPath工厂 newInstance(uri) DEFAULT_PROPERTY_NAME + ":uri"[2] newDefaultInstance()
[1] 其中 schemaLanguage 是 newInstance(schemaLanguage) 方法的参数。

[2] 其中 uri 是 newInstance(uri) 方法的参数。

查找过程

定位 JAXP 工厂 实现类的优先顺序如下，从高到低：
实现说明：

实现特定属性

除了标准JAXP属性外，JDK实现支持一些以"jdk.xml."为前缀的实现特定属性。这些属性也遵循配置部分中定义的配置过程。

请参考实现特定属性表，查看JDK实现支持的属性列表。

处理器支持

这些属性可能由一个或多个处理器支持，如下表所示。根据属性的类型，可以通过方法1：setAttribute/Parameter/Property或方法2：setFeature进行设置，如相关列中所示。
处理器
ID 名称 方法1：setAttribute/Parameter/Property 方法2：setFeature
DOM DOM解析器 DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setAttribute(name, value);		 DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setFeature(name, value);
SAX SAX解析器 SAXParserFactory spf = SAXParserFactory.newInstance();
SAXParser parser = spf.newSAXParser();
parser.setProperty(name, value);		 SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setFeature(name, value);
StAX StAX解析器 XMLInputFactory xif = XMLInputFactory.newInstance();
xif.setProperty(name, value);		 XMLInputFactory xif = XMLInputFactory.newInstance();
xif.setProperty(name, value);
验证 XML验证API SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);
schemaFactory.setProperty(name, value);		 SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);
schemaFactory.setFeature(name, value);
转换 XML转换API TransformerFactory factory = TransformerFactory.newInstance();
factory.setAttribute(name, value);		 TransformerFactory factory = TransformerFactory.newInstance();
factory.setFeature(name, value);
XSLTC序列化器 XSLTC序列化器 Transformer transformer = TransformerFactory.newInstance().newTransformer();
transformer.setOutputProperty(name, value);
DOM加载和保存 DOM加载和保存 LSSerializer serializer = domImplementation.createLSSerializer();
serializer.getDomConfig().setParameter(name, value);
XPath XPath XPathFactory factory = XPathFactory.newInstance();
factory.setProperty(name, value);		 XPathFactory factory = XPathFactory.newInstance();
factory.setFeature(name, value);
实现特定属性
全名（前缀 jdk.xml.）[1] 描述 系统属性[2] 值[3] 安全性[4] 支持的处理器[5] 自从[6]
类型 值 默认 强制 ID 设置方法
jdk.xml.entityExpansionLimit 限制实体扩展的数量。 是 整数 正整数。小于或等于0的值表示没有限制。如果值不是整数，则会抛出NumberFormatException。 64000 64000 是 DOM
SAX
StAX
Validation
Transform		 方法1 8
jdk.xml.elementAttributeLimit 限制元素可以拥有的属性数量。 10000 10000
jdk.xml.maxOccurLimit 限制在构建包含maxOccurs属性值不是"unbounded"的W3C XML模式的语法时可以创建的内容模型节点数量。 5000 5000
jdk.xml.totalEntitySizeLimit 限制包括通用实体和参数实体在内的所有实体的总大小。大小是所有实体的聚合计算。 5x10^7 5x10^7
jdk.xml.maxGeneralEntitySizeLimit 限制任何通用实体的最大大小。 0 0
jdk.xml.maxParameterEntitySizeLimit 限制任何参数实体的最大大小，包括嵌套多个参数实体的结果。 10^6 10^6
jdk.xml.entityReplacementLimit 限制所有实体引用中的节点总数。 3x10^6 3x10^6
jdk.xml.maxElementDepth 限制最大元素深度。 0 0
jdk.xml.maxXMLNameLimit 限制XML名称的最大大小，包括元素名称、属性名称和命名空间前缀和URI。 1000 1000
jdk.xml.isStandalone 指示序列化器应将输出视为独立文档。该属性可用于确保在XML声明后写入换行符。与属性xml-declaration不同，此属性不影响是否应写出XML声明。 布尔值 true/false false N/A 否 DOMLS 17
jdk.xml.xsltcIsStandalone 指示XSLTC序列化器应将输出视为独立文档。该属性可用于确保在XML声明后写入换行符。与属性OMIT_XML_DECLARATION不同，此属性不影响是否应写出XML声明。

此属性类似于上面的DOMLS属性，但适用于XSLTC序列化器，其值为字符串。

 字符串 yes/no no N/A 否 XSLTC序列化器 17
jdk.xml.cdataChunkSize 指示解析器在属性为零或未指定时以单个块返回CData部分中的数据，或在大于零时以多个块返回。解析器应通过换行符拆分数据，并将大于指定大小的块拆分为等于或小于该大小的块。 是 整数 正整数。小于或等于0的值表示未指定属性。如果值不是整数，则会抛出NumberFormatException。 0 N/A 否 SAX
StAX		 9
jdk.xml.extensionClassLoader 设置一个非空的ClassLoader实例，用于加载XSLTC Java扩展函数。 否 对象 对ClassLoader对象的引用。如果未指定值，则为null。 null N/A 否 Transform 9
jdk.xml.xpathExprGrpLimit 限制XPath表达式可以包含的组数。 是 整数 正整数。小于或等于0的值表示没有限制。如果值不是整数，则会抛出NumberFormatException。 10 10 是 Transform
XPath		 19
jdk.xml.xpathExprOpLimit 限制XPath表达式可以包含的运算符数量。 100 100
jdk.xml.xpathTotalOpLimit 限制XSL样式表中XPath运算符的总数。 10000 10000 Transform
jdk.xml.enableExtensionFunctions 确定是否允许使用XSLT和XPath扩展函数。 是 布尔值 true或false。True表示允许扩展函数；否则为false。 true false 是 Transform
XPath		 方法2 8
jdk.xml.overrideDefaultParser 启用第三方解析器实现，以覆盖JDK的Transform、Validation和XPath实现的系统默认解析器。 true或false。True启用第三方解析器实现，以覆盖XML Transform、Validation或XPath操作期间的系统默认实现。False禁用第三方解析器实现。 false false 是 Transform
Validation
XPath		 方法2 9
jdk.xml.resetSymbolTable 指示解析器在每次解析操作期间重置其内部符号表。 true或false。True表示解析器需要在每次解析操作期间重新分配与解析器关联的SymbolTable。
False表示解析器的SymbolTable实例将在后续解析操作期间重用。		 false N/A 否 SAX 方法2 9

[1] 应使用属性的完整名称来设置属性。

[2] 值为"yes"表示该属性有对应的系统属性，否则为"no"。系统属性的名称与属性的名称相同。

[3] 值必须与此表中列出的完全一致，区分大小写。相应系统属性的值是属性值的字符串表示。如果类型为布尔值，则仅当为"true"时系统属性为true；如果类型为字符串，则仅当为表示正值的完全相同字符串时系统属性为true（例如，对于xsltcIsStandalone为"yes"）；否则系统属性为false。如果类型为整数，则系统属性的值是该值的字符串表示（例如，对于entityExpansionLimit为"64000"）。

[4] 值为"yes"表示该属性是安全属性。如在属性优先级中所示，当FSP为true时，将使用列在enforced列中的值来初始化这些属性。

[5] 支持该属性的一个或多个处理器。ID和设置方法如表处理器中所示。

[6] 表示引入属性的初始版本。

旧属性名称（已弃用）

JDK 17之前的JDK版本支持使用URI样式前缀来设置属性。这些旧属性名称自JDK 17起已被弃用，可能会在未来版本中移除。如果同时设置了新旧属性名称，则无论如何和在哪里设置，新属性名称都优先。如在属性优先级中定义的覆盖顺序变为：
  • 使用新属性名称在工厂或处理器上设置的值。
  • 使用旧属性名称在工厂或处理器上设置的值；
  • 作为系统属性设置的值；
  • 在配置文件中设置的值；
  • 通过FEATURE_SECURE_PROCESSING设置的值；
  • 默认值；

以下表列出了属性及其对应的旧名称。

旧属性名称（自17起已弃用）
属性 旧属性名称
jdk.xml.entityExpansionLimit http://www.oracle.com/xml/jaxp/properties/entityExpansionLimit
jdk.xml.elementAttributeLimit http://www.oracle.com/xml/jaxp/properties/elementAttributeLimit
jdk.xml.maxOccurLimit http://www.oracle.com/xml/jaxp/properties/maxOccurLimit
jdk.xml.totalEntitySizeLimit http://www.oracle.com/xml/jaxp/properties/totalEntitySizeLimit
jdk.xml.maxGeneralEntitySizeLimit http://www.oracle.com/xml/jaxp/properties/maxGeneralEntitySizeLimit
jdk.xml.maxParameterEntitySizeLimit http://www.oracle.com/xml/jaxp/properties/maxParameterEntitySizeLimit
jdk.xml.entityReplacementLimit http://www.oracle.com/xml/jaxp/properties/entityReplacementLimit
jdk.xml.maxElementDepth http://www.oracle.com/xml/jaxp/properties/maxElementDepth
jdk.xml.maxXMLNameLimit http://www.oracle.com/xml/jaxp/properties/maxXMLNameLimit
jdk.xml.isStandalone http://www.oracle.com/xml/jaxp/properties/isStandalone
jdk.xml.xsltcIsStandalone http://www.oracle.com/xml/is-standalone
http://www.oracle.com/xml/jaxp/properties/xsltcIsStandalone
jdk.xml.extensionClassLoader jdk.xml.transform.extensionClassLoader
jdk.xml.enableExtensionFunctions http://www.oracle.com/xml/jaxp/properties/enableExtensionFunctions
模块图：
java.xml的模块图java.xml的模块图
自版本：
9