5.2. データベースアクセス（JPA編）

5.2.1.1.1. JPAのO/R Mapping

JPAを使用した際の、リレーショナルデータベースで管理されているレコードとJavaオブジェクトは、以下のようなイメージでマッピングされる。

Picture - Image of O/R Mapping

5.2.1.1.2. JPAの基本用語

以下に、JPAを使う上で、最低限知っていてほしい用語について、簡単に説明する。

項番	用語	説明
	Entityクラス	リレーショナルデータベースで管理されているレコードを表現するJavaクラス。 @javax.persistence.Entityアノテーションを付与されたクラスが、Entityクラスとなる。
	EntityManager	Entityのライフサイクルを管理するために、必要なAPIを提供するインタフェース。 アプリケーションは、javax.persistence.EntityManagerのメソッドを使用して、リレーショナルデータベースで管理されているレコードを、Javaオブジェクトとして操作する。 Spring Data JPAを使う場合は、直接、使用することはないが、Spring Data JPAの仕組みでは表現できないような、Queryを発行する必要がある場合は、このインタフェースを経由してEntityを取得することになる。
	TypedQuery	Entityを検索するためのAPIを提供するインタフェース。 アプリケーションは、javax.persistence.TypedQueryのメソッドを使用して、ID以外の条件に一致するEntityを検索する。 Spring Data JPAを使う場合は、直接使用することはないが、Spring Data JPAの仕組みでは、表現できないようなQueryを発行する必要がある場合は、このインタフェースを使用してEntityを検索することになる。 条件に一致する永続層(DB)のEntityを直接操作(更新または削除)するためのメソッドもこのインタフェースに用意されている。
	PersistenceContext	Entityを管理するための領域。 EntityManager を経由して取得または作成されたEntityは、この領域に格納されてライフサイクル管理される。この領域で管理されているEntityの事を「管理状態のEntity」と呼ぶ。 この領域は、アプリケーションから直接アクセスすることはできない。 Entityの状態は「管理状態」以外に、「作成状態」「削除状態」「分離状態」が存在する。
	findメソッド	管理状態のEntityを取得するためのメソッド。 IDに対応するEntityがPersistenceContextに存在しない場合は、リレーショナルデータベースに格納されているレコードを取得(SELECT)し、管理状態のEntityを生成する。
	persistメソッド	アプリケーションで作成した作成状態のEntityを、管理状態のEntityにするためのメソッド。 EntityManager のメソッドとして提供されており、リレーショナルデータベースにレコードのINSERTを実行するための操作がPersistenceContextに蓄積される。
	mergeメソッド	PersistenceContextで管理されていない分離状態のEntityを、管理状態のEntityにするためのメソッド。 EntityManagerのメソッドとして提供されており、基本的にはリレーショナルデータベースに格納されているレコードに対して、UPDATEを実行するための操作がPersistenceContextに蓄積される。 ただし、リレーショナルデータベースにIDに一致するレコードが存在しない場合は、UPDATEではなくINSERTが実行される。
	removeメソッド	管理状態のEntityを、削除状態のEntityにするためのメソッド。 EntityManagerのメソッドとして提供されており、リレーショナルデータベースに格納されているレコードに対して、DELETEを実行するための操作がPersistenceContextに蓄積される。
	flushメソッド	PersistenceContextで管理されているEntityに対して行われた操作を、リレーショナルデータベースに強制的に反映するためのメソッド。 EntityManagerのメソッドとして提供されており、蓄積された未反映の操作をリレーショナルデータベースに対して実行する。 通常、リレーショナルデータベースへの反映は、トランザクションコミット時に行われるが、コミットより前に反映する必要がある場合は、メソッドを使用する。

5.2.1.1.3. Entityのライフサイクル管理

Entityのライフサイクル管理イメージは、以下の通りである。

Picture - Life cycle of entity

項番	説明
(1)	EntityManagerのpersistメソッドを呼び出すと、引数に渡したEntity(作成状態のEntity)が、管理状態のEntityとして、PersistenceContextに格納される。
(2)	EntityManagerのfindメソッドを呼び出すと、引数に渡したIDをもつ管理状態の、Entityが返却される。 PersistenceContextに存在しない場合は、Queryを発行して、リレーショナルデータベースよりマッピング対象のレコードを取得し、管理状態のEntityとして格納する。
(3)	EntityManagerのmergeメソッドを呼び出すと、引数に渡したEntity(分離状態のEntity)の状態が、管理状態のEntityにマージされる。 PersistenceContextに存在しない場合は、Queryを発行してリレーショナルデータベースよりマッピング対象のレコードを取得し、管理状態のEntityを格納した後に、引数に渡されたEntityの状態がマージされる。 このメソッドを呼び出した場合、persistメソッドとは異なり、引数に渡したEntityが管理状態のEntityとして格納されるわけではないという点に注意すること。
(4)	EntityManagerのremoveメソッドを呼び出すと、引数に渡した管理状態のEntityが削除状態のEntityとなる。 このメソッドを呼び出した場合、削除状態となったEntityを取得することはできなくなる。
(5)	EntityManagerのflushメソッドを呼び出すと、persist、merge、removeメソッドによって、蓄積されたEntityへの操作が、リレーショナルデータベースに反映される。 このメソッドを呼び出すことで、Entityに対して行った変更内容が、リレーショナルデータベースのレコードに同期される。 ただし、リレーショナルデータベース側のレコードに対してのみ行われた変更は、Entityには同期されない EntityManagerのfindメソッドを使わずにQueryを発行してEntityを検索すると、検索処理を行う前に、EntityManager内部の処理でflushメソッドと同等の処理が実行され、蓄積されていたEntityへの操作がリレーショナルデータベースに反映される仕組みになっている。 Spring Data JPAを使用した際の永続操作の反映タイミングについては、 永続操作の反映タイミングについて(その１) 永続操作の反映タイミングについて(その2) を参照されたい。

Note

他のライフサイクル管理用のメソッドについて

EntityManagerには、Entityのライフサイクルを管理するためのメソッドとして、detachメソッド、refreshメソッド、clearメソッドなどがあるが、 Spring Data JPAを使用する場合、デフォルトの機能で、これらのメソッドを呼び出す仕組みが存在しないため、メソッドの役割のみ説明しておく。

• detachメソッドは、管理状態のEntityを分離状態のEntityにするためのメソッド。
• refreshメソッドは、管理状態のEntityをリレーショナルデータベースの状態で最新化するためのメソッド。
• clearメソッドは、PersistenceContextで、管理されているEntityおよび蓄積された操作をメモリ上から破棄するためのメソッド。

clearメソッドについては、Spring Data JPAより提供されている@ModifyingアノテーションのclearAutomatically属性を、trueに設定することで、呼び出すことができる。 詳細については、永続層のEntityを直接操作するを参照されたい。

Note

作成状態と分離状態のEntityへの操作について

作成状態のEntityや、分離状態のEntityに行った操作は、persistメソッドまたはmergeメソッドを呼び出さないと、リレーショナルデータベースには反映されない。

5.2.2.2.1. データソースの設定

5.2.2.2.2. EntityManagerの設定

EntityManagerを使用するための設定を行う。

• xxx-infra.xml

<!-- (1) -->
<bean id="jpaVendorAdapter"
    class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
    <!-- (2) -->
    <property name="showSql" value="false" />
    <!-- (3) -->
    <property name="database" value="POSTGRESQL" />
</bean>

<!-- (4) -->
<bean id="entityManagerFactory"
    class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <!-- (5) -->
    <property name="packagesToScan" value="xxxxxx.yyyyyy.zzzzzz.domain.model" />
    <!-- (6) -->
    <property name="dataSource" ref="dataSource" />
    <!-- (7) -->
    <property name="jpaVendorAdapter" ref="jpaVendorAdapter" />
    <!-- (8) -->
    <property name="jpaPropertyMap">
        <util:map>
            <entry key="hibernate.hbm2ddl.auto" value="none" />
            <entry key="hibernate.ejb.naming_strategy"
                value="org.hibernate.cfg.ImprovedNamingStrategy" />
            <entry key="hibernate.connection.charSet" value="UTF-8" />
            <entry key="hibernate.show_sql" value="false" />
            <entry key="hibernate.format_sql" value="false" />
            <entry key="hibernate.use_sql_comments" value="true" />
            <entry key="hibernate.jdbc.batch_size" value="30" />
            <entry key="hibernate.jdbc.fetch_size" value="100" />
        </util:map>
    </property>
</bean>

項番	説明
(1)	JPAプロバイダが提供する実装クラスとのアダプタクラスを指定する。 JPAプロバイダとしてHibernateを使用するので、org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapterを指定する。
(2)	SQLの出力有無を指定する。設定例では、「false:出力しない 」を指定している。
(3)	使用するRDBMSに対応する値を設定する。org.springframework.orm.jpa.vendor.Database列挙型に定義されている値を、指定することができる。 設定例では「PostgreSQL」を指定している。 【プロジェクトで使用するデータベースに対応する値に変更が必要】 環境によって使用するデータベースがかわる場合は、プロパティファイルに値を定義すること。
(4)	javax.persistence.EntityManagerFactory のインスタンスを作成するFactoryBeanのクラスを指定する。 org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean を指定する。
(5)	Entityクラスが格納されているパッケージを指定する。 指定したパッケージに格納されているEntityクラスが、javax.persistence.EntityManagerで管理することができるEntityクラスとなる。 【プロジェクトのパッケージに変更が必要】
(6)	永続層(DB)にアクセスする際に使用するデータソースを指定する。 設定済みのデータソースのbeanを指定する。
(7)	JpaVendorAdapter のbeanを指定する。 (1)で設定済みのbeanを指定する。
(8)	Hibernateから提供されている EntityManager の動作設定を指定する。 詳細については「Hibernate Reference Documentation」を参照されたい。

Tip

データベースにOracleを使う際に、テーブル結合を行うSQLにANSI標準のJOINを使用したい場合は、(8)のjpaPropertyMapに、以下の設定を指定することで実現できる。

<bean id="entityManagerFactory"
    class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <!-- omitted -->
    <property name="jpaPropertyMap">
        <util:map>
            <!-- omitted -->
            <entry key="hibernate.dialect"
                   value="org.hibernate.dialect.Oracle10gDialect" />  <!-- (9) -->
        </util:map>
    </property>
</bean>

項番	説明
(9)	"hibernate.dialect"にorg.hibernate.dialect.Oracle10gDialectを指定する。 Oracle10gDialectを指定することで、テーブル結合を行うSQLにANSI標準のJOIN句が使用される。

• xxx-infra.xml

<bean id="entityManagerFactory"
    class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">

    <!-- omitted -->

    <!-- (10) -->
    <property name="jtaDataSource" ref="dataSource" />

    <!-- omitted -->

    <property name="jpaPropertyMap">
        <util:map>

            <!-- omitted -->

            <!-- (11)  -->
            <entry key="hibernate.transaction.jta.platform"
                value="org.hibernate.service.jta.platform.internal.WeblogicJtaPlatform" />

        </util:map>
    </property>
</bean>

項番	説明
(10)	永続層(DB)にアクセスする際に使用するデータソースを指定する。 JTAを使用する場合は、"dataSource"プロパティではなく、"jtaDataSource"プロパティに、アプリケーションサーバで定義したDataSourceを指定する。 アプリケーションサーバで定義したDataSourceの取得方法については、共通編のデータソースの設定を参照されたい。
(11)	"jpaPropertyMap" プロパティに、JTAのプラットフォームの指定を追加する。 上記は、WeblogicのJTAを使用する場合の設定例となる。 設定可能な値(プラットフォーム)は、 org.hibernate.service.jta.platform.spi.JtaPlatform の実装クラスのFQCNとなる。 主なアプリケーションサーバ向けの実装クラスについては、Hibernateから提供されている。

Note

環境によって使用するトランザクションマネージャを切り替える必要がある場合は、 "entityManagerFactory" のbean定義は xxx-infra.xml ではなく、 xxx-env.xml に行うことを推奨する。

トランザクションマネージャを環境によって切り替える必要がある具体例としては、ローカルの開発環境ではTomcatなどJTAの機能を持たないアプリケーションサーバを使用し、 本番および各試験環境では、WeblogicなどのJTAの機能をもつアプリケーションサーバを使用するといったケースがあげられる。

5.2.2.2.3. PlatformTransactionManagerの設定

ローカルトランザクションを使用する場合は、以下の設定を行う。

• xxx-env.xml

<bean id="transactionManager"
    class="org.springframework.orm.jpa.JpaTransactionManager"> <!-- (1) -->
    <property name="entityManagerFactory" ref="entityManagerFactory" /> <!-- (2) -->
</bean>

項番	説明
(1)	org.springframework.orm.jpa.JpaTransactionManager を指定する。 このクラスは、JPAのAPIを呼び出してトランザクション制御を行う。
(2)	トランザクション内で使用するEntityManagerの、Factoryを指定する。 設定済みのEntityManagerFactoryのbeanを指定する。

アプリケーションサーバから提供されているトランザクションマネージャ(JTA)を使用する場合は、以下の設定を行う。

• xxx-env.xml

<tx:jta-transaction-manager /> <!-- (1) -->

項番	説明
(1)	アプリケーションがデプロイされているアプリケーションサーバに最適なorg.springframework.transaction.jta.JtaTransactionManagerが、”transactionManager”というidで、bean定義される。 bean定義されたクラスは、JTAのAPIを呼び出して、トランザクション制御を行う。

5.2.2.2.4. persistence.xmlの設定

Todo

TBD

現時点では、persistence.xml に必ず設定しなくてはいけない設定項目はないが、今後増える可能性はある。

また、Java EEのアプリケーションサーバー上のEntityManagerFactoryを使用する場合は、 persistence.xmlに、設定が必要となると思われるので、Java EEのアプリケーションサーバー上のEntityManagerFactoryを使用する場合の設定については、今後整備する予定である。

5.2.2.2.5. Spring Data JPAを有効化するための設定

• xxx-infra.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:jpa="http://www.springframework.org/schema/data/jpa"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation=".....
    http://www.springframework.org/schema/data/jpa
    http://www.springframework.org/schema/data/jpa/spring-jpa.xsd"> <!-- (1) -->

    <!-- ... -->

</beans>

<jpa:repositories base-package="xxxxxx.yyyyyy.zzzzzz.domain.repository" /> <!-- (2) -->

項番	説明
(2)	Spring Data JPAのコンフィギュレーション用のスキーマ定義を取り込み、ネームスペースとして("jpa")を付与する。
(1)	RepositoryインタフェースおよびカスタムRepositoryクラスが格納されているベースパッケージを指定する。 org.springframework.data.repository.Repository を継承しているインタフェースと、org.springframework.data.repository.RepositoryDefinitionアノテーションが付与されているインタフェースが、 Spring Data JPAのRepositoryクラスとして自動的にbean定義される。

• <jpa:repositories>要素の属性について

  属性として、entity-manager-factory-ref、transaction-manager-ref、named-queries-location、query-lookup-strategy、factory-class、repository-impl-postfixが存在する。

項番	要素	説明
	entity-manager-factory-ref	Repositoryで使用する EntityManager を生成するためのFactoryを指定する。 通常指定する必要はないが、 EntityManager のFactoryを複数用意する場合は、使用するbeanの指定する必要がある。
	transaction-manager-ref	Repositoryのメソッドが呼び出された際に使用する PlatformTransactionManager を指定する。 デフォルトは "transactionManager" というbean名で登録されているbeanが使用される。 使用する PlatformTransactionManager のbean名が "transactionManager" でない場合は指定が必要である。
	named-queries-location	Named Queryが指定されているSpring Data JPAのプロパティファイルのロケーションを指定する。 デフォルトは「classpath:META-INF/jpa-named-queries.properties」が使用される。
	query-lookup-strategy	Queryメソッドが呼び出された特に実行するQueryをLookupする方法を指定する。 デフォルトは "CREATE_IF_NOT_FOUND" となっている。詳細は、Spring Data JPA - Reference Documentationの “Query lookup strategies”を参照されたい。 特に理由がない場合は、デフォルトのままでよい。
	factory-class	Repositoryインタフェースのメソッドが呼び出された際の処理を実装するクラスを生成するためのFactoryを指定する。 デフォルトでは、 org.springframework.data.jpa.repository.support.JpaRepositoryFactory が使用される。Spring Data JPAのデフォルト実装を変更する場合や、新しいメソッドを追加する場合に作成したFactoryを指定する。 新しいメソッドを追加する方法については、すべてのRepositoryインタフェースに一括で追加するを参照されたい。
	repository-impl-postfix	カスタムRepositoryの実装クラスをであることを表す接尾辞を指定する。 デフォルトは "Impl" となっている。例えば、Repositoryインタフェースの名前が OrderRepository の場合は、 OrderRepositoryImpl がカスタムRepositoryの実装クラスとなる。特に理由がない場合は、デフォルトのままでよい。 カスタムRepositoryについては、「Entity毎のRepositoryインタフェースに個別に追加する」を参照されたい。

5.2.2.2.6. JPAのアノテーションを使用するための設定

5.2.2.2.7. JPAの例外を DataAccessExceptionに変換するための設定

5.2.2.2.8. OpenEntityManagerInViewInterceptorの設定

ControllerやJSP等のアプリケーション層でEntityのLazy Fetchを行うためには、org.springframework.orm.jpa.support.OpenEntityManagerInViewInterceptorを使用して、 EntityManager の生存期間をアプリケーション層まで伸ばす必要がある。

Picture - Lifetime of EntityManager on OpenEntityManagerInViewInterceptor

OpenEntityManagerInViewInterceptor を使用しない場合は、 EntityManager の生存期間はトランザクションと同じになるため、 アプリケーション層で必要となるデータをServiceクラスの処理としてFetchするか、Lazy Fetchを使わずにEager Fetchを使用する必要がある。

Picture - Default Life time of EntityManager

下記の点から、基本的にはFetch方法はLazy Fetchとして、OpenEntityManagerInViewInterceptorを使用することを推奨する。

• Serviceクラスの処理としてFetchした場合、getterメソッドを呼び出すだけの処理やgetterメソッドへアクセスしたコレクションへのアクセスなど、一見意味のない処理を実装することになってしまう。
• Eager Fetchにした場合、アプリケーション層で使用しないデータへのFetchも行われる可能性があるため、性能に影響を与える可能性がある。

以下に OpenEntityManagerInViewInterceptor の設定例を示す。

• spring-vmc.xml

<mvc:interceptors>
    <mvc:interceptor>
        <mvc:mapping path="/**" /> <!-- (1) -->
        <mvc:exclude-mapping path="/resources/**" /> <!-- (1) -->
        <mvc:exclude-mapping path="/**/*.html" /> <!-- (1) -->
        <!-- (2) -->
        <bean
            class="org.springframework.orm.jpa.support.OpenEntityManagerInViewInterceptor" />
    </mvc:interceptor>
</mvc:interceptors>

項番	説明
(1)	Interceptorを適用するパスと、除外パスを指定する。 例では、リソースファイル(js、css、imageなど)のパスと、静的Webページ(HTML)のパス以外のリクエストに対してInterceptorを適用している。
(2)	org.springframework.orm.jpa.support.OpenEntityManagerInViewInterceptor を指定する。

Note

静的リソースへのパスを適用対象外とする

静的リソース(js、css、image、htmlなど)のパスについては、データアクセスが発生しないため、Interceptorの適用外とすることを推奨する。 適用対象にしてしまうと、 EntityManager に対して無駄な処理（インスタンス生成とクローズ処理）が実行されることになる。

Note

Servlet Filter層でのLazy Fetchについて

Servlet Filter層でLazy Fetchが発生しないように設計および実装することを推奨する。 OpenEntityManagerInViewInterceptor を使用した方が、 適用パターンと除外パターンを柔軟に指定できるため、 EntityManager の生存期間をアプリケーション層まで伸ばす対象のパスを指定しやすくなる。 Servlet Filterで必要となるデータへのアクセスについては、Serviceクラスの処理として事前にFetchしておくか、またはEager Fetchを使用して事前にロードしておくことで、Lazy Fetchが発生しないようにする。

Picture - Lifetime of EntityManager on OpenEntityManagerInViewFilter

以下に OpenEntityManagerInViewFilter の設定例を示す。

• web.xml

<!-- (1) -->
<filter>
    <filter-name>Spring OpenEntityManagerInViewFilter</filter-name>
    <filter-class>org.springframework.orm.jpa.support.OpenEntityManagerInViewFilter</filter-class>
</filter>
<!-- (2) -->
<filter-mapping>
    <filter-name>Spring OpenEntityManagerInViewFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

