javax.persistence

インタフェース Query

既知のサブインタフェースのリスト:

StoredProcedureQuery, TypedQuery<X>

public interface Query

クエリー実行のコントロールに使用するインターフェースです。

導入されたバージョン:

Java Persistence 1.0

関連項目:

TypedQuery, StoredProcedureQuery, Parameter

メソッドのサマリー

修飾子とタイプ	メソッドと説明
int	executeUpdate() 更新または削除ステートメントを実行します。
int	getFirstResult() クエリーオブジェクトが取得するように設定された結果の最初のポジション。
FlushModeType	getFlushMode() クエリーの実行に有効なフラッシュモードを取得します。
java.util.Map<java.lang.String,java.lang.Object>	getHints() クエリーインスタンスで有効なプロパティとヒントと関連する値を取得します。
LockModeType	getLockMode() クエリーの現在のロックモードを取得します。
int	getMaxResults() クエリーオブジェクトが取得するように設定された結果の最大件数。
Parameter<?>	getParameter(int position) 宣言された位置のパラメーターに対応するパラメータオブジェクトを指定された位置で取得します。
<T> Parameter<T>	getParameter(int position, java.lang.Class<T> type) 宣言された位置のパラメーターに対応するパラメータオブジェクトを指定された位置と型で取得します。
Parameter<?>	getParameter(java.lang.String name) 与えられた名前の宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。
<T> Parameter<T>	getParameter(java.lang.String name, java.lang.Class<T> type) 与えられた名前と型の宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。
java.util.Set<Parameter<?>>	getParameters() クエリーの宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。
java.lang.Object	getParameterValue(int position) 位置パラメーターにバインドされた入力値を返します。
<T> T	getParameterValue(Parameter<T> param) パラメーターにバインドされた入力値を返します。
java.lang.Object	getParameterValue(java.lang.String name) 名前付きパラメーターにバインドされた入力値を返します。
java.util.List	getResultList() SELECTクエリーを実行し、問合せ結果を型のないリストとして返します。
default java.util.stream.Stream	getResultStream() SELECTクエリーを実行し、問合せ結果を型のないjava.util.stream.Streamとして戻します。
java.lang.Object	getSingleResult() 一つの型のない結果を返すSELECTクエリーを実行します。
boolean	isBound(Parameter<?> param) 値がパラメータにバインドされているかどうかを示すbooleanを返します。
Query	setFirstResult(int startPosition) 検索結果を取得する最初のポジションを設定します。
Query	setFlushMode(FlushModeType flushMode) クエリーの実行に使用されるフラッシュモードタイプを設定します。
Query	setHint(java.lang.String hintName, java.lang.Object value) クエリーのプロパティもしくはヒントを設定します。
Query	setLockMode(LockModeType lockMode) クエリーの実行に使用されるロックモードタイプを設定します。
Query	setMaxResults(int maxResult) 取得する結果の最大件数を設定します。
Query	setParameter(int position, java.util.Calendar value, TemporalType temporalType) 位置指定のパラメーターにjava.util.Calendarの値をバインドします。
Query	setParameter(int position, java.util.Date value, TemporalType temporalType) 位置指定のパラメーターにjava.util.Dateの値をバインドします。
Query	setParameter(int position, java.lang.Object value) 位置指定のパラメーターに引数の値をバインドします。
Query	setParameter(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType) java.util.CalendarのインスタンスをParameterオブジェクトにバインドします。
Query	setParameter(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType) java.util.DateのインスタンスをParameterオブジェクトにバインドします。
<T> Query	setParameter(Parameter<T> param, T value) Parameterオブジェクトの値をバインドします。
Query	setParameter(java.lang.String name, java.util.Calendar value, TemporalType temporalType) java.util.Calendarのインスタンスを名前付きパラメーターにバインドします。
Query	setParameter(java.lang.String name, java.util.Date value, TemporalType temporalType) java.util.Dateのインスタンスを名前付きパラメーターにバインドします。
Query	setParameter(java.lang.String name, java.lang.Object value) 引数の値を名前付きパラメーターにバインドします。
<T> T	unwrap(java.lang.Class<T> cls) プロバイダ固有のAPIにアクセスできるように、指定された型のオブジェクトを返します。

メソッドの詳細

getResultList

java.util.List getResultList()

SELECTクエリーを実行し、問合せ結果を型のないリストとして返します。

戻り値:

結果のリスト

例外:

java.lang.IllegalStateException - Java Persistenceクエリー言語のUPDATEまたはDELETE文で呼び出された場合

QueryTimeoutException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、そのステートメントだけがロールバックされる場合

TransactionRequiredException - NONE以外のロックモードが設定されトランザクションが存在しない場合、 または永続化コンテキストがトランザクションに参加していない場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされる場合

