001/**
002 * Copyright 2005-2018 The Kuali Foundation
003 *
004 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 */
016package org.kuali.rice.krad.maintenance;
017
018import java.util.List;
019import java.util.Map;
020
021import org.kuali.rice.kim.api.identity.Person;
022import org.kuali.rice.krad.bo.BusinessObject;
023import org.kuali.rice.krad.bo.DocumentHeader;
024import org.kuali.rice.krad.uif.service.ViewHelperService;
025
026/**
027 * Provides contract for implementing a maintenance object within the maintenance framework
028 *
029 * <p> Currently the <code>Maintainable</code> serves many purposes. First since all maintenance documents share the
030 * same document class <code>MaintenanceDocumentBase</code> certain document callbacks such as workflow post processing
031 * are invoked on the maintainable. Second the maintainable provides a hook for custom actions on the maintenance view.
032 * Finally since the maintainable extends <code>ViewHelperService</code> it is used to customize <code>View</code>
033 * configuration for <code>MaintenanceDocumentView</code> instances </p>
034 *
035 * @author Kuali Rice Team (rice.collab@kuali.org)
036 */
037public interface Maintainable extends ViewHelperService, java.io.Serializable {
038
039    /**
040     * Sets the document number on this maintainable for referencing back to the containing
041     * <code>MaintenanceDocument</code>
042     *
043     * @param documentNumber - document number for the containing maintenance document
044     */
045    public void setDocumentNumber(String documentNumber);
046
047    /**
048     * Invoked when setting the title for the document instance in workflow (doc search results)
049     * to customize the title
050     *
051     * @param document - maintenance document instance to build title for
052     * @return String document title
053     */
054    public String getDocumentTitle(MaintenanceDocument document);
055
056    /**
057     * Returns instance of the data object that is being maintained
058     *
059     * @return Object data object instance
060     */
061    public Object getDataObject();
062
063    /**
064     * Sets an instance of a data object that should be maintained
065     *
066     * @param object - data object instance
067     */
068    public void setDataObject(Object object);
069
070    /**
071     * Returns the class for the data object being maintained
072     *
073     * @return Class data object class
074     */
075    public Class<?> getDataObjectClass();
076
077    /**
078     * Sets the class for the data object that will be maintained
079     *
080     * @param dataObjectClass - class for maintenance data object
081     */
082    public void setDataObjectClass(Class<?> dataObjectClass);
083
084    /**
085     * Indicates whether the object can be locked
086     *
087     * <p>
088     * If this method is overridden, most likely  getPersistableBusinessObject() should be
089     * overridden as well.
090     * </p>
091     *
092     * @return true if maintenance is lockable, false otherwise
093     */
094    public boolean isLockable();
095
096    /**
097     * Returns the persistable business object or null if none exists.
098     *
099     * @return persistable buisness object
100     */
101    public Object getPersistableBusinessObject();
102
103    /**
104     * Returns the type of maintenance action this maintainable has been configured with
105     *
106     * @return String maintenance action string
107     */
108    public String getMaintenanceAction();
109
110    /**
111     * Sets the type of maintenance action to be performed (new, edit, or copy)
112     *
113     * @param maintenanceAction - string identifying the action type
114     */
115    public void setMaintenanceAction(String maintenanceAction);
116
117    /**
118     * Invoked to generating the list of maintenance locks used to block other edits
119     * of the same data object record
120     *
121     * @return the locking representation(s) of this document, which are reproducible
122     *         given the same keys and the same maintainable object
123     */
124    public List<MaintenanceLock> generateMaintenanceLocks();
125
126    /**
127     * Invoked to persist changes to the data object being maintained
128     *
129     * <p>
130     * Called after the maintenance document has become final indicating
131     * the changes should be applied
132     * </p>
133     */
134    public void saveDataObject();
135
136    /**
137     * Invokes to delete the data object being maintained
138     *
139     * <p>
140     * Called after the maintenance document has become final indicating
141     * the changes should be applied
142     * </p>
143     */
144    public void deleteDataObject();
145
146    /**
147     * Invoked do perform custom processing when the route status for the containing
148     * maintenance document changes
149     *
150     * <p>
151     * Usually used for determining when the document has become final so further actions
152     * can take place in addition to the usual persistence of the object changes
153     * </p>
154     *
155     * @param documentHeader - document header instance for containing maintenance document which
156     * can be used to check the new status
157     */
158    public void doRouteStatusChange(DocumentHeader documentHeader);
159
160    /**
161     * Retrieves the locking document id for the maintainable which is used to create the
162     * maintenance lock string
163     *
164     * @return String locking id
165     */
166    public String getLockingDocumentId();
167
168    /**
169     * Return an array of document ids to lock prior to processing this document
170     * in the workflow engine
171     *
172     * @return List<String> list of document ids
173     */
174    public List<String> getWorkflowEngineDocumentIdsToLock();
175
176    /**
177     * Indicates whether or not this maintainable supports custom lock
178     * descriptors for pessimistic locking.
179     *
180     * @return boolean true if the maintainable can generate custom lock descriptors,
181     *         false otherwise
182     * @see #getCustomLockDescriptor(org.kuali.rice.kim.api.identity.Person)
183     */
184    public boolean useCustomLockDescriptors();
185
186    /**
187     * Generates a custom lock descriptor for pessimistic locking. This method
188     * should not be called unless {@link #useCustomLockDescriptors()} returns
189     * true
190     *
191     * @param user - the user trying to establish the lock
192     * @return String representing the lock descriptor
193     * @see #useCustomLockDescriptors()
194     * @see org.kuali.rice.krad.service.PessimisticLockService
195     */
196    public String getCustomLockDescriptor(Person user);
197
198    /**
199     * Indicates whether this maintainable supports notes on the maintenance object
200     *
201     * <p>
202     * Note this is only applicable if the data object is an instance of <code>BusinessObject</code>
203     * </p>
204     *
205     * @return boolean true if notes are supported, false if they are not supported
206     */
207    public boolean isNotesEnabled();
208
209    /**
210     * Indicates whether the object being maintained is an instance of <code>ExternalizableBusinessObject</code>
211     *
212     * <p>
213     * For the case when we want to maintain a business object that doesn't
214     * necessarily map to a single table in the database or may doesn't map to a
215     * database at all
216     * </p>
217     *
218     * @return boolean true if the data object is an external business object, false if not
219     */
220    public boolean isExternalBusinessObject();
221
222    /**
223     * Invoked to prepare a new <code>BusinessObject</code> instance that is external
224     *
225     * @param businessObject - new business object instance to prepare
226     */
227    public void prepareExternalBusinessObject(BusinessObject businessObject);
228
229    /**
230     * Indicates whether their is an old data object for the maintainable
231     *
232     * @return boolean true if old data object exists, false if not
233     */
234    public boolean isOldDataObjectInDocument();
235
236    /**
237     * Hook for performing any custom processing before the maintenance object is saved
238     */
239    public void prepareForSave();
240
241    /**
242     * Hook for performing any custom processing after the maintenance object is retrieved from persistence storage
243     */
244    public void processAfterRetrieve();
245
246    /**
247     * Called during setupMaintenanceObject to retrieve the original dataObject that is being
248     * edited or copied.  Override this method for non BusinessObject external persistence,
249     * Maintainable objects that extend BO should override isExternalBusinessObject and
250     * prepareExternalBusinessObject instead.
251     *
252     * Do not override this method and isExternalBusinessObject.
253     *
254     * @param document document instance for the maintenance object
255     * @param dataObjectKeys Map of keys for the requested object
256     * @return the object identified by the dataObjectKeys
257     */
258    public Object retrieveObjectForEditOrCopy(MaintenanceDocument document, Map<String, String> dataObjectKeys);
259
260    /**
261     * Performs the setting of some attributes that might be necessary
262     * if we're creating a new business object using on an existing business object.
263     * For example, create a division Vendor based on an existing parent Vendor.
264     * (Please see VendorMaintainableImpl.java)
265     *
266     * @param document - maintenance document instance this maintainable belong to
267     * @param parameters - map of request parameters sent for the request
268     */
269    public void setupNewFromExisting(MaintenanceDocument document, Map<String, String[]> parameters);
270
271    /**
272     * Hook for performing any custom processing after the maintenance object has been setup for a copy 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 processAfterCopy(MaintenanceDocument document, Map<String, String[]> requestParameters);
278
279    /**
280     * Hook for performing any custom processing after the maintenance object has been setup for a edit action
281     *
282     * @param document - maintenance document instance this maintainable belong to
283     * @param requestParameters - map of request parameters sent for the copy request
284     */
285    public void processAfterEdit(MaintenanceDocument document, Map<String, String[]> requestParameters);
286
287    /**
288     * Hook for performing any custom processing after the maintenance object has been setup for a new action
289     *
290     * @param document - maintenance document instance this maintainable belong to
291     * @param requestParameters - map of request parameters sent for the copy request
292     */
293    public void processAfterNew(MaintenanceDocument document, Map<String, String[]> requestParameters);
294
295    /**
296     * Hook for performing any custom processing after each posting of the maintenance document (for various actions
297     * like add line, refresh)
298     *
299     * @param document - maintenance document instance this maintainable belong to
300     * @param requestParameters - map of request parameters from the post
301     */
302    public void processAfterPost(MaintenanceDocument document, Map<String, String[]> requestParameters);
303}