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