Package org.springframework.jdbc.core

Class BeanPropertyRowMapper<T>

java.lang.Object
org.springframework.jdbc.core.BeanPropertyRowMapper<T>
Type Parameters:
T - the result type
All Implemented Interfaces:
RowMapper<T>
Direct Known Subclasses:
DataClassRowMapper
public class BeanPropertyRowMapper<T> extends Object implements RowMapper<T>
RowMapper implementation that converts a row into a new instance of the specified mapped target class. The mapped target class must be a top-level class or static nested class, and it must have a default or no-arg constructor.

Column values are mapped based on matching the column name (as obtained from result set meta-data) to public setters in the target class for the corresponding properties. The names are matched either directly or by transforming a name separating the parts with underscores to the same name using "camel" case.

Mapping is provided for properties in the target class for many common types — for example: String, boolean, Boolean, byte, Byte, short, Short, int, Integer, long, Long, float, Float, double, Double, BigDecimal, java.util.Date, etc.

To facilitate mapping between columns and properties that don't have matching names, try using underscore-separated column aliases in the SQL statement like "select fname as first_name from customer", where first_name can be mapped to a setFirstName(String) method in the target class.

For a NULL value read from the database, an attempt will be made to call the corresponding setter method with null, but in the case of Java primitives this will result in a TypeMismatchException by default. To ignore NULL database values for all primitive properties in the target class, set the primitivesDefaultedForNullValue flag to true. See setPrimitivesDefaultedForNullValue(boolean) for details.

If you need to map to a target class which has a data class constructor — for example, a Java record or a Kotlin data class — use DataClassRowMapper instead.

Please note that this class is designed to provide convenience rather than high performance. For best performance, consider using a custom RowMapper implementation.

