- * Subclasses should be threadsafe and immutable. + * Subclasses should be thread-safe and immutable. *
* Since Hibernate 6, a single subclass of {@code Dialect} represents all
* releases of a given product-specific SQL dialect. The version of the
@@ -1567,7 +1568,8 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The legacy behavior of Hibernate. LOBs are not processed by merge.
+ * A {@link LobMergeStrategy} representing the legacy behavior of Hibernate.
+ * LOBs are not processed by merge.
*/
@SuppressWarnings("unused")
protected static final LobMergeStrategy LEGACY_LOB_MERGE_STRATEGY = new LobMergeStrategy() {
@@ -1588,7 +1590,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
};
/**
- * Merge strategy based on transferring contents based on streams.
+ * A {@link LobMergeStrategy} based on transferring contents using streams.
*/
@SuppressWarnings("unused")
protected static final LobMergeStrategy STREAM_XFER_LOB_MERGE_STRATEGY = new LobMergeStrategy() {
@@ -1655,7 +1657,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
};
/**
- * Merge strategy based on creating a new LOB locator.
+ * A {@link LobMergeStrategy} based on creating a new LOB locator.
*/
protected static final LobMergeStrategy NEW_LOCATOR_LOB_MERGE_STRATEGY = new LobMergeStrategy() {
@Override
@@ -1712,6 +1714,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
};
+ /**
+ * Get the {@link LobMergeStrategy} to use, {@link #NEW_LOCATOR_LOB_MERGE_STRATEGY}
+ * by default.
+ */
public LobMergeStrategy getLobMergeStrategy() {
return NEW_LOCATOR_LOB_MERGE_STRATEGY;
}
@@ -1863,8 +1869,13 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* should return false.
*
* @return True if the lock timeout is rendered into the {@code SQL}
- * string as a parameter; false otherwise.
+ * string as a parameter; false otherwise.
+ *
+ * @deprecated This is never called, and since at least Hibernate 5 has
+ * just returned {@code false} in every dialect. It will be
+ * removed.
*/
+ @Deprecated(since = "6", forRemoval = true)
public boolean isLockTimeoutParameterized() {
return false;
}
@@ -2090,7 +2101,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* @return The appropriate {@code FOR UPDATE NOWAIT} clause string.
*/
public String getForUpdateNowaitString() {
- // by default we report no support for NOWAIT lock semantics
+ // by default, we report no support for NOWAIT lock semantics
return getForUpdateString();
}
@@ -2100,7 +2111,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* @return The appropriate {@code FOR UPDATE SKIP LOCKED} clause string.
*/
public String getForUpdateSkipLockedString() {
- // by default we report no support for SKIP_LOCKED lock semantics
+ // by default, we report no support for SKIP_LOCKED lock semantics
return getForUpdateString();
}
@@ -2169,6 +2180,67 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return "create table";
}
+ /**
+ * An arbitrary fragment appended to the end of the {@code create table}
+ * statement.
+ *
+ * @apiNote An example is the MySQL {@code engine} option specifying a
+ * storage engine.
+ */
+ public String getTableTypeString() {
+ return "";
+ }
+
+ /**
+ * For dropping a table, can the phrase {@code if exists} be
+ * applied before the table name?
+ *
+ * @apiNote Only one or the other (or neither) of this and
+ * {@link #supportsIfExistsAfterTableName} should
+ * return true.
+ *
+ * @return {@code true} if {@code if exists} can be applied
+ * before the table name
+ */
+ public boolean supportsIfExistsBeforeTableName() {
+ return false;
+ }
+
+ /**
+ * For dropping a table, can the phrase {@code if exists} be
+ * applied after the table name?
+ *
+ * @apiNote Only one or the other (or neither) of this and
+ * {@link #supportsIfExistsBeforeTableName} should
+ * return true.
+ *
+ * @return {@code true} if {@code if exists} can be applied
+ * after the table name
+ */
+ public boolean supportsIfExistsAfterTableName() {
+ return false;
+ }
+
+ /**
+ * The command used to drop a table with the given name, usually
+ * {@code drop table tab_name}.
+ *
+ * @param tableName The name of the table to drop
+ *
+ * @return The {@code drop table} statement as a string
+ */
+ public String getDropTableString(String tableName) {
+ final StringBuilder buf = new StringBuilder( "drop table " );
+ if ( supportsIfExistsBeforeTableName() ) {
+ buf.append( "if exists " );
+ }
+ buf.append( tableName ).append( getCascadeConstraintsString() );
+ if ( supportsIfExistsAfterTableName() ) {
+ buf.append( " if exists" );
+ }
+ return buf.toString();
+ }
+
/**
* The command used to create an index, usually {@code create index}
* or {@code create unique index}.
@@ -2189,6 +2261,38 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return "";
}
+ /**
+ * Do we need to qualify index names with the schema name?
+ *
+ * @return {@code true} if we do
+ */
+ public boolean qualifyIndexName() {
+ return true;
+ }
+
+ /**
+ * Slight variation on {@link #getCreateTableString}. Here, we have
+ * the command used to create a table when there is no primary key
+ * and duplicate rows are expected.
+ *
+ * @apiNote Most databases do not have this distinction; this method
+ * was originally added for Teradata which does.
+ *
+ * @return The command used to create a multiset table.
+ */
+ public String getCreateMultisetTableString() {
+ return getCreateTableString();
+ }
+
+ /**
+ * Does this dialect support the {@code ALTER TABLE} syntax?
+ *
+ * @return True if we support altering existing tables; false otherwise.
+ */
+ public boolean hasAlterTable() {
+ return true;
+ }
+
/**
* The command used to alter a table with the given name, usually
* {@code alter table tab_name} or
@@ -2210,6 +2314,102 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return sb.toString();
}
+ /**
+ * For an {@code alter table}, can the phrase {@code if exists} be
+ * applied?
+ *
+ * @return {@code true} if {@code if exists} can be applied after
+ * {@code alter table}
+ *
+ * @since 5.2.11
+ */
+ public boolean supportsIfExistsAfterAlterTable() {
+ return false;
+ }
+
+ /**
+ * The subcommand of the {@code alter table} command used to add
+ * a column to a table, usually {@code add column} or {@code add}.
+ *
+ * @return The {@code add column} fragment.
+ */
+ public String getAddColumnString() {
+ return "add column";
+ }
+
+ /**
+ * The syntax for the suffix used to add a column to a table.
+ *
+ * @return The suffix of the {@code add column} fragment.
+ */
+ public String getAddColumnSuffixString() {
+ return "";
+ }
+
+ /**
+ * Do we need to drop constraints before dropping tables in this dialect?
+ *
+ * @return True if constraints must be dropped prior to dropping the table;
+ * false otherwise.
+ */
+ public boolean dropConstraints() {
+ return true;
+ }
+
+ /**
+ * The subcommand of the {@code alter table} command used to drop
+ * a foreign key constraint, usually {@code drop constraint}.
+ */
+ public String getDropForeignKeyString() {
+ return "drop constraint";
+ }
+
+ /**
+ * The subcommand of the {@code alter table} command used to drop
+ * a unique key constraint.
+ */
+ public String getDropUniqueKeyString() {
+ return "drop constraint";
+ }
+
+ /**
+ * For dropping a constraint with an {@code alter table} statement,
+ * can the phrase {@code if exists} be applied before the constraint
+ * name?
+ *
+ * @apiNote Only one or the other (or neither) of this and
+ * {@link #supportsIfExistsAfterConstraintName} should
+ * return true
+ *
+ * @return {@code true} if {@code if exists} can be applied before
+ * the constraint name
+ */
+ public boolean supportsIfExistsBeforeConstraintName() {
+ return false;
+ }
+
+ /**
+ * For dropping a constraint with an {@code alter table}, can the
+ * phrase {@code if exists} be applied after the constraint name?
+ *
+ * @apiNote Only one or the other (or neither) of this and
+ * {@link #supportsIfExistsBeforeConstraintName} should
+ * return true.
+ *
+ * @return {@code true} if {@code if exists} can be applied after
+ * the constraint name
+ */
+ public boolean supportsIfExistsAfterConstraintName() {
+ return false;
+ }
+
+ /**
+ * Does this dialect support modifying the type of an existing column?
+ */
+ public boolean supportsAlterColumnType() {
+ return false;
+ }
+
/**
* The fragment of an {@code alter table} command which modifies a
* column type, or null if column types cannot be modified.
@@ -2224,24 +2424,77 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return null;
}
- public boolean supportsAlterColumnType() {
- return false;
+ /**
+ * The syntax used to add a foreign key constraint to a table,
+ * with the referenced key columns explicitly specified.
+ *
+ * @param constraintName The foreign key constraint name
+ * @param foreignKey The names of the columns comprising the
+ * foreign key
+ * @param referencedTable The table referenced by the foreign key
+ * @param primaryKey The explicit columns in the referencedTable
+ * referenced by this foreign key.
+ * @param referencesPrimaryKey if false, constraint should be
+ * explicit about which column names
+ * the constraint refers to
+ *
+ * @return the "add FK" fragment
+ */
+ public String getAddForeignKeyConstraintString(
+ String constraintName,
+ String[] foreignKey,
+ String referencedTable,
+ String[] primaryKey,
+ boolean referencesPrimaryKey) {
+ final StringBuilder res = new StringBuilder( 30 );
+
+ res.append( " add constraint " )
+ .append( quote( constraintName ) )
+ .append( " foreign key (" )
+ .append( String.join( ", ", foreignKey ) )
+ .append( ") references " )
+ .append( referencedTable );
+
+ if ( !referencesPrimaryKey ) {
+ res.append( " (" )
+ .append( String.join( ", ", primaryKey ) )
+ .append( ')' );
+ }
+
+ return res.toString();
}
/**
- * Slight variation on {@link #getCreateTableString}. Here, we have
- * the command used to create a table when there is no primary key
- * and duplicate rows are expected.
+ * The syntax used to add a foreign key constraint to a table,
+ * given the definition of the foreign key as a string.
*
- * @apiNote Most databases do not have this distinction; this method
- * was originally added for Teradata which does.
- *
- * @return The command used to create a multiset table.
+ * @param constraintName The foreign key constraint name
+ * @param foreignKeyDefinition The whole definition of the
+ * foreign key as a fragment
*/
- public String getCreateMultisetTableString() {
- return getCreateTableString();
+ public String getAddForeignKeyConstraintString(
+ String constraintName,
+ String foreignKeyDefinition) {
+ return " add constraint " + quote( constraintName )
+ + " " + foreignKeyDefinition;
}
+ /**
+ * The syntax used to add a primary key constraint to a table.
+ *
+ * @param constraintName The name of the PK constraint.
+ * @return The "add PK" fragment
+ */
+ public String getAddPrimaryKeyConstraintString(String constraintName) {
+ return " add constraint " + constraintName + " primary key ";
+ }
+
+ /**
+ * The {@link SqmMultiTableMutationStrategy} to use when not specified by
+ * {@link org.hibernate.query.spi.QueryEngineOptions#getCustomSqmMultiTableMutationStrategy}.
+ *
+ * @see org.hibernate.query.sqm.mutation.internal.SqmMutationStrategyHelper#resolveStrategy
+ */
public SqmMultiTableMutationStrategy getFallbackSqmMutationStrategy(
EntityMappingType entityDescriptor,
RuntimeModelCreationContext runtimeModelCreationContext) {
@@ -2256,6 +2509,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
);
}
+ /**
+ * The {@link SqmMultiTableInsertStrategy} to use when not specified by
+ * {@link org.hibernate.query.spi.QueryEngineOptions#getCustomSqmMultiTableInsertStrategy}.
+ *
+ * @see org.hibernate.query.sqm.mutation.internal.SqmMutationStrategyHelper#resolveInsertStrategy
+ */
public SqmMultiTableInsertStrategy getFallbackSqmInsertStrategy(
EntityMappingType entityDescriptor,
RuntimeModelCreationContext runtimeModelCreationContext) {
@@ -2747,7 +3006,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* The character specific to this dialect used to begin a quoted identifier.
*
- * @return The dialect's specific open quote character.
+ * @return The dialect-specific open quote character.
*/
public char openQuote() {
return '"';
@@ -2756,7 +3015,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* The character specific to this dialect used to close a quoted identifier.
*
- * @return The dialect's specific close quote character.
+ * @return The dialect-specific close quote character.
*/
public char closeQuote() {
return '"';
@@ -2805,6 +3064,20 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
// DDL support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ /**
+ * The {@link SchemaManagementTool} to use if none is explicitly specified.
+ *
+ * @apiNote Allows implementations to override how schema tooling works by default
+ *
+ * @return a {@link HibernateSchemaManagementTool} by default
+ */
+ @Incubating
+ public SchemaManagementTool getFallbackSchemaManagementTool(
+ Map
+ * Works in conjunction with {@link #getSchemaNameResolver()},
+ * unless the resulting {@link SchemaNameResolver} does not need
+ * this information. For example, a custom implementation might
+ * make use of the Java 1.7 {@link Connection#getSchema()} method.
*
* @return The current schema retrieval SQL
*/
@@ -2982,7 +3328,8 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Get the strategy for determining the schema name of a Connection
+ * Get the strategy for determining the schema name from a JDBC
+ * {@link Connection}, usually {@link DefaultSchemaNameResolver}.
*
* @return The schema name resolver strategy
*/
@@ -2990,129 +3337,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return DefaultSchemaNameResolver.INSTANCE;
}
- /**
- * Does this dialect support the {@code ALTER TABLE} syntax?
- *
- * @return True if we support altering of tables; false otherwise.
- */
- public boolean hasAlterTable() {
- return true;
- }
-
- /**
- * Do we need to drop constraints before dropping tables in this dialect?
- *
- * @return True if constraints must be dropped prior to dropping
- * the table; false otherwise.
- */
- public boolean dropConstraints() {
- return true;
- }
-
- /**
- * Do we need to qualify index names with the schema name?
- *
- * @return boolean
- */
- public boolean qualifyIndexName() {
- return true;
- }
-
- /**
- * The syntax used to add a column to a table (optional).
- *
- * @return The "add column" fragment.
- */
- public String getAddColumnString() {
- return "add column";
- }
-
- /**
- * The syntax for the suffix used to add a column to a table (optional).
- *
- * @return The suffix "add column" fragment.
- */
- public String getAddColumnSuffixString() {
- return "";
- }
-
- /**
- * The {@code alter table} subcommand used to drop a foreign key constraint.
- */
- public String getDropForeignKeyString() {
- return " drop constraint ";
- }
-
- /**
- * The {@code alter table} subcommand used to drop a unique key constraint.
- */
- public String getDropUniqueKeyString() {
- return " drop constraint ";
- }
-
- public String getTableTypeString() {
- // grrr... for differentiation of mysql storage engines
- return "";
- }
-
- /**
- * The syntax used to add a foreign key constraint to a table.
- *
- * @param constraintName The FK constraint name.
- * @param foreignKey The names of the columns comprising the FK
- * @param referencedTable The table referenced by the FK
- * @param primaryKey The explicit columns in the referencedTable referenced
- * by this FK.
- * @param referencesPrimaryKey if false, constraint should be
- * explicit about which column names the constraint refers to
- *
- * @return the "add FK" fragment
- */
- public String getAddForeignKeyConstraintString(
- String constraintName,
- String[] foreignKey,
- String referencedTable,
- String[] primaryKey,
- boolean referencesPrimaryKey) {
- final StringBuilder res = new StringBuilder( 30 );
-
- res.append( " add constraint " )
- .append( quote( constraintName ) )
- .append( " foreign key (" )
- .append( String.join( ", ", foreignKey ) )
- .append( ") references " )
- .append( referencedTable );
-
- if ( !referencesPrimaryKey ) {
- res.append( " (" )
- .append( String.join( ", ", primaryKey ) )
- .append( ')' );
- }
-
- return res.toString();
- }
-
- public String getAddForeignKeyConstraintString(
- String constraintName,
- String foreignKeyDefinition) {
- return " add constraint " + quote(constraintName)
- + " " + foreignKeyDefinition;
- }
-
- /**
- * The syntax used to add a primary key constraint to a table.
- *
- * @param constraintName The name of the PK constraint.
- * @return The "add PK" fragment
- */
- public String getAddPrimaryKeyConstraintString(String constraintName) {
- return " add constraint " + constraintName + " primary key ";
- }
-
/**
* Does the database/driver have bug in deleting rows that refer to
* other rows being deleted in the same query?
*
+ * @implNote The main culprit is MySQL.
+ *
* @return {@code true} if the database/driver has this bug
*/
public boolean hasSelfReferentialForeignKeyBug() {
@@ -3120,18 +3350,17 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The keyword used to specify a nullable column.
- *
- * @return String
+ * The keyword used to specify a nullable column, usually {@code ""},
+ * but sometimes {@code " null"}.
*/
public String getNullColumnString() {
return "";
}
/**
- * The keyword used to specify a nullable column.
+ * The keyword used to specify a nullable column of the given SQL type.
*
- * @return String
+ * @implNote The culprit is {@code timestamp} columns on MySQL.
*/
public String getNullColumnString(String columnType) {
return getNullColumnString();
@@ -3179,88 +3408,6 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return "";
}
- /**
- * For dropping a table, can the phrase "{@code if exists} be
- * applied before the table name?
- *
- * @apiNote Only one or the other (or neither) of this and
- * {@link #supportsIfExistsAfterTableName} should return true.
- *
- * @return {@code true} if {@code if exists} can be applied before the table name
- */
- public boolean supportsIfExistsBeforeTableName() {
- return false;
- }
-
- /**
- * For dropping a table, can the phrase {@code if exists} be
- * applied after the table name?
- *
- * @apiNote Only one or the other (or neither) of this and
- * {@link #supportsIfExistsBeforeTableName} should return true.
- *
- * @return {@code true} if {@code if exists} can be applied after the table name
- */
- public boolean supportsIfExistsAfterTableName() {
- return false;
- }
-
- /**
- * For dropping a constraint with an {@code alter table} statement,
- * can the phrase {@code if exists} be applied before the constraint
- * name?
- *
- * @apiNote Only one or the other (or neither) of this and
- * {@link #supportsIfExistsAfterConstraintName} should return true
- *
- * @return {@code true} if {@code if exists} can be applied before the constraint name
- */
- public boolean supportsIfExistsBeforeConstraintName() {
- return false;
- }
-
- /**
- * For dropping a constraint with an {@code alter table}, can the phrase
- * {@code if exists} be applied after the constraint name?
- *
- * @apiNote Only one or the other (or neither) of this and
- * {@link #supportsIfExistsBeforeConstraintName} should return true.
- *
- * @return {@code true} if {@code if exists} can be applied after the constraint name
- */
- public boolean supportsIfExistsAfterConstraintName() {
- return false;
- }
-
- /**
- * For an {@code alter table}, can the phrase "{@code if exists} be applied?
- *
- * @return {@code true} if {@code if exists} can be applied after {@code alter table}
- * @since 5.2.11
- */
- public boolean supportsIfExistsAfterAlterTable() {
- return false;
- }
-
- /**
- * Generate a {@code DROP TABLE} statement
- *
- * @param tableName The name of the table to drop
- *
- * @return The {@code DROP TABLE} statement as a string
- */
- public String getDropTableString(String tableName) {
- final StringBuilder buf = new StringBuilder( "drop table " );
- if ( supportsIfExistsBeforeTableName() ) {
- buf.append( "if exists " );
- }
- buf.append( tableName ).append( getCascadeConstraintsString() );
- if ( supportsIfExistsAfterTableName() ) {
- buf.append( " if exists" );
- }
- return buf.toString();
- }
-
/**
* Does this dialect support column-level check constraints?
*
@@ -3302,6 +3449,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return "";
}
+ /**
+ * A {@link ColumnAliasExtractor}, usually just {@link ResultSetMetaData#getColumnLabel}.
+ */
public ColumnAliasExtractor getColumnAliasExtractor() {
return ColumnAliasExtractor.COLUMN_LABEL_EXTRACTOR;
}
@@ -3313,6 +3463,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* that is, using {@link PreparedStatement#setBinaryStream}).
*
* @return True if BLOBs and CLOBs should be bound using stream operations.
+ *
* @since 3.2
*/
public boolean useInputStreamToInsertBlob() {
@@ -3320,12 +3471,17 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does this dialect support parameters within the {@code SELECT} clause of
- * {@code INSERT ... SELECT ...} statements?
+ * Does this dialect support parameters within the {@code SELECT} clause
+ * of {@code INSERT ... SELECT ...} statements?
*
* @return True if this is supported; false otherwise.
+ *
* @since 3.2
+ *
+ * @deprecated This seems to be supported on all platforms, and we don't
+ * call this except in test suite
*/
+ @Deprecated(since = "6", forRemoval = true)
public boolean supportsParametersInInsertSelect() {
return true;
}
@@ -3335,8 +3491,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* (i.e, select items) by column positions (1-origin) as defined
* by the select clause?
- * @return true if result variable references by column positions are supported;
- * false otherwise.
+ * @return true if result variable references by column positions
+ * are supported; false otherwise.
+ *
* @since 6.0.0
*/
public boolean supportsOrdinalSelectItemReference() {
@@ -3344,7 +3501,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Returns the ordering of null.
+ * Returns the default ordering of null.
*
* @since 6.0.0
*/
@@ -3352,18 +3509,30 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return NullOrdering.GREATEST;
}
+ /**
+ * Does this dialect support {@code nulls first} and {@code nulls last}?
+ */
public boolean supportsNullPrecedence() {
return true;
}
+ /**
+ * A setting specific to {@link SybaseASEDialect}.
+ *
+ * @deprecated This is only called from {@link SybaseASESqlAstTranslator}
+ * so it doesn't need to be declared here.
+ */
+ @Deprecated(since = "6")
public boolean isAnsiNullOn() {
return true;
}
/**
- * Does this dialect/database require casting of non-string arguments in a concat function?
+ * Does this dialect/database require casting of non-string arguments
+ * in the {@code concat()} function?
+ *
+ * @return {@code true} if casting using {@code cast()} is required
*
- * @return {@code true} if casting of non-string arguments in concat is required
* @since 6.2
*/
public boolean requiresCastForConcatenatingNonStrings() {
@@ -3371,10 +3540,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does this dialect require that integer divisions be wrapped in {@code cast()}
- * calls to tell the db parser the expected type.
+ * Does this dialect require that integer divisions be wrapped in
+ * {@code cast()} calls to tell the db parser the expected type.
*
- * @return True if integer divisions must be cast()ed to float
+ * @implNote The culprit is HSQLDB.
+ *
+ * @return True if integer divisions must be {@code cast()}ed to float
*/
public boolean requiresFloatCastingOfIntegerDivision() {
return false;
@@ -3382,17 +3553,19 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* 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
- * {@link ResultSet#isAfterLast} and
- * {@link ResultSet#isBeforeFirst}. Certain drivers do not
- * allow access to these methods for forward only cursors.
+ * information on forward-only cursors?
+ *
+ * Specifically, in the case of scrolling fetches, Hibernate needs
+ * to use {@link ResultSet#isAfterLast} and
+ * {@link ResultSet#isBeforeFirst}. Certain drivers do not allow
+ * access to these methods for forward-only cursors.
*
* @apiNote This is highly driver dependent!
*
* @return True if methods like {@link ResultSet#isAfterLast} and
- * {@link ResultSet#isBeforeFirst} are supported for forward
- * only cursors; false otherwise.
+ * {@link ResultSet#isBeforeFirst} are supported for forward
+ * only cursors; false otherwise.
+ *
* @since 3.2
*/
public boolean supportsResultSetPositionQueryMethodsOnForwardOnlyCursor() {
@@ -3403,8 +3576,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* Does this dialect support definition of cascade delete constraints
* which can cause circular chains?
*
- * @return True if circular cascade delete constraints are supported; false
- * otherwise.
+ * @return True if circular cascade delete constraints are supported;
+ * false otherwise.
+ *
* @since 3.2
*/
public boolean supportsCircularCascadeDeleteConstraints() {
@@ -3412,13 +3586,14 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Are subselects supported as the left-hand-side (LHS) of
- * IN-predicates.
+ * Is a subselect supported as the left-hand side (LHS) of an {@code IN}
+ * predicates?
*
- * In other words, is syntax like {@code ...
- * 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...
+ * "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.
+ *
+ * @implNote 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 v
+ * ersions of their driver.
*
* @return True if normal LOB usage patterns can be used with this driver;
- * false if driver-specific hookiness needs to be applied.
+ * false if driver-specific hookiness needs to be applied.
+ *
* @since 3.2
*/
public boolean supportsExpectedLobUsagePattern() {
@@ -3444,48 +3621,50 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does the dialect support propagating changes to LOB
- * values back to the database? Talking about mutating the
- * internal value of the locator as opposed to supplying a new
- * locator instance...
- *
- * For BLOBs, the internal value might be changed by:
- * {@link Blob#setBinaryStream},
- * {@link Blob#setBytes(long, byte[])},
- * {@link Blob#setBytes(long, byte[], int, int)},
- * or {@link Blob#truncate(long)}.
- *
- * For CLOBs, the internal value might be changed by:
- * {@link Clob#setAsciiStream(long)},
- * {@link Clob#setCharacterStream(long)},
- * {@link Clob#setString(long, String)},
- * {@link Clob#setString(long, String, int, int)},
- * or {@link Clob#truncate(long)}.
+ * Does the dialect support propagating changes to LOB values back
+ * to the database? Talking about mutating the internal value of
+ * the locator, as opposed to supplying a new locator instance.
+ *
- * Again, part of the trickiness here is the fact that this is largely
- * driver dependent.
*
- * @implNote All database I have tested which {@link #supportsExpectedLobUsagePattern()}
- * also support the ability to materialize a LOB outside the owning transaction.
+ * @implNote Again, part of the trickiness here is the fact that this is
+ * largely driver-dependent. All database I have tested which
+ * {@link #supportsExpectedLobUsagePattern()} also support the
+ * ability to materialize a LOB outside the owning transaction.
*
* @return True if unbounded materialization is supported; false otherwise.
+ *
* @since 3.2
*/
public boolean supportsUnboundedLobLocatorMaterialization() {
@@ -3498,9 +3677,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* update or delete query. And so can that table then be referenced
* in a subquery of the update or delete query?
*
- * For example, would the following two syntaxes be supported:
+ * The entire query is provided, allowing full control over the placement
+ * and syntax of the hint.
*
* By default, ignore the hint and simply return the query.
*
* @param query The query to which to apply the hint.
- * @param hintList The hints to apply
+ * @param hintList The hints to apply
* @return The modified SQL
*/
public String getQueryHintString(String query, List
+ * The entire query is provided, allowing full control over the placement
+ * and syntax of the hint.
*
* By default, ignore the hint and simply return the query.
*
* @param query The query to which to apply the hint.
- * @param hints The hints to apply
+ * @param hints The hints to apply
* @return The modified SQL
*/
public String getQueryHintString(String query, String hints) {
@@ -3682,8 +3868,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Certain dialects support a subset of {@link ScrollMode}s.
- * Provide a default to be used by Criteria and Query.
+ * A default {@link ScrollMode} to be used by {@link Query#scroll()}.
+ *
+ * @apiNote Certain dialects support a subset of {@link ScrollMode}s.
*
* @return the default {@link ScrollMode} to use.
*/
@@ -3693,8 +3880,11 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Does this dialect support {@code offset} in subqueries?
+ *
* For example:
- * {@code select * from Table1 where col1 in (select col1 from Table2 order by col2 limit 1 offset 1)}
+ *
* For example:
- * {@code select * from Table1 where col1 in (select col1 from Table2 order by col2 limit 1)}
+ *
* For example:
- * {@code select col1, (select col2 from Table2 where ...) from Table1}
+ *
+ * By default, decide based on {@link DatabaseMetaData}.
*
- * @return The NameQualifierSupport.
+ * @return The {@link NameQualifierSupport}, or null to use {@link DatabaseMetaData}.
*/
public NameQualifierSupport getNameQualifierSupport() {
return null;
@@ -3843,6 +4047,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return paddedSize;
};
+ /**
+ * The strategy to use for determining batch sizes in batch loading.
+ */
public BatchLoadSizingStrategy getDefaultBatchLoadSizingStrategy() {
return STANDARD_DEFAULT_BATCH_LOAD_SIZING_STRATEGY;
}
@@ -3865,7 +4072,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does the underlying database support partition by?
+ * Does is dialect support {@code partition by}?
*
* @since 5.2
*/
@@ -3874,31 +4081,29 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Override the DatabaseMetaData#supportsNamedParameters()
+ * Override {@link DatabaseMetaData#supportsNamedParameters()}.
*
- * @return boolean
- *
- * @throws SQLException Accessing the DatabaseMetaData can throw it.
- * Just rethrow and Hibernate will handle.
+ * @throws SQLException Accessing the {@link DatabaseMetaData} cause
+ * an exception. Just rethrow and Hibernate will
+ * handle it.
*/
public boolean supportsNamedParameters(DatabaseMetaData databaseMetaData) throws SQLException {
return databaseMetaData != null && databaseMetaData.supportsNamedParameters();
}
/**
- * Determines whether this database requires the use
- * of explicit nationalized character data types.
+ * Determines whether this database requires the use of explicitly
+ * nationalized character (Unicode) data types.
*
- * That is, whether the use of {@link Types#NCHAR},
- * {@link Types#NVARCHAR}, and {@link Types#NCLOB} is
- * required for nationalized character data (Unicode).
+ * That is, whether the use of {@link Types#NCHAR}, {@link Types#NVARCHAR},
+ * and {@link Types#NCLOB} is required for nationalized character data.
*/
public NationalizationSupport getNationalizationSupport() {
return NationalizationSupport.EXPLICIT;
}
/**
- * How the Dialect supports aggregate types like {@link SqlTypes#STRUCT}.
+ * How does this dialect support aggregate types like {@link SqlTypes#STRUCT}.
*
* @since 6.2
*/
@@ -3907,11 +4112,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Database has native support for SQL standard arrays which
- * can be referred to by its base type name.
- *
- * Oracle doesn't allow this, but instead has support for named
- * arrays.
+ * Does this database have native support for ANSI SQL standard arrays which
+ * are expressed in terms of the element type name: {@code integer array}.
+ *
+ * @implNote Oracle doesn't have this; we must instead use named array types.
*
* @return boolean
* @since 6.1
@@ -3921,7 +4125,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The SQL type name for the array of the given type name.
+ * The SQL type name for the array type with elements of the given type name.
+ *
+ * The ANSI-standard syntax is {@code integer array}.
*
* @since 6.1
*/
@@ -3929,6 +4135,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return supportsStandardArrays() ? elementTypeName + " array" : null;
}
+ /**
+ * Append an array literal with the given elements to the given {@link SqlAppender}.
+ */
public void appendArrayLiteral(
SqlAppender appender,
Object[] literal,
@@ -3959,13 +4168,16 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does this dialect support some kind of {@code distinct from}
- * predicate?
+ * Does this dialect support some kind of {@code distinct from} predicate?
*
- * This is, does it support syntax like
- * {@code ... where FIRST_NAME IS DISTINCT FROM LAST_NAME}?
+ * That is, does it support syntax like:
+ *
* Usually {@link SqlTypes#ARRAY} or {@link SqlTypes#VARBINARY}.
*
* @return one of the type codes defined by {@link SqlTypes}.
+ *
* @since 6.1
*/
public int getPreferredSqlTypeCodeForArray() {
@@ -3986,7 +4199,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The JDBC {@link Types type code} to use for mapping
+ * The JDBC {@linkplain Types type code} to use for mapping
* properties of Java type {@code boolean}.
*
* Usually {@link Types#BOOLEAN} or {@link Types#BIT}.
@@ -3999,7 +4212,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Does this dialect support insert, update, and delete statements
- * with Common Table Expressions?
+ * with Common Table Expressions (CTEs)?
*
* @return {@code true} if non-query statements are supported with CTE
*/
@@ -4008,9 +4221,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Does this dialect/database support recursive CTEs (Common Table Expressions)?
+ * Does this dialect/database support recursive CTEs?
*
* @return {@code true} if recursive CTEs are supported
+ *
* @since 6.2
*/
public boolean supportsRecursiveCTE() {
@@ -4031,7 +4245,8 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* Does this dialect support {@code values} lists of form
* {@code VALUES (1), (2), (3)} in insert statements?
*
- * @return {@code true} if {@code values} list are supported in insert statements
+ * @return {@code true} if {@code values} list are allowed
+ * in insert statements
*/
public boolean supportsValuesListForInsert() {
return true;
@@ -4065,16 +4280,20 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Inline String literal.
- *
- * @return escaped String
+ * @deprecated This is no longer called
*/
+ @Deprecated(since = "6", forRemoval = true)
public String inlineLiteral(String literal) {
final StringBuilder sb = new StringBuilder( literal.length() + 2 );
appendLiteral( new StringBuilderSqlAppender( sb ), literal );
return sb.toString();
}
+ /**
+ * Append a literal string to the given {@link SqlAppender}.
+ *
+ * @apiNote Needed because MySQL has nonstandard escape characters
+ */
public void appendLiteral(SqlAppender appender, String literal) {
appender.appendSql( '\'' );
for ( int i = 0; i < literal.length(); i++ ) {
@@ -4087,6 +4306,15 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
appender.appendSql( '\'' );
}
+ /**
+ * Append a binary literal to the given {@link SqlAppender}.
+ */
+ public void appendBinaryLiteral(SqlAppender appender, byte[] bytes) {
+ appender.appendSql( "X'" );
+ PrimitiveByteArrayJavaType.INSTANCE.appendString( appender, bytes );
+ appender.appendSql( '\'' );
+ }
+
/**
* Check whether the JDBC {@link Connection} supports creating LOBs via
* {@link Connection#createBlob()}, {@link Connection#createNClob()}, or
@@ -4103,10 +4331,13 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Check whether the JDBC driver allows setting LOBs via {@link PreparedStatement#setBytes(int, byte[])},
- * {@link PreparedStatement#setNString(int, String)} or {@link PreparedStatement#setString(int, String)} APIs.
+ * Check whether the JDBC driver allows setting LOBs via
+ * {@link PreparedStatement#setBytes(int, byte[])},
+ * {@link PreparedStatement#setNString(int, String)}, or
+ * {@link PreparedStatement#setString(int, String)} APIs.
*
* @return {@code true} if LOBs can be set with the materialized APIs.
+ *
* @since 6.2
*/
public boolean supportsMaterializedLobAccess() {
@@ -4115,13 +4346,19 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Whether to switch from {@code VARCHAR}-like types to {@link SqlTypes#MATERIALIZED_CLOB},
- * {@code NVARCHAR}-like types to {@link SqlTypes#MATERIALIZED_NCLOB}
- * and {@code VARBINARY}-like types to {@link SqlTypes#MATERIALIZED_BLOB} types,
- * when the requested size for a type exceeds the {@link #getMaxVarcharCapacity()}, {@link #getMaxNVarcharCapacity()}
- * and {@link #getMaxVarbinaryCapacity()} respectively.
+ * Whether to switch:
+ *
- * Note that {@link SessionFactoryOptions#getCustomHqlTranslator()}
- * has higher precedence since it comes directly from the user config
+ * Note that {@link SessionFactoryOptions#getCustomHqlTranslator()} has higher
+ * precedence since it comes directly from the user config.
*
* @see org.hibernate.query.hql.internal.StandardHqlTranslator
* @see org.hibernate.query.spi.QueryEngine#getHqlTranslator()
@@ -4174,11 +4418,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Return a {@link SqmTranslatorFactory} specific to this dialect.
- * Return {@code null} to use Hibernate's standard translator.
+ * Return a {@link SqmTranslatorFactory} specific to this dialect, or {@code null}
+ * to use the {@linkplain org.hibernate.query.sqm.sql.internal.StandardSqmTranslator
+ * standard translator}.
*
- * Note that {@link SessionFactoryOptions#getCustomSqmTranslatorFactory()}
- * has higher precedence since it comes directly from the user config
+ * Note that {@link SessionFactoryOptions#getCustomSqmTranslatorFactory()} has higher
+ * precedence since it comes directly from the user config.
*
* @see org.hibernate.query.sqm.sql.internal.StandardSqmTranslator
* @see org.hibernate.query.spi.QueryEngine#getSqmTranslatorFactory()
@@ -4188,28 +4433,37 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Return a {@link SqlAstTranslatorFactory} specific to this dialect.
- * Return {@code null} to use Hibernate's standard translator.
+ * Return a {@link SqlAstTranslatorFactory} specific to this dialect, or {@code null}
+ * to use the {@linkplain org.hibernate.sql.ast.spi.StandardSqlAstTranslatorFactory
+ * standard translator}.
*
- * @see StandardSqlAstTranslatorFactory
+ * @see org.hibernate.sql.ast.spi.StandardSqlAstTranslatorFactory
* @see JdbcEnvironment#getSqlAstTranslatorFactory()
*/
public SqlAstTranslatorFactory getSqlAstTranslatorFactory() {
return null;
}
+ /**
+ * Determine how selected items are referenced in the {@code group by} clause.
+ */
public SelectItemReferenceStrategy getGroupBySelectItemReferenceStrategy() {
return SelectItemReferenceStrategy.EXPRESSION;
}
+ /**
+ * A custom {@link SizeStrategy} for column types.
+ */
public SizeStrategy getSizeStrategy() {
return sizeStrategy;
}
/**
- * The biggest size value that can be supplied as argument to a {@link java.sql.Types#VARCHAR}-like type.
- * For longer column lengths, use some sort of {@code text}-like type for the
- * column.
+ * The biggest size value that can be supplied as argument to a
+ * {@link java.sql.Types#VARCHAR}-like type.
+ *
+ * For longer column lengths, use some sort of {@code text}-like
+ * type for the column.
*/
public int getMaxVarcharLength() {
//the longest possible length of a Java string
@@ -4217,9 +4471,11 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The biggest size value that can be supplied as argument to a {@link java.sql.Types#NVARCHAR}-like type.
- * For longer column lengths, use some sort of {@code ntext}-like type for the
- * column.
+ * The biggest size value that can be supplied as argument to a
+ * {@link java.sql.Types#NVARCHAR}-like type.
+ *
+ * For longer column lengths, use some sort of {@code ntext}-like
+ * type for the column.
*/
public int getMaxNVarcharLength() {
//for most databases it's the same as for VARCHAR
@@ -4227,9 +4483,11 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The biggest size value that can be supplied as argument to a {@link java.sql.Types#VARBINARY}-like type.
- * For longer column lengths, use some sort of {@code image}-like type for the
- * column.
+ * The biggest size value that can be supplied as argument to a
+ * {@link java.sql.Types#VARBINARY}-like type.
+ *
+ * For longer column lengths, use some sort of {@code image}-like
+ * type for the column.
*/
public int getMaxVarbinaryLength() {
//for most databases it's the same as for VARCHAR
@@ -4237,32 +4495,46 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The longest possible length of a {@link java.sql.Types#VARCHAR}-like column.
- * For longer column lengths, use some sort of {@code clob}-like type for the
+ * The longest possible length of a {@link java.sql.Types#VARCHAR}-like
* column.
+ *
+ * For longer column lengths, use some sort of {@code clob}-like type
+ * for the column.
*/
public int getMaxVarcharCapacity() {
return getMaxVarcharLength();
}
/**
- * The longest possible length of a {@link java.sql.Types#NVARCHAR}-like column.
- * For longer column lengths, use some sort of {@code nclob}-like type for the
+ * The longest possible length of a {@link java.sql.Types#NVARCHAR}-like
* column.
+ *
+ * For longer column lengths, use some sort of {@code nclob}-like type
+ * for the column.
*/
public int getMaxNVarcharCapacity() {
return getMaxNVarcharLength();
}
/**
- * The longest possible length of a {@link java.sql.Types#VARBINARY}-like column.
- * For longer column lengths, use some sort of {@code blob}-like type for the
+ * The longest possible length of a {@link java.sql.Types#VARBINARY}-like
* column.
+ *
+ * For longer column lengths, use some sort of {@code blob}-like type for
+ * the column.
*/
public int getMaxVarbinaryCapacity() {
return getMaxVarbinaryLength();
}
+ /**
+ * The default length for a LOB column, if LOB columns have a length in
+ * this dialect.
+ *
+ * @return {@value Size#DEFAULT_LOB_LENGTH} by default
+ *
+ * @see Length#LOB_DEFAULT
+ */
public long getDefaultLobLength() {
return Size.DEFAULT_LOB_LENGTH;
}
@@ -4370,20 +4642,17 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Whether a predicate like {@code a > 0} can appear in an expression context,
- * for example, in a {@code select} list item.
+ * Whether a predicate like {@code a > 0} can appear in an expression
+ * context, for example, in a {@code select} list item.
*/
protected boolean supportsPredicateAsExpression() {
// Most databases seem to allow that
return true;
}
- public void appendBinaryLiteral(SqlAppender appender, byte[] bytes) {
- appender.appendSql( "X'" );
- PrimitiveByteArrayJavaType.INSTANCE.appendString( appender, bytes );
- appender.appendSql( '\'' );
- }
-
+ /**
+ * Obtain a {@link RowLockStrategy} for the given {@link LockMode}.
+ */
public RowLockStrategy getLockRowIdentifier(LockMode lockMode) {
switch ( lockMode ) {
case PESSIMISTIC_READ:
@@ -4421,6 +4690,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return true;
}
+ /**
+ * Create a {@link MutationOperation} for an "upsert".
+ */
public MutationOperation createUpsertOperation(
EntityMutationTarget mutationTarget,
TableUpsert tableUpsert,
@@ -4755,6 +5027,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
}
+ /**
+ * Append a datetime literal representing the given {@link java.time}
+ * value to the given {@link SqlAppender}.
+ */
public void appendDateTimeLiteral(
SqlAppender appender,
TemporalAccessor temporalAccessor,
@@ -4781,6 +5057,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
}
+ /**
+ * Append a datetime literal representing the given {@link Date}
+ * value to the given {@link SqlAppender}.
+ */
public void appendDateTimeLiteral(SqlAppender appender, Date date, TemporalType precision, TimeZone jdbcTimeZone) {
switch ( precision ) {
case DATE:
@@ -4803,6 +5083,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
}
+ /**
+ * Append a datetime literal representing the given {@link Calendar}
+ * value to the given {@link SqlAppender}.
+ */
public void appendDateTimeLiteral(
SqlAppender appender,
Calendar calendar,
@@ -4829,6 +5113,10 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
}
+ /**
+ * Append a literal SQL {@code interval} representing the given Java
+ * {@link Duration}.
+ */
public void appendIntervalLiteral(SqlAppender appender, Duration literal) {
appender.appendSql( "interval '" );
appender.appendSql( literal.getSeconds() );
@@ -4837,6 +5125,13 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
appender.appendSql( "' second" );
}
+ /**
+ * Append a literal SQL {@code uuid} representing the given Java
+ * {@link UUID}.
+ *
+ * This is usually a {@code cast()} expression, but it might be
+ * a function call.
+ */
public void appendUUIDLiteral(SqlAppender appender, UUID literal) {
appender.appendSql( "cast('" );
appender.appendSql( literal.toString() );
@@ -4844,31 +5139,19 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Whether the Dialect supports timezone offset in temporal literals.
+ * Does this dialect supports timezone offsets in temporal literals.
*/
public boolean supportsTemporalLiteralOffset() {
return false;
}
/**
- * How the Dialect supports time zone types like {@link Types#TIMESTAMP_WITH_TIMEZONE}.
+ * How the dialect supports time zone types like {@link Types#TIMESTAMP_WITH_TIMEZONE}.
*/
public TimeZoneSupport getTimeZoneSupport() {
return TimeZoneSupport.NONE;
}
- /**
- * The SchemaManagementTool to use if none explicitly specified.
- *
- * Allows Dialects to override how schema tooling works by default
- */
- @Incubating
- public SchemaManagementTool getFallbackSchemaManagementTool(
- Map
* The main contracts here are {@link #executeUpdate} and {@link #executeDelete}.
+ *
+ * The methods {@link #prepare} and {@link #release} allow the strategy to perform any one time
+ * preparation and cleanup.
*
- * {@link #prepare} and {@link #release} allow the strategy to perform any one time preparation and cleanup.
- *
- * @apiNote See {@link SqmMutationStrategyHelper#resolveStrategy} for standard resolution of the strategy to use
- * for each hierarchy
+ * @apiNote See {@link SqmMutationStrategyHelper#resolveStrategy} for standard resolution of the
+ * strategy to use for each hierarchy.
*
* @author Steve Ebersole
*/
diff --git a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java
index f4b955a8de..ebe363e6ca 100644
--- a/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java
+++ b/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/AbstractSqlAstTranslator.java
@@ -6300,9 +6300,7 @@ public abstract class AbstractSqlAstTranslator getTableExporter() {
return tableExporter;
}
+ /**
+ * Get a {@link TableMigrator},
+ * usually {@link StandardTableMigrator}.
+ */
public TableMigrator getTableMigrator() {
return tableMigrator;
}
+ /**
+ * Get a schema {@link Cleaner},
+ * usually {@link StandardTableCleaner}.
+ */
public Cleaner getTableCleaner() {
return tableCleaner;
}
+ /**
+ * Get an {@link Exporter} for {@link UserDefinedType}s,
+ * usually {@link StandardUserDefinedTypeExporter}.
+ */
public Exporter
+ *
*
- * @implNote I do not know the correct answer currently for
- * databases which (1) are not part of the cruise control process
- * or (2) do not {@link #supportsExpectedLobUsagePattern}.
+ * @implNote I do not know the correct answer currently for databases
+ * which (1) are not part of the cruise control process, or
+ * (2) do not {@link #supportsExpectedLobUsagePattern}.
+ *
+ * @return True if the changes are propagated back to the database;
+ * false otherwise.
*
- * @return True if the changes are propagated back to the
- * database; false otherwise.
* @since 3.2
*/
public boolean supportsLobValueChangePropagation() {
- // todo : pretty sure this is the same as the java.sql.DatabaseMetaData.locatorsUpdateCopy method added in JDBC 4, see HHH-6046
+ // todo : pretty sure this is the same as the
+ // java.sql.DatabaseMetaData.locatorsUpdateCopy()
+ // method added in JDBC 4, see HHH-6046
return true;
}
/**
* Is it supported to materialize a LOB locator outside the transaction
* in which it was created?
- *
- *
+ *
*
* @return True if this dialect allows references the mutating table
@@ -3550,7 +3730,6 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
* params as args, {@code false} otherwise. The default is
* {@code true}.
*/
- @SuppressWarnings("UnusedDeclaration")
public boolean supportsBindAsCallableArgument() {
return true;
}
@@ -3566,7 +3745,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* If {@link #supportsTupleCounts()} is true, does this dialect require
- * the tuple to be delimited with parens?
+ * the tuple to be delimited with parentheses?
*
* @return boolean
*/
@@ -3587,7 +3766,7 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* If {@link #supportsTupleDistinctCounts()} is true, does this dialect
- * require the tuple to be delimited with parens?
+ * require the tuple to be delimited with parentheses?
*
* @return boolean
*/
@@ -3598,17 +3777,18 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Return the limit that the underlying database places on the number of
* elements in an {@code IN} predicate. If the database defines no such
- * limits, simply return zero or less-than-zero.
+ * limits, simply return zero or a number smaller than zero.
*
- * @return int The limit, or zero-or-less to indicate no limit.
+ * @return The limit, or a non-positive integer to indicate no limit.
*/
public int getInExpressionCountLimit() {
return 0;
}
/**
- * HHH-4635
- * Oracle expects all Lob values to be last in inserts and updates.
+ * Must LOB values occur last in inserts and updates?
+ *
+ * @implNote Oracle is the culprit here, see HHH-4635.
*
* @return boolean True if Lob values should be last, false if it
* does not matter.
@@ -3618,7 +3798,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Return whether the dialect considers an empty-string value as null.
+ * Return whether the dialect considers an empty string value to be null.
+ *
+ * @implNote Once again, the culprit is Oracle.
*
* @return boolean True if an empty string is treated as null, false otherwise.
*/
@@ -3653,13 +3835,15 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Apply a hint to the query. The entire query is provided, allowing
- * full control over the placement and syntax of the hint.
+ * Apply a hint to the given SQL query.
+ *
+ * select * from Table1 where col1 in (select col1 from Table2 order by col2 limit 1 offset 1)
+ *
*
* @return {@code true} if it does
*/
@@ -3704,8 +3894,11 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Does this dialect support the {@code order by} clause in subqueries?
+ *
+ * select * from Table1 where col1 in (select col1 from Table2 order by col2 limit 1)
+ *
*
* @return {@code true} if it does
*/
@@ -3715,8 +3908,11 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Does this dialect support subqueries in the {@code select} clause?
+ *
+ * select col1, (select col2 from Table2 where ...) from Table1
+ *
*
* @return {@code true} if it does
*/
@@ -3770,11 +3966,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return false;
}
/**
- * Does this dialect support the given fetch clause type.
+ * Does this dialect support the given {@code FETCH} clause type.
*
* @param type The fetch clause type
- * @return {@code true} if the underlying database supports the given fetch clause type,
- * {@code false} otherwise. The default is {@code false}.
+ * @return {@code true} if the underlying database supports the given
+ * fetch clause type, {@code false} otherwise.
+ * The default is {@code false}.
*/
public boolean supportsFetchClause(FetchClauseType type) {
return false;
@@ -3783,8 +3980,9 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
/**
* Does this dialect support window functions like {@code row_number() over (..)}?
*
- * @return {@code true} if the underlying database supports window functions,
- * {@code false} otherwise. The default is {@code false}.
+ * @return {@code true} if the underlying database supports window
+ * functions, {@code false} otherwise.
+ * The default is {@code false}.
*/
public boolean supportsWindowFunctions() {
return false;
@@ -3801,15 +3999,21 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
return false;
}
+ /**
+ * The {@link CallableStatementSupport} for this database.
+ * Does this database support returning cursors?
+ */
public CallableStatementSupport getCallableStatementSupport() {
// most databases do not support returning cursors (ref_cursor)...
return StandardCallableStatementSupport.NO_REF_CURSOR_INSTANCE;
}
/**
- * By default interpret this based on DatabaseMetaData.
+ * The {@linkplain NameQualifierSupport support for qualified identifiers}.
+ *
+ * ... where FIRST_NAME IS DISTINCT FROM LAST_NAME
+ *
+ *
+ * @return True if this SQL dialect is known to support some kind of
+ * {@code distinct from} predicate; false otherwise
*
- * @return True if this SQL dialect is known to support some kind of distinct from predicate; false otherwise
* @since 6.1
*/
public boolean supportsDistinctFromPredicate() {
@@ -3973,12 +4185,13 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * The JDBC {@link SqlTypes type code} to use for mapping
+ * The JDBC {@linkplain SqlTypes type code} to use for mapping
* properties of basic Java array or {@code Collection} types.
*
+ *
*
* @return {@code true} if materialized LOBs should be used for capacity exceeding types.
+ *
* @since 6.2
*/
public boolean useMaterializedLobWhenCapacityExceeded() {
@@ -4135,22 +4372,28 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
String sql,
QueryOptions queryOptions,
boolean commentsEnabled) {
- // Keep this here, rather than moving to Select. Some Dialects may need the hint to be appended to the very
- // end or beginning of the finalized SQL statement, so wait until everything is processed.
+ // Keep this here, rather than moving to Select.
+ // Some Dialects may need the hint to be appended to the very end or beginning
+ // of the finalized SQL statement, so wait until everything is processed.
if ( queryOptions.getDatabaseHints() != null && queryOptions.getDatabaseHints().size() > 0 ) {
sql = getQueryHintString( sql, queryOptions.getDatabaseHints() );
}
if ( commentsEnabled && queryOptions.getComment() != null ) {
sql = prependComment( sql, queryOptions.getComment() );
}
-
return sql;
}
+ /**
+ * Prepend a comment to the given SQL fragment.
+ */
protected String prependComment(String sql, String comment) {
return "/* " + escapeComment( comment ) + " */ " + sql;
}
+ /**
+ * Perform necessary character escaping on the text of the comment.
+ */
public static String escapeComment(String comment) {
if ( StringHelper.isNotEmpty( comment ) ) {
final String escaped = ESCAPE_CLOSING_COMMENT_PATTERN.matcher( comment ).replaceAll( "*\\\\/" );
@@ -4160,11 +4403,12 @@ public abstract class Dialect implements ConversionContext, TypeContributor, Fun
}
/**
- * Return an {@link HqlTranslator} specific to this dialect.
- * Return {@code null} to use Hibernate's standard translator.
+ * Return an {@link HqlTranslator} specific to this dialect, or {@code null}
+ * to use the {@linkplain org.hibernate.query.hql.internal.StandardHqlTranslator
+ * standard translator}.
*