Legacy System Properties

These properties, which were introduced in JDK 5.0 and 6, continue to be supported for backward compatibility.

Values of External Access Restrictions JAXP Properties

All JAXP properties for external access restrictions have values of the same format:

• Value: A list of protocols separated by comma. A protocol is the scheme portion of an URI, or in the case of the JAR protocol, jar plus the scheme portion separated by colon. A scheme is defined as:

  scheme = alpha *( alpha | digit | "+" | "-" | "." )

  where alpha = a-z and A-Z.

  The JAR protocol is defined as: jar[:scheme]

  Protocols are case-insensitive. Any whitespace characters as defined by Character.isSpaceChar in the value are ignored. Examples of protocols are file, http, and jar:file.

• Default value: The default value is implementation specific. For the JDK, the default value is all, which grants permissions to all protocols.

• Granting all access: The keyword all grants permission to all protocols. For example, specifying javax.xml.accessExternalDTD=all in the jaxp.properties file enables a system to work as before with no restrictions on accessing external DTDs and entity references.

• Denying any access: An empty string ("") means that no permission is granted to any protocol. For example, specifying javax.xml.accessExternalDTD="" in the jaxp.properties file instructs JAXP processors to deny any external connections.

Scope of Setting Feature for Secure Processing

Feature for Secure Processing (FSP) is required for XML processors including DOM, SAX, schema validation, XSLT, and XPath.

When FSP is turned on, then default processing limits (see JAXP Properties for Processing Limits) are enforced. Turning off FSP does not change the limits.

When FSP is "explicitly" turned on through the API, for example, factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true), then external access restrictions (see JAXP Properties for External Access Restrictions) are set to the empty string, which means that no permission is granted to any protocol. Although FSP is turned on by default for DOM, SAX and schema validation, it is not treated as if "explicitly" turned on; therefore, the default value for external access restrictions is all, which means that permission is granted to all protocols.

When a Java Security Manager is present, FSP is turned on and cannot be turned off.

Scope and Order of Setting JAXP Properties

In general, JAXP properties set in a smaller scope override those in a larger one:

• JAXP properties specified through JAXP factories or processors take preference over System properties, the jaxp.properties file, and FSP.
• System properties, when set, affect one JDK invocation only and override processing limit and external access restriction values set by default, set in the jaxp.properties file, or set by FSP.
• Properties specified in the jaxp.properties file affect the entire JDK and override processing limit and external access restriction values set by default or set by FSP.

Scope of Setting External Access Restrictions

External access restrictions have no effect on the relevant constructs that they attempt to restrict in the following situations:

• When there is a resolver and the source returned by the resolver is not null: This applies to entity resolvers that may be set on SAX and DOM parsers, XML resolvers on StAX parsers, LSResourceResolver on SchemaFactory, a Validator or ValidatorHandler, or URIResolver on a transformer.

• When a schema is created explicitly by calling the newSchema method from SchemaFactory.

• When external resources are not required: For example, the following features and properties are supported by the JDK and may be used to instruct the processor to not load the external DTD or resolve external entities:

  http://apache.org/xml/features/disallow-doctype-decl true
  http://apache.org/xml/features/nonvalidating/load-external-dtd false
  http://xml.org/sax/features/external-general-entities false
  http://xml.org/sax/features/external-parameter-entities false

Memory Setting and Limits

XML processing can be very memory intensive. The amount of memory that should be allowed to be consumed depends on the requirements of the applications in a specific environment. Processing of malformed XML data must be prevented from consuming excessive memory.

The default limits are generally set to allow legitimate XML inputs for most applications with memory usage allowed for a small hardware system, such as a PC. It is recommended that the limits are set to the smallest possible values, so that any malformed input can be caught before it consumes large amounts of memory.

The limits are correlated, but not entirely redundant. You should set appropriate values for all of the limits: usually the limits should be set to a much smaller value than the default.

