org.springframework/spring-jdbc/5.3.3 : org/springframework/jdbc/core/BeanPropertyRowMapper.java

BeanPropertyRowMapper
https://github.com/spring-projects/spring-framework: Spring JDBC (Spring IO)
Apache License, Version 2.0
Juergen Hoeller
/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.jdbc.core;

import java.beans.PropertyDescriptor;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Locale;
import java.util.Map;
import java.util.Set;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.beans.BeanUtils;
import org.springframework.beans.BeanWrapper;
import org.springframework.beans.BeanWrapperImpl;
import org.springframework.beans.NotWritablePropertyException;
import org.springframework.beans.TypeConverter;
import org.springframework.beans.TypeMismatchException;
import org.springframework.core.convert.ConversionService;
import org.springframework.core.convert.support.DefaultConversionService;
import org.springframework.dao.DataRetrievalFailureException;
import org.springframework.dao.InvalidDataAccessApiUsageException;
import org.springframework.jdbc.support.JdbcUtils;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;
import org.springframework.util.ClassUtils;
import org.springframework.util.StringUtils;

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 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 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 fields in the target class for many common types, e.g.: 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 fields that don't have matching names,
try using column aliases in the SQL statement like "select fname as first_name from customer".
For 'null' values read from the database, we will attempt to call the setter, but in the case of
Java primitives, this causes a TypeMismatchException. This class can be configured (using the
primitivesDefaultedForNullValue property) to trap this exception and use the primitives default value.
Be aware that if you use the values from the generated bean to update the database the primitive value
will have been set to the primitive's default value instead of null.
Please note that this class is designed to provide convenience rather than high performance. For best performance, consider using a custom RowMapper implementation. 
Author: Thomas Risberg, Juergen Hoeller
Type parameters: <T> – the result type
Since: 2.5/**
 * {@link 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 and it must have a default or no-arg constructor.
 *
 * <p>Column values are mapped based on matching the column name as obtained from result set
 * meta-data to public setters 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.
 *
 * <p>Mapping is provided for fields in the target class for many common types, e.g.:
 * String, boolean, Boolean, byte, Byte, short, Short, int, Integer, long, Long,
 * float, Float, double, Double, BigDecimal, {@code java.util.Date}, etc.
 *
 * <p>To facilitate mapping between columns and fields that don't have matching names,
 * try using column aliases in the SQL statement like "select fname as first_name from customer".
 *
 * <p>For 'null' values read from the database, we will attempt to call the setter, but in the case of
 * Java primitives, this causes a TypeMismatchException. This class can be configured (using the
 * primitivesDefaultedForNullValue property) to trap this exception and use the primitives default value.
 * Be aware that if you use the values from the generated bean to update the database the primitive value
 * will have been set to the primitive's default value instead of null.
 *
 * <p>Please note that this class is designed to provide convenience rather than high performance.
 * For best performance, consider using a custom {@link RowMapper} implementation.
 *
 * @author Thomas Risberg
 * @author Juergen Hoeller
 * @since 2.5
 * @param <T> the result type
 */
public class BeanPropertyRowMapper<T> implements RowMapper<T> {

	Logger available to subclasses. /** Logger available to subclasses. */
	protected final Log logger = LogFactory.getLog(getClass());

	The class we are mapping to. /** The class we are mapping to. */
	@Nullable
	private Class<T> mappedClass;

	Whether we're strictly validating. /** Whether we're strictly validating. */
	private boolean checkFullyPopulated = false;

	Whether we're defaulting primitives when mapping a null value. /** Whether we're defaulting primitives when mapping a null value. */
	private boolean primitivesDefaultedForNullValue = false;

	ConversionService for binding JDBC values to bean properties. /** ConversionService for binding JDBC values to bean properties. */
	@Nullable
	private ConversionService conversionService = DefaultConversionService.getSharedInstance();

	Map of the fields we provide mapping for. /** Map of the fields we provide mapping for. */
	@Nullable
	private Map<String, PropertyDescriptor> mappedFields;

