View Javadoc

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  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>, [&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 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 }