org.w3c.dom

Interface DOMConfiguration

Known Implementing Classes:
DomLSParser, DomLSSerializer, GnomeDocument

public interface DOMConfiguration

The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters. Using the configuration, it is possible to change Document.normalizeDocument() behavior, such as replacing the CDATASection nodes with Text nodes or specifying the type of the schema that must be used when the validation of the Document is requested. DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the DOMParser and DOMSerializer interfaces.

The parameter names used by the DOMConfiguration object are defined throughout the DOM Level 3 specifications. Names are case-insensitive. To avoid possible conflicts, as a convention, names referring to parameters defined outside the DOM specification should be made unique. Because parameters are exposed as properties in the , names are recommended to follow the section 5.16 Identifiers of [Unicode] with the addition of the character '-' (HYPHEN-MINUS) but it is not enforced by the DOM implementation. DOM Level 3 Core Implementations are required to recognize all parameters defined in this specification. Some parameter values may also be required to be supported by the implementation. Refer to the definition of the parameter to know if a value must be supported or not.

Note: Parameters are similar to features and properties used in SAX2 [SAX].

The following list of parameters defined in the DOM:

"canonical-form"
true
optionalCanonical XMLDocumentTypetruefalsefalsetrue
false
requireddefault
"cdata-sections"
true
requireddefaultCDATASection
false
requiredCDATASectionTextTextText
"check-character-normalization"
true
optionalfully normalizedXML 1.1DOMError.type
false
requireddefault
"comments"
true
requireddefaultComment
false
requiredComment
"datatype-normalization"
true
optionalXML Schema normalized valuestruefalse

Note:XML 1.0

false
requireddefault
"element-content-whitespace"
true
requireddefault
false
optionalText [element content whitespace]Text.isElementContentWhitespaceText
"entities"
true
requireddefaultEntityReference
false
requiredEntityReferenceTextNode.normalize unexpanded entity references

Note:Entity

"error-handler"
requiredDOMErrorHandlerDOMErrorHandlerDOMErrorHandlerDOMError.relatedDataDOMError.relatedDataDocument
"infoset"
true
requiredXML Information SetfalsetruegetParametertrue
false
infosetfalse
"namespaces"
true
requireddefault
false
optional
"namespace-declarations"
false
true
requireddefaultXML NamespacesXML Namespaces 1.1
false
requiredNode.prefixfalse
"normalize-characters"
true
optionalFully normalizedXML 1.1
false
requireddefault
"schema-location"
optionalDOMStringnonterminal production SXML 1.0schema-typeschemaLocationimporttargetNamespacetargetNamespacenull

Note:"schema-location"Document.documentURI

"schema-type"
optionalDOMStringnull

Note:XML Schema Part 1"http://www.w3.org/2001/XMLSchema"XML 1.0"http://www.w3.org/TR/REC-xml"

"split-cdata-sections"
true
requireddefaultDOMError.type"cdata-sections-splitted"DOMError.relatedDataCDATASection
false
requiredCDATASection
"validate"
true
optionalXML 1.0true
  • Attribute nodes with Attr.specified equals to false, as specified in the description of the Attr interface;
  • The value of the attribute Text.isElementContentWhitespace for all Text nodes;
  • The value of the attribute Attr.isId for all Attr nodes;
  • The attributes Element.schemaTypeInfo and Attr.schemaTypeInfo.

Note:truefalsetrue

false
requireddefaulttrue
"validate-if-schema"
true
optionaltrue

Note:truefalse

false
requireddefaulttrue
"well-formed"
true
requireddefaultDocument.xmlVersion
  • check if the attribute Node.nodeName contains invalid characters according to its node type and generate a DOMError of type "wf-invalid-character-in-node-name", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the text content inside Attr, Element, Comment, Text, CDATASection nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the data inside ProcessingInstruction nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
false
optional

The resolution of the system identifiers associated with entities is done using Document.documentURI. However, when the feature "LS" defined in [DOM Level 3 Load and Save] is supported by the DOM implementation, the parameter "resource-resolver" can also be used on DOMConfiguration objects attached to Document nodes. If this parameter is set, Document.normalizeDocument() will invoke the resource resolver instead of using Document.documentURI.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary

boolean
canSetParameter(String name, Object value)
Check if setting a parameter to a specific value is supported.
Object
getParameter(String name)
Return the value of a parameter if known.
DOMStringList
getParameterNames()
The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application.
void
setParameter(String name, Object value)
Set the value of a parameter.

Method Details

canSetParameter

public boolean canSetParameter(String name,
                               Object value)
Check if setting a parameter to a specific value is supported.
Parameters:
name - The name of the parameter to check.
value - An object. if null, the returned value is true.
Returns:
true if the parameter could be successfully set to the specified value, or false if the parameter is not recognized or the requested value is not supported. This does not change the current value of the parameter itself.

getParameter

public Object getParameter(String name)
            throws DOMException
Return the value of a parameter if known.
Parameters:
name - The name of the parameter.
Returns:
The current object associated with the specified parameter or null if no object has been associated or if the parameter is not supported.
Throws:
DOMException - NOT_FOUND_ERR: Raised when the parameter name is not recognized.

getParameterNames

public DOMStringList getParameterNames()
The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application. Note that this list can also contain parameter names defined outside this specification.

setParameter

public void setParameter(String name,
                         Object value)
            throws DOMException
Set the value of a parameter.
Parameters:
name - The name of the parameter to set.
value - The new value or null if the user wishes to unset the parameter. While the type of the value parameter is defined as DOMUserData, the object type must match the type defined by the definition of the parameter. For example, if the parameter is "error-handler", the value must be of type DOMErrorHandler.
Throws:
DOMException - NOT_FOUND_ERR: Raised when the parameter name is not recognized.
NOT_SUPPORTED_ERR: Raised when the parameter name is recognized but the requested value cannot be set.
TYPE_MISMATCH_ERR: Raised if the value type for this parameter name is incompatible with the expected value type.

* Copyright (c) 2004 World Wide Web Consortium, * * (Massachusetts Institute of Technology, European Research Consortium for * Informatics and Mathematics, Keio University). All Rights Reserved. This * work is distributed under the W3C(r) Software License [1] in the hope that * it will be useful, but WITHOUT ANY WARRANTY; without even the implied * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231