Module java.xml

Defines the Java APIs for XML Processing (JAXP).

• 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

JAXP comprises a set of APIs built upon a number of XML technologies and standards that are essential for XML processing. These include APIs for:

• 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

Factories are the entry points of each API, providing methods to allow applications to set JAXP Properties programmatically, before creating processors. The Configuration section provides more details on this. Factories also support the JAXP Lookup Mechanism, in which applications can be deployed with third party implementations to use instead of JDK implementations

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

When a JAXP factory is invoked for the first time, it performs a configuration process to determine the implementation to be used and its subsequent behaviors. During configuration, the factory examines configuration sources such as the JAXP Properties, System Properties, and the JAXP Configuration File, and sets the values following the Property Precedence. The terminologies and process are defined below.

JAXP Properties

JAXP properties are configuration settings that are applied to XML processors. They can be used to control and customize the behavior of a processor. Depending on the JAXP API that is being used, JAXP properties may be referred to as Attributes, Properties , or Features .

System Properties

Select JAXP properties have corresponding System Properties allowing the properties to be set at runtime, on the command line, or within the JAXP Configuration File. For example, the System Property javax.xml.catalog.resolve may be used to set the CatalogFeatures ' RESOLVE property.

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

JAXP supports the use of configuration files for specifying the implementation class to load for the JAXP factories as well as for setting JAXP properties.

Configuration files are Java 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:

jaxp.properties File

By default, JAXP looks for the configuration file jaxp.properties , located in the ${java.home}/conf directory; and if the file exists, loads the specified properties to customize the behavior of the XML factories and processors.

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

In addition to the jaxp.properties file, the system property java.xml.config.file can be set to specify the location of a configuration file. If the java.xml.config.file property is included within a configuration file, it will be ignored.

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

JAXP properties can be set in multiple ways, including by API methods, system properties, and the JAXP Configuration File. When not explicitly set, they will be initialized with default values or more restrictive values when FEATURE_SECURE_PROCESSING (FSP) is enabled. The configuration order of precedence for properties is as follows, from highest to lowest:

• 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.

Using the CatalogFeatures ' RESOLVE property as an example, the following illustrates how these rules are applied:

• 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.

  Copy

     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.

  Copy

      // 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 '.

  Copy

      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

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, and System Default method to be used in the procedure.

JAXP Factories

Factory	Method	System Property	System Default
DatatypeFactory	newInstance()	javax.xml.datatype.DatatypeFactory	newDefaultInstance()
DocumentBuilderFactory	newInstance()	javax.xml.parsers.DocumentBuilderFactory	newDefaultInstance()
SAXParserFactory	newInstance()	javax.xml.parsers.SAXParserFactory	newDefaultInstance()
XMLEventFactory	newFactory()	javax.xml.stream.XMLEventFactory	newDefaultFactory()
XMLInputFactory	newFactory()	javax.xml.stream.XMLInputFactory	newDefaultFactory()
XMLOutputFactory	newFactory()	javax.xml.stream.XMLOutputFactory	newDefaultFactory()
TransformerFactory	newInstance()	javax.xml.transform.TransformerFactory	newDefaultInstance()
SchemaFactory	newInstance(schemaLanguage)	javax.xml.validation.SchemaFactory: schemaLanguage[1]	newDefaultInstance()
XPathFactory	newInstance(uri)	DEFAULT_PROPERTY_NAME + ":uri"[2]	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 order of precedence for locating the implementation class of a JAXP Factory is as follows, from highest to lowest:

• 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 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 .