1 package org.apache.torque.adapter;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.io.Serializable;
23 import java.sql.Connection;
24 import java.sql.SQLException;
25
26 import org.apache.torque.TorqueException;
27 import org.apache.torque.sql.Query;
28
29 /**
30 * <code>DB</code> defines the interface for a Torque database
31 * adapter. Support for new databases is added by implementing this
32 * interface. A couple of default settings is provided by
33 * subclassing <code>AbstractDBAdapter</code>. The new database adapter
34 * and its corresponding JDBC driver need to be registered in the service
35 * configuration file.
36 *
37 * <p>The Torque database adapters exist to present a uniform
38 * interface to database access across all available databases. Once
39 * the necessary adapters have been written and configured,
40 * transparent swapping of databases is theoretically supported with
41 * <i>zero code changes</i> and minimal configuration file
42 * modifications.
43 *
44 * All database adapters need to be thread safe, as they are instantiated
45 * only once fore a given configured database and may be accessed
46 * simultaneously from several threads.
47 * *
48 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
49 * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
50 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
51 * @author <a href="mailto:vido@ldh.org">Augustin Vidovic</a>
52 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
53 * @author <a href="mailto:greg.monroe@dukece.com">Greg Monroe</a>
54 * @version $Id: Adapter.java 1355228 2012-06-29 03:38:08Z tfischer $
55 */
56 public interface Adapter extends Serializable
57 {
58 /** Key for the configuration which contains database adapters. */
59 String ADAPTER_KEY = "adapter";
60
61 /** Key for the configuration which contains database drivers. */
62 String DRIVER_KEY = "driver";
63
64 /** Special adapter for auto-detection. */
65 String AUTODETECT_ADAPTER = "auto";
66
67 /**
68 * Wraps the input string in a database function to change it to upper case.
69 *
70 * @param in The string to transform to upper case, may be a literal string,
71 * a prepared statement replacement placeholder(*) or any other
72 * database expression.
73 *
74 * @return The wrapped input string, so that the database evaluates the
75 * returned expression to the upper case of the input.
76 */
77 String toUpperCase(String in);
78
79 /**
80 * Returns the character used to indicate the beginning and end of
81 * a piece of text used in a SQL statement (generally a single
82 * quote).
83 *
84 * @return The text delimiter.
85 */
86 char getStringDelimiter();
87
88 /**
89 * Returns the constant from the {@link
90 * org.apache.torque.adapter.IDMethod} interface denoting which
91 * type of primary key generation method this type of RDBMS uses.
92 *
93 * @return IDMethod constant
94 */
95 IDMethod getIDMethodType();
96
97 /**
98 * Returns SQL used to get the most recently inserted primary key.
99 * Databases which have no support for this return
100 * <code>null</code>.
101 *
102 * @param obj Information used for key generation.
103 *
104 * @return The most recently inserted database key.
105 */
106 String getIDMethodSQL(Object obj);
107
108 /**
109 * Locks the specified table.
110 *
111 * @param con The JDBC connection to use.
112 * @param table The name of the table to lock.
113 *
114 * @throws SQLException No Statement could be created or executed.
115 */
116 void lockTable(Connection con, String table)
117 throws SQLException;
118
119 /**
120 * Unlocks the specified table.
121 *
122 * @param con The JDBC connection to use.
123 * @param table The name of the table to unlock.
124 *
125 * @throws SQLException No Statement could be created or executed.
126 */
127 void unlockTable(Connection con, String table)
128 throws SQLException;
129
130 /**
131 * Wraps the input string in a database function to change it to
132 * a case-insensitive representation.
133 *
134 * @param in The string to transform to a case-insensitive representation,
135 * may be a literal string, a prepared statement replacement
136 * placeholder(*) or any other database expression.
137 *
138 * @return The wrapped input string, so that the database evaluates the
139 * returned expression to a case-insensitive representation
140 * of the input.
141 */
142 String ignoreCase(String in);
143
144 /**
145 * This method is used to ignore case in an ORDER BY clause.
146 * Usually it is the same as ignoreCase, but some databases
147 * (hsqldb for example) does not use the same SQL in ORDER BY
148 * and other clauses.
149 *
150 * @param in The string whose case to ignore.
151 *
152 * @return The string in a case that can be ignored.
153 */
154 String ignoreCaseInOrderBy(String in);
155
156 /**
157 * This method is used to check whether the database natively
158 * supports limiting the size of the resultset.
159 *
160 * @return true if the database natively supports limiting the
161 * size of the resultset.
162 */
163 boolean supportsNativeLimit();
164
165 /**
166 * This method is used to check whether the database natively
167 * supports returning results starting at an offset position other
168 * than 0.
169 *
170 * @return true if the database natively supports returning
171 * results starting at an offset position other than 0.
172 */
173 boolean supportsNativeOffset();
174
175 /**
176 * This method is used to generate the database specific query
177 * extension to limit the number of record returned.
178 *
179 * @param query The query to modify
180 * @param offset the offset Value
181 * @param limit the limit Value
182 *
183 * @throws TorqueException if any error occurs when building the query
184 */
185 void generateLimits(Query query, long offset, int limit)
186 throws TorqueException;
187
188 /**
189 * Determines whether backslashes (\) should be escaped in explicit SQL
190 * strings. If true is returned, a BACKSLASH will be changed to "\\".
191 * If false is returned, a BACKSLASH will be left as "\".
192 *
193 * @return true if the database needs to escape backslashes
194 * in SqlExpressions.
195 */
196 boolean escapeText();
197
198 /**
199 * Whether ILIKE should be used for case insensitive like clauses.
200 *
201 * @return true if ilike should be used for case insensitive likes,
202 * false if ignoreCase should be applied to the compared strings.
203 */
204 boolean useIlike();
205
206 /**
207 * Whether an escape clause in like should be used.
208 * Example : select * from AUTHOR where AUTHOR.NAME like '\_%' ESCAPE '\';
209 *
210 * @return whether the escape clause should be appended or not.
211 */
212 boolean useEscapeClauseForLike();
213
214 /**
215 * Creates a Torque exception from a database-specific exception.
216 *
217 * @param e the database-specific exception to create the exception from
218 *
219 * @return the corresponding Torque exception, possibly a subclass.
220 */
221 TorqueException toTorqueException(SQLException e);
222 }