From adbba712d631ae33c62d12917e81cae61fdc0e77 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Fri, 3 Feb 2023 15:34:32 +0100 Subject: [PATCH] Polish Javadoc for RowMappers --- .../jdbc/core/BeanPropertyRowMapper.java | 41 +++++++++++-------- .../jdbc/core/DataClassRowMapper.java | 9 ++-- .../springframework/jdbc/core/RowMapper.java | 26 ++++++------ 3 files changed, 42 insertions(+), 34 deletions(-) diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/BeanPropertyRowMapper.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/BeanPropertyRowMapper.java index 5c2ae3b8c9..5b8192c317 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/BeanPropertyRowMapper.java +++ b/spring-jdbc/src/main/java/org/springframework/jdbc/core/BeanPropertyRowMapper.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2022 the original author or authors. + * Copyright 2002-2023 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. @@ -48,28 +48,35 @@ import org.springframework.util.StringUtils; /** * {@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. + * top-level class or {@code 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 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. + *

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 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. + *

Mapping is provided for fields 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, {@code 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". + * try using column aliases in the SQL statement like + * {@code "select fname as first_name from customer"}, where {@code first_name} + * can be mapped to a {@code setFirstName(String)} method in the target class. * - *

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. + *

For {@code NULL} values read from the database, an attempt will be made to + * call the corresponding setter method with {@code null}, but in the case of + * Java primitives, this will result in a {@link TypeMismatchException}. This class + * can be configured (via the {@link #setPrimitivesDefaultedForNullValue(boolean) + * primitivesDefaultedForNullValue} property) to catch this exception and use the + * primitive's default value. Be aware that if you use the values from the mapped + * bean to update the database, the primitive value in the database will be + * changed from {@code NULL} to the primitive's default value. * - *

Please note that this class is designed to provide convenience rather than high performance. - * For best performance, consider using a custom {@link RowMapper} implementation. + *

Please note that this class is designed to provide convenience rather than + * high performance. For best performance, consider using a custom {@code RowMapper} + * implementation. * * @author Thomas Risberg * @author Juergen Hoeller diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/DataClassRowMapper.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/DataClassRowMapper.java index 274bfdfa0c..7b1b62cb43 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/DataClassRowMapper.java +++ b/spring-jdbc/src/main/java/org/springframework/jdbc/core/DataClassRowMapper.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2022 the original author or authors. + * Copyright 2002-2023 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. @@ -31,9 +31,10 @@ import org.springframework.util.Assert; /** * {@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 may either expose a data class constructor with named - * parameters corresponding to column names or classic bean property setters - * (or even a combination of both). + * top-level class or {@code static} nested class, and it may expose either a + * data class constructor with named parameters corresponding to column names + * or classic bean property setter methods with property names corresponding to + * column names (or even a combination of both). * *

Note that this class extends {@link BeanPropertyRowMapper} and can * therefore serve as a common choice for any mapped target class, flexibly diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java b/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java index a520b67e8e..291d3f2ac1 100644 --- a/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java +++ b/spring-jdbc/src/main/java/org/springframework/jdbc/core/RowMapper.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2018 the original author or authors. + * Copyright 2002-2023 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. @@ -24,21 +24,21 @@ import org.springframework.lang.Nullable; /** * An interface used by {@link JdbcTemplate} for mapping rows of a * {@link java.sql.ResultSet} on a per-row basis. Implementations of this - * interface perform the actual work of mapping each row to a result object, + * interface perform the actual work of mapping each row to a result object * but don't need to worry about exception handling. * {@link java.sql.SQLException SQLExceptions} will be caught and handled - * by the calling JdbcTemplate. + * by the calling {@code JdbcTemplate}. * - *

Typically used either for {@link JdbcTemplate}'s query methods - * or for out parameters of stored procedures. RowMapper objects are + *

Typically used either for {@code JdbcTemplate}'s query methods or for + * {@code out} parameters of stored procedures. {@code RowMapper} objects are * typically stateless and thus reusable; they are an ideal choice for * implementing row-mapping logic in a single place. * *

Alternatively, consider subclassing * {@link org.springframework.jdbc.object.MappingSqlQuery} from the - * {@code jdbc.object} package: Instead of working with separate - * JdbcTemplate and RowMapper objects, you can build executable query - * objects (containing row-mapping logic) in that style. + * {@code jdbc.object} package: instead of working with separate + * {@code JdbcTemplate} and {@code RowMapper} objects, you can build executable + * query objects (containing row-mapping logic) in that style. * * @author Thomas Risberg * @author Juergen Hoeller @@ -52,13 +52,13 @@ import org.springframework.lang.Nullable; public interface RowMapper { /** - * Implementations must implement this method to map each row of data - * in the ResultSet. This method should not call {@code next()} on - * the ResultSet; it is only supposed to map values of the current row. - * @param rs the ResultSet to map (pre-initialized for the current row) + * Implementations must implement this method to map each row of data in the + * {@code ResultSet}. This method should not call {@code next()} on the + * {@code ResultSet}; it is only supposed to map values of the current row. + * @param rs the {@code ResultSet} to map (pre-initialized for the current row) * @param rowNum the number of the current row * @return the result object for the current row (may be {@code null}) - * @throws SQLException if an SQLException is encountered getting + * @throws SQLException if an SQLException is encountered while getting * column values (that is, there's no need to catch SQLException) */ @Nullable