HIBERNATE - Relational Persistence for Idiomatic Java - 15

HIBERNATE - Relational Persistence for Idiomatic Java

Hibernate Reference Documentation

Hibernateレファレンスドキュメンテーション

3.2.2

Table of Contents(コンテンツテーブル)

Preface(序文)

1. Introduction to Hibernate(Hibernateの紹介)

2. Architecture(アーキテクチャ)

3. Configuration(設定)

4. Persistent Classes(永続クラス)

5. Basic O/R Mapping(基本的なO/Rマッピング)

6. Collection Mapping(コレクションのマッピング)

7. Association Mappings(関連マッピング)

8. Component Mapping(コンポーネントのマッピング)

9. Inheritance Mapping(継承マッピング)

10. Working with objects(オブジェクトを扱う)

11. Transactions And Concurrency(トランザクションと並行性)

12. Interceptors and events(インターセプタとイベント)

13. Batch processing(バッチ処理)

14. HQL: The Hibernate Query Language(HQL：Hibernateクエリ言語)

15. Criteria Queries(Criteriaクエリ)

15.1. Creating a Criteria instance(Criteriaインスタンスの作成)

15.2. Narrowing the result set(result setの絞込み)

15.3. Ordering the results(結果の整列)

15.4. Associations(関連)

15.5. Dynamic association fetching(関連の動的フェッチ)

15.6. Example queries(クエリの例)

15.7. Projections, aggregation and grouping(射影、集約、グループ化)

15.8. Detached queries and subqueries(クエリおよびサブクエリの分離)

15.9. Queries by natural identifier(自然識別子によるクエリ)

Chapter 15. Criteria Queries(Criteriaクエリ)

Hibernate features an intuitive, extensible criteria query API.

Hibernateには、直感的で拡張可能なcriteriaクエリAPIが用意されています。

15.1. Creating a Criteria instance(Criteriaインスタンスの作成)

The interface org.hibernate.Criteria represents a query against a particular persistent class. The Session is a factory for Criteria instances.

org.hibernate.Criteriaインターフェイスは特定の永続性クラスに対するクエリを表現します。Session は Criteria インスタンスのファクトリです。

Criteria crit = sess.createCriteria(Cat.class);

crit.setMaxResults(50);

List cats = crit.list();

15.2. Narrowing the result set(result setの絞込み)

An individual query criterion is an instance of the interfaceorg.hibernate.criterion.Criterion. The class org.hibernate.criterion.Restrictions defines factory methods for obtaining certain built-in Criterion types.

org.hibernate.criterion.Criterion インターフェイスのインスタンスは、個別のクエリクライテリオン（問い合わせの判定基準）を表します。org.hibernate.criterion.Restrictionsクラスは、ある組み込みの Criterion型を取得するためのファクトリメソッドを持っています。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.like("name", "Fritz%") )

    .add( Restrictions.between("weight", minWeight, maxWeight) )

    .list();

Restrictions may be grouped logically.

Restriction（限定）は、論理的にグループ化できます。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.like("name", "Fritz%") )

    .add( Restrictions.or(

        Restrictions.eq( "age", new Integer(0) ),

        Restrictions.isNull("age")

    ) )

    .list();

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) )

    .add( Restrictions.disjunction()

        .add( Restrictions.isNull("age") )

        .add( Restrictions.eq("age", new Integer(0) ) )

        .add( Restrictions.eq("age", new Integer(1) ) )

        .add( Restrictions.eq("age", new Integer(2) ) )

    ) )

    .list();

There are quite a range of built-in criterion types (Restrictions subclasses), but one that is especially useful lets you specify SQL directly.

