Spring Data JPA 3.0.6 - リファレンスドキュメント

このドキュメントのコピーは、あなた自身の使用および他者への配布のために作成することができますが、そのようなコピーに料金を請求しないこと、さらに、印刷物または電子的に配布されるかどうかにかかわらず、各コピーにこの著作権表示が含まれていることを条件とします。

1. 序文

Spring Data JPA は、Jakarta Persistence API（JPA）のリポジトリサポートを提供します。これにより、JPA データソースにアクセスする必要のあるアプリケーションの開発が容易になります。

1.1. プロジェクトメタデータ

バージョン管理: https://github.com/spring-projects/spring-data-jpa (英語)
バグトラッカー: https://github.com/spring-projects/spring-data-jpa/issues (英語)
リリースリポジトリ: https://repo.spring.io/libs-release (英語)
マイルストーンリポジトリ: https://repo.spring.io/libs-milestone (英語)
スナップショットリポジトリ: https://repo.spring.io/libs-snapshot (英語)

2. Spring Data のアップグレード

Spring Data の以前のバージョンからアップグレードする方法については、プロジェクトの wiki [GitHub] (英語) で説明されています。リリースノートセクション [GitHub] (英語) のリンクに従って、アップグレードするバージョンを見つけます。

バージョンアップ手順は、常にリリースノートの最初の項目です。複数のバージョンを飛び越えてバージョンアップする場合は、途中のバージョンのリリースノートも確認してください。

3. 依存関係

個々の Spring Data モジュールの開始日が異なるため、それらのほとんどは異なるメジャーバージョン番号とマイナーバージョン番号を持っています。互換性のあるものを見つける最も簡単な方法は、互換性のあるバージョンが定義された状態で提供される Spring Data リリーストレイン BOM に依存することです。Maven プロジェクトでは、次のように POM の <dependencyManagement /> セクションでこの依存関係を宣言します。

例 1: Spring Data リリーストレイン BOM の使用

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.data</groupId>
      <artifactId>spring-data-bom</artifactId>
      <version>2022.0.6</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

現在のリリーストレインバージョンは 2022.0.6 です。トレインバージョンでは、パターン YYYY.MINOR.MICRO の calver (英語) を使用しています。バージョン名は、GA リリースとサービスリリースでは ${calver} に従い、他のすべてのバージョンでは次のパターンに従います。${calver}-${modifier}。modifier は次のいずれかになります。

SNAPSHOT: 現在のスナップショット
M1、M2 など: マイルストーン
RC1、RC2 など: リリース候補

Spring Data サンプルリポジトリ [GitHub] (英語) で BOM の使用例を見つけることができます。これが適切な場所にあると、次のように、<dependencies /> ブロックでバージョンなしで使用する Spring Data モジュールを宣言できます。

例 2: Spring Data モジュールへの依存関係の宣言

<dependencies>
  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-jpa</artifactId>
  </dependency>
<dependencies>

3.1. Spring Boot を使用した依存関係管理

Spring Boot は、Spring Data モジュールの最新バージョンを選択します。それでも新しいバージョンにアップグレードする場合は、spring-data-bom.version プロパティを、使用するトレーニングバージョンとイテレーションに設定します。

詳細については、Spring Boot のドキュメント ( "Spring Data Bom" で検索) を参照してください。

3.2. Spring Framework

Spring Data モジュールの現在のバージョンには、Spring Framework 6.0.9 以降が必要です。モジュールは、そのマイナーバージョンの古いバグ修正バージョンでも動作する可能性があります。ただし、その世代内の最新バージョンを使用することを強くお勧めします。

4. Spring Data リポジトリの操作

Spring Data リポジトリの抽象化のゴールは、さまざまな永続ストアのデータアクセスレイヤーを実装するために必要な定型コードの量を大幅に削減することです。

Spring Data リポジトリのドキュメントとモジュール

この章では、Spring Data リポジトリの中心的な概念とインターフェースについて説明します。この章の情報は、Spring Data Commons モジュールから取得されます。Jakarta Persistence API (JPA) モジュールの構成とコードサンプルを使用します。XML 構成を使用する場合は、XML 名前空間の宣言と拡張する型を、使用する特定のモジュールと同等のものに適合させる必要があります。"名前空間参照" は、リポジトリ API をサポートするすべての Spring Data モジュールでサポートされる XML 構成を対象としています。"リポジトリクエリキーワード" は、リポジトリの抽象化によって一般的にサポートされているクエリメソッドのキーワードをカバーしています。モジュールの特定の機能の詳細については、このドキュメントのそのモジュールに関する章を参照してください。

4.1. コアコンセプト

Spring Data リポジトリ抽象化の中心的なインターフェースは Repository です。管理するドメインクラスと、ドメインクラスの識別子の型を型引数として取ります。このインターフェースは主に、操作する型をキャプチャーし、このインターフェースを継承するインターフェースを検出するのに役立つマーカーインターフェースとして機能します。CrudRepository (Javadoc) および ListCrudRepository (Javadoc) インターフェースは、管理されているエンティティクラスに高度な CRUD 機能を提供します。

例 3: CrudRepository インターフェース

public interface CrudRepository<T, ID> extends Repository<T, ID> {

  <S extends T> S save(S entity);      (1)

  Optional<T> findById(ID primaryKey); (2)

  Iterable<T> findAll();               (3)

  long count();                        (4)

  void delete(T entity);               (5)

  boolean existsById(ID primaryKey);   (6)

  // … more functionality omitted.
}

1	指定されたエンティティを保存します。
2	指定された ID で識別されるエンティティを返します。
3	すべてのエンティティを返します。
4	エンティティの数を返します。
5	指定されたエンティティを削除します。
6	指定された ID のエンティティが存在するかどうかを示します。

このインターフェースで宣言されたメソッドは、一般に CRUD メソッドと呼ばれます。ListCrudRepository は同等のメソッドを提供しますが、CrudRepository メソッドが Iterable を返すのに対し、それらは List を返します。

また、JpaRepository や MongoRepository などの永続化技術固有の抽象化も提供します。これらのインターフェースは CrudRepository を継承し、CrudRepository などのかなり汎用的な永続化テクノロジーにとらわれないインターフェースに加えて、基礎となる永続化テクノロジーの機能を公開します。

CrudRepository に加えて、エンティティへのページ指定されたアクセスを容易にする追加のメソッドを追加する PagingAndSortingRepository (Javadoc) 抽象化があります。

例 4: PagingAndSortingRepository インターフェース

public interface PagingAndSortingRepository<T, ID>  {

  Iterable<T> findAll(Sort sort);

  Page<T> findAll(Pageable pageable);
}

20 のページサイズで User の 2 番目のページにアクセスするには、次のようなことができます。

PagingAndSortingRepository<User, Long> repository = // … get access to a bean
Page<User> users = repository.findAll(PageRequest.of(1, 20));

クエリメソッドに加えて、カウントクエリと削除クエリの両方のクエリ派生を使用できます。次のリストは、派生カウントクエリのインターフェース定義を示しています。

例 5: 派生カウントクエリ

interface UserRepository extends CrudRepository<User, Long> {

  long countByLastname(String lastname);
}

次のリストは、派生削除クエリのインターフェース定義を示しています。

例 6: 派生削除クエリ

interface UserRepository extends CrudRepository<User, Long> {

  long deleteByLastname(String lastname);

  List<User> removeByLastname(String lastname);
}

4.2. クエリメソッド

通常、標準の CRUD 機能リポジトリには、基になるデータストアに対するクエリがあります。Spring Data では、これらのクエリを宣言することは 4 ステップのプロセスになります。

次の例に示すように、リポジトリまたはそのサブインターフェースの 1 つを継承するインターフェースを宣言し、処理するドメインクラスと ID 型に入力します。
interface PersonRepository extends Repository<Person, Long> { … }

インターフェースでクエリメソッドを宣言します。

interface PersonRepository extends Repository<Person, Long> {
  List<Person> findByLastname(String lastname);
}

JavaConfig または XML 構成を使用して、Spring をセットアップして、これらのインターフェースのプロキシインスタンスを作成します。
Java
import org.springframework.data.….repository.config.EnableJpaRepositories; @EnableJpaRepositories class Config { … }
XML
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jpa="http://www.springframework.org/schema/data/jpa" xsi:schemaLocation="http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/data/jpa https://www.springframework.org/schema/data/jpa/spring-jpa.xsd"> <repositories base-package="com.acme.repositories"/> </beans>
この例では、JPA 名前空間が使用されています。リポジトリの抽象化を他のストアに使用する場合、これをストアモジュールの適切なネームスペース宣言に変更する必要があります。つまり、たとえば mongodb を優先して jpa を交換する必要があります。
アノテーション付きクラスのパッケージがデフォルトで使用されるため、JavaConfig バリアントはパッケージを明示的に構成しないことに注意してください。スキャンするパッケージをカスタマイズするには、データストア固有のリポジトリの @EnableJpaRepositories -annotation の basePackage … 属性のいずれかを使用します。

次の例に示すように、リポジトリインスタンスを挿入して使用します。

class SomeClient {

  private final PersonRepository repository;

  SomeClient(PersonRepository repository) {
    this.repository = repository;
  }

  void doSomething() {
    List<Person> persons = repository.findByLastname("Matthews");
  }
}

以下のセクションでは、各ステップについて詳しく説明します。

リポジトリインターフェースの定義
クエリメソッドの定義
リポジトリインスタンスの作成
Spring Data リポジトリのカスタム実装

4.3. リポジトリインターフェースの定義

リポジトリインターフェースを定義するには、最初にドメインクラス固有のリポジトリインターフェースを定義する必要があります。インターフェースは Repository を継承し、ドメインクラスと ID 型に入力する必要があります。そのドメイン型の CRUD メソッドを公開する場合は、CrudRepository、または Repository の代わりにそのバリアントの 1 つを継承できます。

4.3.1. リポジトリ定義の微調整

リポジトリインターフェースを使い始める方法にはいくつかのバリエーションがあります。

典型的なアプローチは、CrudRepository を継承することです。これにより、CRUD 機能のメソッドが提供されます。CRUD は、Create、Read、Update、Delete の略です。バージョン 3.0 では、CrudRepository と非常によく似た ListCrudRepository も導入されましたが、複数のエンティティを返すメソッドでは、使いやすい Iterable ではなく List が返されます。

リアクティブストアを使用している場合は、使用しているリアクティブフレームワークに応じて ReactiveCrudRepository または RxJava3CrudRepository を選択できます。

Kotlin を使用している場合は、Kotlin のコルーチンを利用する CoroutineCrudRepository を選択できます。

さらに、Sort 抽象化、または最初の場合は Pageable 抽象化を指定できるメソッドが必要な場合は、PagingAndSortingRepository、ReactiveSortingRepository、RxJava3SortingRepository または CoroutineSortingRepository を継承できます。さまざまな並べ替えリポジトリは、3.0 より前の Spring Data バージョンのようにそれぞれの CRUD リポジトリを継承しなくなったことに注意してください。両方の機能が必要な場合は、両方のインターフェースを継承する必要があります。

Spring Data インターフェースを継承したくない場合は、リポジトリインターフェースに @RepositoryDefinition でアノテーションを付けることもできます。CRUD リポジトリインターフェースの 1 つを継承すると、エンティティを操作するためのメソッドの完全なセットが公開されます。公開するメソッドを選択したい場合は、公開するメソッドを CRUD リポジトリからドメインリポジトリにコピーします。その際、メソッドの戻り値の型を変更できます。Spring Data は、可能であれば戻り値の型を尊重します。例: 複数のエンティティを返すメソッドの場合、Iterable<T>、List<T>、Collection<T> または VAVR リストを選択できます。

アプリケーション内の多くのリポジトリに同じメソッドのセットが必要な場合は、継承元の独自のベースインターフェースを定義できます。このようなインターフェースには、@NoRepositoryBean のアノテーションを付ける必要があります。これにより、Spring Data はインスタンスを直接作成しようとして失敗し、そのリポジトリのエンティティを特定できないために失敗します。これは、ジェネリクス型変数がまだ含まれているためです。

次の例は、CRUD メソッド（この場合は findById および save）を選択的に公開する方法を示しています。

例 7: CRUD メソッドを選択的に公開する

@NoRepositoryBean
interface MyBaseRepository<T, ID> extends Repository<T, ID> {

  Optional<T> findById(ID id);

  <S extends T> S save(S entity);
}

interface UserRepository extends MyBaseRepository<User, Long> {
  User findByEmailAddress(EmailAddress emailAddress);
}

前の例では、すべてのドメインリポジトリと公開された findById(…) および save(…) に共通のベースインターフェースを定義しました。これらのメソッドは、Spring Data が提供する選択のストアのベースリポジトリ実装にルーティングされます（たとえば、JPA を使用する場合、実装は SimpleJpaRepository です）。これは、それらが CrudRepository のメソッドシグネチャーと一致するためです。そのため、UserRepository はユーザーを保存し、ID で個々のユーザーを検索し、メールアドレスで Users を検索するクエリをトリガーできるようになりました。

中間リポジトリインターフェースには @NoRepositoryBean のアノテーションが付けられています。Spring Data が実行時にインスタンスを作成してはならないすべてのリポジトリインターフェースに、そのアノテーションを必ず追加してください。

4.3.2. 複数の Spring Data モジュールでリポジトリを使用する

定義済みスコープ内のすべてのリポジトリインターフェースが Spring Data モジュールにバインドされているため、アプリケーションで一意の Spring Data モジュールを使用すると、物事が簡単になります。アプリケーションによっては、複数の Spring Data モジュールを使用する必要がある場合があります。そのような場合、リポジトリ定義は永続化テクノロジーを区別する必要があります。クラスパスで複数のリポジトリファクトリを検出すると、Spring Data は厳密なリポジトリ構成モードに入ります。厳密な構成では、リポジトリまたはドメインクラスの詳細を使用して、リポジトリ定義の Spring Data モジュールバインディングについて決定します。

リポジトリ定義がモジュール固有のリポジトリを継承する場合、特定の Spring Data モジュールの有効な候補です。
ドメインクラスにモジュール固有の型アノテーションが付けられている場合、そのクラスは特定の Spring Data モジュールの有効な候補となります。Spring Data モジュールは、サードパーティのアノテーション (JPA の @Entity など) を受け入れるか、独自のアノテーション (Spring Data MongoDB および Spring Data Elasticsearch の @Document など) を提供します。

次の例は、モジュール固有のインターフェース（この場合は JPA）を使用するリポジトリを示しています。

例 8: モジュール固有のインターフェースを使用したリポジトリ定義

interface MyRepository extends JpaRepository<User, Long> { }

@NoRepositoryBean
interface MyBaseRepository<T, ID> extends JpaRepository<T, ID> { … }

interface UserRepository extends MyBaseRepository<User, Long> { … }

MyRepository および UserRepository は、型階層で JpaRepository を継承します。それらは、Spring Data JPA モジュールの有効な候補です。

次の例は、汎用インターフェースを使用するリポジトリを示しています。

例 9: ジェネリクスインターフェースを使用したリポジトリ定義

interface AmbiguousRepository extends Repository<User, Long> { … }

@NoRepositoryBean
interface MyBaseRepository<T, ID> extends CrudRepository<T, ID> { … }

interface AmbiguousUserRepository extends MyBaseRepository<User, Long> { … }

AmbiguousRepository と AmbiguousUserRepository は、型階層内の Repository と CrudRepository のみを継承します。一意の Spring Data モジュールを使用する場合はこれで問題ありませんが、複数のモジュールでは、これらのリポジトリをどの特定の Spring Data にバインドする必要があるかを区別できません。

次の例は、アノテーション付きのドメインクラスを使用するリポジトリを示しています。

例 10: アノテーション付きのドメインクラスを使用したリポジトリ定義

interface PersonRepository extends Repository<Person, Long> { … }

@Entity
class Person { … }

interface UserRepository extends Repository<User, Long> { … }

@Document
class User { … }

PersonRepository は、JPA @Entity アノテーションが付けられた Person を参照しているため、このリポジトリは明らかに Spring Data JPA に属しています。UserRepository は、Spring Data MongoDB の @Document アノテーションでアノテーションが付けられた User を参照します。

次の悪い例は、アノテーションが混在するドメインクラスを使用するリポジトリを示しています。

例 11: アノテーションが混在するドメインクラスを使用したリポジトリ定義

interface JpaPersonRepository extends Repository<Person, Long> { … }

interface MongoDBPersonRepository extends Repository<Person, Long> { … }

@Entity
@Document
class Person { … }

この例は、JPA アノテーションと Spring Data MongoDB アノテーションの両方を使用するドメインクラスを示しています。JpaPersonRepository と MongoDBPersonRepository の 2 つのリポジトリを定義します。1 つは JPA 用で、もう 1 つは MongoDB での使用を目的としています。Spring Data はリポジトリを区別できなくなり、未定義の動作につながります。

リポジトリ型の詳細および識別ドメインクラスアノテーションは、特定の Spring Data モジュールのリポジトリ候補を識別するための厳密なリポジトリ構成に使用されます。同じドメイン型で複数の永続化テクノロジ固有のアノテーションを使用することが可能であり、複数の永続化テクノロジでドメイン型を再利用できます。ただし、Spring Data は、リポジトリをバインドする一意のモジュールを決定できなくなります。

リポジトリを区別する最後の方法は、リポジトリベースパッケージをスコープすることです。ベースパッケージは、リポジトリインターフェース定義のスキャンの開始点を定義します。これは、適切なパッケージにリポジトリ定義があることを意味します。デフォルトのアノテーション駆動型の構成では、構成クラスのパッケージが使用されます。XML ベースの構成の基本パッケージは必須です。

次の例は、基本パッケージのアノテーション駆動型の構成を示しています。

例 12: 基本パッケージのアノテーション駆動型構成

@EnableJpaRepositories(basePackages = "com.acme.repositories.jpa")
@EnableMongoRepositories(basePackages = "com.acme.repositories.mongo")
class Configuration { … }

4.4. クエリメソッドの定義

リポジトリプロキシには、メソッド名からストア固有のクエリを派生させる 2 つの方法があります。

メソッド名から直接クエリを導出します。
手動で定義されたクエリを使用します。

利用可能なオプションは、実際のストアによって異なります。ただし、作成する実際のクエリを決定する戦略が必要です。次のセクションでは、使用可能なオプションについて説明します。

4.4.1. クエリ検索戦略

クエリを解決するリポジトリインフラストラクチャでは、次の戦略を使用できます。XML 構成では、query-lookup-strategy 属性を使用して名前空間で戦略を構成できます。Java 構成の場合、EnableJpaRepositories アノテーションの queryLookupStrategy 属性を使用できます。特定のデータストアでは一部の戦略がサポートされていない場合があります。

CREATE は、クエリメソッド名からストア固有のクエリを作成しようとします。一般的なアプローチは、メソッド名から既知のプレフィックスの特定のセットを削除し、メソッドの残りを解析することです。クエリ構築の詳細については、"クエリ作成" を参照してください。
USE_DECLARED_QUERY は、宣言されたクエリを見つけようとし、見つからない場合は例外をスローします。クエリは、どこかのアノテーションによって定義することも、他の方法で宣言することもできます。そのストアで利用可能なオプションを見つけるには、特定のストアのドキュメントを参照してください。リポジトリインフラストラクチャがブートストラップ時にメソッドに対して宣言されたクエリを見つけられない場合、失敗します。
CREATE_IF_NOT_FOUND （デフォルト）は、CREATE と USE_DECLARED_QUERY を組み合わせたものです。最初に宣言されたクエリを検索し、宣言されたクエリが見つからない場合は、カスタムメソッド名ベースのクエリを作成します。これはデフォルトのルックアップ戦略であるため、明示的に何も構成しない場合に使用されます。メソッド名によるクエリ定義をすばやく行うだけでなく、必要に応じて宣言されたクエリを導入することにより、これらのクエリをカスタム調整することもできます。

4.4.2. クエリ作成

Spring Data リポジトリインフラストラクチャに組み込まれているクエリビルダーメカニズムは、リポジトリのエンティティに対して制約クエリを構築できます。

次の例は、いくつかのクエリを作成する方法を示しています。

例 13: メソッド名からのクエリ作成

interface PersonRepository extends Repository<Person, Long> {

  List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);

  // Enables the distinct flag for the query
  List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
  List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);

  // Enabling ignoring case for an individual property
  List<Person> findByLastnameIgnoreCase(String lastname);
  // Enabling ignoring case for all suitable properties
  List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);

  // Enabling static ORDER BY for a query
  List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
  List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}

クエリメソッド名の解析は、主語と述語に分けられます。最初の部分（find … By、exists … By）はクエリのサブジェクトを定義し、2 番目の部分は述語を形成します。導入句（主語）には、さらに式を含めることができます。find （または他の導入キーワード）と By の間のテキストは、Distinct などの結果を制限するキーワードの 1 つを使用して、作成するクエリまたは Top/First は、クエリ結果を制限しますに個別のフラグを設定しない限り、説明的であると見なされます。

付録には、クエリメソッドのサブジェクトキーワードとクエリメソッドの述語キーワードの完全なリストが含まれています。これには、並べ替えや大文字小文字の修飾子が含まれます。ただし、最初の By は、実際の条件述語の開始を示す区切り文字として機能します。非常に基本的なレベルでは、エンティティプロパティの条件を定義し、And および Or と連結できます。

メソッドの解析の実際の結果は、クエリを作成する永続ストアによって異なります。ただし、注意すべき一般的な事項がいくつかあります。

式は通常、連結可能な演算子と組み合わせたプロパティトラバーサルです。プロパティ式を AND および OR と組み合わせることができます。プロパティ式の Between、LessThan、GreaterThan、Like などの演算子もサポートされます。サポートされている演算子はデータストアによって異なる可能性があるため、リファレンスドキュメントの適切な部分を参照してください。
メソッドパーサーは、個々のプロパティ（たとえば findByLastnameIgnoreCase(…)）または大文字と小文字の区別をサポートする型のすべてのプロパティ（通常は String インスタンス - findByLastnameAndFirstnameAllIgnoreCase(…) など）の IgnoreCase フラグの設定をサポートします。ケースの無視がサポートされているかどうかはストアによって異なるため、ストア固有のクエリメソッドについては、リファレンスドキュメントの関連セクションを参照してください。
プロパティを参照するクエリメソッドに OrderBy 句を追加し、並べ替え方向（Asc または Desc）を提供することにより、静的な順序を適用できます。動的な並べ替えをサポートするクエリメソッドを作成するには、"特別なパラメーター処理" を参照してください。

