1 /* Copyright 2002, 2003, 2005 Elliotte Rusty Harold
2 
3    This library is free software; you can redistribute it and/or modify
4    it under the terms of version 2.1 of the GNU Lesser General Public
5    License as published by the Free Software Foundation.
6 
7    This library is distributed in the hope that it will be useful,
8    but WITHOUT ANY WARRANTY; without even the implied warranty of
9    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10    GNU Lesser General Public License for more details.
11 
12    You should have received a copy of the GNU Lesser General Public
13    License along with this library; if not, write to the
14    Free Software Foundation, Inc., 59 Temple Place, Suite 330,
15    Boston, MA 02111-1307  USA
16 
17    You can contact Elliotte Rusty Harold by sending e-mail to
18    elharo@ibiblio.org. Please include the word "XOM" in the
19    subject line. The XOM home page is located at http://www.xom.nu/
20 */
21 
22 package nu.xom;
23 
24 import java.util.ArrayList;
25 import java.util.List;
26 
27 /**
28  *
29  * <p>
30  * Implements a list of nodes for traversal purposes.
31  * Changes to the document from which this list was generated
32  * are not reflected in this list, nor are changes to the list
33  * reflected in the document. Changes to the individual
34  * <code>Node</code> objects in the list and the document
35  * are reflected in the other one.
36  * </p>
37  *
38  * <p>
39  * There is no requirement that the list not contain duplicates,
40  * or that all the members come from the same document. It is simply
41  * a list of nodes.
42  * </p>
43  *
44  * @author Elliotte Rusty Harold
45  * @version 1.1b4
46  *
47  */
48 public final class Nodes {
49 
50     private final List nodes;
51 
52 
53     /**
54      * <p>
55      * Creates an empty node list.
56      * </p>
57      */
Nodes()58     public Nodes() {
59         nodes = new ArrayList();
60     }
61 
62 
63     /**
64      * <p>
65      * Creates a node list containing a single node.
66      * </p>
67      *
68      * @param node the node to insert in the list
69      *
70      * @throws NullPointerException if <code>node</code> is null
71      */
Nodes(Node node)72     public Nodes(Node node) {
73 
74         if (node == null) {
75             throw new NullPointerException("Nodes content must be non-null");
76         }
77         nodes = new ArrayList(1);
78         nodes.add(node);
79 
80     }
81 
82 
Nodes(List results)83     Nodes(List results) {
84         this.nodes = results;
85     }
86 
87 
88     /**
89      * <p>
90      * Returns the number of nodes in the list.
91      * This is guaranteed to be non-negative.
92      * </p>
93      *
94      * @return the number of nodes in the list
95      */
size()96     public int size() {
97         return nodes.size();
98     }
99 
100 
101     /**
102      * <p>
103      * Returns the index<sup>th</sup> node in the list.
104      * The first node has index 0. The last node
105      * has index <code>size()-1</code>.
106      * </p>
107      *
108      * @param index the node to return
109      *
110      * @return the node at the specified position
111      *
112      * @throws IndexOutOfBoundsException if <code>index</code> is
113      *     negative or greater than or equal to the size of the list
114      */
get(int index)115     public Node get(int index) {
116         return (Node) nodes.get(index);
117     }
118 
119 
120     /**
121      * <p>
122      * Removes the index<sup>th</sup>node in the list.
123      * Subsequent nodes have their indexes reduced by one.
124      * </p>
125      *
126      * @param index the node to remove
127      *
128      * @return the node at the specified position
129      *
130      * @throws <code>IndexOutOfBoundsException</code> if index is
131      *     negative or greater than or equal to the size of the list
132      */
remove(int index)133     public Node remove(int index) {
134         return (Node) nodes.remove(index);
135     }
136 
137 
138     /**
139      * <p>
140      * Inserts a node at the index<sup>th</sup> position in the list.
141      * Subsequent nodes have their indexes increased by one.
142      * </p>
143      *
144      * @param node the node to insert
145      * @param index the position at which to insert the node
146      *
147      * @throws IndexOutOfBoundsException if <code>index</code> is
148      *     negative or strictly greater than the size of the list
149      * @throws NullPointerException if <code>node</code> is null
150      */
insert(Node node, int index)151     public void insert(Node node, int index) {
152         if (node == null) {
153             throw new NullPointerException("Nodes content must be non-null");
154         }
155         nodes.add(index, node);
156     }
157 
158 
159     /**
160      * <p>
161      * Adds a node at the end of this list.
162      * </p>
163      *
164      * @param node the node to add to the list
165      *
166      * @throws NullPointerException if <code>node</code> is null
167      */
append(Node node)168     public void append(Node node) {
169         if (node == null) {
170             throw new NullPointerException("Nodes content must be non-null");
171         }
172         nodes.add(node);
173     }
174 
175 
176     /**
177      * <p>
178      * Determines whether a node is contained in this list.
179      * </p>
180      *
181      * @param node the node to search for
182      *
183      * @return true if this list contains the specified node;
184      *     false otherwise
185      */
contains(Node node)186     public boolean contains(Node node) {
187         return nodes.contains(node);
188     }
189 
190 
191 }