001/*
002 * HA-JDBC: High-Availability JDBC
003 * Copyright (c) 2004-2007 Paul Ferraro
004 * 
005 * This library is free software; you can redistribute it and/or modify it 
006 * under the terms of the GNU Lesser General Public License as published by the 
007 * Free Software Foundation; either version 2.1 of the License, or (at your 
008 * option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 
013 * for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public License
016 * along with this library; if not, write to the Free Software Foundation, 
017 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018 * 
019 * Contact: ferraro@users.sourceforge.net
020 */
021package net.sf.hajdbc;
022
023import java.sql.DatabaseMetaData;
024import java.sql.SQLException;
025import java.util.Collection;
026import java.util.List;
027import java.util.regex.Pattern;
028
029/**
030 * Encapsulates database vendor specific SQL syntax.  
031 * 
032 * @author  Paul Ferraro
033 * @since   1.1
034 */
035public interface Dialect
036{
037        /**
038         * Returns a simple SQL statement used to validate whether a database is alive or not.
039         * @return a SQL statement
040         * @throws SQLException 
041         */
042        public String getSimpleSQL() throws SQLException;
043        
044        /**
045         * Returns a SQL statement used to truncate a table.
046         * @param properties table meta data
047         * @return a SQL statement
048         * @throws SQLException if there was an error fetching meta data.
049         */
050        public String getTruncateTableSQL(TableProperties properties) throws SQLException;
051        
052        /**
053         * Returns a SQL statement used to create a foreign key constraint.
054         * @param constraint foreign key constraint meta data
055         * @return a SQL statement
056         * @throws SQLException if there was an error fetching meta data.
057         */
058        public String getCreateForeignKeyConstraintSQL(ForeignKeyConstraint constraint) throws SQLException;
059
060        /**
061         * Returns a SQL statement used to drop a foreign key constraint.
062         * @param constraint foreign key constraint meta data
063         * @return a SQL statement
064         * @throws SQLException if there was an error fetching meta data.
065         */
066        public String getDropForeignKeyConstraintSQL(ForeignKeyConstraint constraint) throws SQLException;
067
068        /**
069         * Returns a SQL statement used to create a unique constraint.
070         * @param constraint unique constraint meta data
071         * @return a SQL statement
072         * @throws SQLException if there was an error fetching meta data.
073         */
074        public String getCreateUniqueConstraintSQL(UniqueConstraint constraint) throws SQLException;
075
076        /**
077         * Returns a SQL statement used to drop a unique constraint.
078         * @param constraint unique constraint meta data
079         * @return a SQL statement
080         * @throws SQLException if there was an error fetching meta data.
081         */
082        public String getDropUniqueConstraintSQL(UniqueConstraint constraint) throws SQLException;
083        
084        /**
085         * Determines whether the specified SQL is a SELECT ... FOR UPDATE statement
086         * @param sql a SQL statement
087         * @return true if this is a SELECT ... FOR UPDATE statement, false if it is not
088         * @throws SQLException if there was an error fetching meta data.
089         */
090        public boolean isSelectForUpdate(String sql) throws SQLException;
091        
092        /**
093         * Returns the data type of the specified column of the specified schema and table.
094         * This method is intended to correct JDBC driver type mapping quirks.
095         * @param properties table column meta data
096         * @return the JDBC data type of this column
097         * @throws SQLException 
098         */
099        public int getColumnType(ColumnProperties properties) throws SQLException;
100        
101        /**
102         * Parses a table name from the specified INSERT SQL statement that may contain identity columns.
103         * @param sql a SQL statement
104         * @return the name of a table, or null if this SQL statement is not an INSERT statement or this dialect does not support identity columns
105         * @throws SQLException
106         * @since 2.0
107         */
108        public String parseInsertTable(String sql) throws SQLException;
109
110        /**
111         * Parses a sequence name from the specified SQL statement.
112         * @param sql a SQL statement
113         * @return the name of a sequence, or null if this SQL statement does not reference a sequence or this dialect does not support sequences
114         * @throws SQLException
115         * @since 2.0
116         */
117        public String parseSequence(String sql) throws SQLException;
118        
119        /**
120         * Returns a collection of all sequences in this database.
121         * @param metaData database meta data
122         * @return a collection of sequence names
123         * @throws SQLException
124         * @since 2.0
125         */
126        public Collection<QualifiedName> getSequences(DatabaseMetaData metaData) throws SQLException;
127        
128        /**
129         * Returns a SQL statement for obtaining the next value the specified sequence
130         * @param sequence a sequence name
131         * @return a SQL statement
132         * @throws SQLException
133         * @since 2.0
134         */
135        public String getNextSequenceValueSQL(SequenceProperties sequence) throws SQLException;
136
137        /**
138         * Returns a SQL statement used reset the current value of a sequence.
139         * @param sequence a sequence name
140         * @param value a sequence value
141         * @return a SQL statement
142         * @throws SQLException 
143         * @since 2.0
144         */
145        public String getAlterSequenceSQL(SequenceProperties sequence, long value) throws SQLException;
146        
147        /**
148         * Returns a SQL statement used reset the current value of an identity column.
149         * @param table a sequence name
150         * @param column a sequence name
151         * @param value a sequence value
152         * @return a SQL statement
153         * @throws SQLException 
154         * @since 2.0.2
155         */
156        public String getAlterIdentityColumnSQL(TableProperties table, ColumnProperties column, long value) throws SQLException;
157        
158        /**
159         * Returns a search path of schemas 
160         * @param metaData 
161         * @return a list of schema names
162         * @throws SQLException 
163         * @since 2.0
164         */
165        public List<String> getDefaultSchemas(DatabaseMetaData metaData) throws SQLException;
166        
167        /**
168         * Returns a pattern for identifiers that do not require quoting
169         * @param metaData 
170         * @return a regular expression pattern
171         * @throws SQLException 
172         * @since 2.0.2
173         */
174        public Pattern getIdentifierPattern(DatabaseMetaData metaData) throws SQLException;
175        
176        /**
177         * Replaces non-deterministic CURRENT_DATE functions with deterministic static values.
178         * @param sql an SQL statement
179         * @param date the replacement date
180         * @return an equivalent deterministic SQL statement
181         * @throws SQLException 
182         * @since 2.0.2
183         */
184        public String evaluateCurrentDate(String sql, java.sql.Date date);
185        
186        /**
187         * Replaces non-deterministic CURRENT_TIME functions with deterministic static values.
188         * @param sql an SQL statement
189         * @param time the replacement time
190         * @return an equivalent deterministic SQL statement
191         * @throws SQLException 
192         * @since 2.0.2
193         */
194        public String evaluateCurrentTime(String sql, java.sql.Time time);
195        
196        /**
197         * Replaces non-deterministic CURRENT_TIMESTAMP functions with deterministic static values.
198         * @param sql an SQL statement
199         * @param timestamp the replacement timestamp
200         * @return an equivalent deterministic SQL statement
201         * @throws SQLException 
202         * @since 2.0.2
203         */
204        public String evaluateCurrentTimestamp(String sql, java.sql.Timestamp timestamp);
205        
206        /**
207         * Replaces non-deterministic RAND() functions with deterministic static values.
208         * @param sql an SQL statement
209         * @return an equivalent deterministic SQL statement
210         * @throws SQLException 
211         * @since 2.0.2
212         */
213        public String evaluateRand(String sql);
214}