001/**
002 * Copyright 2005-2015 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 org.kuali.rice.kim.api.identity.Person;
019import org.kuali.rice.krad.bo.BusinessObject;
020import org.kuali.rice.krad.bo.DocumentHeader;
021import org.kuali.rice.krad.bo.PersistableBusinessObject;
022import org.kuali.rice.krad.uif.service.ViewHelperService;
023
024import java.util.List;
025import java.util.Map;
026
027/**
028 * Provides contract for implementing a maintenance object within the maintenance framework
029 *
030 * <p> Currently the <code>Maintainable</code> serves many purposes. First since all maintenance documents share the
031 * same document class <code>MaintenanceDocumentBase</code> certain document callbacks such as workflow post processing
032 * are invoked on the maintainable. Second the maintainable provides a hook for custom actions on the maintenance view.
033 * Finally since the maintainable extends <code>ViewHelperService</code> it is used to customize <code>View</code>
034 * configuration for <code>MaintenanceDocumentView</code> instances </p>
035 *
036 * @author Kuali Rice Team (rice.collab@kuali.org)
037 */
038public interface Maintainable extends ViewHelperService, java.io.Serializable {
039
040    /**
041     * Sets the document number on this maintainable for referencing back to the containing
042     * <code>MaintenanceDocument</code>
043     *
044     * @param documentNumber - document number for the containing maintenance document
045     */
046    public void setDocumentNumber(String documentNumber);
047
048    /**
049     * Invoked when setting the title for the document instance in workflow (doc search results)
050     * to customize the title
051     *
052     * @param document - maintenance document instance to build title for
053     * @return String document title
054     */
055    public String getDocumentTitle(MaintenanceDocument document);
056
057    /**
058     * Returns instance of the data object that is being maintained
059     *
060     * @return Object data object instance
061     */
062    public Object getDataObject();
063
064    /**
065     * Sets an instance of a data object that should be maintained
066     *
067     * @param object - data object instance
068     */
069    public void setDataObject(Object object);
070
071    /**
072     * Returns the class for the data object being maintained
073     *
074     * @return Class data object class
075     */
076    public Class getDataObjectClass();
077
078    /**
079     * Sets the class for the data object that will be maintained
080     *
081     * @param dataObjectClass - class for maintenance data object
082     */
083    public void setDataObjectClass(Class dataObjectClass);
084
085    /**
086     * Indicates whether the object can be locked
087     *
088     * <p>
089     * If this method is overridden, most likely  getPersistableBusinessObject() should be
090     * overridden as well.
091     * </p>
092     *
093     * @return true if maintenance is lockable, false otherwise
094     */
095    public boolean isLockable();
096
097    /**
098     * Returns the persistable business object or null if none exists.
099     *
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(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     */
197    public String getCustomLockDescriptor(Person user);
198
199    /**
200     * Indicates whether this maintainable supports notes on the maintenance object
201     *
202     * <p>
203     * Note this is only applicable if the data object is an instance of <code>BusinessObject</code>
204     * </p>
205     *
206     * @return boolean true if notes are supported, false if they are not supported
207     */
208    public boolean isNotesEnabled();
209
210    /**
211     * Indicates whether the object being maintained is an instance of <code>ExternalizableBusinessObject</code>
212     *
213     * <p>
214     * For the case when we want to maintain a business object that doesn't
215     * necessarily map to a single table in the database or may doesn't map to a
216     * database at all
217     * </p>
218     *
219     * @return boolean true if the data object is an external business object, false if not
220     */
221    public boolean isExternalBusinessObject();
222
223    /**
224     * Invoked to prepare a new <code>BusinessObject</code> instance that is external
225     *
226     * @param businessObject - new business object instance to prepare
227     */
228    public void prepareExternalBusinessObject(BusinessObject businessObject);
229
230    /**
231     * Indicates whether their is an old data object for the maintainable
232     *
233     * @return boolean true if old data object exists, false if not
234     */
235    public boolean isOldDataObjectInDocument();
236
237    /**
238     * Hook for performing any custom processing before the maintenance object is saved
239     */
240    public void prepareForSave();
241
242    /**
243     * Hook for performing any custom processing after the maintenance object is retrieved from persistence storage
244     */
245    public void processAfterRetrieve();
246
247    /**
248     * Called during setupMaintenanceObject to retrieve the original dataObject that is being
249     * edited or copied.  Override this method for non BusinessObject external persistence,
250     * Maintainable objects that extend BO should override isExternalBusinessObject and
251     * prepareBusinessObject instead.
252     *
253     * Do not override this method and isExternalBusinessObject.
254     *
255     * @param document document instance for the maintenance object
256     * @param dataObjectKeys Map of keys for the requested object
257     * @return the object identified by the dataObjectKeys
258     */
259    public Object retrieveObjectForEditOrCopy(MaintenanceDocument document, Map<String, String> dataObjectKeys);
260
261    /**
262     * Performs the setting of some attributes that might be necessary
263     * if we're creating a new business object using on an existing business object.
264     * For example, create a division Vendor based on an existing parent Vendor.
265     * (Please see VendorMaintainableImpl.java)
266     *
267     * @param document - maintenance document instance this maintainable belong to
268     * @param parameters - map of request parameters sent for the request
269     */
270    public void setupNewFromExisting(MaintenanceDocument document, Map<String, String[]> parameters);
271
272    /**
273     * Hook for performing any custom processing after the maintenance object has been setup for a copy action
274     *
275     * @param document - maintenance document instance this maintainable belong to
276     * @param requestParameters - map of request parameters sent for the copy request
277     */
278    public void processAfterCopy(MaintenanceDocument document, Map<String, String[]> requestParameters);
279
280    /**
281     * Hook for performing any custom processing after the maintenance object has been setup for a edit action
282     *
283     * @param document - maintenance document instance this maintainable belong to
284     * @param requestParameters - map of request parameters sent for the copy request
285     */
286    public void processAfterEdit(MaintenanceDocument document, Map<String, String[]> requestParameters);
287
288    /**
289     * Hook for performing any custom processing after the maintenance object has been setup for a new action
290     *
291     * @param document - maintenance document instance this maintainable belong to
292     * @param requestParameters - map of request parameters sent for the copy request
293     */
294    public void processAfterNew(MaintenanceDocument document, Map<String, String[]> requestParameters);
295
296    /**
297     * Hook for performing any custom processing after each posting of the maintenance document (for various actions
298     * like add line, refresh)
299     *
300     * @param document - maintenance document instance this maintainable belong to
301     * @param requestParameters - map of request parameters from the post
302     */
303    public void processAfterPost(MaintenanceDocument document, Map<String, String[]> requestParameters);
304}