元々あるCriterion型（Restrictions のサブクラス）はかなりの範囲に及びますが、特に有用なのはSQLを直接指定できるものです。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.sqlRestriction("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) )

    .list();

The {alias} placeholder with be replaced by the row alias of the queried entity.

{alias} というプレースホルダは、問い合わせを受けたエンティティの行の別名によって置き換えられます。

An alternative approach to obtaining a criterion is to get it from a Property instance. You can create a Property by calling Property.forName().

criterionを得る別の手段は、Property インスタンスから取得することです。Property.forName() を呼び出して、Property インスタンスを作成できます。

Property age = Property.forName("age");

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.disjunction()

        .add( age.isNull() )

        .add( age.eq( new Integer(0) ) )

        .add( age.eq( new Integer(1) ) )

        .add( age.eq( new Integer(2) ) )

    ) )

    .add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) )

    .list();

15.3. Ordering the results(結果の整列)

You may order the results using org.hibernate.criterion.Order.

org.hibernate.criterion.Orderを使って結果を並び替えることができます。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.like("name", "F%")

    .addOrder( Order.asc("name") )

    .addOrder( Order.desc("age") )

    .setMaxResults(50)

    .list();

List cats = sess.createCriteria(Cat.class)

    .add( Property.forName("name").like("F%") )

    .addOrder( Property.forName("name").asc() )

    .addOrder( Property.forName("age").desc() )

    .setMaxResults(50)

    .list();

15.4. Associations(関連)

You may easily specify constraints upon related entities by navigating associations usingcreateCriteria().

createCriteria() を使い、関連をナビゲートすることで、容易に関係するエンティティに制約を指定できます。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.like("name", "F%") )

    .createCriteria("kittens")

        .add( Restrictions.like("name", "F%") )

    .list();

note that the second createCriteria() returns a new instance of Criteria, which refers to the elements of the kittens collection.

2番目の createCriteria() は、kittensコレクションの要素を参照する新しい Criteriaインスタンスを返すことに注意してください。

The following, alternate form is useful in certain circumstances.

以下のような方法も、状況により有用です。

List cats = sess.createCriteria(Cat.class)

    .createAlias("kittens", "kt")

    .createAlias("mate", "mt")

    .add( Restrictions.eqProperty("kt.name", "mt.name") )

    .list();

(createAlias() does not create a new instance of Criteria.)

（createAlias() は新しいCriteria インスタンスを作成しません。）

Note that the kittens collections held by the Cat instances returned by the previous two queries are not pre-filtered by the criteria! If you wish to retrieve just the kittens that match the criteria, you must use a ResultTransformer.

前の2つのクエリによって返される Catインスタンスによって保持されるkittensコレクションは、criteriaによって事前にフィルタリングされないことに注意してください。もしcriteriaに適合するkittenを取得したいなら、ResultTransformer を使わなければなりません。

List cats = sess.createCriteria(Cat.class)

    .createCriteria("kittens", "kt")

        .add( Restrictions.eq("name", "F%") )

    .setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP)

    .list();

Iterator iter = cats.iterator();

while ( iter.hasNext() ) {

    Map map = (Map) iter.next();

    Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS);

    Cat kitten = (Cat) map.get("kt");

}

15.5. Dynamic association fetching(関連の動的フェッチ)

You may specify association fetching semantics at runtime using setFetchMode().

setFetchMode() を使い、実行時に関連の復元方法を指定してもよいです。

List cats = sess.createCriteria(Cat.class)

    .add( Restrictions.like("name", "Fritz%") )

    .setFetchMode("mate", FetchMode.EAGER)

    .setFetchMode("kittens", FetchMode.EAGER)

    .list();

This query will fetch both mate and kittens by outer join. See Section 19.1, "Fetching strategies" for more information.

このクエリは外部結合により mate とkittens の両方をフェッチします。より多くの情報は Section 19.1, "Fetching strategies" を参照してください。

15.6. Example queries(クエリの例)

The class org.hibernate.criterion.Example allows you to construct a query criterion from a given instance.

org.hibernate.criterion.Example クラスは、与えられたインスタンスからクエリクライテリオンを構築できます。

