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