001: /*
002: * Copyright 2004 Clinton Begin
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package com.ibatis.sqlmap.client.extensions;
017:
018: import java.sql.SQLException;
019:
020: /**
021: * A simple interface for implementing custom type handlers.
022: * <p/>
023: * Using this interface, you can implement a type handler that
024: * will perform customized processing before parameters are set
025: * on a PreparedStatement and after values are retrieved from
026: * a ResultSet. Using a custom type handler you can extend
027: * the framework to handle types that are not supported, or
028: * handle supported types in a different way. For example,
029: * you might use a custom type handler to implement proprietary
030: * BLOB support (e.g. Oracle), or you might use it to handle
031: * booleans using "Y" and "N" instead of the more typical 0/1.
032: * <p/>
033: * <b>EXAMPLE</b>
034: * <p>Here's a simple example of a boolean handler that uses "Yes" and "No".</p>
035: * <pre>
036: * public class YesNoBoolTypeHandlerCallback implements TypeHandlerCallback {
037: * <p/>
038: * private static final String YES = "Yes";
039: * private static final String NO = "No";
040: * <p/>
041: * public Object getResult(ResultGetter getter) throws SQLException {
042: * String s = getter.getString();
043: * if (YES.equalsIgnoreCase(s)) {
044: * return new Boolean (true);
045: * } else if (NO.equalsIgnoreCase(s)) {
046: * return new Boolean (false);
047: * } else {
048: * throw new SQLException ("Unexpected value " + s + " found where "+YES+" or "+NO+" was expected.");
049: * }
050: * }
051: * <p/>
052: * public void setParameter(ParameterSetter setter, Object parameter) throws SQLException {
053: * boolean b = ((Boolean)parameter).booleanValue();
054: * if (b) {
055: * setter.setString(YES);
056: * } else {
057: * setter.setString(NO);
058: * }
059: * }
060: * <p/>
061: * public Object valueOf(String s) {
062: * if (YES.equalsIgnoreCase(s)) {
063: * return new Boolean (true);
064: * } else if (NO.equalsIgnoreCase(s)) {
065: * return new Boolean (false);
066: * } else {
067: * throw new SQLException ("Unexpected value " + s + " found where "+YES+" or "+NO+" was expected.");
068: * }
069: * }
070: * <p/>
071: * }
072: * </pre>
073: */
074: public interface TypeHandlerCallback {
075:
076: /**
077: * Performs processing on a value before it is used to set
078: * the parameter of a PreparedStatement.
079: *
080: * @param setter The interface for setting the value on the PreparedStatement.
081: * @param parameter The value to be set.
082: * @throws SQLException If any error occurs.
083: */
084: public void setParameter(ParameterSetter setter, Object parameter)
085: throws SQLException;
086:
087: /**
088: * Performs processing on a value before after it has been retrieved
089: * from a ResultSet.
090: *
091: * @param getter The interface for getting the value from the ResultSet.
092: * @return The processed value.
093: * @throws SQLException If any error occurs.
094: */
095: public Object getResult(ResultGetter getter) throws SQLException;
096:
097: /**
098: * Casts the string representation of a value into a type recognized by
099: * this type handler. This method is used to translate nullValue values
100: * into types that can be appropriately compared. If your custom type handler
101: * cannot support nullValues, or if there is no reasonable string representation
102: * for this type (e.g. File type), you can simply return the String representation
103: * as it was passed in. It is not recommended to return null, unless null was passed
104: * in.
105: *
106: * @param s A string representation of a valid value for this type.
107: * @return One of the following:
108: * <ol>
109: * <li>the casted repersentation of the String value,</li>
110: * <li>the string as is,</li>
111: * <li>null, only if null was passed in.</li>
112: * </ol>
113: */
114: public Object valueOf(String s);
115:
116: }
|