Home » Hibernate-3.3.2.GA » org.hibernate » dialect » [javadoc | source]
abstract public class: Dialect [javadoc | source]
Represents a dialect of SQL implemented by a particular RDBMS. Subclasses implement Hibernate compatibility with different systems.

Subclasses should provide a public default constructor that register() a set of type mappings and default Hibernate properties.

Subclasses should be immutable.
Field Summary
public static final  String DEFAULT_BATCH_SIZE     
public static final  String NO_BATCH     
public static final  String QUOTE    Characters used for quoting SQL identifiers 
public static final  String CLOSED_QUOTE     
 protected Dialect() 
Method from org.hibernate.dialect.Dialect Summary:
appendIdentitySelectToInsert,   appendLockHint,   applyLocksToSql,   areStringComparisonsCaseInsensitive,   bindLimitParametersFirst,   bindLimitParametersInReverseOrder,   buildSQLExceptionConverter,   closeQuote,   convertToFirstRowValue,   createCaseFragment,   createOuterJoinFragment,   doesReadCommittedCauseWritersToBlockReaders,   doesRepeatableReadCauseReadersToBlockWriters,   dropConstraints,   dropTemporaryTableAfterUse,   forUpdateOfColumns,   forceLimitUsage,   generateTemporaryTableName,   getAddColumnString,   getAddForeignKeyConstraintString,   getAddPrimaryKeyConstraintString,   getCascadeConstraintsString,   getCastTypeName,   getColumnComment,   getCreateMultisetTableString,   getCreateSequenceString,   getCreateSequenceString,   getCreateSequenceStrings,   getCreateSequenceStrings,   getCreateTableString,   getCreateTemporaryTablePostfix,   getCreateTemporaryTableString,   getCurrentTimestampSQLFunctionName,   getCurrentTimestampSelectString,   getDefaultProperties,   getDialect,   getDialect,   getDropForeignKeyString,   getDropSequenceString,   getDropSequenceStrings,   getForUpdateNowaitString,   getForUpdateNowaitString,   getForUpdateString,   getForUpdateString,   getForUpdateString,   getFunctions,   getHibernateTypeName,   getHibernateTypeName,   getIdentityColumnString,   getIdentityColumnString,   getIdentityInsertString,   getIdentitySelectString,   getIdentitySelectString,   getKeywords,   getLimitString,   getLimitString,   getLockingStrategy,   getLowercaseFunction,   getMaxAliasLength,   getNativeIdentifierGeneratorClass,   getNoColumnsInsertString,   getNullColumnString,   getQuerySequencesString,   getResultSet,   getSelectClauseNullString,   getSelectGUIDString,   getSelectSequenceNextValString,   getSequenceNextValString,   getTableComment,   getTableTypeString,   getTypeName,   getTypeName,   getViolatedConstraintNameExtracter,   hasAlterTable,   hasDataTypeInIdentityColumn,   hasSelfReferentialForeignKeyBug,   isCurrentTimestampSelectStringCallable,   openQuote,   performTemporaryTableDDLInIsolation,   qualifyIndexName,   quote,   registerColumnType,   registerColumnType,   registerFunction,   registerHibernateType,   registerHibernateType,   registerKeyword,   registerResultSetOutParameter,   requiresCastingOfParametersInSelectClause,   supportsBindAsCallableArgument,   supportsCascadeDelete,   supportsCircularCascadeDeleteConstraints,   supportsColumnCheck,   supportsCommentOn,   supportsCurrentTimestampSelection,   supportsEmptyInList,   supportsExistsInSelect,   supportsExpectedLobUsagePattern,   supportsIdentityColumns,   supportsIfExistsAfterTableName,   supportsIfExistsBeforeTableName,   supportsInsertSelectIdentity,   supportsLimit,   supportsLimitOffset,   supportsLobValueChangePropogation,   supportsNotNullUnique,   supportsOuterJoinForUpdate,   supportsParametersInInsertSelect,   supportsPooledSequences,   supportsResultSetPositionQueryMethodsOnForwardOnlyCursor,   supportsRowValueConstructorSyntax,   supportsRowValueConstructorSyntaxInInList,   supportsSequences,   supportsSubqueryOnMutatingTable,   supportsSubselectAsInPredicateLHS,   supportsTableCheck,   supportsTemporaryTables,   supportsUnboundedLobLocatorMaterialization,   supportsUnionAll,   supportsUnique,   supportsUniqueConstraintInCreateAlterTable,   supportsVariableLimit,   toBooleanValueString,   toString,   transformSelectString,   useInputStreamToInsertBlob,   useMaxForLimit
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.hibernate.dialect.Dialect Detail:
 public String appendIdentitySelectToInsert(String insertString) 
 public String appendLockHint(LockMode mode,
    String tableName) 
    Some dialects support an alternative means to SELECT FOR UPDATE, whereby a "lock hint" is appends to the table name in the from clause.

    contributed by Helge Schulz

 public String applyLocksToSql(String sql,
    Map aliasedLockModes,
    Map keyColumnNames) 
    Modifies the given SQL by applying the appropriate updates for the specified lock modes and key columns.

    The behavior here is that of an ANSI SQL SELECT FOR UPDATE. This method is really intended to allow dialects which do not support SELECT FOR UPDATE to achieve this in their own fashion.

 public boolean areStringComparisonsCaseInsensitive() 
    Are string comparisons implicitly case insensitive.

    In other words, does [where 'XYZ' = 'xyz'] resolve to true?

 public boolean bindLimitParametersFirst() 
    Does the LIMIT clause come at the start of the SELECT statement, rather than at the end?
 public boolean bindLimitParametersInReverseOrder() 
    ANSI SQL defines the LIMIT clause to be in the form LIMIT offset, limit. Does this dialect require us to bind the parameters in reverse order?
 public SQLExceptionConverter buildSQLExceptionConverter() 
    Build an instance of the SQLExceptionConverter preferred by this dialect for converting SQLExceptions into Hibernate's JDBCException hierarchy. The default Dialect implementation simply returns a converter based on X/Open SQLState codes.

    It is strongly recommended that specific Dialect implementations override this method, since interpretation of a SQL error is much more accurate when based on the ErrorCode rather than the SQLState. Unfortunately, the ErrorCode is a vendor- specific approach.

 public char closeQuote() 
    The character specific to this dialect used to close a quoted identifier.
 public int convertToFirstRowValue(int zeroBasedFirstResult) 
    Hibernate APIs explcitly state that setFirstResult() should be a zero-based offset. Here we allow the Dialect a chance to convert that value based on what the underlying db or driver will expect.

    NOTE: what gets passed into #getLimitString(String,int,int) is the zero-based offset. Dialects which do not #supportsVariableLimit should take care to perform any needed #convertToFirstRowValue calls prior to injecting the limit values into the SQL string.

 public CaseFragment createCaseFragment() 
 public JoinFragment createOuterJoinFragment() 
 public boolean doesReadCommittedCauseWritersToBlockReaders() 
    For the underlying database, is READ_COMMITTED isolation implemented by forcing readers to wait for write locks to be released?
 public boolean doesRepeatableReadCauseReadersToBlockWriters() 
    For the underlying database, is REPEATABLE_READ isolation implemented by forcing writers to wait for read locks to be released?
 public boolean dropConstraints() 
    Do we need to drop constraints before dropping tables in this dialect?
 public boolean dropTemporaryTableAfterUse() 
    Do we need to drop the temporary table after use?
 public boolean forUpdateOfColumns() 
    Is FOR UPDATE OF syntax supported?
 public boolean forceLimitUsage() 
    Generally, if there is no limit applied to a Hibernate query we do not apply any limits to the SQL query. This option forces that the limit be written to the SQL query.
 public String generateTemporaryTableName(String baseTableName) 
    Generate a temporary table name given the bas table.
 public String getAddColumnString() 
    The syntax used to add a column to a table (optional).
 public String getAddForeignKeyConstraintString(String constraintName,
    String[] foreignKey,
    String referencedTable,
    String[] primaryKey,
    boolean referencesPrimaryKey) 
    The syntax used to add a foreign key constraint to a table.
 public String getAddPrimaryKeyConstraintString(String constraintName) 
    The syntax used to add a primary key constraint to a table.
 public String getCascadeConstraintsString() 
    Completely optional cascading drop clause
 public String getCastTypeName(int code) 
    Get the name of the database type appropriate for casting operations (via the CAST() SQL function) for the given java.sql.Types typecode.
 public String getColumnComment(String comment) 
 public String getCreateMultisetTableString() 
    Slight variation on #getCreateTableString . Here, we have the command used to create a table when there is no primary key and duplicate rows are expected.

    Most databases do not care about the distinction; originally added for Teradata support which does care.

 protected String getCreateSequenceString(String sequenceName) throws MappingException 
    Typically dialects which support sequences can create a sequence with a single command. This is convenience form of #getCreateSequenceStrings to help facilitate that.

    Dialects which support sequences and can create a sequence in a single command need *only* override this method. Dialects which support sequences but require multiple commands to create a sequence should instead override #getCreateSequenceStrings .

 protected String getCreateSequenceString(String sequenceName,
    int initialValue,
    int incrementSize) throws MappingException 
    Overloaded form of #getCreateSequenceString(String) , additionally taking the initial value and increment size to be applied to the sequence definition.

    The default definition is to suffix #getCreateSequenceString(String) with the string: " start with {initialValue} increment by {incrementSize}" where {initialValue} and {incrementSize} are replacement placeholders. Generally dialects should only need to override this method if different key phrases are used to apply the allocation information.
 public String[] getCreateSequenceStrings(String sequenceName) throws MappingException 