4.4.3. プロパティ式

前の例に示すように、プロパティ式は管理対象エンティティの直接プロパティのみを参照できます。クエリの作成時に、解析されたプロパティが管理対象ドメインクラスのプロパティであることをすでに確認しています。ただし、ネストされたプロパティを走査して制約を定義することもできます。次のメソッドシグネチャーを検討してください。

List<Person> findByAddressZipCode(ZipCode zipCode);

Person に ZipCode を含む Address があると仮定します。その場合、メソッドは x.address.zipCode プロパティトラバーサルを作成します。解決アルゴリズムは、パーツ全体（AddressZipCode）をプロパティとして解釈することから始まり、ドメインクラスでその名前（大文字でない）のプロパティをチェックします。アルゴリズムが成功すると、そのプロパティが使用されます。そうでない場合、アルゴリズムはキャメルケース部分のソースを右側から頭と尾に分割し、対応するプロパティ（この例では、AddressZip と Code）を見つけようとします。アルゴリズムがそのヘッドを持つプロパティを見つけると、テールを取得し、そこからツリーを構築し続け、今説明したメソッドでテールを分割します。最初の分割が一致しない場合、アルゴリズムは分割ポイントを左に移動し（Address、ZipCode）、続行します。

これはほとんどの場合に機能するはずですが、アルゴリズムが間違ったプロパティを選択する可能性があります。Person クラスにも addressZip プロパティがあるとします。アルゴリズムは最初の分割ラウンドですでに一致し、間違ったプロパティを選択して失敗します（addressZip の型にはおそらく code プロパティがないため）。

このあいまいさを解決するには、メソッド名内で _ を使用して、トラバーサルポイントを手動で定義します。メソッド名は次のようになります。

List<Person> findByAddress_ZipCode(ZipCode zipCode);

アンダースコア文字を予約文字として扱うため、標準の Java 命名規則に従うことを強くお勧めします（つまり、プロパティ名にアンダースコアを使用せず、代わりにキャメルケースを使用します）。

4.4.4. 特別なパラメーター処理

クエリでパラメーターを処理するには、前の例ですでに見たようにメソッドパラメーターを定義します。それに加えて、インフラストラクチャは Pageable や Sort などの特定の型を認識し、ページネーションとソートをクエリに動的に適用します。次の例は、これらの機能を示しています。

例 14: クエリメソッドでの Pageable、Slice、Sort の使用

Page<User> findByLastname(String lastname, Pageable pageable);

Slice<User> findByLastname(String lastname, Pageable pageable);

List<User> findByLastname(String lastname, Sort sort);

List<User> findByLastname(String lastname, Pageable pageable);

Sort および Pageable を使用する API は、非 null 値がメソッドに渡されることを想定しています。並べ替えやページ付けを適用したくない場合は、Sort.unsorted() と Pageable.unpaged() を使用してください。

最初のメソッドでは、org.springframework.data.domain.Pageable インスタンスをクエリメソッドに渡して、静的に定義されたクエリにページングを動的に追加できます。Page は、使用可能な要素とページの総数を認識しています。これは、インフラストラクチャがカウントクエリをトリガーして全体の数を計算することによって行われます。これは（使用するストアによっては）高額になる可能性があるため、代わりに Slice を返すことができます。Slice は、次の Slice が使用可能かどうかのみを認識します。これは、より大きな結果セットをウォークスルーする場合に十分な場合があります。

並べ替えオプションも Pageable インスタンスを介して処理されます。並べ替えのみが必要な場合は、メソッドに org.springframework.data.domain.Sort パラメーターを追加します。ご覧のとおり、List を返すことも可能です。この場合、実際の Page インスタンスを構築するために必要な追加のメタデータは作成されません（つまり、必要だったはずの追加のカウントクエリは発行されません）。むしろ、指定された範囲のエンティティのみを検索するようにクエリを制限します。

クエリ全体で取得するページ数を調べるには、追加のカウントクエリをトリガーする必要があります。デフォルトでは、このクエリは実際にトリガーするクエリから派生します。

ページングとソート

プロパティ名を使用して、簡単な並べ替え式を定義できます。式を連結して、複数の条件を 1 つの式に集めることができます。

例 15: ソート式の定義

Sort sort = Sort.by("firstname").ascending()
  .and(Sort.by("lastname").descending());

ソート式を定義するためのより型安全な方法については、ソート式を定義する型から始め、メソッド参照を使用してソートするプロパティを定義します。

例 16: 型安全 API を使用したソート式の定義

TypedSort<Person> person = Sort.sort(Person.class);

Sort sort = person.by(Person::getFirstname).ascending()
  .and(person.by(Person::getLastname).descending());

TypedSort.by(…) は、（通常）CGlib を使用してランタイムプロキシを利用します。これは、Graal VMNative などのツールを使用するときにネイティブイメージのコンパイルを妨げる可能性があります。

ストアの実装が Querydsl をサポートしている場合は、生成されたメタモデル型を使用して、並べ替え式を定義することもできます。

例 17: QuerydslAPI を使用したソート式の定義

QSort sort = QSort.by(QPerson.firstname.asc())
  .and(QSort.by(QPerson.lastname.desc()));

4.4.5. クエリ結果の制限

first または top キーワードを使用して、クエリメソッドの結果を制限できます。これらのキーワードは、同じ意味で使用できます。オプションの数値を top または first に追加して、返される最大結果サイズを指定できます。数値が省略されている場合、結果サイズは 1 と見なされます。次の例は、クエリサイズを制限する方法を示しています。

例 18: Top および First を使用したクエリの結果サイズの制限

User findFirstByOrderByLastnameAsc();

User findTopByOrderByAgeDesc();

Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);

Slice<User> findTop3ByLastname(String lastname, Pageable pageable);

List<User> findFirst10ByLastname(String lastname, Sort sort);

List<User> findTop10ByLastname(String lastname, Pageable pageable);

制限式は、個別のクエリをサポートするデータストアの Distinct キーワードもサポートします。また、結果セットを 1 つのインスタンスに制限するクエリの場合、結果を Optional キーワードでラップすることがサポートされています。

ページネーションまたはスライスが制限クエリページネーション（および使用可能なページ数の計算）に適用される場合、制限された結果内で適用されます。

Sort パラメーターを使用して動的ソートと組み合わせて結果を制限すると、"K" 最小エレメントと "K" 最大エレメントの照会メソッドを表現できます。

4.4.6. コレクションまたはイテラブルを返すリポジトリメソッド

複数の結果を返すクエリメソッドは、標準の Java Iterable、List、Set を使用できます。さらに、Spring Data の Streamable、Iterable のカスタム拡張、Vavr (英語) によって提供されるコレクション型を返すことをサポートします。考えられるすべてのクエリメソッドの戻り値の型について説明している付録を参照してください。

Streamable をクエリメソッドの戻り値の型として使用する

Iterable または任意のコレクション型の代わりに Streamable を使用できます。これは、非並列 Stream （Iterable にはない）にアクセスするための便利なメソッドと、要素を介して … .filter(…) および … .map(…) を直接アクセスし、Streamable を他の要素に連結する機能を提供します。

例 19: Streamable を使用してクエリメソッドの結果を結合する

interface PersonRepository extends Repository<Person, Long> {
  Streamable<Person> findByFirstnameContaining(String firstname);
  Streamable<Person> findByLastnameContaining(String lastname);
}

Streamable<Person> result = repository.findByFirstnameContaining("av")
  .and(repository.findByLastnameContaining("ea"));

カスタムのストリーミング可能なラッパー型を返す

コレクション専用のラッパー型を提供することは、複数の要素を返すクエリ結果の API を提供するために一般的に使用されるパターンです。通常、これらの型は、コレクションのような型を返すリポジトリメソッドを呼び出し、ラッパー型のインスタンスを手動で作成することによって使用されます。Spring Data では、次の条件を満たす場合、これらのラッパー型をクエリメソッドの戻り値の型として使用できるため、この追加の手順を回避できます。

型は Streamable を実装します。
この型は、Streamable を引数として取る of(…) または valueOf(…) という名前のコンストラクターまたは静的ファクトリメソッドのいずれかを公開します。

次のリストに例を示します。

class Product {                                         (1)
  MonetaryAmount getPrice() { … }
}

@RequiredArgsConstructor(staticName = "of")
class Products implements Streamable<Product> {         (2)

  private final Streamable<Product> streamable;

  public MonetaryAmount getTotal() {                    (3)
    return streamable.stream()
      .map(Priced::getPrice)
      .reduce(Money.of(0), MonetaryAmount::add);
  }


  @Override
  public Iterator<Product> iterator() {                 (4)
    return streamable.iterator();
  }
}

interface ProductRepository implements Repository<Product, Long> {
  Products findAllByDescriptionContaining(String text); (5)
}

1	製品の価格にアクセスするための API を公開する `Product` エンティティ。
2	`Products.of(…)` （Lombok アノテーションを使用して作成されたファクトリメソッド）を使用して構築できる `Streamable<Product>` のラッパー型。`Streamable<Product>` を使用する標準のコンストラクターも同様に機能します。
3	ラッパー型は追加の API を公開し、`Streamable<Product>` で新しい値を計算します。
4	`Streamable` インターフェースを実装し、実際の結果に委譲します。
5	そのラッパー型 `Products` は、クエリメソッドの戻り値の型として直接使用できます。`Streamable<Product>` を返し、リポジトリクライアントでクエリの後に手動でラップする必要はありません。

Vavr コレクションのサポート

Vavr (英語) は、Java の関数型プログラミングの概念を取り入れたライブラリです。次の表に示すように、クエリメソッドの戻り値の型として使用できるコレクション型のカスタムセットが付属しています。

Vavr コレクション型使用される Vavr 実装型有効な Java ソース型

Vavr コレクション型	使用される Vavr 実装型	有効な Java ソース型
`io.vavr.collection.Seq`	`io.vavr.collection.List`	`java.util.Iterable`
`io.vavr.collection.Set`	`io.vavr.collection.LinkedHashSet`	`java.util.Iterable`
`io.vavr.collection.Map`	`io.vavr.collection.LinkedHashMap`	`java.util.Map`

io.vavr.collection.Seq

io.vavr.collection.List

java.util.Iterable

io.vavr.collection.Set

io.vavr.collection.LinkedHashSet

java.util.Iterable

io.vavr.collection.Map

io.vavr.collection.LinkedHashMap

java.util.Map

実際のクエリ結果の Java 型（3 番目の列）に応じて、最初の列の型（またはそのサブ型）をクエリメソッドの戻り値の型として使用し、実装型として使用される 2 番目の列の型を取得できます。または、Traversable （Vavr Iterable と同等）を宣言して、実際の戻り値から実装クラスを導出することもできます。つまり、java.util.List は Vavr List または Seq に変換され、java.util.Set は Vavr LinkedHashSet Set に変換されます。

4.4.7. リポジトリメソッドの null 処理

Spring Data 2.0 以降、個々の集約インスタンスを返すリポジトリ CRUD メソッドは、Java 8 の Optional を使用して、値が存在しない可能性があることを示します。さらに、Spring Data はクエリメソッドで次のラッパー型を返すことをサポートしています。

com.google.common.base.Optional
scala.Option
io.vavr.control.Option

または、クエリメソッドは、ラッパー型をまったく使用しないことを選択できます。null を返すことにより、クエリ結果がないことが示されます。コレクション、コレクションの代替、ラッパー、ストリームを返すリポジトリメソッドは、null ではなく、対応する空の表現を返すことが保証されています。詳細については、"リポジトリクエリの戻り値の型" を参照してください。

Nullability アノテーション

Spring Framework の nullability アノテーションを使用して、リポジトリメソッドの nullability 制約を表現できます。これらは、次のように、実行時にツールに優しいアプローチとオプトイン null チェックを提供します。

@NonNullApi (Javadoc) : パッケージレベルで使用され、パラメーターと戻り値のデフォルトの動作が、それぞれ null 値を受け入れることも生成することもないことを宣言します。
@NonNull (Javadoc) : null であってはならないパラメーターまたは戻り値で使用されます（@NonNullApi が適用されるパラメーターおよび戻り値では不要です）。
@Nullable (Javadoc) : null の可能性があるパラメーターまたは戻り値で使用されます。

Spring アノテーションは、JSR 305 (英語) アノテーション（休止中ですが広く使用されている JSR）でメタアノテーションが付けられています。JSR 305 メタアノテーションにより、ツールベンダー（IDEA (英語) 、Eclipse (英語) 、Kotlin (英語) など）は、Spring アノテーションのサポートをハードコードすることなく、一般的な方法で null-safety サポートを提供できます。クエリメソッドの null 可能性制約のランタイムチェックを有効にするには、次の例に示すように、package-info.java で Spring の @NonNullApi を使用して、パッケージレベルで非 null 可能性をアクティブ化する必要があります。

例 20: package-info.java で非 null 可能性を宣言する

@org.springframework.lang.NonNullApi
package com.acme;

null 以外のデフォルトが設定されると、リポジトリクエリメソッドの呼び出しは、実行時に null 可能性の制約について検証されます。クエリ結果が定義された制約に違反している場合、例外がスローされます。これは、メソッドが null を返すが、null 許容ではないと宣言されている場合に発生します（リポジトリが存在するパッケージで定義されたアノテーションのデフォルト）。null 許容の結果に再度オプトインする場合は、個々のメソッドで @Nullable を選択的に使用します。このセクションの冒頭で説明した結果ラッパー型を使用すると、引き続き期待どおりに機能します。空の結果は、不在を表す値に変換されます。

次の例は、今説明したいくつかの手法を示しています。

例 21: さまざまな null 値制約を使用する

package com.acme;                                                       (1)

import org.springframework.lang.Nullable;

interface UserRepository extends Repository<User, Long> {

  User getByEmailAddress(EmailAddress emailAddress);                    (2)

  @Nullable
  User findByEmailAddress(@Nullable EmailAddress emailAdress);          (3)

  Optional<User> findOptionalByEmailAddress(EmailAddress emailAddress); (4)
}

1	リポジトリは、null 以外の動作を定義したパッケージ（またはサブパッケージ）にあります。
2	クエリで結果が生成されない場合は、`EmptyResultDataAccessException` をスローします。メソッドに渡された `emailAddress` が `null` の場合、`IllegalArgumentException` をスローします。
3	クエリが結果を生成しない場合、`null` を返します。`emailAddress` の値として `null` も受け入れます。
4	クエリが結果を生成しない場合、`Optional.empty()` を返します。メソッドに渡された `emailAddress` が `null` の場合、`IllegalArgumentException` をスローします。

Kotlin ベースのリポジトリの Nullability

Kotlin には、言語に組み込まれた null 可能性制約 (英語) の定義があります。Kotlin コードはバイトコードにコンパイルされます。これは、メソッドシグネチャーではなく、コンパイルされたメタデータを通じて nullability 制約を表現しません。kotlin-reflect JAR をプロジェクトに含めて、Kotlin の nullability 制約のイントロスペクションを有効にしてください。Spring Data リポジトリは、言語メカニズムを使用してこれらの制約を定義し、次のように同じランタイムチェックを適用します。

例 22: Kotlin リポジトリでの null 可能性制約の使用

interface UserRepository : Repository<User, String> {

  fun findByUsername(username: String): User     (1)

  fun findByFirstname(firstname: String?): User? (2)
}

1	このメソッドは、パラメーターと結果の両方を null 不可（Kotlin のデフォルト）として定義します。Kotlin コンパイラーは、`null` をメソッドに渡すメソッド呼び出しを拒否します。クエリで空の結果が得られた場合、`EmptyResultDataAccessException` がスローされます。
2	このメソッドは、`firstname` パラメーターに `null` を受け入れ、クエリで結果が生成されない場合は `null` を返します。

4.4.8. クエリ結果のストリーミング

戻り値の型として Java 8 Stream<T> を使用することにより、クエリメソッドの結果を段階的に処理できます。次の例に示すように、クエリ結果を Stream でラップする代わりに、データストア固有のメソッドを使用してストリーミングを実行します。

例 23: Java 8 Stream<T> を使用したクエリの結果のストリーミング

@Query("select u from User u")
Stream<User> findAllByCustomQueryAndStream();

Stream<User> readAllByFirstnameNotNull();

@Query("select u from User u")
Stream<User> streamAllPaged(Pageable pageable);

Stream は潜在的に基礎となるデータストア固有のリソースをラップするため、使用後に閉じる必要があります。次の例に示すように、close() メソッドを使用するか、Java 7 try-with-resources ブロックを使用して、Stream を手動で閉じることができます。

例 24: Stream<T> を操作すると、try-with-resources ブロックが生成されます

try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
  stream.forEach(…);
}

現在、すべての Spring Data モジュールが戻り型として Stream<T> をサポートしているわけではありません。

4.4.9. 非同期クエリ結果

Spring の非同期メソッド実行機能を使用すると、リポジトリクエリを非同期で実行できます。これは、Spring TaskExecutor に送信されたタスクで実際のクエリが発生している間、メソッドは呼び出し直後に戻ることを意味します。非同期クエリはリアクティブクエリとは異なるため、混在させないでください。リアクティブサポートの詳細については、ストア固有のドキュメントを参照してください。次の例は、いくつかの非同期クエリを示しています。

@Async
Future<User> findByFirstname(String firstname);               (1)

@Async
CompletableFuture<User> findOneByFirstname(String firstname); (2)

1	戻り値の型として `java.util.concurrent.Future` を使用します。
2	戻り値の型として Java 8 `java.util.concurrent.CompletableFuture` を使用します。

4.5. リポジトリインスタンスの作成

このセクションでは、定義されたリポジトリインターフェースのインスタンスと Bean 定義を作成する方法について説明します。

4.5.1. Java 構成

Java 構成クラスでストア固有の @EnableJpaRepositories アノテーションを使用して、リポジトリのアクティブ化の構成を定義します。Spring コンテナーの Java ベースの構成の概要については、Spring リファレンスドキュメントの JavaConfig を参照してください。

Spring Data リポジトリを有効にするサンプル構成は次のようになります。

例 25: アノテーションベースのリポジトリ構成のサンプル

@Configuration
@EnableJpaRepositories("com.acme.repositories")
class ApplicationConfiguration {

  @Bean
  EntityManagerFactory entityManagerFactory() {
    // …
  }
}

上記の例では、JPA 固有のアノテーションを使用しています。これは、実際に使用するストアモジュールに応じて変更します。同じことが EntityManagerFactory Bean の定義にも当てはまります。ストア固有の構成について説明しているセクションを参照してください。

4.5.2. XML 構成

次の例に示すように、各 Spring Data モジュールには、Spring がスキャンする基本パッケージを定義できる repositories 要素が含まれています。

例 26: XML を介した Spring Data リポジトリの有効化

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

  <jpa:repositories base-package="com.acme.repositories" />

</beans:beans>

前の例では、Spring は、Repository またはそのサブインターフェースの 1 つを継承するインターフェースについて、com.acme.repositories とそのすべてのサブパッケージをスキャンするように指示されています。見つかったインターフェースごとに、インフラストラクチャは永続化テクノロジ固有の FactoryBean を登録して、クエリメソッドの呼び出しを処理する適切なプロキシを作成します。各 Bean は、インターフェース名から派生した Bean 名で登録されるため、UserRepository のインターフェースは userRepository で登録されます。ネストされたリポジトリインターフェースの Bean 名には、囲む型名がプレフィックスとして付けられます。基本パッケージ属性ではワイルドカードを使用できるため、スキャンされたパッケージのパターンを定義できます。

4.5.3. フィルターの使用

デフォルトでは、インフラストラクチャは、構成された基本パッケージにある永続化テクノロジー固有の Repository サブインターフェースを継承するすべてのインターフェースを選択し、そのための Bean インスタンスを作成します。ただし、どのインターフェースに Bean インスタンスが作成されているかをより細かく制御したい場合があります。これを行うには、リポジトリ宣言内でフィルター要素を使用します。セマンティクスは、Spring のコンポーネントフィルターの要素とまったく同じです。詳細については、これらの要素の Spring リファレンスドキュメントを参照してください。

例: 特定のインターフェースをリポジトリ Bean としてインスタンス化から除外するには、次の構成を使用できます。

例 27: フィルターを使う

Java

@Configuration
@EnableJpaRepositories(basePackages = "com.acme.repositories",
    includeFilters = { @Filter(type = FilterType.REGEX, pattern = ".*SomeRepository") },
    excludeFilters = { @Filter(type = FilterType.REGEX, pattern = ".*SomeOtherRepository") })
class ApplicationConfiguration {

  @Bean
  EntityManagerFactory entityManagerFactory() {
    // …
  }
}

XML

<repositories base-package="com.acme.repositories">
  <context:exclude-filter type="regex" expression=".*SomeRepository" />
  <context:include-filter type="regex" expression=".*SomeOtherRepository" />
</repositories>

前の例では、SomeRepository で終わるすべてのインターフェースをインスタンス化から除外し、SomeOtherRepository で終わるインターフェースを含めます。

4.5.4. スタンドアロンの使用箇所

Spring コンテナーの外部（CDI 環境など）でリポジトリインフラストラクチャを使用することもできます。クラスパスにはまだいくつかの Spring ライブラリが必要ですが、通常は、プログラムでリポジトリを設定することもできます。リポジトリサポートを提供する Spring Data モジュールには、次のように使用できる永続化テクノロジ固有の RepositoryFactory が付属しています。

例 28: リポジトリファクトリのスタンドアロン使用

RepositoryFactorySupport factory = … // Instantiate factory here
UserRepository repository = factory.getRepository(UserRepository.class);

4.6. Spring Data リポジトリのカスタム実装

