001: /*
002: * Copyright 2006-2007 The Kuali Foundation.
003: *
004: * Licensed under the Educational Community License, Version 1.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/ecl1.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: */
016: package org.kuali.core.service;
017:
018: import java.util.List;
019: import java.util.Map;
020:
021: import org.kuali.core.bo.BusinessObjectRelationship;
022: import org.kuali.core.bo.PersistableBusinessObject;
023: import org.kuali.core.exceptions.ClassNotPersistableException;
024: import org.kuali.core.exceptions.ObjectNotABusinessObjectRuntimeException;
025: import org.kuali.core.util.ForeignKeyFieldsPopulationState;
026:
027: /**
028: * This interface defines methods that a Persistence Service must provide. PersistenceMetadataService provides access to
029: * persistence-layer information about persistable classes.
030: */
031: public interface PersistenceStructureService {
032: /**
033: * @param clazz
034: * @return true if the given Class is persistable (is known to OJB)
035: */
036: public boolean isPersistable(Class clazz);
037:
038: /**
039: * @param clazz Class whose primary key field names you want to list
040: * @return a List of field names for the given class which are designated as key fields in the OJB repository file
041: * @throws IllegalArgumentException if the given Class is null
042: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
043: */
044: public List listPrimaryKeyFieldNames(Class clazz);
045:
046: /**
047: * @param clazz Class whose field names you want to list
048: * @return a List of field names for the given class in the OJB repository file
049: * @throws IllegalArgumentException if the given Class is null
050: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
051: */
052: public List listFieldNames(Class clazz);
053:
054: /**
055: * @param clazz whose primary key field name, anonymous key marking is requested for
056: * @return a Map containing the primary key name as the key and Boolean indicating whether or not the pk is marked as anonymous
057: * in the obj repository file
058: * @throws IllegalArgumentException if the given Object is null
059: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
060: */
061: public Map getPrimaryKeyFieldAnonymousMarking(Class clazz);
062:
063: /**
064: *
065: * This method returns a List of Strings, each containing the field name of one of the primary keys, as defined in the ORM
066: * layer.
067: *
068: * @param clazz - Class whose primary key field names are requested
069: * @return A List of Strings, each containing the field name of the primary key
070: * @throws IllegalArgumentException if the given Object is null
071: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
072: *
073: */
074: public List getPrimaryKeys(Class clazz);
075:
076: /**
077: * @param persistableObject
078: * @return true if all primary key fields of the string have a non-null (and non-empty, for Strings) value
079: * @throws IllegalArgumentException if the given Object is null
080: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
081: */
082: public boolean hasPrimaryKeyFieldValues(Object persistableObject);
083:
084: /**
085: * @param persistableObject object whose primary key fields need to be cleared
086: * @return the object whose primary key fields have just been cleared
087: * @throws IllegalArgumentException if the given Object is null
088: * @throws ClassNotPersistableException if the given object is of a type not described in the OJB repository
089: */
090: public Object clearPrimaryKeyFields(Object persistableObject);
091:
092: /**
093: * @param superclazz class whose persistable subclasses (or interface whose implementors) will be returned
094: * @return a List of persistable Classes which extend or implement the given Class
095: * @throws IllegalArgumentException if the given class is null
096: */
097: public List listPersistableSubclasses(Class super clazz);
098:
099: /**
100: * @param persistableClass
101: * @param attributeName Name of an attribute used in the relationship
102: * @return BusinessObjectRelationship object containing information about the object type related via the named relationship of the
103: * given class, or null if the persistence service can find no object type related via the named relationship
104: * @throws IllegalArgumentException if the given Class is null
105: * @throws IllegalArgumentException if the given relationshipName is blanks
106: * @throws ClassNotPersistableException if the given Class is a type not described in the OJB repository
107: */
108: public Map<String, BusinessObjectRelationship> getRelationshipMetadata(
109: Class persistableClass, String attributeName,
110: String attributePrefix);
111:
112: public Map<String, BusinessObjectRelationship> getRelationshipMetadata(
113: Class persistableClass, String attributeName);
114:
115: public String getForeignKeyFieldName(Class persistableObjectClass,
116: 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(
127: Class persistableObjectClass, String attributeName);
128:
129: /**
130: *
131: * This method will return a Map of all the foreign key fields and the corresponding primary key fields for a given reference.
132: *
133: * The Map structure is: Key(String fkFieldName) => Value(String pkFieldName)
134: *
135: * @param clazz - Class that contains the named reference
136: * @param attributeName - Name of the member that is the reference you want foreign keys for
137: * @return returns a Map populated as described above, with one entry per foreign key field
138: *
139: */
140: public Map getForeignKeysForReference(Class clazz,
141: 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: * @throws ObjectNotABusinessObjectRuntimeException - if the class specified is not a descendent of PersistableBusinessObject, or the class of the
153: * named attribute is not descended from PersistableBusinessObject
154: *
155: */
156: public Class getBusinessObjectAttributeClass(Class clazz,
157: String attributeName)
158: throws ObjectNotABusinessObjectRuntimeException;
159:
160: /**
161: * Builds a map of reference pk attributes back to the foreign key.
162: *
163: * @param persistableObjectClass
164: * @return
165: */
166: public Map getNestedForeignKeyMap(Class persistableObjectClass);
167:
168: /**
169: *
170: * This method checks the foreign keys for a reference on a given BO, and tests that all fk fields are populated if any are
171: * populated.
172: *
173: * 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
174: * if they all have values. It also keeps a list of all the fieldNames that do not have values.
175: *
176: * @param bo - A populated BusinessObject descendent. Must contain an attributed named referenceName.
177: * @param referenceName - The name of the field that is a reference we are analyzing.
178: * @return A populated ForeignKeyFieldsPopulation object which represents the state of population for the foreign key fields.
179: */
180: public ForeignKeyFieldsPopulationState getForeignKeyFieldsPopulationState(
181: PersistableBusinessObject bo, String referenceName);
182:
183: /**
184: *
185: * This method uses the persistence layer to determine the list of reference objects contained within this parent object. For
186: * example, an Account object contains sub-objects such as Chart, as well as the key that connects the two, String
187: * chartOfAccountsCode.
188: *
189: * The return structure is: Map<referenceName, referenceClass>.
190: *
191: * As an example, an Account object passed into this would return:
192: *
193: * 0:['chartOfAccounts', org.kuali.module.chart.bo.Chart] 1:['organization', org.kuali.module.chart.bo.Org] etc.
194: *
195: * @param boClass Class that would like to be analyzed for reference names
196: * @return Map containing the reference name for the key as a string, and the class of the reference as the value. If the object
197: * contains no references, then this Map will be empty.
198: *
199: */
200: public Map<String, Class> listReferenceObjectFields(Class boClass);
201:
202: /**
203: *
204: * This method uses the persistence layer to determine the list of reference objects contained within this parent object. For
205: * example, an Account object contains sub-objects such as Chart, as well as the key that connects the two, String
206: * chartOfAccountsCode.
207: *
208: * The return structure is: Map<referenceName, referenceClass>.
209: *
210: * As an example, an Account object passed into this would return:
211: *
212: * 0:['chartOfAccounts', org.kuali.module.chart.bo.Chart] 1:['organization', org.kuali.module.chart.bo.Org] etc.
213: *
214: * @param bo BusinessObject (or subclass) instance that would like to be analyzed for reference names
215: * @return Map containing the reference name for the key as a string, and the class of the reference as the value. If the object
216: * contains no references, then this Map will be empty.
217: *
218: */
219: public Map<String, Class> listReferenceObjectFields(
220: PersistableBusinessObject bo);
221:
222: public Map<String, Class> listCollectionObjectTypes(Class boClass);
223:
224: public Map<String, Class> listCollectionObjectTypes(
225: PersistableBusinessObject bo);
226:
227: /**
228: * Returns whether there is a reference defined in the persistence layer with the given name.
229: * Depending on the type of underlying persistence mechanism, this method may or may not return true
230: * when the referenceName really refers to a collection type.
231: *
232: * To determine whether a reference is a collection, use the hasCollection method instead.
233: *
234: * In OJB, this method will return false for collection references.
235: *
236: * @param boClass
237: * @param referenceName
238: * @return
239: */
240: public boolean hasReference(Class boClass, String referenceName);
241:
242: /**
243: * Returns whether BOs of the given class have a collection defined within them with the given collection name.
244: *
245: * @param boClass
246: * @param collectionName
247: * @return
248: */
249: public boolean hasCollection(Class boClass, String collectionName);
250:
251: public boolean isReferenceUpdatable(Class boClass,
252: String referenceName);
253:
254: public boolean isCollectionUpdatable(Class boClass,
255: String collectionName);
256:
257: /**
258: * Returns a listing of the FK field mappings between a BO and the elements in a collection. Since this is in effect a
259: * 1:n relationship, only the complete primary key set of the parent BO will be returned.
260: *
261: * for example, assume Account BO has an "acctNbrForAcct" PK, and it has a list of subAccounts,
262: * each of which has a ("acctNbrForSubAcct", "subAcctNbr") PK pair.
263: *
264: * the Account PK will be mapped to some of the PK fields of the element list.
265: * When called on the Account BO class with the "subAccounts" collection name, his method should return
266: * a map with a mapping of "acctNbrForAcct" (key) => "acctNbrForSubAcct"
267: *
268: * @param boClass
269: * @param collectionName
270: * @return
271: */
272: public Map<String, String> getInverseForeignKeysForCollection(
273: Class boClass, String collectionName);
274:
275: }
|