# Module java.xml

Defines the Java API for XML Processing (JAXP), the Streaming API for XML (StAX), the Simple API for XML (SAX), and the W3C Document Object Model (DOM) API.

## Configuration File

The java.xml (JAXP) Configuration File is used for configuring factories in the Factory Lookup Mechanism, secure processing, and Catalog API.

### Format

The configuration file is in standard `Properties` format.

The keys are:

- For the Factory Lookup Mechanism, System properties as listed in column System Property of the table JAXP Factories.

- For secure processing, `Full Name` in table Implementation Specific Properties and Features

- For the Catalog API, `System Property` in table `Catalog Features` of class `CatalogFeatures`

The values are:

- For the Factory Lookup Mechanism, the fully qualified name of the implementation class.

- For secure processing, `Value` in table Implementation Specific Properties and Features

- For the Catalog API, `value` in table `Catalog Features` of class `CatalogFeatures`

Below are examples on what can be placed in the configuration file:

         javax.xml.parsers.DocumentBuilderFactory=packagename.DocumentBuilderFactoryImpl
         jdk.xml.entityExpansionLimit=2000

### Default

The JDK may be distributed with a configuration file called `jaxp.properties` that are used by all factories listed in the table below. It may also include one called `stax.properties` that will be used by the StAX factories for the Factory Lookup Mechanism only. The files, if exist, are typically located in the `conf` directory of the Java installation.

The default files will be read only once during a factory initialization and the values are used while the factory is alive. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property after it has been read for the first time.

### System Property

The system property `jdk.xml.config.file` can be used to set up a configuration file outside of the JDK to override the default configuration file (jaxp.properties).

When the system property is specified, the configuration file it points to will override the default file in its entirety, that means no setting in the latter will be used by the factories. If the system property does not exist when a factory is instantiated, no further attempt will be made to locate it while the factory is alive.

## JAXP Lookup Mechanism

JAXP defines an ordered lookup procedure to determine the implementation class to load for the JAXP factories. Factories that support the mechanism are listed in the table below along with the method, System Property name, Configuration File, and System Default method to be used in the procedure.

JAXP Factories
Factory | Method | System Property Name | Configuration File | System Default
--- | --- | --- | --- | ---
`DatatypeFactory` | `newInstance()` | `javax.xml.datatype.DatatypeFactory` | Configuration File, jaxp.properties by default | `newDefaultInstance()`
`DocumentBuilderFactory` | `newInstance()` | `javax.xml.parsers.DocumentBuilderFactory` | Configuration File, jaxp.properties by default | `newDefaultInstance()`
`SAXParserFactory` | `newInstance()` | `javax.xml.parsers.SAXParserFactory` | Configuration File, jaxp.properties by default | `newDefaultInstance()`
`XMLEventFactory` | `newFactory()` | `javax.xml.stream.XMLEventFactory` | Configuration File, stax.properties and/or jaxp.properties by default | `newDefaultFactory()`
`XMLInputFactory` | `newFactory()` | `javax.xml.stream.XMLInputFactory` | Configuration File, stax.properties and/or jaxp.properties by default | `newDefaultFactory()`
`XMLOutputFactory` | `newFactory()` | `javax.xml.stream.XMLOutputFactory` | Configuration File, stax.properties and/or jaxp.properties by default | `newDefaultFactory()`
`TransformerFactory` | `newInstance()` | `javax.xml.transform.TransformerFactory` | Configuration File, jaxp.properties by default | `newDefaultInstance()`
`SchemaFactory` | `newInstance(schemaLanguage)` | `javax.xml.validation.SchemaFactory:`schemaLanguage[1] | Configuration File, jaxp.properties by default | `newDefaultInstance()`
`XPathFactory` | `newInstance(uri)` | `DEFAULT_PROPERTY_NAME` + ":uri"[2] | Configuration File, jaxp.properties by default | `newDefaultInstance()`

[1] where schemaLanguage is the parameter to the `newInstance(schemaLanguage)` method.

[2] where uri is the parameter to the `newInstance(uri)` method.

### Lookup Procedure

The JAXP Factories follow the procedure described below in order to locate and load the implementation class:

- Use the system property as described in column System Property of the table JAXP Factories above.

- Use the Configuration File.

- Use the service-provider loading facility, defined by the `ServiceLoader` class, to attempt to locate and load an implementation of the service using the default loading mechanism: the service-provider loading facility will use the current thread's context class loader to attempt to load the service. If the context class loader is null, the system class loader will be used.

  ### `SchemaFactory`

  In case of the `SchemaFactory`, each potential service provider is required to implement the method `isSchemaLanguageSupported(String schemaLanguage)`. The first service provider found that supports the specified schema language is returned.

  ### `XPathFactory`

  In case of the `XPathFactory`, each potential service provider is required to implement the method `isObjectModelSupported(String objectModel)`. The first service provider found that supports the specified object model is returned.

