1   // ========================================================================
2   // Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
3   // ------------------------------------------------------------------------
4   // Licensed under the Apache License, Version 2.0 (the "License");
5   // you may not use this file except in compliance with the License.
6   // You may obtain a copy of the License at 
7   // http://www.apache.org/licenses/LICENSE-2.0
8   // Unless required by applicable law or agreed to in writing, software
9   // distributed under the License is distributed on an "AS IS" BASIS,
10  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11  // See the License for the specific language governing permissions and
12  // limitations under the License.
13  // ========================================================================
14  
15  package org.mortbay.util;
16  import java.io.Serializable;
17  import java.lang.reflect.Array;
18  import java.util.ArrayList;
19  import java.util.Arrays;
20  import java.util.Collection;
21  import java.util.Collections;
22  import java.util.Iterator;
23  import java.util.List;
24  import java.util.ListIterator;
25  
26  /* ------------------------------------------------------------ */
27  /** Lazy List creation.
28   * A List helper class that attempts to avoid unnecessary List
29   * creation.   If a method needs to create a List to return, but it is
30   * expected that this will either be empty or frequently contain a
31   * single item, then using LazyList will avoid additional object
32   * creations by using Collections.EMPTY_LIST or
33   * Collections.singletonList where possible.
34   * <p>
35   * LazyList works by passing an opaque representation of the list in
36   * and out of all the LazyList methods.  This opaque object is either
37   * null for an empty list, an Object for a list with a single entry
38   * or an ArrayList<Object> for a list of items.
39   *
40   * <p><h4>Usage</h4>
41   * <pre>
42   *   Object lazylist =null;
43   *   while(loopCondition)
44   *   {
45   *     Object item = getItem();
46   *     if (item.isToBeAdded())
47   *         lazylist = LazyList.add(lazylist,item);
48   *   }
49   *   return LazyList.getList(lazylist);
50   * </pre>
51   *
52   * An ArrayList of default size is used as the initial LazyList.
53   *
54   * @see java.util.List
55   * @author Greg Wilkins (gregw)
56   */
57  public class LazyList
58      implements Cloneable, Serializable
59  {
60      private static final String[] __EMTPY_STRING_ARRAY = new String[0];
61      
62      /* ------------------------------------------------------------ */
63      private LazyList()
64      {}
65      
66      /* ------------------------------------------------------------ */
67      /** Add an item to a LazyList 
68       * @param list The list to add to or null if none yet created.
69       * @param item The item to add.
70       * @return The lazylist created or added to.
71       */
72      @SuppressWarnings("unchecked")
73      public static<E> Object add(Object list, E item)
74      {
75          if (list==null)
76          {
77              if (item instanceof List || item==null)
78              {
79                  List<Object> l = new ArrayList<Object>();
80                  l.add(item);
81                  return l;
82              }
83  
84              return item;
85          }
86  
87          if (list instanceof List)
88          {
89              ((List<Object>)list).add(item);
90              return list;
91          }
92  
93          List<Object> l=new ArrayList<Object>();
94          l.add(list);
95          l.add(item);
96          return l;    
97      }
98  
99      /* ------------------------------------------------------------ */
100     /** Add an item to a LazyList 
101      * @param list The list to add to or null if none yet created.
102      * @param index The index to add the item at.
103      * @param item The item to add.
104      * @return The lazylist created or added to.
105      */
106     @SuppressWarnings("unchecked")
107     public static Object add(Object list, int index, Object item)
108     {
109         if (list==null)
110         {
111             if (index>0 || item instanceof List || item==null)
112             {
113                 List<Object> l = new ArrayList<Object>();
114                 l.add(index,item);
115                 return l;
116             }
117             return item;
118         }
119 
120         if (list instanceof List)
121         {
122             ((List<Object>)list).add(index,item);
123             return list;
124         }
125 
126         List<Object> l=new ArrayList<Object>();
127         l.add(list);
128         l.add(index,item);
129         return l;    
130     }
131     
132     /* ------------------------------------------------------------ */
133     /** Add the contents of a Collection to a LazyList
134      * @param list The list to add to or null if none yet created.
135      * @param collection The Collection whose contents should be added.
136      * @return The lazylist created or added to.
137      */
138     public static Object addCollection(Object list, Collection<?> collection)
139     {
140         Iterator<?> i=collection.iterator();
141         while(i.hasNext())
142             list=LazyList.add(list,i.next());
143         return list;
144     }
145     
146     /* ------------------------------------------------------------ */
147     /** Add the contents of an array to a LazyList
148      * @param list The list to add to or null if none yet created.
149      * @param collection The Collection whose contents should be added.
150      * @return The lazylist created or added to.
151      */
152     public static Object addArray(Object list, Object[] array)
153     {
154         for(int i=0;array!=null && i<array.length;i++)
155             list=LazyList.add(list,array[i]);
156         return list;
157     }
158 
159     /* ------------------------------------------------------------ */
160     /** Ensure the capcity of the underlying list.
161      * 
162      */
163     public static Object ensureSize(Object list, int initialSize)
164     {
165         if (list==null)
166             return new ArrayList<Object>(initialSize);
167         if (list instanceof ArrayList)
168         {
169             ArrayList<?> ol=(ArrayList<?>)list;
170             if (ol.size()>initialSize)
171                 return ol;
172             ArrayList<Object> nl = new ArrayList<Object>(initialSize);
173             nl.addAll(ol);
174             return nl;
175         }
176         List<Object> l= new ArrayList<Object>(initialSize);
177         l.add(list);
178         return l;    
179     }
180 
181     /* ------------------------------------------------------------ */
182     public static Object remove(Object list, Object o)
183     {
184         if (list==null)
185             return null;
186 
187         if (list instanceof List)
188         {
189             List<?> l = (List<?>)list;
190             l.remove(o);
191             if (l.size()==0)
192                 return null;
193             return list;
194         }
195 
196         if (list.equals(o))
197             return null;
198         return list;
199     }
200     
201     /* ------------------------------------------------------------ */
202     public static Object remove(Object list, int i)
203     {
204         if (list==null)
205             return null;
206 
207         if (list instanceof List)
208         {
209             List<?> l = (List<?>)list;
210             l.remove(i);
211             if (l.size()==0)
212                 return null;
213             return list;
214         }
215 
216         if (i==0)
217             return null;
218         return list;
219     }
220     
221     
222     
223     /* ------------------------------------------------------------ */
224     /** Get the real List from a LazyList.
225      * 
226      * @param list A LazyList returned from LazyList.add(Object)
227      * @return The List of added items, which may be an EMPTY_LIST
228      * or a SingletonList.
229      */
230     public static<E> List<E> getList(Object list)
231     {
232         return getList(list,false);
233     }
234     
235 
236     /* ------------------------------------------------------------ */
237     /** Get the real List from a LazyList.
238      * 
239      * @param list A LazyList returned from LazyList.add(Object) or null
240      * @param nullForEmpty If true, null is returned instead of an
241      * empty list.
242      * @return The List of added items, which may be null, an EMPTY_LIST
243      * or a SingletonList.
244      */
245     @SuppressWarnings("unchecked")
246     public static<E> List<E> getList(Object list, boolean nullForEmpty)
247     {
248         if (list==null)
249         {
250             if (nullForEmpty)
251                 return null;
252             return Collections.emptyList();
253         }
254         if (list instanceof List)
255             return (List<E>)list;
256         
257         return (List<E>)Collections.singletonList(list);
258     }
259 
260     
261     /* ------------------------------------------------------------ */
262     public static String[] toStringArray(Object list)
263     {
264         if (list==null)
265             return __EMTPY_STRING_ARRAY;
266         
267         if (list instanceof List)
268         {
269             List<?> l = (List<?>)list;
270             String[] a = new String[l.size()];
271             for (int i=l.size();i-->0;)
272             {
273                 Object o=l.get(i);
274                 if (o!=null)
275                     a[i]=o.toString();
276             }
277             return a;
278         }
279         
280         return new String[] {list.toString()};
281     }
282 
283     /* ------------------------------------------------------------ */
284     /** Convert a lazylist to an array
285      * @param list The list to convert
286      * @param aClass The class of the array, which may be a primitive type
287      * @return
288      */
289     public static Object toArray(Object list,Class<?> aClass)
290     {
291         if (list==null)
292             return (Object[])Array.newInstance(aClass,0);
293         
294         if (list instanceof List)
295         {
296             List<?> l = (List<?>)list;
297             if (aClass.isPrimitive())
298             {
299                 Object a = Array.newInstance(aClass,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(aClass,l.size()));
305             
306         }
307         
308         Object a = Array.newInstance(aClass,1);
309         Array.set(a,0,list);
310         return (Object[])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