Spring Data は、コーディングをほとんど行わずにクエリメソッドを作成するためのさまざまなオプションを提供します。ただし、これらのオプションがニーズに合わない場合は、リポジトリメソッドの独自のカスタム実装を提供することもできます。このセクションでは、その方法について説明します。

4.6.1. 個々のリポジトリのカスタマイズ

カスタム機能でリポジトリを強化するには、最初に、次のように、フラグメントインターフェースとカスタム機能の実装を定義する必要があります。

例 29: カスタムリポジトリ機能のインターフェース

interface CustomizedUserRepository {
  void someCustomMethod(User user);
}

例 30: カスタムリポジトリ機能の実装

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  public void someCustomMethod(User user) {
    // Your custom implementation
  }
}

フラグメントインターフェースに対応するクラス名の最も重要な部分は、Impl 後置です。

実装自体は Spring Data に依存せず、通常の Spring Bean にすることができます。そのため、標準の依存性注入動作を使用して、他の Bean（JdbcTemplate など）への参照を注入したり、アスペクトに参加したりすることができます。

次に、次のように、リポジトリインターフェースにフラグメントインターフェースを継承させることができます。

例 31: リポジトリインターフェースの変更

interface UserRepository extends CrudRepository<User, Long>, CustomizedUserRepository {

  // Declare query methods here
}

リポジトリインターフェースでフラグメントインターフェースを拡張すると、CRUD とカスタム機能が組み合わされ、クライアントで使用できるようになります。

Spring Data リポジトリは、リポジトリ構成を形成するフラグメントを使用して実装されます。フラグメントは、基本リポジトリ、機能面（QueryDsl など）、カスタムインターフェースとその実装です。リポジトリインターフェースにインターフェースを追加するたびに、フラグメントを追加して構成を強化します。ベースリポジトリとリポジトリアスペクトの実装は、各 Spring Data モジュールによって提供されます。

次の例は、カスタムインターフェースとその実装を示しています。

例 32: 実装のフラグメント

interface HumanRepository {
  void someHumanMethod(User user);
}

class HumanRepositoryImpl implements HumanRepository {

  public void someHumanMethod(User user) {
    // Your custom implementation
  }
}

interface ContactRepository {

  void someContactMethod(User user);

  User anotherContactMethod(User user);
}

class ContactRepositoryImpl implements ContactRepository {

  public void someContactMethod(User user) {
    // Your custom implementation
  }

  public User anotherContactMethod(User user) {
    // Your custom implementation
  }
}

次の例は、CrudRepository を継承するカスタムリポジトリのインターフェースを示しています。

例 33: リポジトリインターフェースの変更

interface UserRepository extends CrudRepository<User, Long>, HumanRepository, ContactRepository {

  // Declare query methods here
}

リポジトリは、宣言の順序でインポートされる複数のカスタム実装で構成されます。カスタム実装は、基本実装およびリポジトリの側面よりも優先度が高くなります。この順序付けにより、ベースリポジトリおよびアスペクトメソッドをオーバーライドし、2 つのフラグメントが同じメソッドシグネチャーを提供する場合のあいまいさを解決できます。リポジトリフラグメントは、単一のリポジトリインターフェースでの使用に限定されません。複数のリポジトリがフラグメントインターフェースを使用し、異なるリポジトリでカスタマイズを再利用できる場合があります。

次の例は、リポジトリフラグメントとその実装を示しています。

例 34: save(…) をオーバーライドするフラグメント

interface CustomizedSave<T> {
  <S extends T> S save(S entity);
}

class CustomizedSaveImpl<T> implements CustomizedSave<T> {

  public <S extends T> S save(S entity) {
    // Your custom implementation
  }
}

次の例は、前述のリポジトリフラグメントを使用するリポジトリを示しています。

例 35: カスタマイズされたリポジトリインターフェース

interface UserRepository extends CrudRepository<User, Long>, CustomizedSave<User> {
}

interface PersonRepository extends CrudRepository<Person, Long>, CustomizedSave<Person> {
}

構成

リポジトリインフラストラクチャは、リポジトリが見つかったパッケージのクラスをスキャンして、カスタム実装フラグメントを自動検出しようとします。これらのクラスは、デフォルトで Impl になる接尾辞を追加するという命名規則に従う必要があります。

次の例は、デフォルトの接尾辞を使用するリポジトリと、接尾辞のカスタム値を設定するリポジトリを示しています。

例 36: 構成例

Java

@EnableJpaRepositories(repositoryImplementationPostfix = "MyPostfix")
class Configuration { … }

XML

<repositories base-package="com.acme.repository" />

<repositories base-package="com.acme.repository" repository-impl-postfix="MyPostfix" />

前の例の最初の構成は、カスタムリポジトリ実装として機能する com.acme.repository.CustomizedUserRepositoryImpl というクラスを検索しようとします。2 番目の例では、com.acme.repository.CustomizedUserRepositoryMyPostfix を検索しようとします。

あいまいさの解決

一致するクラス名を持つ複数の実装が異なるパッケージで見つかった場合、Spring Data は Bean 名を使用して、使用する実装を識別します。

前に示した CustomizedUserRepository の次の 2 つのカスタム実装を考えると、最初の実装が使用されます。その Bean 名は customizedUserRepositoryImpl であり、これはフラグメントインターフェース（CustomizedUserRepository）の名前と接尾辞 Impl に一致します。

例 37: あいまいな実装の解決

package com.acme.impl.one;

class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  // Your custom implementation
}

package com.acme.impl.two;

@Component("specialCustomImpl")
class CustomizedUserRepositoryImpl implements CustomizedUserRepository {

  // Your custom implementation
}

UserRepository インターフェースに @Component("specialCustom") でアノテーションを付けると、Bean 名に Impl を加えたものが、com.acme.impl.two のリポジトリ実装用に定義されたものと一致し、最初のものの代わりに使用されます。

手動接続

カスタム実装でアノテーションベースの構成とオートワイヤーのみを使用する場合、上記のアプローチは他の Spring Bean と同様に処理されるため、上手く機能します。実装フラグメント Bean に特別な接続が必要な場合、Bean を宣言し、前のセクションで説明した規則に従って名前を付けることができます。インフラストラクチャは、Bean 定義を手動で作成する代わりに、名前で手動で定義したものを参照します。次の例は、カスタム実装を手動で接続する方法を示しています。

例 38: カスタム実装の手動接続

Java

class MyClass {
  MyClass(@Qualifier("userRepositoryImpl") UserRepository userRepository) {
    …
  }
}

XML

<repositories base-package="com.acme.repository" />

<beans:bean id="userRepositoryImpl" class="…">
  <!-- further configuration -->
</beans:bean>

4.6.2. ベースリポジトリをカスタマイズする

前のセクションで説明したアプローチでは、ベースリポジトリの動作をカスタマイズしてすべてのリポジトリが影響を受けるようにする場合、各リポジトリインターフェースをカスタマイズする必要があります。代わりに、すべてのリポジトリの動作を変更するために、永続化テクノロジ固有のリポジトリベースクラスを継承する実装を作成できます。このクラスは、次の例に示すように、リポジトリプロキシのカスタムベースクラスとして機能します。

例 39: カスタムリポジトリベースクラス

class MyRepositoryImpl<T, ID>
  extends SimpleJpaRepository<T, ID> {

  private final EntityManager entityManager;

  MyRepositoryImpl(JpaEntityInformation entityInformation,
                          EntityManager entityManager) {
    super(entityInformation, entityManager);

    // Keep the EntityManager around to used from the newly introduced methods.
    this.entityManager = entityManager;
  }

  @Transactional
  public <S extends T> S save(S entity) {
    // implementation goes here
  }
}

このクラスには、ストア固有のリポジトリファクトリ実装が使用するスーパークラスのコンストラクターが必要です。リポジトリの基本クラスに複数のコンストラクターがある場合は、EntityInformation とストア固有のインフラストラクチャオブジェクト（EntityManager またはテンプレートクラスなど）を取得するコンストラクターをオーバーライドします。

最後のステップは、カスタマイズされたリポジトリ基本クラスを Spring Data インフラストラクチャに認識させることです。構成では、次の例に示すように、repositoryBaseClass を使用してこれを行うことができます。

例 40: カスタムリポジトリ基本クラスの構成

Java

@Configuration
@EnableJpaRepositories(repositoryBaseClass = MyRepositoryImpl.class)
class ApplicationConfiguration { … }

XML

<repositories base-package="com.acme.repository"
     base-class="….MyRepositoryImpl" />

4.7. 集約ルートからのイベントの公開

リポジトリによって管理されるエンティティは、集約ルートです。ドメイン駆動設計アプリケーションでは、これらの集約ルートは通常、ドメインイベントを発行します。Spring Data は、@DomainEvents と呼ばれるアノテーションを提供します。これは、次の例に示すように、集約パブリケーションのメソッドで使用して、その公開をできるだけ簡単にすることができます。

例 41: 集約ルートからのドメインイベントの公開

class AnAggregateRoot {

    @DomainEvents (1)
    Collection<Object> domainEvents() {
        // … return events you want to get published here
    }

    @AfterDomainEventPublication (2)
    void callbackMethod() {
       // … potentially clean up domain events list
    }
}

1	`@DomainEvents` を使用するメソッドは、単一のイベントインスタンスまたはイベントのコレクションのいずれかを返すことができます。引数を取ってはいけません。
2	すべてのイベントが公開された後、`@AfterDomainEventPublication` でアノテーションが付けられたメソッドがあります。これを使用して、公開するイベントのリストを（他の用途の中でも）潜在的にクリーンアップできます。

メソッドは、Spring Data リポジトリの save(…)、saveAll(…)、delete(…) または deleteAll(…) メソッドのいずれかが呼び出されるたびに呼び出されます。

4.8. Spring Data 拡張

このセクションでは、さまざまなコンテキストで Spring Data を使用できるようにする一連の Spring Data 拡張について説明します。現在、ほとんどの統合は Spring MVC を対象としています。

4.8.1. Querydsl 拡張

Querydsl (英語) は、流れるような API を使用して、静的に型指定された SQL のようなクエリの構築を可能にするフレームワークです。

次の例に示すように、いくつかの Spring Data モジュールは、QuerydslPredicateExecutor を介して Querydsl との統合を提供します。

例 42: QuerydslPredicateExecutor インターフェース

public interface QuerydslPredicateExecutor<T> {

  Optional<T> findById(Predicate predicate);  (1)

  Iterable<T> findAll(Predicate predicate);   (2)

  long count(Predicate predicate);            (3)

  boolean exists(Predicate predicate);        (4)

  // … more functionality omitted.
}

1	`Predicate` に一致する単一のエンティティを検索して返します。
2	`Predicate` に一致するすべてのエンティティを検索して返します。
3	`Predicate` に一致するエンティティの数を返します。
4	`Predicate` に一致するエンティティが存在するかどうかを返します。

Querydsl サポートを使用するには、次の例に示すように、リポジトリインターフェースで QuerydslPredicateExecutor を継承します。

例 43: リポジトリでの Querydsl 統合

interface UserRepository extends CrudRepository<User, Long>, QuerydslPredicateExecutor<User> {
}

前の例では、次の例に示すように、Querydsl Predicate インスタンスを使用して型安全なクエリを記述できます。

Predicate predicate = user.firstname.equalsIgnoreCase("dave")
	.and(user.lastname.startsWithIgnoreCase("mathews"));

userRepository.findAll(predicate);

4.8.2. Web サポート

リポジトリプログラミングモデルをサポートする Spring Data モジュールには、さまざまな Web サポートが付属しています。Web 関連のコンポーネントでは、Spring MVC JAR がクラスパス上にある必要があります。それらのいくつかは、Spring HATEOAS [GitHub] (英語) との統合さえ提供します。一般に、統合サポートは、次の例に示すように、JavaConfig 構成クラスで @EnableSpringDataWebSupport アノテーションを使用することで有効になります。

例 44: Spring Data Web サポートの有効化

Java

@Configuration
@EnableWebMvc
@EnableSpringDataWebSupport
class WebConfiguration {}

XML

<bean class="org.springframework.data.web.config.SpringDataWebConfiguration" />

<!-- If you use Spring HATEOAS, register this one *instead* of the former -->
<bean class="org.springframework.data.web.config.HateoasAwareSpringDataWebConfiguration" />

@EnableSpringDataWebSupport アノテーションは、いくつかのコンポーネントを登録します。これらについては、このセクションの後半で説明します。また、クラスパスで Spring HATEOAS を検出し、統合コンポーネント（存在する場合）も登録します。

基本的な Web サポート

XML で Spring Data Web サポートを有効にする

前のセクションで示した構成は、いくつかの基本的なコンポーネントを登録します。

Spring MVC がリクエストパラメーターまたはパス変数からリポジトリ管理ドメインクラスのインスタンスを解決できるようにする DomainClassConverter クラスの使用。
Spring MVC がリクエストパラメーターから Pageable および Sort インスタンスを解決できるようにする HandlerMethodArgumentResolver 実装。
Jackson モジュールは、使用する Spring Data モジュールに応じて、Point や Distance などの型を逆 / 直列化するか、特定の型を格納します。

`DomainClassConverter` クラスの使用

DomainClassConverter クラスを使用すると、Spring MVC コントローラーメソッドシグネチャーでドメイン型を直接使用できるため、次の例に示すように、リポジトリからインスタンスを手動で検索する必要がありません。

例 45: メソッドシグネチャーでドメイン型を使用する Spring MVC コントローラー

@Controller
@RequestMapping("/users")
class UserController {

  @RequestMapping("/{id}")
  String showUserForm(@PathVariable("id") User user, Model model) {

    model.addAttribute("user", user);
    return "userForm";
  }
}

このメソッドは User インスタンスを直接受け取り、それ以上のルックアップは必要ありません。インスタンスは、Spring MVC が最初にパス変数をドメインクラスの id 型に変換し、最終的にドメイン型に登録されたリポジトリインスタンスで findById(…) を呼び出してインスタンスにアクセスすることで解決できます。

現在、リポジトリは変換のために発見される資格があるために CrudRepository を実装しなければなりません。

ページング可能およびソート用の HandlerMethodArgumentResolvers

前のセクションで示した構成スニペットは、PageableHandlerMethodArgumentResolver と SortHandlerMethodArgumentResolver のインスタンスも登録します。次の例に示すように、登録により、Pageable および Sort が有効なコントローラーメソッド引数として有効になります。

例 46: コントローラーメソッドの引数として Pageable を使用する

@Controller
@RequestMapping("/users")
class UserController {

  private final UserRepository repository;

  UserController(UserRepository repository) {
    this.repository = repository;
  }

  @RequestMapping
  String showUsers(Model model, Pageable pageable) {

    model.addAttribute("users", repository.findAll(pageable));
    return "users";
  }
}

上記のメソッドシグネチャーにより、Spring MVC は、次のデフォルト構成を使用して、リクエストパラメーターから Pageable インスタンスを派生させようとします。

表 1: `Pageable` インスタンスについて評価されたリクエストパラメーター
`page`	取得するページ。0 からインデックス付けされ、デフォルトは 0 です。
`size`	取得するページのサイズ。デフォルトは 20 です。
`sort`	`property,property(,ASC\|DESC)(,IgnoreCase)` の形式で並べ替える必要のあるプロパティ。デフォルトの並べ替え方向では、大文字と小文字が区別されます。方向や大文字と小文字の区別を切り替える場合は、複数の `sort` パラメーターを使用します（例: `?sort=firstname&sort=lastname,asc&sort=city,ignorecase`）。

この動作をカスタマイズするには、PageableHandlerMethodArgumentResolverCustomizer インターフェースまたは SortHandlerMethodArgumentResolverCustomizer インターフェースをそれぞれ実装する Bean を登録します。次の例に示すように、customize() メソッドが呼び出され、設定を変更できます。

@Bean SortHandlerMethodArgumentResolverCustomizer sortCustomizer() {
    return s -> s.setPropertyDelimiter("<-->");
}

既存の MethodArgumentResolver のプロパティを設定するだけでは目的に合わない場合は、SpringDataWebConfiguration または HATEOAS 対応の拡張機能を継承し、pageableResolver() または sortResolver() メソッドをオーバーライドし、@Enable アノテーションを使用する代わりにカスタマイズした構成ファイルをインポートします。

リクエストから複数の Pageable または Sort インスタンスを解決する必要がある場合（たとえば、複数のテーブルの場合）、Spring の @Qualifier アノテーションを使用して互いに区別できます。次に、リクエストパラメーターの前に ${qualifier}_ を付ける必要があります。次の例は、結果のメソッドシグネチャーを示しています。

String showUsers(Model model,
      @Qualifier("thing1") Pageable first,
      @Qualifier("thing2") Pageable second) { … }

thing1_page、thing2_page などを設定する必要があります。

メソッドに渡されるデフォルトの Pageable は PageRequest.of(0, 20) と同等ですが、Pageable パラメーターの @PageableDefault アノテーションを使用してカスタマイズできます。

Pageable のハイパーメディアサポート

Spring HATEOAS には、表現モデルクラス（PagedResources）が付属しています。これにより、Page インスタンスのコンテンツを、必要な Page メタデータと、クライアントがページを簡単にナビゲートできるようにするリンクで強化できます。Page から PagedResources への変換は、PagedResourcesAssembler と呼ばれる Spring HATEOAS ResourceAssembler インターフェースの実装によって行われます。次の例は、PagedResourcesAssembler をコントローラーメソッドの引数として使用する方法を示しています。

例 47: コントローラーメソッドの引数として PagedResourcesAssembler を使用する

@Controller
class PersonController {

  @Autowired PersonRepository repository;

  @RequestMapping(value = "/persons", method = RequestMethod.GET)
  HttpEntity<PagedResources<Person>> persons(Pageable pageable,
    PagedResourcesAssembler assembler) {

    Page<Person> persons = repository.findAll(pageable);
    return new ResponseEntity<>(assembler.toResources(persons), HttpStatus.OK);
  }
}

前の例に示すように、構成を有効にすると、PagedResourcesAssembler をコントローラーメソッドの引数として使用できます。その上で toResources(…) を呼び出すと、次の効果があります。

Page のコンテンツは、PagedResources インスタンスのコンテンツになります。
PagedResources オブジェクトは PageMetadata インスタンスをアタッチし、Page および基礎となる PageRequest からの情報が取り込まれます。
PagedResources には、ページの状態に応じて、prev および next リンクが添付される場合があります。リンクは、メソッドがマップする URI を指します。メソッドに追加されたページネーションパラメーターは、PageableHandlerMethodArgumentResolver の設定と一致して、リンクを後で解決できるようにします。

データベースに 30 個の Person インスタンスがあると仮定します。これで、リクエスト（GET http://localhost:8080/persons）をトリガーして、次のような出力を確認できます。

{ "links" : [ { "rel" : "next",
                "href" : "http://localhost:8080/persons?page=1&size=20" }
  ],
  "content" : [
     … // 20 Person instances rendered here
  ],
  "pageMetadata" : {
    "size" : 20,
    "totalElements" : 30,
    "totalPages" : 2,
    "number" : 0
  }
}

アセンブラーは正しい URI を生成し、デフォルト構成を選択して、パラメーターを次のリクエストの Pageable に解決しました。つまり、その構成を変更すると、リンクは自動的に変更に準拠します。デフォルトでは、アセンブラーはそれが呼び出されたコントローラーメソッドを指しますが、ページネーションリンクを構築するためのベースとして使用されるカスタム Link を渡すことにより、それをカスタマイズできます。これにより、PagedResourcesAssembler.toResource(…) メソッドがオーバーロードされます。

Spring Data Jackson モジュール

コアモジュール、および一部のストア固有のモジュールには、Spring Data ドメインで使用される org.springframework.data.geo.Distance や org.springframework.data.geo.Point などの型の Jackson モジュールのセットが付属しています。
これらのモジュールは、Web サポートが有効になり、com.fasterxml.jackson.databind.ObjectMapper が使用可能になるとインポートされます。

初期化中に、SpringDataJacksonConfiguration と同様に SpringDataJacksonModules がインフラストラクチャによって取得されるため、宣言された com.fasterxml.jackson.databind.Module が Jackson ObjectMapper で使用できるようになります。

次のドメイン型のデータバインディングミックスインは、共通のインフラストラクチャによって登録されます。

org.springframework.data.geo.Distance
org.springframework.data.geo.Point
org.springframework.data.geo.Box
org.springframework.data.geo.Circle
org.springframework.data.geo.Polygon

個々のモジュールは、追加の SpringDataJacksonModules を提供する場合があります。
詳細については、ストア固有のセクションを参照してください。

Web データバインディングのサポート

次の例に示すように、Spring Data 射影（射影で説明）を使用して、JSONPath (英語) 式（Jayway JsonPath [GitHub] (英語) が必要）または XPath [W3C] (英語) 式（XmlBeam (英語) が必要）のいずれかを使用して、受信リクエストペイロードをバインドできます。

例 48: JSONPath または XPath 式を使用した HTTP ペイロードバインディング

@ProjectedPayload
public interface UserPayload {

  @XBRead("//firstname")
  @JsonPath("$..firstname")
  String getFirstname();

  @XBRead("/lastname")
  @JsonPath({ "$.lastname", "$.user.lastname" })
  String getLastname();
}

前の例に示されている型は、Spring MVC ハンドラーメソッドの引数として使用するか、RestTemplate のいずれかのメソッドで ParameterizedTypeReference を使用することで使用できます。上記のメソッド宣言は、指定されたドキュメント内の任意の場所で firstname を見つけようとします。lastname XML ルックアップは、受信ドキュメントのトップレベルで実行されます。の JSON バリアントは、トップレベルの lastname を最初に試行しますが、前者が値を返さない場合は、user サブドキュメントにネストされた lastname も試行します。こうすることで、クライアントが公開メソッドを呼び出さなくても、ソースドキュメントの構造の変更を簡単に軽減できます (通常、クラスベースのペイロードバインディングの欠点です)。

ネストされた射影は、射影に従ってサポートされます。メソッドがインターフェース以外の複雑な型を返す場合、Jackson ObjectMapper が最終値のマッピングに使用されます。

