001 /*
002 * Copyright 2001,2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.scaffold.util;
018
019
020 import java.util.Collection;
021 import java.util.Iterator;
022 import java.util.List;
023 import java.util.Map;
024
025
026 /**
027 * A container for a set of results returned from the
028 * resource tier. The list may contain a Map for each
029 * record in a set, or a collection of beans. A setter
030 * for the list is not provided, so that different
031 * implementations can specify the type it expects.
032 * @author Ted Husted
033 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
034 */
035 public interface ResultList extends Collection {
036
037
038 // ----------------------------------------------------------- Properties
039
040
041 /**
042 * Return the result list
043 * @return the result list
044 */
045 public List getResult();
046
047
048 /**
049 * Set our result
050 * @param result The new result
051 */
052 public void setResult(List result);
053
054
055 /**
056 * Return our scroller.
057 * The scroller object tracks the client's current
058 * position in a result list.
059 * The database (or a cache) can return part of a
060 * larger list at a time.
061 * The scroller object can be used to request the
062 * appropriate next or previous entry on the list,
063 * and also to display the relative postion of the
064 * first item in this batch (x of xx).
065 * @return Our scroller
066 */
067 public Scroller getScroller();
068
069
070 /**
071 * Set our scroller.
072 * @param scroller The new scroller
073 */
074 public void setScroller(Scroller scroller);
075
076
077 /**
078 * Convenience method for maintaining a counter
079 * that can be shared among multiple components
080 * in some presentation systems (e.g, Tiles).
081 * @return The next counter value
082 */
083 public int getCounter();
084
085
086 /**
087 * Set a new counter value.
088 */
089 public void setCounter(int counter);
090
091
092 /**
093 * Return the code.
094 * @return the code
095 */
096 public Integer getCode();
097
098
099 /**
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 }