Cat cat = new Cat();

cat.setSex('F');

cat.setColor(Color.BLACK);

List results = session.createCriteria(Cat.class)

    .add( Example.create(cat) )

    .list();

Version properties, identifiers and associations are ignored. By default, null valued properties are excluded.

バージョンプロパティ、識別子、関連は無視されます。デフォルトではnull値のプロパティは除外されます。

You can adjust how the Example is applied.

どのように Example を適用するか調整することができます。

Example example = Example.create(cat)

    .excludeZeroes()           //exclude zero valued properties

    .excludeProperty("color")  //exclude the property named "color"

    .ignoreCase()              //perform case insensitive string comparisons

    .enableLike();             //use like for string comparisons

List results = session.createCriteria(Cat.class)

    .add(example)

    .list();

You can even use examples to place criteria upon associated objects.

関連オブジェクトにcriteriaを指定するために、Exampleを使うことも可能です。

List results = session.createCriteria(Cat.class)

    .add( Example.create(cat) )

    .createCriteria("mate")

        .add( Example.create( cat.getMate() ) )

    .list();

15.7. Projections, aggregation and grouping(射影、集約、グループ化)

The class org.hibernate.criterion.Projections is a factory for Projection instances. We apply a projection to a query by calling setProjection().

org.hibernate.criterion.Projections クラスはProjection インスタンスのファクトリです。setProjection() を呼び出すことで、クエリに射影を適用します。

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.rowCount() )

    .add( Restrictions.eq("color", Color.BLACK) )

    .list();

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.projectionList()

        .add( Projections.rowCount() )

        .add( Projections.avg("weight") )

        .add( Projections.max("weight") )

        .add( Projections.groupProperty("color") )

    )

    .list();

There is no explicit "group by" necessary in a criteria query. Certain projection types are defined to be grouping projections, which also appear in the SQL group by clause.

必要であっても、criteriaクエリに「group by」を明示する必要はありません。ある種のProjection型はグループ化射影として定義され、SQLの group by 節にも現れます。

An alias may optionally be assigned to a projection, so that the projected value may be referred to in restrictions or orderings. Here are two different ways to do this:

任意で射影に別名を付けられるため、射影される値はrestrictionやordering内から参照できます。別名をつける２つの異なる方法を示します。

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) )

    .addOrder( Order.asc("colr") )

    .list();

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.groupProperty("color").as("colr") )

    .addOrder( Order.asc("colr") )

    .list();

The alias() and as() methods simply wrap a projection instance in another, aliased, instance of Projection. As a shortcut, you can assign an alias when you add the projection to a projection list:

alias() と as() メソッドは、Projectionインスタンスを別の名前の Projection インスタンスでラップするだけです。ショートカットとして、射影を射影リストに追加する際に、別名をつけられます。

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.projectionList()

        .add( Projections.rowCount(), "catCountByColor" )

        .add( Projections.avg("weight"), "avgWeight" )

        .add( Projections.max("weight"), "maxWeight" )

        .add( Projections.groupProperty("color"), "color" )

    )

    .addOrder( Order.desc("catCountByColor") )

    .addOrder( Order.desc("avgWeight") )

    .list();

List results = session.createCriteria(Domestic.class, "cat")

    .createAlias("kittens", "kit")

    .setProjection( Projections.projectionList()

        .add( Projections.property("cat.name"), "catName" )

        .add( Projections.property("kit.name"), "kitName" )

    )

    .addOrder( Order.asc("catName") )

    .addOrder( Order.asc("kitName") )

    .list();

You can also use Property.forName() to express projections:

射影の式に Property.forName() も使用できます。

List results = session.createCriteria(Cat.class)

    .setProjection( Property.forName("name") )

    .add( Property.forName("color").eq(Color.BLACK) )

    .list();