Spring MVC の場合、@EnableSpringDataWebSupport がアクティブになり、必要な依存関係がクラスパスで使用可能になるとすぐに、必要なコンバーターが自動的に登録されます。RestTemplate で使用する場合は、手動で ProjectingJackson2HttpMessageConverter (JSON) または XmlBeamHttpMessageConverter を登録します。

詳細については、標準の Spring Data サンプルリポジトリ [GitHub] (英語) の Web 射影の例 [GitHub] (英語) を参照してください。

Querydsl Web サポート

QueryDSL (英語) が統合されているストアの場合、Request クエリ文字列に含まれている属性からクエリを派生させることができます。

次のクエリ文字列を検討してください。

?firstname=Dave&lastname=Matthews

前の例の User オブジェクトが与えられた場合、次のように QuerydslPredicateArgumentResolver を使用して、クエリ文字列を次の値に解決できます。

QUser.user.firstname.eq("Dave").and(QUser.user.lastname.eq("Matthews"))

Querydsl がクラスパスで見つかると、この機能は @EnableSpringDataWebSupport とともに自動的に有効になります。

メソッドシグネチャーに @QuerydslPredicate を追加すると、すぐに使用できる Predicate が提供されます。これは、QuerydslPredicateExecutor を使用して実行できます。

型情報は通常、メソッドの戻り値型から解決されます。その情報は必ずしもドメイン型と一致しないため、QuerydslPredicate の root 属性を使用することをお勧めします。

次の例は、メソッドシグネチャーで @QuerydslPredicate を使用する方法を示しています。

@Controller
class UserController {

  @Autowired UserRepository repository;

  @RequestMapping(value = "/", method = RequestMethod.GET)
  String index(Model model, @QuerydslPredicate(root = User.class) Predicate predicate,    (1)
          Pageable pageable, @RequestParam MultiValueMap<String, String> parameters) {

    model.addAttribute("users", repository.findAll(predicate, pageable));

    return "index";
  }
}

1	`User` の一致する `Predicate` にクエリ文字列引数を解決します。

デフォルトのバインディングは次のとおりです。

eq としての単純なプロパティの Object。
contains のようなプロパティのようなコレクションの Object。
in としての単純なプロパティの Collection。

これらのバインディングは、@QuerydslPredicate の bindings 属性を使用するか、Java 8 default methods を使用して、次のようにリポジトリインターフェースに QuerydslBinderCustomizer メソッドを追加することによってカスタマイズできます。

interface UserRepository extends CrudRepository<User, String>,
                                 QuerydslPredicateExecutor<User>,                (1)
                                 QuerydslBinderCustomizer<QUser> {               (2)

  @Override
  default void customize(QuerydslBindings bindings, QUser user) {

    bindings.bind(user.username).first((path, value) -> path.contains(value))    (3)
    bindings.bind(String.class)
      .first((StringPath path, String value) -> path.containsIgnoreCase(value)); (4)
    bindings.excluding(user.password);                                           (5)
  }
}

1	`QuerydslPredicateExecutor` は、`Predicate` の特定のファインダーメソッドへのアクセスを提供します。
2	リポジトリインターフェースで定義された `QuerydslBinderCustomizer` が自動的に選択され、ショートカット `@QuerydslPredicate(bindings=…)` が選択されます。
3	`username` プロパティのバインディングを単純な `contains` バインディングとして定義します。
4	`String` プロパティのデフォルトのバインディングを、大文字と小文字を区別しない `contains` 一致になるように定義します。
5	`password` プロパティを `Predicate` 解決から除外します。

リポジトリまたは @QuerydslPredicate から特定のバインディングを適用する前に、デフォルトの Querydsl バインディングを保持する QuerydslBinderCustomizerDefaults Bean を登録できます。

4.8.3. リポジトリポピュレーター

Spring JDBC モジュールを使用している場合は、おそらく DataSource に SQL スクリプトを取り込むためのサポートに精通しているでしょう。同様の抽象化がリポジトリレベルで利用できますが、ストアに依存しない必要があるため、データ定義言語として SQL を使用しません。ポピュレーターは XML（Spring の OXM 抽象化による）と JSON（Jackson による）をサポートして、リポジトリにデータを取り込むデータを定義します。

次の内容の data.json というファイルがあるとします。

例 49: JSON で定義されたデータ

[ { "_class" : "com.acme.Person",
 "firstname" : "Dave",
  "lastname" : "Matthews" },
  { "_class" : "com.acme.Person",
 "firstname" : "Carter",
  "lastname" : "Beauford" } ]

Spring Data Commons で提供されるリポジトリ名前空間の populator 要素を使用して、リポジトリにデータを取り込むことができます。上記のデータを PersonRepository に入力するには、次のようなポピュレーターを宣言します。

例 50: Jackson リポジトリポピュレーターの宣言

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

  <repository:jackson2-populator locations="classpath:data.json" />

</beans>

上記の宣言により、data.json ファイルは Jackson ObjectMapper によって読み取られ、逆直列化されます。

JSON オブジェクトが非整列化される型は、JSON ドキュメントの _class 属性を調べることで決定されます。インフラストラクチャは最終的に、適切なリポジトリを選択して、デシリアライズされたオブジェクトを処理します。

代わりに、XML を使用してリポジトリにデータを取り込む必要のあるデータを定義するには、unmarshaller-populator エレメントを使用できます。Spring OXM で使用可能な XML マーシャラーオプションの 1 つを使用するように構成します。詳細については、Spring リファレンスドキュメントを参照してください。次の例は、JAXB を使用してリポジトリポピュレータをアンマーシャルする方法を示しています。

例 51: 非整列化リポジトリポピュレーターの宣言 (JAXB を使用する)

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:repository="http://www.springframework.org/schema/data/repository"
  xmlns:oxm="http://www.springframework.org/schema/oxm"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
    https://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/data/repository
    https://www.springframework.org/schema/data/repository/spring-repository.xsd
    http://www.springframework.org/schema/oxm
    https://www.springframework.org/schema/oxm/spring-oxm.xsd">

  <repository:unmarshaller-populator locations="classpath:data.json"
    unmarshaller-ref="unmarshaller" />

  <oxm:jaxb2-marshaller contextPath="com.acme" />

</beans>

5. リファレンスドキュメント

5.1. JPA リポジトリ

この章では、JPA のリポジトリサポートの専門分野について説明します。これは、"Spring Data リポジトリの操作" で説明されているコアリポジトリサポートに基づいています。そこに説明されている基本概念をしっかり理解していることを確認してください。

5.1.1. 導入

このセクションでは、次のいずれかの方法で Spring Data JPA を構成する基本について説明します。

“Spring ネームスペース” (XML 構成)
“アノテーションベースの構成” (Java 構成)

アノテーションベースの構成

次の例に示すように、Spring Data JPA リポジトリサポートは、JavaConfig とカスタム XML 名前空間の両方を介してアクティブ化できます。

例 52: JavaConfig を使用した Spring Data JPA リポジトリ

@Configuration
@EnableJpaRepositories
@EnableTransactionManagement
class ApplicationConfig {

  @Bean
  public DataSource dataSource() {

    EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
    return builder.setType(EmbeddedDatabaseType.HSQL).build();
  }

  @Bean
  public LocalContainerEntityManagerFactoryBean entityManagerFactory() {

    HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
    vendorAdapter.setGenerateDdl(true);

    LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
    factory.setJpaVendorAdapter(vendorAdapter);
    factory.setPackagesToScan("com.acme.domain");
    factory.setDataSource(dataSource());
    return factory;
  }

  @Bean
  public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {

    JpaTransactionManager txManager = new JpaTransactionManager();
    txManager.setEntityManagerFactory(entityManagerFactory);
    return txManager;
  }
}

EntityManagerFactory ではなく LocalContainerEntityManagerFactoryBean を直接作成する必要があります。前者は EntityManagerFactory の作成に加えて例外変換メカニズムにも参加しているためです。

上記の構成クラスは、spring-jdbc の EmbeddedDatabaseBuilder API を使用して、組み込み HSQL データベースをセットアップします。次に、Spring Data は EntityManagerFactory をセットアップし、Hibernate をサンプル永続プロバイダーとして使用します。ここで宣言された最後のインフラストラクチャコンポーネントは JpaTransactionManager です。最後に、この例では、@EnableJpaRepositories アノテーションを使用して Spring Data JPA リポジトリをアクティブ化します。@EnableJpaRepositories アノテーションは、本質的に XML 名前空間と同じ属性を保持します。基本パッケージが構成されていない場合、構成パッケージが存在するパッケージが使用されます。

Spring ネームスペース

Spring Data の JPA モジュールには、リポジトリ Bean を定義できるカスタム名前空間が含まれています。また、JPA に特有の特定の機能と要素属性も含まれています。一般に、次の例に示すように、repositories 要素を使用して JPA リポジトリを設定できます。

例 53: 名前空間を使用して JPA リポジトリを設定する

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

  <jpa:repositories base-package="com.acme.repositories" />

</beans>

JavaConfig と XML のどちらが優れていますか ? XML は、Spring がずっと前に構成された方法です。Java、レコード型、アノテーションなどが急速に成長している今日の時代では、通常、新しいプロジェクトではできる限り多くの純粋な Java が使用されます。XML サポートを削除する当面の計画はありませんが、最新の機能の一部は XML で利用できない場合があります。

repositories エレメントを使用すると、"リポジトリインスタンスの作成" に従って Spring Data リポジトリが検索されます。さらに、@Repository アノテーションが付けられたすべての Bean の永続性例外変換をアクティブにして、JPA 永続性プロバイダーによってスローされる例外を Spring の DataAccessException 階層に変換できるようにします。

カスタム名前空間属性

repositories 要素のデフォルト属性以外に、JPA 名前空間には追加の属性があり、リポジトリのセットアップをより詳細に制御できます。

表 2: `repositories` 要素のカスタム JPA 固有の属性
`entity-manager-factory-ref`	`EntityManagerFactory` を明示的に接続して、`repositories` 要素によって検出されるリポジトリで使用します。通常、アプリケーション内で複数の `EntityManagerFactory` Bean が使用される場合に使用されます。構成されていない場合、Spring Data は、`ApplicationContext` で `entityManagerFactory` という名前の `EntityManagerFactory` Bean を自動的に検索します。
`transaction-manager-ref`	`PlatformTransactionManager` を明示的に接続して、`repositories` 要素によって検出されるリポジトリで使用します。通常、複数のトランザクションマネージャーまたは `EntityManagerFactory` Bean が構成されている場合にのみ必要です。デフォルトは、現在の `ApplicationContext` 内の単一の定義済み `PlatformTransactionManager` です。

Spring Data JPA では、明示的な transaction-manager-ref が定義されていない場合、transactionManager という名前の PlatformTransactionManager Bean が存在する必要があります。

ブートストラップモード

デフォルトでは、Spring Data JPA リポジトリはデフォルトの Spring Bean です。それらはシングルトンスコープであり、先行初期化されます。起動時に、検証およびメタデータ分析のために、すでに JPA EntityManager と対話します。Spring Framework は、バックグラウンドスレッドで JPA EntityManagerFactory の初期化をサポートします。これは、そのプロセスが Spring アプリケーションで通常かなりの量の起動時間を費やしているためです。バックグラウンドの初期化を効果的に使用するには、JPA リポジトリができるだけ遅く初期化されるようにする必要があります。

Spring Data JPA 2.1 以降、次の値を取る BootstrapMode を（@EnableJpaRepositories アノテーションまたは XML 名前空間を介して）構成できるようになりました。

DEFAULT (default) — リポジトリは、明示的に @Lazy でアノテーションが付けられていない限り、先行してインスタンス化されます。クライアント Bean がリポジトリ Bean の初期化を必要とするため、リポジトリのインスタンスを必要としない場合にのみ、lazification が有効になります。
LAZY — 暗黙的にすべてのリポジトリ Bean を遅延宣言し、また、遅延初期化プロキシを作成してクライアント Bean に注入します。つまり、クライアント Bean がインスタンスをフィールドに単に格納し、初期化中にリポジトリを使用しない場合、そのリポジトリはインスタンス化されません。リポジトリインスタンスは、リポジトリとの最初の対話時に初期化および検証されます。
DEFERRED — 基本的に LAZY と同じ動作モードですが、ContextRefreshedEvent にレスポンスしてリポジトリの初期化をトリガーし、アプリケーションが完全に起動する前にリポジトリが検証されるようにします。

推奨

デフォルトのブートストラップモードで非同期 JPA ブートストラップスティックを使用していない場合。

JPA を非同期にブートストラップする場合、DEFERRED は、Spring Data JPA ブートストラップ自体が他のすべてのアプリケーションコンポーネントの初期化よりも時間がかかる場合にのみ EntityManagerFactory セットアップを待機するようにするため、妥当なデフォルトです。それでも、アプリケーションが起動する前に、リポジトリが適切に初期化および検証されるようにします。

LAZY は、シナリオのテストとローカル開発に適した選択肢です。リポジトリが適切にブートストラップできることを確認したら、またはアプリケーションの他の部分をテストしている場合は、すべてのリポジトリに対して検証を実行すると、起動時間が不必要に長くなる可能性があります。同じことが、単一のリポジトリを初期化する必要がある可能性のあるアプリケーションの部分にのみアクセスするローカル開発にも当てはまります。

5.1.2. 永続化エンティティ

このセクションでは、Spring Data JPA でエンティティを永続化（保存）する方法について説明します。

エンティティの保存

エンティティの保存は、CrudRepository.save(…) メソッドを使用して実行できます。基礎となる JPA EntityManager を使用して、指定されたエンティティを永続化またはマージします。エンティティがまだ永続化されていない場合、Spring Data JPA は entityManager.persist(…) メソッドの呼び出しでエンティティを保存します。それ以外の場合は、entityManager.merge(…) メソッドを呼び出します。

エンティティ状態検出戦略

Spring Data JPA は、エンティティが新しいかどうかを検出するために次の戦略を提供します。

Version-Property および Id-Property インスペクション（デフォルト）: デフォルトでは、Spring Data JPA は、非プリミティブ型のバージョンプロパティがあるかどうかを最初にインスペクションします。存在する場合、そのプロパティの値が null であれば、エンティティは新しいと見なされます。このようなバージョンプロパティがない場合、Spring Data JPA は指定されたエンティティの識別子プロパティをインスペクションします。識別子プロパティが null の場合、エンティティは新しいものと見なされます。それ以外の場合は、新しいものではないと見なされます。
Persistable の実装: エンティティが Persistable を実装している場合、Spring Data JPA は新しい検出をエンティティの isNew(…) メソッドに委譲します。詳細については、JavaDoc (Javadoc) を参照してください。
EntityInformation の実装: JpaRepositoryFactory のサブクラスを作成し、それに応じて getEntityInformation(…) メソッドをオーバーライドすることにより、SimpleJpaRepository 実装で使用される EntityInformation 抽象化をカスタマイズできます。次に、JpaRepositoryFactory のカスタム実装を Spring Bean として登録する必要があります。これはほとんど必要ないことに注意してください。詳細については、JavaDoc (Javadoc) を参照してください。

オプション 1 は、手動で割り当てられた識別子を使用するエンティティのオプションではなく、識別子が常に非 null になるため、バージョン属性はありません。そのシナリオの一般的なパターンは、新しいインスタンスを示すためにデフォルトの一時フラグを持つ共通の基本クラスを使用し、永続操作でそのフラグを反転するために JPA ライフサイクルコールバックを使用することです。

例 54: 手動で割り当てられた識別子を持つエンティティの基本クラス

@MappedSuperclass
public abstract class AbstractEntity<ID> implements Persistable<ID> {

  @Transient
  private boolean isNew = true; (1)

  @Override
  public boolean isNew() {
    return isNew; (2)
  }

  @PrePersist (3)
  @PostLoad
  void markNotNew() {
    this.isNew = false;
  }

  // More code…
}

1	新しい状態を保持するフラグを宣言します。一時的であるため、データベースに保持されません。
2	`Persistable.isNew()` の実装でフラグを返し、Spring Data リポジトリが `EntityManager.persist()` を呼び出すか `… .merge()` を呼び出すかを認識できるようにします。
3	JPA エンティティコールバックを使用してメソッドを宣言し、`save(…)` へのリポジトリ呼び出しまたは永続性プロバイダーによるインスタンス作成の後にフラグが既存のエンティティを示すように切り替えられるようにします。

5.1.3. クエリメソッド

このセクションでは、Spring Data JPA を使用してクエリを作成するさまざまな方法について説明します。

クエリ検索戦略

JPA モジュールは、クエリを文字列として手動で定義すること、またはメソッド名から派生させることをサポートしています。

述語 IsStartingWith、StartingWith、StartsWith、IsEndingWith、EndingWith、EndsWith、IsNotContaining、NotContaining、NotContains、IsContaining、Containing、Contains を持つ派生クエリは、これらのクエリのそれぞれの引数がサニタイズされます。つまり、LIKE によってワイルドカードとして認識される文字が実際に引数に含まれる場合、これらはエスケープされるため、リテラルとしてのみ一致します。使用されるエスケープ文字は、@EnableJpaRepositories アノテーションの escapeCharacter を設定することにより構成できます。SpEL 式の使用と比較してください。

宣言されたクエリ

メソッド名から派生したクエリを取得することは非常に便利ですが、メソッド名パーサーが使用したいキーワードをサポートしていないか、メソッド名が不必要にくなる状況に直面するかもしれません。そのため、命名規則を使用して JPA 名前付きクエリを使用するか（詳細については JPA 名前付きクエリの使用を参照）、@Query を使用してクエリメソッドにアノテーションを付けることができます（詳細については @Query を使用するを参照）。

クエリ作成

一般に、JPA のクエリ作成メカニズムは、"クエリメソッド" に従って機能します。次の例は、JPA クエリメソッドが何に変換されるかを示しています。

例 55: メソッド名からのクエリ作成

public interface UserRepository extends Repository<User, Long> {

  List<User> findByEmailAddressAndLastname(String emailAddress, String lastname);
}

これから JPA 条件 API を使用してクエリを作成しますが、本質的に、これは次のクエリに変換されます: select u from User u where u.emailAddress = ?1 and u.lastname = ?2. Spring Data JPA は、"プロパティ式" に従って、プロパティチェックを実行し、ネストされたプロパティを走査します。

次の表は、JPA でサポートされているキーワードと、そのキーワードを含むメソッドが何に変換されるかを示しています。

表 3: メソッド名内でサポートされているキーワード
キーワード	サンプル	JPQL スニペット
`Distinct`	`findDistinctByLastnameAndFirstname`	`select distinct … where x.lastname = ?1 and x.firstname = ?2`
`And`	`findByLastnameAndFirstname`	`… where x.lastname = ?1 and x.firstname = ?2`
`Or`	`findByLastnameOrFirstname`	`… where x.lastname = ?1 or x.firstname = ?2`
`Is`, `Equals`	`findByFirstname`,`findByFirstnameIs`,`findByFirstnameEquals`	`… where x.firstname = ?1`
`Between`	`findByStartDateBetween`	`… where x.startDate between ?1 and ?2`
`LessThan`	`findByAgeLessThan`	`… where x.age < ?1`
`LessThanEqual`	`findByAgeLessThanEqual`	`… where x.age <= ?1`
`GreaterThan`	`findByAgeGreaterThan`	`… where x.age > ?1`
`GreaterThanEqual`	`findByAgeGreaterThanEqual`	`… where x.age >= ?1`
`After`	`findByStartDateAfter`	`… where x.startDate > ?1`
`Before`	`findByStartDateBefore`	`… where x.startDate < ?1`
`IsNull`, `Null`	`findByAge(Is)Null`	`… where x.age is null`
`IsNotNull`, `NotNull`	`findByAge(Is)NotNull`	`… where x.age not null`
`Like`	`findByFirstnameLike`	`… where x.firstname like ?1`
`NotLike`	`findByFirstnameNotLike`	`… where x.firstname not like ?1`
`StartingWith`	`findByFirstnameStartingWith`	`… where x.firstname like ?1` (parameter bound with appended `%`)
`EndingWith`	`findByFirstnameEndingWith`	`… where x.firstname like ?1` (parameter bound with prepended `%`)
`Containing`	`findByFirstnameContaining`	`… where x.firstname like ?1` (parameter bound wrapped in `%`)
`OrderBy`	`findByAgeOrderByLastnameDesc`	`… where x.age = ?1 order by x.lastname desc`
`Not`	`findByLastnameNot`	`… where x.lastname <> ?1`
`In`	`findByAgeIn(Collection<Age> ages)`	`… where x.age in ?1`
`NotIn`	`findByAgeNotIn(Collection<Age> ages)`	`… where x.age not in ?1`
`True`	`findByActiveTrue()`	`… where x.active = true`
`False`	`findByActiveFalse()`	`… where x.active = false`
`IgnoreCase`	`findByFirstnameIgnoreCase`	`… where UPPER(x.firstname) = UPPER(?1)`

In および NotIn は、配列または可変引数だけでなく、Collection の任意のサブクラスもパラメーターとして受け取ります。同じ論理演算子の他の構文バージョンについては、"リポジトリクエリキーワード" を確認してください。

DISTINCT は扱いにくい場合があり、必ずしも期待どおりの結果が得られるとは限りません。例: select distinct u from User u は、select distinct u.lastname from User u とはまったく異なる結果を生成します。最初のケースでは、User.id を含めているため、何も複製されません。テーブル全体が取得され、User オブジェクトになります。

ただし、後者のクエリでは、フォーカスが User.lastname のみに絞り込まれ、そのテーブルのすべての一意の名前が検索されます。これにより、List<User> 結果セットの代わりに List<String> 結果セットも生成されます。

countDistinctByLastname(String lastname) も予期しない結果を引き起こす可能性があります。Spring Data JPA は select count(distinct u.id) from User u where u.lastname = ?1 を派生させます。繰り返しになりますが、u.id は重複をヒットしないため、このクエリは、バインドされた姓を持つすべてのユーザーをカウントします。これは countByLastname(String lastname) と同じです！

