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