1 /**
2 * Copyright 2005-2014 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.krad.maintenance;
17
18 import org.kuali.rice.kim.api.identity.Person;
19 import org.kuali.rice.krad.bo.BusinessObject;
20 import org.kuali.rice.krad.bo.DocumentHeader;
21 import org.kuali.rice.krad.bo.PersistableBusinessObject;
22 import org.kuali.rice.krad.uif.service.ViewHelperService;
23
24 import java.util.List;
25 import java.util.Map;
26
27 /**
28 * Provides contract for implementing a maintenance object within the maintenance framework
29 *
30 * <p> Currently the <code>Maintainable</code> serves many purposes. First since all maintenance documents share the
31 * same document class <code>MaintenanceDocumentBase</code> certain document callbacks such as workflow post processing
32 * are invoked on the maintainable. Second the maintainable provides a hook for custom actions on the maintenance view.
33 * Finally since the maintainable extends <code>ViewHelperService</code> it is used to customize <code>View</code>
34 * configuration for <code>MaintenanceView</code> instances </p>
35 *
36 * @author Kuali Rice Team (rice.collab@kuali.org)
37 */
38 public interface Maintainable extends ViewHelperService, java.io.Serializable {
39
40 /**
41 * Sets the document number on this maintainable for referencing back to the containing
42 * <code>MaintenanceDocument</code>
43 *
44 * @param documentNumber - document number for the containing maintenance document
45 */
46 public void setDocumentNumber(String documentNumber);
47
48 /**
49 * Invoked when setting the title for the document instance in workflow (doc search results)
50 * to customize the title
51 *
52 * @param document - maintenance document instance to build title for
53 * @return String document title
54 */
55 public String getDocumentTitle(MaintenanceDocument document);
56
57 /**
58 * Returns instance of the data object that is being maintained
59 *
60 * @return Object data object instance
61 */
62 public Object getDataObject();
63
64 /**
65 * Sets an instance of a data object that should be maintained
66 *
67 * @param object - data object instance
68 */
69 public void setDataObject(Object object);
70
71 /**
72 * Returns the class for the data object being maintained
73 *
74 * @return Class data object class
75 */
76 public Class getDataObjectClass();
77
78 /**
79 * Sets the class for the data object that will be maintained
80 *
81 * @param dataObjectClass - class for maintenance data object
82 */
83 public void setDataObjectClass(Class dataObjectClass);
84
85 /**
86 * Indicates whether the object can be locked
87 *
88 * <p>
89 * If this method is overridden, most likely getPersistableBusinessObject() should be
90 * overridden as well.
91 * </p>
92 *
93 * @return true if maintenance is lockable, false otherwise
94 */
95 public boolean isLockable();
96
97 /**
98 * Returns the persistable business object or null if none exists.
99 *
100 * @return persistable buisness object
101 */
102 public PersistableBusinessObject getPersistableBusinessObject();
103
104 /**
105 * Returns the type of maintenance action this maintainable has been configured with
106 *
107 * @return String maintenance action string
108 */
109 public String getMaintenanceAction();
110
111 /**
112 * Sets the type of maintenance action to be performed (new, edit, or copy)
113 *
114 * @param maintenanceAction - string identifying the action type
115 */
116 public void setMaintenanceAction(String maintenanceAction);
117
118 /**
119 * Invoked to generating the list of maintenance locks used to block other edits
120 * of the same data object record
121 *
122 * @return the locking representation(s) of this document, which are reproducible
123 * given the same keys and the same maintainable object
124 */
125 public List<MaintenanceLock> generateMaintenanceLocks();
126
127 /**
128 * Invoked to persist changes to the data object being maintained
129 *
130 * <p>
131 * Called after the maintenance document has become final indicating
132 * the changes should be applied
133 * </p>
134 */
135 public void saveDataObject();
136
137 /**
138 * Invokes to delete the data object being maintained
139 *
140 * <p>
141 * Called after the maintenance document has become final indicating
142 * the changes should be applied
143 * </p>
144 */
145 public void deleteDataObject();
146
147 /**
148 * Invoked do perform custom processing when the route status for the containing
149 * maintenance document changes
150 *
151 * <p>
152 * Usually used for determining when the document has become final so further actions
153 * can take place in addition to the usual persistence of the object changes
154 * </p>
155 *
156 * @param documentHeader - document header instance for containing maintenance document which
157 * can be used to check the new status
158 */
159 public void doRouteStatusChange(DocumentHeader documentHeader);
160
161 /**
162 * Retrieves the locking document id for the maintainable which is used to create the
163 * maintenance lock string
164 *
165 * @return String locking id
166 */
167 public String getLockingDocumentId();
168
169 /**
170 * Return an array of document ids to lock prior to processing this document
171 * in the workflow engine
172 *
173 * @return List<String> list of document ids
174 */
175 public List<String> getWorkflowEngineDocumentIdsToLock();
176
177 /**
178 * Indicates whether or not this maintainable supports custom lock
179 * descriptors for pessimistic locking.
180 *
181 * @return boolean true if the maintainable can generate custom lock descriptors,
182 * false otherwise
183 * @see #getCustomLockDescriptor(Map, org.kuali.rice.kim.api.identity.Person)
184 */
185 public boolean useCustomLockDescriptors();
186
187 /**
188 * Generates a custom lock descriptor for pessimistic locking. This method
189 * should not be called unless {@link #useCustomLockDescriptors()} returns
190 * true
191 *
192 * @param user - the user trying to establish the lock
193 * @return String representing the lock descriptor
194 * @see #useCustomLockDescriptors()
195 * @see org.kuali.rice.krad.service.PessimisticLockService
196 * @see org.kuali.rice.krad.service.impl.PessimisticLockServiceImpl
197 */
198 public String getCustomLockDescriptor(Person user);
199
200 /**
201 * Indicates whether this maintainable supports notes on the maintenance object
202 *
203 * <p>
204 * Note this is only applicable if the data object is an instance of <code>BusinessObject</code>
205 * </p>
206 *
207 * @return boolean true if notes are supported, false if they are not supported
208 */
209 public boolean isNotesEnabled();
210
211 /**
212 * Indicates whether the object being maintained is an instance of <code>ExternalizableBusinessObject</code>
213 *
214 * <p>
215 * For the case when we want to maintain a business object that doesn't
216 * necessarily map to a single table in the database or may doesn't map to a
217 * database at all
218 * </p>
219 *
220 * @return boolean true if the data object is an external business object, false if not
221 */
222 public boolean isExternalBusinessObject();
223
224 /**
225 * Invoked to prepare a new <code>BusinessObject</code> instance that is external
226 *
227 * @param businessObject - new business object instance to prepare
228 */
229 public void prepareExternalBusinessObject(BusinessObject businessObject);
230
231 /**
232 * Indicates whether their is an old data object for the maintainable
233 *
234 * @return boolean true if old data object exists, false if not
235 */
236 public boolean isOldDataObjectInDocument();
237
238 /**
239 * Hook for performing any custom processing before the maintenance object is saved
240 */
241 public void prepareForSave();
242
243 /**
244 * Hook for performing any custom processing after the maintenance object is retrieved from persistence storage
245 */
246 public void processAfterRetrieve();
247
248 /**
249 * Called during setupMaintenanceObject to retrieve the original dataObject that is being
250 * edited or copied. Override this method for non BusinessObject external persistence,
251 * Maintainable objects that extend BO should override isExternalBusinessObject and
252 * prepareBusinessObject instead.
253 *
254 * Do not override this method and isExternalBusinessObject.
255 *
256 * @param document document instance for the maintenance object
257 * @param dataObjectKeys Map of keys for the requested object
258 * @return the object identified by the dataObjectKeys
259 */
260 public Object retrieveObjectForEditOrCopy(MaintenanceDocument document, Map<String, String> dataObjectKeys);
261
262 /**
263 * Performs the setting of some attributes that might be necessary
264 * if we're creating a new business object using on an existing business object.
265 * For example, create a division Vendor based on an existing parent Vendor.
266 * (Please see VendorMaintainableImpl.java)
267 *
268 * @param document - maintenance document instance this maintainable belong to
269 * @param requestParameters - map of request parameters sent for the request
270 */
271 public void setupNewFromExisting(MaintenanceDocument document, Map<String, String[]> parameters);
272
273 /**
274 * Hook for performing any custom processing after the maintenance object has been setup for a copy action
275 *
276 * @param document - maintenance document instance this maintainable belong to
277 * @param requestParameters - map of request parameters sent for the copy request
278 */
279 public void processAfterCopy(MaintenanceDocument document, Map<String, String[]> requestParameters);
280
281 /**
282 * Hook for performing any custom processing after the maintenance object has been setup for a edit action
283 *
284 * @param document - maintenance document instance this maintainable belong to
285 * @param requestParameters - map of request parameters sent for the copy request
286 */
287 public void processAfterEdit(MaintenanceDocument document, Map<String, String[]> requestParameters);
288
289 /**
290 * Hook for performing any custom processing after the maintenance object has been setup for a new action
291 *
292 * @param document - maintenance document instance this maintainable belong to
293 * @param requestParameters - map of request parameters sent for the copy request
294 */
295 public void processAfterNew(MaintenanceDocument document, Map<String, String[]> requestParameters);
296
297 /**
298 * Hook for performing any custom processing after each posting of the maintenance document (for various actions
299 * like add line, refresh)
300 *
301 * @param document - maintenance document instance this maintainable belong to
302 * @param requestParameters - map of request parameters from the post
303 */
304 public void processAfterPost(MaintenanceDocument document, Map<String, String[]> requestParameters);
305 }