For example, ENTITY_EXPANSION_LIMIT and GENERAL_ENTITY_SIZE_LIMIT can be set to prevent excessive entity references. But when the exact combination of the expansion and entity sizes are unknown, TOTAL_ENTITY_SIZE_LIMIT can serve as a overall control. Similarly, while TOTAL_ENTITY_SIZE_LIMIT controls the total size of a replacement text, if the text is a very large chunk of XML, ENTITY_REPLACEMENT_LIMIT sets a restriction on the total number of nodes that can appear in the text and prevents overloading the system.

Estimating the Limits Using the getEntityCountInfo Property

To help you analyze what values you should set for the limits, a special property called http://www.oracle.com/xml/jaxp/properties/getEntityCountInfo is available. The following code snippet, from Processing Limit Samples in The Java Tutorials, shows an example of using the property:

    public static final String ORACLE_JAXP_PROPERTY_PREFIX =
        "http://www.oracle.com/xml/jaxp/properties/";
    // ...
    public static final String JDK_ENTITY_COUNT_INFO = 
        ORACLE_JAXP_PROPERTY_PREFIX + "getEntityCountInfo";
    // ...
    parser.setProperty(JDK_ENTITY_COUNT_INFO, "yes");

When you run the processing limit sample with the DTD in W3C MathML 3.0, it prints out the following table:

In this example, the total number of entity references, or the entity expansion, is 1417; the default limit is 64000. The total size of all entities is 55425; the default limit is 50000000. The biggest parameter entity is %MultiScriptExpression with a length of 7303 after all references are resolved; the default limit is 1000000.

If this is the largest file that the application is expected to process, it is recommended that the limits be set to smaller numbers. For example, 2000 for ENTITY_EXPANSION_LIMIT, 100000 for TOTAL_ENTITY_SIZE_LIMIT, and 10000 for PARAMETER_ENTITY_SIZE_LIMIT.

Setting Properties Through JAXP Factories

If you can modify your application's code, or you're creating a new application, then setting JAXP properties through JAXP factories or a parser is the preferred method. Set these properties through the following interfaces:

    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
    dbf.setAttribute(name, value);
 
    SAXParserFactory spf = SAXParserFactory.newInstance();
    SAXParser parser = spf.newSAXParser();
    parser.setProperty(name, value);
 
    XMLInputFactory xif = XMLInputFactory.newInstance();
    xif.setProperty(name, value);
 
    SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);
    schemaFactory.setProperty(name, value);
 
    TransformerFactory factory = TransformerFactory.newInstance();
    factory.setAttribute(name, value);

The following is an example of setting processing limits:

    dbf.setAttribute(JDK_ENTITY_EXPANSION_LIMIT, "2000");
    dbf.setAttribute(TOTAL_ENTITY_SIZE_LIMIT, "100000");
    dbf.setAttribute(PARAMETER_ENTITY_SIZE_LIMIT, "10000"); 
    dbf.setAttribute(JDK_MAX_ELEMENT_DEPTH, "100");

The following is an example of limiting a DOM parser to only local connections for external DTDs:

    dbf.setAttribute(XMLConstants.ACCESS_EXTERNAL_DTD, "file, jar:file");

If a parser module within the application handles untrusted sources, it may further restrict access. The following code overrides those in the jaxp.properties file and those specified by System properties and enables the XML processor to read local files only:

    DocumentBuilderFactory dbf =
    DocumentBuilderFactory.newInstance();   
    dbf.setAttribute(XMLConstants.ACCESS_EXTERNAL_DTD, "file");
    // ...   
    SchemaFactory schemaFactory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);   
    schemaFactory.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, "file");   
    schemaFactory.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, "file");

As described in Scope and Order of Setting JAXP Properties, JAXP properties specified through JAXP factories have the narrowest scope, affecting only the processors created by the factories, and therefore override any default settings, System properties, and those in the jaxp.properties file. By setting JAXP properties through JAXP factories, you can ensure that your applications behave the same way regardless of which JDK release you're using or whether JAXP properties are set through other means.

