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

Class AutoInsertQuery<ENTITY>

java.lang.Object
org.seasar.doma.jdbc.query.AbstractQuery
org.seasar.doma.jdbc.query.AutoModifyQuery<ENTITY>
org.seasar.doma.jdbc.query.AutoInsertQuery<ENTITY>
Type Parameters:
ENTITY - the entity type
All Implemented Interfaces:
InsertQuery, ModifyQuery, Query
public class AutoInsertQuery<ENTITY> extends AutoModifyQuery<ENTITY> implements InsertQuery
A query implementation for automatically inserting an entity into a database table.

This class provides functionality to generate and execute SQL INSERT statements based on entity definitions. It handles various insert scenarios including:

  • Standard inserts with all entity properties
  • Inserts with null property exclusion
  • Inserts with generated ID values (identity or sequence-based)
  • Inserts with version number initialization
  • Handling of duplicate key scenarios (exception or update)

The query execution process includes:

  1. Pre-insert entity processing
  2. SQL statement preparation
  3. Statement execution
  4. Generated ID retrieval (if applicable)
  5. Post-insert entity processing

  • Field Details

    • nullExcluded

      protected boolean nullExcluded
      Indicates whether null properties should be excluded from the INSERT statement.

    • generatedIdPropertyType

      protected GeneratedIdPropertyType<ENTITY,?,?> generatedIdPropertyType
      The property type for the generated ID, if the entity has one.

    • idGenerationConfig

      protected IdGenerationConfig idGenerationConfig
      Configuration for ID generation, used when the entity has a generated ID property.

    • duplicateKeyType

      protected DuplicateKeyType duplicateKeyType
      The strategy for handling duplicate key violations. Default is DuplicateKeyType.EXCEPTION, which throws an exception on duplicate key.

    • duplicateKeyNames

      protected String[] duplicateKeyNames
      The names of properties that form the unique key for duplicate key handling. Used when duplicateKeyType is not DuplicateKeyType.EXCEPTION.

  • Constructor Details

    • AutoInsertQuery

      public AutoInsertQuery(EntityType<ENTITY> entityType)
      Constructs an instance.
      Parameters:
      entityType - the entity type

  • Method Details

    • prepare

      public void prepare()
      Prepares this query for execution.

      This method performs the following operations:

      1. Validates that required components are not null
      2. Executes pre-insert entity processing
      3. Prepares special property types (ID, version, etc.)
      4. Prepares query options
      5. Determines target properties for the INSERT statement
      6. Prepares ID and version values
      7. Builds the SQL statement
      Specified by:
      prepare in interface Query
      Overrides:
      prepare in class AutoModifyQuery<ENTITY>

    • preInsert

      protected void preInsert()
      Executes pre-insert entity processing.

      This method creates a pre-insert context and calls the entity's preInsert method, allowing entity listeners to modify the entity before insertion.

    • prepareSpecialPropertyTypes

      protected void prepareSpecialPropertyTypes()
      Prepares special property types for this query.

      This method initializes the generated ID property type and its configuration, and determines if auto-generated keys are supported for this query.

      Overrides:
      prepareSpecialPropertyTypes in class AutoModifyQuery<ENTITY>

    • prepareTargetPropertyType

      protected void prepareTargetPropertyType()
      Prepares the target property types for the INSERT statement.

      This method determines which entity properties should be included in the INSERT statement based on the following rules:

      • Properties must be insertable
      • ID properties are included if they are not auto-generated or if they have a value
      • Version properties are always included
      • If nullExcluded is true, null-valued properties are excluded
      • Properties must match the include/exclude name filters if specified

      This method throws a JdbcException if a non-generated ID property has a null value.

    • prepareIdValue

      protected void prepareIdValue()
      Prepares the ID value for the entity before insertion.

      If the entity has a generated ID property, this method calls its preInsert method to generate or prepare the ID value before the INSERT operation.

    • prepareVersionValue

      protected void prepareVersionValue()
      Prepares the version value for the entity before insertion.

      If the entity has a version property, this method initializes it to 1 for optimistic locking.

    • prepareSql

      protected void prepareSql()
      Prepares the SQL statement for this query.

      This method builds either a standard INSERT statement or an UPSERT statement based on the duplicate key handling strategy. It uses the dialect-specific SQL assemblers to generate the appropriate SQL syntax.

      If the duplicate key type is EXCEPTION, a standard INSERT statement is generated. Otherwise, an UPSERT statement is generated, unless the dialect supports MERGE statements and an identity key is included in the duplicate keys, in which case it falls back to a standard INSERT.

    • generateId

      public void generateId(Statement statement)
      Generates an ID for the inserted entity.

      This method is called after executing the INSERT statement to retrieve and set auto-generated keys for the entity. It's only executed if auto-generated keys are supported for this query.

      Specified by:
      generateId in interface InsertQuery
      Parameters:
      statement - the statement used for the INSERT operation

    • complete

      public void complete()
      Completes this query by executing post-insert processing.

      This method is called after the INSERT statement has been executed and any generated IDs have been retrieved.

      Specified by:
      complete in interface Query

    • postInsert

      protected void postInsert()
      Executes post-insert entity processing.

      This method creates a post-insert context and calls the entity's postInsert method, allowing entity listeners to modify the entity after insertion.

    • setNullExcluded

      public void setNullExcluded(boolean nullExcluded)
      Sets whether null properties should be excluded from the INSERT statement.
      Parameters:
      nullExcluded - true to exclude null properties, false otherwise

    • setDuplicateKeyType

      public void setDuplicateKeyType(DuplicateKeyType duplicateKeyType)
      Sets the strategy for handling duplicate key violations.
      Parameters:
      duplicateKeyType - the duplicate key handling strategy

    • setDuplicateKeyNames

      public void setDuplicateKeyNames(String... duplicateKeyNames)
      Sets the names of properties that form the unique key for duplicate key handling.
      Parameters:
      duplicateKeyNames - the property names that form the unique key