1 /*
2 * Copyright 2004-2022 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 com.ibatis.sqlmap.client.extensions;
17
18 import java.sql.SQLException;
19
20 /**
21 * A simple interface for implementing custom type handlers.
22 * <p>
23 * Using this interface, you can implement a type handler that will perform customized processing before parameters are
24 * set on a PreparedStatement and after values are retrieved from a ResultSet. Using a custom type handler you can
25 * extend the framework to handle types that are not supported, or handle supported types in a different way. For
26 * example, you might use a custom type handler to implement proprietary BLOB support (e.g. Oracle), or you might use it
27 * to handle booleans using "Y" and "N" instead of the more typical 0/1.
28 * <p>
29 * <b>EXAMPLE</b>
30 * <p>
31 * Here's a simple example of a boolean handler that uses "Yes" and "No".
32 *
33 * <pre>
34 * public class YesNoBoolTypeHandlerCallback implements TypeHandlerCallback {
35 *
36 * private static final String YES = "Yes";
37 * private static final String NO = "No";
38 *
39 * public Object getResult(ResultGetter getter) throws SQLException {
40 * String s = getter.getString();
41 * if (YES.equalsIgnoreCase(s)) {
42 * return new Boolean(true);
43 * } else if (NO.equalsIgnoreCase(s)) {
44 * return new Boolean(false);
45 * } else {
46 * throw new SQLException("Unexpected value " + s + " found where " + YES + " or " + NO + " was expected.");
47 * }
48 * }
49 *
50 * public void setParameter(ParameterSetter setter, Object parameter) throws SQLException {
51 * boolean b = ((Boolean) parameter).booleanValue();
52 * if (b) {
53 * setter.setString(YES);
54 * } else {
55 * setter.setString(NO);
56 * }
57 * }
58 *
59 * public Object valueOf(String s) {
60 * if (YES.equalsIgnoreCase(s)) {
61 * return new Boolean(true);
62 * } else if (NO.equalsIgnoreCase(s)) {
63 * return new Boolean(false);
64 * } else {
65 * throw new SQLException("Unexpected value " + s + " found where " + YES + " or " + NO + " was expected.");
66 * }
67 * }
68 *
69 * }
70 * </pre>
71 */
72 public interface TypeHandlerCallback {
73
74 /**
75 * Performs processing on a value before it is used to set the parameter of a PreparedStatement.
76 *
77 * @param setter
78 * The interface for setting the value on the PreparedStatement.
79 * @param parameter
80 * The value to be set.
81 *
82 * @throws SQLException
83 * If any error occurs.
84 */
85 public void setParameter(ParameterSetter setter, Object parameter) throws SQLException;
86
87 /**
88 * Performs processing on a value before after it has been retrieved from a ResultSet.
89 *
90 * @param getter
91 * The interface for getting the value from the ResultSet.
92 *
93 * @return The processed value.
94 *
95 * @throws SQLException
96 * If any error occurs.
97 */
98 public Object getResult(ResultGetter getter) throws SQLException;
99
100 /**
101 * Casts the string representation of a value into a type recognized by this type handler. This method is used to
102 * translate nullValue values into types that can be appropriately compared. If your custom type handler cannot
103 * support nullValues, or if there is no reasonable string representation for this type (e.g. File type), you can
104 * simply return the String representation as it was passed in. It is not recommended to return null, unless null was
105 * passed in.
106 *
107 * @param s
108 * A string representation of a valid value for this type.
109 *
110 * @return One of the following:
111 * <ol>
112 * <li>the casted repersentation of the String value,</li>
113 * <li>the string as is,</li>
114 * <li>null, only if null was passed in.</li>
115 * </ol>
116 */
117 public Object valueOf(String s);
118
119 }