Package 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 ConfigurablePropertyAccessor.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

    Modifier and Type
    Method
    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, setAutoGrowCollectionLimit

    Methods inherited from interface org.springframework.beans.ConfigurablePropertyAccessor

    getConversionService, isAutoGrowNestedPaths, isExtractOldValueForEditor, setAutoGrowNestedPaths, 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, convertIfNecessary

  • Method Details

    • 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:

    • 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:

    • 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: