org.kuali.rice.krad.data

Interface DataObjectWrapper<T>

Type Parameters:

T - the type of the data object instance which is wrapped by this accessor

All Superinterfaces:

org.springframework.beans.BeanWrapper, org.springframework.beans.ConfigurablePropertyAccessor, org.springframework.beans.PropertyAccessor, org.springframework.beans.PropertyEditorRegistry, org.springframework.beans.TypeConverter

All Known Implementing Classes:

DataObjectWrapperBase

public interface DataObjectWrapper<T>
extends org.springframework.beans.BeanWrapper

Wraps a data object and it's associated metadata. Provides additional utility methods to access portions of the data object based on the metadata that's available.

This interface extends the BeanWrapper interface provided by Spring which means property references can be nested and may be auto-grown depending on the setting of BeanWrapper.isAutoGrowNestedPaths()

Field Summary

Fields inherited from interface org.springframework.beans.PropertyAccessor

NESTED_PROPERTY_SEPARATOR, NESTED_PROPERTY_SEPARATOR_CHAR, PROPERTY_KEY_PREFIX, PROPERTY_KEY_PREFIX_CHAR, PROPERTY_KEY_SUFFIX, PROPERTY_KEY_SUFFIX_CHAR

Method Summary

Methods

Modifier and Type	Method and Description
boolean	areAllPrimaryKeyAttributesPopulated() Returns whether all fields in the primary key are populated with a non-null/non-blank value.
boolean	areAnyPrimaryKeyAttributesPopulated() Returns whether any fields in the primary key is populated with a non-null/non-blank value.
boolean	equalsByPrimaryKey(T object) Determines if the given data object is equal to the data object wrapped by this accessor based on primary key values only.
void	fetchRelationship(String relationshipName) Fetches and populates the value for the relationship with the given name on the wrapped data object.
void	fetchRelationship(String relationshipName, boolean useForeignKeyAttribute, boolean nullifyDanglingRelationship) Fetches and populates the value for the relationship with the given name on the wrapped object.
Object	getForeignKeyAttributeValue(String relationshipName) As getForeignKeyValue(String) except only returns the value for the "attribute" foreign key value.
Object	getForeignKeyValue(String relationshipName) Returns the value of the foreign key for the specified relationship on the wrapped data object, or null if the wrapped object has no value for the requested foreign key.
DataObjectMetadata	getMetadata() Returns the metadata of the data object wrapped by this accessor.
Object	getPrimaryKeyValue() Returns the value of the primary key for the wrapped data object, or null if the wrapped object has no value for it's primary key.
Map<String,Object>	getPrimaryKeyValues() Returns a map containing the values of the primary keys on this data object.
Class<?>	getPropertyTypeNullSafe(Class<?> objectType, String propertyName) Get property type for property name on object, this can be a nested property and method will recursively use the metadata to find type.
Object	getPropertyValueNullSafe(String propertyName) Get the current value of the specified property, but suppresses any NullValueInNestedPathExceptions that would be thrown if a null value is encountered in a nested path and just returns null instead.
List<String>	getUnpopulatedPrimaryKeyAttributeNames() Returns the list of field of the primary key which have a null or blank value.
Class<T>	getWrappedClass() Return the type of the wrapped data object.
T	getWrappedInstance() Returns the data object wrapped by this accessor.
void	linkChanges(Set<String> changedPropertyPaths) Executes reference linking using the wrapped object as the root and the set of changed paths.
void	linkForeignKeys(boolean onlyLinkReadOnly) Links foreign key values on the wrapped data object and then recurses through all child relationships and collections which are cascaded during persistence and does the same.
void	linkForeignKeys(String relationshipName, boolean onlyLinkReadOnly) Links foreign keys non-recursively using the relationship with the given name on the wrapped data object.
void	materializeReferencedObjects(MaterializeOption... options) Fetches and populates referenced objects within the wrapped object.
void	materializeReferencedObjectsToDepth(int maxDepth, MaterializeOption... options) Fetches and populates referenced objects within the wrapped object.