Since:
2.5
Author:
Thomas Risberg, Juergen Hoeller, Sam Brannen
See Also:

  • Field Details

    • logger

      protected final Log logger
      Logger available to subclasses.

  • Constructor Details

    • BeanPropertyRowMapper

      public BeanPropertyRowMapper()
      Create a new BeanPropertyRowMapper for bean-style configuration.
      See Also:

    • BeanPropertyRowMapper

      public BeanPropertyRowMapper(Class<T> mappedClass)
      Create a new BeanPropertyRowMapper, accepting unpopulated properties in the target bean.
      Parameters:
      mappedClass - the class that each row should be mapped to

    • BeanPropertyRowMapper

      public BeanPropertyRowMapper(Class<T> mappedClass, boolean checkFullyPopulated)
      Create a new BeanPropertyRowMapper.
      Parameters:
      mappedClass - the class that each row should be mapped to
      checkFullyPopulated - whether we're strictly validating that all bean properties have been mapped from corresponding database columns

  • Method Details

    • setMappedClass

      public void setMappedClass(Class<T> mappedClass)
      Set the class that each row should be mapped to.

    • getMappedClass

      @Nullable public final Class<T> getMappedClass()
      Get the class that we are mapping to.

    • setCheckFullyPopulated

      public void setCheckFullyPopulated(boolean checkFullyPopulated)
      Set whether we're strictly validating that all bean properties have been mapped from corresponding database columns.

      Default is false, accepting unpopulated properties in the target bean.

    • isCheckFullyPopulated

      public boolean isCheckFullyPopulated()
      Return whether we're strictly validating that all bean properties have been mapped from corresponding database columns.

    • setPrimitivesDefaultedForNullValue

      public void setPrimitivesDefaultedForNullValue(boolean primitivesDefaultedForNullValue)
      Set whether a NULL database column value should be ignored when mapping to a corresponding primitive property in the target class.

      Default is false, throwing an exception when nulls are mapped to Java primitives.

      If this flag is set to true and you use an ignored primitive property value from the mapped bean to update the database, the value in the database will be changed from NULL to the current value of that primitive property. That value may be the property's initial value (potentially Java's default value for the respective primitive type), or it may be some other value set for the property in the default constructor (or initialization block) or as a side effect of setting some other property in the mapped bean.

    • isPrimitivesDefaultedForNullValue

      public boolean isPrimitivesDefaultedForNullValue()
      Get the value of the primitivesDefaultedForNullValue flag.
      See Also:

    • setConversionService

      public void setConversionService(@Nullable ConversionService conversionService)
      Set a ConversionService for binding JDBC values to bean properties, or null for none.

      Default is a DefaultConversionService, as of Spring 4.3. This provides support for java.time conversion and other special types.

      Since:
      4.3
      See Also:

    • getConversionService

      @Nullable public ConversionService getConversionService()
      Return a ConversionService for binding JDBC values to bean properties, or null if none.
      Since:
      4.3

    • initialize

      protected void initialize(Class<T> mappedClass)
      Initialize the mapping meta-data for the given class.
      Parameters:
      mappedClass - the mapped class
      See Also:

    • suppressProperty

      protected void suppressProperty(String propertyName)
      Remove the specified property from the mapped properties.
      Parameters:
      propertyName - the property name (as used by property descriptors)
      Since:
      5.3.9

    • mappedNames

      protected Set<String> mappedNames(PropertyDescriptor pd)
      Determine the mapped names for the given property.

      Subclasses may override this method to customize the mapped names, adding to or removing from the set determined by this base method (which returns the property name in lower-case and underscore-based form), or replacing the set completely.

      Parameters:
      pd - the property descriptor discovered on initialization
      Returns:
      a set of mapped names
      Since:
      6.1.4
      See Also:

    • lowerCaseName

      protected String lowerCaseName(String name)
      Convert the given name to lower case.

      By default, conversions will happen within the US locale.

      Parameters:
      name - the original name
      Returns:
      the converted name
      Since:
      4.2
      See Also:

    • underscoreName

      protected String underscoreName(String name)
      Convert a name in camelCase to an underscored name in lower case.

      Any upper case letters are converted to lower case with a preceding underscore.

      Parameters:
      name - the original name
      Returns:
      the converted name
      Since:
      4.2
      See Also:

    • mapRow

      public T mapRow(ResultSet rs, int rowNumber) throws SQLException
      Extract the values for all columns in the current row.

      Utilizes public setters and result set meta-data.

      Specified by:
      mapRow in interface RowMapper<T>
      Parameters:
      rs - the ResultSet to map (pre-initialized for the current row)
      rowNumber - the number of the current row
      Returns:
      the result object for the current row (may be null)
      Throws:
      SQLException - if an SQLException is encountered while getting column values (that is, there's no need to catch SQLException)
      See Also:

    • constructMappedInstance

      protected T constructMappedInstance(ResultSet rs, TypeConverter tc) throws SQLException
      Construct an instance of the mapped class for the current row.
      Parameters:
      rs - the ResultSet to map (pre-initialized for the current row)
      tc - a TypeConverter with this RowMapper's conversion service
      Returns:
      a corresponding instance of the mapped class
      Throws:
      SQLException - if an SQLException is encountered
      Since:
      5.3

    • initBeanWrapper

      protected void initBeanWrapper(BeanWrapper bw)
      Initialize the given BeanWrapper to be used for row mapping.

      To be called for each row.

      The default implementation applies the configured ConversionService, if any. Can be overridden in subclasses.

      Parameters:
      bw - the BeanWrapper to initialize
      See Also:

    • getColumnValue

      @Nullable protected Object getColumnValue(ResultSet rs, int index, PropertyDescriptor pd) throws SQLException
      Retrieve a JDBC object value for the specified column.

      The default implementation calls JdbcUtils.getResultSetValue(java.sql.ResultSet, int, Class) using the type of the specified PropertyDescriptor.

      Subclasses may override this to check specific value types upfront, or to post-process values returned from getResultSetValue.

      Parameters:
      rs - is the ResultSet holding the data
      index - is the column index
      pd - the bean property that each result object is expected to match
      Returns:
      the Object value
      Throws:
      SQLException - in case of extraction failure
      See Also:

    • getColumnValue

      @Nullable protected Object getColumnValue(ResultSet rs, int index, Class<?> paramType) throws SQLException
      Retrieve a JDBC object value for the specified column.

      The default implementation calls JdbcUtils.getResultSetValue(java.sql.ResultSet, int, Class).

      Subclasses may override this to check specific value types upfront, or to post-process values returned from getResultSetValue.

      Parameters:
      rs - is the ResultSet holding the data
      index - is the column index
      paramType - the target parameter type
      Returns:
      the Object value
      Throws:
      SQLException - in case of extraction failure
      Since:
      5.3
      See Also:

    • newInstance

      public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass)
      Static factory method to create a new BeanPropertyRowMapper.
      Parameters:
      mappedClass - the class that each row should be mapped to
      See Also:

    • newInstance

      public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass, @Nullable ConversionService conversionService)
      Static factory method to create a new BeanPropertyRowMapper.
      Parameters:
      mappedClass - the class that each row should be mapped to
      conversionService - the ConversionService for binding JDBC values to bean properties, or null for none
      Since:
      5.2.3
      See Also: