追加

DAO メソッドに @Insert を付けて、追加操作を実行します。

@Dao
public interface EmployeeDao {
    @Insert
    int insert(Employee employee);

    @Insert
    Result<ImmutableEmployee> insert(ImmutableEmployee employee);
}

デフォルトでは、INSERT ステートメントが自動生成されます。@Insert アノテーション内の sqlFile プロパティに true を設定することで、任意の SQL ファイルをマッピングできます。

エンティティクラスパラメータにエンティティリスナーが指定されている場合、追加操作を実行する前にその preInsert メソッドが呼び出されます。同様に、追加操作が完了した後で postInsert メソッドが呼び出されます。

戻り値

returning プロパティを使用する場合

Returning を参照してください。

returning プロパティを使用しない場合

パラメータが不変のエンティティクラスの場合、戻り値はエンティティクラスを要素とする org.seasar.doma.jdbc.Result である必要があります。

上記の条件が満たされない場合、戻り値は更新された件数を表す int でなければなりません。

自動生成された SQL による追加

パラメータの型はエンティティクラスである必要があります。指定できるパラメータは1つだけです。パラメータはnullであってはなりません。

@Insert
int insert(Employee employee);

@Insert
Result<ImmutableEmployee> insert(ImmutableEmployee employee);

ID

エンティティ のIDが @GeneratedValue で注釈されている場合にIDは自動的に生成され設定されます。

注意点については ID自動生成 を参照してください。

バージョン番号

エンティティ に @Version が注釈されたプロパティがある場合、 そのプロパティに明示的に 0 以上の値が設定されていればその値を使用します。

もし設定されていないか、0 未満の値が設定されていれば、1 を自動的に設定します。

@Insert のプロパティ

insertable

エンティティクラスに @Column が注釈されたプロパティが含まれており、その @Column の insertable 要素がfalseに設定されている場合、プロパティは追加から除外されます。

exclude

@Insert の exclude 要素に指定されたプロパティは挿入から除外されます。 @Column の insertable 要素が true に設定されていても、この要素にプロパティが指定されている場合は追加から除外されます。

@Insert(exclude = {"name", "salary"})
int insert(Employee employee);

include

@Insert の include 要素に指定されたプロパティのみを追加対象とします。 @Insert の include 要素と exclude 要素の両方に同じプロパティが指定された場合、 そのプロパティは追加対象外になります。

この要素にプロパティが指定されている場合でも、 @Column の insertable 要素が false に設定されている場合は追加されません。

@Insert(include = {"name", "salary"})
int insert(Employee employee);

excludeNull

@Insert の excludeNull 要素が true に設定されている場合、値が null であるプロパティは追加から除外されます。この要素が true に設定されている場合でも、そのプロパティの @Column アノテーションの insertable 要素が true でも、またはそのプロパティが @Insert の include 要素で指定されていても、値が null の場合は挿入から除外されます。

@Insert(excludeNull = true)
int insert(Employee employee);

duplicateKeyType

このプロパティは、追加操作時に重複したキーを処理する方法を定義します。

次の3つの値のいずれかを取ることができます:

• DuplicateKeyType.UPDATE: 重複したキーが見つかった場合、テーブル内の既存の行が更新されます。

• DuplicateKeyType.IGNORE: 重複したキーが見つかった場合、挿入操作は無視され、テーブルに変更は加えられません。

• DuplicateKeyType.EXCEPTION: 重複したキーが発生した場合、例外が投げられます。

@Insert(duplicateKeyType = DuplicateKeyType.UPDATE)
int insert(Employee employee);

duplicateKeys

このプロパティは、重複キーが存在するかどうかを判断するために使用するキーを表します。 重複キーが存在する場合、重複キーを処理するために duplicateKeyType ストラテジーを使用します。

@Insert(duplicateKeyType = DuplicateKeyType.UPDATE, duplicateKeys = {"employeeNo"})
int insert(Employee employee);

注釈

このプロパティは、duplicateKeyType ストラテジーが DuplicateKeyType.UPDATE または DuplicateKeyType.IGNORE のいずれかである場合にのみ使用されます。

注釈

MySQLの方言はこのプロパティを利用しません。

returning

returning プロパティで @Returning を指定することで、SQL の INSERT .. RETURNING 句に相当するコードを生成できます。

@Dao
public interface EmployeeDao {
    @Insert(returning = @Returning)
    Employee insert(Employee employee);

    @Insert(returning = @Returning(include = { "employeeId", "version" }))
    Employee insertReturningIdAndVersion(Employee employee);

    @Insert(returning = @Returning(exclude = { "password" }))
    Employee insertReturningExceptPassword(Employee employee);

    @Insert(returning = @Returning, duplicateKeyType = DuplicateKeyType.IGNORE)
    Optional<Employee> insertOrIgnore(Employee employee);
}

@Returning の include 要素を使用して、RETURNING 句によって返されるエンティティのプロパティ（データベース列に対応）を指定できます。また、exclude 要素を使用して、返されるべきでないプロパティを指定することもできます。同じエンティティのプロパティが include と exclude の両方の要素に含まれている場合、それは返されません。

戻り値の型は、エンティティクラスまたはエンティティクラスを要素として含む Optional のいずれかでなければなりません。

注釈

この機能は、H2 Database、PostgreSQL、SQL Server、およびSQLiteのダイアレクトのみがサポートしています。

SQLファイルによる追加

SQLファイルによる挿入を行うには、@Insert の sqlFile 要素に true を設定し、メソッドに対応するSQLファイルを用意します。

任意の型をパラメータとして使用できます。指定できるパラメータの数に制限はありません。パラメータの型が基本型またはドメインクラスの場合、パラメータに null を設定できます。型がそれ以外の場合、パラメータは null であってはなりません。

@Insert(sqlFile = true)
int insert(Employee employee);

@Insert(sqlFile = true)
Result<ImmutableEmployee> insert(ImmutableEmployee employee);

たとえば、上記のメソッドに対応するSQLは次のように記述します。

insert into employee (id, name, salary, version)
values (/* employee.id */0,
        /* employee.name */'hoge',
        /* employee.salary */100,
        /* employee.version */0)

SQLファイルから追加する際に、識別子およびバージョンの自動設定は行われません。

また、以下の @Insert のプロパティは使用されません。

• exclude

• include

• excludeNull

• duplicateKeyType

• duplicateKeys

一意制約違反

SQLファイルの使用にかかわらず、ユニーク制約違反が発生すると UniqueConstraintException がスローされます。

クエリタイムアウト

@Insert の queryTimeout 要素にクエリタイムアウトの秒数を指定できます。

@Insert(queryTimeout = 10)
int insert(Employee employee);

この指定は、SQLファイルの使用の有無に関係なく適用されます。 queryTimeout 要素に値を指定しない場合、 設定 に指定されたクエリタイムアウトが使用されます。

SQLログの出力形式

@Insert の sqlLog 要素に SQL のログ出力形式を指定できます。

@Insert(sqlLog = SqlLogType.RAW)
int insert(Employee employee);

SqlLogType.RAW は、バインドパラメータでSQLをログに記録することを示します。