1/* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25/* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file and, per its terms, should not be removed: 30 * 31 * Copyright (c) 2004 World Wide Web Consortium, 32 * 33 * (Massachusetts Institute of Technology, European Research Consortium for 34 * Informatics and Mathematics, Keio University). All Rights Reserved. This 35 * work is distributed under the W3C(r) Software License [1] in the hope that 36 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 37 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 38 * 39 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 40 */ 41 42package org.w3c.dom; 43 44/** 45 * The <code>DOMConfiguration</code> interface represents the configuration 46 * of a document and maintains a table of recognized parameters. Using the 47 * configuration, it is possible to change 48 * <code>Document.normalizeDocument()</code> behavior, such as replacing the 49 * <code>CDATASection</code> nodes with <code>Text</code> nodes or 50 * specifying the type of the schema that must be used when the validation 51 * of the <code>Document</code> is requested. <code>DOMConfiguration</code> 52 * objects are also used in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>DOM Level 3 Load and Save</a>] 53 * in the <code>DOMParser</code> and <code>DOMSerializer</code> interfaces. 54 * <p> The parameter names used by the <code>DOMConfiguration</code> object 55 * are defined throughout the DOM Level 3 specifications. Names are 56 * case-insensitive. To avoid possible conflicts, as a convention, names 57 * referring to parameters defined outside the DOM specification should be 58 * made unique. Because parameters are exposed as properties in names 59 * are recommended to follow the section 5.16 Identifiers of [Unicode] with the addition of the character '-' (HYPHEN-MINUS) but it is not 60 * enforced by the DOM implementation. DOM Level 3 Core Implementations are 61 * required to recognize all parameters defined in this specification. Some 62 * parameter values may also be required to be supported by the 63 * implementation. Refer to the definition of the parameter to know if a 64 * value must be supported or not. 65 * <p ><b>Note:</b> Parameters are similar to features and properties used in 66 * SAX2 [<a href='http://www.saxproject.org/'>SAX</a>]. 67 * <p> The following list of parameters defined in the DOM: 68 * <dl> 69 * <dt> 70 * <code>"canonical-form"</code></dt> 71 * <dd> 72 * <dl> 73 * <dt><code>true</code></dt> 74 * <dd>[<em>optional</em>] Canonicalize the document according to the rules specified in [<a href='http://www.w3.org/TR/2001/REC-xml-c14n-20010315'>Canonical XML</a>], 75 * such as removing the <code>DocumentType</code> node (if any) from the 76 * tree, or removing superfluous namespace declarations from each element. 77 * Note that this is limited to what can be represented in the DOM; in 78 * particular, there is no way to specify the order of the attributes in the 79 * DOM. In addition, Setting this parameter to <code>true</code> will also 80 * set the state of the parameters listed below. Later changes to the state 81 * of one of those parameters will revert "canonical-form" back to 82 * <code>false</code>. Parameters set to <code>false</code>: "entities", " 83 * normalize-characters", "cdata-sections". Parameters set to 84 * <code>true</code>: "namespaces", "namespace-declarations", "well-formed", 85 * "element-content-whitespace". Other parameters are not changed unless 86 * explicitly specified in the description of the parameters.</dd> 87 * <dt> 88 * <code>false</code></dt> 89 * <dd>[<em>required</em>] (<em>default</em>)Do not canonicalize the document.</dd> 90 * </dl></dd> 91 * <dt><code>"cdata-sections"</code></dt> 92 * <dd> 93 * <dl> 94 * <dt> 95 * <code>true</code></dt> 96 * <dd>[<em>required</em>] (<em>default</em>)Keep <code>CDATASection</code> nodes in the document.</dd> 97 * <dt><code>false</code></dt> 98 * <dd>[<em>required</em>]Transform <code>CDATASection</code> nodes in the document into 99 * <code>Text</code> nodes. The new <code>Text</code> node is then combined 100 * with any adjacent <code>Text</code> node.</dd> 101 * </dl></dd> 102 * <dt> 103 * <code>"check-character-normalization"</code></dt> 104 * <dd> 105 * <dl> 106 * <dt><code>true</code></dt> 107 * <dd>[<em>optional</em>] Check if the characters in the document are <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>fully 108 * normalized</a>, as defined in appendix B of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. When a 109 * sequence of characters is encountered that fails normalization checking, 110 * an error with the <code>DOMError.type</code> equals to 111 * "check-character-normalization-failure" is issued. </dd> 112 * <dt><code>false</code></dt> 113 * <dd>[<em>required</em>] (<em>default</em>)Do not check if characters are normalized.</dd> 114 * </dl></dd> 115 * <dt><code>"comments"</code></dt> 116 * <dd> 117 * <dl> 118 * <dt> 119 * <code>true</code></dt> 120 * <dd>[<em>required</em>] (<em>default</em>)Keep <code>Comment</code> nodes in the document.</dd> 121 * <dt><code>false</code></dt> 122 * <dd>[<em>required</em>]Discard <code>Comment</code> nodes in the document.</dd> 123 * </dl></dd> 124 * <dt> 125 * <code>"datatype-normalization"</code></dt> 126 * <dd> 127 * <dl> 128 * <dt><code>true</code></dt> 129 * <dd>[<em>optional</em>] Expose schema normalized values in the tree, such as <a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/#key-nv'>XML 130 * Schema normalized values</a> in the case of XML Schema. Since this parameter requires to have schema 131 * information, the "validate" parameter will also be set to 132 * <code>true</code>. Having this parameter activated when "validate" is 133 * <code>false</code> has no effect and no schema-normalization will happen. 134 * <p ><b>Note:</b> Since the document contains the result of the XML 1.0 135 * processing, this parameter does not apply to attribute value 136 * normalization as defined in section 3.3.3 of [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] and is only 137 * meant for schema languages other than Document Type Definition (DTD). </dd> 138 * <dt> 139 * <code>false</code></dt> 140 * <dd>[<em>required</em>] (<em>default</em>) Do not perform schema normalization on the tree. </dd> 141 * </dl></dd> 142 * <dt> 143 * <code>"element-content-whitespace"</code></dt> 144 * <dd> 145 * <dl> 146 * <dt><code>true</code></dt> 147 * <dd>[<em>required</em>] (<em>default</em>)Keep all whitespaces in the document.</dd> 148 * <dt><code>false</code></dt> 149 * <dd>[<em>optional</em>] Discard all <code>Text</code> nodes that contain whitespaces in element 150 * content, as described in <a href='http://www.w3.org/TR/2004/REC-xml-infoset-20040204#infoitem.character'> 151 * [element content whitespace]</a>. The implementation is expected to use the attribute 152 * <code>Text.isElementContentWhitespace</code> to determine if a 153 * <code>Text</code> node should be discarded or not.</dd> 154 * </dl></dd> 155 * <dt><code>"entities"</code></dt> 156 * <dd> 157 * <dl> 158 * <dt> 159 * <code>true</code></dt> 160 * <dd>[<em>required</em>] (<em>default</em>)Keep <code>EntityReference</code> nodes in the document.</dd> 161 * <dt> 162 * <code>false</code></dt> 163 * <dd>[<em>required</em>] Remove all <code>EntityReference</code> nodes from the document, 164 * putting the entity expansions directly in their place. <code>Text</code> 165 * nodes are normalized, as defined in <code>Node.normalize</code>. Only <a href='http://www.w3.org/TR/2004/REC-xml-infoset-20040204/#infoitem.rse'> 166 * unexpanded entity references</a> are kept in the document. </dd> 167 * </dl> 168 * <p ><b>Note:</b> This parameter does not affect <code>Entity</code> nodes. </dd> 169 * <dt> 170 * <code>"error-handler"</code></dt> 171 * <dd>[<em>required</em>] Contains a <code>DOMErrorHandler</code> object. If an error is 172 * encountered in the document, the implementation will call back the 173 * <code>DOMErrorHandler</code> registered using this parameter. The 174 * implementation may provide a default <code>DOMErrorHandler</code> object. 175 * When called, <code>DOMError.relatedData</code> will contain the closest 176 * node to where the error occurred. If the implementation is unable to 177 * determine the node where the error occurs, 178 * <code>DOMError.relatedData</code> will contain the <code>Document</code> 179 * node. Mutations to the document from within an error handler will result 180 * in implementation dependent behavior. </dd> 181 * <dt><code>"infoset"</code></dt> 182 * <dd> 183 * <dl> 184 * <dt> 185 * <code>true</code></dt> 186 * <dd>[<em>required</em>]Keep in the document the information defined in the XML Information Set [<a href='http://www.w3.org/TR/2004/REC-xml-infoset-20040204/'>XML Information Set</a>] 187 * .This forces the following parameters to <code>false</code>: " 188 * validate-if-schema", "entities", "datatype-normalization", "cdata-sections 189 * ".This forces the following parameters to <code>true</code>: " 190 * namespace-declarations", "well-formed", "element-content-whitespace", " 191 * comments", "namespaces".Other parameters are not changed unless 192 * explicitly specified in the description of the parameters. Note that 193 * querying this parameter with <code>getParameter</code> returns 194 * <code>true</code> only if the individual parameters specified above are 195 * appropriately set.</dd> 196 * <dt><code>false</code></dt> 197 * <dd>Setting <code>infoset</code> to 198 * <code>false</code> has no effect.</dd> 199 * </dl></dd> 200 * <dt><code>"namespaces"</code></dt> 201 * <dd> 202 * <dl> 203 * <dt> 204 * <code>true</code></dt> 205 * <dd>[<em>required</em>] (<em>default</em>) Perform the namespace processing as defined in . </dd> 206 * <dt><code>false</code></dt> 207 * <dd>[<em>optional</em>] Do not perform the namespace processing. </dd> 208 * </dl></dd> 209 * <dt> 210 * <code>"namespace-declarations"</code></dt> 211 * <dd> This parameter has no effect if the 212 * parameter "namespaces" is set to <code>false</code>. 213 * <dl> 214 * <dt><code>true</code></dt> 215 * <dd>[<em>required</em>] (<em>default</em>) Include namespace declaration attributes, specified or defaulted from 216 * the schema, in the document. See also the sections "Declaring Namespaces" 217 * in [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 218 * and [<a href='http://www.w3.org/TR/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>] 219 * .</dd> 220 * <dt><code>false</code></dt> 221 * <dd>[<em>required</em>]Discard all namespace declaration attributes. The namespace prefixes ( 222 * <code>Node.prefix</code>) are retained even if this parameter is set to 223 * <code>false</code>.</dd> 224 * </dl></dd> 225 * <dt><code>"normalize-characters"</code></dt> 226 * <dd> 227 * <dl> 228 * <dt><code>true</code></dt> 229 * <dd>[<em>optional</em>] <a href='http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm'>Fully 230 * normalized</a> the characters in the document as defined in appendix B of [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. </dd> 231 * <dt> 232 * <code>false</code></dt> 233 * <dd>[<em>required</em>] (<em>default</em>)Do not perform character normalization.</dd> 234 * </dl></dd> 235 * <dt><code>"schema-location"</code></dt> 236 * <dd>[<em>optional</em>] Represent a <code>DOMString</code> object containing a list of URIs, 237 * separated by whitespaces (characters matching the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-S'>nonterminal 238 * production S</a> defined in section 2.3 [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]), that 239 * represents the schemas against which validation should occur, i.e. the 240 * current schema. The types of schemas referenced in this list must match 241 * the type specified with <code>schema-type</code>, otherwise the behavior 242 * of an implementation is undefined. The schemas specified using this 243 * property take precedence to the schema information specified in the 244 * document itself. For namespace aware schema, if a schema specified using 245 * this property and a schema specified in the document instance (i.e. using 246 * the <code>schemaLocation</code> attribute) in a schema document (i.e. 247 * using schema <code>import</code> mechanisms) share the same 248 * <code>targetNamespace</code>, the schema specified by the user using this 249 * property will be used. If two schemas specified using this property share 250 * the same <code>targetNamespace</code> or have no namespace, the behavior 251 * is implementation dependent. If no location has been provided, this 252 * parameter is <code>null</code>. 253 * <p ><b>Note:</b> The <code>"schema-location"</code> parameter is ignored 254 * unless the "schema-type" parameter value is set. It is strongly 255 * recommended that <code>Document.documentURI</code> will be set so that an 256 * implementation can successfully resolve any external entities referenced. </dd> 257 * <dt> 258 * <code>"schema-type"</code></dt> 259 * <dd>[<em>optional</em>] Represent a <code>DOMString</code> object containing an absolute URI 260 * and representing the type of the schema language used to validate a 261 * document against. Note that no lexical checking is done on the absolute 262 * URI. If this parameter is not set, a default value may be provided by 263 * the implementation, based on the schema languages supported and on the 264 * schema language used at load time. If no value is provided, this 265 * parameter is <code>null</code>. 266 * <p ><b>Note:</b> For XML Schema [<a href='http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/'>XML Schema Part 1</a>] 267 * , applications must use the value 268 * <code>"http://www.w3.org/2001/XMLSchema"</code>. For XML DTD [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>], 269 * applications must use the value 270 * <code>"http://www.w3.org/TR/REC-xml"</code>. Other schema languages are 271 * outside the scope of the W3C and therefore should recommend an absolute 272 * URI in order to use this method. </dd> 273 * <dt><code>"split-cdata-sections"</code></dt> 274 * <dd> 275 * <dl> 276 * <dt> 277 * <code>true</code></dt> 278 * <dd>[<em>required</em>] (<em>default</em>)Split CDATA sections containing the CDATA section termination marker 279 * ']]>'. When a CDATA section is split a warning is issued with a 280 * <code>DOMError.type</code> equals to 281 * <code>"cdata-sections-splitted"</code> and 282 * <code>DOMError.relatedData</code> equals to the first 283 * <code>CDATASection</code> node in document order resulting from the split.</dd> 284 * <dt> 285 * <code>false</code></dt> 286 * <dd>[<em>required</em>]Signal an error if a <code>CDATASection</code> contains an 287 * unrepresentable character.</dd> 288 * </dl></dd> 289 * <dt><code>"validate"</code></dt> 290 * <dd> 291 * <dl> 292 * <dt><code>true</code></dt> 293 * <dd>[<em>optional</em>] Require the validation against a schema (i.e. XML schema, DTD, any 294 * other type or representation of schema) of the document as it is being 295 * normalized as defined by [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. If 296 * validation errors are found, or no schema was found, the error handler is 297 * notified. Schema-normalized values will not be exposed according to the 298 * schema in used unless the parameter "datatype-normalization" is 299 * <code>true</code>. This parameter will reevaluate: 300 * <ul> 301 * <li> Attribute nodes with 302 * <code>Attr.specified</code> equals to <code>false</code>, as specified in 303 * the description of the <code>Attr</code> interface; 304 * </li> 305 * <li> The value of the 306 * attribute <code>Text.isElementContentWhitespace</code> for all 307 * <code>Text</code> nodes; 308 * </li> 309 * <li> The value of the attribute 310 * <code>Attr.isId</code> for all <code>Attr</code> nodes; 311 * </li> 312 * <li> The attributes 313 * <code>Element.schemaTypeInfo</code> and <code>Attr.schemaTypeInfo</code>. 314 * </li> 315 * </ul> 316 * <p ><b>Note:</b> "validate-if-schema" and "validate" are mutually 317 * exclusive, setting one of them to <code>true</code> will set the other 318 * one to <code>false</code>. Applications should also consider setting the 319 * parameter "well-formed" to <code>true</code>, which is the default for 320 * that option, when validating the document. </dd> 321 * <dt><code>false</code></dt> 322 * <dd>[<em>required</em>] (<em>default</em>) Do not accomplish schema processing, including the internal subset 323 * processing. Default attribute values information are kept. Note that 324 * validation might still happen if "validate-if-schema" is <code>true</code> 325 * . </dd> 326 * </dl></dd> 327 * <dt><code>"validate-if-schema"</code></dt> 328 * <dd> 329 * <dl> 330 * <dt><code>true</code></dt> 331 * <dd>[<em>optional</em>]Enable validation only if a declaration for the document element can be 332 * found in a schema (independently of where it is found, i.e. XML schema, 333 * DTD, or any other type or representation of schema). If validation is 334 * enabled, this parameter has the same behavior as the parameter "validate" 335 * set to <code>true</code>. 336 * <p ><b>Note:</b> "validate-if-schema" and "validate" are mutually 337 * exclusive, setting one of them to <code>true</code> will set the other 338 * one to <code>false</code>. </dd> 339 * <dt><code>false</code></dt> 340 * <dd>[<em>required</em>] (<em>default</em>) No schema processing should be performed if the document has a schema, 341 * including internal subset processing. Default attribute values 342 * information are kept. Note that validation must still happen if "validate 343 * " is <code>true</code>. </dd> 344 * </dl></dd> 345 * <dt><code>"well-formed"</code></dt> 346 * <dd> 347 * <dl> 348 * <dt><code>true</code></dt> 349 * <dd>[<em>required</em>] (<em>default</em>) Check if all nodes are XML well formed according to the XML version in 350 * use in <code>Document.xmlVersion</code>: 351 * <ul> 352 * <li> check if the attribute 353 * <code>Node.nodeName</code> contains invalid characters according to its 354 * node type and generate a <code>DOMError</code> of type 355 * <code>"wf-invalid-character-in-node-name"</code>, with a 356 * <code>DOMError.SEVERITY_ERROR</code> severity, if necessary; 357 * </li> 358 * <li> check if 359 * the text content inside <code>Attr</code>, <code>Element</code>, 360 * <code>Comment</code>, <code>Text</code>, <code>CDATASection</code> nodes 361 * for invalid characters and generate a <code>DOMError</code> of type 362 * <code>"wf-invalid-character"</code>, with a 363 * <code>DOMError.SEVERITY_ERROR</code> severity, if necessary; 364 * </li> 365 * <li> check if 366 * the data inside <code>ProcessingInstruction</code> nodes for invalid 367 * characters and generate a <code>DOMError</code> of type 368 * <code>"wf-invalid-character"</code>, with a 369 * <code>DOMError.SEVERITY_ERROR</code> severity, if necessary; 370 * </li> 371 * </ul></dd> 372 * <dt> 373 * <code>false</code></dt> 374 * <dd>[<em>optional</em>] Do not check for XML well-formedness. </dd> 375 * </dl></dd> 376 * </dl> 377 * <p> The resolution of the system identifiers associated with entities is 378 * done using <code>Document.documentURI</code>. However, when the feature 379 * "LS" defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>DOM Level 3 Load and Save</a>] 380 * is supported by the DOM implementation, the parameter 381 * "resource-resolver" can also be used on <code>DOMConfiguration</code> 382 * objects attached to <code>Document</code> nodes. If this parameter is 383 * set, <code>Document.normalizeDocument()</code> will invoke the resource 384 * resolver instead of using <code>Document.documentURI</code>. 385 * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>. 386 * @since 1.5, DOM Level 3 387 */ 388public interface DOMConfiguration { 389 /** 390 * Set the value of a parameter. 391 * @param name The name of the parameter to set. 392 * @param value The new value or <code>null</code> if the user wishes to 393 * unset the parameter. While the type of the value parameter is 394 * defined as <code>DOMUserData</code>, the object type must match the 395 * type defined by the definition of the parameter. For example, if 396 * the parameter is "error-handler", the value must be of type 397 * <code>DOMErrorHandler</code>. 398 * @exception DOMException 399 * NOT_FOUND_ERR: Raised when the parameter name is not recognized. 400 * <br> NOT_SUPPORTED_ERR: Raised when the parameter name is recognized 401 * but the requested value cannot be set. 402 * <br> TYPE_MISMATCH_ERR: Raised if the value type for this parameter 403 * name is incompatible with the expected value type. 404 */ 405 public void setParameter(String name, 406 Object value) 407 throws DOMException; 408 409 /** 410 * Return the value of a parameter if known. 411 * @param name The name of the parameter. 412 * @return The current object associated with the specified parameter or 413 * <code>null</code> if no object has been associated or if the 414 * parameter is not supported. 415 * @exception DOMException 416 * NOT_FOUND_ERR: Raised when the parameter name is not recognized. 417 */ 418 public Object getParameter(String name) 419 throws DOMException; 420 421 /** 422 * Check if setting a parameter to a specific value is supported. 423 * @param name The name of the parameter to check. 424 * @param value An object. if <code>null</code>, the returned value is 425 * <code>true</code>. 426 * @return <code>true</code> if the parameter could be successfully set 427 * to the specified value, or <code>false</code> if the parameter is 428 * not recognized or the requested value is not supported. This does 429 * not change the current value of the parameter itself. 430 */ 431 public boolean canSetParameter(String name, 432 Object value); 433 434 /** 435 * The list of the parameters supported by this 436 * <code>DOMConfiguration</code> object and for which at least one value 437 * can be set by the application. Note that this list can also contain 438 * parameter names defined outside this specification. 439 */ 440 public DOMStringList getParameterNames(); 441 442} 443