このクエリのポイントは何ですか？与えられた名前を持つ人の数を見つけるには？その拘束力のある姓を持つ明確な人々の数を見つけるには？ 個別の名前の数を見つけるには？（最後のクエリはまったく異なるクエリです！） distinct を使用するには、クエリを手動で記述し、@Query を使用して、検索する情報を最適にキャプチャーする必要がある場合があります。これは、結果セットをキャプチャーするために射影が必要になる場合もあるためです。

アノテーションベースの構成

アノテーションベースの構成には、別の構成ファイルを編集する必要がないという利点があり、メンテナンスの労力が軽減されます。新しいクエリの宣言ごとにドメインクラスを再コンパイルする必要があるため、そのメリットを享受できます。

例 56: アノテーションベースの名前付きクエリの構成

@Entity
@NamedQuery(name = "User.findByEmailAddress",
  query = "select u from User u where u.emailAddress = ?1")
public class User {

}

JPA 名前付きクエリの使用

例では、<named-query /> 要素と @NamedQuery アノテーションを使用しています。これらの構成要素のクエリは、JPA クエリ言語で定義する必要があります。もちろん、<named-native-query /> または @NamedNativeQuery も使用できます。これらの要素を使用すると、データベースプラットフォームの独立性が失われるため、ネイティブ SQL でクエリを定義できます。

XML 名前付きクエリ定義

XML 構成を使用するには、必要な <named-query /> 要素を、クラスパスの META-INF フォルダーにある orm.xml JPA 構成ファイルに追加します。名前付きクエリの自動呼び出しは、定義済みの命名規則を使用することで有効になります。詳細については、以下を参照してください。

例 57: XML 名前付きクエリの構成

<named-query name="User.findByLastname">
  <query>select u from User u where u.lastname = ?1</query>
</named-query>

クエリには、実行時に解決するために使用される特別な名前があります。

インターフェースの宣言

これらの名前付きクエリを許可するには、UserRepositoryWithRewriter を次のように指定します。

例 58: UserRepository でのクエリメソッド宣言

public interface UserRepository extends JpaRepository<User, Long> {

  List<User> findByLastname(String lastname);

  User findByEmailAddress(String emailAddress);
}

Spring Data は、これらのメソッドへの呼び出しを名前付きクエリに解決しようとします。構成されたドメインクラスの単純な名前で始まり、その後にドットで区切られたメソッド名が続きます。前述の例では、メソッド名からクエリを作成する代わりに、前に定義した名前付きクエリを使用します。

`@Query` を使用する

名前付きクエリを使用してエンティティのクエリを宣言することは有効なアプローチであり、少数のクエリに対しては正常に機能します。クエリ自体はそれらを実行する Java メソッドに関連付けられているため、ドメインクラスにアノテーションを付けるのではなく、Spring Data JPA @Query アノテーションを使用して実際に直接バインドできます。これにより、ドメインクラスが永続性固有の情報から解放され、クエリがリポジトリインターフェースに配置されます。

クエリメソッドにアノテーションが付けられたクエリは、@NamedQuery を使用して定義されたクエリまたは orm.xml で宣言された名前付きクエリよりも優先されます。

次の例は、@Query アノテーションを使用して作成されたクエリを示しています。

例 59: @Query を使用して、クエリメソッドでクエリを宣言する

public interface UserRepository extends JpaRepository<User, Long> {

  @Query("select u from User u where u.emailAddress = ?1")
  User findByEmailAddress(String emailAddress);
}

QueryRewriter の適用

適用しようとする機能の数に関係なく、EntityManager に送信される前に、Spring Data JPA に必要なすべてのものをクエリに適用させることが不可能な場合があります。

EntityManager に送信される直前に、クエリを取得して「書き換える」ことができます。つまり、最後の瞬間に変更を加えることができます。

例 60: @Query を使用して QueryRewriter を宣言する

public interface MyRepository extends JpaRepository<User, Long> {

		@Query(value = "select original_user_alias.* from SD_USER original_user_alias",
                nativeQuery = true,
				queryRewriter = MyQueryRewriter.class)
		List<User> findByNativeQuery(String param);

		@Query(value = "select original_user_alias from User original_user_alias",
                queryRewriter = MyQueryRewriter.class)
		List<User> findByNonNativeQuery(String param);
}

この例は、ネイティブ（純粋な SQL）リライターと JPQL クエリの両方を示しており、どちらも同じ QueryRewriter を利用しています。このシナリオでは、Spring Data JPA は、対応するタイプのアプリケーションコンテキストに登録されている Bean を探します。

次のようなクエリリライタを記述できます。

例 61: 例 QueryRewriter

public class MyQueryRewriter implements QueryRewriter {

     @Override
     public String rewrite(String query, Sort sort) {
         return query.replaceAll("original_user_alias", "rewritten_user_alias");
     }
}

Spring Framework の @Component ベースのアノテーションのいずれかを適用するか、@Configuration クラス内の @Bean メソッドの一部として使用するかにかかわらず、QueryRewriter がアプリケーションコンテキストに登録されていることを確認する必要があります。

もう 1 つのオプションは、リポジトリ自体にインターフェースを実装させることです。

例 62: QueryRewriter を提供するリポジトリ

public interface MyRepository extends JpaRepository<User, Long>, QueryRewriter {

		@Query(value = "select original_user_alias.* from SD_USER original_user_alias",
                nativeQuery = true,
				queryRewriter = MyRepository.class)
		List<User> findByNativeQuery(String param);

		@Query(value = "select original_user_alias from User original_user_alias",
                queryRewriter = MyRepository.class)
		List<User> findByNonNativeQuery(String param);

		@Override
		default String rewrite(String query, Sort sort) {
			return query.replaceAll("original_user_alias", "rewritten_user_alias");
		}
}

QueryRewriter で何をしているのかによっては、それぞれがアプリケーションコンテキストに登録されている複数のサイトを用意することをお勧めします。

CDI ベースの環境では、Spring Data JPA は BeanManager を検索して、QueryRewriter の実装のインスタンスを探します。

高度な `LIKE` 式の使用

次の例に示すように、@Query で作成された手動で定義されたクエリのクエリ実行メカニズムにより、クエリ定義内で高度な LIKE 式を定義できます。

例 63: @Query の高度な like 式

public interface UserRepository extends JpaRepository<User, Long> {

  @Query("select u from User u where u.firstname like %?1")
  List<User> findByFirstnameEndsWith(String firstname);
}

前の例では、LIKE 区切り文字（%）が認識され、クエリが有効な JPQL クエリに変換されます（% が削除されます）。クエリを実行すると、メソッド呼び出しに渡されたパラメーターは、以前に認識された LIKE パターンで拡張されます。

ネイティブクエリ

@Query アノテーションでは、次の例に示すように、nativeQuery フラグを true に設定することにより、ネイティブクエリを実行できます。

例 64: @Query を使用して、クエリメソッドでネイティブクエリを宣言します。

public interface UserRepository extends JpaRepository<User, Long> {

  @Query(value = "SELECT * FROM USERS WHERE EMAIL_ADDRESS = ?1", nativeQuery = true)
  User findByEmailAddress(String emailAddress);
}

Spring Data JPA は、宣言された実際のクエリを操作する必要があるため、ネイティブクエリの動的ソートを現在サポートしていません。ただし、次の例に示すように、カウントクエリを自分で指定することにより、ページネーションにネイティブクエリを使用できます。

例 65: @Query を使用して、クエリメソッドでページネーションのネイティブカウントクエリを宣言します。

public interface UserRepository extends JpaRepository<User, Long> {

  @Query(value = "SELECT * FROM USERS WHERE LASTNAME = ?1",
    countQuery = "SELECT count(*) FROM USERS WHERE LASTNAME = ?1",
    nativeQuery = true)
  Page<User> findByLastname(String lastname, Pageable pageable);
}

同様のアプローチは、クエリのコピーに .count サフィックスを追加することにより、名前付きネイティブクエリでも機能します。ただし、カウントクエリの結果セットマッピングを登録する必要があります。

並べ替えの使用

ソートは、PageRequest を提供するか、Sort を直接使用することによって実行できます。Sort の Order インスタンス内で実際に使用されるプロパティは、ドメインモデルと一致する必要があります。つまり、クエリ内で使用されるプロパティまたはエイリアスのいずれかに解決する必要があります。JPQL は、これを状態フィールドパス式として定義しています。

参照不可能なパス式を使用すると、Exception になります。

ただし、Sort を @Query と組み合わせて使用すると、ORDER BY 句内の関数を含む、パスがチェックされていない Order インスタンスに忍び込むことができます。これは、Order が特定のクエリ文字列に追加されるため可能です。デフォルトでは、Spring Data JPA は関数呼び出しを含む Order インスタンスを拒否しますが、JpaSort.unsafe を使用して、潜在的に安全でない順序を追加できます。

次の例では、Sort と JpaSort を使用しています。JpaSort の安全でないオプションも含まれています。

例 66: Sort および JpaSort の使用

public interface UserRepository extends JpaRepository<User, Long> {

  @Query("select u from User u where u.lastname like ?1%")
  List<User> findByAndSort(String lastname, Sort sort);

  @Query("select u.id, LENGTH(u.firstname) as fn_len from User u where u.lastname like ?1%")
  List<Object[]> findByAsArrayAndSort(String lastname, Sort sort);
}

repo.findByAndSort("lannister", Sort.by("firstname"));                (1)
repo.findByAndSort("stark", Sort.by("LENGTH(firstname)"));            (2)
repo.findByAndSort("targaryen", JpaSort.unsafe("LENGTH(firstname)")); (3)
repo.findByAsArrayAndSort("bolton", Sort.by("fn_len"));               (4)

1	ドメインモデルのプロパティを指す有効な `Sort` 式。
2	関数呼び出しを含む無効な `Sort`。例外をスローします。
3	明示的に安全でない `Order` を含む有効な `Sort`。
4	エイリアス機能を指す有効な `Sort` 式。

名前付きパラメーターの使用

上記のすべての例で説明したように、デフォルトでは、Spring Data JPA は位置ベースのパラメーターバインディングを使用します。これにより、パラメーターの位置に関するリファクタリング時に、クエリメソッドが少しエラーを起こしやすくなります。この課題を解決するには、次の例に示すように、@Param アノテーションを使用してメソッドパラメーターに具体的な名前を付け、クエリ内の名前をバインドします。

例 67: 名前付きパラメーターの使用

public interface UserRepository extends JpaRepository<User, Long> {

  @Query("select u from User u where u.firstname = :firstname or u.lastname = :lastname")
  User findByLastnameOrFirstname(@Param("lastname") String lastname,
                                 @Param("firstname") String firstname);
}

メソッドパラメーターは、定義されたクエリの順序に従って切り替えられます。

バージョン 4 の時点で、Spring は -parameters コンパイラーフラグに基づいて Java 8 のパラメーター名の検出を完全にサポートしています。デバッグ情報の代替としてビルドでこのフラグを使用することにより、名前付きパラメーターの @Param アノテーションを省略できます。

SpEL 式の使用

Spring Data JPA リリース 1.4 の時点で、@Query で定義された手動で定義されたクエリでの制限付き SpEL テンプレート式の使用をサポートしています。クエリが実行されると、これらの式は事前定義された変数のセットに対して評価されます。Spring Data JPA は、entityName と呼ばれる変数をサポートします。その使用箇所は select x from #{#entityName} x です。指定されたリポジトリに関連付けられているドメイン型の entityName を挿入します。entityName は、次のように解決されます。ドメイン型が @Entity アノテーションに name プロパティを設定している場合、それが使用されます。それ以外の場合は、ドメイン型の単純なクラス名が使用されます。

次の例は、クエリ文字列内の #{#entityName} 式の 1 つのユースケースを示しています。ここでは、クエリメソッドと手動で定義されたクエリでリポジトリインターフェースを定義します。

例 68: リポジトリクエリメソッドで SpEL 式を使用する - entityName

@Entity
public class User {

  @Id
  @GeneratedValue
  Long id;

  String lastname;
}

public interface UserRepository extends JpaRepository<User,Long> {

  @Query("select u from #{#entityName} u where u.lastname = ?1")
  List<User> findByLastname(String lastname);
}

@Query アノテーションのクエリ文字列に実際のエンティティ名が記述されないようにするには、#{#entityName} 変数を使用できます。

entityName は、@Entity アノテーションを使用してカスタマイズできます。orm.xml のカスタマイズは、SpEL 式ではサポートされていません。

もちろん、クエリ宣言で User を直接使用することもできますが、その場合もクエリを変更する必要があります。#entityName への参照は、User クラスの潜在的な将来の再マッピングを別のエンティティ名にピックアップします（たとえば、@Entity(name = "MyUser") を使用して）。

クエリ文字列の #{#entityName} 式のもう 1 つの使用例は、具体的なドメイン型用の特殊なリポジトリインターフェースで汎用リポジトリインターフェースを定義する場合です。具体的なインターフェースでカスタムクエリメソッドの定義を繰り返さないようにするには、次の例に示すように、汎用リポジトリインターフェースの @Query アノテーションのクエリ文字列でエンティティ名式を使用できます。

例 69: リポジトリクエリメソッドでの SpEL 式の使用 - 継承を使用した entityName

@MappedSuperclass
public abstract class AbstractMappedType {
  …
  String attribute
}

@Entity
public class ConcreteType extends AbstractMappedType { … }

@NoRepositoryBean
public interface MappedTypeRepository<T extends AbstractMappedType>
  extends Repository<T, Long> {

  @Query("select t from #{#entityName} t where t.attribute = ?1")
  List<T> findAllByAttribute(String attribute);
}

public interface ConcreteRepository
  extends MappedTypeRepository<ConcreteType> { … }

上記の例では、MappedTypeRepository インターフェースは、AbstractMappedType を継承するいくつかのドメイン型の共通の親インターフェースです。また、汎用の findAllByAttribute(…) メソッドも定義します。これは、特殊なリポジトリインターフェースのインスタンスで使用できます。ConcreteRepository で findByAllAttribute(…) を呼び出すと、クエリは select t from ConcreteType t where t.attribute = ?1 になります。

引数を操作する SpEL 式は、メソッドの引数を操作するためにも使用できます。これらの SpEL 式では、エンティティ名は使用できませんが、引数は使用できます。次の例に示すように、名前またはインデックスでアクセスできます。

例 70: リポジトリクエリメソッドでの SpEL 式の使用 - 引数へのアクセス。

@Query("select u from User u where u.firstname = ?1 and u.firstname=?#{[0]} and u.emailAddress = ?#{principal.emailAddress}")
List<User> findByFirstnameAndCurrentUserWithCustomQuery(String firstname);

like -conditions の場合、文字列値パラメーターの最初または最後に % を追加したいことがよくあります。これは、バインドパラメーターマーカーまたは SpEL 式に % を追加または接頭辞として付けることで実行できます。繰り返しますが、次の例はこれを示しています。

例 71: リポジトリクエリメソッドでの SpEL 式の使用 - ワイルドカードショートカット。

@Query("select u from User u where u.lastname like %:#{[0]}% and u.lastname like %:lastname%")
List<User> findByLastnameWithSpelExpression(@Param("lastname") String lastname);

安全でないソースからの値で like -conditions を使用する場合、ワイルドカードを含めることができないように値をサニタイズする必要があります。これにより、攻撃者は必要以上のデータを選択できるようになります。この目的のために、escape(String) メソッドが SpEL コンテキストで使用可能になります。最初の引数の _ および % のすべてのインスタンスの前に、2 番目の引数の 1 文字を付けます。JPQL および標準 SQL で使用可能な like 式の escape 句と組み合わせることで、バインドパラメーターを簡単にクリーニングできます。

例 72: リポジトリクエリメソッドでの SpEL 式の使用 - 入力値のサニタイズ。

@Query("select u from User u where u.firstname like %?#{escape([0])}% escape ?#{escapeCharacter()}")
List<User> findContainingEscaped(String namePart);

リポジトリインターフェースでこのメソッド宣言を指定すると、findContainingEscaped("Peter_") は Peter_Parker を検出しますが、Peter Parker は検出しません。使用するエスケープ文字は、@EnableJpaRepositories アノテーションの escapeCharacter を設定することで設定できます。SpEL コンテキストで使用可能なメソッド escape(String) は、SQL および JPQL 標準のワイルドカード _ および % のみをエスケープすることに注意してください。基盤となるデータベースまたは JPA 実装が追加のワイルドカードをサポートしている場合、これらはエスケープされません。

クエリの変更

これまでのすべてのセクションでは、特定のエンティティまたはエンティティのコレクションにアクセスするためのクエリを宣言する方法について説明しました。"Spring Data リポジトリのカスタム実装" で説明されているカスタムメソッド機能を使用して、カスタム変更動作を追加できます。このアプローチは包括的なカスタム機能に適しているため、次の例に示すように、クエリメソッドに @Modifying アノテーションを付けることで、パラメーターのバインドのみが必要なクエリを変更できます。

例 73: 操作クエリの宣言

@Modifying
@Query("update User u set u.firstname = ?1 where u.lastname = ?2")
int setFixedFirstnameFor(String firstname, String lastname);

これを行うと、メソッドにアノテーションが付けられたクエリが、選択クエリではなく更新クエリとしてトリガーされます。EntityManager には変更クエリの実行後に古いエンティティが含まれる可能性があるため、自動的にクリアしません（詳細については EntityManager.clear() の JavaDoc (英語) を参照）。これにより、EntityManager で保留中のすべての非フラッシュ変更が効果的にドロップされます。EntityManager を自動的にクリアする場合、@Modifying アノテーションの clearAutomatically 属性を true に設定できます。

@Modifying アノテーションは、@Query アノテーションとの組み合わせでのみ関連します。派生クエリメソッドまたはカスタムメソッドは、このアノテーションを必要としません。

派生削除クエリ

Spring Data JPA は、次の例に示すように、JPQL クエリを明示的に宣言する必要のない派生削除クエリもサポートしています。

例 74: 派生削除クエリを使用する

interface UserRepository extends Repository<User, Long> {

  void deleteByRoleId(long roleId);

  @Modifying
  @Query("delete from User u where u.role.id = ?1")
  void deleteInBulkByRoleId(long roleId);
}

deleteByRoleId(…) メソッドは、基本的に deleteInBulkByRoleId(…) と同じ結果を生成するように見えますが、実行方法の点で 2 つのメソッド宣言には重要な違いがあります。名前が示すように、後者のメソッドは、データベースに対して単一の JPQL クエリ（アノテーションで定義されたもの）を発行します。これは、現在ロードされている User のインスタンスでさえ、呼び出されたライフサイクルコールバックを認識しないことを意味します。

ライフサイクルクエリが実際に呼び出されることを確認するために、deleteByRoleId(…) の呼び出しはクエリを実行し、返されたインスタンスを 1 つずつ削除して、永続性プロバイダーがそれらのエンティティで @PreRemove コールバックを実際に呼び出すことができるようにします。

実際、派生削除クエリは、クエリを実行し、結果に対して CrudRepository.delete(Iterable<User> users) を呼び出し、CrudRepository の他の delete(…) メソッドの実装との同期を維持するためのショートカットです。

クエリヒントの適用

リポジトリインターフェースで宣言されたクエリに JPA クエリヒントを適用するには、@QueryHints アノテーションを使用できます。次の例に示すように、JPA @QueryHint アノテーションの配列とブールフラグを使用して、ページネーションを適用するときにトリガーされる追加カウントクエリに適用されるヒントを潜在的に無効にします。

例 75: QueryHints をリポジトリ方式で使用する

public interface UserRepository extends Repository<User, Long> {

  @QueryHints(value = { @QueryHint(name = "name", value = "value")},
              forCounting = false)
  Page<User> findByLastname(String lastname, Pageable pageable);
}

上記の宣言は、実際のクエリに構成済みの @QueryHint を適用しますが、ページ総数を計算するためにトリガーされるカウントクエリには適用しません。

クエリへのコメントの追加

データベースのパフォーマンスに基づいてクエリをデバッグする必要がある場合があります。データベース管理者が示すクエリは、@Query を使用して記述したものとは非常に異なって見える場合があります。または、カスタムファインダーに関して Spring Data JPA が生成したと推定するものとはまったく異なる場合があります。また、例としてクエリを使用した場合も同様です。

このプロセスを簡単にするために、@Meta アノテーションを適用することにより、クエリまたはその他の操作に関係なく、ほとんどすべての JPA 操作にカスタムコメントを挿入できます。

例 76: @Meta アノテーションをリポジトリ操作に適用します

public interface RoleRepository extends JpaRepository<Role, Integer> {

	@Meta(comment = "find roles by name")
	List<Role> findByName(String name);

	@Override
	@Meta(comment = "find roles using QBE")
	<S extends Role> List<S> findAll(Example<S> example);

	@Meta(comment = "count roles for a given name")
	long countByName(String name);

	@Override
	@Meta(comment = "exists based on QBE")
	<S extends Role> boolean exists(Example<S> example);
}

このサンプルリポジトリには、カスタムファインダーが混在しているだけでなく、JpaRepository から継承された操作をオーバーライドしています。いずれにせよ、@Meta アノテーションを使用すると、データベースに送信される前にクエリに挿入される comment を追加できます。

この機能はクエリだけに限定されないことに注意することも重要です。これは、count および exists 操作にまでおよびます。また、表示されていませんが、特定の delete 操作にも拡張されます。

この機能を可能な限り適用しようとしましたが、基盤となる EntityManager の一部の操作はコメントをサポートしていません。例: entityManager.createQuery() はサポートコメントとして明確にドキュメント化されていますが、entityManager.find() 操作はそうではありません。

JPQL ロギングも SQL ロギングも JPA の標準ではないため、以下のセクションに示すように、各プロバイダーにはカスタム構成が必要です。

Hibernate コメントのアクティブ化

Hibernate でクエリコメントをアクティブにするには、hibernate.use_sql_comments を true に設定する必要があります。

Java ベースの構成設定を使用している場合、これは次のように実行できます。

例 77: Java ベースの JPA 構成

@Bean
public Properties jpaProperties() {

	Properties properties = new Properties();
	properties.setProperty("hibernate.use_sql_comments", "true");
	return properties;
}

persistence.xml ファイルがある場合は、そこで適用できます。

例 78: persistence.xml ベースの構成

<persistence-unit name="my-persistence-unit">

   ...registered classes...

	<properties>
		<property name="hibernate.use_sql_comments" value="true" />
	</properties>
</persistence-unit>

最後に、Spring Boot を使用している場合は、application.properties ファイル内に設定できます。

例 79: Spring Boot プロパティベースの構成

spring.jpa.properties.hibernate.use_sql_comments=true

EclipseLink コメントのアクティブ化

EclipseLink でクエリコメントをアクティブにするには、eclipselink.logging.level.sql を FINE に設定する必要があります。

Java ベースの構成設定を使用している場合、これは次のように実行できます。

例 80: Java ベースの JPA 構成

@Bean
public Properties jpaProperties() {

	Properties properties = new Properties();
	properties.setProperty("eclipselink.logging.level.sql", "FINE");
	return properties;
}

persistence.xml ファイルがある場合は、そこで適用できます。

例 81: persistence.xml ベースの構成

<persistence-unit name="my-persistence-unit">

   ...registered classes...

	<properties>
		<property name="eclipselink.logging.level.sql" value="FINE" />
	</properties>
</persistence-unit>

最後に、Spring Boot を使用している場合は、application.properties ファイル内に設定できます。

例 82: Spring Boot プロパティベースの構成

spring.jpa.properties.eclipselink.logging.level.sql=FINE

Fetch- および LoadGraphs の構成

JPA 2.1 仕様では、@NamedEntityGraph 定義を参照できる @EntityGraph アノテーションでもサポートする Fetch- および LoadGraphs の指定のサポートが導入されました。エンティティでそのアノテーションを使用して、結果のクエリのフェッチプランを構成できます。フェッチの型（Fetch または Load）は、@EntityGraph アノテーションの type 属性を使用して構成できます。詳細については、JPA 2.1 仕様 3.7.4 を参照してください。

次の例は、エンティティに名前付きエンティティグラフを定義する方法を示しています。

例 83: エンティティ上の名前付きエンティティグラフの定義。

@Entity
@NamedEntityGraph(name = "GroupInfo.detail",
  attributeNodes = @NamedAttributeNode("members"))
public class GroupInfo {

  // default fetch mode is lazy.
  @ManyToMany
  List<GroupMember> members = new ArrayList<GroupMember>();

  …
}

次の例は、リポジトリクエリメソッドで名前付きエンティティグラフを参照する方法を示しています。

例 84: リポジトリクエリメソッドで名前付きエンティティグラフ定義を参照します。

public interface GroupRepository extends CrudRepository<GroupInfo, String> {

  @EntityGraph(value = "GroupInfo.detail", type = EntityGraphType.LOAD)
  GroupInfo getByGroupName(String name);

}

@EntityGraph を使用して、アドホックエンティティグラフを定義することもできます。提供された attributePaths は、次の例に示すように、@NamedEntityGraph をドメイン型に明示的に追加する必要なく、対応する EntityGraph に変換されます。

例 85: リポジトリクエリメソッドでの AD-HOC エンティティグラフ定義の使用。

public interface GroupRepository extends CrudRepository<GroupInfo, String> {

  @EntityGraph(attributePaths = { "members" })
  GroupInfo getByGroupName(String name);

}

射影

Spring Data クエリメソッドは通常、リポジトリによって管理される集約ルートの 1 つまたは複数のインスタンスを返します。ただし、これらの型の特定の属性に基づいて射影を作成することが望ましい場合があります。Spring Data では、専用の戻り値型をモデル化して、管理対象集合体の部分ビューをより選択的に取得できます。

次の例のようなリポジトリおよび集約ルート型を想像してください。

例 86: サンプルの集約とリポジトリ

class Person {

  @Id UUID id;
  String firstname, lastname;
  Address address;

  static class Address {
    String zipCode, city, street;
  }
}

interface PersonRepository extends Repository<Person, UUID> {

  Collection<Person> findByLastname(String lastname);
}

ここで、人の名前属性のみを取得することを想像してください。Spring Data はこれを達成するためにどのような意味を持っていますか？この章の残りはその質問に回答します。

インターフェースベースの射影

クエリの結果を名前属性のみに制限する最も簡単な方法は、次の例に示すように、読み取るプロパティのアクセサーメソッドを公開するインターフェースを宣言することです。

例 87: 属性のサブセットを取得する射影インターフェース

interface NamesOnly {

  String getFirstname();
  String getLastname();
}

ここで重要なことは、ここで定義されたプロパティが集約ルートのプロパティと正確に一致することです。これにより、クエリメソッドを次のように追加できます。

例 88: クエリメソッドでインターフェースベースの射影を使用するリポジトリ

interface PersonRepository extends Repository<Person, UUID> {

  Collection<NamesOnly> findByLastname(String lastname);
}

クエリ実行エンジンは、返された各要素に対して実行時にそのインターフェースのプロキシインスタンスを作成し、公開されたメソッドへの呼び出しをターゲットオブジェクトに転送します。

基本メソッド（たとえば、CrudRepository、ストア固有のリポジトリインターフェース、Simple … Repository で宣言されている）をオーバーライドするメソッドを Repository で宣言すると、宣言された戻り値の型に関係なく、基本メソッドが呼び出されます。基本メソッドは射影に使用できないため、互換性のある戻り値の型を使用してください。一部のストアモジュールは、@Query アノテーションをサポートして、オーバーライドされたベースメソッドをクエリメソッドに変換します。このクエリメソッドを使用して、射影を返すことができます。

射影は再帰的に使用できます。Address 情報の一部も含めたい場合は、次の例に示すように、そのための射影インターフェースを作成し、getAddress() の宣言からそのインターフェースを返します。

例 89: 属性のサブセットを取得する射影インターフェース

interface PersonSummary {

  String getFirstname();
  String getLastname();
  AddressSummary getAddress();

  interface AddressSummary {
    String getCity();
  }
}

メソッドの呼び出し時に、ターゲットインスタンスの address プロパティが取得され、順番に投影プロキシにラップされます。

閉じた射影

アクセサーメソッドがすべてターゲット集合体のプロパティに一致する射影インターフェースは、閉じた射影と見なされます。次の例（この章の前半でも使用しました）は、閉じた射影です。

例 90: 閉じた射影

interface NamesOnly {

  String getFirstname();
  String getLastname();
}

閉じた射影を使用する場合、Spring Data はクエリの実行を最適化できます。これは、射影プロキシのバックアップに必要なすべての属性がわかっているためです。詳細については、リファレンスドキュメントのモジュール固有の部分を参照してください。

開いた射影

次の例に示すように、@Value アノテーションを使用して、射影インターフェースのアクセサーメソッドを使用して新しい値を計算することもできます。

例 91: 開いた射影

interface NamesOnly {

  @Value("#{target.firstname + ' ' + target.lastname}")
  String getFullName();
  …
}

射影を支える集約ルートは、target 変数で利用可能です。@Value を使用した射影インターフェースは、オープン射影です。この場合、Spring Data はクエリ実行最適化を適用できません。これは、SpEL 式が集約ルートの任意の属性を使用できるためです。

@Value で使用される式は複雑すぎてはいけません — String 変数でのプログラミングは避けたいです。非常に単純な式の場合、次の例に示すように、1 つのオプションはデフォルトのメソッド（Java 8 で導入）に頼ることです。

例 92: カスタムロジックにデフォルトのメソッドを使用する射影インターフェース

interface NamesOnly {

  String getFirstname();
  String getLastname();

  default String getFullName() {
    return getFirstname().concat(" ").concat(getLastname());
  }
}

このアプローチでは、射影インターフェースで公開される他のアクセサーメソッドに純粋に基づいてロジックを実装できる必要があります。次の例に示すように、2 番目のより柔軟なオプションは、Spring Bean にカスタムロジックを実装し、SpEL 式からそれを呼び出すことです。

例 93: サンプル Person オブジェクト

@Component
class MyBean {

  String getFullName(Person person) {
    …
  }
}

interface NamesOnly {

  @Value("#{@myBean.getFullName(target)}")
  String getFullName();
  …
}

SpEL 式が myBean を参照し、getFullName(…) メソッドを呼び出し、射影ターゲットをメソッドパラメーターとして転送する方法に注目してください。SpEL 式の評価に裏付けられたメソッドは、メソッドパラメーターを使用することもできます。このパラメーターは、式から参照できます。メソッドのパラメーターは、args という名前の Object 配列を介して使用できます。次の例は、args 配列からメソッドパラメーターを取得する方法を示しています。

例 94: サンプル Person オブジェクト

interface NamesOnly {

  @Value("#{args[0] + ' ' + target.firstname + '!'}")
  String getSalutation(String prefix);
}

繰り返しますが、より複雑な式の場合は、前に説明したように、Spring Bean を使用し、式でメソッドを呼び出す必要があります。

null 可能ラッパー

射影インターフェースの Getter は、null 許容ラッパーを使用して null の安全性を向上させることができます。現在サポートされているラッパー型は次のとおりです。

java.util.Optional
com.google.common.base.Optional
scala.Option
io.vavr.control.Option

例 95: null 許容ラッパーを使用した射影インターフェース

interface NamesOnly {

  Optional<String> getFirstname();
}

基になる射影値が null でない場合、値はラッパー型の現在の表現を使用して返されます。バッキング値が null の場合、getter メソッドは使用されたラッパー型の空の表現を返します。

クラスベースの射影 (DTO)

射影を定義するもう 1 つの方法は、取得することになっているフィールドのプロパティを保持する値型 DTO（データ転送オブジェクト）を使用することです。これらの DTO 型は、プロキシが発生せず、ネストされた射影を適用できないことを除いて、射影インターフェースとまったく同じ方法で使用できます。

ストアがロードするフィールドを制限することでクエリの実行を最適化する場合、ロードされるフィールドは公開されているコンストラクターのパラメーター名から決定されます。

次の例は、投影 DTO を示しています。

例 96: 投影 DTO

record NamesOnly(String firstname, String lastname) {
}

Java レコードは、値のセマンティクスに準拠しているため、DTO 型を定義するのに理想的です。すべてのフィールドは private final であり、equals(…)/hashCode()/toString() メソッドは自動的に作成されます。または、投影するプロパティを定義する任意のクラスを使用できます。

JPQL を使用したクラスベースの射影は、JPQL 式のコンストラクター式 (例: SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u) に限定されます。(DTO 型の FQDN の使用箇所に注意してください ! ) この JPQL 式は、名前付きクエリを定義する @Query アノテーションでも使用できます。また、クラスベースの射影はネイティブクエリではまったく機能しないことを指摘しておくことが重要です。回避策として、ResultSetMapping または Hibernate 固有の ResultTransformer (英語) で名前付きクエリを使用できます。

動的射影

これまで、コレクションの戻り値型または要素型として射影型を使用しました。ただし、呼び出し時に使用する型を選択することもできます（これにより、動的になります）。動的射影を適用するには、次の例に示すようなクエリメソッドを使用します。

例 97: 動的射影パラメーターを使用するリポジトリ

interface PersonRepository extends Repository<Person, UUID> {

  <T> Collection<T> findByLastname(String lastname, Class<T> type);
}

この方法では、次の例に示すように、メソッドを使用して、そのままで、または射影を適用して集約を取得できます。

例 98: 動的射影でリポジトリを使用する

void someMethod(PersonRepository people) {

  Collection<Person> aggregates =
    people.findByLastname("Matthews", Person.class);

  Collection<NamesOnly> aggregates =
    people.findByLastname("Matthews", NamesOnly.class);
}

型 Class のクエリパラメーターは、動的射影パラメーターとして適格かどうかがインスペクションされます。クエリの実際の戻り値の型が Class パラメーターのジェネリクスパラメーター型と等しい場合、一致する Class パラメーターはクエリまたは SpEL 式内で使用できません。Class パラメーターをクエリ引数として使用する場合は、必ず別のジェネリクスパラメーター（Class<?> など）を使用してください。

5.1.4. ストアドプロシージャー

JPA 2.1 仕様では、JPA 条件クエリ API を使用してストアドプロシージャを呼び出すサポートが導入されました。リポジトリメソッドでストアドプロシージャメタデータを宣言するための @Procedure アノテーションを導入しました。

以下の例では、次のストアドプロシージャを使用します。

例 99: HSQL DB の plus1inout プロシージャの定義。

/;
DROP procedure IF EXISTS plus1inout
/;
CREATE procedure plus1inout (IN arg int, OUT res int)
BEGIN ATOMIC
 set res = arg + 1;
END
/;

ストアドプロシージャのメタデータは、エンティティ型で NamedStoredProcedureQuery アノテーションを使用して構成できます。

例 100: エンティティの StoredProcedure メタデータ定義。

@Entity
@NamedStoredProcedureQuery(name = "User.plus1", procedureName = "plus1inout", parameters = {
  @StoredProcedureParameter(mode = ParameterMode.IN, name = "arg", type = Integer.class),
  @StoredProcedureParameter(mode = ParameterMode.OUT, name = "res", type = Integer.class) })
public class User {}

@NamedStoredProcedureQuery には、ストアドプロシージャの 2 つの異なる名前があることに注意してください。name は、JPA が使用する名前です。procedureName は、データベース内のストアドプロシージャの名前です。

リポジトリメソッドからストアドプロシージャを複数の方法で参照できます。呼び出されるストアードプロシージャーは、@Procedure アノテーションの value または procedureName 属性を使用して直接定義できます。これは、データベース内のストアドプロシージャを直接参照し、@NamedStoredProcedureQuery を介した構成を無視します。

または、@NamedStoredProcedureQuery.name 属性を @Procedure.name 属性として指定できます。value、procedureName、name のいずれも構成されていない場合、リポジトリ方式の名前が name 属性として使用されます。

次の例は、明示的にマップされたプロシージャを参照する方法を示しています。

例 101: データベースで "plus1inout" という名前の明示的にマップされたプロシージャを参照しています。

@Procedure("plus1inout")
Integer explicitlyNamedPlus1inout(Integer arg);

次の例は前の例と同等ですが、procedureName エイリアスを使用しています。

例 102: procedureName エイリアスを介してデータベース内の名前 "plus1inout" を持つ暗黙的にマップされたプロシージャを参照します。

@Procedure(procedureName = "plus1inout")
Integer callPlus1InOut(Integer arg);

次も前の 2 つと同じですが、明示的なアノテーション属性の代わりにメソッド名を使用しています。

例 103: メソッド名を使用して、EntityManager で暗黙的にマップされた名前付きストアドプロシージャ "User.plus1" を参照します。

@Procedure
Integer plus1inout(@Param("arg") Integer arg);

次の例は、@NamedStoredProcedureQuery.name 属性を参照してストアドプロシージャを参照する方法を示しています。

例 104: EntityManager で明示的にマップされた名前付きストアドプロシージャ "User.plus1IO" の参照。

@Procedure(name = "User.plus1IO")
Integer entityAnnotatedCustomNamedProcedurePlus1IO(@Param("arg") Integer arg);

呼び出されるストアドプロシージャに単一の出力パラメーターがある場合、そのパラメーターはメソッドの戻り値として返されます。@NamedStoredProcedureQuery アノテーションで複数の出力パラメーターが指定されている場合、@NamedStoredProcedureQuery アノテーションで指定されたパラメーター名をキーとして Map として返すことができます。

5.1.5. Specification

JPA 2 は、クエリをプログラムで作成するために使用できる条件 API を導入しています。criteria を記述することにより、ドメインクラスのクエリの where 句を定義します。別のステップに戻ると、これらの条件は、JPA 条件 API 制約によって記述されたエンティティに関する述語と見なすことができます。

Spring Data JPA は、同じセマンティクスに従い、JPA 条件 API を使用してそのような仕様を定義する API を提供する、エリックエバンスの著書 "Domain Driven Design" から仕様の概念を取り入れています。次のように、仕様をサポートするために、JpaSpecificationExecutor インターフェースを使用してリポジトリインターフェースを継承できます。

public interface CustomerRepository extends CrudRepository<Customer, Long>, JpaSpecificationExecutor<Customer> {
 …
}

追加のインターフェースには、さまざまな方法で仕様を実行できるメソッドがあります。例: 次の例に示すように、findAll メソッドは仕様に一致するすべてのエンティティを返します。

List<T> findAll(Specification<T> spec);

Specification インターフェースは次のように定義されます。

public interface Specification<T> {
  Predicate toPredicate(Root<T> root, CriteriaQuery<?> query,
            CriteriaBuilder builder);
}

次の例に示すように、仕様を簡単に使用して、エンティティの上に拡張可能な一連の述語を構築し、JpaRepository と組み合わせて使用し、必要な組み合わせごとにクエリ（メソッド）を宣言する必要なしに使用できます。

例 105: 顧客の仕様

public class CustomerSpecs {


  public static Specification<Customer> isLongTermCustomer() {
    return (root, query, builder) -> {
      LocalDate date = LocalDate.now().minusYears(2);
      return builder.lessThan(root.get(Customer_.createdAt), date);
    };
  }

  public static Specification<Customer> hasSalesOfMoreThan(MonetaryAmount value) {
    return (root, query, builder) -> {
      // build query here
    };
  }
}

Customer_ 型は、JPA メタモデルジェネレーターを使用して生成されたメタモデル型です（Hibernate 実装のドキュメントの例 (英語) を参照）。式 Customer_.createdAt は、Customer が型 Date の createdAt 属性を持っていることを前提としています。さらに、ビジネス要件の抽象化レベルでいくつかの条件を表現し、実行可能な Specifications を作成しました。クライアントは次のように Specification を使用する可能性があります。

例 106: 簡単な仕様を使用する

List<Customer> customers = customerRepository.findAll(isLongTermCustomer());

この種のデータアクセスのクエリを作成してみませんか？単一の Specification を使用しても、単純なクエリ宣言よりも大きな利点は得られません。仕様を組み合わせて新しい Specification オブジェクトを作成すると、仕様の威力が本当に発揮されます。これは、次のような式を作成するために提供されている Specification のデフォルトメソッドを使用して実現できます。

例 107: 組み合わせ仕様

MonetaryAmount amount = new MonetaryAmount(200.0, Currencies.DOLLAR);
List<Customer> customers = customerRepository.findAll(
  isLongTermCustomer().or(hasSalesOfMoreThan(amount)));

Specification は、チェーンにいくつかの「グルーコード」デフォルトメソッドを提供し、Specification インスタンスを結合します。これらのメソッドを使用すると、新しい Specification 実装を作成し、既存の実装と組み合わせることにより、データアクセスレイヤーを継承できます。

