Module java.xml

• The JAXP APIs
• Factories and Processors
• Configuration
  • JAXP Properties
  • System Properties
  • Configuration File
    • jaxp.properties File
    • User-defined Configuration File
  • Property Precedence
• JAXP Lookup Mechanism
  • Lookup Procedure
• Implementation Note

The JAXP APIs

• Parsing: the JAXP Parsing API based on Document Object Model (DOM) and Simple API for XML Parsing (SAX), and Streaming API for XML (StAX);
• Serializing: StAX and Extensible Stylesheet Language Transformations (XSLT);
• Validation: the JAXP Validation API based on the XML Schema Definition Language;
• Transformation: the JAXP Transformation API or XSLT (Extensible Stylesheet Language Transformations);
• Querying and traversing XML documents: the XML XPath Language API (XPath);
• Resolving external resources: the XML Catalog API;

Factories and Processors

Processors are aggregates of parsers (or readers), serializers (or writers), validators, and transformers that control and perform the processing in their respective areas. They are defined in their relevant packages. In the parsers package for example, are the DocumentBuilder and SAXParser, that represent the DOM and SAX processors.

The processors are configured and instantiated with their corresponding factories. The DocumentBuilder and SAXParser for example are constructed with the DocumentBuilderFactory and SAXParserFactory respectively.

Configuration

JAXP Properties

System Properties

The exact time at which system properties are read is unspecified. In order to ensure that the desired values are properly applied, applications should ensure that system properties are set appropriately prior to the creation of the first JAXP factory and are not modified thereafter.

Configuration File

Configuration files are Java java.util.Properties files that consist of mappings between system properties and their values defined by various APIs or processes. The following configuration file entries demonstrate setting the javax.xml.parsers.DocumentBuilderFactory and CatalogFeatures.RESOLVE properties:

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

jaxp.properties File

The jaxp.properties file will be read only once during the initialization of the JAXP implementation and cached in memory. If there is an error accessing or reading the file, the configuration process proceeds as if the file does not exist.

User-defined Configuration File

When the java.xml.config.file is specified, the configuration file will be read and the included properties will override the same properties that were defined in the jaxp.properties file. If the java.xml.config.file has not been set when the JAXP implementation is initialized, no further attempt will be made to check for its existence.

The java.xml.config.file value must contain a valid pathname to a configuration file. If the pathname is not absolute, it will be considered relative to the working directory of the JVM. If there is an error reading the configuration file, the configuration process proceeds as if the java.xml.config.file property was not set. Implementations may optionally issue a warning message.

Property Precedence

• The APIs for factories or processors

• System Property

• User-defined Configuration File

• The default JAXP Configuration File jaxp.properties

• The default values for JAXP Properties. If the FSP is true, the default values will be set to process XML securely.

• Properties specified with factory or processor APIs have the highest precedence. The following code effectively sets the RESOLVE property to strict, regardless of settings in any other configuration sources.

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

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

• If the property is not set on the factory as in the above code, a system property setting will be in effect.

   // in the following example, the RESOLVE property is set to 'continue' // for the entire application java -Djavax.xml.catalog.resolve=continue myApp

  // in the following example, the RESOLVE property is set to 'continue'
  // for the entire application
  java -Djavax.xml.catalog.resolve=continue myApp
  

• If the property is not set on the factory, or using a system property, the setting in a configuration file will take effect. The following entry sets the property to 'continue'.

   javax.xml.catalog.resolve=continue

  javax.xml.catalog.resolve=continue
  

• If the property is not set anywhere, it will be resolved to its default value that is 'strict'.

JAXP Lookup Mechanism

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

Lookup Procedure

• The system property as listed in the column System Property of the table JAXP Factories above

• The Configuration File

• The service-provider loading facility, defined by the java.util.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.

JDK built-in Catalog

The catalog is loaded once when the first JAXP processor factory is created.

External Resource Resolution Process with the built-in Catalog

XML processors may use resolvers (such as EntityResolver, XMLResolver, and CatalogResolver) to handle external references. In the absence of the user-defined resolvers, the JDK XML processors fall back to the default CatalogResolver to attempt to find a resolution before making a connection to fetch the resources. The fall-back also takes place if a user-defined resolver exists but allows the process to continue when unable to resolve the resource.

If the default CatalogResolver is unable to locate a resource, it may signal the XML processors to continue processing, or skip the resource, or throw a CatalogException. The behavior is configured with the jdk.xml.jdkcatalog.resolve property.

Implementation Specific Properties

Refer to the Implementation Specific Properties table for the list of properties supported by the JDK implementation.

Processor Support

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

[2] A value "yes" indicates there is a corresponding System Property for the property, "no" otherwise. The name of the System Property is the same as that of the property.

[3] 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).

[4] A value "yes" indicates the property is a Security Property. As indicated in the Property Precedence, the values listed in the column enforced will be used to initialize these properties when FSP is true.

[5] One or more processors that support the property. The IDs and Set Method are as shown in the table Processors.

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

[7] The jdk.xml.dtd.support property complements the two existing DTD-related properties, disallow-doctype-decl(fully qualified name: http://apache.org/xml/features/disallow-doctype-decl) and supportDTD (javax.xml.stream.supportDTD), by providing a uniformed support for the processors listed and a system property that can be used in the JAXP Configuration File. When disallow-doctype-decl is set on the DOM or SAX factory, or supportDTD on StAX factory, the jdk.xml.dtd.support property will have no effect.

These three properties control whether DTDs as a whole shall be processed. When they are set to deny or ignore, other properties that regulate a part or an aspect of DTD shall have no effect.

Legacy Property Names (deprecated)

• Value set on factories or processors using new property names.
• Value set on factories or processors using legacy property names;
• Value set as System Property;
• Value set in the configuration file;
• Value set by FEATURE_SECURE_PROCESSING;
• The default value;

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