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

Class AutoMultiInsertQuery<ENTITY>

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

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

  • Batch inserts with multiple entities in a single statement
  • Inserts with generated ID values (sequence-based only for multiple rows)
  • Inserts with version number initialization
  • Handling of duplicate key scenarios (exception or update)

The query execution process includes:

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

  • Field Details

    • entities

      protected List<ENTITY> entities
      The list of entities to be inserted.

    • 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

    • AutoMultiInsertQuery

      public AutoMultiInsertQuery(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. Checks if the dialect supports multi-row INSERT statements
      3. Skips execution if the entity list is empty
      4. Executes pre-insert entity processing for each entity
      5. Prepares special property types (ID, version, etc.)
      6. Prepares query options
      7. Determines target properties for the INSERT statement
      8. Prepares ID and version values
      9. 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 for each entity.

      This method creates a pre-insert context for each entity and calls the entity's preInsert method, allowing entity listeners to modify the entities 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.

      It also checks if the dialect supports auto-increment when inserting multiple rows, and throws an exception if not supported with IDENTITY generation type.

      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
      • 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 values for the entities before insertion.

      If the entities have a generated ID property, this method calls its preInsert method to generate or prepare the ID values before the INSERT operation.

    • prepareVersionValue

      protected void prepareVersionValue()
      Prepares the version values for the entities before insertion.

      If the entities have 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 multi-row 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 IDs for the inserted entities.

      This method is called after executing the INSERT statement to retrieve and set auto-generated keys for the entities. 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 for each entity.

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

    • 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

    • setEntities

      public void setEntities(List<ENTITY> entities)
      Sets the list of entities to be inserted.
      Parameters:
      entities - the list of entities

    • getEntities

      public List<ENTITY> getEntities()
      Returns the list of entities to be inserted.
      Returns:
      the list of entities

    • setEntity

      public void setEntity(ENTITY entity)
      This method is not supported for multi-insert queries. Use setEntities(List) instead.
      Overrides:
      setEntity in class AutoModifyQuery<ENTITY>
      Parameters:
      entity - the entity
      Throws:
      UnsupportedOperationException - always thrown

    • getEntity

      public ENTITY getEntity()
      This method is not supported for multi-insert queries. Use getEntities() instead.
      Overrides:
      getEntity in class AutoModifyQuery<ENTITY>
      Returns:
      never returns
      Throws:
      UnsupportedOperationException - always thrown