項番	説明
(1)	org.springframework.orm.jpa.support.OpenEntityManagerInViewFilter を指定する。 このServlet Filterは、 Lazy Fetchが発生するServlet Filterより前に定義する必要がある。
(2)	フィルタを適用するURLのパターンを指定する。可能な限り必要なパスのみに適用することを推奨するが、設定が煩雑になってしまうのであれば、「/*」（すべてのリクエスト）としてもよい。

Note

OpenEntityManagerInViewFilter を適用するURLのパターンに「/*」（すべてのリクエスト）を指定した場合は、 OpenEntityManagerInViewInterceptor の設定は不要となる。

5.2.2.3.1. Spring Data提供のインタフェースを継承する

Spring Dataから提供されているインタフェースを継承してEntity毎のRepositoryインタフェースを作成する方法について説明する。

継承することができるインタフェースは以下の通り。

項番	インタフェース	説明
	org.springframework.data.repository CrudRepository	汎用的なCRUD操作を行うメソッドを提供しているRepositoryインタフェース。
	org.springframework.data.repository PagingAndSortingRepository	CrudRepository のfindAllメソッドにページネーション機能とソート機能を追加したRepositoryインタフェース。
	org.springframework.data.jpa.repository JpaRepository	JPAの仕様に依存するメソッドを提供しているRepositoryインタフェース。 PagingAndSortingRepository を継承しているため、 PagingAndSortingRepository および CrudRepository のメソッドも使用する事ができる。 特に理由がない場合は、本インタフェースを継承してEntity毎のRepositoryインタフェースを作成することを推奨する。

Note

Spring Data提供のRepositoryインタフェースのデフォルト実装について

上記インタフェースで定義されているメソッドの実装は、Spring Data JPAより提供されている org.springframework.data.jpa.repository.support.SimpleJpaRepository で行われている。

以下に、作成例を示す。

public interface OrderRepository extends JpaRepository<Order, Integer> { // (1)

}

項番	説明
(1)	JpaRepository を継承し、ジェネリック型 <T> にEntityの型、ジェネリック型 <ID extends Serializable> にEntityのIDの型を指定する。 上記例では、EntityにOrder型、EntityのIDにInteger型を指定している。

JpaRepository を継承してEntity毎のRepositoryインタフェースを作成すると、以下のメソッドに対する実装を得ることが出来る。

項番	メソッド	説明
	<S extends T> S save(S entity)	指定されたEntityに対する永続操作(INSERT/UPDATE)を javax.persistence.EntityManger に蓄積するためのメソッド。 IDプロパティ(@javax.persistence.Id アノテーションまたは @javax.persistence.EmbeddedId アノテーションが付与されているプロパティ)に値が設定されていない場合は EntityManager の persist メソッドが呼ばれ、値が設定されている場合は merge メソッドが呼び出される。 mergeメソッドが呼び出された場合、返却されるEntityオブジェクトは、引数で渡されたEntityとは別のオブジェクトとなるので注意すること。
	<S extends T> List<S> save(Iterable<S> entities)	指定された複数のEntityに対する永続操作を EntityManger に蓄積するためのメソッド。 <S extends T> S save(S entity) メソッドを繰り返し呼び出す事で実現している。
	T saveAndFlush(T entity)	指定されたEntityに対する永続操作を EntityManger に蓄積した後に、蓄積されている永続操作(INSERT/UPDATE/DELETE)を永続層(DB)に反映するためのメソッド。
	void flush()	EntityManager に蓄積されたEntityへの永続操作(INSERT/UPDATE/DELETE)を永続層(DB)に実行するためのメソッド。
	void delete(ID id)	指定されたIDのEntityに対する削除操作を EntityManger に蓄積するためのメソッド。 このメソッドは T findOne(ID) メソッドを呼び出してEntityオブジェクトを EntityManger の管理下にしてから削除している。 T findOne(ID) メソッドの呼び出し時にEntityが存在しない場合は、 org.springframework.dao.EmptyResultDataAccessExceptionが発生する。
	void delete(T entity)	指定されたEntityに対する削除操作を EntityManger に蓄積するためのメソッド。
	void delete(Iterable<? extends T> entities)	指定された複数のEntityに対する削除操作を EntityManger に蓄積するためのメソッド。 void delete(T entity) メソッドを繰り返し呼び出す事で実現している。削除対象のEntityが大量になる場合は、 voiddeleteInBatch(Iterable<T> entities) メソッドを使用した方が効率的に削除することができる。
	void deleteAll()	すべてのEntityに対する削除操作を EntityManger に蓄積するためのメソッド。 List<T> findAll() メソッドで取得したEntityに対して void delete(T entity) メソッドを繰り返し呼び出す事で実現している。 削除対象のEntityが大量になる場合は、 void deleteAllInBatch() メソッドを使用すること。このメソッドは削除するEntityをすべてアプリケーション上に読み込むので、メモリ枯渇の原因になる。
	void deleteInBatch(Iterable<T> entities)	指定された複数のEntityを直接永続層(DB)から削除するためのメソッド。 このメソッドを使って削除した場合、 EntityManager 上で管理(キャッシュ)されているEntityは削除されないため、 本メソッドで削除した後に T findOne(ID id) メソッドを呼び出すと EntityManager 上で管理されているEntityが返却されるので注意が必要。 後続処理で削除したEntityに対して T findOne(ID id) メソッドなどの EntityManager 上で管理(キャッシュ)されているEntityオブジェクトを返却するメソッドを呼び出す可能性がある場合は、 void delete(Iterable<? extends T> entities) メソッドを使用して削除すること。
	void deleteAllInBatch()	すべてのEntityを直接永続層(DB)から削除するためのメソッド。 void deleteInBatch(Iterable<T> entities) メソッドと同様、EntityManager 上で管理(キャッシュ)されているEntityは削除されない点に注意すること。
	T findOne(ID id)	指定されたIDのEntityを永続層(DB)から取得するためのメソッド。 永続層から取得されたEntityは EntityManager によって管理(キャッシュ)されるため、2回目以降のアクセスでは永続層へのアクセスは発生せず、キャッシュされているEntityが返却される。
	List<T> findAll()	すべてのEntityを永続層(DB)から取得するためのメソッド。 永続層から取得されたEntityは EntityManager によって管理(キャッシュ)される。
	Iterable<T> findAll(Iterable<ID> ids)	指定された複数のIDのEntityを永続層(DB)から取得するためのメソッド。 永続層から取得されたEntityは EntityManager によって管理(キャッシュ)される。 指定されたIDはIN句を使って検索されるため、OracleなどIN句に指定できる値の数に制限があるDBを使う場合は注意すること。
	List<T> findAll(Sort sort)	指定された並び順ですべてのEntityを永続層(DB)から取得するためのメソッド。 永続層から取得されたEntityは EntityManager によって管理(キャッシュ)される。
	Page<T> findAll(Pageable pageable)	指定されたページ(並び順、ページ数、ページ内に表示する件数)に一致するEntityを永続層(DB)から取得するためのメソッド。 永続層から取得されたEntityは EntityManager によって管理(キャッシュ)される。
	boolean exists(ID id)	指定されたIDのEntityが存在するかチェックするためのメソッド。
	long count()	永続化対象のEntityの件数を取得するためのメソッド。

Warning

JPAの楽観ロック(@javax.persistence.Version)使用時の動作について

JPAの楽観ロック( @Version )使用時に更新対象のEntityが更新または削除された場合は、org.springframework.dao.OptimisticLockingFailureExceptionが発生する。 OptimisticLockingFailureException が発生する可能性があるメソッドは、以下の通りである。

• <S extends T> S save(S entity)
• <S extends T> List<S> save(Iterable<S> entities)
• T saveAndFlush(T entity)
• void delete(ID id)
• void delete(T entity)
• void delete(Iterable<? extends T> entities)
• void deleteAll()
• void flush()

JPAの楽観ロックの詳細については 排他制御 を参照されたい。

Note

永続操作の反映タイミングについて(その１)

EntityManagerに蓄積されたEntityへの永続操作は、トランザクションをコミットする直前に実行され永続層(DB)に反映される。 そのため、一意制約違反などのエラーをトランザクション管理内の処理(Serviceの処理)でハンドリングしたい場合は、 saveAndFlush メソッドまたは flush メソッドを呼び出して EntityManager 内に蓄積されているEntityへの永続操作を強制的に実行する必要がある。 単にエラーをクライアントに通知するだけでよければ、Controllerで例外ハンドリングを行い適切なメッセージを設定すればよい。

saveAndFlushメソッドおよびflushメソッドはJPA依存のメソッドなので、意図なく使用しないように注意すること。

• 通常のフロー

Picture - Normal sequence of persistence processing

• flush時のフロー

Picture - Sequence of persistence processing when use flush method

Note

永続操作の反映タイミングについて(その２)

以下のメソッドを呼び出した場合、EntityManagerと、永続層(DB)で管理しているデータの不整合が発生しないようにするために、 メインの処理が行われる前に EntityManager に蓄積されているEntityへの永続操作が永続層(DB)に反映される。

• List<T> findAll 系メソッド
• boolean exists(ID id)
• long count()

上記のメソッドは、永続層(DB)に直接Queryを発行するため、 メインの処理が行われる前に永続層(DB)に反映されないとデータの不整合が発生することになる。 後述するQueryメソッドを呼び出した際も、 EntityManager に蓄積されていたEntityへの永続操作が、永続層(DB)に反映されるトリガーとなる。

• Query発行時のフロー

Picture - Sequence of persistence processing when use query method

5.2.2.3.2. 必要なメソッドのみ定義したインタフェースを継承する

Spring Dataから提供されているインタフェースに定義されているメソッドの中から、必要なメソッドのみ定義した共通インタフェースを 作成し継承する事でEntity毎のRepositoryインタフェースを作成する方法について説明する。

メソッドのシグネチャをSpring Dataから提供されているRepositoryインタフェースのメソッドと一致させる必要があるが、Spring Data提供の Repositoryインタフェースを継承して作成した際と同様、メソッドの実装は不要である。

Note

想定される適用ケース

Spring Dataから提供されているRepositoryインタフェースのメソッドの中には、実際のアプリケーションでは使用しないまたは使用しない方がよいメソッドもある。 そのようなメソッドをRepositoryインタフェースから削除したい場合は、この方法で作成する。 インタフェースに定義したメソッドの実装は、Spring Data JPAより提供されているorg.springframework.data.jpa.repository.support.SimpleJpaRepositoryで行われている。

以下に、作成例を示す。

public interface MyProjectRepository<T, ID extends Serializable> extends
        Repository<T, ID> { // (1)

    T findOne(ID id); // (2)

    T save(T entity); // (2)

    // ...

}

public interface OrderRepository extends MyProjectRepository<Order, Integer> { // (3)

}

項番	説明
(1)	org.springframework.data.repository.Repository を継承しプロジェクト用の汎用インタフェースを作成する。 汎用インタフェースなので、ジェネリック型を使用する。
(2)	Spring Dataから提供されているRepositoryインタフェースのメソッドの中から必要なメソッドを選んで定義する。
(3)	プロジェクト用の汎用インタフェースを継承し、ジェネリック型 <T> にEntityの型、ジェネリック型 <ID extends Serializable> にEntityのIDの型を指定する。例では、EntityにOrder型、EntityのIDにInteger型を指定している。

5.2.2.3.3. インタフェースの継承は行わない

Spring Dataより提供されているインタフェースや共通インタフェースを継承しないで、Entity毎のRepositoryインタフェースを作成する方法について、説明する。

Note

想定される適用ケース

共通的なEntityの操作が必要ない場合は、この方法で作成してもよい。 Spring Dataから提供されているRepositoryインタフェースに定義されているメソッドと同じシグネチャのメソッドの実装は、Spring Data JPAより提供されているorg.springframework.data.jpa.repository.support.SimpleJpaRepository で行われている。

以下に、作成例を示す。

@RepositoryDefinition(domainClass = Order.class, idClass = Integer.class) // (1)
public interface OrderRepository { //(2)

    Order findOne(Integer id); // (3)

    Order save(Order entity); // (3)

    // ...
}

項番	説明
(1)	@RepositoryDefinition アノテーションを指定する。 例では、domainClass属性(Entityの型)にOrder型、idClass属性(EntityのIDの型)にInteger型を指定している。
(2)	Spring Dataから提供されているインタフェース(org.springframework.data.repository.Repository)の継承は不要である。
(3)	Entity毎に必要なメソッドを定義する。

5.2.2.4.1. Queryメソッドを定義する

Queryメソッドは、Entity毎のRepositoryインタフェースのメソッドとして定義する。

public interface OrderRepository extends JpaRepository<Order, Integer> {
    List<Order> findByStatusCode(String statusCode);
}

5.2.2.4.2. 実行するQueryを指定する

項番	Queryの指定方法	説明
	@Query アノテーション (Spring Dataの機能)	Entity毎のRepositoryインタフェースに追加したメソッドに @org.springframework.data.jpa.repository.Query アノテーションを指定し、実行するQueryを指定する。 特に理由がない場合は、この方法で指定することを推奨する。
	命名規約ベースのメソッド名 (Spring Dataの機能)	Spring Dataが定めた命名規約に則りメソッド名を付与することで実行するQueryを指定する。 Spring Data JPAの機能によってメソッド名から実行するQuery(JPQL)が生成される。生成できるJPQLはSELECTのみとなっている。 条件が少なくシンプルなQueryの場合は、 @Query アノテーションを使わずにこの方法を使ってもよい。 ただし、条件が多く複雑なQueryの場合は、メソッド名は振る舞いを表すシンプルな名前にして @Query アノテーションでQueryを指定すること。
	プロパティファイルのNamed query (Spring Dataの機能)	Spring Data JPAから提供されているプロパティファイルに実行するQueryを指定する。 メソッド定義とQuery指定を行う箇所が分離してしまうので、基本的にはこの方法での指定は推奨しない。 ただし、QueryとしてNativeなSQLを使用する場合は、データベースに依存するSQLをプロパティファイルに定義する必要があるか確認すること。 使用するデータベースを任意に選択できるアプリケーションや、実行環境によって用意できるデータベースが変わる(変わる可能性がある)場合には、この方法でQueryを指定し、プロパティファイルを環境依存資材として管理する必要がある。

Note

Query指定方法の併用について

複数のQueryの指定方法を併用することに対して、特に制限は設けない。プロジェクトで使用する指定方法や併用の制限については、プロジェクト毎に判断すること。

Note

QueryのLookup方法について

Spring Dataデフォルトの動作は、 CREATE_IF_NOT_FOUND に設定されているため、以下の動作となる。

1. @Query アノテーションに指定されているQueryを取得し、指定があればそのQueryを使用する。
2. Named queryから対応するQueryを取得し、対応するQueryが見つかった場合はそのQueryを使用する。
3. メソッド名からQuery(JPQL)を作成して使用する。
4. メソッド名からQuery(JPQL)が作成できない場合は、エラーとなる。

QueryのLookup方法の詳細については、 Spring Data JPA - Reference Documentation「1.2.2 Defining query methods」の 「Query lookup strategies」を参照されたい。

5.2.2.4.3. Entityのロックを取得する

@Query(value = "SELECT o FROM Order o WHERE o.status.code = :statusCode ORDER BY o.id DESC")
@Lock(LockModeType.PESSIMISTIC_WRITE) // (1)
List<Order> findByStatusCode(@Param("statusCode") String statusCode);

-- (2) statusCode='accepted'
SELECT
        order0_.id AS id1_5_
        ,order0_.status_code AS status2_5_
    FROM
        t_order order0_
    WHERE
        order0_.status_code = 'accepted'
    ORDER BY
        order0_.id DESC
    FOR UPDATE

項番	説明
(1)	@Lock アノテーションのvalue属性にロックモードを指定する。 指定可能なロックモードについては、Java Platform, Enterprise Edition API Specificationを参照されたい。
(2)	JPQLから変換されたNativeなSQL。(使用DBはPostgreSQL) 例では、LockModeType.PESSIMISTIC_WRITE を指定しているので、SQLに”FOR UPDATE”句が追加される。

5.2.2.4.4. 永続層のEntityを直接操作する

Note

性能劣化の要因軽減

永続層のEntityを直接操作することで、Entityの操作を行うためのSQLの発行回数を減らすことができる。 そのため、高い性能要件があるアプリケーションの場合は、この方法でEntityの一括操作を行うことで、性能劣化の要因を減らす事ができる。 減らすことが出来るSQLは以下の通り。

• EntityオブジェクトをEntityManager上に読み込むためのSQL。発行が不要となる。
• Entityを更新および削除するためのSQL。n回の発行が必要だったものが1回の発行で済む。

Note

永続層のEntityを直接操作するかの判断基準について

永続層のEntityを直接操作する場合、機能的な注意点がいくつかあるため、 性能要件が高くないアプリケーションの場合は、 一括操作についても EntityManager 上で管理されているEntityオブジェクトに対して行うことを推奨する。 具体的な注意点については、実装例を参照されたい。

以下に、Queryメソッドを使って、永続層のEntityを直接操作する実装例を示す。

@Modifying // (1)
@Query("UPDATE OrderItem oi SET oi.logicalDelete = true WHERE oi.id.orderId = :orderId ") // (2)
int updateToLogicalDelete(@Param("orderId") Integer orderId); // (3)

項番	説明
(1)	更新系のQueryメソッドであることを示す @org.springframework.data.jpa.repository.Modifying アノテーションを指定する。 指定しないと実行時にエラーとなる。
(2)	更新系(UPDATEまたはDELETE)用のQueryを指定する。
(3)	更新件数や削除件数が必要な場合は、int または java.lang.Integer を戻り値の型として指定し、件数が必要ない場合は、 void を指定する。

Warning

EntityManager上で管理しているEntityとの整合性について

Queryメソッドを使って永続層のEntityを直接操作した場合、Spring Data JPAのデフォルト動作ではEntityManager上で管理されているEntityに反映されない。 そのため、直後に JpaRepository#findOne(ID) メソッドを呼び出して取得されるEntityオブジェクトは、操作前の状態である点に注意すること。

この動作を回避する方法として、 @Modifying アノテーションのclearAutomatically属性を true に指定する方法がある。 clearAutomatically属性に true を指定した場合、永続層のEntityを直接操作した後に、 EntityManager の clear() メソッドが呼び出され、EntityManager 上で管理されていたEntityオブジェクトと蓄積されていた永続操作が EntityManager 上から破棄される。 そのため、直後に JpaRepository#findOne(ID) メソッドを呼び出した場合、永続層から最新状態のEntityが取得され、永続層とEntityManager の状態が同期される仕組みになっている。

Warning

@Modifying(clearAutomatically = true) 使用時の注意点

@Modifying(clearAutomatically = true) とすることで、蓄積されていた永続操作(INSERT/UPDATE/DELETE)も EntityManager 上から破棄されてしまうという点に注意が必要となる。 これは、必要な永続操作が永続層に反映されない可能性がある事を意味するため、バグを引き起こす要因となりうる。

この問題を回避するためには、 永続層のEntityを直接操作する前に JpaRepository#saveAndFlush(T entity) または JpaRepository#flush() メソッドを呼び出し、蓄積されている永続操作を永続層に反映しておく必要がある。

5.2.2.4.5. Queryヒントを設定する

Queryにヒントを設定する必要がある場合は、Queryメソッドに @org.springframework.data.jpa.repository.QueryHints アノテーションを追加し、 value属性にQueryヒント( @javax.persistence.QueryHint )を指定する。

@Query(value = "SELECT o FROM Order o WHERE o.status.code = :statusCode ORDER BY o.id DESC")
@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(value = { @QueryHint(name = "javax.persistence.lock.timeout", value = "0") }) // (1)
List<Order> findByStatusCode(@Param("statusCode") String statusCode);

項番	説明
(1)	@QueryHint アノテーションのname属性にヒント名、value属性にヒント値を設定する。 指定できるヒントは、JPAの仕様で決められているものに加え、プロバイダ固有のものがある。 上記例では、ロックタイムアウトを 0 に設定している(使用DBはPostgreSQL)。SQLに”FOR UPDATE NOWAIT”句が追加される。

Note

Hibernateで指定できるQueryヒントについて

JPA仕様で決められているQueryヒントは以下の通り。 詳細は、JSR 317: Java Persistence API, Version 2.0のSpecification(PDF)を参照されたい。

• javax.persistence.query.timeout
• javax.persistence.lock.timeout
• javax.persistence.cache.retrieveMode
• javax.persistence.cache.storeMode

Hibernate固有のQueryヒントについては、 Hibernate EntityManager User guideの「3.4.1.8. Query hints」を参照されたい。

5.2.2.5.1. @Query アノテーションで指定する

@Query アノテーションのvalue属性に実行するQuery(JPQL)を指定する。

@Query(value = "SELECT o FROM Order o WHERE o.status.code = :statusCode ORDER BY o.id DESC") // (1)
List<Order> findByStatusCode(@Param("statusCode") String statusCode);

-- (2) statusCode='accepted'
SELECT
        order0_.id AS id1_5_
        ,order0_.status_code AS status2_5_
    FROM
        t_order order0_
    WHERE
        order0_.status_code = 'accepted'
    ORDER BY
        order0_.id DESC

項番	説明
(1)	@Query アノテーションのvalue属性に実行するQuery(JPQL)を指定する。 上記例では、Order オブジェクトで保持している status プロパティ( OrderStatus 型)の code プロパティ( String 型) の値が指定したパラメータ値( statusCode )と一致する Order オブジェクトを id プロパティの降順に並べて取得するためのQueryを指定している。
(2)	JPQLから変換されたNativeなSQL。@Query アノテーションのvalue属性に指定したQuery(JPQL)は、使用するデータベースのNativeなSQLに変換され実行される。

Note

JPQLではなくNativeなSQLを直接指定する方法

QueryとしてJPQLではなくNativeなSQLを直接指定したい場合は、 nativeQuery属性を true に設定することで指定可能となる。 基本的にはJPQLを使用する事を推奨するが、JPQLで表現できないQueryを発行する必要がある場合はNativeなSQLを直接指定してもよい。 データベースに依存するSQLを指定する場合は、SQLをプロパティファイルに定義することを検討すること。

SQLをプロパティファイルに定義する方法については、「プロパティファイルにNamed queryとして指定する」を参照されたい。

Note

Named Parametersについて

Queryにバインドするパラメータに対して名前を付与し、Query内からはパラメータ名を指定することで値をバインドすることができる。 Named Parameterを使用する場合は、 @org.springframework.data.repository.query.Param アノテーションを対象とする引数に追加し、value属性にパラメータ名を指定する。 Queryでは、バインドしたい位置に「:パラメータ名」の形式で指定する。

特に理由がない場合は、 Qyeryのメンテナンス性と可読性を考慮し、Named Parametersを使用することを推奨する。

項番	一致方法	形式	具体例
	前方一致	:parameterName% or ?n%	SELECT a FROM Account WHERE a.firstName LIKE :firstName% SELECT a FROM Account WHERE a.firstName LIKE ?1%
	後方一致	%:parameterName or %?n	SELECT a FROM Account WHERE a.firstName LIKE %:firstName SELECT a FROM Account WHERE a.firstName LIKE %?1
	部分一致	%:parameterName% or %?n%	SELECT a FROM Account WHERE a.firstName LIKE %:firstName% SELECT a FROM Account WHERE a.firstName LIKE %?1%

Note

LIKE検索時のエスケープについて

LIKE検索を行う場合は、検索条件となる値をLIKE検索用にエスケープする必要がある。

org.terasoluna.gfw.common.query.QueryEscapeUtils クラスにエスケープするためのメソッドが用意されているため、要件を充たせる場合は使用を検討すること。 QueryEscapeUtils クラスの詳細については、「データベースアクセス（共通編）」の「LIKE検索時のエスケープについて」を参照されたい。

Note

一致方法を動的に変化させる必要がある場合

一致方法(前方一致、後方一致、部分一致)を動的に変化させる必要がある場合は、 JPQL内に % を指定するのではなく、従来通りバインドするパラメータ値の前後に "%" を追加すること。

org.terasoluna.gfw.common.query.QueryEscapeUtils クラスに一致方法に対応する検索条件値に変換するメソッドが用意されているため、 要件を充たせる場合は、使用を検討すること。 QueryEscapeUtils クラスの詳細については、「データベースアクセス（共通編）」の「LIKE検索時のエスケープについて」を参照されたい。

// (1)
@Query(value = "SELECT o FROM Order o WHERE o.status.code = :statusCode ORDER BY o.id DESC")
Page<Order> findByStatusCode(@Param("statusCode") String statusCode, Pageable pageable);

項番	説明
(1)	Queryに "ORDER BY" を指定する。降順にする場合は DESC を、昇順にする場合は ASC を指定する。DESC/ASCを省略した場合は、 ASC が適用される。

• Controller

@RequestMapping("list")
public String list(@PageableDefault(
                        size=5,
                        sort = "id", // (1)
                        direction = Direction.DESC // (1)
                        ) Pageable pageable,
                          Model model) {
    Page<Order> orderPage = orderService.getOrders(pageable); // (2)
    model.addAttribute("orderPage", orderPage);
    return "order/list";
}

項番	説明
(1)	ソート条件を指定する。 Pageable#getSort() メソッドで取得できる Sort オブジェクトにソート条件が設定される。 上記例では、 idフィールドの降順をソート条件として指定している。
(2)	Pageable オブジェクトを指定してServiceのメソッドを呼び出す。

• Service (Caller)

public String getOrders(Pageable pageable){
    return orderRepository.findByStatusCode("accepted", pageable); // (3)
}

項番	説明
(3)	Controllerから渡された Pageable オブジェクトを指定してRepositoryのメソッドを呼び出す。

• Repositoryインタフェース

@Query(value = "SELECT o FROM Order o WHERE o.status.code = :statusCode") // (4)
Page<Order> findByStatusCode(@Param("statusCode") String statusCode, Pageable pageable);

-- (5) statusCode='accepted'
SELECT
        COUNT(order0_.id) AS col_0_0_
    FROM
        t_order order0_
    WHERE
        order0_.status_code = 'accepted'

-- (6) statusCode='accepted'
SELECT
        order0_.id AS id1_5_
        ,order0_.status_code AS status2_5_
    FROM
        t_order order0_
    WHERE
        order0_.status_code = 'accepted'
    ORDER BY
        order0_.id DESC
    LIMIT 5

項番	説明
(4)	Queryに”ORDER BY”句の指定は行わない。countQuery属性の指定も不要。
(5)	JPQLから変換された件数カウント用のNativeなSQL。
(6)	JPQLから変換された指定されたページ位置のEntityを取得するためのNativeなSQL。 Queryに指定はしていないが、Pageableオブジェクト内に保持している Sort オブジェクトに指定した条件で”ORDER BY”句が追加される。例では、PostgreSQL用のSQLになっている。

5.2.2.5.2. 命名規約ベースのメソッド名で指定する

メソッド名からJPQLを生成するための命名規約などのルールについては、以下のページを参照されたい。

項番	参照ページ	説明
	Spring Data JPA - Reference Documentation「1.2.2 Defining query methods」の「Query creation」	Distinct、ORDER BY、Case insensitiveの指定方法などが記載されている。
	Spring Data JPA - Reference Documentation「1.2.2 Defining query methods」の「Property expressions」	ネストされたEntityのプロパティを条件に指定する方法などが記載されている。
	Spring Data JPA - Reference Documentation「1.2.2 Defining query methods」の「Special parameter handling」	特別なメソッド引数(Pageable 、 Sort)についての説明が記載されている。
	Spring Data JPA - Reference Documentation「2.2.2. Query creation」	JPQLを組み立てるための命名規約(キーワード)に関する説明が記載されている。
	Spring Data JPA - Reference Documentation「Appendix B. Repository query keywords」	JPQLを組み立てるための命名規約(キーワード)に関する説明が記載されている。

以下に、実装例を示す。

• OrderRepositry.java

Page<Order> findByStatusCode(String statusCode, Pageable pageable); // (1)

項番	説明
(1)	メソッド名が ^(find|read|get).*By(.+) のパターンに一致する場合、メソッド名からJPQLを生成する対象のメソッドとなる。 (.+) の部分に条件となるEntityのプロパティや操作を示すキーワードを指定する。 例では、Order オブジェクトで保持している status プロパティ( OrderStatus 型)の code プロパティ( String 型) の値が指定したパラメータ値( statusCode )と一致する Order オブジェクトをページ形式で取得している。

• 件数カウント用Query

-- (2) JPQL
SELECT
        COUNT(*)
    FROM
        ORDER AS generatedAlias0
            LEFT JOIN generatedAlias0.status AS generatedAlias1
        WHERE
            generatedAlias1.code = ?1

-- (3) SQL statusCode='accepted'
SELECT
        COUNT(*) AS col_0_0_
    FROM
        t_order order0_
            LEFT OUTER JOIN c_order_status orderstatu1_
                ON order0_.status_code = orderstatu1_.code
    WHERE
        orderstatu1_.code = 'accepted'

項番	説明
(2)	メソッド名から生成された件数カウント用のJPQLのQuery。
(3)	(2)のJPQLから変換された件数カウント用のNativeなSQL。

• Entity取得用Query

-- (4) JPQL
SELECT
        generatedAlias0
    FROM
        ORDER AS generatedAlias0
            LEFT JOIN generatedAlias0.status AS generatedAlias1
        WHERE
            generatedAlias1.code = ?1
        ORDER BY
            generatedAlias0.id DESC;

-- (5) statusCode='accepted'
SELECT
        order0_.id AS id1_5_
        ,order0_.status_code AS status2_5_
    FROM
        t_order order0_
            LEFT OUTER JOIN c_order_status orderstatu1_
                ON order0_.status_code = orderstatu1_.code
    WHERE
        orderstatu1_.code = 'accepted'
    ORDER BY
        order0_.id DESC
    LIMIT 5

項番	説明
(4)	メソッド名から生成されたEntity取得用のJPQLのQuery。
(5)	(4)のJPQLから変換されたEntity取得用のNativeなSQL。

5.2.2.5.3. プロパティファイルにNamed queryとして指定する

Spring Data JPAから提供されているプロパティファイル(classpath:META-INF/jpa-named-queries.properties)に、実行するQueryを指定する。

• OrderRepositry.java

@Query(nativeQuery = true)
List<Order> findAllByStatusCode(@Param("statusCode") String statusCode); // (1)

項番	説明
(1)	Named queryのLookup名は、Entityのクラス名とメソッド名を "." (dot) で連結したものが使用される。 上記例だと、 "Order.findAllByStatusCode" がLookup名となる。

Tip

Named queryのLookup名を指定する方法

デフォルトの動作では、Entityのクラス名とメソッド名を "." (dot) で連結したものがLookup名として使用されるが、任意のクエリ名を指定することも出来る。

• Entity取得用のLookup名に任意のクエリ名を指定したい場合は、 @Query アノテーションのname属性にクエリ名を指定する。
• ページ検索時の件数カウント用のLookup名に任意のクエリ名を指定したい場合は、 @Query アノテーションのcountName属性にクエリ名を指定する。

@Query(name = "OrderRepository.findAllByStatusCode", nativeQuery = true) // (2)
List<Order> findAllByStatusCode(@Param("statusCode") String statusCode);

項番	説明
(2)	上記例では、"OrderRepository.findAllByStatusCode" をLookup用のクエリ名として指定している。

• jpa-named-queries.properties

# (3)
Order.findAllByStatusCode=SELECT * FROM order WHERE status_code = :statusCode

項番	説明
(3)	クエリー名をキーとして、実行するSQLを指定する。 上記例では、"Order.findAllByStatusCode" をキーに、実行するSQLを指定している。

Tip

Spring Data JPAから提供されているプロパティファイルではなく、任意のプロパティファイルにNamed Queryを指定する方法を以下に紹介する。

• xxx-infra.xml

<!-- (4) -->
<jpa:repositories base-package="xxxxxx.yyyyyy.zzzzzz.domain.repository"
    named-queries-location="classpath:META-INF/jpa/jpa-named-queries.properties" />

項番	説明
(4)	<jpa:repositories>要素のnamed-queries-location属性に、任意のプロパティファイルを指定する。 上記例では、クラスパス上にあるMETA-INF/jpa/jpa-named-queries.propertiesが使用される。

5.2.2.6.1. 条件に一致するEntityを全件検索

条件に一致するEntityを全件取得するQueryメソッドを呼び出す。

• Repositroyインタフェース

public interface AccountRepository extends JpaRepository<Account, String> {

    // (1)
    @Query("SELECT a FROM Account a WHERE :createdDateFrom <= a.createdDate AND a.createdDate < :createdDateTo ORDER BY a.createdDate DESC")
    List<Account> findByCreatedDate(
            @Param("createdDateFrom") Date createdDateFrom,
            @Param("createdDateTo") Date createdDateTo);

}

項番	説明
(1)	java.util.List インタフェースを返却するQueryメソッドを定義する。

• Service

public List<Account> getAccounts(Date targetDate) {
    DateMidnight targetDateMidnight = new DateMidnight(targetDate);
    Date fromDate = targetDateMidnight.toDate();
    Date toDate = targetDateMidnight.dayOfYear().addToCopy(1).toDate();

    // (2)
    List<Account> accounts = accountRepository.findByCreatedDate(fromDate,
            toDate);
    if (accounts.isEmpty()) { // (3)
        // ...
    }
    return accounts;
}

項番	説明
(2)	Repositryインタフェースに実装したQueryメソッドを呼び出す。
(3)	検索結果が0件の場合は、空のリストが返却される。nullは返却されないのでnullチェックは不要。 必要に応じて、検索結果が0件の場合の処理を実装する。

5.2.2.6.2. 条件に一致するEntityのページ検索

条件に一致するEntityの中から指定ページに該当するEntityを取得するQueryメソッドを呼び出す。

• Repositroyインタフェース

public interface AccountRepository extends JpaRepository<Account, String> {

    // (1)
    @Query("SELECT a FROM Account a WHERE :createdDateFrom <= a.createdDate AND a.createdDate < :createdDateTo")
    Page<Account> findByCreatedDate(
            @Param("createdDateFrom") Date createdDateFrom,
            @Param("createdDateTo") Date createdDateTo, Pageable pageable);

}

項番	説明
(1)	引数として org.springframework.data.domain.Pageable インタフェースを受け取り、 org.springframework.data.domain.Page インタフェースを返却するQueryメソッドを定義する。

• Controller

@RequestMapping("list")
public String list(@RequestParam("targetDate") Date targetDate,
                   @PageableDefaults(
                       pageNumber = 0,
                       value = 5,
                       sort = { "createdDate" },
                       sortDir = Direction.DESC)
                       Pageable pageable, // (2)
                   Model model) {
    Page<Order> accountPage = accountService.getAccounts(targetDate, pageable);
    model.addAttribute("accountPage", accountPage);
    return "account/list";
}

項番	説明
(2)	Spring Dataより提供されているページング検索用のオブジェクト（ org.springframework.data.domain.Pageable ）を生成する。 詳細は「ページネーション」を参照されたい。

• Service

public Page<Account> getAccounts(Date targetDate ,Pageable pageable) {

    DateMidnight targetDateMidnight = new DateMidnight(targetDate);
    Date fromDate = targetDateMidnight.toDate();
    Date toDate = targetDateMidnight.dayOfYear().addToCopy(1).toDate();

    // (3)
    Page<Account> page = accountRepository.findByCreatedDate(fromDate,
            toDate, pageable);
    if (!page.hasContent()) { // (4)
        // ...
    }
    return page;
}

項番	説明
(3)	Repositryインタフェースに実装したQueryメソッドを呼び出す。
(4)	検索結果が0件の場合は、Page オブジェクトに空のリストが設定され、 Page#hasContent() メソッドの返り値が false になる。 必要に応じて、検索結果が0件の場合の処理を実装する。

5.2.2.7.1. 動的条件に一致するEntityを全件検索

動的条件に一致するEntityを全件取得するQueryメソッドを実装し、呼び出す。

以下の実装例を示す。

実装例では、動的条件として、

• 注文ID
• 商品名
• 注文状態(複数指定可能)

を指定可能とし、指定された条件に一致する注文をAND条件で絞り込む検索とする。 なお、条件の指定がない場合は、検索は行わず空のリストを返却する。

• Criteria (JavaBean)

public class OrderCriteria implements Serializable { // (1)

    private Integer id;

    private String itemName;

    private List<String> statusCodes;

    // ...

}

項番	説明
(1)	検索条件を保持するCriteriaオブジェクト(JavaBean)を作成する。

• カスタムRepositoryインタフェース

public interface OrderRepositoryCustom {

    Page<Order> findAllByCriteria(OrderCriteria criteria); // (2)

}

項番	説明
(2)	カスタムRepositoryインタフェースに、Criteriaオブジェクトを引数にとり、Listを返却するメソッドを定義する。

• カスタムRepositoryクラス

public class OrderRepositoryImpl implements OrderRepositoryCustom { // (3)

    @PersistenceContext
    EntityManager entityManager; // (4)

    public List<Order> findAllByCriteria(OrderCriteria criteria) { // (5)

        // Collect dynamic conditions.
        // (6)
        final List<String> andConditions = new ArrayList<String>();
        final List<String> joinConditions = new ArrayList<String>();
        final Map<String, Object> bindParameters = new HashMap<String, Object>();

        // (7)
        if (criteria.getId() != null) {
            andConditions.add("o.id = :id");
            bindParameters.put("id", criteria.getId());
        }
        if (!CollectionUtils.isEmpty(criteria.getStatusCodes())) {
            andConditions.add("o.status.code IN :statusCodes");
            bindParameters.put("statusCodes", criteria.getStatusCodes());
        }
        if (StringUtils.hasLength(criteria.getItemName())) {
            joinConditions.add("o.orderItems oi");
            joinConditions.add("oi.item i");
            andConditions.add("i.name LIKE :itemName ESCAPE '~'");
            bindParameters.put("itemName", SqlUtils
                    .toLikeCondition(criteria.getItemName()));
        }

        // (8)
        if (andConditions.isEmpty()) {
            return Collections.emptyList();
        }

        // (9)
        // Create dynamic query.
        final StringBuilder queryString = new StringBuilder();

        // (10)
        queryString.append("SELECT o FROM Order o");

        // (11)
        // add join conditions.
        for (String joinCondition : joinConditions) {
            queryString.append(" LEFT JOIN ").append(joinCondition);
        }
        // add conditions.
        Iterator<String> andConditionsIt = andConditions.iterator();
        if (andConditionsIt.hasNext()) {
            queryString.append(" WHERE ").append(andConditionsIt.next());
        }
        while (andConditionsIt.hasNext()) {
            queryString.append(" AND ").append(andConditionsIt.next());
        }

        // (12)
        // add order by condition.
        queryString.append(" ORDER BY o.id");

        // (13)
        // Create typed query.
        final TypedQuery<Order> findQuery = entityManager.createQuery(
                queryString.toString(), Order.class);
        // Bind parameters.
        for (Map.Entry<String, Object> bindParameter : bindParameters
                .entrySet()) {
            findQuery.setParameter(bindParameter.getKey(), bindParameter
                    .getValue());
        }

        // (14)
        // Execute query.
        return findQuery.getResultList();

    }

}

項番	説明
(3)	カスタムRepositoryインタフェースの実装クラスを作成する。
(4)	EntityManager をInjectする。 @javax.persistence.PersistenceContext アノテーションを使用してInjectすること。
(5)	動的条件に一致するEntityを全件取得するQueryメソッドを実装する。 上記実装例では説明のためにメソッド分割はしていないが、必要に応じてメソッド分割すること。
(6)	動的クエリを組み立てるための変数（AND条件用リスト、結合条件用リスト、バインドパラメータ用マップ）を定義している。 OrderCriteriaオブジェクトに条件の指定があるものについて、これらの変数に必要な情報を設定する。
(7)	OrderCriteriaオブジェクトに条件の指定があるか判定し、動的クエリを組み立てるために必要な情報を設定していく。 上記例では、id は指定した値と完全一致するもの、 statusCodes は指定したリストに含まれるもの、 itemName は指定した値と前方一致するものを取得対象とするための情報を設定している。 itemName については、比較対象の値を保持する関連Entityが複雑なネスト関係になっているため、関連EntityをJOINする必要がある。
(8)	上記実装例では条件が指定されていない場合は、検索する必要がないため、空のリストを返却する。
(9)	条件が指定されている場合は、Entityを検索するためのQueryを組み立てる。 上記例では実行するQueryを java.lang.StringBuilder クラスを使って組み立てる実装例となっている。
(10)	静的なQuery要素を組み立てる。 上記例では、SELECT句とFROM句は静的なQueryの構成要素として組み立てている。
(11)	動的なQuery要素を組み立てる。 上記例では、結合条件用リスト(JOIN句)とAND条件用リスト(WHERE句)に設定する条件を動的なQuery要素として組み立てている。
(12)	静的なQuery要素を組み立てる。 上記例では、ORDER BY句は静的なQuery要素として組み立てている。
(13)	動的に組み立てたQuery文字列を javax.persistence.TypedQuery に変換し、Query実行に必要なバインド用のパラメータを設定する。
(14)	動的に組み立てたQueryを実行し、条件に一致するEntityを全件取得する。

• Entity毎のRepositoryインタフェース

public interface OrderRepository extends JpaRepository<Order, Integer>,
                                OrderRepositoryCustom { // (15)
    // ...
}

項番	説明
(15)	Entity毎のRepositoryインタフェースに、カスタムRepositoryインタフェースを継承する。

• Service (Caller)

// condition values for sample.
Integer conditionValueOfId = 4;
List<String> conditionValueOfStatusCodes = Arrays.asList("accepted");
String conditionValueOfItemName = "Wat";

// implementation of sample.
// (16)
OrderCriteria criteria = new OrderCriteria();
criteria.setId(conditionValueOfId);
criteria.setStatusCodes(conditionValueOfStatusCodes);
criteria.setItemName(conditionValueOfItemName);
List<Order> orders = orderRepository.findAllByCriteria(criteria); // (17)
if (orders.isEmpty()) { // (18)
    // ...
}

項番	説明
(16)	OrderCriteriaオブジェクトに検索条件を指定する。
(17)	OrderCriteriaオブジェクトを引数として、動的条件に一致するEntityを全件取得するQueryメソッドを呼び出す。
(18)	必要に応じて検索結果を判定し、0件の場合の処理を行う。

• 実行されるJPQL(SQL)

-- (19)
--   conditionValueOfId=4
--   conditionValueOfStatusCodes = ["accepted"]
--   conditionValueOfItemName = "Wat"

-- JPQL
SELECT
        o
    FROM
        ORDER o
            JOIN o.orderItems oi
                JOIN oi.item i
            WHERE
                o.id = :id
                AND o.status.code IN :statusCodes
                AND i.name LIKE :itemName ESCAPE '~'
            ORDER BY
                o.id

-- SQL
SELECT
        order0_.id AS id1_6_
        ,order0_.created_by AS created2_6_
        ,order0_.created_date AS created3_6_
        ,order0_.last_modified_by AS last4_6_
        ,order0_.last_modified_date AS last5_6_
        ,order0_.status_code AS status6_6_
    FROM
        t_order order0_ INNER JOIN t_order_item orderitems1_
            ON order0_.id = orderitems1_.order_id INNER JOIN m_item item2_
            ON orderitems1_.item_code = item2_.code
WHERE
    order0_.id = 4
    AND (
        order0_.status_code IN ('accepted')
    )
    AND (
        item2_.name LIKE 'Wat%' ESCAPE '~'
    )
ORDER BY
    order0_.id

項番	説明
(19)	すべての条件を指定した場合に発行されるJPQLとSQLの例。

-- (20)
--   conditionValueOfId=4
--   conditionValueOfStatusCodes = ["accepted"]
--   conditionValueOfItemName = ""
-- JPQL
SELECT
        o
    FROM
        ORDER o
    WHERE
        o.id = :id
        AND o.status.code IN :statusCodes
    ORDER BY
        o.id

-- SQL
SELECT
        order0_.id AS id1_6_
        ,order0_.created_by AS created2_6_
        ,order0_.created_date AS created3_6_
        ,order0_.last_modified_by AS last4_6_
        ,order0_.last_modified_date AS last5_6_
        ,order0_.status_code AS status6_6_
    FROM
        t_order order0_
    WHERE
        order0_.id = 4
        AND (
            order0_.status_code IN ('accepted')
        )
    ORDER BY
        order0_.id;

項番	説明
(20)	iteName 以外の条件を指定した場合に発行されるJPQLとSQLの例。

-- (21)
--   conditionValueOfId=4
--   conditionValueOfStatusCodes = []
--   conditionValueOfItemName = ""
-- JPQL
SELECT
        o
    FROM
        ORDER o
    WHERE
        o.id = :id
    ORDER BY
        o.id

-- SQL
SELECT
        order0_.id AS id1_6_
        ,order0_.created_by AS created2_6_
        ,order0_.created_date AS created3_6_
        ,order0_.last_modified_by AS last4_6_
        ,order0_.last_modified_date AS last5_6_
        ,order0_.status_code AS status6_6_
    FROM
        t_order order0_
    WHERE
        order0_.id = 4
    ORDER BY
        order0_.id;

項番	説明
(21)	id のみを指定した場合に発行されるJPQLとSQLの例。

5.2.2.7.2. 動的条件に一致するEntityをページ検索

動的条件に一致するEntityの中から指定ページに該当するEntityを取得するQueryメソッドを実装し、呼び出す。

以下に実装例を示すが、該当ページを取得する箇所以外は、全件取得する場合と同じ仕様とする。 なお、全件取得で説明した箇所の説明は省略する。

• カスタムRepositoryインタフェース

public interface OrderRepositoryCustom {

    Page<Order> findPageByCriteria(OrderCriteria criteria, Pageable pageable); // (1)

}

項番	説明
(1)	動的条件に一致するEntityの中から指定ページに該当するEntityを取得するQueryメソッドを定義する。

• カスタムRepositoryクラス

public class OrderRepositoryCustomImpl implements OrderRepositoryCustom {

    @PersistenceContext
    EntityManager entityManager;

    public Page<Order> findPageByCriteria(OrderCriteria criteria,
            Pageable pageable) { // (2)

        // collect dynamic conditions.
        final List<String> andConditions = new ArrayList<String>();
        final List<String> joinConditions = new ArrayList<String>();
        final Map<String, Object> bindParameters = new HashMap<String, Object>();

        if (criteria.getId() != null) {
            andConditions.add("o.id = :id");
            bindParameters.put("id", criteria.getId());
        }
        if (!CollectionUtils.isEmpty(criteria.getStatusCodes())) {
            andConditions.add("o.status.code IN :statusCodes");
            bindParameters.put("statusCodes", criteria.getStatusCodes());
        }
        if (StringUtils.hasLength(criteria.getItemName())) {
            joinConditions.add("o.orderItems oi");
            joinConditions.add("oi.item i");
            andConditions.add("i.name LIKE :itemName ESCAPE '~'");
            bindParameters.put("itemName", SqlUtils.toLikeCondition(criteria
                    .getItemName()));
        }

        if (andConditions.isEmpty()) {
            List<Order> orders = Collections.emptyList();
            return new PageImpl<Order>(orders, pageable, 0); // (3)
        }

        // create dynamic query.
        final StringBuilder queryString = new StringBuilder();
        final StringBuilder countQueryString = new StringBuilder(); // (4)
        final StringBuilder conditionsString = new StringBuilder(); // (4)

        queryString.append("SELECT o FROM Order o");
        countQueryString.append("SELECT COUNT(o) FROM Order o"); // (5)

        // add join conditions.
        for (String joinCondition : joinConditions) {
            conditionsString.append(" JOIN ").append(joinCondition);
        }

        // add conditions.
        Iterator<String> andConditionsIt = andConditions.iterator();
        if (andConditionsIt.hasNext()) {
            conditionsString.append(" WHERE ").append(andConditionsIt.next());
        }
        while (andConditionsIt.hasNext()) {
            conditionsString.append(" AND ").append(andConditionsIt.next());
        }
        queryString.append(conditionsString); // (6)
        countQueryString.append(conditionsString); // (6)

        // add order by condition.
        // (7)
        String orderByString = QueryUtils.applySorting("", pageable.getSort(), "o");
        queryString.append(orderByString);

        // create typed query.
        final TypedQuery<Long> countQuery = entityManager.createQuery(
                countQueryString.toString(), Long.class); // (8)

        final TypedQuery<Order> findQuery = entityManager.createQuery(
                queryString.toString(), Order.class);

        // bind parameters.
        for (Map.Entry<String, Object> bindParameter : bindParameters
                .entrySet()) {
            countQuery.setParameter(bindParameter.getKey(), bindParameter
                    .getValue()); // (8)
            findQuery.setParameter(bindParameter.getKey(), bindParameter
                    .getValue());
        }

        long total = countQuery.getSingleResult().longValue(); // (9)
        List<Order> orders = null;
        if (total != 0) { // (10)
            findQuery.setFirstResult(pageable.getOffset());
            findQuery.setMaxResults(pageable.getPageSize());
            // execute query.
            orders = findQuery.getResultList();
        } else { // (11)
            orders = Collections.emptyList();
        }

        return new PageImpl<Order>(orders, pageable, total); // (12)
    }

}

項番	説明
(2)	動的条件に一致するEntityの中から指定ページに該当するEntityを取得するQueryメソッドを実装する。 上記実装例では説明のためにメソッド分割はしていないが、必要に応じてメソッド分割すること。
(3)	上記実装例では条件が指定されていない場合は、検索する必要がないため、空のページ情報を返却する。
(4)	件数取得用のQueryを組み立てるための変数と、条件(結合条件とAND条件)を組み立てるための変数を用意する。 Entity取得用のQueryと件数取得用のQueryで同じ条件を使用する必要があるため、条件(結合条件とAND条件)を組み立てるための変数を用意している。
(5)	件数取得用Queryの静的なQuery要素を組み立てる。 上記例では、SELECT句とFROM句は静的なQueryの構成要素として組み立てている。
(6)	Entity取得用Queryと件数取得用Queryの動的なQuery要素を組み立てる。
(7)	Entity取得用Queryに対してソート条件(ORDER BY句)を動的なQuery要素として組み立てている。 ORDER BY句の組み立ては、 Spring Data JPAから提供されているユーティリティ部品( org.springframework.data.jpa.repository.query.QueryUtils )を使用している。
(8)	動的に組み立てた件数取得用のQuery文字列を javax.persistence.TypedQuery に変換し、Query実行に必要なバインド用のパラメータを設定する。
(9)	件数取得用のQueryを実行し、条件に一致する合計件数を取得する。
(10)	条件に一致するEntityが存在する場合は、Entity取得用Queryを実行し、該当ページの情報を取得する。 Entity取得用Queryを実行する際は、取得開始位置( TypedQuery#setFirstResult )と取得件数( TypedQuery#setMaxResults )を指定する。
(11)	条件に一致するEntityが存在しない場合は、空のリストを取得結果とする。
(12)	該当ページのEntityのリスト、ページ情報、条件に条件した合計件数を引数に指定して、 Page オブジェクトを生成し返却する。

• Service (Caller)

// condition values for sample.
Integer conditionValueOfId = 4;
List<String> conditionValueOfStatusCodes = Arrays.asList("accepted");
String conditionValueOfItemName = "Wat";

// implementation of sample.
OrderCriteria criteria = new OrderCriteria();
criteria.setId(conditionValueOfId);
criteria.setStatusCodes(conditionValueOfStatusCodes);
criteria.setItemName(conditionValueOfItemName);
Page<Order> orderPage = orderRepository.findPageByCriteria(criteria,
        pageable); // (13)
if (!orderPage.hasContent()) {
    // ...
}

項番	説明
(13)	動的条件に一致するEntityの中から指定ページに該当するEntityを取得するQueryメソッドを呼び出す。

5.2.2.8.1. IDを指定してEntityを1件取得

ID(Primary Key)がわかっている場合は、RepositryインタフェースのfindOneメソッドを呼び出してEntityオブジェクトを取得する。

public Account getAccount(String accountUuid) {
    Account account = accountRepository.findOne(accountUuid); // (1)
    if (account == null) { // (2)
        // ...
    }
    return account;
}

項番	説明
(1)	EntityのID(Primary Key)を指定して、RepositryインタフェースのfindOne(ID)メソッドを呼び出す。
(2)	指定したIDのEntityが存在しない場合は、返却値がnullになるので、null判定が必要となる。 必要に応じて、指定したIDのEntityが存在しない場合の処理を実装する。

Note

返却されるEntityオブジェクトについて

指定したIDのEntityオブジェクトが、既に EntityManager 上で管理されている場合は、永続層(DB)へのアクセスは行われずに、 EntityManager 上で管理されているEntityオブジェクトが返却される。 そのため、 findOneメソッドを使用すると、永続層への無駄なアクセスを抑えることが出来る。

Note

関連Entityのロードタイミングについて

Query実行時の関連Entityのロードは、Entityの関連付けアノテーション( @javax.persistence.OneToOne 、 @javax.persistence.OneToMany 、 @javax.persistence.ManyToOne 、 @javax.persistence.ManyToMany )の fetch属性に指定されている値によって決定される。

• javax.persistence.FetchType#LAZY の場合は、JOIN FETCH対象からはずれるため、、関連Entityのロードは初回アクセス時に行われる。
• javax.persistence.FetchType#EAGER の場合は、 JOIN FETCHされるため、関連Entityがロードされる。

fetch属性のデフォルトはアノテーションによって異なる。デフォルト値は以下の通り。

• @OneToOne アノテーション : EAGER
• @ManyToOne アノテーション : EAGER
• @OneToMany アノテーション : LAZY
• @ManyToMany アノテーション : LAZY

Note

1:N(N:M)の関連をもつ関連Entityの並び順について

関連Entityのプロパティのアノテーションに、 @javax.persistence.OrderBy アノテーションを指定して制御する。

例を以下に示す。

@OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
@OrderBy // (1)
private Set<OrderItem> orderItems;

項番	説明
(1)	value属性を指定しない場合は、 IDの昇順となる。 詳細は、 JSR 317: Java Persistence API, Version 2.0のSpecification(PDF)「OrderBy Annotation」(P.404-406)

Todo

TBD

今後、以下の内容を追加する予定である。

• fetch属性をデフォルト値から変更した方がよいケースの例。

5.2.2.8.2. ID以外の条件を指定してEntityを1件取得

IDがわからない場合は、ID以外の条件でEntityを検索するQueryメソッドを呼び出す。

• Repositroyインタフェース

public interface AccountRepository extends JpaRepository<Account, String> {

    // (1)
    @Query("SELECT a FROM Account a WHERE a.accountId = :accountId")
    Account findByAccountId(@Param("accountId") String accountId);

}

項番	説明
(1)	ID以外の項目を条件として、Entityを1件検索するQueryメソッドを定義する。

• Service

public Account getAccount(String accountId) {
    Account account = accountRepository.findByAccountId(accountId); // (2)
    if (account == null) { // (3)
        // ...
    }

項番	説明
(2)	Repositryインタフェースに実装したQueryメソッドを呼び出す。
(3)	RepositryインタフェースのfindOneメソッドと同様に、条件に一致するEntityが存在しない場合は、返却値がnullになるので、null判定が必要となる。 必要に応じて、指定した条件に一致するEntityが存在しない場合の処理を実装する。 条件に一致するEntityが複数存在した場合は、 org.springframework.dao.IncorrectResultSizeDataAccessException が発生する。

Note

返却されるEntityオブジェクトについて

Queryメソッドを呼び出した場合、必ず永続層(DB)に対してQueryが実行される。 ただし、Queryを実行して取得されたEntityが既に EntityManager 上で管理されている場合は、 Queryを実行して取得されたEntityオブジェクトは破棄され、 EntityManager 上で管理されているEntityオブジェクトが返却される。

Note

ID + α を条件とするQueryメソッドについて

ID + α を条件とするQueryメソッドは、原則作成しないようにすることを推奨する。 このケースは、 findOneメソッドを呼び出して取得したEntityオブジェクトのプロパティ値を比較するロジックを組むことで、同じことが実現できる。

原則作成しないことを推奨する理由は、Queryを実行して取得されたEntityオブジェクトが破棄される可能性があり、無駄なQueryの実行となってしまうためである。 IDがわかっているのであれば、 無駄なQueryの実行が行われないfindOneメソッドを使用した方がよい。 特に、性能要件が高いアプリケーションの場合は、意識して実装すること。

ただし、以下の条件に当てはまる場合は、Queryメソッドを使用した方がQueryの実行回数が少なくなる事もあるので、その場合はQueryメソッドを使用してもよい。

• + α の条件の部分に関連オブジェクトのプロパティ(関連テーブルのカラム)が含まれる。
• 条件となる関連EntityへのFetchTypeに LAZY が含まれる。

Note

関連Entityのロードタイミングについて

JOIN FETCHに指定された関連Entityは、Query実行直後にロードされる。

JOIN FETCHに指定がない関連Entityは、関連付けアノテーション( @OneToOne 、 @OneToMany 、 @ManyToOne 、 @ManyToMany )の fetch属性に指定されている値によって以下の動作になる。

• javax.persistence.FetchType#LAZY の場合は、Lazy Load対象となり、関連Entityのロードは初回アクセス時に行われる。
• javax.persistence.FetchType#EAGER の場合は、 関連EntityをロードするためのQueryが実行され、関連Entityのオブジェクトがロードされる。

Note

1:N(N:M)の関連をもつ関連Entityの並び順について

• JOIN FETCHに指定された関連Entityの並び順は、JPQLに”ORDER BY”句を指定して制御する。
• Query実行後にロードされる関連Entityの並び順は、 関連Entityのプロパティのアノテーションに、 @javax.persistence.OrderBy アノテーションを指定して制御する。

5.2.2.9.1. Entityの追加

Entityを追加したい場合は、Entityオブジェクトを生成し、Repositryインタフェースのsaveメソッドを呼び出す。

• Service

Order order = new Order("accepted"); // (1)
order = orderRepository.save(order); // (2)

項番	説明
(1)	Entityオブジェクトのインスタンスを生成し、必要なプロパティに値を設定する。 上記例では、IDの設定はJPAのID採番機能を使用している。JPAのID採番機能を使用する場合は、アプリケーションコードでIDの設定は行ってはいけない。 アプリケーションコードでIDを設定してしまうと、 EntityManager のmergeメソッドが呼び出されるため、不要な処理が実行されてしまう。
(2)	Repositoryインタフェースのsaveメソッドを呼び出し、(1)で生成したEntityオブジェクトを EntityManager の管理対象にする。 EntityManager によって管理されるEntityオブジェクトは、saveメソッドの引数に渡したEntityオブジェクトではなく、saveメソッドから返却されたEntityオブジェクトになるので注意すること。 IDは、このタイミングでJPAのID採番機能によって設定される。

Note

mergeメソッドが呼び出されるデメリット

EntityManager のmergeメソッドは、Entityを EntityManager の管理対象にする際に、永続層(DB)から同じIDをもつEntityを取得する仕組みになっている。 Entityの追加処理としては、Entityの取得処理はは無駄な処理となる。高い性能要件があるアプリケーションの場合は、IDの採番タイミングを意識すること。

Note

制約エラーのハンドリング

saveメソッドを呼び出したタイミングでは、永続層(DB)にQuery(INSERT)は実行されない。 そのため、一意制約違反などの制約系のエラーをハンドリングする必要がある場合は、Repositoryインタフェースのsaveメソッドではなく、 saveAndFlushメソッドまたはflushメソッドを呼び出す必要がある。

• Entity

@Entity // (3)
@Table(name = "t_order") // (4)
public class Order implements Serializable {

    // (5)
    @SequenceGenerator(name = "GEN_ORDER_ID", sequenceName = "s_order_id",
                       allocationSize = 1)
    @GeneratedValue(strategy = GenerationType.SEQUENCE,
                    generator = "GEN_ORDER_ID")
    @Id // (6)
    private int id;

    // (7)
    @ManyToOne
    @JoinColumn(name = "status_code")
    private OrderStatus status;

    // ...

    public Order(String statusCode) {
        this.status = new OrderStatus(statusCode);
    }

    // ...

}

項番	説明
(3)	Entityクラスには @javax.persistence.Entity アノテーションを付与する。
(4)	Entityクラスとマッピングするテーブル名は @javax.persistence.Table アノテーションのname属性に指定する。 エンティティ名からテーブル名が解決できる場合は指定しなくてもよいが、解決できない場合は指定すること。
(5)	JPAのID採番機能を使用するために必要なアノテーションを指定している。 JPAのID採番機能を使用する場合は、 @javax.persistence.GeneratedValue アノテーションを指定する。 シーケンスオブジェクトを使用する場合は、 @javax.persistence.SequenceGenerator アノテーション、採番テーブルを使用する場合は、 @javax.persistence.TableGenerator アノテーションの指定も必要となる。 上記例では、 "s_order_id" という名前のシーケンスオブジェクトを使ってIDを採番している。
(6)	主キーを保持するプロパティに、 @javax.persistence.Id アノテーションを付与する。 複合キーの場合は、 @javax.persistence.EmbeddedId アノテーションを付与する。
(7)	別のEntityとの関連を保持するプロパティに、 関連付けアノテーション( @OneToOne 、 @OneToMany 、 @ManyToOne 、 @ManyToMany )を付与する。

Note

ID採番用のアノテーションについて

各アノテーションの詳細は、JSR 317: Java Persistence API, Version 2.0のSpecification(PDF)を参照されたい。

• @GeneratedValue : P.375-376
• @SequenceGenerator : P.413-414
• @TableGenerator : P.415-417

Note

IDの採番方法について

採番方法は、 @GeneratedValue アノテーションのstrategy属性に javax.persistence.GenerationType 列挙の値を指定する。 指定可能な値は以下の通り。

• TABLE : 永続層(DB)のテーブルを使用してIDを採番する。
• SEQUENCE : 永続層(DB)のシーケンスオブジェクトを使用してIDを採番する。
• IDENTITY : 永続層(DB)のidentity列を使用してIDを採番する。
• AUTO : 永続層(DB)に最も適切な採番方法選択してIDを採番する。

原則 AUTO は使用せず、明示的に使用するタイプを指定することを推奨する。

5.2.2.9.2. Entityと関連Entityの追加

Entityと関連Entityを一緒に追加したい場合は、Repositryインタフェースのsaveメソッドを呼び出してEntityオブジェクトを EntityManager の管理対象にした後に、 関連Entityのオブジェクトを生成し、Entityオブジェクトに関連づける。

この方法を使用するためには、関連EntityのCascade対象の操作に、persist が含まれている必要がある。

Note

Cascade対象となった場合の挙動について

関連EntityがCascade対象に指定されている場合、Entityに対するJPAの操作( persist , merge , remove , refresh , detach ) が関連Entityに対して、連鎖して行われる。

Spring Data JPAのRepositoryインタフェースの操作とのマッピングは以下の通り。

• saveメソッド : persist or merge
• deleteメソッド : remove

refresh , detach は Spring Data JPAのデフォルト実装で実行されることはない。

• Service

String itemCode = "ITM0000001";
int itemQuantity = 10;
String wayToPay = "card";

Order order = new Order("accepted");
order = orderRepository.save(order); // (1)

OrderItem orderItem = new OrderItem(order.getId(), itemCode,
        itemQuantity);
order.setOrderItems(Collections.singleton(orderItem));    // (2)
order.setOrderPay(new OrderPay(order.getId(), wayToPay)); // (2)

項番	説明
(1)	Repositoryインタフェースのsaveメソッドを呼び出し、まずEntityオブジェクトを EntityManager の管理対象にする。 上記例では、Entityオブジェクトに対して、関連Entityのオブジェクトを設定する前に、saveメソッドを呼び出している。これは、関連EntityのIDの一部として使用されるEntityのID(orderId)を採番する必要があるためである。
(2)	EntityManager の管理対象となっているEntityオブジェクトに対して、関連Entityのオブジェクトを設定する。 トランザクションのコミット時に、Entityオブジェクトへのpersist操作(INSERT)が、関連Entityのオブジェクトに対して連鎖される。

• Entity

@Entity
@Table(name = "t_order")
public class Order implements Serializable {

    private static final long serialVersionUID = 1L;

    @Id
    @SequenceGenerator(name = "GEN_ORDER_ID", sequenceName = "s_order_id",
                       allocationSize = 1)
    @GeneratedValue(strategy = GenerationType.SEQUENCE,
                    generator = "GEN_ORDER_ID")
    private int id;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL,  // (3)
               orphanRemoval = true)
    @OrderBy
    private Set<OrderItem> orderItems;

    @OneToOne(mappedBy = "order", cascade = CascadeType.ALL,
              orphanRemoval = true)
    private OrderPay orderPay;

    @ManyToOne
    @JoinColumn(name = "status_code")
    private OrderStatus status;

    // ...

    public Order(String statusCode) {
        this.status = new OrderStatus(statusCode);
    }

    // ...

}

項番	説明
(3)	関連アノテーションのcascade属性に、Cascade対象にする操作のタイプ( javax.persistence.CascadeType )を指定する。 上記例では、すべての操作を関連EntityのCascade対象としている。 特に理由がない場合は、すべての操作をCascade対象にしておくことを推奨する。

Warning

cascade属性を指定してはいけない関連Entityについて

トランザクション系のEntityからコード系およびマスタ系のEntityに関連をもつ場合は、cascade属性は指定してはいけない。 上記例だと、OrderStatus はコード系のEntityになるので Order の status プロパティの @ManyToOne アノテーションにcascade属性は指定してはいけない。

• 関連Entity

@Entity
@Table(name = "t_order_item")
public class OrderItem implements Serializable {

    @EmbeddedId
    private OrderItemPK id;

    private int quantity;

    @ManyToOne
    @JoinColumn(name = "order_id", insertable = false, updatable = false)
    private Order order;

    // ...

    public OrderItem(Integer orderId, String itemCode, int quantity) {
        this.id = new OrderItemPK(orderId, itemCode);
        this.quantity = quantity;
    }

    // ...

}

@Entity
@Table(name = "t_order_pay")
public class OrderPay implements Serializable {

    @Id
    @Column(name = "order_id")
    private Integer orderId;

    @Column(name = "way_to_pay")
    private String wayToPay;

    @OneToOne
    @JoinColumn(name = "order_id")
    private Order order;

    // ...

    public OrderPay(int orderId, String wayToPay) {
        this.orderId = orderId;
        this.wayToPay = wayToPay;
    }

    // ...

}

5.2.2.9.3. 関連Entityの追加

関連Entityを追加したい場合は、Repositoryインタフェース経由で取得したEntityオブジェクトに対して、生成した関連Entityのオブジェクトを関連付る。

この方法を使用するためには、関連EntityのCascade対象の操作に、persist と merge が含まれている必要がある。

String itemCode = "ITM0000003";
int quantity = 30;

Order order = orderRepository.findOne(orderId); // (1)

OrderItem orderItem = new OrderItem(order.getId(), itemCode, quantity);
order.getOrderItems().add(orderItem); // (2)

OrderPay orderPay = order.getOrderPay();
if (orderPay == null) {
    order.setOrderPay(new OrderPay(order.getId(), "cash")); // (3)
} else {
    orderPay.setWayToPay("cash");
}

項番	説明
(1)	Repositoryインタフェースのメソッドを使用して、Entityオブジェクトを取得する。
(2)	1:Nの関連Entityの場合、生成した関連Entityのオブジェクトを、Entityオブジェクトから取得したコレクションに追加する。
(3)	1:1の関連Entityの場合、生成した関連EntityのオブジェクトをEntityオブジェクトに設定する。

5.2.2.9.4. 関連Entityの直接追加

関連Entityを、親のEntityオブジェクトに関連付けせずに直接追加したい場合は、関連Entity用のRepositoryインタフェースを使用して保存する。

String itemCode = "ITM0000003";
int quantity = 40;

OrderItem orderItem = new OrderItem(orderId, itemCode, quantity); // (1)

orderItemRepository.save(orderItem); // (2)

項番	説明
(1)	関連Entityのオブジェクトを生成する。
(2)	関連Entity用のRepositoryインタフェースのsaveメソッドを呼び出す。

Note

関連Entityを直接保存するメリット

生成されるオブジェクトの数が少なくなる。 親のEntityオブジェクトを取得する場合、処理に不要な関連Entityのオブジェクトが生成される可能性がある。

Note

関連Entityを直接保存するデメリット

IDの一部に親EntityのIDを使用している場合、saveメソッドを呼び出す前にIDを設定しておく必要がある。 IDを設定してしまうとSpring Data JPAのデフォルト実装は EntityManager のmergeメソッドを呼び出す。 そのため、必ず永続層(DB)からIDが同じEntityを取得する処理が実行されてしまう。

Warning

追加後に親のEntityオブジェクトを利用する際の注意点

関連Entity用Repositoryのsaveメソッドを使って関連Entity追加した場合は、 親にあたるEntityオブジェクトには関連付けられていないため、親のEntityオブジェクトを経由して取得することができない。

回避方法は、

1. 関連Entityのオブジェクトを直接追加するのではなく、親のEntityオブジェクトに関連付けて追加するようにする。
2. saveAndFlushメソッドを使用することで、永続層(DB)と同期を親のEntityを取得する前に行う。

このケースの場合、特に理由がないのであれば、前者の方法で関連Entityのオブジェクトを追加すること。 後者は、親にあたるEntityオブジェクトが既に管理状態のEntityになっていた場合に、問題を回避することができない。

5.2.2.10.1. Entityの更新

Entityを更新したい場合は、Repositoryインタフェースのメソッドを使用して取得したEntityオブジェクトに対して、変更したい値を設定する。

Order order = orderRepository.findOne(orderId); // (1)
order.setStatus(new OrderStatus("checking")); // (2)

項番	説明
(1)	Repositoryインタフェースのメソッドを使用して、Entityオブジェクトを取得する。
(2)	Entityオブジェクトの状態を、setterメソッドを呼び出して更新する。

Note

Repositoryのsaveメソッドの呼び出しについて

Repositoryインタフェースのメソッドを使用して取得したEntityオブジェクトは、 EntityManager 上で管理されている。 EntityManager 上で管理されているEntityオブジェクトは、setterメソッドを使ってオブジェクトの状態を変更するだけで、 トランザクションコミット時に変更内容が永続層(DB)に反映される仕組みになっている。 そのため、Repositoryインタフェースのsaveメソッドを明示的に呼び出す必要はない。

ただし、Entityオブジェクトが EntityManager 上で管理されていない場合は、 saveメソッドを呼び出す必要がある。 例えば、画面から送信されたリクエストパラメータをもとにEntityオブジェクトを生成した場合などが、このケースに当てはまる。

5.2.2.10.2. 関連Entityの更新

関連Entityを更新したい場合は、Repositoryインタフェースのメソッドを使用して取得したEntityオブジェクトから取得した関連Entityのオブジェクトに対して、変更したい値を設定する。

この方法を使用するためには、関連EntityのCascade対象の操作に、merge が含まれている必要がある。

Order order = orderRepository.findOne(orderId); // (1)

for (OrderItem orderItem : order.getOrderItems()) {
    int newQuantity = quantityMap.get(orderItem.getId().getItemCode());
    orderItem.setQuantity(newQuantity); // (2)
}

order.getOrderPay().setWayToPay("cash"); // (3)

項番	説明
(1)	Repositoryインタフェースのメソッドを使用して、Entityオブジェクトを取得する。
(2)	1:Nの関連Entityの場合、Entityオブジェクトから取得したコレクションに格納されている関連Entityのオブジェクトの状態を、setterメソッドを呼び出して更新する。
(3)	1:1の関連Entityの場合、Entityオブジェクトから取得した関連Entityのオブジェクトの状態を、setterメソッドを呼び出して更新する。

5.2.2.10.3. 関連Entityの直接更新

関連Entityを、親のEntityを使用せず直接更新したい場合は、関連Entity用のRepositoryインタフェースのメソッドを使用して取得したEntityオブジェクトに対して、変更したい値を設定する。

int quantity = 43;

OrderItem orderItem = orderItemRepository.findOne(new OrderItemPK(
        orderId, itemCode)); // (1)

orderItem.setQuantity(quantity); // (2)

項番	説明
(1)	関連EntityのRepositoryインタフェースのfindOneメソッドを呼び出して、関連Entityのオブジェクトを取得する。
(2)	関連Entityのオブジェクトの状態を、setterメソッドを使って更新する。

Note

更新後に親のEntityを利用した場合の動作について

関連Entity用Repositoryのsaveメソッドを使って関連Entityを更新した場合は、 追加時とは異なり、親のEntityオブジェクトで保持している関連Entityにも反映される これは、EntityManager 上で管理されている同じインスタンスの参照を保持しているためである。

5.2.2.10.4. Queryメソッドを使用して更新

5.2.2.11.1. Entityと関連Entityの削除

Entityと関連Entityを一緒に削除したい場合は、Repositryインタフェースのdeleteメソッドを呼び出す。

この方法を使用するためには、関連EntityのCascade対象の操作に remove が含まれているか、 または関連Entityを削除するための設定を有効(関連付けアノテーションのorphanRemoval属性を true )にする必要がある。

• Service

orderRepository.delete(orderId); // (1)

項番	説明
(1)	IDまたはEntityオブジェクトを指定してRepositryインタフェースのdeleteメソッドを呼び出す。

• Entity

@Entity
@Table(name = "t_order")
public class Order implements Serializable {

    // ...

    @OneToMany(mappedBy = "order",
               cascade = CascadeType.ALL, orphanRemoval = true) // (2)
    @OrderBy
    private Set<OrderItem> orderItems;

    // ...

}

項番	説明
(2)	Cascade対象の操作に remove を含め、 関連Entityを削除するための設定を有効 (関連付けアノテーションのorphanRemoval属性を true )にする。

Note

関連Entityの削除について

関連Entityのオブジェクトを一緒に削除したくない場合は、 Cascade対象の操作に remove が含まれないようにしておく必要がある。 また、関連付けアノテーションのorphanRemoval属性も false に指定しておくこと。

5.2.2.11.2. 関連Entityの削除

関連Entityを削除したい場合は、Repositoryインタフェース経由で取得したEntityオブジェクトから、関連Entityのオブジェクトを削除する。

この方法を使用するためには、関連Entityを削除するための設定を有効(関連付けアノテーションのorphanRemoval属性を true )にする必要がある。

Note

関連Entityを削除する設定を有効にした場合の挙動について

関連Entityを削除する設定を有効にした場合、以下の動作になる。

• 1:Nの関連Entityの場合は、関連Entityのオブジェクトをコレクションの中から削除すると、トランザクションコミット時に永続層(DB)からも削除される。
• 1:1の関連Entityの場合は、関連Entityを null に設定すると、トランザクションコミット時に永続層(DB)からも削除される。

orphanRemoval属性のデフォルト値となっている false が指定されている場合は、メモリ上からは消えるが、 削除した関連Entityのオブジェクトに対する永続処理(UPDATE/DELETE)は行われない。

• Service

Order order = orderRepository.findOne(orderId); // (1)

// (2)
Set<OrderItem> orderItemsOfRemoveTarget = new LinkedHashSet<OrderItem>(); // (3)
for (OrderItem orderItem : order.getOrderItems()) {
    String itemCode = orderItem.getId().getItemCode();
    if (quantityMap.containsKey(itemCode)) {
        int newQuantity = quantityMap.get(itemCode);
        orderItem.setQuantity(newQuantity);
    } else {
        orderItemsOfRemoveTarget.add(orderItem); // (4)
    }
}
order.getOrderItems().removeAll(orderItemsOfRemoveTarget); // (5)

order.setOrderPay(null); // (6)

項番	説明
(1)	Repositoryインタフェースのメソッドを使用して、Entityオブジェクトを取得する。
(2)	1:Nの関連Entityを削除する実装例について説明する。
(3)	削除する関連Entityのオブジェクトを格納しておくコレクションを用意する。
(4)	削除対象の関連Entityのオブジェクトを、(3)のコレクションに追加する。
(5)	削除対象の関連Entityのオブジェクトから取得したコレクションの中から削除する。
(6)	1:1の関連Entityの場合、削除したい関連Entityのオブジェクトを保持するプロパティを null に設定する。

• Entity

@Entity
@Table(name = "t_order")
public class Order implements Serializable {

    @Id
    @SequenceGenerator(name = "GEN_ORDER_ID", sequenceName = "s_order_id", allocationSize = 1)
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "GEN_ORDER_ID")
    private int id;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL,
               orphanRemoval = true) // (7)
    @OrderBy
    private Set<OrderItem> orderItems;

    @OneToOne(mappedBy = "order", cascade = CascadeType.ALL,
              orphanRemoval = true) // (7)
    private OrderPay orderPay;

    @ManyToOne
    @JoinColumn(name = "status_code")
    private OrderStatus status;

    // ...

}

項番	説明
(7)	関連Entityを削除するための設定を有効(関連付けアノテーションのorphanRemoval属性を true )にする。

Note

orphanRemoval属性が指定できる関連付けアノテーションについて

orphanRemoval属性が指定できる関連付けアノテーションは、 @OneToOne と @OneToMany の2つとなっている。