- Otherwise, the `system-default` implementation is returned, which is equivalent to calling the `newDefaultInstance() or newDefaultFactory()` method as shown in column System Default of the table JAXP Factories above.

  ### `SchemaFactory`

  In case of the `SchemaFactory`, there must be a platform default `SchemaFactory` for W3C XML Schema.

  ### `XPathFactory`

  In case of the `XPathFactory`, there must be a platform default `XPathFactory` for the W3C DOM, i.e. `DEFAULT_OBJECT_MODEL_URI`.

Implementation Note:

  ## Implementation Specific Features and Properties

  In addition to the standard features and properties described within the public APIs of this module, the JDK implementation supports a further number of implementation specific features and properties. This section describes the naming convention, System Properties, scope and order, and processors to which a property applies. A table listing the implementation specific features and properties that the implementation currently supports can be found at the end of this note.

  ### Naming Convention

  The names of the features and properties are fully qualified, composed of a prefix and name.

  #### Prefix

  The prefix for JDK features and properties, as well as their corresponding System Properties if any, is defined as:

           jdk.xml.

  #### Name

  A name may consist of one or multiple words that are case-sensitive. All letters of the first word are in lowercase, while the first letter of each subsequent word is capitalized.

  An example of a property that indicates whether an XML document is standalone would thus have a format:

           jdk.xml.isStandalone

  and a corresponding System Property:

  ### System Properties

  A property may have a corresponding System Property with the same name. A System Property should be set prior to the creation of a processor and may be cleared afterwards.

  ### Configuration File

  A system property can be specified in the Configuration File to set the behavior for all invocations of the JDK. The format is `system-property-name=value`. For example:

           jdk.xml.isStandalone=true

  ### Scope and Order

  The `XMLConstants.FEATURE_SECURE_PROCESSING` feature (hereafter referred to as secure processing) is required for XML processors including DOM, SAX, Schema Validation, XSLT, and XPath. When secure processing is set to true, security related features and properties, such as those flagged as `"security: yes"` (hereafter referred to as security properties) in table Implementation Specific Features and Properties, are enforced. Such enforcement includes setting security properties and features to more restrictive values and limits as shown in `"Value"`'s subcolumn `"Enforced"` in the tables. When secure processing is set to false, however, the property values will not be affected.

  When the Java Security Manager is present, secure processing is set to true and can not be turned off. The security properties are therefore enforced.

  Properties specified in the configuration file affect all invocations of the JDK, and will override their default values, or those that may have been set by secure processing.

  System properties, when set, affect the invocation of the JDK and override the default settings or those that may have been set in the configuration file or by secure processing.

  JAXP properties specified through JAXP factories or processors (e.g. SAXParser) take preference over system properties, the configuration file, as well as secure processing.

  ### Processor Support

  Features and properties may be supported by one or more processors. The following table lists the processors by IDs that can be used for reference.

  Processors
  ID | Name | How to set the property | How to set the feature
  --- | --- | --- | ---
  DOM | DOM Parser | `DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();` `dbf.setAttribute(name, value);` | `DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();` `dbf.setFeature(name, value);`
  SAX | SAX Parser | `SAXParserFactory spf = SAXParserFactory.newInstance();` `SAXParser parser = spf.newSAXParser();` `parser.setProperty(name, value);` | `SAXParserFactory spf = SAXParserFactory.newInstance();` `spf.setFeature(name, value);`
  StAX | StAX Parser | `XMLInputFactory xif = XMLInputFactory.newInstance();` `xif.setProperty(name, value);` | `XMLInputFactory xif = XMLInputFactory.newInstance();` `xif.setProperty(name, value);`
  Validation | XML Validation API | `SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);` `schemaFactory.setProperty(name, value);` | `SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);` `schemaFactory.setFeature(name, value);`
  Transform | XML Transform API | `TransformerFactory factory = TransformerFactory.newInstance();` `factory.setAttribute(name, value);` | `TransformerFactory factory = TransformerFactory.newInstance();` `factory.setFeature(name, value);`
  XSLTC Serializer | XSLTC Serializer | `Transformer transformer = TransformerFactory.newInstance().newTransformer();` `transformer.setOutputProperty(name, value);` |
  DOMLS | DOM Load and Save | `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);`

  ### Implementation Specific Features and Properties

  The Implementation Specific Features and Properties reflect JDK's choice to manage the limitations on resources while complying with the API specification, or allow applications to alter behaviors beyond those required by the standards.

  The table below lists the Implementation Specific Properties currently supported by the JDK. More properties may be added in the future if necessary.

  Implementation Specific Properties
  Full Name (prefix + name) [1] | Description | API Property [2] | System Property [3] | Configuration File [3] | Value [4] | Security [5] | Supported Processor [6] | Since [7]
  --- | --- | --- | --- | --- | --- | --- | --- | ---
  Type | Value | Default | Enforced
  | Limits the number of entity expansions. | yes | yes | yes | Integer | A positive integer. A value less than or equal to 0 indicates no limit. If the value is not an integer, a NumberFormatException is thrown. | 64000 | 64000 | Yes | DOM SAX StAX Validation Transform | 8
  | Limits the number of attributes an element can have. | 10000 | 10000
  | Limits the number of content model nodes that may be created when building a grammar for a W3C XML Schema that contains maxOccurs attributes with values other than "unbounded". | 5000 | 5000
  | Limits the total size of all entities that include general and parameter entities. The size is calculated as an aggregation of all entities. | 5x10^7 | 5x10^7
  | Limits the maximum size of any general entities. | 0 | 0
  | Limits the maximum size of any parameter entities, including the result of nesting multiple parameter entities. | 10^6 | 10^6
  | Limits the total number of nodes in all entity references. | 3x10^6 | 3x10^6
  | Limits the maximum element depth. | 0 | 0
  | Limits the maximum size of XML names, including element name, attribute name and namespace prefix and URI. | 1000 | 1000
  | Indicates that the serializer should treat the output as a standalone document. The property can be used to ensure a newline is written after the XML declaration. Unlike the property `xml-declaration`, this property does not have an effect on whether an XML declaration should be written out. | yes | yes | yes | boolean | true/false | false | N/A | No | DOMLS | 17
  | Indicates that the XSLTC serializer should treat the output as a standalone document. The property can be used to ensure a newline is written after the XML declaration. Unlike the property `OMIT_XML_DECLARATION`, this property does not have an effect on whether an XML declaration should be written out. This property behaves similar to that for DOMLS above, except that it is for the XSLTC Serializer and its value is a String. | yes | yes | yes | String | yes/no | no | N/A | No | XSLTC Serializer | 17
  | Instructs the parser to return the data in a CData section in a single chunk when the property is zero or unspecified, or in multiple chunks when it is greater than zero. The parser shall split the data by linebreaks, and any chunks that are larger than the specified size to ones that are equal to or smaller than the size. | yes | yes | yes | Integer | A positive integer. A value less than or equal to 0 indicates that the property is not specified. If the value is not an integer, a NumberFormatException is thrown. | 0 | N/A | No | SAX StAX | 9
  jdk.xml.extensionClassLoader | Sets a non-null ClassLoader instance to be used for loading XSLTC java extension functions. | yes | no | no | Object | A reference to a ClassLoader object. Null if the value is not specified. | null | N/A | No | Transform | 9
  jdk.xml.xpathExprGrpLimit | Limits the number of groups an XPath expression can contain. | Transform:yes XPath:no | yes | yes | Integer | A positive integer. A value less than or equal to 0 indicates no limit. If the value is not an integer, a NumberFormatException is thrown. | 10 | 10 | Yes | Transform XPath | 19
  jdk.xml.xpathExprGrpLimit | Limits the number of operators an XPath expression can contain. | 100 | 100
  jdk.xml.xpathTotalOpLimit | Limits the total number of XPath operators in an XSL Stylesheet. | yes | 10000 | 10000 | Transform

  The table below lists the Implementation Specific Features currently supported by the JDK. More features may be added in the future if necessary.

  Implementation Specific Features
  Full Name (prefix + name) [1] | Description | API Property [2] | System Property [3] | Configuration File [3] | Value [4] | Security [5] | Supported Processor [6] | Since [7]
  --- | --- | --- | --- | --- | --- | --- | --- | ---
  Type | Value | Default | Enforced
  | Determines if XSLT and XPath extension functions are to be allowed. | yes | yes | yes | Boolean | true or false. True indicates that extension functions are allowed; False otherwise. | true | false | Yes | Transform XPath | 8
  | Enables the use of a 3rd party's parser implementation to override the system-default parser for the JDK's Transform, Validation and XPath implementations. | true or false. True enables the use of 3rd party's parser implementations to override the system-default implementation during XML Transform, Validation or XPath operation. False disables the use of 3rd party's parser implementations. | false | false | Yes | Transform Validation XPath | 9
  | Instructs the parser to reset its internal symbol table during each parse operation. | true or false. True indicates that the SymbolTable associated with a parser needs to be reallocated during each parse operation. False indicates that the parser's SymbolTable instance shall be reused during subsequent parse operations. | false | N/A | No | SAX | 9

  [1] The full name of a property should be used to set the property.

  [2] A value "yes" indicates that the property can be set through the processor or its factory, "no" otherwise.

  [3] A value "yes" indicates there is a corresponding System Property for the property, "no" otherwise.

  [4] The value must be exactly as listed in this table, case-sensitive. The value of the corresponding System Property is the String representation of the property value. If the type is boolean, the system property is true only if it is "true"; If the type is String, the system property is true only if it is exactly the same string representing the positive value (e.g. "yes" for `xsltcIsStandalone`); The system property is false otherwise. If the type is Integer, the value of the System Property is the String representation of the value (e.g. "64000" for `entityExpansionLimit`).

  [5] A value "yes" indicates the property is a Security Property. Refer to the Scope and Order on how secure processing may affect the value of a Security Property.

  [6] One or more processors that support the property. The values of the field are IDs described in table Processors.

  [7] Indicates the initial release the property is introduced.

  ### Legacy Property Names (deprecated)

  JDK releases prior to JDK 17 support the use of URI style prefix for properties. These legacy property names are deprecated as of JDK 17 and may be removed in future releases. If both new and legacy properties are set, the new property names take precedence regardless of how and where they are set. The overriding order as defined in Scope and Order thus becomes, in descending order:
  - The default value;
  - Value set by FEATURE_SECURE_PROCESSING;
  - Value set in the configuration file;
  - Value set as System Property;
  - Value set on factories or processors using legacy property names;
  - Value set on factories or processors using new property names.

  The following table lists the properties and their corresponding legacy names.

  Legacy Property Names (deprecated since 17)
  Property | Legacy Property Name(s)
  --- | ---
  | `http://www.oracle.com/xml/jaxp/properties/entityExpansionLimit`
  | `http://www.oracle.com/xml/jaxp/properties/elementAttributeLimit`
  | `http://www.oracle.com/xml/jaxp/properties/maxOccurLimit`
  | `http://www.oracle.com/xml/jaxp/properties/totalEntitySizeLimit`
  | `http://www.oracle.com/xml/jaxp/properties/maxGeneralEntitySizeLimit`
  | `http://www.oracle.com/xml/jaxp/properties/maxParameterEntitySizeLimit`
  | `http://www.oracle.com/xml/jaxp/properties/entityReplacementLimit`
  | `http://www.oracle.com/xml/jaxp/properties/maxElementDepth`
  | `http://www.oracle.com/xml/jaxp/properties/maxXMLNameLimit`
  | `http://www.oracle.com/xml/jaxp/properties/isStandalone`
  | `http://www.oracle.com/xml/is-standalone` `http://www.oracle.com/xml/jaxp/properties/xsltcIsStandalone`
  `jdk.xml.extensionClassLoader` | `jdk.xml.transform.extensionClassLoader`
  | `http://www.oracle.com/xml/jaxp/properties/enableExtensionFunctions`

