1 /**
2 * Copyright 2005-2013 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.data;
17
18 import java.util.List;
19 import java.util.Map;
20
21 import org.kuali.rice.krad.data.metadata.DataObjectMetadata;
22 import org.springframework.beans.BeanWrapper;
23 import org.springframework.beans.BeansException;
24
25 /**
26 * Wraps a data object and it's associated metadata. Provides additional utility methods to access portions of the data
27 * object based on the metadata that's available.
28 *
29 * <p>This interface extends the {@link BeanWrapper} interface provided by Spring which means property references can
30 * be nested and may be auto-grown depending on the setting of {@link #isAutoGrowNestedPaths()}</p>
31 *
32 * @param <T> the type of the data object instance which is wrapped by this accessor
33 */
34 public interface DataObjectWrapper<T> extends BeanWrapper {
35
36 /**
37 * Return the type of the wrapped data object.
38 *
39 * @return the type of the wrapped data instance, or <code>null</code> if no wrapped object has been set
40 */
41 @Override
42 Class<T> getWrappedClass();
43
44 /**
45 * Returns the data object wrapped by this accessor.
46 *
47 * @return the data object wrapped by this accessor
48 */
49 @Override
50 T getWrappedInstance();
51
52 /**
53 * Returns the metadata of the data object wrapped by this accessor.
54 *
55 * @return the metadata of the data object wrapped by this accessor
56 */
57 DataObjectMetadata getMetadata();
58
59 /**
60 * Get the current value of the specified property, but suppresses any
61 * {@link org.springframework.beans.NullValueInNestedPathException}s that would be thrown if a null value is
62 * encountered in a nested path and just returns null instead. This method is essentially a convenience method to
63 * prevent calling code from having to wrap calls to {@link #getPropertyValue(String)} with a try-catch block to
64 * check for NullValueInNestedPathExceptions.
65 *
66 * @param propertyName the name of the property to get the value of
67 * (may be a nested path and/or an indexed/mapped property)
68 * @return the value of the property, or null if any null values were encountered in nested paths
69 * @throws org.springframework.beans.InvalidPropertyException if there is no such property or
70 * if the property isn't readable
71 * @throws org.springframework.beans.PropertyAccessException if the property was valid but the
72 * accessor method failed
73 */
74 Object getPropertyValueNullSafe(String propertyName) throws BeansException;
75
76 /**
77 * Returns a map containing the values of the primary keys on this data object. The key of this map will be the
78 * attribute name of the primary key field on the data object and the value will the value of that primary key
79 * attribute on the data object wrapped by this accessor. If this data object has no primary key fields, an empty
80 * map will be returned.
81 *
82 * @return a map of primary key values where the key is the attribute name of the primary key field and the value
83 * is the value of that primary key field on the wrapped data object
84 */
85 Map<String, Object> getPrimaryKeyValues();
86
87 /**
88 * Determines if the given data object is equal to the data object wrapped by this accessor based on primary key
89 * values only. If the given object is null, then this method will always return false.
90 *
91 * @param object the object to compare to the data object wrapped by this accessor
92 * @return true if the primary key values are equal, false otherwise
93 */
94 boolean equalsByPrimaryKey(T object);
95
96 /**
97 * Returns whether all fields in the primary key are populated with a non-null/non-blank value.
98 */
99 boolean areAllPrimaryKeyAttributesPopulated();
100
101 /**
102 * Returns whether any fields in the primary key is populated with a non-null/non-blank value.
103 */
104 boolean areAnyPrimaryKeyAttributesPopulated();
105
106 /**
107 * Returns the list of field of the primary key which have a null or blank value.
108 */
109 List<String> getUnpopulatedPrimaryKeyAttributeNames();
110
111 /**
112 * Get property type for property name on object, this can be a nested property and method will
113 * recursively use the metadata to find type.
114 * @param objectType - Root object type
115 * @param propertyName - Property name
116 * @return Class of propertyName
117 */
118 Class<?> getPropertyTypeNullSafe(Class<?> objectType, String propertyName);
119 }