|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
DOM Level 3 WD Experimental: 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 DOMBuilder and
DOMWriter interfaces.
The DOMConfiguration distinguish two types of parameters:
boolean (boolean parameters) and DOMUserData
(parameters). The names used by the DOMConfiguration object
are defined throughout the DOM Level 3 specifications. Names are
case-insensitives. To avoid possible conflicts, as a convention, names
referring to boolean parameters and parameters defined outside the DOM
specification should be made unique. Names are recommended to follow the
XML name production rule but it is not enforced by the DOM
implementation. DOM Level 3 Core Implementations are required to
recognize all boolean parameters and parameters defined in this
specification. Each boolean parameter state or parameter value may then
be supported or not by the implementation. Refer to their definition to
know if a state or a value must be supported or not. Parameters are
similar to features and properties used in SAX2 [SAX]. Can we rename boolean
parameters to "flags"? Are boolean parameters and parameters within the
same scope for uniqueness? Which exception should be raised by
setBooleanParameter("error-handler", true)?
The following list of parameters defined in the DOM:
"error-handler"DOMErrorHandler
object. If an error is encountered in the document, the implementation
will call back the DOMErrorHandler registered using this
parameter. When called, DOMError.relatedData will contain
the closest node to where the error occured. If the implementation is
unable to determine the node where the error occurs,
DOMError.relatedData will contain the Document
node. Mutations to the document from within an error handler will result
in implementation dependent behaviour. Should we say non "readonly"
operations are implementation dependent instead? Removed: "or
re-invoking a validation operation". "schema-type"DOMString object containing an absolute URI and
representing the type of the schema language used to validate a document
against. Note that no lexical checking is done on the absolute URI. If
this parameter is not set, a default value may be provided by the
implementation, based on the schema languages supported and on the schema
language used at load time. For XML Schema [XML Schema Part 1], applications must use the
value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0],
applications must use the value
"http://www.w3.org/TR/REC-xml". Other schema languages are
outside the scope of the W3C and therefore should recommend an absolute
URI in order to use this method. "schema-location"DOMString object containing a list of URIs, separated by
white spaces (characters matching the nonterminal production S defined in
section 2.3 [XML 1.0]), that represents the schemas against which validation
should occur. The types of schemas referenced in this list must match the
type specified with schema-type, otherwise the behaviour of
an implementation is undefined. If the schema type is XML Schema [XML Schema Part 1], only
one of the XML Schemas in the list can be with no namespace. If
validation occurs against a namespace aware schema, i.e. XML Schema, and
the targetNamespace of a schema (specified using this property) matches
the targetNamespace of a schema occurring in the instance document, i.e
in schemaLocation attribute, the schema specified by the user using this
property will be used (i.e., in XML Schema the schemaLocation
attribute in the instance document or on the import element
will be effectively ignored). It is illegal to set the schema-location
parameter if the schema-type parameter value is not set. It is strongly
recommended that DOMInputSource.baseURI will be set, so that
an implementation can successfully resolve any external entities
referenced. The following list of boolean parameters (features) defined in the DOM:
"canonical-form"truefalse"cdata-sections"trueCDATASection nodes in the document.Name does not work
really well in this case. ALH suggests renaming this to "cdata-sections".
It works for both load and save.Renamed as suggested. (Telcon 27 Jan
2002).falseCDATASection
nodes in the document into Text nodes. The new
Text node is then combined with any adjacent
Text node."comments"trueComment nodes in the document.falseComment nodes in the
Document."datatype-normalization"truefalse"discard-default-content"truespecified flag on Attr nodes,
and so on) to decide what attributes and content should be discarded or
not. Note that the specified flag on Attr nodes
in itself is not always reliable, it is only reliable when it is set to
false since the only case where it can be set to
false is if the attribute was created by the implementation.
The default content won't be removed if an implementation does not have
any information available.How does exactly work? What's the comment about
level 1 implementations?Remove "Level 1" (Telcon 16 Jan 2002).false"entities"trueEntityReference and Entity nodes in the
document.How does that interact with expand-entity-references? ALH
suggests consolidating the two to a single feature called
"entity-references" that is used both for load and save.Consolidate both
features into a single feature called 'entities'. (Telcon 27 Jan 2002).falseEntityReference and Entity nodes from the
document, putting the entity expansions directly in their place.
Text nodes are into "normal" form. Only
EntityReference nodes to non-defined entities are kept in
the document."infoset"truefalse:
namespace-declarations, validate-if-schema,
entities, datatype-normalization,
cdata-sections.This forces the following features to
true: whitespace-in-element-content,
comments, namespaces.Other features are not
changed unless explicity specified in the description of the features.
Note that querying this feature with getFeature returns
true only if the individual features specified above are
appropriately set.Name doesn't work well here. ALH suggests renaming this
to limit-to-infoset or match-infoset, something like that.Renamed
'infoset' (Telcon 27 Jan 2002).falseinfoset to false has no effect.Shouldn't we
change this to setting the relevant options back to their default value?
No, this is more like a convenience function, it's better to keep it
simple. (F2F 28 Feb 2002)."namespaces"truefalse"namespace-declarations"truefalsefalse."normalize-characters"truefalse"split-cdata-sections"truefalseCDATASection contains an unrepresentable character."validate"truedatatype-normalization is true.
validate-if-schema and validate are mutually
exclusive, setting one of them to true will set the other
one to false. falsevalidate-if-schema is true
. "validate-if-schema"truedatatype-normalization is true.
validate-if-schema and validate are mutually
exclusive, setting one of them to true will set the other
one to false. falsevalidate is true
. "whitespace-in-element-content"true"validate" and
Text.isWhitespaceInElementContent. issue no longer relevant
(f2f october 2002).falseisWhitespaceInElementContent flag on Text
nodes to determine if a text node should be written out or not. The resolutions of entities is done using Document.baseURI
. However, when the features "LS-Load" or "LS-Save" defined in [DOM Level 3 Load and Save] are
supported by the DOM implementation, the parameter
"entity-resolver" can also be used on
DOMConfiguration objects attached to Document
nodes. If this parameter is set, Document.normalizeDocument
will invoke the entity resolver instead of using
Document.baseURI.
See also the Document Object Model (DOM) Level 3 Core Specification.
| Method Summary | |
boolean |
canSetParameter(java.lang.String name,
java.lang.Object value)
Check if setting a parameter to a specific value is supported. |
java.lang.Object |
getParameter(java.lang.String name)
Return the value of a parameter if known. |
void |
setParameter(java.lang.String name,
java.lang.Object value)
Set the value of a parameter. |
| Method Detail |
public void setParameter(java.lang.String name,
java.lang.Object value)
throws org.w3c.dom.DOMException
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. Should we allow implementations
to raise exception if the type does not match? INVALID_ACCESS_ERR
seems the closest exception code...org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised when the parameter name is recognized but
the requested value cannot be set.
public java.lang.Object getParameter(java.lang.String name)
throws org.w3c.dom.DOMException
name - The name of the parameter.null if no object has been associated or if the
parameter is not supported. "by a DOM application" prevents a DOM
implementation to return its default behavior (such as the default
"schema-type") if any.org.w3c.dom.DOMException - NOT_FOUND_ERR: Raised when the parameter name is not recognized.
public boolean canSetParameter(java.lang.String name,
java.lang.Object value)
name - The name of the parameter to check.value - An object. if null, the returned value is
true.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.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||