286N/A * reserved comment block 286N/A * DO NOT REMOVE OR ALTER! 286N/A * Copyright 1999-2002,2004,2005 The Apache Software Foundation. 286N/A * Licensed under the Apache License, Version 2.0 (the "License"); 286N/A * you may not use this file except in compliance with the License. 286N/A * You may obtain a copy of the License at 286N/A * Unless required by applicable law or agreed to in writing, software 286N/A * distributed under the License is distributed on an "AS IS" BASIS, 286N/A * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 286N/A * See the License for the specific language governing permissions and 286N/A * limitations under the License. 286N/A * ParentNode inherits from ChildNode and adds the capability of having child 286N/A * nodes. Not every node in the DOM can have children, so only nodes that can 286N/A * should inherit from this class and pay the price for it. 286N/A * ParentNode, just like NodeImpl, also implements NodeList, so it can 286N/A * return itself in response to the getChildNodes() query. This eliminiates 286N/A * the need for a separate ChildNodeList object. Note that this is an 286N/A * IMPLEMENTATION DETAIL; applications should _never_ assume that 286N/A * this identity exists. On the other hand, subclasses may need to override 286N/A * this, in case of conflicting names. This is the case for the classes 286N/A * HTMLSelectElementImpl and HTMLFormElementImpl of the HTML DOM. 286N/A * While we have a direct reference to the first child, the last child is 286N/A * stored as the previous sibling of the first child. First child nodes are 286N/A * marked as being so, and getNextSibling hides this fact. 286N/A * <P>Note: Not all parent nodes actually need to also be a child. At some 286N/A * point we used to have ParentNode inheriting from NodeImpl and another class 286N/A * called ChildAndParentNode that inherited from ChildNode. But due to the lack 286N/A * of multiple inheritance a lot of code had to be duplicated which led to a 286N/A * maintenance nightmare. At the same time only a few nodes (Document, 286N/A * DocumentFragment, Entity, and Attribute) cannot be a child so the gain in 286N/A * memory wasn't really worth it. The only type for which this would be the 286N/A * case is Attribute, but we deal with there in another special way, so this is 286N/A * This class doesn't directly support mutation events, however, it notifies 286N/A * the document when mutations are performed so that the document class do so. 286N/A * <p><b>WARNING</b>: Some of the code here is partially duplicated in 286N/A * AttrImpl, be careful to keep these two classes in sync! 286N/A * @author Arnaud Le Hors, IBM 286N/A * @author Joe Kesselman, IBM 286N/A * @author Andy Clark, IBM 286N/A /** Serialization version. */ 286N/A * No public constructor; only subclasses of ParentNode should be 286N/A * instantiated, and those normally via a Document's factory methods 286N/A /** Constructor for serialization. */ 286N/A * Returns a duplicate of a given node. You can consider this a 286N/A * generic "copy constructor" for nodes. The newly returned object should 286N/A * be completely independent of the source object's subtree, so changes 286N/A * in one after the clone has been made will not affect the other. 286N/A * Example: Cloning a Text node will copy both the node and the text it 286N/A * Example: Cloning something that has children -- Element or Attr, for 286N/A * example -- will _not_ clone those children unless a "deep clone" 286N/A * has been requested. A shallow clone of an Attr node will yield an 286N/A * empty Attr of the same name. 286N/A * NOTE: Clones will always be read/write, even if the node being cloned 286N/A * is read-only, to permit applications using only the DOM API to obtain 286N/A * editable copies of locked portions of the tree. 286N/A // Need to break the association w/ original kids 286N/A // invalidate cache for children NodeList 286N/A // Then, if deep, clone the kids too. 286N/A }
// cloneNode(boolean):Node 286N/A * Find the Document that this Node belongs to (the document in 286N/A * whose context the Node was created). The Node may or may not 286N/A * currently be part of that Document's actual contents. 286N/A * same as above but returns internal type and this one is not overridden 286N/A * by CoreDocumentImpl to return null 286N/A * set the ownerDocument of this node and its children 286N/A /* setting the owner document of self, after it's children makes the 286N/A data of children available to the new document. */ 286N/A * Test whether this node has any children. Convenience shorthand 286N/A * for (Node.getFirstChild()!=null) 286N/A * Obtain a NodeList enumerating all children of this node. If there 286N/A * are none, an (initially) empty NodeList is returned. 286N/A * will immediately reflect those changes. Also, the NodeList refers 286N/A * to the actual nodes, so changes to those nodes made via the DOM tree 286N/A * will be reflected in the NodeList and vice versa. 286N/A * In this implementation, Nodes implement the NodeList interface and 286N/A * provide their own getChildNodes() support. Other DOMs may solve this 286N/A }
// getChildNodes():NodeList 286N/A /** The first child of this Node, or null if none. */ 286N/A }
// getFirstChild():Node 286N/A /** The last child of this Node, or null if none. */ 286N/A }
// getLastChild():Node 286N/A // last child is stored as the previous sibling of first child 286N/A // store lastChild as previous sibling of first child 286N/A * Move one or more node(s) to our list of children. Note that this 286N/A * implicitly removes them from their previous parent. 286N/A * @param newChild The Node to be moved to our subtree. As a 286N/A * convenience feature, inserting a DocumentNode will instead insert 286N/A * @param refChild Current child which newChild should be placed 286N/A * immediately before. If refChild is null, the insertion occurs 286N/A * after all existing Nodes, like appendChild(). 286N/A * @return newChild, in its new state (relocated, or emptied in the case of 286N/A * @throws DOMException(HIERARCHY_REQUEST_ERR) if newChild is of a 286N/A * type that shouldn't be a child of this node, or if newChild is an 286N/A * ancestor of this node. 286N/A * @throws DOMException(WRONG_DOCUMENT_ERR) if newChild has a 286N/A * different owner document than we do. 286N/A * @throws DOMException(NOT_FOUND_ERR) if refChild is not a child of 286N/A * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is 286N/A // Tail-call; optimizer should be able to do good things with. 286N/A }
// insertBefore(Node,Node):Node 286N/A /** NON-DOM INTERNAL: Within DOM actions,we sometimes need to be able 286N/A * to control which mutation events are spawned. This version of the 286N/A * insertBefore operation allows us to do so. It is not intended 286N/A * for use by application programs. 286N/A // SLOW BUT SAFE: We could insert the whole subtree without 286N/A // parent's child-list, patch the parent pointers, set the 286N/A // ends of the list.) But we know some subclasses have special- 286N/A // case behavior they add to insertBefore(), so we don't risk it. 286N/A // This approch also takes fewer bytecodes. 286N/A // NOTE: If one of the children is not a legal child of this 286N/A // node, throw HIERARCHY_REQUEST_ERR before _any_ of the children 286N/A // have been transferred. (Alternative behaviors would be to 286N/A // reparent up to the first failure point or reparent all those 286N/A // which are acceptable to the target node, neither of which is 286N/A // as robust. PR-DOM-0818 isn't entirely clear on which it 286N/A // No need to check kids for right-document; if they weren't, 286N/A // they wouldn't be kids of that DocFrag. 286N/A // stupid case that must be handled as a no-op triggering events... 286N/A // refChild must be a child of this node (or null) 286N/A // Prevent cycles in the tree 286N/A // newChild cannot be ancestor of this Node, 286N/A // and actually cannot be this 286N/A // Convert to internal type, to avoid repeated casting 286N/A // Convert to internal type, to avoid repeated casting 286N/A // Attach before and after 286N/A // Note: firstChild.previousSibling == lastChild!! 286N/A // this our first and only child 286N/A // at the head of the list 286N/A // somewhere in the middle 286N/A // update cached length if we have any 286N/A // if we happen to insert just before the cached node, update 286N/A // the cache to the new node to match the cached index 286N/A // otherwise just invalidate the cache 286N/A }
// internalInsertBefore(Node,Node,boolean):Node 286N/A * Remove a child from this Node. The removed child's subtree 286N/A * remains intact so it may be re-inserted elsewhere. 286N/A * @return oldChild, in its new state (removed). 286N/A * @throws DOMException(NOT_FOUND_ERR) if oldChild is not a child of 286N/A * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is 286N/A // Tail-call, should be optimizable 286N/A }
// removeChild(Node) :Node 286N/A /** NON-DOM INTERNAL: Within DOM actions,we sometimes need to be able 286N/A * to control which mutation events are spawned. This version of the 286N/A * removeChild operation allows us to do so. It is not intended 286N/A * for use by application programs. 286N/A // update cached length if we have any 286N/A // if the removed node is the cached node 286N/A // move the cache to its (soon former) previous sibling 286N/A // otherwise just invalidate the cache 286N/A // Patch linked list around oldChild 286N/A // Note: lastChild == firstChild.previousSibling 286N/A // removing first child 286N/A // removing some other child in the middle 286N/A // Save previous sibling for normalization checking. 286N/A // Remove oldInternal's references to tree 286N/A }
// internalRemoveChild(Node,boolean):Node 286N/A * Make newChild occupy the location that oldChild used to 286N/A * have. Note that newChild will first be removed from its previous 286N/A * parent, if any. Equivalent to inserting newChild before oldChild, 286N/A * then removing oldChild. 286N/A * @return oldChild, in its new state (removed). 286N/A * @throws DOMException(HIERARCHY_REQUEST_ERR) if newChild is of a 286N/A * type that shouldn't be a child of this node, or if newChild is 286N/A * one of our ancestors. 286N/A * @throws DOMException(WRONG_DOCUMENT_ERR) if newChild has a 286N/A * different owner document than we do. 286N/A * @throws DOMException(NOT_FOUND_ERR) if oldChild is not a child of 286N/A * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) if this node is 286N/A // If Mutation Events are being generated, this operation might 286N/A // throw aggregate events twice when modifying an Attr -- once 286N/A // on insertion and once on removal. DOM Level 2 does not specify 286N/A // this as either desirable or undesirable, but hints that 286N/A // aggregations should be issued only once per user request. 286N/A * Get Node text content 286N/A // internal method taking a StringBuffer in parameter 286N/A // internal method returning whether to take the given node's text content 286N/A * Set Node text content 286N/A // get rid of any existing children 286N/A // create a Text node to hold the given content 286N/A * Count the immediate children of this node. Use to implement 286N/A * NodeList.getLength(). 286N/A // get rid of trivial cases 286N/A // otherwise request a cache object 286N/A // start from the cached node if we have one 286N/A }
// nodeListGetLength():int 286N/A * NodeList method: Count the immediate children of this node 286N/A * Return the Nth immediate child of this node, or null if the index is 286N/A * out of bounds. Use to implement NodeList.item(). 286N/A // get rid of trivial case 286N/A // otherwise request a cache object 286N/A // release cache if reaching last child or first child 286N/A // we can keep using the cache until it is actually reused 286N/A // fNodeListCache will be nulled by the pool (document) if that 286N/A // fNodeListCache = null; 286N/A }
// nodeListItem(int):Node 286N/A * NodeList method: Return the Nth immediate child of this node, or 286N/A * null if the index is out of bounds. 286N/A * @return org.w3c.dom.Node 286N/A * Create a NodeList to access children that is use by subclass elements 286N/A * that have methods named getLength() or item(int). ChildAndParentNode 286N/A * optimizes getChildNodes() by implementing NodeList itself. However if 286N/A * a subclass Element implements methods with the same name as the NodeList 286N/A * methods, they will override the actually methods in this class. 286N/A * To use this method, the subclass should implement getChildNodes() and 286N/A * have it call this method. The resulting NodeList instance maybe 286N/A * shared and cached in a transient field, but the cached value must be 286N/A * cleared if the node is cloned. 286N/A * @see NodeList.getLength() 286N/A * @see NodeList.item(int) 286N/A }
// getChildNodesUnoptimized():NodeList 286N/A // DOM2: methods, getters, setters 286N/A * Override default behavior to call normalize() on this Node's 286N/A * children. It is up to implementors or Node to override normalize() 286N/A // No need to normalize if already normalized. 286N/A * DOM Level 3 WD- Experimental. 286N/A * Override inherited behavior from NodeImpl to support deep equal. 286N/A // there are many ways to do this test, and there isn't any way 286N/A // better than another. Performance may vary greatly depending on 286N/A // the implementations involved. This one should work fine for us. 286N/A * Override default behavior so that if deep is true, children are also 286N/A * Note: this will not change the state of an EntityReference or its 286N/A * children, which are always read-only. 286N/A // Recursively set kids 286N/A }
// setReadOnly(boolean,boolean) 286N/A * Override this method in subclass to hook in efficient 286N/A * internal data structure. 286N/A // By default just change the flag to avoid calling this method again 286N/A * Checks the normalized state of this node after inserting a child. 286N/A * If the inserted child causes this node to be unnormalized, then this 286N/A * node is flagged accordingly. 286N/A * The conditions for changing the normalized state are: 286N/A * <li>The inserted child is a text node and one of its adjacent siblings 286N/A * <li>The inserted child is is itself unnormalized. 286N/A * @param insertedChild the child node that was inserted into this node 286N/A * @throws NullPointerException if the inserted child is <code>null</code> 286N/A // See if insertion caused this node to be unnormalized. 286N/A // If an adjacent sibling of the new child is a text node, 286N/A // flag this node as unnormalized. 286N/A // If the new child is not normalized, 286N/A // then this node is inherently not normalized. 286N/A }
// checkNormalizationAfterInsert(ChildNode) 286N/A * Checks the normalized of this node after removing a child. 286N/A * If the removed child causes this node to be unnormalized, then this 286N/A * node is flagged accordingly. 286N/A * The conditions for changing the normalized state are: 286N/A * <li>The removed child had two adjacent siblings that were text nodes. 286N/A * @param previousSibling the previous sibling of the removed child, or 286N/A // See if removal caused this node to be unnormalized. 286N/A // If the adjacent siblings of the removed child were both text nodes, 286N/A // flag this node as unnormalized. 286N/A }
// checkNormalizationAfterRemove(Node) 286N/A // Serialization methods 286N/A /** Serialize object. */ 286N/A }
// writeObject(ObjectOutputStream) 286N/A /** Deserialize object. */ 286N/A // perform default deseralization 286N/A // hardset synchildren - so we don't try to sync - it does not make any 286N/A // sense to try to synchildren when we just deserialize object. 286N/A }
// readObject(ObjectInputStream) 286N/A * a class to store some user data along with its handler 286N/A /** Serialization version. */