Coverage Report

Coverage Report - org.kuali.rice.krad.maintenance.Maintainable

Classes in this File

 /**
  * Copyright 2005-2011 The Kuali Foundation
  *
  * Licensed under the Educational Community License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.opensource.org/licenses/ecl2.php
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.kuali.rice.krad.maintenance;
 
 import org.kuali.rice.kim.api.identity.Person;
 import org.kuali.rice.krad.bo.BusinessObject;
 import org.kuali.rice.krad.bo.DocumentHeader;
 import org.kuali.rice.krad.document.MaintenanceDocument;
 import org.kuali.rice.krad.document.MaintenanceLock;
 import org.kuali.rice.krad.uif.service.ViewHelperService;
 
 import java.util.List;
 import java.util.Map;
 
 /**
  * Provides contract for implementing a maintenance object within the maintenance framework
  *
  * <p> Currently the <code>Maintainable</code> serves many purposes. First since all maintenance documents share the
  * same document class <code>MaintenanceDocumentBase</code> certain document callbacks such as workflow post processing
  * are invoked on the maintainable. Second the maintainable provides a hook for custom actions on the maintenance view.
  * Finally since the maintainable extends <code>ViewHelperService</code> it is used to customize <code>View</code>
  * configuration for <code>MaintenanceView</code> instances </p>
  *
  * @author Kuali Rice Team (rice.collab@kuali.org)
  */
 public interface Maintainable extends ViewHelperService, java.io.Serializable {
 
     /**
      * Sets the document number on this maintainable for referencing back to the containing
      * <code>MaintenanceDocument</code>
      *
      * @param documentNumber - document number for the containing maintenance document
      */
     public void setDocumentNumber(String documentNumber);
 
     /**
      * Invoked when setting the title for the document instance in workflow (doc search results)
      * to customize the title
      *
      * @param document - maintenance document instance to build title for
      * @return String document title
      */
     public String getDocumentTitle(MaintenanceDocument document);
 
     /**
      * Returns instance of the data object that is being maintained
      *
      * @return Object data object instance
      */
     public Object getDataObject();
 
     /**
      * Sets an instance of a data object that should be maintained
      *
      * @param object - data object instance
      */
     public void setDataObject(Object object);
 
     /**
      * Returns the class for the data object being maintained
      *
      * @return Class data object class
      */
     public Class getDataObjectClass();
 
     /**
      * Sets the class for the data object that will be maintained
      *
      * @param dataObjectClass - class for maintenance data object
      */
     public void setDataObjectClass(Class dataObjectClass);
 
     /**
      * Returns the type of maintenance action this maintainable has been configured with
      *
      * @return String maintenance action string
      */
     public String getMaintenanceAction();
 
     /**
      * Sets the type of maintenance action to be performed (new, edit, or copy)
      *
      * @param maintenanceAction - string identifying the action type
      */
     public void setMaintenanceAction(String maintenanceAction);
 
     /**
      * Invoked to generating the list of maintenance locks used to block other edits
      * of the same data object record
      *
      * @return the locking representation(s) of this document, which are reproducible
      *         given the same keys and the same maintainable object
      */
     public List<MaintenanceLock> generateMaintenanceLocks();
 
     /**
      * Invoked to persist changes to the data object being maintained
      *
      * <p>
      * Called after the maintenance document has become final indicating
      * the changes should be applied
      * </p>
      */
     public void saveDataObject();
 
     /**
      * Invokes to delete the data object being maintained
      *
      * <p>
      * Called after the maintenance document has become final indicating
      * the changes should be applied
      * </p>
      */
     public void deleteDataObject();
 
     /**
      * Invoked do perform custom processing when the route status for the containing
      * maintenance document changes
      *
      * <p>
      * Usually used for determining when the document has become final so further actions
      * can take place in addition to the usual persistence of the object changes
      * </p>
      *
      * @param documentHeader - document header instance for containing maintenance document which
      * can be used to check the new status
      */
     public void doRouteStatusChange(DocumentHeader documentHeader);
 
     /**
      * Retrieves the locking document id for the maintainable which is used to create the
      * maintenance lock string
      *
      * @return String locking id
      */
     public String getLockingDocumentId();
 
     /**
      * Return an array of document ids to lock prior to processing this document
      * in the workflow engine
      *
      * @return List<String> list of document ids
      */
     public List<String> getWorkflowEngineDocumentIdsToLock();
 
     /**
      * Indicates whether or not this maintainable supports custom lock
      * descriptors for pessimistic locking.
      *
      * @return boolean true if the maintainable can generate custom lock descriptors,
      *         false otherwise
      * @see #getCustomLockDescriptor(Map, org.kuali.rice.kim.api.identity.Person)
      */
     public boolean useCustomLockDescriptors();
 
     /**
      * Generates a custom lock descriptor for pessimistic locking. This method
      * should not be called unless {@link #useCustomLockDescriptors()} returns
      * true
      *
      * @param user - the user trying to establish the lock
      * @return String representing the lock descriptor
      * @see #useCustomLockDescriptors()
      * @see org.kuali.rice.krad.service.PessimisticLockService
      * @see org.kuali.rice.krad.service.impl.PessimisticLockServiceImpl
      */
     public String getCustomLockDescriptor(Person user);
 
     /**
      * Indicates whether this maintainable supports notes on the maintenance object
      *
      * <p>
      * Note this is only applicable if the data object is an instance of <code>BusinessObject</code>
      * </p>
      *
      * @return boolean true if notes are supported, false if they are not supported
      */
     public boolean isNotesEnabled();
 
     /**
      * Indicates whether the object being maintained is an instance of <code>ExternalizableBusinessObject</code>
      *
      * <p>
      * For the case when we want to maintain a business object that doesn't
      * necessarily map to a single table in the database or may doesn't map to a
      * database at all
      * </p>
      *
      * @return boolean true if the data object is an external business object, false if not
      */
     public boolean isExternalBusinessObject();
 
     /**
      * Invoked to prepare a new <code>BusinessObject</code> instance that is external
      *
      * @param businessObject - new business object instance to prepare
      */
     public void prepareExternalBusinessObject(BusinessObject businessObject);
 
     /**
      * Indicates whether their is an old data object for the maintainable
      *
      * @return boolean true if old data object exists, false if not
      */
     public boolean isOldDataObjectInDocument();
 
     /**
      * Hook for performing any custom processing before the maintenance object is saved
      */
     public void prepareForSave();
 
     /**
      * Hook for performing any custom processing after the maintenance object is retrieved from persistence storage
      */
     public void processAfterRetrieve();
 
     /**
      * Called during setupMaintenanceObject to retrieve the original dataObject that is being
      * edited or copied.  Override this method for non BusinessObject external persistence,
      * Maintainable objects that extend BO should override isExternalBusinessObject and
      * prepareBusinessObject instead.
      *
      * Do not override this method and isExternalBusinessObject.
      *
      * @param document document instance for the maintenance object
      * @param dataObjectKeys Map of keys for the requested object
      * @return the object identified by the dataObjectKeys
      */
     public Object retrieveObjectForEditOrCopy(MaintenanceDocument document, Map<String, String> dataObjectKeys);
 
     /**
      * Performs the setting of some attributes that might be necessary
      * if we're creating a new business object using on an existing business object.
      * For example, create a division Vendor based on an existing parent Vendor.
      * (Please see VendorMaintainableImpl.java)
      *
      * @param document - maintenance document instance this maintainable belong to
      * @param requestParameters - map of request parameters sent for the request
      */
     public void setupNewFromExisting(MaintenanceDocument document, Map<String, String[]> parameters);
 
     /**
      * Hook for performing any custom processing after the maintenance object has been setup for a copy action
      *
      * @param document - maintenance document instance this maintainable belong to
      * @param requestParameters - map of request parameters sent for the copy request
      */
     public void processAfterCopy(MaintenanceDocument document, Map<String, String[]> requestParameters);
 
     /**
      * Hook for performing any custom processing after the maintenance object has been setup for a edit action
      *
      * @param document - maintenance document instance this maintainable belong to
      * @param requestParameters - map of request parameters sent for the copy request
      */
     public void processAfterEdit(MaintenanceDocument document, Map<String, String[]> requestParameters);
 
     /**
      * Hook for performing any custom processing after the maintenance object has been setup for a new action
      *
      * @param document - maintenance document instance this maintainable belong to
      * @param requestParameters - map of request parameters sent for the copy request
      */
     public void processAfterNew(MaintenanceDocument document, Map<String, String[]> requestParameters);
 
     /**
      * Hook for performing any custom processing after each posting of the maintenance document (for various actions
      * like add line, refresh)
      *
      * @param document - maintenance document instance this maintainable belong to
      * @param requestParameters - map of request parameters from the post
      */
     public void processAfterPost(MaintenanceDocument document, Map<String, String[]> requestParameters);
 }

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		}