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