lib/jetty/org/eclipse/jetty/util/LazyList.java

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