KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > torque > adapter > DB


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 JavaDoc;
23 import java.sql.Connection JavaDoc;
24 import java.sql.SQLException JavaDoc;
25 import java.util.Date JavaDoc;
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 JavaDoc, 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>, [&lt;offset&gt;]</code>
75      * @deprecated This should not be exposed to the outside
76      */
77     int LIMIT_STYLE_POSTGRES = 1;
78
79     /** <code>SELECT ... LIMIT [<offset>, ] &lt;offset&gt;</code>
80      * @deprecated This should not be exposed to the outside
81      */
82     int LIMIT_STYLE_MYSQL = 2;
83
84     /** <code>SET ROWCOUNT &lt;offset&gt; 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 JavaDoc ADAPTER_KEY = "adapter";
103
104     /**
105      * Key for the configuration which contains database drivers.
106      */
107     String JavaDoc 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 JavaDoc toUpperCase(String JavaDoc 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 JavaDoc 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 JavaDoc getIDMethodSQL(Object JavaDoc 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 JavaDoc con, String JavaDoc table)
153             throws SQLException JavaDoc;
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 JavaDoc con, String JavaDoc table)
163             throws SQLException JavaDoc;
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 JavaDoc ignoreCase(String JavaDoc 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 JavaDoc ignoreCaseInOrderBy(String JavaDoc 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 JavaDoc getDateString(Date JavaDoc 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 JavaDoc getBooleanString(Boolean JavaDoc 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 }
272
Popular Tags