	Set of bean properties we provide mapping for. /** Set of bean properties we provide mapping for. */
	@Nullable
	private Set<String> mappedProperties;


	Create a new BeanPropertyRowMapper for bean-style configuration. 
See Also: setMappedClass
setCheckFullyPopulated/**
	 * Create a new {@code BeanPropertyRowMapper} for bean-style configuration.
	 * @see #setMappedClass
	 * @see #setCheckFullyPopulated
	 */
	public BeanPropertyRowMapper() {
	}

	Create a new BeanPropertyRowMapper, accepting unpopulated properties in the target bean. 
Params: mappedClass – the class that each row should be mapped to/**
	 * Create a new {@code BeanPropertyRowMapper}, accepting unpopulated
	 * properties in the target bean.
	 * @param mappedClass the class that each row should be mapped to
	 */
	public BeanPropertyRowMapper(Class<T> mappedClass) {
		initialize(mappedClass);
	}

	Create a new BeanPropertyRowMapper. 
Params: 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 fields/**
	 * Create a new {@code BeanPropertyRowMapper}.
	 * @param mappedClass the class that each row should be mapped to
	 * @param checkFullyPopulated whether we're strictly validating that
	 * all bean properties have been mapped from corresponding database fields
	 */
	public BeanPropertyRowMapper(Class<T> mappedClass, boolean checkFullyPopulated) {
		initialize(mappedClass);
		this.checkFullyPopulated = checkFullyPopulated;
	}


	Set the class that each row should be mapped to.
/**
	 * Set the class that each row should be mapped to.
	 */
	public void setMappedClass(Class<T> mappedClass) {
		if (this.mappedClass == null) {
			initialize(mappedClass);
		}
		else {
			if (this.mappedClass != mappedClass) {
				throw new InvalidDataAccessApiUsageException("The mapped class can not be reassigned to map to " +
						mappedClass + " since it is already providing mapping for " + this.mappedClass);
			}
		}
	}

	Get the class that we are mapping to.
/**
	 * Get the class that we are mapping to.
	 */
	@Nullable
	public final Class<T> getMappedClass() {
		return this.mappedClass;
	}

	Set whether we're strictly validating that all bean properties have been mapped
from corresponding database fields.
Default is false, accepting unpopulated properties in the target bean. /**
	 * Set whether we're strictly validating that all bean properties have been mapped
	 * from corresponding database fields.
	 * <p>Default is {@code false}, accepting unpopulated properties in the target bean.
	 */
	public void setCheckFullyPopulated(boolean checkFullyPopulated) {
		this.checkFullyPopulated = checkFullyPopulated;
	}

	Return whether we're strictly validating that all bean properties have been
mapped from corresponding database fields.
/**
	 * Return whether we're strictly validating that all bean properties have been
	 * mapped from corresponding database fields.
	 */
	public boolean isCheckFullyPopulated() {
		return this.checkFullyPopulated;
	}

	Set whether we're defaulting Java primitives in the case of mapping a null value
from corresponding database fields.
Default is false, throwing an exception when nulls are mapped to Java primitives. /**
	 * Set whether we're defaulting Java primitives in the case of mapping a null value
	 * from corresponding database fields.
	 * <p>Default is {@code false}, throwing an exception when nulls are mapped to Java primitives.
	 */
	public void setPrimitivesDefaultedForNullValue(boolean primitivesDefaultedForNullValue) {
		this.primitivesDefaultedForNullValue = primitivesDefaultedForNullValue;
	}

	Return whether we're defaulting Java primitives in the case of mapping a null value
from corresponding database fields.
/**
	 * Return whether we're defaulting Java primitives in the case of mapping a null value
	 * from corresponding database fields.
	 */
	public boolean isPrimitivesDefaultedForNullValue() {
		return this.primitivesDefaultedForNullValue;
	}

	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. 
See Also: initBeanWrapper(BeanWrapper)
Since: 4.3/**
	 * Set a {@link ConversionService} for binding JDBC values to bean properties,
	 * or {@code null} for none.
	 * <p>Default is a {@link DefaultConversionService}, as of Spring 4.3. This
	 * provides support for {@code java.time} conversion and other special types.
	 * @since 4.3
	 * @see #initBeanWrapper(BeanWrapper)
	 */
	public void setConversionService(@Nullable ConversionService conversionService) {
		this.conversionService = conversionService;
	}

