1 /*
2 * Copyright 2016-2025 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.mybatis.dynamic.sql;
17
18 import org.jspecify.annotations.Nullable;
19
20 /**
21 * A parameter type converter is used to change a parameter value from one type to another
22 * during statement rendering and before the parameter is placed into the parameter map. This can be used
23 * to somewhat mimic the function of a MyBatis type handler for runtimes such as Spring that don't have
24 * a corresponding concept.
25 *
26 * <p>Since Spring does not have the concept of type handlers, it is a best practice to only use
27 * Java data types that have a clear correlation to SQL data types (for example Java String correlates
28 * automatically with VARCHAR). Using a parameter type converter will allow you to use data types in your
29 * model classes that would otherwise be difficult to use with Spring.
30 *
31 * <p>A parameter type converter is associated with a SqlColumn.
32 *
33 * <p>This interface is based on Spring's general Converter interface and is intentionally compatible with it.
34 * Existing converters may be reused if they are marked with this additional interface.
35 *
36 * <p>The converter is only used for parameters in a parameter map. It is not used for result set processing.
37 * It is also not used for insert statements that are based on an external row class. The converter will be called
38 * in the following circumstances:
39 *
40 * <ul>
41 * <li>Parameters in a general insert statement (for the Value and ValueWhenPresent mappings)</li>
42 * <li>Parameters in an update statement (for the Value and ValueWhenPresent mappings)</li>
43 * <li>Parameters in a where clause in any statement (for conditions that accept a value or multiple values)</li>
44 * </ul>
45 *
46 * @param <S> Source Type
47 * @param <T> Target Type
48 *
49 * @see SqlColumn
50 * @author Jeff Butler
51 * @since 1.1.5
52 */
53 @FunctionalInterface
54 public interface ParameterTypeConverter<S, T> {
55 /**
56 * Convert the value from one value to another.
57 *
58 * <p>The input value will never be null - the framework will automatically handle nulls.
59 *
60 * @param source value as specified in the condition, or after a map operation. Never null.
61 * @return Possibly null converted value.
62 */
63 @Nullable T convert(S source);
64 }