また、JPA 2.1 では、CriteriaBuilder API によって CriteriaDelete が導入されました。これは、JpaSpecificationExecutor’s `delete(Specification) API を介して提供されます。

例 108: Specification を使用してエントリを削除します。

Specification<User> ageLessThan18 = (root, query, cb) -> cb.lessThan(root.get("age").as(Integer.class), 18)

userRepository.delete(ageLessThan18);

Specification は、age フィールド（整数としてキャスト）が 18 よりも小さい条件を構築します。userRepository に渡され、JPA の CriteriaDelete 機能を使用して、適切な DELETE 操作を生成します。次に、削除されたエンティティの数を返します。

5.1.6. 例示による問い合わせ

導入

この章では、Query by Example の概要とその使用方法について説明します。

Query by Example（QBE）は、シンプルなインターフェースを備えた使いやすいクエリ手法です。動的なクエリの作成が可能になり、フィールド名を含むクエリを作成する必要がなくなります。実際、Query by Example では、ストア固有のクエリ言語を使用してクエリを記述する必要はまったくありません。

使用方法

例示による問い合わせ API は、次の 4 つの部分で構成されています。

プローブ: フィールドが設定されたドメインオブジェクトの実際の例。
ExampleMatcher: ExampleMatcher には、特定のフィールドの照合方法に関する詳細が記載されています。複数の例で再利用できます。
Example: Example は、プローブと ExampleMatcher で構成されています。クエリの作成に使用されます。
FetchableFluentQuery: FetchableFluentQuery は流れるような API を提供し、Example から派生したクエリをさらにカスタマイズできるようにします。Fluent API を使用すると、クエリの順序付けの射影と結果の処理を指定できます。

例示による問い合わせは、いくつかのユースケースに適しています。

静的または動的な制約のセットを使用してデータストアをクエリします。
既存のクエリを壊すことを心配せずにドメインオブジェクトを頻繁にリファクタリングします。
基礎となるデータストア API から独立して動作します。

例示による問い合わせには、いくつかの制限もあります。

firstname = ?0 or (firstname = ?1 and lastname = ?2) など、ネストまたはグループ化されたプロパティ制約はサポートされていません。
文字列の starts/contains/ends/regex マッチングと他のプロパティ型の完全一致のみをサポートします。

Query by Example を開始する前に、ドメインオブジェクトが必要です。開始するには、次の例に示すように、リポジトリのインターフェースを作成します。

例 109: サンプル Person オブジェクト

public class Person {

  @Id
  private String id;
  private String firstname;
  private String lastname;
  private Address address;

  // … getters and setters omitted
}

前の例は、単純なドメインオブジェクトを示しています。これを使用して Example を作成できます。デフォルトでは、null 値を持つフィールドは無視され、文字列はストア固有のデフォルトを使用して照合されます。

例示による問い合わせ条件へのプロパティの包含は、null 可能性に基づいています。プリミティブ型（int、double、…）を使用するプロパティは、ExampleMatcher はプロパティパスを無視しますでない限り、常に含まれます。

例は、of ファクトリメソッドを使用するか、ExampleMatcher を使用して作成できます。Example は不変です。次のリストは、簡単な例を示しています。

例 110: 簡単な例

Person person = new Person();                         (1)
person.setFirstname("Dave");                          (2)

Example<Person> example = Example.of(person);         (3)

1	ドメインオブジェクトの新しいインスタンスを作成します。
2	クエリにプロパティを設定します。
3	`Example` を作成します。

リポジトリを使用して、サンプルクエリを実行できます。これを行うには、リポジトリインターフェースに QueryByExampleExecutor<T> を継承させます。次のリストは、QueryByExampleExecutor インターフェースからの抜粋を示しています。

例 111: QueryByExampleExecutor

public interface QueryByExampleExecutor<T> {

  <S extends T> S findOne(Example<S> example);

  <S extends T> Iterable<S> findAll(Example<S> example);

  // … more functionality omitted.
}

マッチャーの例

例はデフォルト設定に限定されません。次の例に示すように、ExampleMatcher を使用して、文字列照合、null 処理、プロパティ固有の設定に独自のデフォルトを指定できます。

例 112: カスタマイズされたマッチングを使用したマッチャーの例

Person person = new Person();                          (1)
person.setFirstname("Dave");                           (2)

ExampleMatcher matcher = ExampleMatcher.matching()     (3)
  .withIgnorePaths("lastname")                         (4)
  .withIncludeNullValues()                             (5)
  .withStringMatcher(StringMatcher.ENDING);            (6)

Example<Person> example = Example.of(person, matcher); (7)

1	ドメインオブジェクトの新しいインスタンスを作成します。
2	セットのプロパティ。
3	`ExampleMatcher` を作成して、すべての値が一致することを期待します。この段階では、さらに構成しなくても使用できます。
4	`lastname` プロパティパスを無視する新しい `ExampleMatcher` を構築します。
5	新しい `ExampleMatcher` を作成して、`lastname` プロパティパスを無視し、null 値を含めます。
6	新しい `ExampleMatcher` を作成して、`lastname` プロパティパスを無視し、null 値を含め、サフィックス文字列の照合を実行します。
7	ドメインオブジェクトと設定された `ExampleMatcher` に基づいて新しい `Example` を作成します。

デフォルトでは、ExampleMatcher はプローブに設定されたすべての値が一致することを期待しています。暗黙的に定義された述語のいずれかに一致する結果を取得する場合は、ExampleMatcher.matchingAny() を使用します。

個々のプロパティ（「名」や「姓」、ネストされたプロパティの場合は "address.city" など）の動作を指定できます。次の例に示すように、一致するオプションと大文字と小文字の区別を使用して調整できます。

例 113: マッチャーオプションの構成

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", endsWith())
  .withMatcher("lastname", startsWith().ignoreCase());
}

マッチャーオプションを構成する別の方法は、ラムダ（Java 8 で導入）を使用することです。このアプローチは、実装者にマッチャーの変更を要求するコールバックを作成します。設定オプションはマッチャーインスタンス内に保持されているため、マッチャーを返す必要はありません。次の例は、ラムダを使用するマッチャーを示しています。

例 114: ラムダを使用したマッチャーオプションの構成

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("firstname", match -> match.endsWith())
  .withMatcher("firstname", match -> match.startsWith());
}

Example によって作成されたクエリは、構成の統合ビューを使用します。デフォルトのマッチング設定は ExampleMatcher レベルで設定できますが、個々の設定は特定のプロパティパスに適用できます。ExampleMatcher で設定された設定は、明示的に定義されていない限り、プロパティパス設定に継承されます。プロパティパッチの設定は、デフォルト設定よりも優先されます。次の表は、さまざまな ExampleMatcher 設定の範囲を説明しています。

表 4: `ExampleMatcher` 設定の範囲
設定	スコープ
null ハンドリング	`ExampleMatcher`
文字列マッチング	`ExampleMatcher` and property path
Ignoring properties	Property path
Case sensitivity	`ExampleMatcher` and property path
Value transformation	Property path

Fluent API

QueryByExampleExecutor offers one more method, which we did not mention so far: <S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction). As with other methods, it executes a query derived from an Example. However, with the second argument, you can control aspects of that execution that you cannot dynamically control otherwise. You do so by invoking the various methods of the FetchableFluentQuery in the second argument. sortBy lets you specify an ordering for your result. as lets you specify the type to which you want the result to be transformed. project limits the queried attributes. first, firstValue, one, oneValue, all, page, stream, count, and exists define what kind of result you get and how the query behaves when more than the expected number of results are available.

Example 115. Use the fluent API to get the last of potentially many results, ordered by lastname.

Optional<Person> match = repository.findBy(example,
    q -> q
        .sortBy(Sort.by("lastname").descending())
        .first()
);

Running an Example

In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example:

Example 116. Query by Example using a Repository

public interface PersonRepository extends JpaRepository<Person, String> { … }

public class PersonService {

  @Autowired PersonRepository personRepository;

  public List<Person> findPeople(Person probe) {
    return personRepository.findAll(Example.of(probe));
  }
}

Currently, only SingularAttribute properties can be used for property matching.

The property specifier accepts property names (such as firstname and lastname). You can navigate by chaining properties together with dots (address.city). You can also tune it with matching options and case sensitivity.

The following table shows the various StringMatcher options that you can use and the result of using them on a field named firstname:

Table 5. `StringMatcher` options
Matching	Logical result
`DEFAULT` (case-sensitive)	`firstname = ?0`
`DEFAULT` (case-insensitive)	`LOWER(firstname) = LOWER(?0)`
`EXACT` (case-sensitive)	`firstname = ?0`
`EXACT` (case-insensitive)	`LOWER(firstname) = LOWER(?0)`
`STARTING` (case-sensitive)	`firstname like ?0 + '%'`
`STARTING` (case-insensitive)	`LOWER(firstname) like LOWER(?0) + '%'`
`ENDING` (case-sensitive)	`firstname like '%' + ?0`
`ENDING` (case-insensitive)	`LOWER(firstname) like '%' + LOWER(?0)`
`CONTAINING` (case-sensitive)	`firstname like '%' + ?0 + '%'`
`CONTAINING` (case-insensitive)	`LOWER(firstname) like '%' + LOWER(?0) + '%'`

5.1.7. トランザクション性

デフォルトでは、CrudRepository から継承されたメソッドは SimpleJpaRepository (Javadoc) からトランザクション構成を継承します。読み取り操作の場合、トランザクション構成 readOnly フラグが true に設定されます。他のすべてはプレーンな @Transactional で構成されているため、デフォルトのトランザクション構成が適用されます。トランザクションリポジトリフラグメントによってサポートされるリポジトリメソッドは、実際のフラグメントメソッドからトランザクション属性を継承します。

リポジトリで宣言されているメソッドの 1 つのトランザクション構成を微調整する必要がある場合は、次のように、リポジトリインターフェースでメソッドを再宣言します。

例 117: CRUD のカスタムトランザクション設定

public interface UserRepository extends CrudRepository<User, Long> {

  @Override
  @Transactional(timeout = 10)
  public List<User> findAll();

  // Further query method declarations
}

これを行うと、findAll() メソッドは 10 秒のタイムアウトで、readOnly フラグなしで実行されます。

トランザクションの動作を変更するもう 1 つの方法は、（通常）複数のリポジトリをカバーするファサードまたはサービス実装を使用することです。その目的は、非 CRUD 操作のトランザクション境界を定義することです。次の例は、そのようなファサードを複数のリポジトリに使用する方法を示しています。

例 118: ファサードを使用して複数のリポジトリ呼び出しのトランザクションを定義する

@Service
public class UserManagementImpl implements UserManagement {

  private final UserRepository userRepository;
  private final RoleRepository roleRepository;

  public UserManagementImpl(UserRepository userRepository,
    RoleRepository roleRepository) {
    this.userRepository = userRepository;
    this.roleRepository = roleRepository;
  }

  @Transactional
  public void addRoleToAllUsers(String roleName) {

    Role role = roleRepository.findByName(roleName);

    for (User user : userRepository.findAll()) {
      user.addRole(role);
      userRepository.save(user);
    }
  }
}

この例では、addRoleToAllUsers(…) の呼び出しをトランザクション内で実行します（既存のトランザクションに参加するか、まだ実行されていない場合は新しいトランザクションを作成します）。リポジトリでのトランザクション構成は無視されます。外部のトランザクション構成が実際に使用される構成を決定するためです。ファサードのアノテーションベースの構成を機能させるには、<tx:annotation-driven /> をアクティブにするか、@EnableTransactionManagement を明示的に使用する必要があることに注意してください。この例では、コンポーネントスキャンを使用することを前提としています。

JPA の観点からは save の呼び出しは厳密には必要ありませんが、Spring Data によって提供されるリポジトリの抽象化との整合性を保つために必要です。

トランザクションクエリメソッド

宣言されたクエリメソッド (既定のメソッドを含む) は、既定で適用されるトランザクション構成を取得しません。これらのメソッドをトランザクションで実行するには、次の例に示すように、定義したリポジトリインターフェースで @Transactional を使用します。

例 119: クエリメソッドで @Transactional を使用する

@Transactional(readOnly = true)
interface UserRepository extends JpaRepository<User, Long> {

  List<User> findByLastname(String lastname);

  @Modifying
  @Transactional
  @Query("delete from User u where u.active = false")
  void deleteInactiveUsers();
}

通常、ほとんどのクエリメソッドはデータの読み取りのみを行うため、readOnly フラグを true に設定する必要があります。それとは対照的に、deleteInactiveUsers() は @Modifying アノテーションを使用して、トランザクション構成をオーバーライドします。メソッドは readOnly フラグを false に設定して実行されます。

readOnly フラグを設定することにより、読み取り専用クエリにトランザクションを使用し、そのようなものとしてマークできます。ただし、そうすることで、クエリの操作をトリガーしないことを確認することはできません（ただし、一部のデータベースは、読み取り専用トランザクション内で INSERT および UPDATE ステートメントを拒否します）。readOnly フラグは、代わりに、パフォーマンスの最適化のための基礎となる JDBC ドライバーへのヒントとして伝搬されます。さらに、Spring は、基礎となる JPA プロバイダーでいくつかの最適化を実行します。例: Hibernate で使用する場合、トランザクションを readOnly として設定すると、フラッシュモードは NEVER に設定されます。これにより、Hibernate はダーティチェックをスキップします（大きなオブジェクトツリーの顕著な改善）。

5.1.8. ロック

使用するロックモードを指定するには、次の例に示すように、クエリメソッドで @Lock アノテーションを使用できます。

例 120: クエリメソッドのロックメタデータの定義

interface UserRepository extends Repository<User, Long> {

  // Plain query method
  @Lock(LockModeType.READ)
  List<User> findByLastname(String lastname);
}

このメソッド宣言により、トリガーされるクエリに READ の LockModeType が装備されます。次の例に示すように、リポジトリインターフェースでメソッドを再宣言し、@Lock アノテーションを追加することにより、CRUD メソッドのロックを定義することもできます。

例 121: CRUD メソッドのロックメタデータの定義

interface UserRepository extends Repository<User, Long> {

  // Redeclaration of a CRUD method
  @Lock(LockModeType.READ)
  List<User> findAll();
}

5.1.9. 監査

基本

Spring Data は、エンティティを作成または変更したユーザーと変更がいつ発生したかを透過的に追跡するための高度なサポートを提供します。この機能を利用するには、アノテーションを使用するか、インターフェースを実装することで定義できる監査メタデータをエンティティクラスに装備する必要があります。さらに、必要なインフラストラクチャコンポーネントを登録するには、アノテーション構成または XML 構成のいずれかを介して監査を有効にする必要があります。構成サンプルについては、ストア固有のセクションを参照してください。

作成日と変更日のみを追跡するアプリケーションでは、エンティティに AuditorAware を実装する必要はありません。

アノテーションベースの監査メタデータ

エンティティを作成または変更したユーザーをキャプチャーする @CreatedBy と @LastModifiedBy、および変更が発生したときにキャプチャーする @CreatedDate と @LastModifiedDate を提供します。

例 122: 監査対象エンティティ

class Customer {

  @CreatedBy
  private User user;

  @CreatedDate
  private Instant createdDate;

  // … further properties omitted
}

ご覧のとおり、キャプチャーする情報に応じて、アノテーションを選択的に適用できます。変更が行われたときにキャプチャーすることを示すアノテーションは、JDK8 の日付と時刻の型、long、Long、レガシー Java Date と Calendar のプロパティで使用できます。

以下のスニペットに示すように、監査メタデータは必ずしもルートレベルのエンティティに存在する必要はありませんが、埋め込まれたエンティティに追加できます（実際に使用されているストアによって異なります）。

例 123: 埋め込みエンティティのメタデータを監査する

class Customer {

  private AuditMetadata auditingMetadata;

  // … further properties omitted
}

class AuditMetadata {

  @CreatedBy
  private User user;

  @CreatedDate
  private Instant createdDate;

}

インターフェースベースの監査メタデータ

アノテーションを使用して監査メタデータを定義したくない場合は、ドメインクラスに Auditable インターフェースを実装させることができます。すべての監査プロパティの setter メソッドを公開します。

`AuditorAware`

@CreatedBy または @LastModifiedBy を使用する場合、監査インフラストラクチャは何らかの形で現在のプリンシパルを認識する必要があります。そのために、現在のユーザーまたはアプリケーションと対話するシステムが誰であるかをインフラストラクチャに伝えるために実装する必要がある AuditorAware<T> SPI インターフェースを提供します。ジェネリクス型 T は、@CreatedBy または @LastModifiedBy アノテーションが付けられたプロパティの型を定義します。

次の例は、Spring Security の Authentication オブジェクトを使用するインターフェースの実装を示しています。

例 124: Spring Security に基づく AuditorAware の実装

class SpringSecurityAuditorAware implements AuditorAware<User> {

  @Override
  public Optional<User> getCurrentAuditor() {

    return Optional.ofNullable(SecurityContextHolder.getContext())
            .map(SecurityContext::getAuthentication)
            .filter(Authentication::isAuthenticated)
            .map(Authentication::getPrincipal)
            .map(User.class::cast);
  }
}

実装は、Spring Security が提供する Authentication オブジェクトにアクセスし、UserDetailsService 実装で作成したカスタム UserDetails インスタンスを検索します。ここでは、UserDetails 実装を介してドメインユーザーを公開しているが、見つかった Authentication に基づいて、どこからでも検索できると想定しています。

`ReactiveAuditorAware`

リアクティブインフラストラクチャを使用する場合、コンテキスト情報を利用して @CreatedBy または @LastModifiedBy 情報を提供することができます。アプリケーションと対話している現在のユーザーまたはシステムが誰であるかをインフラストラクチャに通知するために実装する必要がある ReactiveAuditorAware<T> SPI インターフェースを提供します。ジェネリクス型 T は、@CreatedBy または @LastModifiedBy でアノテーションが付けられたプロパティがどの型でなければならないかを定義します。

次の例は、リアクティブ Spring Security の Authentication オブジェクトを使用するインターフェースの実装を示しています。

例 125: Spring Security に基づく ReactiveAuditorAware の実装

class SpringSecurityAuditorAware implements ReactiveAuditorAware<User> {

  @Override
  public Mono<User> getCurrentAuditor() {

    return ReactiveSecurityContextHolder.getContext()
                .map(SecurityContext::getAuthentication)
                .filter(Authentication::isAuthenticated)
                .map(Authentication::getPrincipal)
                .map(User.class::cast);
  }
}

また、便利な基本クラス AbstractAuditable もあります。これは、インターフェースメソッドを手動で実装する必要を回避するために拡張できます。これにより、ドメインクラスの Spring Data への結合が増加しますが、これは避けたい場合があります。通常、監査メタデータを定義するアノテーションベースのメソッドは、侵襲性が低く、柔軟性が高いため好まれます。

5.1.10. JPA 監査

一般的な監査構成

Spring Data JPA には、監査情報のキャプチャーをトリガーするために使用できるエンティティリスナーが付属しています。まず、次の例に示すように、orm.xml ファイル内の永続コンテキストのすべてのエンティティに使用される AuditingEntityListener を登録する必要があります。

例 126: 監査構成 orm.xml

<persistence-unit-metadata>
  <persistence-unit-defaults>
    <entity-listeners>
      <entity-listener class="….data.jpa.domain.support.AuditingEntityListener" />
    </entity-listeners>
  </persistence-unit-defaults>
</persistence-unit-metadata>

次のように、@EntityListeners アノテーションを使用して、エンティティごとに AuditingEntityListener を有効にすることもできます。

@Entity
@EntityListeners(AuditingEntityListener.class)
public class MyEntity {

}

監査機能では、spring-aspects.jar がクラスパス上にある必要があります。

orm.xml が適切に変更され、spring-aspects.jar がクラスパスにある場合、監査機能をアクティブ化するには、次のように Spring Data JPA auditing 名前空間要素を構成に追加します。

例 127: XML 構成を使用した監査のアクティブ化

<jpa:auditing auditor-aware-ref="yourAuditorAwareBean" />

Spring Data JPA 1.5 以降、構成クラスに @EnableJpaAuditing アノテーションを付けることにより、監査を有効にすることができます。ただし、orm.xml ファイルを変更し、クラスパスに spring-aspects.jar を含める必要があります。次の例は、@EnableJpaAuditing アノテーションの使用方法を示しています。

例 128: Java 構成を使用した監査のアクティブ化

@Configuration
@EnableJpaAuditing
class Config {

  @Bean
  public AuditorAware<AuditableUser> auditorProvider() {
    return new AuditorAwareImpl();
  }
}

型 AuditorAware の Bean を ApplicationContext に公開すると、監査インフラストラクチャはそれを自動的に選択し、それを使用してドメイン型に設定する現在のユーザーを決定します。ApplicationContext に複数の実装が登録されている場合、@EnableJpaAuditing の auditorAwareRef 属性を明示的に設定することにより、使用する実装を選択できます。

5.2. その他の考慮事項

5.2.1. カスタム実装での `JpaContext` の使用

複数の EntityManager インスタンスとカスタムリポジトリ実装を使用する場合、正しい EntityManager をリポジトリ実装クラスに接続する必要があります。そのためには、@PersistenceContext アノテーションで EntityManager を明示的に命名するか、EntityManager が @Autowired である場合は @Qualifier を使用します。

Spring Data JPA 1.9 の時点で、Spring Data JPA には JpaContext と呼ばれるクラスが含まれています。これにより、アプリケーションの EntityManager インスタンスの 1 つだけで管理されていると仮定して、管理対象ドメインクラスで EntityManager を取得できます。次の例は、カスタムリポジトリで JpaContext を使用する方法を示しています。

例 129: カスタムリポジトリ実装での JpaContext の使用

class UserRepositoryImpl implements UserRepositoryCustom {

  private final EntityManager em;

  @Autowired
  public UserRepositoryImpl(JpaContext context) {
    this.em = context.getEntityManagerByManagedType(User.class);
  }

  …
}

このアプローチの利点は、ドメイン型が別の永続性ユニットに割り当てられた場合、永続性ユニットへの参照を変更するためにリポジトリに触れる必要がないことです。

5.2.2. 永続性ユニットのマージ

Spring は、複数の永続性ユニットを持つことをサポートしています。ただし、場合によっては、アプリケーションをモジュール化しながら、これらのすべてのモジュールが単一の永続性ユニット内で実行されるようにすることもできます。この動作を可能にするために、Spring Data JPA は、次の例に示すように、名前に基づいて永続性ユニットを自動的にマージする PersistenceUnitManager 実装を提供します。

例 130: MergingPersistenceUnitmanager の使用

<bean class="….LocalContainerEntityManagerFactoryBean">
  <property name="persistenceUnitManager">
    <bean class="….MergingPersistenceUnitManager" />
  </property>
</bean>

@Entity クラスと JPA マッピングファイルのクラスパススキャン

プレーンな JPA セットアップでは、すべてのアノテーションがマッピングされたエンティティクラスが orm.xml にリストされている必要があります。同じことが XML マッピングファイルにも当てはまります。Spring Data JPA は、基本パッケージを構成し、オプションでマッピングファイル名パターンを取得する ClasspathScanningPersistenceUnitPostProcessor を提供します。次に、指定されたパッケージをスキャンして @Entity または @MappedSuperclass アノテーションが付けられたクラスを探し、ファイル名パターンに一致する構成ファイルをロードして、JPA 構成に渡します。ポストプロセッサーは次のように構成する必要があります。

例 131: ClasspathScanningPersistenceUnitPostProcessor の使用

<bean class="….LocalContainerEntityManagerFactoryBean">
  <property name="persistenceUnitPostProcessors">
    <list>
      <bean class="org.springframework.data.jpa.support.ClasspathScanningPersistenceUnitPostProcessor">
        <constructor-arg value="com.acme.domain" />
        <property name="mappingFileNamePattern" value="**/*Mapping.xml" />
      </bean>
    </list>
  </property>
</bean>

Spring 3.1 以降、エンティティクラスのクラスパススキャンを有効にするために、LocalContainerEntityManagerFactoryBean でスキャンするパッケージを直接構成できます。詳細については、JavaDoc (Javadoc) を参照してください。

5.2.3. CDI 統合

リポジトリインターフェースのインスタンスは通常、コンテナーによって作成されます。Spring Data を使用する場合は、Spring が最も自然な選択です。Spring は、リポジトリインスタンスの作成でドキュメント化されているように、Bean インスタンスを作成するための洗練されたサポートを提供します。バージョン 1.1.0 の時点で、Spring Data JPA には CDI 環境でリポジトリ抽象化を使用できるカスタム CDI 拡張が付属しています。拡張機能は JAR の一部です。有効にするには、クラスパスに Spring Data JPA JAR を含めます。

次の例に示すように、EntityManagerFactory および EntityManager の CDI プロデューサーを実装することにより、インフラストラクチャをセットアップできます。

class EntityManagerFactoryProducer {

  @Produces
  @ApplicationScoped
  public EntityManagerFactory createEntityManagerFactory() {
    return Persistence.createEntityManagerFactory("my-persistence-unit");
  }

  public void close(@Disposes EntityManagerFactory entityManagerFactory) {
    entityManagerFactory.close();
  }

  @Produces
  @RequestScoped
  public EntityManager createEntityManager(EntityManagerFactory entityManagerFactory) {
    return entityManagerFactory.createEntityManager();
  }

  public void close(@Disposes EntityManager entityManager) {
    entityManager.close();
  }
}

必要なセットアップは、JavaEE 環境によって異なります。次のように、EntityManager を CDI Bean として再宣言するだけでよい場合があります。

class CdiConfig {

  @Produces
  @RequestScoped
  @PersistenceContext
  public EntityManager entityManager;
}

上記の例では、コンテナーは JPA EntityManagers 自体を作成できる必要があります。すべての構成は、JPA EntityManager を CDI Bean として再エクスポートするだけです。

Spring Data JPA CDI 拡張機能は、使用可能なすべての EntityManager インスタンスを CDI Bean としてピックアップし、コンテナーによってリポジトリ型の Bean がリクエストされるたびに、Spring Data リポジトリのプロキシを作成します。Spring Data リポジトリのインスタンスを取得するには、次の例に示すように、@Injected プロパティを宣言する必要があります。

class RepositoryClient {

  @Inject
  PersonRepository repository;

  public void businessMethod() {
    List<Person> people = repository.findAll();
  }
}

5.3. Spring Data Envers

5.3.1. Spring Data Envers とは何ですか？

Spring Data Envers は、典型的な Envers クエリを Spring Data JPA のリポジトリで利用できるようにします。他の Spring Data モジュールとは異なり、常に別の Spring Data モジュールである Spring Data JPA と組み合わせて使用されます。

5.3.2. Envers とは何ですか？

Envers は、JPA エンティティに監査機能を追加する Hibernate モジュール (英語) です。このドキュメントは、Spring Data Envers が Envers が適切に構成されていることに依存しているのと同様に、Envers に精通していることを前提としています。

5.3.3. 構成

Spring Data Envers を使用するための開始点として、クラスパスに Spring Data JPA があり、追加の spring-data-envers 依存関係があるプロジェクトが必要です。

<dependencies>

  <!-- other dependency elements omitted -->

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-envers</artifactId>
    <version>3.0.6</version>
  </dependency>

</dependencies>

これにより、hibernate-envers が一時的な依存関係としてプロジェクトに組み込まれます。

Spring Data Envers と Spring Data JPA を有効にするには、2 つの Bean と特別な repositoryFactoryBeanClass を構成する必要があります。

@Configuration
@EnableEnversRepositories
@EnableTransactionManagement
public class EnversDemoConfiguration {

	@Bean
	public DataSource dataSource() {

		EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
		return builder.setType(EmbeddedDatabaseType.HSQL).build();
	}

	@Bean
	public LocalContainerEntityManagerFactoryBean entityManagerFactory() {

		HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
		vendorAdapter.setGenerateDdl(true);

		LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
		factory.setJpaVendorAdapter(vendorAdapter);
		factory.setPackagesToScan("example.springdata.jpa.envers");
		factory.setDataSource(dataSource());
		return factory;
	}

	@Bean
	public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {

		JpaTransactionManager txManager = new JpaTransactionManager();
		txManager.setEntityManagerFactory(entityManagerFactory);
		return txManager;
	}
}

Spring Data Envers を実際に使用するには、1 つ以上のリポジトリを継承インターフェースとして追加して {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[RevisionRepository] にします。

interface PersonRepository
    extends CrudRepository<Person, Long>,
    RevisionRepository<Person, Long, Long> (1)
{}

1	最初の型パラメーター（`Person`）はエンティティ型を示し、2 番目（`Long`）は id プロパティの型を示し、最後の型パラメーター（`Long`）はリビジョン番号の型を示します。デフォルト構成の Envers の場合、リビジョン番号パラメーターは `Integer` または `Long` である必要があります。

そのリポジトリのエンティティは、Envers 監査が有効になっているエンティティである必要があります（つまり、@Audited アノテーションが必要です）。

@Entity
@Audited
class Person {

	@Id @GeneratedValue
	Long id;
	String name;
	@Version Long version;
}

5.3.4. 使用方法

次のテストケースに示すように、RevisionRepository のメソッドを使用して、エンティティのリビジョンをクエリできるようになりました。

@ExtendWith(SpringExtension.class)
@Import(EnversDemoConfiguration.class) (1)
class EnversIntegrationTests {

	final PersonRepository repository;
	final TransactionTemplate tx;

	EnversIntegrationTests(@Autowired PersonRepository repository, @Autowired PlatformTransactionManager tm) {
		this.repository = repository;
		this.tx = new TransactionTemplate(tm);
	}

	@Test
	void testRepository() {

		Person updated = preparePersonHistory();

		Revisions<Long, Person> revisions = repository.findRevisions(updated.id);

		Iterator<Revision<Long, Person>> revisionIterator = revisions.iterator();

		checkNextRevision(revisionIterator, "John", RevisionType.INSERT);
		checkNextRevision(revisionIterator, "Jonny", RevisionType.UPDATE);
		checkNextRevision(revisionIterator, null, RevisionType.DELETE);
		assertThat(revisionIterator.hasNext()).isFalse();

	}

	/**
    * Checks that the next element in the iterator is a Revision entry referencing a Person
    * with the given name after whatever change brought that Revision into existence.
    * <p>
    * As a side effect the Iterator gets advanced by one element.
    *
    * @param revisionIterator the iterator to be tested.
    * @param name the expected name of the Person referenced by the Revision.
    * @param revisionType the type of the revision denoting if it represents an insert, update or delete.
    */
	private void checkNextRevision(Iterator<Revision<Long, Person>> revisionIterator, String name,
			RevisionType revisionType) {

		assertThat(revisionIterator.hasNext()).isTrue();
		Revision<Long, Person> revision = revisionIterator.next();
		assertThat(revision.getEntity().name).isEqualTo(name);
		assertThat(revision.getMetadata().getRevisionType()).isEqualTo(revisionType);
	}

	/**
    * Creates a Person with a couple of changes so it has a non-trivial revision history.
    * @return the created Person.
    */
	private Person preparePersonHistory() {

		Person john = new Person();
		john.setName("John");

		// create
		Person saved = tx.execute(__ -> repository.save(john));
		assertThat(saved).isNotNull();

		saved.setName("Jonny");

		// update
		Person updated = tx.execute(__ -> repository.save(saved));
		assertThat(updated).isNotNull();

		// delete
		tx.executeWithoutResult(__ -> repository.delete(updated));
		return updated;
	}
}

1	これは、前に（構成セクションで）示したアプリケーションコンテキスト構成を参照します。

5.3.5. その他のリソース

Spring Data サンプルリポジトリの Spring Data Envers サンプル [GitHub] (英語) をダウンロードして、ライブラリがどのように機能するかを試してみることができます。

{spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html [Javadoc for RevisionRepository] および関連するクラスも確認する必要があります。

spring-data-envers タグを使用した Stackoverflow (英語) で質問をすることができます。

Spring Data Envers のソースコードと課題追跡システムは、GitHub でホストされています (英語) 。

6. 付録

付録 A: 名前空間参照

`<repositories />` 要素

<repositories /> 要素は、Spring Data リポジトリインフラストラクチャのセットアップをトリガーします。最も重要な属性は base-package です。これは、Spring Data リポジトリインターフェースをスキャンするパッケージを定義します。"XML 構成" を参照してください。次の表は、<repositories /> 要素の属性を説明しています。

表 6: 属性
名前	説明
`base-package`	自動検出モードで `*Repository` を継承するリポジトリインターフェース（実際のインターフェースは特定の Spring Data モジュールによって決定されます）をスキャンするパッケージを定義します。設定されたパッケージのすべてのパッケージもスキャンされます。ワイルドカードが許可されます。
`repository-impl-postfix`	カスタムリポジトリ実装を自動検出するための接尾辞を定義します。名前が構成された接尾辞で終わるクラスは、候補と見なされます。デフォルトは `Impl` です。
`query-lookup-strategy`	ファインダー照会の作成に使用される戦略を決定します。詳細については、"クエリ検索戦略" を参照してください。デフォルトは `create-if-not-found` です。
`named-queries-location`	外部で定義されたクエリを含むプロパティファイルを検索する場所を定義します。
`consider-nested-repositories`	ネストされたリポジトリインターフェース定義を考慮する必要があるかどうか。デフォルトは `false` です。

付録 B: Populators 名前空間リファレンス

<populator/> 要素

<populator /> 要素を使用すると、Spring Data リポジトリインフラストラクチャを介してデータストアにデータを入力できます。^{[ 1 ]}

表 7: 属性
名前	説明
`locations`	リポジトリからオブジェクトを読み取るためのファイルの場所には、データが入力されます。

付録 C: リポジトリクエリキーワード

サポートされているクエリメソッドの件名キーワード

次の表に、述語を表現するために Spring Data リポジトリのクエリ導出メカニズムで一般的にサポートされているサブジェクトキーワードを示します。ここにリストされている一部のキーワードは特定のストアでサポートされていない可能性があるため、サポートされているキーワードの正確なリストについては、ストア固有のドキュメントを参照してください。

表 8: 件名のキーワードを照会する
キーワード	説明
`find…By`, `read…By`, `get…By`, `query…By`, `search…By`, `stream…By`	通常、リポジトリ型、`Collection` または `Streamable` サブ型、`Page`、`GeoResults` などの結果ラッパーまたはその他のストア固有の結果ラッパーを返す一般的なクエリメソッド。`findBy …`、`findMyDomainTypeBy …` として、または追加のキーワードと組み合わせて使用できます。
`exists…By`	射影が存在し、通常は `boolean` の結果を返します。
`count…By`	数値結果を返す射影をカウントします。
`delete…By`, `remove…By`	結果なし（`void`）または削除カウントのいずれかを返すクエリメソッドを削除します。
`…First<number>…`, `…Top<number>…`	クエリ結果を結果の最初の `<number>` に制限します。このキーワードは、`find` （および他のキーワード）と `by` の間の件名の任意の場所で使用できます。
`…Distinct…`	一意のクエリを使用して、一意の結果のみを返します。その機能がサポートされているかどうかは、ストア固有のドキュメントを参照してください。このキーワードは、`find` （および他のキーワード）と `by` の間の件名の任意の場所で使用できます。

サポートされているクエリメソッドの述語キーワードと修飾子

次の表に、Spring Data リポジトリクエリ派生メカニズムで一般的にサポートされている述語キーワードを示します。ただし、ここにリストされている一部のキーワードは特定のストアでサポートされていない可能性があるため、サポートされているキーワードの正確なリストについては、ストア固有のドキュメントを参照してください。

表 9: 述語キーワードのクエリ
論理キーワード	キーワード表現
`AND`	`And`
`OR`	`Or`
`AFTER`	`After`, `IsAfter`
`BEFORE`	`Before`, `IsBefore`
`CONTAINING`	`Containing`, `IsContaining`, `Contains`
`BETWEEN`	`Between`, `IsBetween`
`ENDING_WITH`	`EndingWith`, `IsEndingWith`, `EndsWith`
`EXISTS`	`Exists`
`FALSE`	`False`, `IsFalse`
`GREATER_THAN`	`GreaterThan`, `IsGreaterThan`
`GREATER_THAN_EQUALS`	`GreaterThanEqual`, `IsGreaterThanEqual`
`IN`	`In`, `IsIn`
`IS`	`Is`, `Equals`, (or no keyword)
`IS_EMPTY`	`IsEmpty`, `Empty`
`IS_NOT_EMPTY`	`IsNotEmpty`, `NotEmpty`
`IS_NOT_NULL`	`NotNull`, `IsNotNull`
`IS_NULL`	`Null`, `IsNull`
`LESS_THAN`	`LessThan`, `IsLessThan`
`LESS_THAN_EQUAL`	`LessThanEqual`, `IsLessThanEqual`
`LIKE`	`Like`, `IsLike`
`NEAR`	`Near`, `IsNear`
`NOT`	`Not`, `IsNot`
`NOT_IN`	`NotIn`, `IsNotIn`
`NOT_LIKE`	`NotLike`, `IsNotLike`
`REGEX`	`Regex`, `MatchesRegex`, `Matches`
`STARTING_WITH`	`StartingWith`, `IsStartingWith`, `StartsWith`
`TRUE`	`True`, `IsTrue`
`WITHIN`	`Within`, `IsWithin`

フィルター述語に加えて、次の修飾子のリストがサポートされています。

表 10: 述語修飾子キーワードのクエリ
キーワード	説明
`IgnoreCase`, `IgnoringCase`	大文字と小文字を区別しない比較のために、述語キーワードとともに使用されます。
`AllIgnoreCase`, `AllIgnoringCase`	すべての適切なプロパティの大文字と小文字を区別しません。クエリメソッド述語のどこかで使用されます。
`OrderBy…`	静的な並べ替え順序を指定し、その後にプロパティのパスと方向を指定します（例: `OrderByFirstnameAscLastnameDesc`）。

付録 D: リポジトリクエリの戻り値の型

サポートされているクエリの戻り値の型

次の表に、Spring Data リポジトリで一般的にサポートされる戻り値の型を示します。ただし、ここにリストされている一部の型は特定のストアでサポートされていない可能性があるため、サポートされる戻り値の型の正確なリストについてはストア固有のドキュメントを参照してください。

地理空間型（GeoResult、GeoResults、GeoPage など）は、地理空間クエリをサポートするデータストアでのみ使用できます。一部のストアモジュールは、独自の結果ラッパー型を定義する場合があります。

表 11: クエリの戻り型
戻りの型	説明
`void`	戻り値がないことを示します。
プリミティブ	Java プリミティブ。
ラッパーの種類	Java ラッパー型。
`T`	一意のエンティティ。クエリメソッドが最大で 1 つの結果を返すことを期待します。結果が見つからない場合、`null` が返されます。複数の結果が `IncorrectResultSizeDataAccessException` をトリガーします。
`Iterator<T>`	`Iterator`
`Collection<T>`	`Collection`
`List<T>`	`List`
`Optional<T>`	Java 8 または Guava `Optional` クエリメソッドが最大で 1 つの結果を返すことを期待します。結果が見つからない場合、`Optional.empty()` または `Optional.absent()` が返されます。複数の結果が `IncorrectResultSizeDataAccessException` をトリガーします。
`Option<T>`	Scala または Vavr `Option` 型のいずれか。前述の Java 8 の `Optional` と同じ意味の振る舞い。
`Stream<T>`	Java 8 `Stream`
`Streamable<T>`	`Iterable` の便利な拡張機能で、結果のストリーミング、マッピング、フィルタリング、連結などのメソッドを直接公開します。
`Streamable` を実装し、`Streamable` コンストラクターまたはファクトリメソッド引数を取る型	`Streamable` を引数として取るコンストラクターまたは `… .of(…)`/ `… .valueOf(…)` ファクトリメソッドを公開する型。詳細については、カスタムのストリーミング可能なラッパー型を返すを参照してください。
Vavr `Seq`、`List`、`Map`、`Set`	Vavr コレクション型。詳細については、Vavr コレクションのサポートを参照してください。
`Future<T>`	`Future` メソッドに `@Async` のアノテーションが付けられることを期待し、Spring の非同期メソッド実行機能を有効にする必要があります。
`CompletableFuture<T>`	Java 8 `CompletableFuture` メソッドに `@Async` のアノテーションが付けられることを期待し、Spring の非同期メソッド実行機能を有効にする必要があります。
`Slice<T>`	使用可能なデータがさらにあるかどうかを示すサイズのデータチャンク。`Pageable` メソッドパラメーターが必要です。
`Page<T>`	結果の総数などの追加情報を含む `Slice`。`Pageable` メソッドパラメーターが必要です。
`GeoResult<T>`	参照場所までの距離などの追加情報を含む結果エントリ。
`GeoResults<T>`	参照場所までの平均距離などの追加情報を含む `GeoResult<T>` のリスト。
`GeoPage<T>`	参照位置までの平均距離など、`Page` と `GeoResult<T>`。
`Mono<T>`	リアクティブリポジトリを使用して 0 個または 1 個の要素を放出するプロジェクト Reactor `Mono`。クエリメソッドが最大で 1 つの結果を返すことを期待します。結果が見つからない場合、`Mono.empty()` が返されます。複数の結果が `IncorrectResultSizeDataAccessException` をトリガーします。
`Flux<T>`	プロジェクト Reactor `Flux` は、リアクティブリポジトリを使用してゼロ、1 つ、多くの要素を放出します。`Flux` を返すクエリは、無限の数の要素も放出できます。
`Single<T>`	リアクティブリポジトリを使用して単一の要素を放出する RxJava `Single`。クエリメソッドが最大で 1 つの結果を返すことを期待します。結果が見つからない場合、`Mono.empty()` が返されます。複数の結果が `IncorrectResultSizeDataAccessException` をトリガーします。
`Maybe<T>`	リアクティブリポジトリを使用して 0 個または 1 個の要素を放出する RxJava `Maybe`。クエリメソッドが最大で 1 つの結果を返すことを期待します。結果が見つからない場合、`Mono.empty()` が返されます。複数の結果が `IncorrectResultSizeDataAccessException` をトリガーします。
`Flowable<T>`	リアクティブリポジトリを使用してゼロ、1 つ、多くの要素を放出する RxJava `Flowable`。`Flowable` を返すクエリは、無限の数の要素も放出できます。

付録 E: よくある質問

共通

たとえば、JpaRepository 内で呼び出されるメソッドに関する詳細なログ情報を取得したいと思います。どうすれば獲得できますか？

次の例に示すように、Spring が提供する CustomizableTraceInterceptor を使用できます。

<bean id="customizableTraceInterceptor" class="
  org.springframework.aop.interceptor.CustomizableTraceInterceptor">
  <property name="enterMessage" value="Entering $[methodName]($[arguments])"/>
  <property name="exitMessage" value="Leaving $[methodName](): $[returnValue]"/>
</bean>

<aop:config>
  <aop:advisor advice-ref="customizableTraceInterceptor"
    pointcut="execution(public * org.springframework.data.jpa.repository.JpaRepository+.*(..))"/>
</aop:config>

監査

Spring Data JPA 監査機能を使用したいのですが、エンティティの変更日と作成日を設定するようにデータベースがすでに構成されています。Spring Data がプログラムで日付を設定しないようにするにはどうすればよいですか？
auditing 名前空間要素の set-dates 属性を false に設定します。

付録 F: 用語集

AOP: アスペクト指向プログラミング
Commons DBCP: Commons DataBase 接続プール - DataSource インターフェースのプーリング実装を提供する Apache 財団のライブラリ。
CRUD: 作成、読み取り、更新、削除 - 基本的な永続化操作。
DAO: データアクセスオブジェクト - 永続化するオブジェクトから永続化ロジックを分離するパターン
依存性注入: 外部からコンポーネントへのコンポーネントの依存関係を渡すパターン。コンポーネントを解放して、依存関係自体をルックアップします。詳細については、https://en.wikipedia.org/wiki/Dependency_Injection を参照してください。
EclipseLink: JPA を実装するオブジェクトリレーショナルマッパー -https://www.eclipse.org/eclipselink/ (英語)
Hibernate: JPA を実装するオブジェクトリレーショナルマッパー -https://hibernate.org/ (英語)
JPA: Jakarta Persistence API
Spring: Java アプリケーションフレームワーク - https://spring.io/projects/spring-framework

1. XML 構成を参照

Spring Data JPA - リファレンスドキュメント

1. 序文

1.1. プロジェクトメタデータ

2. Spring Data のアップグレード

3. 依存関係

3.1. Spring Boot を使用した依存関係管理

3.2. Spring Framework

4. Spring Data リポジトリの操作

4.1. コアコンセプト

4.2. クエリメソッド

4.3. リポジトリインターフェースの定義

4.3.1. リポジトリ定義の微調整

4.3.2. 複数の Spring Data モジュールでリポジトリを使用する

4.4. クエリメソッドの定義

4.4.1. クエリ検索戦略

4.4.2. クエリ作成

4.4.3. プロパティ式

4.4.4. 特別なパラメーター処理

ページングとソート

4.4.5. クエリ結果の制限

4.4.6. コレクションまたはイテラブルを返すリポジトリメソッド

Streamable をクエリメソッドの戻り値の型として使用する

カスタムのストリーミング可能なラッパー型を返す

Vavr コレクションのサポート

4.4.7. リポジトリメソッドの null 処理

Nullability アノテーション

Kotlin ベースのリポジトリの Nullability

4.4.8. クエリ結果のストリーミング

4.4.9. 非同期クエリ結果

4.5. リポジトリインスタンスの作成

4.5.1. Java 構成

4.5.2. XML 構成

4.5.3. フィルターの使用

4.5.4. スタンドアロンの使用箇所

4.6. Spring Data リポジトリのカスタム実装

4.6.1. 個々のリポジトリのカスタマイズ

構成

あいまいさの解決

手動接続

4.6.2. ベースリポジトリをカスタマイズする

4.7. 集約ルートからのイベントの公開

4.8. Spring Data 拡張

4.8.1. Querydsl 拡張

4.8.2. Web サポート

基本的な Web サポート

DomainClassConverter クラスの使用

ページング可能およびソート用の HandlerMethodArgumentResolvers

Pageable のハイパーメディアサポート

Spring Data Jackson モジュール

Web データバインディングのサポート

Querydsl Web サポート

4.8.3. リポジトリポピュレーター

5. リファレンスドキュメント

5.1. JPA リポジトリ

5.1.1. 導入

アノテーションベースの構成

Spring ネームスペース

カスタム名前空間属性

ブートストラップモード

推奨

5.1.2. 永続化エンティティ

エンティティの保存

エンティティ状態検出戦略

5.1.3. クエリメソッド

クエリ検索戦略

宣言されたクエリ

クエリ作成

アノテーションベースの構成

JPA 名前付きクエリの使用

XML 名前付きクエリ定義

インターフェースの宣言

@Query を使用する

QueryRewriter の適用

高度な LIKE 式の使用

ネイティブクエリ

並べ替えの使用

名前付きパラメーターの使用

SpEL 式の使用

クエリの変更

派生削除クエリ

`DomainClassConverter` クラスの使用

`@Query` を使用する

高度な `LIKE` 式の使用

`AuditorAware`

`ReactiveAuditorAware`

5.2.1. カスタム実装での `JpaContext` の使用

`<repositories />` 要素