	Return a ConversionService for binding JDBC values to bean properties, or null if none. 
Since: 4.3/**
	 * Return a {@link ConversionService} for binding JDBC values to bean properties,
	 * or {@code null} if none.
	 * @since 4.3
	 */
	@Nullable
	public ConversionService getConversionService() {
		return this.conversionService;
	}


	Initialize the mapping meta-data for the given class.
Params: mappedClass – the mapped class/**
	 * Initialize the mapping meta-data for the given class.
	 * @param mappedClass the mapped class
	 */
	protected void initialize(Class<T> mappedClass) {
		this.mappedClass = mappedClass;
		this.mappedFields = new HashMap<>();
		this.mappedProperties = new HashSet<>();

		for (PropertyDescriptor pd : BeanUtils.getPropertyDescriptors(mappedClass)) {
			if (pd.getWriteMethod() != null) {
				this.mappedFields.put(lowerCaseName(pd.getName()), pd);
				String underscoredName = underscoreName(pd.getName());
				if (!lowerCaseName(pd.getName()).equals(underscoredName)) {
					this.mappedFields.put(underscoredName, pd);
				}
				this.mappedProperties.add(pd.getName());
			}
		}
	}

	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.
Params: name – the original name
See Also: lowerCaseName
Returns: the converted name
Since: 4.2/**
	 * 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.
	 * @param name the original name
	 * @return the converted name
	 * @since 4.2
	 * @see #lowerCaseName
	 */
	protected String underscoreName(String name) {
		if (!StringUtils.hasLength(name)) {
			return "";
		}

		StringBuilder result = new StringBuilder();
		for (int i = 0; i < name.length(); i++) {
			char c = name.charAt(i);
			if (Character.isUpperCase(c)) {
				result.append('_').append(Character.toLowerCase(c));
			}
			else {
				result.append(c);
			}
		}
		return result.toString();
	}

	Convert the given name to lower case.
By default, conversions will happen within the US locale.
Params: name – the original name
Returns: the converted name
Since: 4.2/**
	 * Convert the given name to lower case.
	 * By default, conversions will happen within the US locale.
	 * @param name the original name
	 * @return the converted name
	 * @since 4.2
	 */
	protected String lowerCaseName(String name) {
		return name.toLowerCase(Locale.US);
	}


	Extract the values for all columns in the current row.
Utilizes public setters and result set meta-data.
See Also: ResultSetMetaData/**
	 * Extract the values for all columns in the current row.
	 * <p>Utilizes public setters and result set meta-data.
	 * @see java.sql.ResultSetMetaData
	 */
	@Override
	public T mapRow(ResultSet rs, int rowNumber) throws SQLException {
		BeanWrapperImpl bw = new BeanWrapperImpl();
		initBeanWrapper(bw);

		T mappedObject = constructMappedInstance(rs, bw);
		bw.setBeanInstance(mappedObject);

		ResultSetMetaData rsmd = rs.getMetaData();
		int columnCount = rsmd.getColumnCount();
		Set<String> populatedProperties = (isCheckFullyPopulated() ? new HashSet<>() : null);

		for (int index = 1; index <= columnCount; index++) {
			String column = JdbcUtils.lookupColumnName(rsmd, index);
			String field = lowerCaseName(StringUtils.delete(column, " "));
			PropertyDescriptor pd = (this.mappedFields != null ? this.mappedFields.get(field) : null);
			if (pd != null) {
				try {
					Object value = getColumnValue(rs, index, pd);
					if (rowNumber == 0 && logger.isDebugEnabled()) {
						logger.debug("Mapping column '" + column + "' to property '" + pd.getName() +
								"' of type '" + ClassUtils.getQualifiedName(pd.getPropertyType()) + "'");
					}
					try {
						bw.setPropertyValue(pd.getName(), value);
					}
					catch (TypeMismatchException ex) {
						if (value == null && this.primitivesDefaultedForNullValue) {
							if (logger.isDebugEnabled()) {
								logger.debug("Intercepted TypeMismatchException for row " + rowNumber +
										" and column '" + column + "' with null value when setting property '" +
										pd.getName() + "' of type '" +
										ClassUtils.getQualifiedName(pd.getPropertyType()) +
										"' on object: " + mappedObject, ex);
							}
						}
						else {
							throw ex;
						}
					}
					if (populatedProperties != null) {
						populatedProperties.add(pd.getName());
					}
				}
				catch (NotWritablePropertyException ex) {
					throw new DataRetrievalFailureException(
							"Unable to map column '" + column + "' to property '" + pd.getName() + "'", ex);
				}
			}
			else {
				// No PropertyDescriptor found
				if (rowNumber == 0 && logger.isDebugEnabled()) {
					logger.debug("No property found for column '" + column + "' mapped to field '" + field + "'");
				}
			}
		}

		if (populatedProperties != null && !populatedProperties.equals(this.mappedProperties)) {
			throw new InvalidDataAccessApiUsageException("Given ResultSet does not contain all fields " +
					"necessary to populate object of " + this.mappedClass + ": " + this.mappedProperties);
		}

		return mappedObject;
	}

	Construct an instance of the mapped class for the current row.
Params: rs – the ResultSet to map (pre-initialized for the current row)
tc – a TypeConverter with this RowMapper's conversion service
Throws: SQLException – if an SQLException is encountered
Returns: a corresponding instance of the mapped class
Since: 5.3/**
	 * Construct an instance of the mapped class for the current row.
	 * @param rs the ResultSet to map (pre-initialized for the current row)
	 * @param tc a TypeConverter with this RowMapper's conversion service
	 * @return a corresponding instance of the mapped class
	 * @throws SQLException if an SQLException is encountered
	 * @since 5.3
	 */
	protected T constructMappedInstance(ResultSet rs, TypeConverter tc) throws SQLException  {
		Assert.state(this.mappedClass != null, "Mapped class was not specified");
		return BeanUtils.instantiateClass(this.mappedClass);
	}

	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. 
Params: bw – the BeanWrapper to initialize
See Also: getConversionService()
ConfigurablePropertyAccessor.setConversionService/**
	 * Initialize the given BeanWrapper to be used for row mapping.
	 * To be called for each row.
	 * <p>The default implementation applies the configured {@link ConversionService},
	 * if any. Can be overridden in subclasses.
	 * @param bw the BeanWrapper to initialize
	 * @see #getConversionService()
	 * @see BeanWrapper#setConversionService
	 */
	protected void initBeanWrapper(BeanWrapper bw) {
		ConversionService cs = getConversionService();
		if (cs != null) {
			bw.setConversionService(cs);
		}
	}

	Retrieve a JDBC object value for the specified column.
The default implementation delegates to getColumnValue(ResultSet, int, Class). 
Params: rs – is the ResultSet holding the data
index – is the column index
pd – the bean property that each result object is expected to match
Throws: SQLException – in case of extraction failure
See Also: getColumnValue(ResultSet, int, Class)
Returns: the Object value/**
	 * Retrieve a JDBC object value for the specified column.
	 * <p>The default implementation delegates to
	 * {@link #getColumnValue(ResultSet, int, Class)}.
	 * @param rs is the ResultSet holding the data
	 * @param index is the column index
	 * @param pd the bean property that each result object is expected to match
	 * @return the Object value
	 * @throws SQLException in case of extraction failure
	 * @see #getColumnValue(ResultSet, int, Class)
	 */
	@Nullable
	protected Object getColumnValue(ResultSet rs, int index, PropertyDescriptor pd) throws SQLException {
		return JdbcUtils.getResultSetValue(rs, index, pd.getPropertyType());
	}

