1 package org.apache.torque.adapter;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.io.Serializable;
23 import java.sql.Connection;
24 import java.sql.SQLException;
25 import java.util.Date;
26
27 import org.apache.torque.TorqueException;
28 import org.apache.torque.util.Query;
29 import org.apache.torque.util.functions.FunctionEnum;
30
31 /***
32 * <code>DB</code> defines the interface for a Torque database
33 * adapter. Support for new databases is added by implementing this
34 * interface. A couple of default settings is provided by
35 * subclassing <code>AbstractDBAdapter</code>. The new database adapter
36 * and its corresponding JDBC driver need to be registered in the service
37 * configuration file.
38 *
39 * <p>The Torque database adapters exist to present a uniform
40 * interface to database access across all available databases. Once
41 * the necessary adapters have been written and configured,
42 * transparent swapping of databases is theoretically supported with
43 * <i>zero code changes</i> and minimal configuration file
44 * modifications.
45 *
46 * All database adapters need to be thread safe, as they are instantiated
47 * only once fore a given configured database and may be accessed
48 * simultaneously from several threads.
49 *
50 * <p>Torque uses the driver class name to find the right adapter.
51 * A JDBC driver corresponding to your adapter must be added to the properties
52 * file, using the fully-qualified class name of the driver. If no driver is
53 * specified for your database, <code>driver.default</code> is used.
54 *
55 * <pre>
56 * #### MySQL MM Driver
57 * database.default.driver=org.gjt.mm.mysql.Driver
58 * database.default.url=jdbc:mysql://localhost/DATABASENAME
59 * </pre>
60 *
61 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
62 * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
63 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
64 * @author <a href="mailto:vido@ldh.org">Augustin Vidovic</a>
65 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
66 * @author <a href="mailto:greg.monroe@dukece.com">Greg Monroe</a>
67 * @version $Id: DB.java 643209 2008-03-31 23:33:41Z gmonroe $
68 */
69 public interface DB extends Serializable, IDMethod
70 {
71 /*** Database does not support limiting result sets.
72 * @deprecated This should not be exposed to the outside
73 */
74 int LIMIT_STYLE_NONE = 0;
75
76 /*** <code>SELECT ... LIMIT <limit>, [<offset>]</code>
77 * @deprecated This should not be exposed to the outside
78 */
79 int LIMIT_STYLE_POSTGRES = 1;
80
81 /*** <code>SELECT ... LIMIT [<offset>, ] <offset></code>
82 * @deprecated This should not be exposed to the outside
83 */
84 int LIMIT_STYLE_MYSQL = 2;
85
86 /*** <code>SET ROWCOUNT <offset> SELECT ... SET ROWCOUNT 0</code>
87 * @deprecated This should not be exposed to the outside
88 */
89 int LIMIT_STYLE_SYBASE = 3;
90
91 /*** <code><pre>SELECT ... WHERE ... AND ROWNUM < <limit></pre></code>
92 * @deprecated This should not be exposed to the outside
93 */
94 int LIMIT_STYLE_ORACLE = 4;
95
96 /*** <code><pre>SELECT ... WHERE ... AND ROW_NUMBER() OVER() < <limit></pre></code>
97 * @deprecated This should not be exposed to the outside
98 */
99 int LIMIT_STYLE_DB2 = 5;
100
101 /***
102 * Key for the configuration which contains database adapters.
103 */
104 String ADAPTER_KEY = "adapter";
105
106 /***
107 * Key for the configuration which contains database drivers.
108 */
109 String DRIVER_KEY = "driver";
110
111 /***
112 * This method is used to ignore case.
113 *
114 * @param in The string to transform to upper case.
115 * @return The upper case string.
116 */
117 String toUpperCase(String in);
118
119 /***
120 * Returns the character used to indicate the beginning and end of
121 * a piece of text used in a SQL statement (generally a single
122 * quote).
123 *
124 * @return The text delimeter.
125 */
126 char getStringDelimiter();
127
128 /***
129 * Returns the constant from the {@link
130 * org.apache.torque.adapter.IDMethod} interface denoting which
131 * type of primary key generation method this type of RDBMS uses.
132 *
133 * @return IDMethod constant
134 */
135 String getIDMethodType();
136
137 /***
138 * Returns SQL used to get the most recently inserted primary key.
139 * Databases which have no support for this return
140 * <code>null</code>.
141 *
142 * @param obj Information used for key generation.
143 * @return The most recently inserted database key.
144 */
145 String getIDMethodSQL(Object obj);
146
147 /***
148 * Locks the specified table.
149 *
150 * @param con The JDBC connection to use.
151 * @param table The name of the table to lock.
152 * @throws SQLException No Statement could be created or executed.
153 */
154 void lockTable(Connection con, String table)
155 throws SQLException;
156
157 /***
158 * Unlocks the specified table.
159 *
160 * @param con The JDBC connection to use.
161 * @param table The name of the table to unlock.
162 * @throws SQLException No Statement could be created or executed.
163 */
164 void unlockTable(Connection con, String table)
165 throws SQLException;
166
167 /***
168 * Modifies a SQL snippet such that its case is ignored by the database.
169 * The SQL snippet can be a column name (like AURHOR.NAME), an
170 * quoted explicit sql string (like 'abc') or any other sql value (like a
171 * number etc.).
172 *
173 * @param in The SQL snippet whose case to ignore.
174 * @return The string in a case that can be ignored.
175 */
176 String ignoreCase(String in);
177
178 /***
179 * This method is used to ignore case in an ORDER BY clause.
180 * Usually it is the same as ignoreCase, but some databases
181 * (Interbase for example) does not use the same SQL in ORDER BY
182 * and other clauses.
183 *
184 * @param in The string whose case to ignore.
185 * @return The string in a case that can be ignored.
186 */
187 String ignoreCaseInOrderBy(String in);
188
189 /***
190 * This method is used to check whether the database natively
191 * supports limiting the size of the resultset.
192 *
193 * @return True if the database natively supports limiting the
194 * size of the resultset.
195 */
196 boolean supportsNativeLimit();
197
198 /***
199 * This method is used to check whether the database natively
200 * supports returning results starting at an offset position other
201 * than 0.
202 *
203 * @return True if the database natively supports returning
204 * results starting at an offset position other than 0.
205 */
206 boolean supportsNativeOffset();
207
208 /***
209 * This method is used to generate the database specific query
210 * extension to limit the number of record returned.
211 *
212 * @param query The query to modify
213 * @param offset the offset Value
214 * @param limit the limit Value
215 *
216 * @throws TorqueException if any error occurs when building the query
217 */
218 void generateLimits(Query query, int offset, int limit)
219 throws TorqueException;
220
221 /***
222 * Whether backslashes (\) should be escaped in explicit SQL strings.
223 * If true is returned, a BACKSLASH will be changed to "//". If false
224 * is returned, a BACKSLASH will be left as "\".
225 *
226 * @return true if the database needs to escape backslashes
227 * in SqlExpressions.
228 */
229
230 boolean escapeText();
231
232 /***
233 * This method is used to check whether the database supports
234 * limiting the size of the resultset.
235 *
236 * @return The limit style for the database.
237 * @deprecated This should not be exposed to the outside
238 */
239 int getLimitStyle();
240
241 /***
242 * This method is used to format any date string.
243 * Database can use different default date formats.
244 *
245 * @param date the Date to format
246 * @return The proper date formatted String.
247 */
248 String getDateString(Date date);
249
250 /***
251 * This method is used to format a boolean string.
252 *
253 * @param b the Boolean to format
254 * @return The proper date formatted String.
255 */
256 String getBooleanString(Boolean b);
257
258 /***
259 * Whether ILIKE should be used for case insensitive like clauses.
260 *
261 * @return true if ilike should be used for case insensitive likes,
262 * false if ignoreCase should be applied to the compared strings.
263 */
264 boolean useIlike();
265
266 /***
267 * Whether an escape clause in like should be used.
268 * Example : select * from AUTHOR where AUTHOR.NAME like '\_%' ESCAPE '\';
269 *
270 * @return whether the escape clause should be appended or not.
271 */
272 boolean useEscapeClauseForLike();
273
274 /***
275 * Return the class which implements the SQLFunction interface for the
276 * specified function. This class must have an empty constructor and
277 * can be a single level inner class (or not).
278 *
279 * @param function The function to get the class for.
280 * @return The SQLFunction implementation for a function of this type that
281 * will work with this type of DB. Null indicates a class was not
282 * found.
283 * @see SQLFunction
284 * @see AbstractFunction
285 * @see Aggregate
286 */
287 Class getFunctionClass( FunctionEnum function );
288 }