001: package org.apache.torque.adapter;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.io.Serializable;
023: import java.sql.Connection;
024: import java.sql.SQLException;
025: import java.util.Date;
026:
027: import org.apache.torque.TorqueException;
028: import org.apache.torque.util.Query;
029:
030: /**
031: * <code>DB</code> defines the interface for a Torque database
032: * adapter. Support for new databases is added by implementing this
033: * interface. A couple of default settings is provided by
034: * subclassing <code>AbstractDBAdapter</code>. The new database adapter
035: * and its corresponding JDBC driver need to be registered in the service
036: * configuration file.
037: *
038: * <p>The Torque database adapters exist to present a uniform
039: * interface to database access across all available databases. Once
040: * the necessary adapters have been written and configured,
041: * transparent swapping of databases is theoretically supported with
042: * <i>zero code changes</i> and minimal configuration file
043: * modifications.
044: *
045: * All database adapters need to be thread safe, as they are instantiated
046: * only once fore a given configured database and may be accessed
047: * simultaneously from several threads.
048: *
049: * <p>Torque uses the driver class name to find the right adapter.
050: * A JDBC driver corresponding to your adapter must be added to the properties
051: * file, using the fully-qualified class name of the driver. If no driver is
052: * specified for your database, <code>driver.default</code> is used.
053: *
054: * <pre>
055: * #### MySQL MM Driver
056: * database.default.driver=org.gjt.mm.mysql.Driver
057: * database.default.url=jdbc:mysql://localhost/DATABASENAME
058: * </pre>
059: *
060: * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
061: * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
062: * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
063: * @author <a href="mailto:vido@ldh.org">Augustin Vidovic</a>
064: * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
065: * @version $Id: DB.java 476550 2006-11-18 16:08:37Z tfischer $
066: */
067: public interface DB extends Serializable, IDMethod {
068: /** Database does not support limiting result sets.
069: * @deprecated This should not be exposed to the outside
070: */
071: int LIMIT_STYLE_NONE = 0;
072:
073: /** <code>SELECT ... LIMIT <limit>, [<offset>]</code>
074: * @deprecated This should not be exposed to the outside
075: */
076: int LIMIT_STYLE_POSTGRES = 1;
077:
078: /** <code>SELECT ... LIMIT [<offset>, ] <offset></code>
079: * @deprecated This should not be exposed to the outside
080: */
081: int LIMIT_STYLE_MYSQL = 2;
082:
083: /** <code>SET ROWCOUNT <offset> SELECT ... SET ROWCOUNT 0</code>
084: * @deprecated This should not be exposed to the outside
085: */
086: int LIMIT_STYLE_SYBASE = 3;
087:
088: /** <code><pre>SELECT ... WHERE ... AND ROWNUM < <limit></pre></code>
089: * @deprecated This should not be exposed to the outside
090: */
091: int LIMIT_STYLE_ORACLE = 4;
092:
093: /** <code><pre>SELECT ... WHERE ... AND ROW_NUMBER() OVER() < <limit></pre></code>
094: * @deprecated This should not be exposed to the outside
095: */
096: int LIMIT_STYLE_DB2 = 5;
097:
098: /**
099: * Key for the configuration which contains database adapters.
100: */
101: String ADAPTER_KEY = "adapter";
102:
103: /**
104: * Key for the configuration which contains database drivers.
105: */
106: String DRIVER_KEY = "driver";
107:
108: /**
109: * This method is used to ignore case.
110: *
111: * @param in The string to transform to upper case.
112: * @return The upper case string.
113: */
114: String toUpperCase(String in);
115:
116: /**
117: * Returns the character used to indicate the beginning and end of
118: * a piece of text used in a SQL statement (generally a single
119: * quote).
120: *
121: * @return The text delimeter.
122: */
123: char getStringDelimiter();
124:
125: /**
126: * Returns the constant from the {@link
127: * org.apache.torque.adapter.IDMethod} interface denoting which
128: * type of primary key generation method this type of RDBMS uses.
129: *
130: * @return IDMethod constant
131: */
132: String getIDMethodType();
133:
134: /**
135: * Returns SQL used to get the most recently inserted primary key.
136: * Databases which have no support for this return
137: * <code>null</code>.
138: *
139: * @param obj Information used for key generation.
140: * @return The most recently inserted database key.
141: */
142: String getIDMethodSQL(Object obj);
143:
144: /**
145: * Locks the specified table.
146: *
147: * @param con The JDBC connection to use.
148: * @param table The name of the table to lock.
149: * @throws SQLException No Statement could be created or executed.
150: */
151: void lockTable(Connection con, String table) throws SQLException;
152:
153: /**
154: * Unlocks the specified table.
155: *
156: * @param con The JDBC connection to use.
157: * @param table The name of the table to unlock.
158: * @throws SQLException No Statement could be created or executed.
159: */
160: void unlockTable(Connection con, String table) throws SQLException;
161:
162: /**
163: * Modifies a SQL snippet such that its case is ignored by the database.
164: * The SQL snippet can be a column name (like AURHOR.NAME), an
165: * quoted explicit sql string (like 'abc') or any other sql value (like a
166: * number etc.).
167: *
168: * @param in The SQL snippet whose case to ignore.
169: * @return The string in a case that can be ignored.
170: */
171: String ignoreCase(String in);
172:
173: /**
174: * This method is used to ignore case in an ORDER BY clause.
175: * Usually it is the same as ignoreCase, but some databases
176: * (Interbase for example) does not use the same SQL in ORDER BY
177: * and other clauses.
178: *
179: * @param in The string whose case to ignore.
180: * @return The string in a case that can be ignored.
181: */
182: String ignoreCaseInOrderBy(String in);
183:
184: /**
185: * This method is used to check whether the database natively
186: * supports limiting the size of the resultset.
187: *
188: * @return True if the database natively supports limiting the
189: * size of the resultset.
190: */
191: boolean supportsNativeLimit();
192:
193: /**
194: * This method is used to check whether the database natively
195: * supports returning results starting at an offset position other
196: * than 0.
197: *
198: * @return True if the database natively supports returning
199: * results starting at an offset position other than 0.
200: */
201: boolean supportsNativeOffset();
202:
203: /**
204: * This method is used to generate the database specific query
205: * extension to limit the number of record returned.
206: *
207: * @param query The query to modify
208: * @param offset the offset Value
209: * @param limit the limit Value
210: *
211: * @throws TorqueException if any error occurs when building the query
212: */
213: void generateLimits(Query query, int offset, int limit)
214: throws TorqueException;
215:
216: /**
217: * Whether backslashes (\) should be escaped in explicit SQL strings.
218: * If true is returned, a BACKSLASH will be changed to "\\". If false
219: * is returned, a BACKSLASH will be left as "\".
220: *
221: * @return true if the database needs to escape backslashes
222: * in SqlExpressions.
223: */
224:
225: boolean escapeText();
226:
227: /**
228: * This method is used to check whether the database supports
229: * limiting the size of the resultset.
230: *
231: * @return The limit style for the database.
232: * @deprecated This should not be exposed to the outside
233: */
234: int getLimitStyle();
235:
236: /**
237: * This method is used to format any date string.
238: * Database can use different default date formats.
239: *
240: * @param date the Date to format
241: * @return The proper date formatted String.
242: */
243: String getDateString(Date date);
244:
245: /**
246: * This method is used to format a boolean string.
247: *
248: * @param b the Boolean to format
249: * @return The proper date formatted String.
250: */
251: String getBooleanString(Boolean b);
252:
253: /**
254: * Whether ILIKE should be used for case insensitive like clauses.
255: *
256: * @return true if ilike should be used for case insensitive likes,
257: * false if ignoreCase should be applied to the compared strings.
258: */
259: boolean useIlike();
260:
261: /**
262: * Whether an escape clause in like should be used.
263: * Example : select * from AUTHOR where AUTHOR.NAME like '\_%' ESCAPE '\';
264: *
265: * @return whether the escape clause should be appended or not.
266: */
267: boolean useEscapeClauseForLike();
268: }
|