Using System Properties

System properties may be useful if you can't modify your application's code.

To set JAXP properties for an entire JDK invocation, set their corresponding System properties on the command line.

To set JAXP properties for only a portion of the application, set their corresponding System properties before the portion, and then clear them afterward. For example, if your application requires access to external DTDs and schemas, then add these lines to your application's initialization code block:

    System.setProperty("javax.xml.accessExternalDTD", "file, http");
    System.setProperty("javax.xml.accessExternalSchema", "file, http");

Then, once your application is done processing XML documents or before it exits, clear out the properties as follows:

    System.clearProperty("javax.xml.accessExternalDTD");   
    System.clearProperty("javax.xml.accessExternalSchema");

The following code, from Processing Limit Samples in The Java Tutorials, is another example that shows how to do this for the processing limit maxGeneralEntitySizeLimit:

    public static final String SP_GENERAL_ENTITY_SIZE_LIMIT =
        "jdk.xml.maxGeneralEntitySizeLimit";

    // Set limits using System property;
    // this setting will affect all processing after it's set
    System.setProperty(SP_GENERAL_ENTITY_SIZE_LIMIT, "2000");

    // Perform some processing here

    // After it is done, clear the property
    System.clearProperty(SP_GENERAL_ENTITY_SIZE_LIMIT);

Note that processing limit values are integers. A NumberFormatException is thrown if a processing limit's value is not a parsable integer; see the method java.lang.Integer.parseInt(String).

The following example allows the resolution of external schemas for a portion of an application:

    // Allow resolution of external schemas
    // This setting will affect all processing after it's set
    System.setProperty("javax.xml.accessExternalSchema", "file, http");

    // Perform some processing here

    // After it's done, clear the property
    System.clearProperty("javax.xml.accessExternalSchema");

Using the jaxp.properties File

If you want to specify a JAXP property that affects every JDK invocation, then create a configuration file named <java-home>/conf/jaxp.properties and specify names and values of JAXP properties in it, one name-value pair on each line. For example, the following jaxp.properties file sets the maxGeneralEntitySizeLimit processing limit property to 2000 and restricts access to the file and HTTP protocols for external references set by the stylesheet processing instruction, document function, and the import and include elements.

jdk.xml.maxGeneralEntitySizeLimit=2000
javax.xml.accessExternalStylesheet=file, http

If you don't want to allow any external connection by XML processors, you can set all access external restrictions to file only:

javax.xml.accessExternalDTD=file
javax.xml.accessExternalSchema=file
javax.xml.accessExternalStylesheet=file

If you want to prevent applications from accidentally reading external files through an XML processor, set the external access restrictions as follows in the jaxp.properties file as follows:

javax.xml.accessExternalDTD=""   
javax.xml.accessExternalSchema=""   
javax.xml.accessExternalStylesheet=""

StAX and Processing Limits

JDK's StAX implementation supports processing limits and their corresponding System properties. However, because FSP is not supported, you can't turn on or off processing limits for StAX by turning on or off FSP. Processing limits continue to behave as described in JAXP Properties for Processing Limits.

StAX and External Access Restrictions

JDK's StAX implementation supports the JAXP properties related to external access restrictions. Setting them is similar to SAX or DOM, but through the XMLInputFactory class, for example:

    XMLInputFactory xif = XMLInputFactory.newInstance();
    xif.setProperty(
        "http://javax.xml.XMLConstants/property/accessExternalDTD",
        "file");

For compatibility, StAX properties and features take precedence over the processing limit and external access restriction properties. For example, the SupportDTD property, when set to false, causes a program to throw an exception when an input file contains a DTD before it can be parsed. Therefore, processing limits and external access restrictions on DTDs will have no effect on applications that have disabled by setting SupportDTD property to false.