追加

追加を実行するための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 を自動で設定します。

追加対象プロパティの制御

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);

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ファイルによる追加では、IDの自動設定やバージョン番号の自動設定は行われません。 また、 @Insert の exclude 要素、 include 要素、 excludeNull 要素は参照されません。

Upsert

duplicateKeyType プロパティを使用することで、レコードが重複した場合に更新するか無視するかを指定できます。デフォルトでは DuplicateKeyType.EXCEPTION が使用され、重複時にエラーが発生することを表します。 duplicateKeyType プロパティには DuplicateKeyType.UPDATE , DuplicateKeyType.IGNORE , DuplicateKeyType.EXCEPTION の3つの中からいずれかを選択して指定できます。

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

@Insert(duplicateKeyType = DuplicateKeyType.IGNORE)
int insertOnDuplicateKeyIgnore(Employee employee);

一意制約違反

一意制約違反が発生した場合は、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 をログ出力することを表します。