DbAdapter


1   /* ====================================================================
2    *
3    * The ObjectStyle Group Software License, version 1.1
4    * ObjectStyle Group - http://objectstyle.org/
5    * 
6    * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7    * of the software. All rights reserved.
8    * 
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   * 
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   * 
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   * 
21   * 3. The end-user documentation included with the redistribution, if any,
22   *    must include the following acknowlegement:
23   *    "This product includes software developed by independent contributors
24   *    and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25   *    Alternately, this acknowlegement may appear in the software itself,
26   *    if and wherever such third-party acknowlegements normally appear.
27   * 
28   * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29   *    or promote products derived from this software without prior written
30   *    permission. For written permission, email
31   *    "andrus at objectstyle dot org".
32   * 
33   * 5. Products derived from this software may not be called "ObjectStyle"
34   *    or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35   *    names without prior written permission.
36   * 
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   * 
51   * This software consists of voluntary contributions made by many
52   * individuals and hosted on ObjectStyle Group web site.  For more
53   * information on the ObjectStyle Group, please see
54   * <http://objectstyle.org/>.
55   */
56  
57  package org.objectstyle.cayenne.dba;
58  
59  import java.sql.Connection  ;
60  import java.sql.PreparedStatement  ;
61  import java.sql.SQLException  ;
62  import java.util.Collection  ;
63  
64  import org.objectstyle.cayenne.access.DataNode;
65  import org.objectstyle.cayenne.access.OperationObserver;
66  import org.objectstyle.cayenne.access.QueryTranslator;
67  import org.objectstyle.cayenne.access.trans.QualifierTranslator;
68  import org.objectstyle.cayenne.access.trans.QueryAssembler;
69  import org.objectstyle.cayenne.access.types.ExtendedTypeMap;
70  import org.objectstyle.cayenne.map.DbAttribute;
71  import org.objectstyle.cayenne.map.DbEntity;
72  import org.objectstyle.cayenne.map.DbRelationship;
73  import org.objectstyle.cayenne.query.BatchQuery;
74  import org.objectstyle.cayenne.query.Query;
75  import org.objectstyle.cayenne.query.SQLAction;
76  
77  /**
78   * Defines API needed to handle differences between various databases accessed via JDBC.
79   * Implementing classed are intended to be pluggable database-specific adapters.
80   * DbAdapter-based architecture is introduced to solve the following problems:
81   * <ul>
82   * <li>Make Cayenne code independent from SQL syntax differences between different RDBMS.
83   * <li>Allow for vendor-specific tuning of JDBC access.
84   * </ul>
85   * 
86   * @author Andrei Adamchik
87   */
88  public interface DbAdapter {
89  
90      /**
91       * Returns a String used to terminate a batch in command-line tools. E.g. ";" on
92       * Oracle or "go" on Sybase.
93       * 
94       * @since 1.0.4
95       */
96      public String   getBatchTerminator();
97  
98      /**
99       * Creates an returns a named instance of a DataNode.
100      * 
101      * @deprecated since 1.2 this method is not used as node behavior customization is
102      *             done via SQLActionVisitor.
103      */
104     public DataNode createDataNode(String   name);
105 
106     /**
107      * Creates and returns a QueryTranslator appropriate for the specified
108      * <code>query</code> parameter. Sets translator "query" and "adapter" property.
109      * <p>
110      * This factory method allows subclasses to specify their own translators that
111      * implement vendor-specific optimizations.
112      * </p>
113      * 
114      * @deprecated since 1.2 this method is unneeded as customizations are done via custom
115      *             SQLActions.
116      */
117     public QueryTranslator getQueryTranslator(Query query) throws Exception  ;
118 
119     // TODO: deprecate and move into SQLAction implementation
120     public QualifierTranslator getQualifierTranslator(QueryAssembler queryAssembler);
121 
122     /**
123      * Returns an instance of SQLAction that should handle the query.
124      * 
125      * @since 1.2
126      */
127     public SQLAction getAction(Query query, DataNode node);
128 
129     /**
130      * Returns true if a target database supports FK constraints.
131      */
132     public boolean supportsFkConstraints();
133 
134     /**
135      * Returns true if a target database supports UNIQUE constraints.
136      * 
137      * @since 1.1
138      */
139     public boolean supportsUniqueConstraints();
140 
141     /**
142      * Returns true if a target database supports key autogeneration. This feature also
143      * requires JDBC3-compliant driver.
144      * 
145      * @since 1.2
146      */
147     public boolean supportsGeneratedKeys();
148 
149     /**
150      * Returns <code>true</code> if the target database supports batch updates.
151      */
152     public boolean supportsBatchUpdates();
153 
154     /**
155      * Returns a SQL string that can be used to drop a database table corresponding to
156      * <code>ent</code> parameter.
157      */
158     public String   dropTable(DbEntity ent);
159 
160     /**
161      * Returns a SQL string that can be used to create database table corresponding to
162      * <code>ent</code> parameter.
163      */
164     public String   createTable(DbEntity ent);
165 
166     /**
167      * Returns a DDL string to create a unique constraint over a set of columns.
168      * 
169      * @since 1.1
170      */
171     public String   createUniqueConstraint(DbEntity source, Collection   columns);
172 
173     /**
174      * Returns a SQL string that can be used to create a foreign key constraint for the
175      * relationship.
176      */
177     public String   createFkConstraint(DbRelationship rel);
178 
179     /**
180      * Returns an array of RDBMS types that can be used with JDBC <code>type</code>.
181      * Valid JDBC types are defined in java.sql.Types.
182      */
183     public String  [] externalTypesForJdbcType(int type);
184 
185     /**
186      * Returns a map of ExtendedTypes that is used to translate values between Java and
187      * JDBC layer.
188      * 
189      * @see org.objectstyle.cayenne.access.types.ExtendedType
190      */
191     public ExtendedTypeMap getExtendedTypes();
192 
193     /**
194      * Returns primary key generator associated with this DbAdapter.
195      */
196     public PkGenerator getPkGenerator();
197 
198     /**
199      * Creates and returns a DbAttribute based on supplied parameters (usually obtained
200      * from database meta data).
201      * 
202      * @param name database column name
203      * @param typeName database specific type name, may be used as a hint to determine the
204      *            right JDBC type.
205      * @param type JDBC column type
206      * @param size database column size (ignored if less than zero)
207      * @param precision database column precision (ignored if less than zero)
208      * @param allowNulls database column nullable parameter
209      */
210     public DbAttribute buildAttribute(
211             String   name,
212             String   typeName,
213             int type,
214             int size,
215             int precision,
216             boolean allowNulls);
217 
218     /**
219      * Binds an object value to PreparedStatement's numbered parameter.
220      */
221     public void bindParameter(
222             PreparedStatement   statement,
223             Object   object,
224             int pos,
225             int sqlType,
226             int precision) throws SQLException  , Exception  ;
227 
228     /**
229      * Returns the name of the table type (as returned by
230      * <code>DatabaseMetaData.getTableTypes</code>) for a simple user table.
231      */
232     public String   tableTypeForTable();
233 
234     /**
235      * Returns the name of the table type (as returned by
236      * <code>DatabaseMetaData.getTableTypes</code>) for a view table.
237      */
238     public String   tableTypeForView();
239 
240     /**
241      * @deprecated Since 1.2 this method is obsolete and is ignored across Cayenne.
242      */
243     public boolean shouldRunBatchQuery(
244             DataNode node,
245             Connection   con,
246             BatchQuery query,
247             OperationObserver delegate) throws SQLException  , Exception  ;
248 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags