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.
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
19 package org.eclipse.jetty.util;
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;
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.
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.
46 * Object lazylist =null;
47 * while(loopCondition)
49 * Object item = getItem();
50 * if (item.isToBeAdded())
51 * lazylist = LazyList.add(lazylist,item);
53 * return LazyList.getList(lazylist);
56 * An ArrayList of default size is used as the initial LazyList.
60 @SuppressWarnings("serial")
62 implements Cloneable, Serializable
64 private static final String[] __EMTPY_STRING_ARRAY = new String[0];
66 /* ------------------------------------------------------------ */
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.
76 @SuppressWarnings("unchecked")
77 public static Object add(Object list, Object item)
81 if (item instanceof List || item==null)
83 List<Object> l = new ArrayList<Object>();
91 if (list instanceof List)
93 ((List<Object>)list).add(item);
97 List<Object> l=new ArrayList<Object>();
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.
110 @SuppressWarnings("unchecked")
111 public static Object add(Object list, int index, Object item)
115 if (index>0 || item instanceof List || item==null)
117 List<Object> l = new ArrayList<Object>();
124 if (list instanceof List)
126 ((List<Object>)list).add(index,item);
130 List<Object> l=new ArrayList<Object>();
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.
142 public static Object addCollection(Object list, Collection<?> collection)
144 Iterator<?> i=collection.iterator();
146 list=LazyList.add(list,i.next());
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.
156 public static Object addArray(Object list, Object[] array)
158 for(int i=0;array!=null && i<array.length;i++)
159 list=LazyList.add(list,array[i]);
163 /* ------------------------------------------------------------ */
164 /** Ensure the capacity of the underlying list.
167 public static Object ensureSize(Object list, int initialSize)
170 return new ArrayList<Object>(initialSize);
171 if (list instanceof ArrayList)
173 ArrayList<?> ol=(ArrayList<?>)list;
174 if (ol.size()>initialSize)
176 ArrayList<Object> nl = new ArrayList<Object>(initialSize);
180 List<Object> l= new ArrayList<Object>(initialSize);
185 /* ------------------------------------------------------------ */
186 public static Object remove(Object list, Object o)
191 if (list instanceof List)
193 List<?> l = (List<?>)list;
205 /* ------------------------------------------------------------ */
206 public static Object remove(Object list, int i)
211 if (list instanceof List)
213 List<?> l = (List<?>)list;
227 /* ------------------------------------------------------------ */
228 /** Get the real List from a LazyList.
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.
234 public static<E> List<E> getList(Object list)
236 return getList(list,false);
240 /* ------------------------------------------------------------ */
241 /** Get the real List from a LazyList.
243 * @param list A LazyList returned from LazyList.add(Object) or null
244 * @param nullForEmpty If true, null is returned instead of an
246 * @return The List of added items, which may be null, an EMPTY_LIST
247 * or a SingletonList.
249 @SuppressWarnings("unchecked")
250 public static<E> List<E> getList(Object list, boolean nullForEmpty)
256 return Collections.emptyList();
258 if (list instanceof List)
259 return (List<E>)list;
261 return (List<E>)Collections.singletonList(list);
265 * Simple utility method to test if List has at least 1 entry.
268 * a LazyList, {@link List} or {@link Object}
269 * @return true if not-null and is not empty
271 public static boolean hasEntry(Object list)
275 if (list instanceof List)
276 return !((List<?>)list).isEmpty();
281 * Simple utility method to test if List is empty
284 * a LazyList, {@link List} or {@link Object}
285 * @return true if null or is empty
287 public static boolean isEmpty(Object list)
291 if (list instanceof List)
292 return ((List<?>)list).isEmpty();
297 /* ------------------------------------------------------------ */
298 public static String[] toStringArray(Object list)
301 return __EMTPY_STRING_ARRAY;
303 if (list instanceof List)
305 List<?> l = (List<?>)list;
306 String[] a = new String[l.size()];
307 for (int i=l.size();i-->0;)
316 return new String[] {list.toString()};
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
325 public static Object toArray(Object list,Class<?> clazz)
328 return Array.newInstance(clazz,0);
330 if (list instanceof List)
332 List<?> l = (List<?>)list;
333 if (clazz.isPrimitive())
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));
340 return l.toArray((Object[])Array.newInstance(clazz,l.size()));
344 Object a = Array.newInstance(clazz,1);
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.
354 public static int size(Object list)
358 if (list instanceof List)
359 return ((List<?>)list).size();
363 /* ------------------------------------------------------------ */
364 /** Get item from the list
365 * @param list A LazyList returned from LazyList.add(Object) or null
367 * @return the item from the list.
369 @SuppressWarnings("unchecked")
370 public static <E> E get(Object list, int i)
373 throw new IndexOutOfBoundsException();
375 if (list instanceof List)
376 return (E)((List<?>)list).get(i);
381 throw new IndexOutOfBoundsException();
384 /* ------------------------------------------------------------ */
385 public static boolean contains(Object list,Object item)
390 if (list instanceof List)
391 return ((List<?>)list).contains(item);
393 return list.equals(item);
397 /* ------------------------------------------------------------ */
398 public static Object clone(Object list)
402 if (list instanceof List)
403 return new ArrayList<Object>((List<?>)list);
407 /* ------------------------------------------------------------ */
408 public static String toString(Object list)
412 if (list instanceof List)
413 return list.toString();
417 /* ------------------------------------------------------------ */
418 @SuppressWarnings("unchecked")
419 public static<E> Iterator<E> iterator(Object list)
423 List<E> empty=Collections.emptyList();
424 return empty.iterator();
426 if (list instanceof List)
428 return ((List<E>)list).iterator();
430 List<E> l=getList(list);
434 /* ------------------------------------------------------------ */
435 @SuppressWarnings("unchecked")
436 public static<E> ListIterator<E> listIterator(Object list)
440 List<E> empty=Collections.emptyList();
441 return empty.listIterator();
443 if (list instanceof List)
444 return ((List<E>)list).listIterator();
446 List<E> l=getList(list);
447 return l.listIterator();