1 /*
2 * Copyright 2001,2004 The Apache Software Foundation.
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 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.commons.scaffold.util;
18
19
20 import java.util.Collection;
21 import java.util.Iterator;
22 import java.util.List;
23 import java.util.Map;
24
25
26 /**
27 * A container for a set of results returned from the
28 * resource tier. The list may contain a Map for each
29 * record in a set, or a collection of beans. A setter
30 * for the list is not provided, so that different
31 * implementations can specify the type it expects.
32 * @author Ted Husted
33 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
34 */
35 public interface ResultList extends Collection {
36
37
38 // ----------------------------------------------------------- Properties
39
40
41 /**
42 * Return the result list
43 * @return the result list
44 */
45 public List getResult();
46
47
48 /**
49 * Set our result
50 * @param result The new result
51 */
52 public void setResult(List result);
53
54
55 /**
56 * Return our scroller.
57 * The scroller object tracks the client's current
58 * position in a result list.
59 * The database (or a cache) can return part of a
60 * larger list at a time.
61 * The scroller object can be used to request the
62 * appropriate next or previous entry on the list,
63 * and also to display the relative postion of the
64 * first item in this batch (x of xx).
65 * @return Our scroller
66 */
67 public Scroller getScroller();
68
69
70 /**
71 * Set our scroller.
72 * @param scroller The new scroller
73 */
74 public void setScroller(Scroller scroller);
75
76
77 /**
78 * Convenience method for maintaining a counter
79 * that can be shared among multiple components
80 * in some presentation systems (e.g, Tiles).
81 * @return The next counter value
82 */
83 public int getCounter();
84
85
86 /**
87 * Set a new counter value.
88 */
89 public void setCounter(int counter);
90
91
92 /**
93 * Return the code.
94 * @return the code
95 */
96 public Integer getCode();
97
98
99 /**
100 * Set the code.
101 * @param code The new code
102 */
103 public void setCode(Integer code);
104
105
106 /**
107 * Return the legend.
108 * @return the legend
109 */
110 public String getLegend();
111
112
113 /**
114 * Set the legend.
115 * @param legend The new legend
116 */
117 public void setLegend(String legend);
118
119
120 /**
121 * Set the legend.
122 * @param legend The new legend
123 */
124 public void setLegend(String name, String value);
125
126
127 /**
128 * Return the displayName map (a HashMap).
129 * These are localized titles for the
130 * properties names in the result list.
131 * @return the displayName list
132 */
133 public Map getDisplayName();
134
135
136 /**
137 * Assign a new displayName list.
138 * These are localized titles for the
139 * properties names in the result list.
140 */
141 public void setDisplayName(Map displayName);
142
143
144 // ------------------------------------------------------- Collection Methods
145
146 // ----- array operations -----
147
148
149 /**
150 * Returns an array containing all of the elements in this collection.
151 * @return an array containing all of the elements in this collection
152 */
153 public Object[] toArray();
154
155
156 /**
157 * Returns an array containing all of the elements in this collection; the
158 * runtime type of the returned array is that of the specified array.
159 * @return an array containing the elements of this collection
160 */
161 public Object[] toArray(Object a[]);
162
163
164 // ----- basic operations -----
165
166
167 /**
168 * Returns true if this collection contains no elements.
169 * @return true if this collection contains no elements
170 */
171 public boolean isEmpty();
172
173
174 /**
175 * Return the number of elements on the List.
176 * @return the size of the List
177 */
178 public int size();
179
180
181 /**
182 * Returns true if this collection contains the specified element.
183 * @return true if this collection contains the specified element
184 */
185 public boolean contains(Object element);
186
187
188 /**
189 * Appends the specified element to the end of this list (optional
190 * operation).
191 * @return the row count
192 */
193 public boolean add(Object o);
194
195
196 /**
197 * Return an iterator for the List.
198 * @return an iterator for the List
199 */
200 public Iterator iterator();
201
202
203 // ----- list operations -----
204
205 /**
206 * Returns the element at the specified position in this list.
207 */
208 public Object get(int index);
209
210
211 // ----- bulk operations ------
212
213 /**
214 * Appends all of the elements in the specified Collection
215 * to the end of this list, in the order that they are
216 * returned by the specified Collection's Iterator.
217 */
218 public boolean addAll(Collection c);
219
220
221 /**
222 * Removes all of the elements from this list..
223 */
224 public void clear();
225
226
227 /**
228 * Returns true if this collection contains all of the elements in the
229 * specified collection.
230 * @return true if this collection contains all of the elements in the
231 * specified collection
232 */
233 public boolean containsAll(Collection c);
234
235
236 /**
237 * Removes a single instance of the specified element from this
238 * collection, if it is present (optional operation).
239 */
240 public boolean remove(Object o);
241
242
243 /**
244 * Removes all this collection's elements that are also contained in the
245 * specified collection.
246 */
247 public boolean removeAll(Collection c);
248
249 /**
250 * Retains only the elements in this collection that are contained in the
251 * specified collection.
252 */
253 public boolean retainAll(Collection c);
254
255
256
257 // ----------------------------------------------------------- Public Methods
258
259
260 /**
261 * Convenience accessor for <code>get()</code>.
262 */
263 public Object getElement(int index);
264
265
266 /**
267 * Convenience accessor for <code>iterator()</code>.
268 * @return an iterator for the List
269 */
270 public Iterator getIterator();
271
272
273 /**
274 * Convenience accessor for <code>size()</code>.
275 * @return the size of the List
276 */
277 public int getSize();
278
279
280 /**
281 * Populate matching properties on given object,
282 * using bean at given index. Returns false if index>size.
283 * <code>PropertyUtils.describe</code>.
284 * @exception Throws StateException on any error.
285 */
286 public boolean populate(Object o, int index) throws Exception;
287
288 }