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.service;
17
18 import org.kuali.rice.krad.bo.DataObjectRelationship;
19 import org.kuali.rice.krad.datadictionary.RelationshipDefinition;
20
21 import java.util.List;
22 import java.util.Map;
23
24 /**
25 * Provides metadata such as relationships and key fields for data objects
26 *
27 * <p>
28 * Service provides a facade to the various services for retrieving metadata
29 * within the framework, such as the <code>DataDictionaryService</code> and
30 * the <code>PersistenceService</code>
31 * </p>
32 *
33 * @author Kuali Rice Team (rice.collab@kuali.org)
34 */
35 public interface DataObjectMetaDataService {
36
37 /**
38 * Checks the DataDictionary and OJB Repository File to determine the primary
39 * fields names for a given class.
40 *
41 * @param clazz - the Class to check for primary keys
42 * @return a list of the primary key field names or an empty list if none are found
43 */
44 public List<String> listPrimaryKeyFieldNames(Class<?> clazz);
45
46 /**
47 * Determines the primary keys for the class of the given object, then for each
48 * key field retrieves the value from the object instance and populates the return
49 * map with the primary key name as the map key and the object value as the map value
50 *
51 * @param dataObject - object whose primary key field name,value pairs you want
52 * @return a Map containing the names and values of fields for the given class which
53 * are designated as key fields in the OJB repository file or DataDictionary
54 * @throws IllegalArgumentException if the given Object is null
55 */
56 public Map<String, ?> getPrimaryKeyFieldValues(Object dataObject);
57
58 /**
59 * Determines the primary keys for the class of the given object, then for each
60 * key field retrieves the value from the object instance and populates the return
61 * map with the primary key name as the map key and the object value as the map value
62 *
63 * @param dataObject - object whose primary key field name,value pairs you want
64 * @param sortFieldNames - if true, the returned Map will iterate through its entries sorted by fieldName
65 * @return a Map containing the names and values of fields for the given class which
66 * are designated as key fields in the OJB repository file or DataDictionary
67 * @throws IllegalArgumentException if the given Object is null
68 */
69 public Map<String, ?> getPrimaryKeyFieldValues(Object dataObject, boolean sortFieldNames);
70
71 /**
72 * Compares two dataObject instances for equality of type and key values using toString()
73 * of each value for comparison purposes.
74 *
75 * @param do1
76 * @param do2
77 * @return boolean indicating whether the two objects are equal.
78 */
79 public boolean equalsByPrimaryKeys(Object do1, Object do2);
80
81 /**
82 * Attempts to find a relationship for the given attribute within the given
83 * data object
84 *
85 * <p>
86 * First the data dictionary is queried to find any relationship definitions
87 * setup that include the attribute, if found the
88 * <code>BusinessObjectRetationship</code> is build from that. If not and
89 * the data object class is persistent, relationships are retrieved from the
90 * persistence service. Nested attributes are handled in addition to
91 * external business objects. If multiple relationships are found, the one
92 * that contains the least amount of joining keys is returned
93 * </p>
94 *
95 * @param dataObject - data object instance that contains the attribute
96 * @param dataObjectClass - class for the data object that contains the attribute
97 * @param attributeName - property name for the attribute
98 * @param attributePrefix - property prefix for the attribute
99 * @param keysOnly - indicates whether only primary key fields should be returned
100 * in the relationship
101 * @param supportsLookup - indicates whether the relationship should support lookup
102 * @param supportsInquiry - indicates whether the relationship should support inquiry
103 * @return BusinessObjectRelationship for the attribute, or null if not
104 * found
105 */
106 public DataObjectRelationship getDataObjectRelationship(Object dataObject, Class<?> dataObjectClass,
107 String attributeName, String attributePrefix, boolean keysOnly, boolean supportsLookup,
108 boolean supportInquiry);
109
110 /**
111 * Fetches the RelationshipDefinition for the attribute with the given name within
112 * the given class
113 *
114 * @param dataObjectClass - data object class that contains the attribute
115 * @param attributeName - property name for the attribute
116 * @return RelationshipDefinition for the attribute, or null if not found
117 */
118 public RelationshipDefinition getDictionaryRelationship(Class<?> dataObjectClass, String attributeName);
119
120 /**
121 * Returns the attribute to be associated with for object level markings. This would
122 * be the field chosen for inquiry links etc.
123 *
124 * @param dataObjectClass - data object class to obtain title attribute of
125 * @return property name of title attribute or null if data object entry not found
126 * @throws IllegalArgumentException if the given Class is null
127 */
128 public String getTitleAttribute(Class<?> dataObjectClass);
129
130 /**
131 * Indicates whether notes are supported by the given data object class, currently this
132 * can only be true for business objects
133 *
134 * @param dataObjectClass - class for data object to check
135 * @return boolean true if notes are supported for data object, false if notes are not supported
136 */
137 public boolean areNotesSupported(Class dataObjectClass);
138
139 /**
140 * Builds a string that uniquely identifiers the data object instance
141 *
142 * <p>
143 * Based on the metadata available for the class of the data object, the values for fields that uniquely
144 * identify an instance are concatenated together into one string. For general data objects these fields
145 * will be the primary key fields defined in the data dictionary. For the case of objects with type
146 * <code>PersistableBusinessObject</code>, the object id field will be used.
147 * </p>
148 *
149 * @param dataObject - data object instance to build identifier string for
150 * @return String identifier string for data object
151 */
152 public String getDataObjectIdentifierString(Object dataObject);
153 }