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.bo;
17
18 import org.kuali.rice.core.api.mo.common.GloballyUnique;
19 import org.kuali.rice.core.api.mo.common.Versioned;
20
21 import java.util.Collection;
22 import java.util.List;
23 import java.util.UUID;
24
25 /**
26 * Declares a common interface for all {@link BusinessObject} classes which can have their
27 * state persisted. A business object which is persistable defines some additional methods
28 * which allow for various operations to be executed that relate to the persistent nature of
29 * the business object. A persistable business object also has some additional data
30 * attributes which include the version number, the object id, and the extension.
31 *
32 * <p>The version number indicates the version of the business object when it was retrieved
33 * from persistent storage. This allows for services to check this version number
34 * during persistence operations to prevent silent overwrites of business object state.
35 * These kinds of scenarios might arise as a result of concurrent modification to the business
36 * object in the persistent store (i.e. two web application users updating the same record
37 * in a database). The kind of check which would be performed using the version number is commonly
38 * referred to as "optimistic locking".
39 *
40 * <p>The object id represents a globally unique identifier for the business object. In practice,
41 * this can be used by other portions of the system to link to persistable business objects which
42 * might be stored in different locations or even different persistent data stores. In general, it
43 * is not the responsibility of the client who implements a persistable business object to handle
44 * generating this value. The framework will handle this automatically at the point in time when
45 * the business object is persisted. If the client does need to do this themselves, however, care
46 * should be taken that an appropriate globally unique value generator algorithm is used
47 * (such as the one provided by {@link UUID}).
48 *
49 * <p>The extension object is primarily provided for the purposes of allowing implementer
50 * customization of the business object without requiring the original business object to be
51 * modified. The additional {@link PersistableBusinessObjectExtension} which is linked with the
52 * parent business object can contain additional data attributes and methods. The framework will
53 * automatically request that this extension object be persisted when the parent business object
54 * is persisted. This is generally the most useful in cases where an application is defining
55 * business objects that will be used in redistributable software packages (such as the
56 * actual Kuali Foundation projects themselves). If using the framework for the purposes
57 * of implementing an internal application, the use of a business object extensions
58 * is likely unnecessary.
59 *
60 * @author Kuali Rice Team (rice.collab@kuali.org)
61 */
62 public interface PersistableBusinessObject extends BusinessObject, Versioned, GloballyUnique {
63
64 /**
65 * Sets the business object's version number. It is rarely advisable
66 * for client code to manually set this value as the framework should
67 * generally handle the management of version numbers internally.
68 *
69 * @param versionNumber the version number to set on this business object
70 */
71 public void setVersionNumber(Long versionNumber);
72
73 /**
74 * Sets the unique identifier for the object
75 *
76 * @param objectId
77 */
78 public void setObjectId(String objectId);
79
80 public PersistableBusinessObjectExtension getExtension();
81
82 public void setExtension(PersistableBusinessObjectExtension extension);
83
84 /**
85 * @see BusinessObject#refresh()
86 */
87 public abstract void refreshNonUpdateableReferences();
88
89 /**
90 * This method is used to refresh a reference object that hangs off of a document. For example, if the attribute's keys were
91 * updated for a reference object, but the reference object wasn't, this method would go out and retrieve the reference object.
92 *
93 * @param referenceObjectName
94 */
95 public abstract void refreshReferenceObject(String referenceObjectName);
96
97 /**
98 * If this method is not implemented appropriately for PersistableBusinessObject with collections, then PersistableBusinessObject with collections will not persist deletions correctly.
99 * Elements that have been deleted will reappear in the DB after retrieval.
100 *
101 * @return List of collections which need to be monitored for changes by OJB
102 */
103 public List<Collection<PersistableBusinessObject>> buildListOfDeletionAwareLists();
104
105 /**
106 * Returns the boolean indicating whether this record is a new record of a maintenance document collection.
107 * Used to determine whether the record can be deleted on the document.
108 */
109 public boolean isNewCollectionRecord();
110
111 /**
112 * Sets the boolean indicating this record is a new record of a maintenance document collection.
113 * Used to determine whether the record can be deleted on the document.
114 */
115 public void setNewCollectionRecord(boolean isNewCollectionRecord);
116
117 /**
118 * Hook to link in any editable user fields.
119 */
120 public void linkEditableUserFields();
121
122
123
124 }