1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 /* 19 * $Id: DTMNodeList.java 468653 2006-10-28 07:07:05Z minchau $ 20 */ 21 package org.apache.xml.dtm.ref; 22 23 import org.apache.xml.dtm.DTM; 24 import org.apache.xml.dtm.DTMIterator; 25 import org.w3c.dom.Node; 26 27 /** 28 * <code>DTMNodeList</code> gives us an implementation of the DOM's 29 * NodeList interface wrapped around a DTM Iterator. The author 30 * considers this something of an abominations, since NodeList was not 31 * intended to be a general purpose "list of nodes" API and is 32 * generally considered by the DOM WG to have be a mistake... but I'm 33 * told that some of the XPath/XSLT folks say they must have this 34 * solution. 35 * 36 * Please note that this is not necessarily equivlaent to a DOM 37 * NodeList operating over the same document. In particular: 38 * <ul> 39 * 40 * <li>If there are several Text nodes in logical succession (ie, 41 * across CDATASection and EntityReference boundaries), we will return 42 * only the first; the caller is responsible for stepping through 43 * them. 44 * (%REVIEW% Provide a convenience routine here to assist, pending 45 * proposed DOM Level 3 getAdjacentText() operation?) </li> 46 * 47 * <li>Since the whole XPath/XSLT architecture assumes that the source 48 * document is not altered while we're working with it, we do not 49 * promise to implement the DOM NodeList's "live view" response to 50 * document mutation. </li> 51 * 52 * </ul> 53 * 54 * <p>State: In progress!!</p> 55 * */ 56 public class DTMNodeList extends DTMNodeListBase { 57 private DTMIterator m_iter; 58 59 //================================================================ 60 // Methods unique to this class 61 private DTMNodeList() { 62 } 63 64 /** 65 * Public constructor: Wrap a DTMNodeList around an existing 66 * and preconfigured DTMIterator 67 * 68 * WARNING: THIS HAS THE SIDE EFFECT OF ISSUING setShouldCacheNodes(true) 69 * AGAINST THE DTMIterator. 70 * 71 */ 72 public DTMNodeList(DTMIterator dtmIterator) { 73 if (dtmIterator != null) { 74 int pos = dtmIterator.getCurrentPos(); 75 try { 76 m_iter=(DTMIterator)dtmIterator.cloneWithReset(); 77 } catch(CloneNotSupportedException cnse) { 78 m_iter = dtmIterator; 79 } 80 m_iter.setShouldCacheNodes(true); 81 m_iter.runTo(-1); 82 m_iter.setCurrentPos(pos); 83 } 84 } 85 86 /** 87 * Access the wrapped DTMIterator. I'm not sure whether anyone will 88 * need this or not, but let's write it and think about it. 89 * 90 */ 91 public DTMIterator getDTMIterator() { 92 return m_iter; 93 } 94 95 //================================================================ 96 // org.w3c.dom.NodeList API follows 97 98 /** 99 * Returns the <code>index</code>th item in the collection. If 100 * <code>index</code> is greater than or equal to the number of nodes in 101 * the list, this returns <code>null</code>. 102 * @param index Index into the collection. 103 * @return The node at the <code>index</code>th position in the 104 * <code>NodeList</code>, or <code>null</code> if that is not a valid 105 * index. 106 */ 107 public Node item(int index) 108 { 109 if (m_iter != null) { 110 int handle=m_iter.item(index); 111 if (handle == DTM.NULL) { 112 return null; 113 } 114 return m_iter.getDTM(handle).getNode(handle); 115 } else { 116 return null; 117 } 118 } 119 120 /** 121 * The number of nodes in the list. The range of valid child node indices 122 * is 0 to <code>length-1</code> inclusive. 123 */ 124 public int getLength() { 125 return (m_iter != null) ? m_iter.getLength() : 0; 126 } 127 } 128