LockTimeoutException - 悲観ロックに失敗し、そのステートメントのみロールバックされる場合

PersistenceException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、トランザクションがロールバックされる場合

getResultStream

default java.util.stream.Stream getResultStream()

SELECTクエリーを実行し、問合せ結果を型のないjava.util.stream.Streamとして戻します。 デフォルトでは、このメソッドはgetResultList().stream()に委譲しますが、 永続化プロバイダはこのメソッドをオーバーライドして追加の機能を提供することもできます。

戻り値:

結果のストリーム

例外:

java.lang.IllegalStateException - Java Persistenceクエリー言語のUPDATEまたはDELETE文で呼び出された場合

QueryTimeoutException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、そのステートメントだけがロールバックされる場合

TransactionRequiredException - NONE以外のロックモードが設定されトランザクションが存在しない場合、 または永続化コンテキストがトランザクションに参加していない場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされる場合

LockTimeoutException - 悲観ロックに失敗し、そのステートメントのみロールバックされる場合

PersistenceException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、トランザクションがロールバックされる場合

導入されたバージョン:

2.2

関連項目:

Stream, getResultList()

getSingleResult

java.lang.Object getSingleResult()

一つの型のない結果を返すSELECTクエリーを実行します。

戻り値:

結果

例外:

NoResultException - 結果がなかった場合

NonUniqueResultException - 2つ以上の結果があった場合

java.lang.IllegalStateException - Java Persistenceクエリー言語のUPDATEまたはDELETE文で呼び出された場合

QueryTimeoutException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、そのステートメントだけがロールバックされる場合

TransactionRequiredException - NONE以外のロックモードが設定されトランザクションが存在しない場合、 または永続化コンテキストがトランザクションに参加していない場合

PessimisticLockException - 悲観ロックに失敗し、トランザクションがロールバックされる場合

LockTimeoutException - 悲観ロックに失敗し、そのステートメントのみロールバックされる場合

PersistenceException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、トランザクションがロールバックされる場合

executeUpdate

int executeUpdate()

更新または削除ステートメントを実行します。

戻り値:

エンティティが更新や削除された数

例外:

java.lang.IllegalStateException - Java Persistenceクエリー言語のSELECT文もしくはクライテリアクエリーで呼び出された場合

TransactionRequiredException - トランザクションが存在しない場合、 または永続化コンテキストがトランザクションに参加していない場合

QueryTimeoutException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、そのステートメントだけがロールバックされる場合

PersistenceException - クエリーの実行がクエリーの設定されたタイムアウト値を超え、トランザクションがロールバックされる場合

setMaxResults

Query setMaxResults(int maxResult)

取得する結果の最大件数を設定します。

パラメータ:

maxResult - 取得する結果の最大件数

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 引数が負の数の場合

getMaxResults

int getMaxResults()

クエリーオブジェクトが取得するように設定された結果の最大件数。 setMaxResultsがクエリーオブジェクトで呼び出されていなかった場合はInteger.MAX_VALUEを返します。

戻り値:

結果の最大件数

導入されたバージョン:

Java Persistence 2.0

setFirstResult

Query setFirstResult(int startPosition)

検索結果を取得する最初のポジションを設定します。

パラメータ:

startPosition - 検索結果の0から始まる最初のポジション

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 引数が負数だった場合

getFirstResult

int getFirstResult()

クエリーオブジェクトが取得するように設定された結果の最初のポジション。 setFirstResultがクエリーオブジェクトで呼び出されていなかった場合は0を返します。

戻り値:

結果の最初のポジション

導入されたバージョン:

Java Persistence 2.0

setHint

Query setHint(java.lang.String hintName,
              java.lang.Object value)

クエリーのプロパティもしくはヒントを設定します。 ヒント要素はクエリーのプロパティとヒントを指定するために使用できます。 この仕様で定義されているプロパティはプロバイダによって監視されなければなりません。 プロバイダによって認識されないベンダー固有のヒントは、暗黙のうちに無視されなければなりません。 ポータブルアプリケーションは標準のタイムアウトのヒントに頼るべきではありません。 使用されているデータベースおよびプロバイダによっては、このヒントが監視されるかどうかはわかりません。

パラメータ:

hintName - プロパティもしくはヒントの名前

value - プロパティもしくはヒントのための値

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - 二つ目の引数が実装に適合しない場合

getHints

java.util.Map<java.lang.String,java.lang.Object> getHints()

クエリーインスタンスで有効なプロパティとヒントと関連する値を取得します。

戻り値:

クエリーのプロパティとヒント

導入されたバージョン:

Java Persistence 2.0

setParameter

<T> Query setParameter(Parameter<T> param,
                       T value)

Parameterオブジェクトの値をバインドします。

パラメータ:

param - パラメーターオブジェクト

value - パラメーターの値

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーターがクエリーのパラメーターに対応しない場合

