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
22 import org.apache.commons.scaffold.lang.ResourceException;
23
24
25 /**
26 * Base class for scrolling searches.
27 *
28 * @author Ted Husted
29 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
30 */
31 public interface ScrollerBean {
32
33
34 /**
35 * The relative position of the first entry in this set.
36 * @return the position to start this set
37 */
38 public Integer getScrollFrom();
39
40 public void setScrollFrom(Integer scrollFrom);
41
42
43 /**
44 * The number of entries before the first entry in the set
45 * (One less than scrollFrom) [0].
46 * @return Offset to next entry
47 */
48 public Integer scrollOffset();
49
50
51 /**
52 * The number of entries to return [Scroller.SCROLL_ROWS].
53 * @return Entries per page.
54 */
55 public int scrollRows();
56
57
58 /**
59 * Returns the String to use to retrieve the
60 * appropriate query to count the entries matching this search.
61 * Must be overridden or provide functionality.
62 * @return Value of count key
63 */
64 public String countKey();
65
66
67 /**
68 * Returns whether this search takes a parameter
69 * (eg primary key) [false].
70 * Override this method to return true and
71 * <code>getParameter</code> to return the
72 * required parameter.
73 * @return True if this search uses a parameter
74 */
75 public boolean hasParameter();
76
77
78 /**
79 * Returns the value used in the search [null].
80 * This can be the literal value used in the
81 * query or (if hasParameter==false) a description
82 * of what the search returns.
83 * Must be overridden or provide functionality.
84 * @return Value of search parameter
85 */
86 public Object searchValue();
87
88
89 /**
90 * Returns whether this search uses the LIKE
91 * operator so that other methods know to
92 * wrap <code>searchValue</code> in a call to
93 * <code>like</code> [false].
94 * @return True if this search uses the LIKE operator
95 */
96 public boolean isLike();
97
98
99 /**
100 * The total number of entries in search list.
101 * The default behavior returns a "like" search count
102 * of entries matching the searchKey.
103 * Override to provide functionality.
104 * @return total entries
105 * @exception May throw an exception on data access error
106 */
107 public int entryCount() throws ResourceException;
108
109
110 /**
111 * Returns the String to use to retrieve the
112 * appropriate query for this search.
113 * Must be overridden or provide functionality.
114 * @return Value of command key
115 */
116 public String commandKey();
117
118
119 /**
120 * Returns the name of the property being matched
121 * with the <code>searchValue</code>.
122 * Default method returns null.
123 * Must be overridden or provide functionality.
124 * @return The search property
125 */
126 public String searchProperty();
127
128
129 /**
130 * Returns a label to the property being searched.
131 * This can be the property name or a more
132 * descriptive legend.
133 * Default method returns <code>searchProperty</code>.
134 * Must be overridden or provide functionality.
135 * @return The label for the search property
136 */
137 public String searchLabel();
138
139
140 /**
141 * Whether to branch to "failure" if list returns zero entries.
142 */
143 public boolean failsOnEmpty ();
144
145
146 /**
147 * Returns the message token for an empty result
148 * [Tokens.DATA_ACCESS_EMPTY].
149 * May be used when isFailOnEmpty is true.
150 * @return Message token for an empty result.
151 */
152 public String tokenEmptyMessage();
153
154
155 /**
156 * Returns the dispatch token for an empty result
157 * [Tokens.FAILURE].
158 * May be used when isFailOnEmpty is true.
159 * @return Message token for an empty result.
160 */
161 public String tokenEmptyDispatch();
162
163
164 /**
165 * Return the array of parameters needed to select the
166 * entries for this set.
167 * @param parameter The additional parameter needed to select
168 * this set, if any.
169 */
170 public Object[] scrollerParams(String parameter);
171
172
173 /**
174 * Returns the collection representing the result of the Search [null].
175 * The default behavior performs a "like" search for the parameter
176 * Override for an other search type.
177 * Subclasses may ignor parameter argument
178 * when <code>isParameter</code> is false.
179 * @param target Bean to use for entries
180 * @param parameter Value to use to match entries
181 * @return Collection with the result of the search
182 */
183 public Collection result(Object target, Object parameter)
184 throws ResourceException;
185
186
187 /**
188 * Return new scroller using the
189 * current starting point (getScrollFrom),
190 * the default limit (set.SCROLL_ROWS),
191 * and current count from Access (countCurrent).
192 * @return new Scroller using current and default settings.
193 * @exception ResourceException on data access error
194 */
195 public Scroller newScroller(int entries) throws ResourceException;
196
197
198 /**
199 * Setup the legend for the result list.
200 * Default behavior is to use the <code>searchLabel</code>
201 * and <code>searchValue</code> (if any).
202 */
203 public void listLegend(ResultList list);
204
205
206 /**
207 * Invoke business logic; return result.
208 */
209 public ProcessResult scrollerSearch() throws Exception;
210
211
212 } // end ScrollerBean