Deprecated! Use - #getCreateSequenceString(String, int, int) instead

    The multiline script used to create a sequence.
 public String[] getCreateSequenceStrings(String sequenceName,
    int initialValue,
    int incrementSize) throws MappingException 
 public String getCreateTableString() 
    Command used to create a table.
 public String getCreateTemporaryTablePostfix() 
    Get any fragments needing to be postfixed to the command for temporary table creation.
 public String getCreateTemporaryTableString() 
    Command used to create a temporary table.
 public String getCurrentTimestampSQLFunctionName() 
    The name of the database-specific SQL function for retrieving the current timestamp.
 public String getCurrentTimestampSelectString() 
    Retrieve the command used to retrieve the current timestammp from the database.
 public final Properties getDefaultProperties() 
    Retrieve a set of default Hibernate properties for this database.
 public static Dialect getDialect() throws HibernateException 
    Get an instance of the dialect specified by the current System properties.
 public static Dialect getDialect(Properties props) throws HibernateException 
    Get an instance of the dialect specified by the given properties or by the current System properties.
 public String getDropForeignKeyString() 
 protected String getDropSequenceString(String sequenceName) throws MappingException 
    Typically dialects which support sequences can drop a sequence with a single command. This is convenience form of #getDropSequenceStrings to help facilitate that.

    Dialects which support sequences and can drop a sequence in a single command need *only* override this method. Dialects which support sequences but require multiple commands to drop a sequence should instead override #getDropSequenceStrings .

 public String[] getDropSequenceStrings(String sequenceName) throws MappingException 
    The multiline script used to drop a sequence.
 public String getForUpdateNowaitString() 
    Retrieves the FOR UPDATE NOWAIT syntax specific to this dialect.
 public String getForUpdateNowaitString(String aliases) 
    Get the FOR UPDATE OF column_list NOWAIT fragment appropriate for this dialect given the aliases of the columns to be write locked.
 public String getForUpdateString() 
    Get the string to append to SELECT statements to acquire locks for this dialect.
 public String getForUpdateString(LockMode lockMode) 
    Given a lock mode, determine the appropriate for update fragment to use.
 public String getForUpdateString(String aliases) 
    Get the FOR UPDATE OF column_list fragment appropriate for this dialect given the aliases of the columns to be write locked.
 public final Map getFunctions() 
 public String getHibernateTypeName(int code) throws HibernateException 
 public String getHibernateTypeName(int code,
    int length,
    int precision,
    int scale) throws HibernateException 
 protected String getIdentityColumnString() throws MappingException 
    The syntax used during DDL to define a column as being an IDENTITY.
 public String getIdentityColumnString(int type) throws MappingException 
    The syntax used during DDL to define a column as being an IDENTITY of a particular type.
 public String getIdentityInsertString() 
    The keyword used to insert a generated value into an identity column (or null). Need if the dialect does not support inserts that specify no column values.
 protected String getIdentitySelectString() throws MappingException 
    Get the select command to use to retrieve the last generated IDENTITY value.
 public String getIdentitySelectString(String table,
    String column,
    int type) throws MappingException 
    Get the select command to use to retrieve the last generated IDENTITY value for a particuar table
 public Set getKeywords() 
 protected String getLimitString(String query,
    boolean hasOffset) 
    Apply s limit clause to the query.

    Typically dialects utilize variable limit caluses when they support limits. Thus, when building the select command we do not actually need to know the limit or the offest since we will just be using placeholders.

    Here we do still pass along whether or not an offset was specified so that dialects not supporting offsets can generate proper exceptions. In general, dialects will override one or the other of this method and #getLimitString(String, int, int) .

 public String getLimitString(String query,
    int offset,
    int limit) 
    Given a limit and an offset, apply the limit clause to the query.
 public LockingStrategy getLockingStrategy(Lockable lockable,
    LockMode lockMode) 
    Get a strategy instance which knows how to acquire a database-level lock of the specified mode for this dialect.
 public String getLowercaseFunction() 
    The name of the SQL function that transforms a string to lowercase
 public int getMaxAliasLength() 
    What is the maximum length Hibernate can use for generated aliases?
 public Class getNativeIdentifierGeneratorClass() 
    The class (which implements org.hibernate.id.IdentifierGenerator ) which acts as this dialects native generation strategy.

    Comes into play whenever the user specifies the native generator.

 public String getNoColumnsInsertString() 
    The fragment used to insert a row without specifying any column values. This is not possible on some databases.
 public String getNullColumnString() 
    The keyword used to specify a nullable column.
 public String getQuerySequencesString() 
    Get the select command used retrieve the names of all sequences.
 public ResultSet getResultSet(CallableStatement statement) throws SQLException 
 public String getSelectClauseNullString(int sqlType) 
    Given a java.sql.Types type code, determine an appropriate null value to use in a select clause.

    One thing to consider here is that certain databases might require proper casting for the nulls here since the select here will be part of a UNION/UNION ALL.

 public String getSelectGUIDString() 
    Get the command used to select a GUID from the underlying database.

    Optional operation.

 public String getSelectSequenceNextValString(String sequenceName) throws MappingException 
    Generate the select expression fragment that will retreive the next value of a sequence as part of another (typically DML) statement.

    This differs from #getSequenceNextValString(String) in that this should return an expression usable within another statement.

 public String getSequenceNextValString(String sequenceName) throws MappingException 
    Generate the appropriate select statement to to retreive the next value of a sequence.

    This should be a "stand alone" select statement.

 public String getTableComment(String comment) 
 public String getTableTypeString() 
 public String getTypeName(int code) throws HibernateException 
    Get the name of the database type associated with the given java.sql.Types typecode.
 public String getTypeName(int code,
    int length,
    int precision,
    int scale) throws HibernateException 
    Get the name of the database type associated with the given java.sql.Types typecode with the given storage specification parameters.
 public ViolatedConstraintNameExtracter getViolatedConstraintNameExtracter() 
 public boolean hasAlterTable() 
    Does this dialect support the ALTER TABLE syntax?
 public boolean hasDataTypeInIdentityColumn() 
    Whether this dialect have an Identity clause added to the data type or a completely seperate identity data type
 public boolean hasSelfReferentialForeignKeyBug() 
 public boolean isCurrentTimestampSelectStringCallable() 
 public char openQuote() 
    The character specific to this dialect used to begin a quoted identifier.
 public Boolean performTemporaryTableDDLInIsolation() 
    Does the dialect require that temporary table DDL statements occur in isolation from other statements? This would be the case if the creation would cause any current transaction to get committed implicitly.

    JDBC defines a standard way to query for this information via the java.sql.DatabaseMetaData#dataDefinitionCausesTransactionCommit() method. However, that does not distinguish between temporary table DDL and other forms of DDL; MySQL, for example, reports DDL causing a transaction commit via its driver, even though that is not the case for temporary table DDL.

    Possible return values and their meanings:

 public boolean qualifyIndexName() 
    Do we need to qualify index names with the schema name?
 public final String quote(String column) 
    Apply dialect-specific quoting.

    By default, the incoming value is checked to see if its first character is the back-tick (`). If so, the dialect specific quoting is applied.

 protected  void registerColumnType(int code,
    String name) 
    Subclasses register a type name for the given type code. $l in the type name with be replaced by the column length (if appropriate).
 protected  void registerColumnType(int code,
    int capacity,
    String name) 
    Subclasses register a type name for the given type code and maximum column length. $l in the type name with be replaced by the column length (if appropriate).
 protected  void registerFunction(String name,
    SQLFunction function) 
 protected  void registerHibernateType(int code,
    String name) 
 protected  void registerHibernateType(int code,
    int capacity,
    String name) 
 protected  void registerKeyword(String word) 
 public int registerResultSetOutParameter(CallableStatement statement,
    int position) throws SQLException 
    Registers an OUT parameter which will be returing a java.sql.ResultSet . How this is accomplished varies greatly from DB to DB, hence its inclusion (along with #getResultSet ) here.
 public boolean requiresCastingOfParametersInSelectClause() 
    Does this dialect require that parameters appearing in the SELECT clause be wrapped in cast() calls to tell the db parser the expected type.
 public boolean supportsBindAsCallableArgument() 
    Does this dialect support using a JDBC bind parameter as an argument to a function or procedure call?
 public boolean supportsCascadeDelete() 
 public boolean supportsCircularCascadeDeleteConstraints() 
    Does this dialect support definition of cascade delete constraints which can cause circular chains?
 public boolean supportsColumnCheck() 
    Does this dialect support column-level check constraints?
 public boolean supportsCommentOn() 
 public boolean supportsCurrentTimestampSelection() 
    Does this dialect support a way to retrieve the database's current timestamp value?
 public boolean supportsEmptyInList() 
    Does this dialect support empty IN lists?

    For example, is [where XYZ in ()] a supported construct?

 public boolean supportsExistsInSelect() 
    Does the dialect support an exists statement in the select clause?
 public boolean supportsExpectedLobUsagePattern() 
    Expected LOB usage pattern is such that I can perform an insert via prepared statement with a parameter binding for a LOB value without crazy casting to JDBC driver implementation-specific classes...

    Part of the trickiness here is the fact that this is largely driver dependent. For example, Oracle (which is notoriously bad with LOB support in their drivers historically) actually does a pretty good job with LOB support as of the 10.2.x versions of their drivers...

 public boolean supportsIdentityColumns() 
    Does this dialect support identity column key generation?
 public boolean supportsIfExistsAfterTableName() 
 public boolean supportsIfExistsBeforeTableName() 
 public boolean supportsInsertSelectIdentity() 
    Does the dialect support some form of inserting and selecting the generated IDENTITY value all in the same statement.
 public boolean supportsLimit() 
    Does this dialect support some form of limiting query results via a SQL clause?
 public boolean supportsLimitOffset() 
    Does this dialect's LIMIT support (if any) additionally support specifying an offset?
 public boolean supportsLobValueChangePropogation() 
 public boolean supportsNotNullUnique() 
 public boolean supportsOuterJoinForUpdate() 
    Does this dialect support FOR UPDATE in conjunction with outer joined rows?
 public boolean supportsParametersInInsertSelect() 
    Does this dialect support parameters within the SELECT clause of INSERT ... SELECT ... statements?
 public boolean supportsPooledSequences() 
    Does this dialect support "pooled" sequences. Not aware of a better name for this. Essentially can we specify the initial and increment values?
 public boolean supportsResultSetPositionQueryMethodsOnForwardOnlyCursor() 
    Does this dialect support asking the result set its positioning information on forward only cursors. Specifically, in the case of scrolling fetches, Hibernate needs to use java.sql.ResultSet#isAfterLast and java.sql.ResultSet#isBeforeFirst . Certain drivers do not allow access to these methods for forward only cursors.

    NOTE : this is highly driver dependent!

 public boolean supportsRowValueConstructorSyntax() 
    Is this dialect known to support what ANSI-SQL terms "row value constructor" syntax; sometimes called tuple syntax.

    Basically, does it support syntax like "... where (FIRST_NAME, LAST_NAME) = ('Steve', 'Ebersole') ...".

 public boolean supportsRowValueConstructorSyntaxInInList() 
    If the dialect supports row values , does it offer such support in IN lists as well?

    For example, "... where (FIRST_NAME, LAST_NAME) IN ( (?, ?), (?, ?) ) ..."

 public boolean supportsSequences() 
    Does this dialect support sequences?
 public boolean supportsSubqueryOnMutatingTable() 
    Does this dialect support referencing the table being mutated in a subquery. The "table being mutated" is the table referenced in an UPDATE or a DELETE query. And so can that table then be referenced in a subquery of said UPDATE/DELETE query.

    For example, would the following two syntaxes be supported:

    • delete from TABLE_A where ID not in ( select ID from TABLE_A )
    • update TABLE_A set NON_ID = 'something' where ID in ( select ID from TABLE_A)
 public boolean supportsSubselectAsInPredicateLHS() 
    Are subselects supported as the left-hand-side (LHS) of IN-predicates.

    In other words, is syntax like "... IN (1, 2, 3) ..." supported?

 public boolean supportsTableCheck() 
    Does this dialect support table-level check constraints?
 public boolean supportsTemporaryTables() 
    Does this dialect support temporary tables?
 public boolean supportsUnboundedLobLocatorMaterialization() 
    Is it supported to materialize a LOB locator outside the transaction in which it was created?

    Again, part of the trickiness here is the fact that this is largely driver dependent.

    NOTE: all database I have tested which #supportsExpectedLobUsagePattern() also support the ability to materialize a LOB outside the owning transaction...

 public boolean supportsUnionAll() 
    Does this dialect support UNION ALL, which is generally a faster variant of UNION?
 public boolean supportsUnique() 
    Does this dialect support the UNIQUE column syntax?
 public boolean supportsUniqueConstraintInCreateAlterTable() 
    Does this dialect support adding Unique constraints via create and alter table ?
 public boolean supportsVariableLimit() 
    Does this dialect support bind variables (i.e., prepared statememnt parameters) for its limit/offset?
 public String toBooleanValueString(boolean bool) 
    The SQL literal value to which this database maps boolean values.
 public String toString() 
 public String transformSelectString(String select) 
 public boolean useInputStreamToInsertBlob() 
 public boolean useMaxForLimit() 
    Does the LIMIT clause take a "maximum" row number instead of a total number of returned rows?

    This is easiest understood via an example. Consider you have a table with 20 rows, but you only want to retrieve rows number 11 through 20. Generally, a limit with offset would say that the offset = 11 and the limit = 10 (we only want 10 rows at a time); this is specifying the total number of returned rows. Some dialects require that we instead specify offset = 11 and limit = 20, where 20 is the "last" row we want relative to offset (i.e. total number of rows = 20 - 11 = 9)

    So essentially, is limit relative from offset? Or is limit absolute?