Since:
  9

- - ### Packages

    Exports
    Package | Description
    --- | ---
    javax.xml | Defines constants for XML processing.
    javax.xml.catalog | Provides the classes for implementing XML Catalogs OASIS Standard V1.1, 7 October 2005.
    javax.xml.datatype | Defines XML/Java Type Mappings.
    javax.xml.namespace | Defines XML Namespace processing.
    javax.xml.parsers | Provides the classes for processing XML documents with a SAX (Simple API for XML) parser or a DOM (Document Object Model) Document builder.
    javax.xml.stream | Defines interfaces and classes for the Streaming API for XML (StAX).
    javax.xml.stream.events | Defines event interfaces for the Streaming API for XML (StAX).
    javax.xml.stream.util | Provides utility classes for the Streaming API for XML (StAX).
    javax.xml.transform | Defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
    javax.xml.transform.dom | Provides DOM specific transformation classes.
    javax.xml.transform.sax | Provides SAX specific transformation classes.
    javax.xml.transform.stax | Provides StAX specific transformation classes.
    javax.xml.transform.stream | Provides stream and URI specific transformation classes.
    javax.xml.validation | Provides an API for validation of XML documents.
    javax.xml.xpath | Provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.
    org.xml.sax | Provides the interfaces for the Simple API for XML (SAX).
    org.xml.sax.ext | Provides interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
    org.xml.sax.helpers | Provides helper classes, including support for bootstrapping SAX-based applications.

  - ### Services

    Uses
    Type | Description
    --- | ---
    DatatypeFactory | Factory that creates new `javax.xml.datatype` `Object`s that map XML to/from Java `Object`s.
    DocumentBuilderFactory | Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents.
    SAXParserFactory | Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents.
    SchemaFactory | Factory that creates `Schema` objects.
    TransformerFactory | A TransformerFactory instance can be used to create `Transformer` and `Templates` objects.
    XMLEventFactory | This interface defines a utility class for creating instances of XMLEvents
    XMLInputFactory | Defines an abstract implementation of a factory for getting streams.
    XMLOutputFactory | Defines an abstract implementation of a factory for getting XMLEventWriters and XMLStreamWriters.
    XMLReader | Interface for reading an XML document using callbacks.
    XPathFactory | An `XPathFactory` instance can be used to create `XPath` objects.