View Javadoc

1   package org.apache.torque.adapter;
2   
3   /*
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.Date;
20  import java.io.Serializable;
21  import java.sql.Connection;
22  import java.sql.SQLException;
23  import java.sql.Timestamp;
24  
25  /***
26   * <code>DB</code> defines the interface for a Torque database
27   * adapter.  Support for new databases is added by subclassing
28   * <code>DB</code> and implementing its abstract interface, and by
29   * registering the new database adapter and its corresponding
30   * JDBC driver in the service configuration file.
31   *
32   * <p>The Torque database adapters exist to present a uniform
33   * interface to database access across all available databases.  Once
34   * the necessary adapters have been written and configured,
35   * transparent swapping of databases is theoretically supported with
36   * <i>zero code changes</i> and minimal configuration file
37   * modifications.
38   *
39   * <p>Torque uses the driver class name to find the right adapter.
40   * A JDBC driver corresponding to your adapter must be added to the properties
41   * file, using the fully-qualified class name of the driver. If no driver is
42   * specified for your database, <code>driver.default</code> is used.
43   *
44   * <pre>
45   * #### MySQL MM Driver
46   * database.default.driver=org.gjt.mm.mysql.Driver
47   * database.default.url=jdbc:mysql://localhost/DATABASENAME
48   * </pre>
49   *
50   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
51   * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
52   * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
53   * @author <a href="mailto:vido@ldh.org">Augustin Vidovic</a>
54   * @version $Id: DB.java,v 1.31.2.3 2004/08/06 12:13:12 seade Exp $
55   */
56  public abstract class DB implements Serializable, IDMethod
57  {
58      /*** Database does not support limiting result sets. */
59      public static final int LIMIT_STYLE_NONE = 0;
60  
61      /*** <code>SELECT ... LIMIT <limit>, [&lt;offset&gt;]</code> */
62      public static final int LIMIT_STYLE_POSTGRES = 1;
63  
64      /*** <code>SELECT ... LIMIT [<offset>, ] &lt;offset&gt;</code> */
65      public static final int LIMIT_STYLE_MYSQL = 2;
66  
67      /*** <code>SET ROWCOUNT &lt;offset&gt; SELECT ... SET ROWCOUNT 0</code> */
68      public static final int LIMIT_STYLE_SYBASE = 3;
69  
70      /*** <code><pre>SELECT ... WHERE ... AND ROWNUM < <limit></pre></code> */
71      public static final int LIMIT_STYLE_ORACLE = 4;
72  
73      /*** <code><pre>SELECT ... WHERE ... AND ROW_NUMBER() OVER() < <limit></pre></code> */
74      public static final int LIMIT_STYLE_DB2 = 5;
75  
76      /***
77       * Empty constructor.
78       */
79      protected DB()
80      {
81      }
82  
83      /***
84       * This method is used to ignore case.
85       *
86       * @param in The string to transform to upper case.
87       * @return The upper case string.
88       */
89      public abstract String toUpperCase(String in);
90  
91      /***
92       * Returns the character used to indicate the beginning and end of
93       * a piece of text used in a SQL statement (generally a single
94       * quote).
95       *
96       * @return The text delimeter.
97       */
98      public char getStringDelimiter()
99      {
100         return '\'';
101     }
102 
103     /***
104      * Returns the constant from the {@link
105      * org.apache.torque.adapter.IDMethod} interface denoting which
106      * type of primary key generation method this type of RDBMS uses.
107      *
108      * @return IDMethod constant
109      */
110     public abstract String getIDMethodType();
111 
112     /***
113      * Returns SQL used to get the most recently inserted primary key.
114      * Databases which have no support for this return
115      * <code>null</code>.
116      *
117      * @param obj Information used for key generation.
118      * @return The most recently inserted database key.
119      */
120     public abstract String getIDMethodSQL(Object obj);
121 
122     /***
123      * Locks the specified table.
124      *
125      * @param con The JDBC connection to use.
126      * @param table The name of the table to lock.
127      * @throws SQLException No Statement could be created or executed.
128      */
129     public abstract void lockTable(Connection con, String table)
130             throws SQLException;
131 
132     /***
133      * Unlocks the specified table.
134      *
135      * @param con The JDBC connection to use.
136      * @param table The name of the table to unlock.
137      * @throws SQLException No Statement could be created or executed.
138      */
139     public abstract void unlockTable(Connection con, String table)
140             throws SQLException;
141 
142     /***
143      * This method is used to ignore case.
144      *
145      * @param in The string whose case to ignore.
146      * @return The string in a case that can be ignored.
147      */
148     public abstract String ignoreCase(String in);
149 
150     /***
151      * This method is used to ignore case in an ORDER BY clause.
152      * Usually it is the same as ignoreCase, but some databases
153      * (Interbase for example) does not use the same SQL in ORDER BY
154      * and other clauses.
155      *
156      * @param in The string whose case to ignore.
157      * @return The string in a case that can be ignored.
158      */
159     public String ignoreCaseInOrderBy(String in)
160     {
161         return ignoreCase(in);
162     }
163 
164     /***
165      * This method is used to check whether the database natively
166      * supports limiting the size of the resultset.
167      *
168      * @return True if the database natively supports limiting the
169      * size of the resultset.
170      */
171     public boolean supportsNativeLimit()
172     {
173         return false;
174     }
175 
176     /***
177      * This method is used to check whether the database natively
178      * supports returning results starting at an offset position other
179      * than 0.
180      *
181      * @return True if the database natively supports returning
182      * results starting at an offset position other than 0.
183      */
184     public boolean supportsNativeOffset()
185     {
186         return false;
187     }
188 
189    /***
190     * This method is for the SqlExpression.quoteAndEscape rules.  The rule is,
191     * any string in a SqlExpression with a BACKSLASH will either be changed to
192     * "//" or left as "\".  SapDB does not need the escape character.
193     *
194     * @return true if the database needs to escape text in SqlExpressions.
195     */
196 
197     public boolean escapeText()
198     {
199         return true;
200     }
201 
202     /***
203      * This method is used to check whether the database supports
204      * limiting the size of the resultset.
205      *
206      * @return The limit style for the database.
207      */
208     public int getLimitStyle()
209     {
210         return LIMIT_STYLE_NONE;
211     }
212 
213     /***
214      * This method is used to format any date string.
215      * Database can use different default date formats.
216      *
217      * @param date the Date to format
218      * @return The proper date formatted String.
219      */
220     public String getDateString(Date date)
221     {
222         Timestamp ts = null;
223         if (date instanceof Timestamp)
224         {
225             ts = (Timestamp) date;
226         }
227         else
228         {
229             ts = new Timestamp(date.getTime());
230         }
231 
232         return ("{ts '" + ts + "'}");
233     }
234 
235     /***
236      * This method is used to format a boolean string.
237      *
238      * @param b the Boolean to format
239      * @return The proper date formatted String.
240      */
241     public String getBooleanString(Boolean b)
242     {
243         return (Boolean.TRUE.equals(b) ? "1" : "0");
244     }
245 }