Source for org.w3c.dom.DOMConfiguration

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