1 package fulmine.util.collection;
2
3 import java.util.Collection;
4 import java.util.List;
5 import java.util.Map;
6 import java.util.Queue;
7 import java.util.Set;
8
9 /**
10 * A builder for {@link Collection} instances. This is used as a plug-in for the
11 * {@link CollectionFactory} to provide different implementations.
12 *
13 * @author Ramon Servadei
14 */
15 public interface ICollectionBuilder
16 {
17
18 /**
19 * Construct a {@link Set} implementation with the given size.
20 *
21 * @param <T>
22 * the type for the set elements
23 * @param size
24 * the size
25 * @return a {@link Set} implementation
26 */
27 <T> Set<T> newSet(int size);
28
29 /**
30 * Construct a {@link Set} implementation from another {@link Collection}
31 * instance. This copies the contents of the other collection into the newly
32 * constructed implementation.
33 *
34 * @param <T>
35 * the type for the set elements
36 * @param other
37 * the other {@link Collection} instance to construct the
38 * {@link Set} from
39 * @return a {@link Set} implementation constructed from a
40 * {@link Collection} instance.
41 */
42 <T> Set<T> newSet(Collection<T> other);
43
44 /**
45 * Construct a {@link Set} implementation with the implementation default
46 * size.
47 *
48 * @param <T>
49 * the type for the set elements
50 * @return a {@link Set} implementation
51 */
52 <T> Set<T> newSet();
53
54 /**
55 * Construct a {@link Queue} implementation with the implementation default
56 * size.
57 *
58 * @param <T>
59 * the type for the queue elements
60 * @return a {@link Queue} implementation
61 */
62 <T> Queue<T> newQueue();
63
64 /**
65 * Construct a {@link Queue} implementation with the given size.
66 *
67 * @param <T>
68 * the type for the queue elements
69 * @param size
70 * the size
71 * @return a {@link Queue} implementation
72 */
73 <T> Queue<T> newQueue(int size);
74
75 /**
76 * Construct a {@link List} implementation with its implementation default
77 * size.
78 *
79 * @param <T>
80 * the type for the list elements
81 * @return a {@link List} implementation
82 */
83 <T> List<T> newList();
84
85 /**
86 * Construct a {@link List} implementation from another {@link Collection}
87 * instance size.
88 *
89 * @param <T>
90 * the type for the list elements
91 * @param other
92 * the other {@link Collection} to construct this list from
93 * @return a {@link List} implementation constructed with the elements of
94 * the other {@link Collection}
95 */
96 <T> List<T> newList(Collection<T> other);
97
98 /**
99 * Construct a {@link List} implementation with the given size.
100 *
101 * @param <T>
102 * the type for the list elements
103 * @param size
104 * the size
105 * @return a {@link List} implementation
106 */
107 <T> List<T> newList(int size);
108
109 /**
110 * Construct a {@link Map} implementation with the given size.
111 *
112 * @param <K>
113 * the type for the map keys
114 * @param <V>
115 * the type for the map values
116 * @param size
117 * the size
118 * @return a {@link Map} implementation
119 */
120 <K, V> Map<K, V> newMap(int size);
121
122 /**
123 * Construct a {@link Map} implementation with the given size. The
124 * implementation maintains insertion order and does not have any generic
125 * type information.
126 *
127 * @param size
128 * the size
129 * @return a {@link Map} implementation
130 */
131 @SuppressWarnings("unchecked")
132 Map newUntypedOrderedMap(int size);
133
134 /**
135 * Construct a {@link Map} implementation with the given size. This returns
136 * a map with no generic type information.
137 *
138 * @param size
139 * the size
140 * @return a {@link Map} implementation
141 */
142 @SuppressWarnings("unchecked")
143 Map newUntypedMap(int size);
144
145 /**
146 * Construct a {@link Map} implementation with the given size and
147 * loadFactor.
148 *
149 * @param <K>
150 * the type for the map keys
151 * @param <V>
152 * the type for the map values
153 * @param size
154 * the size
155 * @param loadFactor
156 * the loadFactor
157 * @return a {@link Map} implementation
158 */
159 <K, V> Map<K, V> newMap(int size, float loadFactor);
160
161 /**
162 * Construct a {@link Map} implementation from another instance. This copies
163 * the contents of the other map into the newly constructed implementation.
164 *
165 * @param <K>
166 * the type for the map keys
167 * @param <V>
168 * the type for the map values
169 * @param other
170 * the other instance to construct this map from
171 * @return a {@link Map} implementation constructed from the other instance.
172 */
173 <K, V> Map<K, V> newMap(Map<K, V> other);
174
175 /**
176 * Construct a {@link Map} implementation with the implementation default
177 * size.
178 *
179 * @param <K>
180 * the type for the map keys
181 * @param <V>
182 * the type for the map values
183 * @return a {@link Map} implementation
184 */
185 <K, V> Map<K, V> newMap();
186
187 }