Methods inherited from interface org.springframework.beans.BeanWrapper

getAutoGrowCollectionLimit, getPropertyDescriptor, getPropertyDescriptors, isAutoGrowNestedPaths, setAutoGrowCollectionLimit, setAutoGrowNestedPaths

Methods inherited from interface org.springframework.beans.ConfigurablePropertyAccessor

getConversionService, isExtractOldValueForEditor, setConversionService, setExtractOldValueForEditor

Methods inherited from interface org.springframework.beans.PropertyAccessor

getPropertyType, getPropertyTypeDescriptor, getPropertyValue, isReadableProperty, isWritableProperty, setPropertyValue, setPropertyValue, setPropertyValues, setPropertyValues, setPropertyValues, setPropertyValues

Methods inherited from interface org.springframework.beans.PropertyEditorRegistry

findCustomEditor, registerCustomEditor, registerCustomEditor

Methods inherited from interface org.springframework.beans.TypeConverter

convertIfNecessary, convertIfNecessary, convertIfNecessary

Method Detail

getWrappedClass

Class<T> getWrappedClass()

Return the type of the wrapped data object.

Specified by:

getWrappedClass in interface org.springframework.beans.BeanWrapper

Returns:

the type of the wrapped data instance, or null if no wrapped object has been set

getWrappedInstance

T getWrappedInstance()

Returns the data object wrapped by this accessor.

Specified by:

getWrappedInstance in interface org.springframework.beans.BeanWrapper

Returns:

the data object wrapped by this accessor

getMetadata

DataObjectMetadata getMetadata()

Returns the metadata of the data object wrapped by this accessor.

Returns:

the metadata of the data object wrapped by this accessor

getPropertyValueNullSafe

Object getPropertyValueNullSafe(String propertyName)
                                throws org.springframework.beans.BeansException

Get the current value of the specified property, but suppresses any NullValueInNestedPathExceptions that would be thrown if a null value is encountered in a nested path and just returns null instead. This method is essentially a convenience method to prevent calling code from having to wrap calls to PropertyAccessor.getPropertyValue(String) with a try-catch block to check for NullValueInNestedPathExceptions.

Parameters:

propertyName - the name of the property to get the value of (may be a nested path and/or an indexed/mapped property)

Returns:

the value of the property, or null if any null values were encountered in nested paths

Throws:

org.springframework.beans.InvalidPropertyException - if there is no such property or if the property isn't readable

org.springframework.beans.PropertyAccessException - if the property was valid but the accessor method failed

org.springframework.beans.BeansException

getPrimaryKeyValues

Map<String,Object> getPrimaryKeyValues()

Returns a map containing the values of the primary keys on this data object. The key of this map will be the attribute name of the primary key field on the data object and the value will the value of that primary key attribute on the data object wrapped by this accessor. If this data object has no primary key fields, an empty map will be returned.

Returns:

a map of primary key values where the key is the attribute name of the primary key field and the value is the value of that primary key field on the wrapped data object

getPrimaryKeyValue

Object getPrimaryKeyValue()

Returns the value of the primary key for the wrapped data object, or null if the wrapped object has no value for it's primary key.

If the primary key consists of multiple values, this method will return an instance of CompoundKey, otherwise the single primary key value will be returned. If the primary key consists of multiple values but those values are only partially populated, this method will return null.

Returns:

the single primary key value for the wrapped data object, or null if it has no fully-populated primary key value

equalsByPrimaryKey

boolean equalsByPrimaryKey(T object)

Determines if the given data object is equal to the data object wrapped by this accessor based on primary key values only. If the given object is null, then this method will always return false.

Parameters:

object - the object to compare to the data object wrapped by this accessor

Returns:

true if the primary key values are equal, false otherwise

areAllPrimaryKeyAttributesPopulated

boolean areAllPrimaryKeyAttributesPopulated()

Returns whether all fields in the primary key are populated with a non-null/non-blank value.

areAnyPrimaryKeyAttributesPopulated

