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