View Javadoc

1   //
2   //  ========================================================================
3   //  Copyright (c) 1995-2016 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