導入されたバージョン:

Java Persistence 2.0

setParameter

Query setParameter(Parameter<java.util.Calendar> param,
                   java.util.Calendar value,
                   TemporalType temporalType)

java.util.CalendarのインスタンスをParameterオブジェクトにバインドします。

パラメータ:

param - パラメーターオブジェクト

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーターがクエリーのパラメーターに対応しない場合

導入されたバージョン:

Java Persistence 2.0

setParameter

Query setParameter(Parameter<java.util.Date> param,
                   java.util.Date value,
                   TemporalType temporalType)

java.util.DateのインスタンスをParameterオブジェクトにバインドします。

パラメータ:

param - パラメーターオブジェクト

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーターがクエリーのパラメーターに対応しない場合

導入されたバージョン:

Java Persistence 2.0

setParameter

Query setParameter(java.lang.String name,
                   java.lang.Object value)

引数の値を名前付きパラメーターにバインドします。

パラメータ:

name - パラメーターの名前

value - パラメーターの値

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーター名がクエリーのパラメーターに対応しない場合、もしくは引数が不正な型の場合

setParameter

Query setParameter(java.lang.String name,
                   java.util.Calendar value,
                   TemporalType temporalType)

java.util.Calendarのインスタンスを名前付きパラメーターにバインドします。

パラメータ:

name - パラメーターの名前

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーター名がクエリーのパラメーターに対応しない場合、もしくは引数が不正な型の場合

setParameter

Query setParameter(java.lang.String name,
                   java.util.Date value,
                   TemporalType temporalType)

java.util.Dateのインスタンスを名前付きパラメーターにバインドします。

パラメータ:

name - パラメーターの名前

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - パラメーター名がクエリーのパラメーターに対応しない場合、もしくは引数が不正な型の場合

setParameter

Query setParameter(int position,
                   java.lang.Object value)

位置指定のパラメーターに引数の値をバインドします。

パラメータ:

position - 位置

value - パラメーターの値

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - positionがクエリーの位置指定のパラメーターに対応しない場合、もしくは引数が不正な型の場合

setParameter

Query setParameter(int position,
                   java.util.Calendar value,
                   TemporalType temporalType)

位置指定のパラメーターにjava.util.Calendarの値をバインドします。

パラメータ:

position - 位置

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - positionがクエリーの位置指定のパラメーターに対応しない場合、もしくは引数が不正な型の場合

setParameter

Query setParameter(int position,
                   java.util.Date value,
                   TemporalType temporalType)

位置指定のパラメーターにjava.util.Dateの値をバインドします。

パラメータ:

position - 位置

value - パラメーターの値

temporalType - 時制の型

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalArgumentException - positionがクエリーの位置指定のパラメーターに対応しない場合、もしくは引数が不正な型の場合

getParameters

java.util.Set<Parameter<?>> getParameters()

クエリーの宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。 クエリーにパラメーターがない場合は空のセットを返します。 このメソッドはネイティブクエリーではサポートされない場合があります。

戻り値:

パラメーターオブジェクトのSet

例外:

java.lang.IllegalStateException - 実装がこの使用をサポートしていないネイティブクエリーで呼び出された場合

導入されたバージョン:

Java Persistence 2.0

getParameter

Parameter<?> getParameter(java.lang.String name)

与えられた名前の宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。 このメソッドはネイティブクエリーではサポートされない場合があります。

パラメータ:

name - パラメーターの名前

戻り値:

パラメーターオブジェクト

例外:

java.lang.IllegalArgumentException - 指定した名前のパラメーターが存在しない場合

java.lang.IllegalStateException - 実装がこの使用をサポートしていないネイティブクエリーで呼び出された場合

導入されたバージョン:

Java Persistence 2.0

getParameter

<T> Parameter<T> getParameter(java.lang.String name,
                              java.lang.Class<T> type)

与えられた名前と型の宣言されたパラメーターに対応するパラメーターオブジェクトを取得します。 このメソッドはクライテリアクエリー以外ではサポートされない場合があります。

パラメータ:

name - パラメーターの名前

type - 型

戻り値:

パラメーターオブジェクト

例外:

java.lang.IllegalArgumentException - 指定した名前のパラメーターが存在しないか、型が割り当て不能な場合

java.lang.IllegalStateException - 実装がこの使用をサポートしてないネイティブクエリーかJPQLクエリーで呼び出された場合

導入されたバージョン:

Java Persistence 2.0

getParameter

Parameter<?> getParameter(int position)

宣言された位置のパラメーターに対応するパラメータオブジェクトを指定された位置で取得します。 このメソッドはネイティブクエリーではサポートされない場合があります。

パラメータ:

position - 位置

戻り値:

パラメーターオブジェクト

例外:

