1 /*
2 * Copyright 2005-2007 The Kuali Foundation
3 *
4 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 package org.kuali.rice.kns.lookup;
17
18 import java.io.Serializable;
19 import java.util.Collection;
20 import java.util.List;
21 import java.util.Map;
22
23 import org.kuali.rice.kns.authorization.BusinessObjectRestrictions;
24 import org.kuali.rice.kns.bo.BusinessObject;
25 import org.kuali.rice.kns.web.struts.form.LookupForm;
26 import org.kuali.rice.kns.web.ui.Field;
27 import org.kuali.rice.kns.web.ui.ResultRow;
28
29 /**
30 * This class defines an interface for lookupables.
31 *
32 * They should act as facades for LookupableHelperServices and also expose bean handlers
33 * (getCreateNewUrl, getHtmlMenuBar, getTitle, getRows, getExtraButton{Source,Params})
34 *
35 */
36 public interface Lookupable extends Serializable {
37
38 /**
39 * Initializes the lookup with a businss object class
40 *
41 * It is required that implementations of this method will initialize the
42 * search area used by the UI to provide the search form. In particular,
43 * it will ensure that getRows() will return valid results
44 *
45 * @param boClass
46 */
47 public void setBusinessObjectClass(Class businessObjectClass);
48
49 /**
50 *
51 * @return Returns the businessObjectClass this lookupable is representing
52 *
53 */
54 public Class getBusinessObjectClass();
55
56 /**
57 * Initializes the lookup with the given Map of parameters.
58 *
59 * @param parameters
60 */
61 public void setParameters(Map parameters);
62
63 /**
64 * @return Returns the parameters passed to this lookup
65 */
66 public Map getParameters();
67
68 /**
69 * @return the html to be displayed as a menu bar
70 */
71 public String getHtmlMenuBar();
72
73 /**
74 * @return the html to be displayed as a supplemental menu bar
75 */
76 public String getSupplementalMenuBar();
77
78 /**
79 * @return List of Row objects used to render the search area
80 */
81 public List getRows();
82
83 /**
84 * @return String displayed as title for the lookup
85 */
86 public String getTitle();
87
88 /**
89 * @return String url for the location to return to after the lookup
90 */
91 public String getReturnLocation();
92
93 /**
94 * @return List of Column objects used to render the result table
95 */
96 public List getColumns();
97
98 /**
99 * Validates the values filled in as search criteria, also checks for required field values.
100 *
101 * @param fieldValues - Map of property/value pairs
102 */
103 public void validateSearchParameters(Map fieldValues);
104
105 /**
106 *
107 * This method performs the lookup and returns a collection of lookup items
108 * @param lookupForm
109 * @param resultTable
110 * @param bounded
111 * @return results of lookup
112 */
113 public Collection performLookup(LookupForm lookupForm, List<ResultRow> resultTable, boolean bounded);
114
115 /**
116 * Performs a search and returns result list.
117 *
118 * @param fieldValues - Map of property/value pairs
119 * @return List of business objects found by the search
120 * @throws Exception
121 */
122 public List<BusinessObject> getSearchResults(Map<String, String> fieldValues);
123
124 /**
125 * Similar to getSearchResults, but the number of returned rows is not bounded
126 *
127 * @param fieldValues
128 * @return
129 */
130 public List<BusinessObject> getSearchResultsUnbounded(Map<String, String> fieldValues);
131
132 /**
133 * @return String providing source for optional extra button
134 */
135 public String getExtraButtonSource();
136
137 /**
138 * @return String providing return parameters for optional extra button
139 */
140 public String getExtraButtonParams();
141
142 /**
143 * Determines if there should be more search fields rendered based on already entered search criteria.
144 *
145 * @param fieldValues - Map of property/value pairs
146 * @return boolean
147 */
148 public boolean checkForAdditionalFields(Map fieldValues);
149
150 /**
151 * Builds the return value url.
152 *
153 * @param businessObject - Instance of a business object containing the return values
154 * @param fieldConversions - Map of conversions mapping bo names to caller field names.
155 * @param lookupImpl - Current lookup impl name
156 * @return String url called when selecting a row from the result set
157 */
158 public HtmlData getReturnUrl(BusinessObject businessObject, Map fieldConversions, String lookupImpl, BusinessObjectRestrictions businessObjectRestrictions);
159
160 /**
161 * Builds the Url for a maintenance new document for the lookup business object class
162 * @param businessObject
163 * @return String rendered on Lookup screen for maintenance new document
164 */
165 public String getCreateNewUrl();
166
167 /**
168 * Sets the requested fields conversions in the lookupable
169 *
170 * @param fieldConversions
171 */
172 public void setFieldConversions(Map fieldConversions);
173
174 /**
175 * Sets the requested read only fields list in the lookupable
176 *
177 * @param readOnlyFieldsList
178 */
179 public void setReadOnlyFieldsList(List<String> readOnlyFieldsList);
180
181 /**
182 * Sets the helper service for instance
183 * @param helper the helper service
184 */
185 public void setLookupableHelperService(LookupableHelperService helper);
186
187 /**
188 * Returns the LookupableHelperService designated to help this lookup
189 * @return
190 */
191 public LookupableHelperService getLookupableHelperService();
192
193 /**
194 * Returns whether this search was performed using the values of the primary keys only
195 *
196 * @return
197 */
198 public boolean isSearchUsingOnlyPrimaryKeyValues();
199
200 /**
201 * Returns a comma delimited list of primary key field labels, as defined in the DD
202 *
203 * @return
204 */
205 public String getPrimaryKeyFieldLabels();
206
207 /**
208 * This method returns a list of the default columns used to sort the result set. For multiple value lookups,
209 * this method does not change when different columns are sorted.
210 *
211 * @return
212 */
213 public List getDefaultSortColumns();
214
215 /**
216 *
217 * This method allows for customization of the lookup clear
218 *
219 */
220 public void performClear(LookupForm lookupForm);
221
222 /**
223 *
224 * This method checks whether the header non maint actions should be shown
225 *
226 */
227 public boolean shouldDisplayHeaderNonMaintActions();
228
229 /**
230 *
231 * This method checks whether the criteria should be shown
232 *
233 */
234 public boolean shouldDisplayLookupCriteria();
235
236 /**
237 *
238 * This method is called from a custom action button or script
239 *
240 */
241 public boolean performCustomAction(boolean ignoreErrors);
242
243 /**
244 *
245 * get extra field
246 *
247 * @return
248 */
249 public Field getExtraField();
250
251 /**
252 * method returns the extraOnLoad variable. The
253 * varible is currently accessed in page.tag and is called in the onLoad.
254 * it allows us to inject javascript onload.
255 */
256 public String getExtraOnLoad();
257
258 public void setExtraOnLoad(String extraOnLoad);
259 public void applyFieldAuthorizationsFromNestedLookups(Field field);
260
261 /**
262 * Performs conditional logic (based on current search values or other parameters) to
263 * override field hidden, read-only, and required attributes previously set.
264 */
265 public void applyConditionalLogicForFieldDisplay();
266 }