Source code: marf/util/FreeVector.java
1 package marf.util;
2
3 import java.util.Vector;
4 import java.util.Collection;
5 import java.util.List;
6
7
8 /**
9 * <p>Adaptive extension of the java.util.Vector class.</p>
10 *
11 * <p>You may access elements of a Vector beyond it's initial length --- the Vector
12 * will be automaticall adjusted as appropriate.</p>
13 *
14 * <p>Useful in the applications where desirable vector's growth by setting an element
15 * beyond its upper boundary automatticaly lengthens the vector to accomondate the
16 * change (similar to Perl arrays).</p>
17 *
18 * <p>Similarly, getting an element beyond the upper boundary is not desirable failure, but
19 * an empty element returned. This makes the application to see as vector of a theoretically infinite
20 * in length.</p>
21 *
22 * TODO: allow negative index boundaries.
23 *
24 * $Id: FreeVector.java,v 1.12 2005/08/11 00:44:50 mokhov Exp $
25 *
26 * @author Serguei Mokhov
27 * @version $Revision: 1.12 $
28 * @since 0.3.0.1
29 */
30 public class FreeVector
31 extends Vector
32 {
33 /**
34 * For serialization versioning.
35 * When adding new members or make other structural
36 * changes regenerate this number with the
37 * <code>serialver</code> tool that comes with JDK.
38 * @since 0.3.0.4
39 */
40 private static final long serialVersionUID = 8706834105778495182L;
41
42 /**
43 * A free vector with default capacity as specified by java.util.Vector.
44 */
45 public FreeVector()
46 {
47 super();
48 }
49
50 /**
51 * Constructs this vector given capacity other than default.
52 * Inherited from java.util.Vector.
53 * @param piInitialCapacity initial element capacity (number of object placeholders)
54 */
55 public FreeVector(int piInitialCapacity)
56 {
57 super(piInitialCapacity);
58 }
59
60 /**
61 * Constructs this vector given capacity and its increment.
62 * Inherited from java.util.Vector.
63 * @param piInitialCapacity initial element capacity (number of object placeholders)
64 * @param piCapacityIncrement when current capacity reached, until how much capacity should be extened
65 */
66 public FreeVector(int piInitialCapacity, int piCapacityIncrement)
67 {
68 super(piInitialCapacity, piCapacityIncrement);
69 }
70
71 /**
72 * Constructs this vector out of a collection.
73 * Inherited from java.util.Vector.
74 * @param poCollection collection for the vector elements.
75 */
76 public FreeVector(Collection poCollection)
77 {
78 super(poCollection);
79 }
80
81 /**
82 * Access an element of the vector given index.
83 * Overridden from java.util.Vector.
84 * @param piIndex vector element index to retrieve
85 * @return object cotained at specified index, null if beyond boundary
86 */
87 public Object elementAt(int piIndex)
88 {
89 if(piIndex > size() - 1)
90 return null;
91
92 return super.elementAt(piIndex);
93 }
94
95 /**
96 * Set an element of the vector given index.
97 * Capacity is always ensured to be able to accomodate
98 * any positive inidex (barring out of memory problems).
99 * Overridden from java.util.Vector.
100 *
101 * @param poElement element to set at the index
102 * @param piIndex the index
103 */
104 public void setElementAt(Object poElement, int piIndex)
105 {
106 ensureIndexCapacity(piIndex);
107 super.setElementAt(poElement, piIndex);
108 }
109
110 /**
111 * Inserts an element of the vector after given index.
112 * Capacity is always ensured to be able to accomodate
113 * any positive inidex (barring out of memory problems).
114 * Overridden from java.util.Vector.
115 *
116 * @param poElement element to set after the index
117 * @param piIndex the index
118 */
119 public void insertElementAt(Object poElement, int piIndex)
120 {
121 ensureIndexCapacity(piIndex);
122 super.insertElementAt(poElement, piIndex);
123 }
124
125 /**
126 * Make sure the capacity of the vector is enough
127 * to hold an element with the specified index.
128 * Has effect only if the index is greater than
129 * the current vector's size.
130 *
131 * @param piIndex the index to accomodate
132 */
133 public void ensureIndexCapacity(int piIndex)
134 {
135 if(piIndex > size() - 1)
136 {
137 ensureCapacity(piIndex + 1);
138 setSize(piIndex + 1);
139 }
140 }
141
142 /**
143 * Access an element of the vector given index.
144 * Overridden from java.util.Vector. Calls the overridden elementAt().
145 *
146 * @param piIndex vector element index to retrieve
147 * @return object cotained at specified index, null if beyond boundary
148 */
149 public synchronized Object get(int piIndex)
150 {
151 return elementAt(piIndex);
152 }
153
154 /**
155 * Set an element of the vector given index.
156 * Capacity is always ensured to be able to accomodate
157 * any positive inidex (barring out of memory problems).
158 * Overridden from java.util.Vector.
159 *
160 * @param poElement element to set at the index
161 * @param piIndex the index
162 * @return object that was previously at that index.
163 */
164 public synchronized Object set(int piIndex, Object poElement)
165 {
166 Object oOldElement = elementAt(piIndex);
167 setElementAt(poElement, piIndex);
168 return oOldElement;
169 }
170
171 /**
172 * Adds an element of the vector at the specified index.
173 * Overridden from java.util.Vector. Calls the overridden insertElementAt().
174 * @param piIndex the index
175 * @param poElement element to set after the index
176 */
177 public synchronized void add(int piIndex, Object poElement)
178 {
179 insertElementAt(poElement, piIndex);
180 }
181
182 /**
183 * Removes an element at index.
184 * If the index is beyond the upper boundary, returns null.
185 * Overrides java.util.Vector.
186 * @param piIndex index of the element to be removed
187 * @return object reference of the element just removed; null if index exceeds the upper bound
188 */
189 public synchronized Object remove(int piIndex)
190 {
191 if(piIndex >= size())
192 {
193 //???
194 // 1 less than the index
195 //ensureIndexCapacity(piIndex - 1);
196
197 return null;
198 }
199
200 return super.remove(piIndex);
201 }
202
203 /**
204 * Adds a collection of elements to this vector starting at given index.
205 * Makes sure the capacity of the current vector reaches the piIndex.
206 * Overrides java.util.Vector.
207 *
208 * @param piIndex starting index to add elements from
209 * @param poCollection collection of elements to add
210 *
211 * @return <code>true</code> if the vector has changed
212 */
213 public synchronized boolean addAll(int piIndex, Collection poCollection)
214 {
215 ensureIndexCapacity(piIndex);
216 return super.addAll(piIndex, poCollection);
217 }
218
219 /**
220 * Retrieves a sublist subset of vector elements given index boundaries.
221 * Makes sure the capacity of the current vector reaches the piToIndex.
222 * Overrides java.util.Vector.
223 *
224 * @param piFromIndex starting index to fetch elements from
225 * @param piToIndex last index to fetch elements to
226 *
227 * @return a corresponding List reference.
228 */
229 public synchronized List subList(int piFromIndex, int piToIndex)
230 {
231 ensureIndexCapacity(piToIndex);
232 return super.subList(piFromIndex, piToIndex);
233 }
234
235 /**
236 * Not implemented.
237 * Meant to remove a set of elements between two specified indices.
238 * @param piFromIndex starting index to remove elements from
239 * @param piToIndex last index to remove elements to
240 * @throws NotImplementedException
241 */
242 public synchronized void removeRange(int piFromIndex, int piToIndex)
243 {
244 // TODO: implement
245 throw new NotImplementedException(this, "removeRange()");
246 }
247
248 /**
249 * Retrieves class' revision.
250 * @return revision string
251 * @since 0.3.0.2
252 */
253 public static String getMARFSourceCodeRevision()
254 {
255 return "$Revision: 1.12 $";
256 }
257 }
258
259 // EOF