boolean areAnyPrimaryKeyAttributesPopulated()

Returns whether any fields in the primary key is populated with a non-null/non-blank value.

getUnpopulatedPrimaryKeyAttributeNames

List<String> getUnpopulatedPrimaryKeyAttributeNames()

Returns the list of field of the primary key which have a null or blank value.

getForeignKeyValue

Object getForeignKeyValue(String relationshipName)

Returns the value of the foreign key for the specified relationship on the wrapped data object, or null if the wrapped object has no value for the requested foreign key.

If the foreign key is a compound/composite and consists of multiple values, this method will return an instance of CompoundKey, otherwise the single foreign key value will be returned. If the foreign key is compound/composite but those values are only partially populated, this method will return null.

It is common that a data object may have more than one field or set of fields that constitute a specific foreign key for the specified relationship. In such cases there would be an attribute (or attributes) which represent the foreign key as well as the related object itself. For example, consider the following scenario:

 public class One {
     String twoId;
     Two two;
 }
 
 

In this case, twoId is an attribute that serves as a foreign key to Two, but the two attribute would contain an internal twoId attribute which is the primary key value for Two and represents the foreign key in this case.

In cases like above, the twoId attribute on the One class would take precedence unless it contains a null value, in which case this method will attempt to extract a non-null foreign key value from the related object.

Parameters:

relationshipName - the name of the relationship on the wrapped data object for which to determine the foreign key value

Returns:

the single foreign key value on the wrapped data object for the given relationship name, or null if it has no fully-populated foreign key value

Throws:

IllegalArgumentException - if the given relationshipName does not represent a valid relationship for this data object

getForeignKeyAttributeValue

Object getForeignKeyAttributeValue(String relationshipName)

As getForeignKeyValue(String) except only returns the value for the "attribute" foreign key value. If the wrapped data object has no attribute foreign key for the given relationship, this method will return null.

Parameters:

relationshipName - the name of the relationship on the wrapped data object for which to determine the foreign key value

Returns:

the single foreign key attribute value on the wrapped data object for the given relationship name, or null if it has no fully-populated foreign key attribute value

Throws:

IllegalArgumentException - if the given relationshipName does not represent a valid relationship for this data object

getPropertyTypeNullSafe

Class<?> getPropertyTypeNullSafe(Class<?> objectType,
                               String propertyName)

Get property type for property name on object, this can be a nested property and method will recursively use the metadata to find type.

Parameters:

objectType - - Root object type

propertyName - - Property name

Returns:

Class of propertyName

linkChanges

void linkChanges(Set<String> changedPropertyPaths)

Executes reference linking using the wrapped object as the root and the set of changed paths.

Executes reference linker as per the algorithm described on ReferenceLinker

Parameters:

changedPropertyPaths - the Set of changed property paths relative to the wrapped object

See Also:

ReferenceLinker.linkChanges(Object, java.util.Set)

linkForeignKeys

void linkForeignKeys(boolean onlyLinkReadOnly)

Links foreign key values on the wrapped data object and then recurses through all child relationships and collections which are cascaded during persistence and does the same.

In this context, linking of foreign key values means that on data objects that have both a field (or fields) that represent a foreign key to a relationship as well as an actual reference object for that relationship, if that foreign key field(s) is read only, then it will copy the value of the primary key(s) on the reference object to the associated foreign key field(s).

If onlyLinkReadOnly is true, this method will only link values into foreign keys that are "read-only" according to the metadata of the data object. This is to avoid situations where the foreign key field itself is the "master" value for the key. In those situations you do not want a read-only reference object to obliterate or corrupt the master key.

Parameters:

onlyLinkReadOnly - indicates whether or not only read-only foreign keys should be linked

linkForeignKeys

void linkForeignKeys(String relationshipName,
                   boolean onlyLinkReadOnly)

Links foreign keys non-recursively using the relationship with the given name on the wrapped data object.

