追加 

追加を実行するためのDAOメソッドに @Insert アノテーションを付けます。

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

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

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

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

戻り値 

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

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

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

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

@Insert
int insert(Employee employee);

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

ID 

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の方言はこのプロパティを利用しません。

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 をログ出力することを表します。