1 /* 2 * reserved comment block 3 * DO NOT REMOVE OR ALTER! 4 */ 5 /* 6 * Licensed to the Apache Software Foundation (ASF) under one or more 7 * contributor license agreements. See the NOTICE file distributed with 8 * this work for additional information regarding copyright ownership. 9 * The ASF licenses this file to You under the Apache License, Version 2.0 10 * (the "License"); you may not use this file except in compliance with 11 * the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, 17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 */ 21 22 package com.sun.org.apache.xml.internal.dtm; 23 24 import javax.xml.transform.SourceLocator; 25 26 import com.sun.org.apache.xml.internal.utils.XMLString; 27 28 /** 29 * <code>DTM</code> is an XML document model expressed as a table 30 * rather than an object tree. It attempts to provide an interface to 31 * a parse tree that has very little object creation. (DTM 32 * implementations may also support incremental construction of the 33 * model, but that's hidden from the DTM API.) 34 * 35 * <p>Nodes in the DTM are identified by integer "handles". A handle must 36 * be unique within a process, and carries both node identification and 37 * document identification. It must be possible to compare two handles 38 * (and thus their nodes) for identity with "==".</p> 39 * 40 * <p>Namespace URLs, local-names, and expanded-names can all be 41 * represented by and tested as integer ID values. An expanded name 42 * represents (and may or may not directly contain) a combination of 43 * the URL ID, and the local-name ID. Note that the namespace URL id 44 * can be 0, which should have the meaning that the namespace is null. 45 * For consistancy, zero should not be used for a local-name index. </p> 46 * 47 * <p>Text content of a node is represented by an index and length, 48 * permitting efficient storage such as a shared FastStringBuffer.</p> 49 * 50 * <p>The model of the tree, as well as the general navigation model, 51 * is that of XPath 1.0, for the moment. The model will eventually be 52 * adapted to match the XPath 2.0 data model, XML Schema, and 53 * InfoSet.</p> 54 * 55 * <p>DTM does _not_ directly support the W3C's Document Object 56 * Model. However, it attempts to come close enough that an 57 * implementation of DTM can be created that wraps a DOM and vice 58 * versa.</p> 59 * 60 * <p><strong>Please Note:</strong> The DTM API is still 61 * <strong>Subject To Change.</strong> This wouldn't affect most 62 * users, but might require updating some extensions.</p> 63 * 64 * <p> The largest change being contemplated is a reconsideration of 65 * the Node Handle representation. We are still not entirely sure 66 * that an integer packed with two numeric subfields is really the 67 * best solution. It has been suggested that we move up to a Long, to 68 * permit more nodes per document without having to reduce the number 69 * of slots in the DTMManager. There's even been a proposal that we 70 * replace these integers with "cursor" objects containing the 71 * internal node id and a pointer to the actual DTM object; this might 72 * reduce the need to continuously consult the DTMManager to retrieve 73 * the latter, and might provide a useful "hook" back into normal Java 74 * heap management. But changing this datatype would have huge impact 75 * on Xalan's internals -- especially given Java's lack of C-style 76 * typedefs -- so we won't cut over unless we're convinced the new 77 * solution really would be an improvement!</p> 78 * */ 79 public interface DTM 80 { 81 82 /** 83 * Null node handles are represented by this value. 84 */ 85 public static final int NULL = -1; 86 87 // These nodeType mnemonics and values are deliberately the same as those 88 // used by the DOM, for convenient mapping 89 // 90 // %REVIEW% Should we actually define these as initialized to, 91 // eg. org.w3c.dom.Document.ELEMENT_NODE? 92 93 /** 94 * The node is a <code>Root</code>. 95 */ 96 public static final short ROOT_NODE = 0; 97 98 /** 99 * The node is an <code>Element</code>. 100 */ 101 public static final short ELEMENT_NODE = 1; 102 103 /** 104 * The node is an <code>Attr</code>. 105 */ 106 public static final short ATTRIBUTE_NODE = 2; 107 108 /** 109 * The node is a <code>Text</code> node. 110 */ 111 public static final short TEXT_NODE = 3; 112 113 /** 114 * The node is a <code>CDATASection</code>. 115 */ 116 public static final short CDATA_SECTION_NODE = 4; 117 118 /** 119 * The node is an <code>EntityReference</code>. 120 */ 121 public static final short ENTITY_REFERENCE_NODE = 5; 122 123 /** 124 * The node is an <code>Entity</code>. 125 */ 126 public static final short ENTITY_NODE = 6; 127 128 /** 129 * The node is a <code>ProcessingInstruction</code>. 130 */ 131 public static final short PROCESSING_INSTRUCTION_NODE = 7; 132 133 /** 134 * The node is a <code>Comment</code>. 135 */ 136 public static final short COMMENT_NODE = 8; 137 138 /** 139 * The node is a <code>Document</code>. 140 */ 141 public static final short DOCUMENT_NODE = 9; 142 143 /** 144 * The node is a <code>DocumentType</code>. 145 */ 146 public static final short DOCUMENT_TYPE_NODE = 10; 147 148 /** 149 * The node is a <code>DocumentFragment</code>. 150 */ 151 public static final short DOCUMENT_FRAGMENT_NODE = 11; 152 153 /** 154 * The node is a <code>Notation</code>. 155 */ 156 public static final short NOTATION_NODE = 12; 157 158 /** 159 * The node is a <code>namespace node</code>. Note that this is not 160 * currently a node type defined by the DOM API. 161 */ 162 public static final short NAMESPACE_NODE = 13; 163 164 /** 165 * The number of valid nodetypes. 166 */ 167 public static final short NTYPES = 14; 168 169 // ========= DTM Implementation Control Functions. ============== 170 // %TBD% RETIRED -- do via setFeature if needed. Remove from impls. 171 // public void setParseBlockSize(int blockSizeSuggestion); 172 173 /** 174 * Set an implementation dependent feature. 175 * <p> 176 * %REVIEW% Do we really expect to set features on DTMs? 177 * 178 * @param featureId A feature URL. 179 * @param state true if this feature should be on, false otherwise. 180 */ 181 public void setFeature(String featureId, boolean state); 182 183 /** 184 * Set a run time property for this DTM instance. 185 * 186 * @param property a <code>String</code> value 187 * @param value an <code>Object</code> value 188 */ 189 public void setProperty(String property, Object value); 190 191 // ========= Document Navigation Functions ========= 192 193 /** 194 * This returns a stateless "traverser", that can navigate over an 195 * XPath axis, though not in document order. 196 * 197 * @param axis One of Axes.ANCESTORORSELF, etc. 198 * 199 * @return A DTMAxisIterator, or null if the givin axis isn't supported. 200 */ 201 public DTMAxisTraverser getAxisTraverser(final int axis); 202 203 /** 204 * This is a shortcut to the iterators that implement 205 * XPath axes. 206 * Returns a bare-bones iterator that must be initialized 207 * with a start node (using iterator.setStartNode()). 208 * 209 * @param axis One of Axes.ANCESTORORSELF, etc. 210 * 211 * @return A DTMAxisIterator, or null if the givin axis isn't supported. 212 */ 213 public DTMAxisIterator getAxisIterator(final int axis); 214 215 /** 216 * Get an iterator that can navigate over an XPath Axis, predicated by 217 * the extended type ID. 218 * 219 * @param axis 220 * @param type An extended type ID. 221 * 222 * @return A DTMAxisIterator, or null if the givin axis isn't supported. 223 */ 224 public DTMAxisIterator getTypedAxisIterator(final int axis, final int type); 225 226 /** 227 * Given a node handle, test if it has child nodes. 228 * <p> %REVIEW% This is obviously useful at the DOM layer, where it 229 * would permit testing this without having to create a proxy 230 * node. It's less useful in the DTM API, where 231 * (dtm.getFirstChild(nodeHandle)!=DTM.NULL) is just as fast and 232 * almost as self-evident. But it's a convenience, and eases porting 233 * of DOM code to DTM. </p> 234 * 235 * @param nodeHandle int Handle of the node. 236 * @return int true if the given node has child nodes. 237 */ 238 public boolean hasChildNodes(int nodeHandle); 239 240 /** 241 * Given a node handle, get the handle of the node's first child. 242 * 243 * @param nodeHandle int Handle of the node. 244 * @return int DTM node-number of first child, 245 * or DTM.NULL to indicate none exists. 246 */ 247 public int getFirstChild(int nodeHandle); 248 249 /** 250 * Given a node handle, get the handle of the node's last child. 251 * 252 * @param nodeHandle int Handle of the node. 253 * @return int Node-number of last child, 254 * or DTM.NULL to indicate none exists. 255 */ 256 public int getLastChild(int nodeHandle); 257 258 /** 259 * Retrieves an attribute node by local name and namespace URI 260 * 261 * %TBD% Note that we currently have no way to support 262 * the DOM's old getAttribute() call, which accesses only the qname. 263 * 264 * @param elementHandle Handle of the node upon which to look up this attribute. 265 * @param namespaceURI The namespace URI of the attribute to 266 * retrieve, or null. 267 * @param name The local name of the attribute to 268 * retrieve. 269 * @return The attribute node handle with the specified name ( 270 * <code>nodeName</code>) or <code>DTM.NULL</code> if there is no such 271 * attribute. 272 */ 273 public int getAttributeNode(int elementHandle, String namespaceURI, 274 String name); 275 276 /** 277 * Given a node handle, get the index of the node's first attribute. 278 * 279 * @param nodeHandle int Handle of the node. 280 * @return Handle of first attribute, or DTM.NULL to indicate none exists. 281 */ 282 public int getFirstAttribute(int nodeHandle); 283 284 /** 285 * Given a node handle, get the index of the node's first namespace node. 286 * 287 * @param nodeHandle handle to node, which should probably be an element 288 * node, but need not be. 289 * 290 * @param inScope true if all namespaces in scope should be 291 * returned, false if only the node's own 292 * namespace declarations should be returned. 293 * @return handle of first namespace, 294 * or DTM.NULL to indicate none exists. 295 */ 296 public int getFirstNamespaceNode(int nodeHandle, boolean inScope); 297 298 /** 299 * Given a node handle, advance to its next sibling. 300 * @param nodeHandle int Handle of the node. 301 * @return int Node-number of next sibling, 302 * or DTM.NULL to indicate none exists. 303 */ 304 public int getNextSibling(int nodeHandle); 305 306 /** 307 * Given a node handle, find its preceeding sibling. 308 * WARNING: DTM implementations may be asymmetric; in some, 309 * this operation has been resolved by search, and is relatively expensive. 310 * 311 * @param nodeHandle the id of the node. 312 * @return int Node-number of the previous sib, 313 * or DTM.NULL to indicate none exists. 314 */ 315 public int getPreviousSibling(int nodeHandle); 316 317 /** 318 * Given a node handle, advance to the next attribute. If an 319 * element, we advance to its first attribute; if an attr, we advance to 320 * the next attr of the same element. 321 * 322 * @param nodeHandle int Handle of the node. 323 * @return int DTM node-number of the resolved attr, 324 * or DTM.NULL to indicate none exists. 325 */ 326 public int getNextAttribute(int nodeHandle); 327 328 /** 329 * Given a namespace handle, advance to the next namespace in the same scope 330 * (local or local-plus-inherited, as selected by getFirstNamespaceNode) 331 * 332 * @param baseHandle handle to original node from where the first child 333 * was relative to (needed to return nodes in document order). 334 * @param namespaceHandle handle to node which must be of type 335 * NAMESPACE_NODE. 336 * NEEDSDOC @param inScope 337 * @return handle of next namespace, 338 * or DTM.NULL to indicate none exists. 339 */ 340 public int getNextNamespaceNode(int baseHandle, int namespaceHandle, 341 boolean inScope); 342 343 /** 344 * Given a node handle, find its parent node. 345 * 346 * @param nodeHandle the id of the node. 347 * @return int Node handle of parent, 348 * or DTM.NULL to indicate none exists. 349 */ 350 public int getParent(int nodeHandle); 351 352 /** 353 * Given a DTM which contains only a single document, 354 * find the Node Handle of the Document node. Note 355 * that if the DTM is configured so it can contain multiple 356 * documents, this call will return the Document currently 357 * under construction -- but may return null if it's between 358 * documents. Generally, you should use getOwnerDocument(nodeHandle) 359 * or getDocumentRoot(nodeHandle) instead. 360 * 361 * @return int Node handle of document, or DTM.NULL if a shared DTM 362 * can not tell us which Document is currently active. 363 */ 364 public int getDocument(); 365 366 /** 367 * Given a node handle, find the owning document node. This version mimics 368 * the behavior of the DOM call by the same name. 369 * 370 * @param nodeHandle the id of the node. 371 * @return int Node handle of owning document, or DTM.NULL if the node was 372 * a Document. 373 * @see #getDocumentRoot(int nodeHandle) 374 */ 375 public int getOwnerDocument(int nodeHandle); 376 377 /** 378 * Given a node handle, find the owning document node. 379 * 380 * @param nodeHandle the id of the node. 381 * @return int Node handle of owning document, or the node itself if it was 382 * a Document. (Note difference from DOM, where getOwnerDocument returns 383 * null for the Document node.) 384 * @see #getOwnerDocument(int nodeHandle) 385 */ 386 public int getDocumentRoot(int nodeHandle); 387 388 /** 389 * Get the string-value of a node as a String object 390 * (see http://www.w3.org/TR/xpath#data-model 391 * for the definition of a node's string-value). 392 * 393 * @param nodeHandle The node ID. 394 * 395 * @return A string object that represents the string-value of the given node. 396 */ 397 public XMLString getStringValue(int nodeHandle); 398 399 /** 400 * Get number of character array chunks in 401 * the string-value of a node. 402 * (see http://www.w3.org/TR/xpath#data-model 403 * for the definition of a node's string-value). 404 * Note that a single text node may have multiple text chunks. 405 * 406 * @param nodeHandle The node ID. 407 * 408 * @return number of character array chunks in 409 * the string-value of a node. 410 */ 411 public int getStringValueChunkCount(int nodeHandle); 412 413 /** 414 * Get a character array chunk in the string-value of a node. 415 * (see http://www.w3.org/TR/xpath#data-model 416 * for the definition of a node's string-value). 417 * Note that a single text node may have multiple text chunks. 418 * 419 * @param nodeHandle The node ID. 420 * @param chunkIndex Which chunk to get. 421 * @param startAndLen A two-integer array which, upon return, WILL 422 * BE FILLED with values representing the chunk's start position 423 * within the returned character buffer and the length of the chunk. 424 * @return The character array buffer within which the chunk occurs, 425 * setting startAndLen's contents as a side-effect. 426 */ 427 public char[] getStringValueChunk(int nodeHandle, int chunkIndex, 428 int[] startAndLen); 429 430 /** 431 * Given a node handle, return an ID that represents the node's expanded name. 432 * 433 * @param nodeHandle The handle to the node in question. 434 * 435 * @return the expanded-name id of the node. 436 */ 437 public int getExpandedTypeID(int nodeHandle); 438 439 /** 440 * Given an expanded name, return an ID. If the expanded-name does not 441 * exist in the internal tables, the entry will be created, and the ID will 442 * be returned. Any additional nodes that are created that have this 443 * expanded name will use this ID. 444 * 445 * NEEDSDOC @param namespace 446 * NEEDSDOC @param localName 447 * NEEDSDOC @param type 448 * 449 * @return the expanded-name id of the node. 450 */ 451 public int getExpandedTypeID(String namespace, String localName, int type); 452 453 /** 454 * Given an expanded-name ID, return the local name part. 455 * 456 * @param ExpandedNameID an ID that represents an expanded-name. 457 * @return String Local name of this node. 458 */ 459 public String getLocalNameFromExpandedNameID(int ExpandedNameID); 460 461 /** 462 * Given an expanded-name ID, return the namespace URI part. 463 * 464 * @param ExpandedNameID an ID that represents an expanded-name. 465 * @return String URI value of this node's namespace, or null if no 466 * namespace was resolved. 467 */ 468 public String getNamespaceFromExpandedNameID(int ExpandedNameID); 469 470 /** 471 * Given a node handle, return its DOM-style node name. This will 472 * include names such as #text or #document. 473 * 474 * @param nodeHandle the id of the node. 475 * @return String Name of this node, which may be an empty string. 476 * %REVIEW% Document when empty string is possible... 477 */ 478 public String getNodeName(int nodeHandle); 479 480 /** 481 * Given a node handle, return the XPath node name. This should be 482 * the name as described by the XPath data model, NOT the DOM-style 483 * name. 484 * 485 * @param nodeHandle the id of the node. 486 * @return String Name of this node. 487 */ 488 public String getNodeNameX(int nodeHandle); 489 490 /** 491 * Given a node handle, return its DOM-style localname. 492 * (As defined in Namespaces, this is the portion of the name after the 493 * prefix, if present, or the whole node name if no prefix exists) 494 * 495 * @param nodeHandle the id of the node. 496 * @return String Local name of this node. 497 */ 498 public String getLocalName(int nodeHandle); 499 500 /** 501 * Given a namespace handle, return the prefix that the namespace decl is 502 * mapping. 503 * Given a node handle, return the prefix used to map to the namespace. 504 * (As defined in Namespaces, this is the portion of the name before any 505 * colon character). 506 * 507 * <p> %REVIEW% Are you sure you want "" for no prefix? </p> 508 * 509 * @param nodeHandle the id of the node. 510 * @return String prefix of this node's name, or "" if no explicit 511 * namespace prefix was given. 512 */ 513 public String getPrefix(int nodeHandle); 514 515 /** 516 * Given a node handle, return its DOM-style namespace URI 517 * (As defined in Namespaces, this is the declared URI which this node's 518 * prefix -- or default in lieu thereof -- was mapped to.) 519 * @param nodeHandle the id of the node. 520 * @return String URI value of this node's namespace, or null if no 521 * namespace was resolved. 522 */ 523 public String getNamespaceURI(int nodeHandle); 524 525 /** 526 * Given a node handle, return its node value. This is mostly 527 * as defined by the DOM, but may ignore some conveniences. 528 * <p> 529 * @param nodeHandle The node id. 530 * @return String Value of this node, or null if not 531 * meaningful for this node type. 532 */ 533 public String getNodeValue(int nodeHandle); 534 535 /** 536 * Given a node handle, return its DOM-style node type. 537 * 538 * <p>%REVIEW% Generally, returning short is false economy. Return int?</p> 539 * 540 * @param nodeHandle The node id. 541 * @return int Node type, as per the DOM's Node._NODE constants. 542 */ 543 public short getNodeType(int nodeHandle); 544 545 /** 546 * Get the depth level of this node in the tree (equals 1 for 547 * a parentless node). 548 * 549 * @param nodeHandle The node id. 550 * @return the number of ancestors, plus one 551 * @xsl.usage internal 552 */ 553 public short getLevel(int nodeHandle); 554 555 // ============== Document query functions ============== 556 557 /** 558 * Tests whether DTM DOM implementation implements a specific feature and 559 * that feature is supported by this node. 560 * @param feature The name of the feature to test. 561 * @param version This is the version number of the feature to test. 562 * If the version is not 563 * specified, supporting any version of the feature will cause the 564 * method to return <code>true</code>. 565 * @return Returns <code>true</code> if the specified feature is 566 * supported on this node, <code>false</code> otherwise. 567 */ 568 public boolean isSupported(String feature, String version); 569 570 /** 571 * Return the base URI of the document entity. If it is not known 572 * (because the document was parsed from a socket connection or from 573 * standard input, for example), the value of this property is unknown. 574 * 575 * @return the document base URI String object or null if unknown. 576 */ 577 public String getDocumentBaseURI(); 578 579 /** 580 * Set the base URI of the document entity. 581 * 582 * @param baseURI the document base URI String object or null if unknown. 583 */ 584 public void setDocumentBaseURI(String baseURI); 585 586 /** 587 * Return the system identifier of the document entity. If 588 * it is not known, the value of this property is null. 589 * 590 * @param nodeHandle The node id, which can be any valid node handle. 591 * @return the system identifier String object or null if unknown. 592 */ 593 public String getDocumentSystemIdentifier(int nodeHandle); 594 595 /** 596 * Return the name of the character encoding scheme 597 * in which the document entity is expressed. 598 * 599 * @param nodeHandle The node id, which can be any valid node handle. 600 * @return the document encoding String object. 601 */ 602 public String getDocumentEncoding(int nodeHandle); 603 604 /** 605 * Return an indication of the standalone status of the document, 606 * either "yes" or "no". This property is derived from the optional 607 * standalone document declaration in the XML declaration at the 608 * beginning of the document entity, and has no value if there is no 609 * standalone document declaration. 610 * 611 * @param nodeHandle The node id, which can be any valid node handle. 612 * @return the document standalone String object, either "yes", "no", or null. 613 */ 614 public String getDocumentStandalone(int nodeHandle); 615 616 /** 617 * Return a string representing the XML version of the document. This 618 * property is derived from the XML declaration optionally present at the 619 * beginning of the document entity, and has no value if there is no XML 620 * declaration. 621 * 622 * @param documentHandle the document handle 623 * @return the document version String object 624 */ 625 public String getDocumentVersion(int documentHandle); 626 627 /** 628 * Return an indication of 629 * whether the processor has read the complete DTD. Its value is a 630 * boolean. If it is false, then certain properties (indicated in their 631 * descriptions below) may be unknown. If it is true, those properties 632 * are never unknown. 633 * 634 * @return <code>true</code> if all declarations were processed; 635 * <code>false</code> otherwise. 636 */ 637 public boolean getDocumentAllDeclarationsProcessed(); 638 639 /** 640 * A document type declaration information item has the following properties: 641 * 642 * 1. [system identifier] The system identifier of the external subset, if 643 * it exists. Otherwise this property has no value. 644 * 645 * @return the system identifier String object, or null if there is none. 646 */ 647 public String getDocumentTypeDeclarationSystemIdentifier(); 648 649 /** 650 * Return the public identifier of the external subset, 651 * normalized as described in 4.2.2 External Entities [XML]. If there is 652 * no external subset or if it has no public identifier, this property 653 * has no value. 654 * 655 * @return the public identifier String object, or null if there is none. 656 */ 657 public String getDocumentTypeDeclarationPublicIdentifier(); 658 659 /** 660 * Returns the <code>Element</code> whose <code>ID</code> is given by 661 * <code>elementId</code>. If no such element exists, returns 662 * <code>DTM.NULL</code>. Behavior is not defined if more than one element 663 * has this <code>ID</code>. Attributes (including those 664 * with the name "ID") are not of type ID unless so defined by DTD/Schema 665 * information available to the DTM implementation. 666 * Implementations that do not know whether attributes are of type ID or 667 * not are expected to return <code>DTM.NULL</code>. 668 * 669 * <p>%REVIEW% Presumably IDs are still scoped to a single document, 670 * and this operation searches only within a single document, right? 671 * Wouldn't want collisions between DTMs in the same process.</p> 672 * 673 * @param elementId The unique <code>id</code> value for an element. 674 * @return The handle of the matching element. 675 */ 676 public int getElementById(String elementId); 677 678 /** 679 * The getUnparsedEntityURI function returns the URI of the unparsed 680 * entity with the specified name in the same document as the context 681 * node (see [3.3 Unparsed Entities]). It returns the empty string if 682 * there is no such entity. 683 * <p> 684 * XML processors may choose to use the System Identifier (if one 685 * is provided) to resolve the entity, rather than the URI in the 686 * Public Identifier. The details are dependent on the processor, and 687 * we would have to support some form of plug-in resolver to handle 688 * this properly. Currently, we simply return the System Identifier if 689 * present, and hope that it a usable URI or that our caller can 690 * map it to one. 691 * %REVIEW% Resolve Public Identifiers... or consider changing function name. 692 * <p> 693 * If we find a relative URI 694 * reference, XML expects it to be resolved in terms of the base URI 695 * of the document. The DOM doesn't do that for us, and it isn't 696 * entirely clear whether that should be done here; currently that's 697 * pushed up to a higher level of our application. (Note that DOM Level 698 * 1 didn't store the document's base URI.) 699 * %REVIEW% Consider resolving Relative URIs. 700 * <p> 701 * (The DOM's statement that "An XML processor may choose to 702 * completely expand entities before the structure model is passed 703 * to the DOM" refers only to parsed entities, not unparsed, and hence 704 * doesn't affect this function.) 705 * 706 * @param name A string containing the Entity Name of the unparsed 707 * entity. 708 * 709 * @return String containing the URI of the Unparsed Entity, or an 710 * empty string if no such entity exists. 711 */ 712 public String getUnparsedEntityURI(String name); 713 714 // ============== Boolean methods ================ 715 716 /** 717 * Return true if the xsl:strip-space or xsl:preserve-space was processed 718 * during construction of the document contained in this DTM. 719 * 720 * NEEDSDOC ($objectName$) @return 721 */ 722 public boolean supportsPreStripping(); 723 724 /** 725 * Figure out whether nodeHandle2 should be considered as being later 726 * in the document than nodeHandle1, in Document Order as defined 727 * by the XPath model. This may not agree with the ordering defined 728 * by other XML applications. 729 * <p> 730 * There are some cases where ordering isn't defined, and neither are 731 * the results of this function -- though we'll generally return true. 732 * <p> 733 * %REVIEW% Make sure this does the right thing with attribute nodes!!! 734 * <p> 735 * %REVIEW% Consider renaming for clarity. Perhaps isDocumentOrder(a,b)? 736 * 737 * @param firstNodeHandle DOM Node to perform position comparison on. 738 * @param secondNodeHandle DOM Node to perform position comparison on. 739 * 740 * @return false if secondNode comes before firstNode, otherwise return true. 741 * You can think of this as 742 * <code>(firstNode.documentOrderPosition <= secondNode.documentOrderPosition)</code>. 743 */ 744 public boolean isNodeAfter(int firstNodeHandle, int secondNodeHandle); 745 746 /** 747 * 2. [element content whitespace] A boolean indicating whether a 748 * text node represents white space appearing within element content 749 * (see [XML], 2.10 "White Space Handling"). Note that validating 750 * XML processors are required by XML 1.0 to provide this 751 * information... but that DOM Level 2 did not support it, since it 752 * depends on knowledge of the DTD which DOM2 could not guarantee 753 * would be available. 754 * <p> 755 * If there is no declaration for the containing element, an XML 756 * processor must assume that the whitespace could be meaningful and 757 * return false. If no declaration has been read, but the [all 758 * declarations processed] property of the document information item 759 * is false (so there may be an unread declaration), then the value 760 * of this property is indeterminate for white space characters and 761 * should probably be reported as false. It is always false for text 762 * nodes that contain anything other than (or in addition to) white 763 * space. 764 * <p> 765 * Note too that it always returns false for non-Text nodes. 766 * <p> 767 * %REVIEW% Joe wants to rename this isWhitespaceInElementContent() for clarity 768 * 769 * @param nodeHandle the node ID. 770 * @return <code>true</code> if the node definitely represents whitespace in 771 * element content; <code>false</code> otherwise. 772 */ 773 public boolean isCharacterElementContentWhitespace(int nodeHandle); 774 775 /** 776 * 10. [all declarations processed] This property is not strictly speaking 777 * part of the infoset of the document. Rather it is an indication of 778 * whether the processor has read the complete DTD. Its value is a 779 * boolean. If it is false, then certain properties (indicated in their 780 * descriptions below) may be unknown. If it is true, those properties 781 * are never unknown. 782 * 783 * @param documentHandle A node handle that must identify a document. 784 * @return <code>true</code> if all declarations were processed; 785 * <code>false</code> otherwise. 786 */ 787 public boolean isDocumentAllDeclarationsProcessed(int documentHandle); 788 789 /** 790 * 5. [specified] A flag indicating whether this attribute was actually 791 * specified in the start-tag of its element, or was defaulted from the 792 * DTD (or schema). 793 * 794 * @param attributeHandle The attribute handle 795 * @return <code>true</code> if the attribute was specified; 796 * <code>false</code> if it was defaulted or the handle doesn't 797 * refer to an attribute node. 798 */ 799 public boolean isAttributeSpecified(int attributeHandle); 800 801 // ========== Direct SAX Dispatch, for optimization purposes ======== 802 803 /** 804 * Directly call the 805 * characters method on the passed ContentHandler for the 806 * string-value of the given node (see http://www.w3.org/TR/xpath#data-model 807 * for the definition of a node's string-value). Multiple calls to the 808 * ContentHandler's characters methods may well occur for a single call to 809 * this method. 810 * 811 * @param nodeHandle The node ID. 812 * @param ch A non-null reference to a ContentHandler. 813 * @param normalize true if the content should be normalized according to 814 * the rules for the XPath 815 * <a href="http://www.w3.org/TR/xpath#function-normalize-space">normalize-space</a> 816 * function. 817 * 818 * @throws org.xml.sax.SAXException 819 */ 820 public void dispatchCharactersEvents( 821 int nodeHandle, org.xml.sax.ContentHandler ch, boolean normalize) 822 throws org.xml.sax.SAXException; 823 824 /** 825 * Directly create SAX parser events representing the XML content of 826 * a DTM subtree. This is a "serialize" operation. 827 * 828 * @param nodeHandle The node ID. 829 * @param ch A non-null reference to a ContentHandler. 830 * 831 * @throws org.xml.sax.SAXException 832 */ 833 public void dispatchToEvents(int nodeHandle, org.xml.sax.ContentHandler ch) 834 throws org.xml.sax.SAXException; 835 836 /** 837 * Return an DOM node for the given node. 838 * 839 * @param nodeHandle The node ID. 840 * 841 * @return A node representation of the DTM node. 842 */ 843 public org.w3c.dom.Node getNode(int nodeHandle); 844 845 // ==== Construction methods (may not be supported by some implementations!) ===== 846 // %REVIEW% What response occurs if not supported? 847 848 /** 849 * @return true iff we're building this model incrementally (eg 850 * we're partnered with a CoroutineParser) and thus require that the 851 * transformation and the parse run simultaneously. Guidance to the 852 * DTMManager. 853 */ 854 public boolean needsTwoThreads(); 855 856 // %REVIEW% Do these appends make any sense, should we support a 857 // wider set of methods (like the "append" methods in the 858 // current DTMDocumentImpl draft), or should we just support SAX 859 // listener interfaces? Should it be a separate interface to 860 // make that distinction explicit? 861 862 /** 863 * Return this DTM's content handler, if it has one. 864 * 865 * @return null if this model doesn't respond to SAX events. 866 */ 867 public org.xml.sax.ContentHandler getContentHandler(); 868 869 /** 870 * Return this DTM's lexical handler, if it has one. 871 * 872 * %REVIEW% Should this return null if constrution already done/begun? 873 * 874 * @return null if this model doesn't respond to lexical SAX events. 875 */ 876 public org.xml.sax.ext.LexicalHandler getLexicalHandler(); 877 878 /** 879 * Return this DTM's EntityResolver, if it has one. 880 * 881 * @return null if this model doesn't respond to SAX entity ref events. 882 */ 883 public org.xml.sax.EntityResolver getEntityResolver(); 884 885 /** 886 * Return this DTM's DTDHandler, if it has one. 887 * 888 * @return null if this model doesn't respond to SAX dtd events. 889 */ 890 public org.xml.sax.DTDHandler getDTDHandler(); 891 892 /** 893 * Return this DTM's ErrorHandler, if it has one. 894 * 895 * @return null if this model doesn't respond to SAX error events. 896 */ 897 public org.xml.sax.ErrorHandler getErrorHandler(); 898 899 /** 900 * Return this DTM's DeclHandler, if it has one. 901 * 902 * @return null if this model doesn't respond to SAX Decl events. 903 */ 904 public org.xml.sax.ext.DeclHandler getDeclHandler(); 905 906 /** 907 * Append a child to "the end of the document". Please note that 908 * the node is always cloned in a base DTM, since our basic behavior 909 * is immutable so nodes can't be removed from their previous 910 * location. 911 * 912 * <p> %REVIEW% DTM maintains an insertion cursor which 913 * performs a depth-first tree walk as nodes come in, and this operation 914 * is really equivalent to: 915 * insertionCursor.appendChild(document.importNode(newChild))) 916 * where the insert point is the last element that was appended (or 917 * the last one popped back to by an end-element operation).</p> 918 * 919 * @param newChild Must be a valid new node handle. 920 * @param clone true if the child should be cloned into the document. 921 * @param cloneDepth if the clone argument is true, specifies that the 922 * clone should include all it's children. 923 */ 924 public void appendChild(int newChild, boolean clone, boolean cloneDepth); 925 926 /** 927 * Append a text node child that will be constructed from a string, 928 * to the end of the document. Behavior is otherwise like appendChild(). 929 * 930 * @param str Non-null reference to a string. 931 */ 932 public void appendTextChild(String str); 933 934 /** 935 * Get the location of a node in the source document. 936 * 937 * @param node an <code>int</code> value 938 * @return a <code>SourceLocator</code> value or null if no location 939 * is available 940 */ 941 public SourceLocator getSourceLocatorFor(int node); 942 943 /** 944 * As the DTM is registered with the DTMManager, this method 945 * will be called. This will give the DTM implementation a 946 * chance to initialize any subsystems that are required to 947 * build the DTM 948 */ 949 public void documentRegistration(); 950 951 /** 952 * As documents are released from the DTMManager, the DTM implementation 953 * will be notified of the event. This will allow the DTM implementation 954 * to shutdown any subsystem activity that may of been assoiated with 955 * the active DTM Implementation. 956 */ 957 958 public void documentRelease(); 959 960 /** 961 * Migrate a DTM built with an old DTMManager to a new DTMManager. 962 * After the migration, the new DTMManager will treat the DTM as 963 * one that is built by itself. 964 * This is used to support DTM sharing between multiple transformations. 965 * @param manager the DTMManager 966 */ 967 public void migrateTo(DTMManager manager); 968 }