If onlyLinkReadOnly is true then it will only perform linking for foreign key fields that are "read-only" according to the metadata for the data object. This is to avoid situations where the foreign key field itself is the "master" value for the key. In those situations you do not want a read-only reference object to obliterate or corrupt the master key.

Parameters:

relationshipName - the name of the relationship on the wrapped data object for which to link foreign keys, must not be a nested path

onlyLinkReadOnly - indicates whether or not only read-only foreign keys should be linked

fetchRelationship

void fetchRelationship(String relationshipName)

Fetches and populates the value for the relationship with the given name on the wrapped data object.

This is done by identifying the current foreign key attribute value for the relationship using the algorithm described on getForeignKeyAttributeValue(String) and then loading the related object using that foreign key value, updating the relationship value on the wrapped data object afterward.

If the foreign key value is null or the loading of the related object using the foreign key returns a null value, this method will set the relationship value to null.

This method is equivalent to invoking fetchRelationship(String, boolean, boolean) passing "true" for both useForeignKeyAttribute and nullifyDanglingRelationship.

Parameters:

relationshipName - the name of the relationship on the wrapped data object to refresh

Throws:

IllegalArgumentException - if the given relationshipName does not represent a valid relationship for this data object

org.springframework.dao.DataAccessException - if there is a data access problem when attempting to refresh the relationship

fetchRelationship

void fetchRelationship(String relationshipName,
                     boolean useForeignKeyAttribute,
                     boolean nullifyDanglingRelationship)

Fetches and populates the value for the relationship with the given name on the wrapped object.

The value of useForeignKeyAttribute will be used to determine whether the foreign key attribute is used to fetch the relationship (if this parameter is "true"), or whether the primary key on the related object itself will be used (if it is false). In the case that the primary key is used, once the relationship has been fetched, the foreign key field value (if one exists) will also be updated to remain in sync with the reference object.

If no related object is found when attempting to fetch by the key values, then the behavior of this method will depend upon the value passed for nullifyDanglingRelationship. If false, this method will not modify the wrapped object. If true, then the related object will be set to null.

Parameters:

relationshipName - the name of the relationship on the wrapped data object to refresh

useForeignKeyAttribute - if true, use the foreign key attribute to fetch the relationship, otherwise use the primary key value on the related object

nullifyDanglingRelationship - if true and no relationship value is found for the given key then set the related object to null, otherwise leave the existing object state alone

Throws:

IllegalArgumentException - if the given relationshipName does not represent a valid relationship for this data object

org.springframework.dao.DataAccessException - if there is a data access problem when attempting to refresh the relationship

materializeReferencedObjects

void materializeReferencedObjects(MaterializeOption... options)

Fetches and populates referenced objects within the wrapped object. See fetchRelationship(String) for details on how the relationships will be fetched. By default, this method will go through and instantiate all lazy-loaded, non-persisted-with-parent reference objects and collections on the master object. See MaterializeOption for the available options. This method does not recurse into child objects. For that, use the materializeReferencedObjectsToDepth(int, MaterializeOption...) method.

Parameters:

options - An optional list of MaterializeOption objects which may adjust the behavior of this method.

Throws:

org.springframework.dao.DataAccessException - if there is a data access problem when attempting to refresh the relationship

See Also:

fetchRelationship(String), MaterializeOption

materializeReferencedObjectsToDepth

void materializeReferencedObjectsToDepth(int maxDepth,
                                       MaterializeOption... options)

Fetches and populates referenced objects within the wrapped object. See fetchRelationship(String) for details on how the relationships will be fetched. By default, this method will go through and instantiate all lazy-loaded, non-persisted-with-parent reference objects and collections on the master object. See MaterializeOption for the available options.

Parameters:

maxDepth - The number of levels of child objects to refresh. A value of 1 will only materialize the child object on the wrapped object.

options - An optional list of MaterializeOption objects which may adjust the behavior of this method.

Throws:

org.springframework.dao.DataAccessException - if there is a data access problem when attempting to refresh the relationship

See Also:

fetchRelationship(String), MaterializeOption