Spring JDBC 6.1.4 · org.springframework.jdbc.core.BeanPropertyRowMapper

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.

Field Summary

Modifier and Type	Field and Description
private boolean	checkFullyPopulated Whether we're strictly validating.
private ConversionService	conversionService ConversionService for binding JDBC values to bean properties.
protected final Log	logger Logger available to subclasses.
private Class<T>	mappedClass The class we are mapping to.
private Map<String, PropertyDescriptor>	mappedProperties Map of the properties we provide mapping for.
private Set<String>	mappedPropertyNames Set of bean property names we provide mapping for.
private boolean	primitivesDefaultedForNullValue Whether `NULL` database values should be ignored for primitive properties in the target class.

Constructor Summary

Access	Constructor and Description
public	BeanPropertyRowMapper() Create a new `BeanPropertyRowMapper` for bean-style configuration.
public	BeanPropertyRowMapper(Class<T> the class that each row should be mapped to mappedClass) Create a new `BeanPropertyRowMapper`, accepting unpopulated properties in the target bean.
public	BeanPropertyRowMapper(Class<T> the class that each row should be mapped to mappedClass, boolean whether we're strictly validating that all bean properties have been mapped from corresponding database columns checkFullyPopulated) Create a new `BeanPropertyRowMapper`.

Method Summary

Modifier and Type	Method and Description
protected T	Returns: a corresponding instance of the mapped class constructMappedInstance(ResultSet the ResultSet to map (pre-initialized for the current row) rs, TypeConverter a TypeConverter with this RowMapper's conversion service tc) Construct an instance of the mapped class for the current row.
protected Object	Returns: the Object value getColumnValue(ResultSet is the ResultSet holding the data rs, int is the column index index, PropertyDescriptor the bean property that each result object is expected to match pd) Retrieve a JDBC object value for the specified column.
protected Object	Returns: the Object value getColumnValue(ResultSet is the ResultSet holding the data rs, int is the column index index, Class<?> the target parameter type paramType) Retrieve a JDBC object value for the specified column.
public ConversionService	getConversionService() Return a `ConversionService` for binding JDBC values to bean properties, or `null` if none.
public final Class<T>	getMappedClass() Get the class that we are mapping to.
protected void	initBeanWrapper(BeanWrapper the BeanWrapper to initialize bw) Initialize the given BeanWrapper to be used for row mapping.
protected void	initialize(Class<T> the mapped class mappedClass) Initialize the mapping meta-data for the given class.
public boolean	isCheckFullyPopulated() Return whether we're strictly validating that all bean properties have been mapped from corresponding database columns.
public boolean	isPrimitivesDefaultedForNullValue() Get the value of the `primitivesDefaultedForNullValue` flag.
protected String	Returns: the converted name lowerCaseName(String the original name name) Convert the given name to lower case.
protected Set<String>	Returns: a set of mapped names mappedNames(PropertyDescriptor the property descriptor discovered on initialization pd) Determine the mapped names for the given property.
public T	mapRow(ResultSet the `ResultSet` to map (pre-initialized for the current row) rs, int the number of the current row rowNumber) Implements org.springframework.jdbc.core.RowMapper.mapRow. Extract the values for all columns in the current row.
public static <T> BeanPropertyRowMapper<T>	newInstance(Class<T> the class that each row should be mapped to mappedClass) Static factory method to create a new `BeanPropertyRowMapper`.
public static <T> BeanPropertyRowMapper<T>	newInstance(Class<T> the class that each row should be mapped to mappedClass, ConversionService the `ConversionService` for binding JDBC values to bean properties, or `null` for none conversionService) Static factory method to create a new `BeanPropertyRowMapper`.
public void	setCheckFullyPopulated(boolean checkFullyPopulated) Set whether we're strictly validating that all bean properties have been mapped from corresponding database columns.
public void	setConversionService(ConversionService conversionService) Set a `ConversionService` for binding JDBC values to bean properties, or `null` for none.
public void	setMappedClass(Class<T> mappedClass) Set the class that each row should be mapped to.
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.
protected void	suppressProperty(String the property name (as used by property descriptors) propertyName) Remove the specified property from the mapped properties.
protected String	Returns: the converted name underscoreName(String the original name name) Convert a name in camelCase to an underscored name in lower case.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

checkFullyPopulated	back to summary
private boolean checkFullyPopulated Whether we're strictly validating.

conversionService	back to summary
private ConversionService conversionService ConversionService for binding JDBC values to bean properties. Annotations @Nullable

logger	back to summary
protected final Log logger Logger available to subclasses.

mappedClass	back to summary
private Class<T> mappedClass The class we are mapping to. Annotations @Nullable

mappedProperties	back to summary
private Map<String, PropertyDescriptor> mappedProperties Map of the properties we provide mapping for. Annotations @Nullable

mappedPropertyNames	back to summary
private Set<String> mappedPropertyNames Set of bean property names we provide mapping for. Annotations @Nullable

primitivesDefaultedForNullValue back to summary

primitivesDefaultedForNullValue	back to summary
private boolean primitivesDefaultedForNullValue Whether `NULL` database values should be ignored for primitive properties in the target class. See Also `setPrimitivesDefaultedForNullValue(boolean)`

private boolean primitivesDefaultedForNullValue

Whether NULL database values should be ignored for primitive properties in the target class.

See Also: setPrimitivesDefaultedForNullValue(boolean)

Constructor Detail

BeanPropertyRowMapper back to summary

BeanPropertyRowMapper	back to summary
public BeanPropertyRowMapper() Create a new `BeanPropertyRowMapper` for bean-style configuration. See Also `setMappedClass`, `setCheckFullyPopulated`

public BeanPropertyRowMapper()

Create a new BeanPropertyRowMapper for bean-style configuration.

See Also: setMappedClass, setCheckFullyPopulated

BeanPropertyRowMapper back to summary

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

public BeanPropertyRowMapper(Class<T> mappedClass)

Create a new BeanPropertyRowMapper, accepting unpopulated properties in the target bean.

Parameters

mappedClass:Class<T>: the class that each row should be mapped to

BeanPropertyRowMapper back to summary

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

public BeanPropertyRowMapper(Class<T> mappedClass, boolean checkFullyPopulated)

Create a new BeanPropertyRowMapper.

Parameters

mappedClass:Class<T>: the class that each row should be mapped to
checkFullyPopulated:boolean: whether we're strictly validating that all bean properties have been mapped from corresponding database columns

Method Detail

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

constructMappedInstance

back to summary

protected T constructMappedInstance(ResultSet rs, TypeConverter tc) throws SQLException

Construct an instance of the mapped class for the current row.

Parameters

rs:ResultSet: the ResultSet to map (pre-initialized for the current row)
tc:TypeConverter: a TypeConverter with this RowMapper's conversion service

Returns:T

a corresponding instance of the mapped class

Exceptions

SQLException:: if an SQLException is encountered

Since

5.3

getColumnValue back to summary

getColumnValue	back to summary
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:ResultSet is the ResultSet holding the data index:int is the column index pd:PropertyDescriptor the bean property that each result object is expected to match Returns:Object the Object value Annotations @Nullable Exceptions SQLException: in case of extraction failure See Also `getColumnValue(ResultSet, int, Class)`

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:ResultSet: is the ResultSet holding the data
index:int: is the column index
pd:PropertyDescriptor: the bean property that each result object is expected to match

Returns:Object

the Object value

Annotations

@Nullable

Exceptions

SQLException:: in case of extraction failure

See Also

getColumnValue(ResultSet, int, Class)

getColumnValue back to summary

getColumnValue	back to summary
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:ResultSet is the ResultSet holding the data index:int is the column index paramType:Class<?> the target parameter type Returns:Object the Object value Annotations @Nullable Exceptions SQLException: in case of extraction failure Since 5.3 See Also `org.springframework.jdbc.support.JdbcUtils#getResultSetValue(java.sql.ResultSet, int, Class)`

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:ResultSet: is the ResultSet holding the data
index:int: is the column index
paramType:Class<?>: the target parameter type

Returns:Object

the Object value

Annotations

@Nullable

Exceptions

SQLException:: in case of extraction failure

Since

5.3

getConversionService back to summary

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

public ConversionService getConversionService()

Return a ConversionService for binding JDBC values to bean properties, or null if none.

Annotations

@Nullable

Since

4.3

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

getMappedClass

back to summary

public final Class<T> getMappedClass()

Get the class that we are mapping to.

Annotations

@Nullable

initBeanWrapper back to summary

initBeanWrapper	back to summary
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:BeanWrapper the BeanWrapper to initialize See Also `getConversionService()`, `BeanWrapper#setConversionService`

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:BeanWrapper: the BeanWrapper to initialize

initialize back to summary

initialize	back to summary
protected void initialize(Class<T> mappedClass) Initialize the mapping meta-data for the given class. Parameters mappedClass:Class<T> the mapped class See Also `setMappedClass`, `BeanUtils#getPropertyDescriptors`, `mappedNames(PropertyDescriptor)`

protected void initialize(Class<T> mappedClass)

Initialize the mapping meta-data for the given class.

Parameters

mappedClass:Class<T>: the mapped class

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

isPrimitivesDefaultedForNullValue back to summary

isPrimitivesDefaultedForNullValue	back to summary
public boolean isPrimitivesDefaultedForNullValue() Get the value of the `primitivesDefaultedForNullValue` flag. See Also `setPrimitivesDefaultedForNullValue(boolean)`

public boolean isPrimitivesDefaultedForNullValue()

Get the value of the primitivesDefaultedForNullValue flag.

See Also: setPrimitivesDefaultedForNullValue(boolean)

lowerCaseName back to summary

lowerCaseName	back to summary
protected String lowerCaseName(String name) Convert the given name to lower case. By default, conversions will happen within the US locale. Parameters name:String the original name Returns:String the converted name Since 4.2 See Also `underscoreName`

protected String lowerCaseName(String name)

Convert the given name to lower case.

By default, conversions will happen within the US locale.

Parameters

name:String: the original name

Returns:String

the converted name

Since

4.2

See Also

underscoreName

mappedNames back to summary

mappedNames	back to summary
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:PropertyDescriptor the property descriptor discovered on initialization Returns:Set<String> a set of mapped names Since 6.1.4 See Also `initialize`, `lowerCaseName`, `underscoreName`

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:PropertyDescriptor: the property descriptor discovered on initialization

Returns:Set<String>

a set of mapped names

Since

6.1.4

mapRow back to summary

mapRow	back to summary
public T mapRow(ResultSet rs, int rowNumber) throws SQLException Implements org.springframework.jdbc.core.RowMapper.mapRow. Extract the values for all columns in the current row. Utilizes public setters and result set meta-data. Parameters rs:ResultSet Doc from org.springframework.jdbc.core.RowMapper.mapRow. the `ResultSet` to map (pre-initialized for the current row) rowNumber:int Doc from org.springframework.jdbc.core.RowMapper.mapRow. the number of the current row Returns:T Doc from org.springframework.jdbc.core.RowMapper.mapRow. the result object for the current row (may be `null`) Annotations @Override Exceptions SQLException: Doc from org.springframework.jdbc.core.RowMapper.mapRow. if an SQLException is encountered while getting column values (that is, there's no need to catch SQLException) See Also `java.sql.ResultSetMetaData`

public T mapRow(ResultSet rs, int rowNumber) throws SQLException

Implements org.springframework.jdbc.core.RowMapper.mapRow.

Extract the values for all columns in the current row.

Utilizes public setters and result set meta-data.

Parameters

rs:ResultSet

Doc from org.springframework.jdbc.core.RowMapper.mapRow.

the ResultSet to map (pre-initialized for the current row)

rowNumber:int

Doc from org.springframework.jdbc.core.RowMapper.mapRow.

the number of the current row

Returns:T

Doc from org.springframework.jdbc.core.RowMapper.mapRow.

the result object for the current row (may be null)

Annotations

@Override

Exceptions

SQLException:

Doc from org.springframework.jdbc.core.RowMapper.mapRow.

if an SQLException is encountered while getting column values (that is, there's no need to catch SQLException)

See Also

java.sql.ResultSetMetaData

newInstance back to summary

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

public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass)

Static factory method to create a new BeanPropertyRowMapper.

Parameters

mappedClass:Class<T>: the class that each row should be mapped to

See Also

newInstance(Class, ConversionService)

newInstance back to summary

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

public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass, ConversionService conversionService)

Static factory method to create a new BeanPropertyRowMapper.

Parameters

mappedClass:Class<T>: the class that each row should be mapped to
conversionService:ConversionService: the ConversionService for binding JDBC values to bean properties, or null for none

Since

5.2.3

setCheckFullyPopulated back to summary

setCheckFullyPopulated	back to summary
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.

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.

setConversionService back to summary

setConversionService	back to summary
public void setConversionService(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)`

public void setConversionService(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)

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

setPrimitivesDefaultedForNullValue back to summary

setPrimitivesDefaultedForNullValue	back to summary
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.

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.

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

suppressProperty

back to summary

protected void suppressProperty(String propertyName)

Remove the specified property from the mapped properties.

Parameters

propertyName:String: the property name (as used by property descriptors)

Since

5.3.9

underscoreName back to summary

underscoreName	back to summary
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:String the original name Returns:String the converted name Since 4.2 See Also `JdbcUtils#convertPropertyNameToUnderscoreName`

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:String: the original name

Returns:String

the converted name

Since

4.2

public Class BeanPropertyRowMapper<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail