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