Module org.seasar.doma.core
Package org.seasar.doma.jdbc.dialect

Interface Dialect

All Known Implementing Classes:
Db2Dialect, H212126Dialect, H214199Dialect, H2Dialect, HsqldbDialect, Mssql2008Dialect, MssqlDialect, MysqlDialect, Oracle11Dialect, OracleDialect, PostgresDialect, SqliteDialect, StandardDialect
public interface Dialect
A database dialect interface that abstracts differences between various RDBMS implementations.

This interface is a core component of Doma's database abstraction layer, allowing applications to work with different database systems without changing application code. It provides methods to handle database-specific behaviors such as SQL syntax, identifier quoting, data type mappings, pagination, sequence generation, and other vendor-specific features.

Custom dialects can be created by implementing this interface or extending existing implementations to support additional database systems or to customize behavior for specific needs.

The implementation instance must be thread safe.

See Also:

  • Method Details

    • getName

      String getName()
      Returns the name of this dialect.

      The dialect name typically identifies the database system that this dialect supports. This name can be used for logging, debugging, or to make decisions based on the specific database being used.

      Each dialect implementation should return a unique and descriptive name.

      Returns:
      the name of this dialect

    • transformSelectSqlNode

      SqlNode transformSelectSqlNode(SqlNode sqlNode, SelectOptions options)
      Transforms the SQL node for a SELECT statement according to the specified options.

      This method is responsible for applying database-specific transformations to SELECT statements, such as adding pagination (LIMIT/OFFSET), FOR UPDATE clauses, or other dialect-specific syntax.

      Parameters:
      sqlNode - the SQL node representing the SELECT statement to transform
      options - the options that specify how to transform the SQL, including pagination and locking settings
      Returns:
      the transformed SQL node with dialect-specific modifications applied
      Throws:
      DomaNullPointerException - if any argument is null
      JdbcException - if unsupported options are specified

    • transformSelectSqlNodeForGettingCount

      SqlNode transformSelectSqlNodeForGettingCount(SqlNode sqlNode)
      Transforms the SQL node to create a query that returns the total count of rows.

      This method is typically used for pagination scenarios where the total number of results needs to be known. It transforms a regular SELECT statement into a COUNT query that returns the total number of rows that would be returned by the original query without pagination.

      The implementation should handle removing ORDER BY clauses and other elements that are not necessary for counting rows, while preserving the WHERE conditions and JOIN clauses.

      Parameters:
      sqlNode - the SQL node representing the original SELECT statement
      Returns:
      the transformed SQL node that will return the total row count
      Throws:
      DomaNullPointerException - if sqlNode is null

    • isUniqueConstraintViolated

      boolean isUniqueConstraintViolated(SQLException sqlException)
      Determines whether the given SQLException represents a unique constraint violation.

      Different database systems use different error codes and states to indicate unique constraint violations. This method abstracts these differences.

      Parameters:
      sqlException - the SQL exception to analyze
      Returns:
      true if the exception represents a unique constraint violation, false otherwise
      Throws:
      DomaNullPointerException - if sqlException is null

    • includesIdentityColumn

      boolean includesIdentityColumn()
      Determines whether this dialect includes IDENTITY columns in SQL INSERT statements.

      Some database systems require that IDENTITY columns be excluded from INSERT statements, while others allow or require them to be included.

      Returns:
      true if this dialect includes IDENTITY columns in INSERT statements, false otherwise

    • includesIdentityColumn

      default boolean includesIdentityColumn(Object idValue)
      Determines if the identity column is included based on the provided identifier value.

      The type of idValue must be one of the basic types. It must never be a domain class or an Optional type that wraps a basic type.

      Parameters:
      idValue - an identity value; may be null
      Returns:
      true if the identity column is included, false otherwise

    • supportsIdentity

      boolean supportsIdentity()
      Determines whether this dialect supports the IDENTITY column.

      An IDENTITY column is a column that automatically generates a unique value for each row when data is inserted. The exact implementation varies by database system.

      Returns:
      true if this dialect supports IDENTITY columns, false otherwise

    • supportsSequence

      boolean supportsSequence()
      Determines whether this dialect supports database sequences.

      A sequence is a database object that generates a sequence of unique numbers. Sequences are commonly used to generate primary key values.

      Returns:
      true if this dialect supports sequences, false otherwise

    • supportsAutoGeneratedKeys

      boolean supportsAutoGeneratedKeys()
      Determines whether this dialect supports retrieving auto-generated keys via Statement.getGeneratedKeys().

      This feature allows retrieving values that were automatically generated during an insert operation, such as identity column values, without executing a separate query.

      Returns:
      true if this dialect supports retrieving auto-generated keys, false otherwise

    • supportsBatchUpdateResults

      boolean supportsBatchUpdateResults()
      Determines whether this dialect supports reliable results from Statement.executeBatch().

      Some database systems do not correctly report the number of affected rows for each statement in a batch operation. This method indicates whether the dialect can rely on these results.

      Returns:
      true if this dialect supports reliable batch update results, false otherwise

    • supportsBatchExecutionReturningGeneratedValues

      default boolean supportsBatchExecutionReturningGeneratedValues()
      Determines whether this dialect supports retrieving generated values from batch executions.

      Some database systems can return auto-generated values (like identity columns) even when executing statements in batch mode, while others cannot.

      The default implementation returns false.

      Returns:
      true if this dialect supports retrieving generated values from batch executions, false otherwise

    • supportsSelectForUpdate

      boolean supportsSelectForUpdate(SelectForUpdateType type, boolean withTargets)
      Determines whether this dialect supports pessimistic locking with the specified options.

      Pessimistic locking (SELECT FOR UPDATE) prevents other transactions from modifying selected rows. Different database systems support different variations of this feature.

      Parameters:
      type - the type of pessimistic locking (e.g., standard FOR UPDATE, NOWAIT, WAIT)
      withTargets - true if specific columns are targeted for locking, false for row-level locking
      Returns:
      true if this dialect supports the specified locking options, false otherwise

    • supportsResultSetReturningAsOutParameter

      boolean supportsResultSetReturningAsOutParameter()
      Determines whether this dialect supports result sets as OUT parameters in stored procedures.

      Some database systems allow stored procedures to return result sets through OUT parameters, while others use different mechanisms (like returning result sets directly).

      Returns:
      true if this dialect supports result sets as OUT parameters, false otherwise

    • supportsIdentityReservation

      @Deprecated boolean supportsIdentityReservation()
      Deprecated.
      This feature is deprecated and may be removed in a future version
      Determines whether this dialect supports reserving identity values in advance.

      Some database systems allow pre-allocating a range of identity values, which can improve performance in certain scenarios.

      Returns:
      true if this dialect supports identity reservation, false otherwise

    • supportsAliasInDeleteClause

      default boolean supportsAliasInDeleteClause()
      Determines whether this object supports alias reference in DELETE clause as follows: 
       DELETE t FROM employee t
      Returns:
      true, if this object supports it

    • supportsAliasInDeleteStatement

      default boolean supportsAliasInDeleteStatement()
      Determines whether the use of table aliases is supported in the context of a DELETE statement. 
       DELETE FROM employee t
      Returns:
      true if table aliasing is supported in DELETE statements, false otherwise

    • supportsAliasInUpdateClause

      default boolean supportsAliasInUpdateClause()
      Determines whether this object supports alias reference in UPDATE clause as follows: 
       UPDATE t SET t.age = 30 FROM employee t
      Returns:
      true, if this object supports it

    • supportsAliasInUpdateStatement

      default boolean supportsAliasInUpdateStatement()
      Determines whether the use of table aliases is supported in the context of an UPDATE statement. 
       UPDATE employee t SET t.age = 30
      Returns:
      true if table aliasing is supported in UPDATE statements, false otherwise

    • supportsModOperator

      default boolean supportsModOperator()
      Determines whether this object supports mod operator %.
      Returns:
      true, if this object supports it

    • supportsMultiRowInsertStatement

      default boolean supportsMultiRowInsertStatement()
      Determines whether this dialect supports multi-row insert statements (bulk inserts).

      Multi-row insert statements allow inserting multiple rows in a single SQL statement, which can significantly improve performance when inserting large amounts of data.

      The default implementation returns true.

      Returns:
      true if this dialect supports multi-row insert statements, false otherwise

    • supportsAutoIncrementWhenInsertingMultipleRows

      default boolean supportsAutoIncrementWhenInsertingMultipleRows()
      Determines whether this dialect supports auto-increment columns when inserting multiple rows.

      Some databases do not properly handle auto-increment columns in multi-row insert statements, or have limitations on how generated values can be retrieved.

      The default implementation returns true.

      Returns:
      true if this dialect supports auto-increment columns in multi-row inserts, false otherwise

    • supportsUpsertEmulationWithMergeStatement

      default boolean supportsUpsertEmulationWithMergeStatement()
      Determines whether this dialect supports upsert emulation using MERGE statements.

      An upsert operation (update or insert) can be emulated using MERGE statements in some database systems. This method indicates whether the dialect supports this approach.

      The default implementation returns false.

      Returns:
      true if this dialect supports upsert emulation with MERGE statements, false otherwise

    • supportsParenthesesForSetOperands

      default boolean supportsParenthesesForSetOperands()
      Determines whether this dialect requires parentheses around set operation operands.

      Set operations include UNION, INTERSECT, and EXCEPT. Some databases require parentheses around the operands of these operations, especially when they include ORDER BY or LIMIT clauses.

      The default implementation returns true.

      Returns:
      true if this dialect requires parentheses for set operands, false otherwise

    • getIdentitySelectSql

      Sql<?> getIdentitySelectSql(String catalogName, String schemaName, String tableName, String columnName, boolean isQuoteRequired, boolean isIdColumnQuoteRequired)
      Returns an SQL object to retrieve IDENTITY values that were generated during an insert operation.

      This method is used to create the SQL statement that retrieves the last generated identity value for a specific table and column.

      This method is available only if supportsIdentity() returns true.

      Parameters:
      catalogName - the catalog name of the table (may be null if not applicable)
      schemaName - the schema name of the table (may be null if not applicable)
      tableName - the name of the table containing the identity column
      columnName - the name of the identity column
      isQuoteRequired - whether the table name should be quoted in the SQL statement
      isIdColumnQuoteRequired - whether the identity column name should be quoted in the SQL statement
      Returns:
      the SQL object that can be executed to retrieve the generated identity value
      Throws:
      DomaNullPointerException - if either the tableName or the columnName is null

    • getIdentityReservationSql

      @Deprecated Sql<?> getIdentityReservationSql(String catalogName, String schemaName, String tableName, String columnName, boolean isQuoteRequired, boolean isIdColumnQuoteRequired, int reservationSize)
      Deprecated.
      Returns an SQL object to reserve identity in the database.

      This method is available, only if supportsIdentityReservation() returns true.

      Parameters:
      catalogName - the catalog name
      schemaName - the schema name
      tableName - the table name
      columnName - the IDENTITY column name
      isQuoteRequired - whether the quotation marks are required
      isIdColumnQuoteRequired - whether the quotation marks are required for the IDENTITY column
      reservationSize - the size of the reservation
      Returns:
      the SQL object
      Throws:
      DomaNullPointerException - if either the tableName or the columnName is null

    • getSequenceNextValSql

      Sql<?> getSequenceNextValSql(String qualifiedSequenceName, long allocationSize)
      Returns an SQL object to retrieve the next value from a database sequence.

      This method creates the SQL statement needed to get the next value from a sequence.

      The allocation size parameter can be used to optimize sequence access by retrieving multiple values at once in database systems that support this feature.

      This method is available only if supportsSequence() returns true.

      Parameters:
      qualifiedSequenceName - the fully qualified name of the sequence, which may include catalog and schema information depending on the database system
      allocationSize - the number of sequence values to allocate at once for optimization; a value greater than 1 may improve performance by reducing database calls
      Returns:
      the SQL object that can be executed to retrieve the next sequence value(s)
      Throws:
      DomaNullPointerException - if qualifiedSequenceName is null

    • getResultSetType

      JdbcType<ResultSet> getResultSetType()
      Returns the JdbcType object that corresponds to the ResultSet class.

      This method is available, only if supportsResultSetReturningAsOutParameter() is true.

      Returns:
      the JdbcType object for the ResultSet class

    • applyQuote

      String applyQuote(String name)
      Encloses the name with quotation marks.
      Parameters:
      name - the name of a database object such as a table, a column, and so on
      Returns:
      the name that is enclosed with quotation marks

    • removeQuote

      String removeQuote(String name)
      Removes quotation marks from the name
      Parameters:
      name - the name of a database object such as a table, a column, and so on
      Returns:
      the name that has no enclosing quotation marks

    • getRootCause

      Throwable getRootCause(SQLException sqlException)
      Returns the root cause of the SQL exception.
      Parameters:
      sqlException - the SQL exception
      Returns:
      the root cause
      Throws:
      DomaNullPointerException - if the sqlException is null

    • getJdbcMappingVisitor

      JdbcMappingVisitor getJdbcMappingVisitor()
      Returns the visitor that maps Wrapper to JdbcType.
      Returns:
      the visitor

    • getSqlLogFormattingVisitor

      SqlLogFormattingVisitor getSqlLogFormattingVisitor()
      Returns the visitor that maps Wrapper to SqlLogFormatter.
      Returns:
      the visitor

    • getExpressionFunctions

      ExpressionFunctions getExpressionFunctions()
      Returns the aggregation of the expression functions that are available in the SQL templates.
      Returns:
      the aggregation of the expression functions

    • createScriptBlockContext

      ScriptBlockContext createScriptBlockContext()
      Creates the context object to process an SQL block in a script.
      Returns:
      the context object

    • getScriptBlockDelimiter

      String getScriptBlockDelimiter()
      Returns the delimiter that is used as the end of an SQL block in a script.
      Returns:
      the delimiter

    • getAutoGeneratedKeysType

      AutoGeneratedKeysType getAutoGeneratedKeysType()
      Returns the type of the auto generated keys.
      Returns:
      the type of the auto generated keys

    • getCriteriaBuilder

      CriteriaBuilder getCriteriaBuilder()
      Returns the criteria builder for this dialect.

      The criteria builder is used to construct SQL queries using the criteria API, which provides a type-safe way to build queries programmatically. The returned builder will generate SQL that is compatible with the specific database dialect.

      Returns:
      the criteria builder for this dialect

    • getUpsertAssembler

      UpsertAssembler getUpsertAssembler(UpsertAssemblerContext context)
      Returns the UpsertAssembler implementation for the given context.
      Parameters:
      context - the UpsertAssemblerContext object
      Returns:
      the UpsertAssembler object for the given context

    • getMultiInsertAssembler

      <ENTITY> MultiInsertAssembler getMultiInsertAssembler(MultiInsertAssemblerContext<ENTITY> context)
      Provides an implementation of MultiInsertAssembler based on the given context.
      Type Parameters:
      ENTITY - the type of the entity to be handled by the assembler
      Parameters:
      context - the context that holds the information required to create the MultiInsertAssembler
      Returns:
      an instance of MultiInsertAssembler specific to the provided entity context

    • getInsertAssembler

      default <ENTITY> InsertAssembler getInsertAssembler(InsertAssemblerContext<ENTITY> context)
      Provides an implementation of InsertAssembler based on the given context.
      Type Parameters:
      ENTITY - the type of the entity to be handled by the assembler
      Parameters:
      context - the context that holds the information required to create the InsertAssembler
      Returns:
      an instance of InsertAssembler specific to the provided entity context

    • getUpdateAssembler

      default <ENTITY> UpdateAssembler getUpdateAssembler(UpdateAssemblerContext<ENTITY> context)
      Provides an implementation of UpdateAssembler based on the given context.
      Type Parameters:
      ENTITY - the type of the entity to be handled by the assembler
      Parameters:
      context - the context that holds the information required to create the UpdateAssembler
      Returns:
      an instance of UpdateAssembler specific to the provided entity context

    • getDeleteAssembler

      default <ENTITY> DeleteAssembler getDeleteAssembler(DeleteAssemblerContext<ENTITY> context)
      Provides an implementation of DeleteAssembler based on the given context.
      Type Parameters:
      ENTITY - the type of the entity to be handled by the assembler
      Parameters:
      context - the context that holds the information required to create the DeleteAssembler
      Returns:
      an instance of DeleteAssembler specific to the provided entity context

    • supportsReturning

      default boolean supportsReturning()
      Determines if this dialect supports the SQL RETURNING clause in database operations.

      The RETURNING clause allows a DML statement (INSERT, UPDATE, DELETE) to return data from rows that were affected by the operation. This feature is particularly useful for retrieving auto-generated values or updated columns in a single database operation, without requiring a separate SELECT statement.

      The default implementation returns true, but dialect implementations for databases that don't support this feature should override this method to return false.

      Returns:
      true if the RETURNING clause is supported by this dialect, false otherwise