java.lang.IllegalArgumentException - 指定した位置のパラメーターが存在しない場合

java.lang.IllegalStateException - 実装がこの使用をサポートしていないネイティブクエリーで呼び出された場合

導入されたバージョン:

Java Persistence 2.0

getParameter

<T> Parameter<T> getParameter(int position,
                              java.lang.Class<T> type)

宣言された位置のパラメーターに対応するパラメータオブジェクトを指定された位置と型で取得します。 このメソッドはプロバイダによってはサポートされない場合があります。

パラメータ:

position - 位置

type - 型

戻り値:

パラメーターオブジェクト

例外:

java.lang.IllegalArgumentException - 指定した位置のパラメーターが存在しないか、型が割り当て不能な場合

java.lang.IllegalStateException - 実装がこの使用をサポートしてないネイティブクエリーかJPQLクエリーで呼び出された場合

導入されたバージョン:

Java Persistence 2.0

isBound

boolean isBound(Parameter<?> param)

値がパラメータにバインドされているかどうかを示すbooleanを返します。

パラメータ:

param - パラメーターオブジェクト

戻り値:

パラメータがバインドされているかどうかを示すboolean

導入されたバージョン:

Java Persistence 2.0

getParameterValue

<T> T getParameterValue(Parameter<T> param)

パラメーターにバインドされた入力値を返します。 (注意：OUTパラメータはバインドされていません。)

パラメータ:

param - パラメーターオブジェクト

戻り値:

パラメーターの値

例外:

java.lang.IllegalArgumentException - パラメーターがクエリーのパラメーターでない場合

java.lang.IllegalStateException - パラメーターがバインドされてない場合

導入されたバージョン:

Java Persistence 2.0

getParameterValue

java.lang.Object getParameterValue(java.lang.String name)

名前付きパラメーターにバインドされた入力値を返します。 (注意：OUTパラメータはバインドされていません。)

パラメータ:

name - パラメーターの名前

戻り値:

パラメーターの値

例外:

java.lang.IllegalStateException - パラメーターがバインドされてない場合

java.lang.IllegalArgumentException - 指定された名前のパラメーターが存在しない場合

導入されたバージョン:

Java Persistence 2.0

getParameterValue

java.lang.Object getParameterValue(int position)

位置パラメーターにバインドされた入力値を返します。 (注意：OUTパラメータはバインドされていません。)

パラメータ:

position - 位置

戻り値:

パラメーターの値

例外:

java.lang.IllegalStateException - パラメーターがバインドされてない場合

java.lang.IllegalArgumentException - 指定された位置にパラメーターが存在しない場合

導入されたバージョン:

Java Persistence 2.0

setFlushMode

Query setFlushMode(FlushModeType flushMode)

クエリーの実行に使用されるフラッシュモードタイプを設定します。 フラッシュモードタイプはエンティティマネージャーで使用中のフラッシュモードタイプと関係なくクエリーに適用されます。

パラメータ:

flushMode - フラッシュモード

戻り値:

同じクエリーのインスタンス

getFlushMode

FlushModeType getFlushMode()

クエリーの実行に有効なフラッシュモードを取得します。 クエリーオブジェクトにフラッシュモードが設定されていない場合は、エンティティマネージャーで有効なフラッシュモードを返します。

戻り値:

フラッシュモード

導入されたバージョン:

Java Persistence 2.0

setLockMode

Query setLockMode(LockModeType lockMode)

クエリーの実行に使用されるロックモードタイプを設定します。

パラメータ:

lockMode - ロックモード

戻り値:

同じクエリーのインスタンス

例外:

java.lang.IllegalStateException - クエリーがJava Persistenceクエリー言語のSELECTクエリーかCriteriaQueryクエリーでないと判明した場合

導入されたバージョン:

Java Persistence 2.0

getLockMode

LockModeType getLockMode()

クエリーの現在のロックモードを取得します。 nullが返ってくる場合はクエリーオブジェクトにロックモードが設定されていません。

戻り値:

ロックモード

例外:

java.lang.IllegalStateException - クエリーがJava Persistenceクエリー言語のSELECTクエリーかCriteriaQueryクエリーでないと判明した場合

導入されたバージョン:

Java Persistence 2.0

unwrap

<T> T unwrap(java.lang.Class<T> cls)

プロバイダ固有のAPIにアクセスできるように、指定された型のオブジェクトを返します。 プロバイダのクエリー実装が指定されたクラスをサポートしていない場合、 PersistenceExceptionが投げられます。

パラメータ:

cls - 返されるオブジェクトのクラス、通常だと基礎となるクエリーの実装クラスか実装するインターフェイスのいずれかです。

戻り値:

指定されたクラスのインスタンス

例外:

PersistenceException - プロバイダが呼び出しをサポートしない場合

導入されたバージョン:

Java Persistence 2.0