	Retrieve a JDBC object value for the specified column.
The default implementation calls JdbcUtils.getResultSetValue(ResultSet, int, Class<?>). Subclasses may override this to check specific value types upfront, or to post-process values return from getResultSetValue. 
Params: rs – is the ResultSet holding the data
index – is the column index
paramType – the target parameter type
Throws: SQLException – in case of extraction failure
See Also: JdbcUtils.getResultSetValue(ResultSet, int, Class<?>)
Returns: the Object value
Since: 5.3/**
	 * Retrieve a JDBC object value for the specified column.
	 * <p>The default implementation calls
	 * {@link JdbcUtils#getResultSetValue(java.sql.ResultSet, int, Class)}.
	 * Subclasses may override this to check specific value types upfront,
	 * or to post-process values return from {@code getResultSetValue}.
	 * @param rs is the ResultSet holding the data
	 * @param index is the column index
	 * @param paramType the target parameter type
	 * @return the Object value
	 * @throws SQLException in case of extraction failure
	 * @since 5.3
	 * @see org.springframework.jdbc.support.JdbcUtils#getResultSetValue(java.sql.ResultSet, int, Class)
	 */
	@Nullable
	protected Object getColumnValue(ResultSet rs, int index, Class<?> paramType) throws SQLException {
		return JdbcUtils.getResultSetValue(rs, index, paramType);
	}


	Static factory method to create a new BeanPropertyRowMapper. 
Params: mappedClass – the class that each row should be mapped to
See Also: newInstance(Class<Object>, ConversionService)/**
	 * Static factory method to create a new {@code BeanPropertyRowMapper}.
	 * @param mappedClass the class that each row should be mapped to
	 * @see #newInstance(Class, ConversionService)
	 */
	public static <T> BeanPropertyRowMapper<T> newInstance(Class<T> mappedClass) {
		return new BeanPropertyRowMapper<>(mappedClass);
	}

	Static factory method to create a new BeanPropertyRowMapper. 
Params: mappedClass – the class that each row should be mapped to
conversionService – the ConversionService for binding JDBC values to bean properties, or null for none
See Also: newInstance(Class<Object>)
setConversionService
Since: 5.2.3/**
	 * Static factory method to create a new {@code BeanPropertyRowMapper}.
	 * @param mappedClass the class that each row should be mapped to
	 * @param conversionService the {@link ConversionService} for binding
	 * JDBC values to bean properties, or {@code null} for none
	 * @since 5.2.3
	 * @see #newInstance(Class)
	 * @see #setConversionService
	 */
	public static <T> BeanPropertyRowMapper<T> newInstance(
			Class<T> mappedClass, @Nullable ConversionService conversionService) {

		BeanPropertyRowMapper<T> rowMapper = newInstance(mappedClass);
		rowMapper.setConversionService(conversionService);
		return rowMapper;
	}

}
Author:	Thomas Risberg, Juergen Hoeller
Type parameters:	<T> – the result type
Since:	2.5
Params:	name – the original name
See Also:	lowerCaseName
Returns:	the converted name
Since:	4.2
Params:	rs – the ResultSet to map (pre-initialized for the current row) tc – a TypeConverter with this RowMapper's conversion service
Throws:	SQLException – if an SQLException is encountered
Returns:	a corresponding instance of the mapped class
Since:	5.3
Params:	bw – the BeanWrapper to initialize
See Also:	getConversionService() ConfigurablePropertyAccessor.setConversionService
Params:	rs – is the ResultSet holding the data index – is the column index pd – the bean property that each result object is expected to match
Throws:	SQLException – in case of extraction failure
See Also:	getColumnValue(ResultSet, int, Class)
Returns:	the Object value
Params:	mappedClass – the class that each row should be mapped to
See Also:	newInstance(Class<Object>, ConversionService)
/

org.springframework/ spring-jdbc/ 5.3.3/ org/springframework/jdbc/core/BeanPropertyRowMapper.java
