1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections.list;
18
19 import java.util.List;
20
21 import org.apache.commons.collections.Factory;
22
23 /**
24 * Decorates another <code>List</code> to create objects in the list on demand.
25 * <p>
26 * When the {@link #get(int)} method is called with an index greater than
27 * the size of the list, the list will automatically grow in size and return
28 * a new object from the specified factory. The gaps will be filled by null.
29 * If a get method call encounters a null, it will be replaced with a new
30 * object from the factory. Thus this list is unsuitable for storing null
31 * objects.
32 * <p>
33 * For instance:
34 *
35 * <pre>
36 * Factory<Date> factory = new Factory<Date>() {
37 * public Date create() {
38 * return new Date();
39 * }
40 * }
41 * List<Date> lazy = LazyList.decorate(new ArrayList<Date>(), factory);
42 * Date date = lazy.get(3);
43 * </pre>
44 *
45 * After the above code is executed, <code>date</code> will contain
46 * a new <code>Date</code> instance. Furthermore, that <code>Date</code>
47 * instance is the fourth element in the list. The first, second,
48 * and third element are all set to <code>null</code>.
49 * <p>
50 * This class differs from {@link GrowthList} because here growth occurs on
51 * get, where <code>GrowthList</code> grows on set and add. However, they
52 * could easily be used together by decorating twice.
53 * <p>
54 * This class is Serializable from Commons Collections 3.1.
55 *
56 * @see GrowthList
57 * @since 3.0
58 * @version $Id: LazyList.java 1429905 2013-01-07 17:15:14Z ggregory $
59 */
60 public class LazyList<E> extends AbstractSerializableListDecorator<E> {
61
62 /** Serialization version */
63 private static final long serialVersionUID = -1708388017160694542L;
64
65 /** The factory to use to lazily instantiate the objects */
66 protected final Factory<? extends E> factory;
67
68 /**
69 * Factory method to create a lazily instantiating list.
70 *
71 * @param <E> the type of the elements in the list
72 * @param list the list to decorate, must not be null
73 * @param factory the factory to use for creation, must not be null
74 * @return a new lazy list
75 * @throws IllegalArgumentException if list or factory is null
76 */
77 public static <E> LazyList<E> lazyList(final List<E> list, final Factory<? extends E> factory) {
78 return new LazyList<E>(list, factory);
79 }
80
81 //-----------------------------------------------------------------------
82 /**
83 * Constructor that wraps (not copies).
84 *
85 * @param list the list to decorate, must not be null
86 * @param factory the factory to use for creation, must not be null
87 * @throws IllegalArgumentException if list or factory is null
88 */
89 protected LazyList(final List<E> list, final Factory<? extends E> factory) {
90 super(list);
91 if (factory == null) {
92 throw new IllegalArgumentException("Factory must not be null");
93 }
94 this.factory = factory;
95 }
96
97 //-----------------------------------------------------------------------
98 /**
99 * Decorate the get method to perform the lazy behaviour.
100 * <p>
101 * If the requested index is greater than the current size, the list will
102 * grow to the new size and a new object will be returned from the factory.
103 * Indexes in-between the old size and the requested size are left with a
104 * placeholder that is replaced with a factory object when requested.
105 *
106 * @param index the index to retrieve
107 * @return the element at the given index
108 */
109 @Override
110 public E get(final int index) {
111 final int size = decorated().size();
112 if (index < size) {
113 // within bounds, get the object
114 E object = decorated().get(index);
115 if (object == null) {
116 // item is a place holder, create new one, set and return
117 object = factory.create();
118 decorated().set(index, object);
119 return object;
120 }
121 // good and ready to go
122 return object;
123 }
124 // we have to grow the list
125 for (int i = size; i < index; i++) {
126 decorated().add(null);
127 }
128 // create our last object, set and return
129 final E object = factory.create();
130 decorated().add(object);
131 return object;
132 }
133
134 @Override
135 public List<E> subList(final int fromIndex, final int toIndex) {
136 final List<E> sub = decorated().subList(fromIndex, toIndex);
137 return new LazyList<E>(sub, factory);
138 }
139
140 }