追加
追加を実行するための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
要素は参照されません。
一意制約違反
一意制約違反が発生した場合は、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 をログ出力することを表します。