挿入¶
挿入を行うには、 @Insert をDaoのメソッドに注釈します。
@Config(config = AppConfig.class)
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);
バージョン番号¶
エンティティクラス に @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ファイルによる挿入では、識別子の自動設定やバージョン番号の自動設定は行われません。 また、 @Insert の exclude 要素、 include 要素、 excludeNull 要素は参照されません。
クエリタイムアウト¶
@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 をログ出力することを表します。