1 /**
2 * Copyright 2005-2014 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.service;
17
18 import org.kuali.rice.krad.bo.DataObjectRelationship;
19 import org.kuali.rice.krad.bo.PersistableBusinessObject;
20 import org.kuali.rice.krad.bo.PersistableBusinessObjectExtension;
21 import org.kuali.rice.krad.util.ForeignKeyFieldsPopulationState;
22
23 import java.util.List;
24 import java.util.Map;
25
26 /**
27 * Defines methods that a Persistence Service must provide. PersistenceMetadataService provides access to
28 * persistence-layer information about persistable classes
29 *
30 * @author Kuali Rice Team (rice.collab@kuali.org)
31 */
32 public interface PersistenceStructureService {
33 /**
34 * @param clazz
35 * @return true if the given Class is persistable (is known to OJB)
36 */
37 public boolean isPersistable(Class clazz);
38
39 /**
40 * @param clazz Class whose primary key field names you want to list
41 * @return a List of field names for the given class which are designated as key fields in the OJB repository file
42 * @throws IllegalArgumentException if the given Class is null
43 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
44 */
45 public List listPrimaryKeyFieldNames(Class clazz);
46
47
48 /**
49 * @param clazz Class whose field names you want to list
50 * @return a List of field names for the given class in the OJB repository file
51 * @throws IllegalArgumentException if the given Class is null
52 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
53 */
54 public List listFieldNames(Class clazz);
55
56
57 /**
58 * @param clazz whose primary key field name, anonymous key marking is requested for
59 * @return a Map containing the primary key name as the key and Boolean indicating whether or not the pk is marked as anonymous
60 * in the obj repository file
61 * @throws IllegalArgumentException if the given Object is null
62 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
63 */
64 /* No references - https://test.kuali.org/confluence/x/SYCf
65 public Map getPrimaryKeyFieldAnonymousMarking(Class clazz);
66 */
67
68 /**
69 *
70 * This method returns a List of Strings, each containing the field name of one of the primary keys, as defined in the ORM
71 * layer.
72 *
73 * @param clazz - Class whose primary key field names are requested
74 * @return A List of Strings, each containing the field name of the primary key
75 * @throws IllegalArgumentException if the given Object is null
76 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
77 *
78 */
79 public List getPrimaryKeys(Class clazz);
80
81 /**
82 * @param persistableObject
83 * @return true if all primary key fields of the string have a non-null (and non-empty, for Strings) value
84 * @throws IllegalArgumentException if the given Object is null
85 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
86 */
87 public boolean hasPrimaryKeyFieldValues(Object persistableObject);
88
89 /**
90 * @param persistableObject object whose primary key fields need to be cleared
91 * @return the object whose primary key fields have just been cleared
92 * @throws IllegalArgumentException if the given Object is null
93 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given object is of a type not described in the OJB repository
94 */
95 public Object clearPrimaryKeyFields(Object persistableObject);
96
97
98 /**
99 * @param superclazz class whose persistable subclasses (or interface whose implementors) will be returned
100 * @return a List of persistable Classes which extend or implement the given Class
101 * @throws IllegalArgumentException if the given class is null
102 */
103 public List listPersistableSubclasses(Class superclazz);
104
105 /**
106 * @param persistableClass
107 * @param attributeName Name of an attribute used in the relationship
108 * @return BusinessObjectRelationship object containing information about the object type related via the named relationship of the
109 * given class, or null if the persistence service can find no object type related via the named relationship
110 * @throws IllegalArgumentException if the given Class is null
111 * @throws IllegalArgumentException if the given relationshipName is blanks
112 * @throws org.kuali.rice.krad.exception.ClassNotPersistableException if the given Class is a type not described in the OJB repository
113 */
114 public Map<String,DataObjectRelationship> getRelationshipMetadata(Class persistableClass, String attributeName, String attributePrefix );
115
116 public Map<String,DataObjectRelationship> getRelationshipMetadata(Class persistableClass, String attributeName);
117
118 public String getForeignKeyFieldName(Class persistableObjectClass, String attributeName, String pkName);
119
120 /**
121 * Attempts to match the attribute name given for the class as a fk field to a reference class defined in the repository. Since
122 * a fk field can have references to many tables, this returns a list of all found.
123 *
124 * @param persistableObjectClass
125 * @param attributeName
126 * @return Map with attribue name as key of map and class as value
127 */
128 public Map<String,Class> getReferencesForForeignKey(Class persistableObjectClass, String attributeName);
129
130 /**
131 *
132 * This method will return a Map of all the foreign key fields and the corresponding primary key fields for a given reference.
133 *
134 * The Map structure is: Key(String fkFieldName) => Value(String pkFieldName)
135 *
136 * @param clazz - Class that contains the named reference
137 * @param attributeName - Name of the member that is the reference you want foreign keys for
138 * @return returns a Map populated as described above, with one entry per foreign key field
139 *
140 */
141 public Map getForeignKeysForReference(Class clazz, String attributeName);
142
143 /**
144 *
145 * This method is a PersistableBusinessObject specifific utility method. If the Class clazz passed in is a descendent of PersistableBusinessObject,
146 * and if the attributeName specified exists on the object, then the class of this
147 * attribute named will be returned.
148 *
149 * @param clazz - class to be examined for the attribute's class
150 * @param attributeName - name of the class' attribute to be examined
151 * @return the class of the named attribute, if no exceptions occur
152 */
153 public Class<? extends PersistableBusinessObjectExtension> getBusinessObjectAttributeClass(Class<? extends PersistableBusinessObject> clazz, String attributeName);
154
155 /**
156 * Builds a map of reference pk attributes back to the foreign key.
157 *
158 * @param persistableObjectClass
159 * @return
160 */
161 public Map getNestedForeignKeyMap(Class persistableObjectClass);
162
163 /**
164 *
165 * This method checks the foreign keys for a reference on a given BO, and tests that all fk fields are populated if any are
166 * populated.
167 *
168 * In other words, for a given reference, it finds all the attributes of the BO that make up the foreign keys, and checks to see
169 * if they all have values. It also keeps a list of all the fieldNames that do not have values.
170 *
171 * @param bo - A populated BusinessObject descendent. Must contain an attributed named referenceName.
172 * @param referenceName - The name of the field that is a reference we are analyzing.
173 * @return A populated ForeignKeyFieldsPopulation object which represents the state of population for the foreign key fields.
174 */
175 public ForeignKeyFieldsPopulationState getForeignKeyFieldsPopulationState(PersistableBusinessObject bo, String referenceName);
176
177 /**
178 *
179 * This method uses the persistence layer to determine the list of reference objects contained within this parent object. For
180 * example, an Account object contains sub-objects such as Chart, as well as the key that connects the two, String
181 * chartOfAccountsCode.
182 *
183 * The return structure is: Map<referenceName, referenceClass>.
184 *
185 * As an example, an Account object passed into this would return:
186 *
187 * 0:['chartOfAccounts', org.kuali.module.chart.bo.Chart] 1:['organization', org.kuali.module.chart.bo.Org] etc.
188 *
189 * @param boClass Class that would like to be analyzed for reference names
190 * @return Map containing the reference name for the key as a string, and the class of the reference as the value. If the object
191 * contains no references, then this Map will be empty.
192 *
193 */
194 public Map<String, Class> listReferenceObjectFields(Class boClass);
195
196 /**
197 *
198 * This method uses the persistence layer to determine the list of reference objects contained within this parent object. For
199 * example, an Account object contains sub-objects such as Chart, as well as the key that connects the two, String
200 * chartOfAccountsCode.
201 *
202 * The return structure is: Map<referenceName, referenceClass>.
203 *
204 * As an example, an Account object passed into this would return:
205 *
206 * 0:['chartOfAccounts', org.kuali.module.chart.bo.Chart] 1:['organization', org.kuali.module.chart.bo.Org] etc.
207 *
208 * @param bo BusinessObject (or subclass) instance that would like to be analyzed for reference names
209 * @return Map containing the reference name for the key as a string, and the class of the reference as the value. If the object
210 * contains no references, then this Map will be empty.
211 *
212 */
213 public Map<String, Class> listReferenceObjectFields(PersistableBusinessObject bo);
214
215 public Map<String, Class> listCollectionObjectTypes(Class boClass);
216 public Map<String, Class> listCollectionObjectTypes(PersistableBusinessObject bo);
217
218 /**
219 * Returns whether there is a reference defined in the persistence layer with the given name.
220 * Depending on the type of underlying persistence mechanism, this method may or may not return true
221 * when the referenceName really refers to a collection type.
222 *
223 * To determine whether a reference is a collection, use the hasCollection method instead.
224 *
225 * In OJB, this method will return false for collection references.
226 *
227 * @param boClass
228 * @param referenceName
229 * @return
230 */
231 public boolean hasReference(Class boClass, String referenceName);
232
233
234 /**
235 * Returns whether BOs of the given class have a collection defined within them with the given collection name.
236 *
237 * @param boClass
238 * @param collectionName
239 * @return
240 */
241 public boolean hasCollection(Class boClass, String collectionName);
242
243 public boolean isReferenceUpdatable(Class boClass, String referenceName);
244 public boolean isCollectionUpdatable(Class boClass, String collectionName);
245
246 /**
247 * Returns a listing of the FK field mappings between a BO and the elements in a collection. Since this is in effect a
248 * 1:n relationship, only the complete primary key set of the parent BO will be returned.
249 *
250 * for example, assume Account BO has an "acctNbrForAcct" PK, and it has a list of subAccounts,
251 * each of which has a ("acctNbrForSubAcct", "subAcctNbr") PK pair.
252 *
253 * the Account PK will be mapped to some of the PK fields of the element list.
254 * When called on the Account BO class with the "subAccounts" collection name, his method should return
255 * a map with a mapping of "acctNbrForAcct" (key) => "acctNbrForSubAcct"
256 *
257 * @param boClass
258 * @param collectionName
259 * @return
260 */
261 public Map<String, String> getInverseForeignKeysForCollection(Class boClass, String collectionName);
262
263 /**
264 * Returns the name of the table underlying the business object class
265 *
266 * @param boClass
267 * @return
268 */
269 public String getTableName(Class<? extends PersistableBusinessObject> boClass);
270 }