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
022 import org.apache.commons.scaffold.lang.ResourceException;
023
024
025 /**
026 * Base class for scrolling searches.
027 *
028 * @author Ted Husted
029 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
030 */
031 public interface ScrollerBean {
032
033
034 /**
035 * The relative position of the first entry in this set.
036 * @return the position to start this set
037 */
038 public Integer getScrollFrom();
039
040 public void setScrollFrom(Integer scrollFrom);
041
042
043 /**
044 * The number of entries before the first entry in the set
045 * (One less than scrollFrom) [0].
046 * @return Offset to next entry
047 */
048 public Integer scrollOffset();
049
050
051 /**
052 * The number of entries to return [Scroller.SCROLL_ROWS].
053 * @return Entries per page.
054 */
055 public int scrollRows();
056
057
058 /**
059 * Returns the String to use to retrieve the
060 * appropriate query to count the entries matching this search.
061 * Must be overridden or provide functionality.
062 * @return Value of count key
063 */
064 public String countKey();
065
066
067 /**
068 * Returns whether this search takes a parameter
069 * (eg primary key) [false].
070 * Override this method to return true and
071 * <code>getParameter</code> to return the
072 * required parameter.
073 * @return True if this search uses a parameter
074 */
075 public boolean hasParameter();
076
077
078 /**
079 * Returns the value used in the search [null].
080 * This can be the literal value used in the
081 * query or (if hasParameter==false) a description
082 * of what the search returns.
083 * Must be overridden or provide functionality.
084 * @return Value of search parameter
085 */
086 public Object searchValue();
087
088
089 /**
090 * Returns whether this search uses the LIKE
091 * operator so that other methods know to
092 * wrap <code>searchValue</code> in a call to
093 * <code>like</code> [false].
094 * @return True if this search uses the LIKE operator
095 */
096 public boolean isLike();
097
098
099 /**
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