1 // ========================================================================
2 // Copyright (c) 2004-2009 Mort Bay Consulting Pty. Ltd.
3 // ------------------------------------------------------------------------
4 // All rights reserved. This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v1.0
6 // and Apache License v2.0 which accompanies this distribution.
7 // The Eclipse Public License is available at
8 // http://www.eclipse.org/legal/epl-v10.html
9 // The Apache License v2.0 is available at
10 // http://www.opensource.org/licenses/apache2.0.php
11 // You may elect to redistribute this code under either of these licenses.
12 // ========================================================================
13
14 package org.eclipse.jetty.util;
15 import java.io.Serializable;
16 import java.lang.reflect.Array;
17 import java.util.ArrayList;
18 import java.util.Arrays;
19 import java.util.Collection;
20 import java.util.Collections;
21 import java.util.Iterator;
22 import java.util.List;
23 import java.util.ListIterator;
24
25 /* ------------------------------------------------------------ */
26 /** Lazy List creation.
27 * A List helper class that attempts to avoid unnecessary List
28 * creation. If a method needs to create a List to return, but it is
29 * expected that this will either be empty or frequently contain a
30 * single item, then using LazyList will avoid additional object
31 * creations by using Collections.EMPTY_LIST or
32 * Collections.singletonList where possible.
33 * <p>
34 * LazyList works by passing an opaque representation of the list in
35 * and out of all the LazyList methods. This opaque object is either
36 * null for an empty list, an Object for a list with a single entry
37 * or an ArrayList<Object> for a list of items.
38 *
39 * <p><h4>Usage</h4>
40 * <pre>
41 * Object lazylist =null;
42 * while(loopCondition)
43 * {
44 * Object item = getItem();
45 * if (item.isToBeAdded())
46 * lazylist = LazyList.add(lazylist,item);
47 * }
48 * return LazyList.getList(lazylist);
49 * </pre>
50 *
51 * An ArrayList of default size is used as the initial LazyList.
52 *
53 * @see java.util.List
54 *
55 */
56 public class LazyList
57 implements Cloneable, Serializable
58 {
59 private static final String[] __EMTPY_STRING_ARRAY = new String[0];
60
61 /* ------------------------------------------------------------ */
62 private LazyList()
63 {}
64
65 /* ------------------------------------------------------------ */
66 /** Add an item to a LazyList
67 * @param list The list to add to or null if none yet created.
68 * @param item The item to add.
69 * @return The lazylist created or added to.
70 */
71 @SuppressWarnings("unchecked")
72 public static Object add(Object list, Object item)
73 {
74 if (list==null)
75 {
76 if (item instanceof List || item==null)
77 {
78 List<Object> l = new ArrayList<Object>();
79 l.add(item);
80 return l;
81 }
82
83 return item;
84 }
85
86 if (list instanceof List)
87 {
88 ((List<Object>)list).add(item);
89 return list;
90 }
91
92 List<Object> l=new ArrayList<Object>();
93 l.add(list);
94 l.add(item);
95 return l;
96 }
97
98 /* ------------------------------------------------------------ */
99 /** Add an item to a LazyList
100 * @param list The list to add to or null if none yet created.
101 * @param index The index to add the item at.
102 * @param item The item to add.
103 * @return The lazylist created or added to.
104 */
105 @SuppressWarnings("unchecked")
106 public static Object add(Object list, int index, Object item)
107 {
108 if (list==null)
109 {
110 if (index>0 || item instanceof List || item==null)
111 {
112 List<Object> l = new ArrayList<Object>();
113 l.add(index,item);
114 return l;
115 }
116 return item;
117 }
118
119 if (list instanceof List)
120 {
121 ((List<Object>)list).add(index,item);
122 return list;
123 }
124
125 List<Object> l=new ArrayList<Object>();
126 l.add(list);
127 l.add(index,item);
128 return l;
129 }
130
131 /* ------------------------------------------------------------ */
132 /** Add the contents of a Collection to a LazyList
133 * @param list The list to add to or null if none yet created.
134 * @param collection The Collection whose contents should be added.
135 * @return The lazylist created or added to.
136 */
137 public static Object addCollection(Object list, Collection<?> collection)
138 {
139 Iterator<?> i=collection.iterator();
140 while(i.hasNext())
141 list=LazyList.add(list,i.next());
142 return list;
143 }
144
145 /* ------------------------------------------------------------ */
146 /** Add the contents of an array to a LazyList
147 * @param list The list to add to or null if none yet created.
148 * @param array The array whose contents should be added.
149 * @return The lazylist created or added to.
150 */
151 public static Object addArray(Object list, Object[] array)
152 {
153 for(int i=0;array!=null && i<array.length;i++)
154 list=LazyList.add(list,array[i]);
155 return list;
156 }
157
158 /* ------------------------------------------------------------ */
159 /** Ensure the capcity of the underlying list.
160 *
161 */
162 public static Object ensureSize(Object list, int initialSize)
163 {
164 if (list==null)
165 return new ArrayList<Object>(initialSize);
166 if (list instanceof ArrayList)
167 {
168 ArrayList<?> ol=(ArrayList<?>)list;
169 if (ol.size()>initialSize)
170 return ol;
171 ArrayList<Object> nl = new ArrayList<Object>(initialSize);
172 nl.addAll(ol);
173 return nl;
174 }
175 List<Object> l= new ArrayList<Object>(initialSize);
176 l.add(list);
177 return l;
178 }
179
180 /* ------------------------------------------------------------ */
181 public static Object remove(Object list, Object o)
182 {
183 if (list==null)
184 return null;
185
186 if (list instanceof List)
187 {
188 List<?> l = (List<?>)list;
189 l.remove(o);
190 if (l.size()==0)
191 return null;
192 return list;
193 }
194
195 if (list.equals(o))
196 return null;
197 return list;
198 }
199
200 /* ------------------------------------------------------------ */
201 public static Object remove(Object list, int i)
202 {
203 if (list==null)
204 return null;
205
206 if (list instanceof List)
207 {
208 List<?> l = (List<?>)list;
209 l.remove(i);
210 if (l.size()==0)
211 return null;
212 return list;
213 }
214
215 if (i==0)
216 return null;
217 return list;
218 }
219
220
221
222 /* ------------------------------------------------------------ */
223 /** Get the real List from a LazyList.
224 *
225 * @param list A LazyList returned from LazyList.add(Object)
226 * @return The List of added items, which may be an EMPTY_LIST
227 * or a SingletonList.
228 */
229 public static<E> List<E> getList(Object list)
230 {
231 return getList(list,false);
232 }
233
234
235 /* ------------------------------------------------------------ */
236 /** Get the real List from a LazyList.
237 *
238 * @param list A LazyList returned from LazyList.add(Object) or null
239 * @param nullForEmpty If true, null is returned instead of an
240 * empty list.
241 * @return The List of added items, which may be null, an EMPTY_LIST
242 * or a SingletonList.
243 */
244 @SuppressWarnings("unchecked")
245 public static<E> List<E> getList(Object list, boolean nullForEmpty)
246 {
247 if (list==null)
248 {
249 if (nullForEmpty)
250 return null;
251 return Collections.emptyList();
252 }
253 if (list instanceof List)
254 return (List<E>)list;
255
256 return (List<E>)Collections.singletonList(list);
257 }
258
259
260 /* ------------------------------------------------------------ */
261 public static String[] toStringArray(Object list)
262 {
263 if (list==null)
264 return __EMTPY_STRING_ARRAY;
265
266 if (list instanceof List)
267 {
268 List<?> l = (List<?>)list;
269 String[] a = new String[l.size()];
270 for (int i=l.size();i-->0;)
271 {
272 Object o=l.get(i);
273 if (o!=null)
274 a[i]=o.toString();
275 }
276 return a;
277 }
278
279 return new String[] {list.toString()};
280 }
281
282 /* ------------------------------------------------------------ */
283 /** Convert a lazylist to an array
284 * @param list The list to convert
285 * @param clazz The class of the array, which may be a primitive type
286 * @return
287 */
288 @SuppressWarnings("unchecked")
289 public static Object toArray(Object list,Class<?> clazz)
290 {
291 if (list==null)
292 return Array.newInstance(clazz,0);
293
294 if (list instanceof List)
295 {
296 List<?> l = (List<?>)list;
297 if (clazz.isPrimitive())
298 {
299 Object a = Array.newInstance(clazz,l.size());
300 for (int i=0;i<l.size();i++)
301 Array.set(a,i,l.get(i));
302 return a;
303 }
304 return l.toArray((Object[])Array.newInstance(clazz,l.size()));
305
306 }
307
308 Object a = Array.newInstance(clazz,1);
309 Array.set(a,0,list);
310 return a;
311 }
312
313 /* ------------------------------------------------------------ */
314 /** The size of a lazy List
315 * @param list A LazyList returned from LazyList.add(Object) or null
316 * @return the size of the list.
317 */
318 public static int size(Object list)
319 {
320 if (list==null)
321 return 0;
322 if (list instanceof List)
323 return ((List<?>)list).size();
324 return 1;
325 }
326
327 /* ------------------------------------------------------------ */
328 /** Get item from the list
329 * @param list A LazyList returned from LazyList.add(Object) or null
330 * @param i int index
331 * @return the item from the list.
332 */
333 @SuppressWarnings("unchecked")
334 public static <E> E get(Object list, int i)
335 {
336 if (list==null)
337 throw new IndexOutOfBoundsException();
338
339 if (list instanceof List)
340 return (E)((List<?>)list).get(i);
341
342 if (i==0)
343 return (E)list;
344
345 throw new IndexOutOfBoundsException();
346 }
347
348 /* ------------------------------------------------------------ */
349 public static boolean contains(Object list,Object item)
350 {
351 if (list==null)
352 return false;
353
354 if (list instanceof List)
355 return ((List<?>)list).contains(item);
356
357 return list.equals(item);
358 }
359
360
361 /* ------------------------------------------------------------ */
362 public static Object clone(Object list)
363 {
364 if (list==null)
365 return null;
366 if (list instanceof List)
367 return new ArrayList<Object>((List<?>)list);
368 return list;
369 }
370
371 /* ------------------------------------------------------------ */
372 public static String toString(Object list)
373 {
374 if (list==null)
375 return "[]";
376 if (list instanceof List)
377 return list.toString();
378 return "["+list+"]";
379 }
380
381 /* ------------------------------------------------------------ */
382 @SuppressWarnings("unchecked")
383 public static<E> Iterator<E> iterator(Object list)
384 {
385 if (list==null)
386 {
387 List<E> empty=Collections.emptyList();
388 return empty.iterator();
389 }
390 if (list instanceof List)
391 {
392 return ((List<E>)list).iterator();
393 }
394 List<E> l=getList(list);
395 return l.iterator();
396 }
397
398 /* ------------------------------------------------------------ */
399 @SuppressWarnings("unchecked")
400 public static<E> ListIterator<E> listIterator(Object list)
401 {
402 if (list==null)
403 {
404 List<E> empty=Collections.emptyList();
405 return empty.listIterator();
406 }
407 if (list instanceof List)
408 return ((List<E>)list).listIterator();
409
410 List<E> l=getList(list);
411 return l.listIterator();
412 }
413
414 /* ------------------------------------------------------------ */
415 /**
416 * @param array Any array of object
417 * @return A new <i>modifiable</i> list initialised with the elements from <code>array</code>.
418 */
419 public static<E> List<E> array2List(E[] array)
420 {
421 if (array==null || array.length==0)
422 return new ArrayList<E>();
423 return new ArrayList<E>(Arrays.asList(array));
424 }
425
426 /* ------------------------------------------------------------ */
427 /** Add element to an array
428 * @param array The array to add to (or null)
429 * @param item The item to add
430 * @param type The type of the array (in case of null array)
431 * @return new array with contents of array plus item
432 */
433 @SuppressWarnings("unchecked")
434 public static Object[] addToArray(Object[] array, Object item, Class<?> type)
435 {
436 if (array==null)
437 {
438 if (type==null && item!=null)
439 type= (Class<Object>)item.getClass();
440 Object[] na = (Object[])Array.newInstance(type, 1);
441 na[0]=item;
442 return na;
443 }
444 else
445 {
446 Class<?> c = array.getClass().getComponentType();
447 Object[] na = (Object[])Array.newInstance(c, Array.getLength(array)+1);
448 System.arraycopy(array, 0, na, 0, array.length);
449 na[array.length]=item;
450 return na;
451 }
452 }
453
454 /* ------------------------------------------------------------ */
455 @SuppressWarnings("unchecked")
456 public static Object removeFromArray(Object[] array, Object item)
457 {
458 if (item==null || array==null)
459 return array;
460 for (int i=array.length;i-->0;)
461 {
462 if (item.equals(array[i]))
463 {
464 Class<?> c = array==null?item.getClass():array.getClass().getComponentType();
465 Object[] na = (Object[])Array.newInstance(c, Array.getLength(array)-1);
466 if (i>0)
467 System.arraycopy(array, 0, na, 0, i);
468 if (i+1<array.length)
469 System.arraycopy(array, i+1, na, i, array.length-(i+1));
470 return na;
471 }
472 }
473 return array;
474 }
475
476 }
477