List results = session.createCriteria(Cat.class)

    .setProjection( Projections.projectionList()

        .add( Projections.rowCount().as("catCountByColor") )

        .add( Property.forName("weight").avg().as("avgWeight") )

        .add( Property.forName("weight").max().as("maxWeight") )

        .add( Property.forName("color").group().as("color" )

    )

    .addOrder( Order.desc("catCountByColor") )

    .addOrder( Order.desc("avgWeight") )

    .list();

15.8. Detached queries and subqueries(クエリおよびサブクエリの分離)

The DetachedCriteria class lets you create a query outside the scope of a session, and then later execute it using some arbitrary Session.

DetachedCriteria クラスにより、セッションスコープ外にクエリを作成できます。後で、任意の Session を使って、実行できます。

DetachedCriteria query = DetachedCriteria.forClass(Cat.class)

    .add( Property.forName("sex").eq('F') );

    

Session session = ....;

Transaction txn = session.beginTransaction();

List results = query.getExecutableCriteria(session).setMaxResults(100).list();

txn.commit();

session.close();

A DetachedCriteria may also be used to express a subquery. Criterion instances involving subqueries may be obtained via Subqueries or Property.

DetachedCriteria は、サブクエリを表現するためにも使えます。サブクエリを伴うCriterionインスタンスは、Subqueries もしくは Property から得られます。

DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class)

    .setProjection( Property.forName("weight").avg() );

session.createCriteria(Cat.class)

    .add( Property.forName("weight).gt(avgWeight) )

    .list();

DetachedCriteria weights = DetachedCriteria.forClass(Cat.class)

    .setProjection( Property.forName("weight") );

session.createCriteria(Cat.class)

    .add( Subqueries.geAll("weight", weights) )

    .list();

Even correlated subqueries are possible:

相互関係があるサブクエリでさえも可能です。

DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2")

    .setProjection( Property.forName("weight").avg() )

    .add( Property.forName("cat2.sex").eqProperty("cat.sex") );

session.createCriteria(Cat.class, "cat")

    .add( Property.forName("weight).gt(avgWeightForSex) )

    .list();

15.9. Queries by natural identifier(自然識別子によるクエリ)

For most queries, including criteria queries, the query cache is not very efficient, because query cache invalidation occurs too frequently. However, there is one special kind of query where we can optimize the cache invalidation algorithm: lookups by a constant natural key. In some applications, this kind of query occurs frequently. The criteria API provides special provision for this use case.

criteriaクエリを含むたいていのクエリにとって、クエリキャッシュはあまり効率がよくないです。なぜなら、クエリキャッシュが頻繁に無効になるためです。しかしながら、キャッシュを無効にするアルゴリズムを最適化できる特別なクエリの種類が１つあります。更新されない自然キーによる検索です。いくつかのアプリケーションでは、この種類のクエリが頻繁に現れます。このような使われ方のために、criteria APIは特別な対策を提供します。

First, you should map the natural key of your entity using <natural-id>, and enable use of the second-level cache.

最初に、&lt;natural-id&gt; を使って、エンティティの自然キーをマップしてください。そして、二次キャッシュを有効にします。

<class name="User">

    <cache usage="read-write"/>

    <id name="id">

        <generator class="increment"/>

    </id>

    <natural-id>

        <property name="name"/>

        <property name="org"/>

    </natural-id>

    <property name="password"/>

</class>

Note that this functionality is not intended for use with entities with mutable natural keys.

注意：変更される自然キーを持つエンティティにこの機能を使うのは、意図されていない使い方です。

Next, enable the Hibernate query cache.

次に、Hibernateクエリキャッシュを有効にします。

Now, Restrictions.naturalId() allows us to make use of the more efficient cache algorithm.

これで、Restrictions.naturalId() により、より効率的なキャッシュアルゴリズムを使用できます。

session.createCriteria(User.class)

    .add( Restrictions.naturalId()

        .set("name", "gavin")

        .set("org", "hb") 

    ).setCacheable(true)

    .uniqueResult();