Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * Copyright (c) 2004 World Wide Web Consortium,3 *4 * (Massachusetts Institute of Technology, European Research Consortium for5 * Informatics and Mathematics, Keio University). All Rights Reserved. This6 * work is distributed under the W3C(r) Software License [1] in the hope that7 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied8 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.9 *10 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-2002123111 */12 13 package org.w3c.dom;14 15 /**16 * <code>DocumentFragment</code> is a "lightweight" or "minimal" 17 * <code>Document</code> object. It is very common to want to be able to 18 * extract a portion of a document's tree or to create a new fragment of a 19 * document. Imagine implementing a user command like cut or rearranging a 20 * document by moving fragments around. It is desirable to have an object 21 * which can hold such fragments and it is quite natural to use a Node for 22 * this purpose. While it is true that a <code>Document</code> object could 23 * fulfill this role, a <code>Document</code> object can potentially be a 24 * heavyweight object, depending on the underlying implementation. What is 25 * really needed for this is a very lightweight object. 26 * <code>DocumentFragment</code> is such an object.27 * <p>Furthermore, various operations -- such as inserting nodes as children 28 * of another <code>Node</code> -- may take <code>DocumentFragment</code> 29 * objects as arguments; this results in all the child nodes of the 30 * <code>DocumentFragment</code> being moved to the child list of this node.31 * <p>The children of a <code>DocumentFragment</code> node are zero or more 32 * nodes representing the tops of any sub-trees defining the structure of 33 * the document. <code>DocumentFragment</code> nodes do not need to be 34 * well-formed XML documents (although they do need to follow the rules 35 * imposed upon well-formed XML parsed entities, which can have multiple top 36 * nodes). For example, a <code>DocumentFragment</code> might have only one 37 * child and that child node could be a <code>Text</code> node. Such a 38 * structure model represents neither an HTML document nor a well-formed XML 39 * document.40 * <p>When a <code>DocumentFragment</code> is inserted into a 41 * <code>Document</code> (or indeed any other <code>Node</code> that may 42 * take children) the children of the <code>DocumentFragment</code> and not 43 * the <code>DocumentFragment</code> itself are inserted into the 44 * <code>Node</code>. This makes the <code>DocumentFragment</code> very 45 * useful when the user wishes to create nodes that are siblings; the 46 * <code>DocumentFragment</code> acts as the parent of these nodes so that 47 * the user can use the standard methods from the <code>Node</code> 48 * interface, such as <code>Node.insertBefore</code> and 49 * <code>Node.appendChild</code>.50 * <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>.51 */52 publicinterface DocumentFragment extendsNode {53 }54