Add new base type handler for using nullable JDBC APIs

src/main/java/org/apache/ibatis/type/BaseTypeHandler.java

@@ -24,8 +24,11 @@
 import org.apache.ibatis.session.Configuration;
 
 /**
+ * The base {@link TypeHandler} for references a generic type.
+ *
  * @author Clinton Begin
  * @author Simone Tripodi
+ * @author Kzuki Shimizu
  */
 public abstract class BaseTypeHandler<T> extends TypeReference<T> implements TypeHandler<T> {
 
@@ -75,11 +78,7 @@ public T getResult(ResultSet rs, String columnName) throws SQLException {
     } catch (Exception e) {
       throw new ResultMapException("Error attempting to get column '" + columnName + "' from result set.  Cause: " + e, e);
     }
-    if (rs.wasNull()) {
-      return null;
-    } else {
-      return result;
-    }
+    return handleResult(rs, result);
   }
 
   @Override
@@ -90,11 +89,7 @@ public T getResult(ResultSet rs, int columnIndex) throws SQLException {
     } catch (Exception e) {
       throw new ResultMapException("Error attempting to get column #" + columnIndex+ " from result set.  Cause: " + e, e);
     }
-    if (rs.wasNull()) {
-      return null;
-    } else {
-      return result;
-    }
+    return handleResult(rs, result);
   }
 
   @Override
@@ -105,6 +100,40 @@ public T getResult(CallableStatement cs, int columnIndex) throws SQLException {
     } catch (Exception e) {
       throw new ResultMapException("Error attempting to get column #" + columnIndex+ " from callable statement.  Cause: " + e, e);
     }
+    return handleResult(cs, result);
+  }
+
+  /**
+   * Handle a fetched result value from {@link ResultSet}.
+   * 
+   * @param rs a {@link ResultSet}
+   * @param result a fetched value
+   * @return If {@link ResultSet#wasNull()} return {@code true}, it return {@code null}. Otherwise
+   *         return a fetched result value.
+   * @exception SQLException if a database access error occurs or this method is
+   *            called on a closed result set
+   * @since 3.5.0
+   */
+  protected T handleResult(ResultSet rs, T result) throws SQLException {
+    if (rs.wasNull()) {
+      return null;
+    } else {
+      return result;
+    }
+  }
+
+  /**
+   * Handle a fetched result value
+   *
+   * @param cs a {@link CallableStatement}
+   * @param result a fetched value
+   * @return If {@link ResultSet#wasNull()} return {@code true}, it return {@code null}. Otherwise
+   *         return a fetched result value.
+   * @exception SQLException if a database access error occurs or this method is
+   *            called on a closed result set
+   * @since 3.5.0
+   */
+  protected T handleResult(CallableStatement cs, T result) throws SQLException {
     if (cs.wasNull()) {
       return null;
     } else {

src/main/java/org/apache/ibatis/type/BigDecimalTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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,7 +24,7 @@
 /**
  * @author Clinton Begin
  */
-public class BigDecimalTypeHandler extends BaseTypeHandler<BigDecimal> {
+public class BigDecimalTypeHandler extends NullableApiBasedTypeHandler<BigDecimal> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, BigDecimal parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/BigIntegerTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -25,7 +25,7 @@
 /**
  * @author Paul Krause
  */
-public class BigIntegerTypeHandler extends BaseTypeHandler<BigInteger> {
+public class BigIntegerTypeHandler extends NullableApiBasedTypeHandler<BigInteger> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, BigInteger parameter, JdbcType jdbcType) throws SQLException {

src/main/java/org/apache/ibatis/type/ByteArrayTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -23,7 +23,7 @@
 /**
  * @author Clinton Begin
  */
-public class ByteArrayTypeHandler extends BaseTypeHandler<byte[]> {
+public class ByteArrayTypeHandler extends NullableApiBasedTypeHandler<byte[]> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, byte[] parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/ByteObjectArrayTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -23,7 +23,7 @@
 /**
  * @author Clinton Begin
  */
-public class ByteObjectArrayTypeHandler extends BaseTypeHandler<Byte[]> {
+public class ByteObjectArrayTypeHandler extends NullableApiBasedTypeHandler<Byte[]> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, Byte[] parameter, JdbcType jdbcType) throws SQLException {

src/main/java/org/apache/ibatis/type/CharacterTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -23,7 +23,7 @@
 /**
  * @author Clinton Begin
  */
-public class CharacterTypeHandler extends BaseTypeHandler<Character> {
+public class CharacterTypeHandler extends NullableApiBasedTypeHandler<Character> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, Character parameter, JdbcType jdbcType) throws SQLException {

src/main/java/org/apache/ibatis/type/DateOnlyTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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,7 +24,7 @@
 /**
  * @author Clinton Begin
  */
-public class DateOnlyTypeHandler extends BaseTypeHandler<Date> {
+public class DateOnlyTypeHandler extends NullableApiBasedTypeHandler<Date> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, Date parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/DateTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -25,7 +25,7 @@
 /**
  * @author Clinton Begin
  */
-public class DateTypeHandler extends BaseTypeHandler<Date> {
+public class DateTypeHandler extends NullableApiBasedTypeHandler<Date> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, Date parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/EnumTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -23,7 +23,7 @@
 /**
  * @author Clinton Begin
  */
-public class EnumTypeHandler<E extends Enum<E>> extends BaseTypeHandler<E> {
+public class EnumTypeHandler<E extends Enum<E>> extends NullableApiBasedTypeHandler<E> {
 
   private final Class<E> type;
 

src/main/java/org/apache/ibatis/type/InstantTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -29,7 +29,7 @@
  * @author Tomas Rohovsky
  */
 @UsesJava8
-public class InstantTypeHandler extends BaseTypeHandler<Instant> {
+public class InstantTypeHandler extends NullableApiBasedTypeHandler<Instant> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, Instant parameter, JdbcType jdbcType) throws SQLException {

src/main/java/org/apache/ibatis/type/JapaneseDateTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -32,7 +32,7 @@
  * @author Kazuki Shimizu
  */
 @UsesJava8
-public class JapaneseDateTypeHandler extends BaseTypeHandler<JapaneseDate> {
+public class JapaneseDateTypeHandler extends NullableApiBasedTypeHandler<JapaneseDate> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, JapaneseDate parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/LocalDateTimeTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -29,7 +29,7 @@
  * @author Tomas Rohovsky
  */
 @UsesJava8
-public class LocalDateTimeTypeHandler extends BaseTypeHandler<LocalDateTime> {
+public class LocalDateTimeTypeHandler extends NullableApiBasedTypeHandler<LocalDateTime> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, LocalDateTime parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/LocalDateTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -29,7 +29,7 @@
  * @author Tomas Rohovsky
  */
 @UsesJava8
-public class LocalDateTypeHandler extends BaseTypeHandler<LocalDate> {
+public class LocalDateTypeHandler extends NullableApiBasedTypeHandler<LocalDate> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, LocalDate parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/LocalTimeTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -29,7 +29,7 @@
  * @author Tomas Rohovsky
  */
 @UsesJava8
-public class LocalTimeTypeHandler extends BaseTypeHandler<LocalTime> {
+public class LocalTimeTypeHandler extends NullableApiBasedTypeHandler<LocalTime> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, LocalTime parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/NStringTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2015 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -23,7 +23,7 @@
 /**
  * @author Clinton Begin
  */
-public class NStringTypeHandler extends BaseTypeHandler<String> {
+public class NStringTypeHandler extends NullableApiBasedTypeHandler<String> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType)

src/main/java/org/apache/ibatis/type/NullableApiBasedTypeHandler.java

@@ -0,0 +1,76 @@
+/**
+ *    Copyright 2009-2018 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
+ *
+ *       http://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.apache.ibatis.type;
+
+import java.sql.CallableStatement;
+import java.sql.ResultSet;
+
+/**
+ * The base {@link TypeHandler} for using nullable JDBC APIs (APIs that it return <code>null</code>,
+ * if the value is SQL <code>NULL</code>).
+ * <p>
+ * Nullable JDBC APIs are follows on {@link ResultSet} or {@link CallableStatement}:
+ * </p>
+ * <ul>
+ * <li><code>getAsciiStream()</code></li>
+ * <li><code>getBigDecimal()</code></li>
+ * <li><code>getBinaryStream()</code></li>
+ * <li><code>getBytes()</code></li>
+ * <li><code>getCharacterStream()</code></li>
+ * <li><code>getDate()</code></li>
+ * <li><code>getNCharacterStream()</code></li>
+ * <li><code>getNString()</code></li>
+ * <li><code>getRowId()</code></li>
+ * <li><code>getString()</code></li>
+ * <li><code>getTime()</code></li>
+ * <li><code>getTimestamp()</code></li>
+ * <li><code>getUnicodeStream()</code></li>
+ * <li><code>getURL()</code></li>
+ * </ul>
+ * <p>
+ * If you create a custom {@link TypeHandler} using above APIs, we propose to use this class instead
+ * of the {@link BaseTypeHandler}. This class is efficient than the {@link BaseTypeHandler} because
+ * it does not call the <code>wasNull()</code> on {@link ResultSet} or {@link CallableStatement} for
+ * handling null value.
+ * </p>
+ *
+ * @param <T> the referenced type
+ * @author Kazuki Shimizu
+ * @since 3.5.0
+ */
+public abstract class NullableApiBasedTypeHandler<T> extends BaseTypeHandler<T> {
+
+  /**
+   * {@inheritDoc}
+   * 
+   * @return Always return a fetched result
+   */
+  @Override
+  protected T handleResult(ResultSet rs, T result) {
+    return result;
+  }
+
+  /**
+   * {@inheritDoc}
+   * 
+   * @return Always return a fetched result
+   */
+  @Override
+  protected T handleResult(CallableStatement cs, T result) {
+    return result;
+  }
+
+}

src/main/java/org/apache/ibatis/type/OffsetDateTimeTypeHandler.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2018 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.
@@ -30,7 +30,7 @@
  * @author Tomas Rohovsky
  */
 @UsesJava8
-public class OffsetDateTimeTypeHandler extends BaseTypeHandler<OffsetDateTime> {
+public class OffsetDateTimeTypeHandler extends NullableApiBasedTypeHandler<OffsetDateTime> {
 
   @Override
   public void setNonNullParameter(PreparedStatement ps, int i, OffsetDateTime parameter, JdbcType jdbcType)