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:
  - `DataClassRowMapper`
  - `SimplePropertyRowMapper`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final org.apache.commons.logging.Log`
`logger`
Logger available to subclasses.

## Constructor Summary

Constructors
Constructor
Description
`BeanPropertyRowMapper()`
Create a new `BeanPropertyRowMapper` for bean-style configuration.
`BeanPropertyRowMapper(Class<T> mappedClass)`
Create a new `BeanPropertyRowMapper`, accepting unpopulated properties in the target bean.
`BeanPropertyRowMapper(Class<T> mappedClass, boolean checkFullyPopulated)`
Create a new `BeanPropertyRowMapper`.

## Method Summary

Modifier and Type
Method
Description
`protected T`
`constructMappedInstance(ResultSet rs, org.springframework.beans.TypeConverter tc)`
Construct an instance of the mapped class for the current row.
`protected Object`
`getColumnValue(ResultSet rs, int index, PropertyDescriptor pd)`
Retrieve a JDBC object value for the specified column.
`protected Object`
`getColumnValue(ResultSet rs, int index, Class<?> paramType)`
Retrieve a JDBC object value for the specified column.
`org.springframework.core.convert.ConversionService`
`getConversionService()`
Return a `ConversionService` for binding JDBC values to bean properties, or `null` if none.
`final Class<T>`
`getMappedClass()`
Get the class that we are mapping to.
`protected void`
`initBeanWrapper(org.springframework.beans.BeanWrapper bw)`
Initialize the given BeanWrapper to be used for row mapping.
`protected void`
`initialize(Class<T> mappedClass)`
Initialize the mapping meta-data for the given class.
`boolean`
`isCheckFullyPopulated()`
Return whether we're strictly validating that all bean properties have been mapped from corresponding database columns.
`boolean`
`isPrimitivesDefaultedForNullValue()`
Get the value of the `primitivesDefaultedForNullValue` flag.
`protected String`
`lowerCaseName(String name)`
Convert the given name to lower case.
`protected Set<String>`
`mappedNames(PropertyDescriptor pd)`
Determine the mapped names for the given property.
`T`
`mapRow(ResultSet rs, int rowNumber)`
Extract the values for all columns in the current row.
`static <T> BeanPropertyRowMapper<T>`
`newInstance(Class<T> mappedClass)`
Static factory method to create a new `BeanPropertyRowMapper`.
`static <T> BeanPropertyRowMapper<T>`
`newInstance(Class<T> mappedClass, org.springframework.core.convert.ConversionService conversionService)`
Static factory method to create a new `BeanPropertyRowMapper`.
`void`
`setCheckFullyPopulated(boolean checkFullyPopulated)`
Set whether we're strictly validating that all bean properties have been mapped from corresponding database columns.
`void`
`setConversionService(org.springframework.core.convert.ConversionService conversionService)`
Set a `ConversionService` for binding JDBC values to bean properties, or `null` for none.
`void`
`setMappedClass(Class<T> mappedClass)`
Set the class that each row should be mapped to.
`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.
`protected void`
`suppressProperty(String propertyName)`
Remove the specified property from the mapped properties.
`protected String`
`underscoreName(String name)`
Convert a name in camelCase to an underscored name in lower case.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### logger

protected final org.apache.commons.logging.Log logger
Logger available to subclasses.

## Constructor Details

### BeanPropertyRowMapper

public BeanPropertyRowMapper()
Create a new `BeanPropertyRowMapper` for bean-style configuration.

See Also:
  - `setMappedClass(java.lang.Class<T>)`
  - `setCheckFullyPopulated(boolean)`

### 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:
  - `setPrimitivesDefaultedForNullValue(boolean)`

### setConversionService

public void setConversionService(@Nullable org.springframework.core.convert.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:
  - `initBeanWrapper(BeanWrapper)`

### getConversionService

@Nullable public org.springframework.core.convert.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:
  - `setMappedClass(java.lang.Class<T>)`
  - `BeanUtils.getPropertyDescriptors(java.lang.Class<?>)`
  - `mappedNames(PropertyDescriptor)`

### 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:
  - `initialize(java.lang.Class<T>)`
  - `lowerCaseName(java.lang.String)`
  - `underscoreName(java.lang.String)`

### 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(java.lang.String)`

### 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:
  - `JdbcUtils.convertPropertyNameToUnderscoreName(java.lang.String)`

### 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:
  - `ResultSetMetaData`

### constructMappedInstance

protected T constructMappedInstance(ResultSet rs, org.springframework.beans.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(org.springframework.beans.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:
  - `getConversionService()`
  - `ConfigurablePropertyAccessor.setConversionService(org.springframework.core.convert.ConversionService)`

### 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(ResultSet, int, Class)`

### 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:
  - `JdbcUtils.getResultSetValue(java.sql.ResultSet, int, Class)`

### 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(Class, ConversionService)`

### newInstance

public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass, @Nullable org.springframework.core.convert.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:
  - `newInstance(Class)`
  - `setConversionService(org.springframework.core.convert.ConversionService)`