javax.persistence

インタフェース StoredProcedureQuery

すべてのスーパーインタフェース:

Query

public interface StoredProcedureQuery
extends Query

ストアドプロシージャーのクエリー実行を制御するために使用されるインターフェイスです。

ストアドプロシージャーのクエリーの実行は、以下のように制御されるでしょう。

• setParameterメソッドはすべての必須なINパラメーターとINOUTパラメーターの値を設定するために使用されます。 ストアドプロシージャーによってデフォルト値が定義されているストアドプロシージャーのパラメーターの値を設定する必要はありません。
• StoredProcedureQueryオブジェクトのgetResultListやgetSingleResultが呼び出されると、 実行されていないストアドプロシージャーのクエリーに対して プロバイダはgetResultListまたはgetSingleResultを処理する前に、 executeを呼び出すでしょう。
• StoredProcedureQueryオブジェクトのexecuteUpdateが呼び出されると、 プロバイダは実行されていないストアドプロシージャーのexecuteの実行に続いてgetUpdateCountを実行します。 executeUpdateの結果はgetUpdateCountの結果になるでしょう。
• executeメソッドは、最も一般的なケース (複数の結果セットおよび/または更新件数、場合によっては出力パラメータ値とも組み合わされる)だけでなく、 スカラー結果がINOUTおよびOUTパラメータを介して戻される単純なケースもサポートします。
• executeメソッドは、最初の結果が結果セットの場合はtrueを返し、 更新件数の場合や、INOUTおよびOUTパラメーターがあったとしても、それ以外の結果がない場合はfalseを返します。
• executeメソッドがtrueを返した場合、保留された結果セットはgetResultListやgetSingleResultを呼び出すことで取得できます。
• hasMoreResultsメソッドはさらに結果があるかどうかの確認に使用することができます。
• executeまたはhasMoreResultsがfalseを返した場合、 getUpdateCountメソッドを呼び出して、更新件数の場合は保留中の結果を取得できます。 getUpdateCountメソッドは更新件数(ゼロ以上)を、更新件数が存在しない場合(つまり、次の結果が結果セットである場合、もしくは次の更新件数がない場合)は-1を返します。
• 移植性のためにはINOUTやOUTパラメータの値が抽出される前に、 JDBC結果セットおよび更新件数に対応する結果を処理する必要があります。
• getResultListやgetUpdateCountで返された結果が枯渇した後、 INOUTおよびOUTパラメーターによって返される結果を取得できます。
• getOutputParameterValueメソッドは、プロシージャーからINOUTおよびOUTパラメーターを介して戻された値を取得するために使用されます。
• 結果セットにREF_CURSORパラメータを使用する場合、getResultListを呼び出して結果セットを取得する前に更新件数を枯渇させる必要があります。 代わりにREF_CURSOR結果セットはgetOutputParameterValueを使用して取得できます。 結果セットのマッピングはREF_CURSORパラメーターがクエリに登録された順序でREF_CURSORパラメーターに対応する結果に適用されます。
• 結果がINOUTおよびOUTパラメータを介してのみ返される最も単純なケースでは、 executeに続けてすぐにgetOutputParameterValueを呼び出すことができます。

導入されたバージョン:

Java Persistence 2.1

関連項目:

Query, Parameter

メソッドのサマリー

修飾子とタイプ	メソッドと説明
boolean	execute() 最初の結果が結果セットに対応する場合はtrueを返し、更新件数の場合や、INOUTおよびOUTパラメーター以外の結果が存在しない場合はfalseを返します。
int	executeUpdate() 保留中の結果がない場合や最初の結果が更新件数でない場合は、更新件数-1を返します。
java.lang.Object	getOutputParameterValue(int position) プロシージャーからINOUTまたはOUTパラメーターを介して戻された値を戻します。
java.lang.Object	getOutputParameterValue(java.lang.String parameterName) プロシージャーからINOUTまたはOUTパラメーターを介して戻された値を戻します。
java.util.List	getResultList() 次の結果セットから結果のリストを取得します。
java.lang.Object	getSingleResult() 次の結果セットから単一の結果を取得します。
int	getUpdateCount() 更新件数を返すか、保留している結果が存在しない場合や次の結果が更新件数でない場合は-1を返します。
boolean	hasMoreResults() 次の結果が結果セットに対応する場合はtrueを返し、更新件数の場合や、INOUTおよびOUTパラメーター以外の結果が存在しない場合はfalseを返します。
StoredProcedureQuery	registerStoredProcedureParameter(int position, java.lang.Class type, ParameterMode mode) 位置指定のパラメーターのを登録します。
StoredProcedureQuery	registerStoredProcedureParameter(java.lang.String parameterName, java.lang.Class type, ParameterMode mode) 名前付きパラメーターを登録します。
StoredProcedureQuery	setFlushMode(FlushModeType flushMode) クエリーの実行に使用されるフラッシュモードタイプを設定します。
StoredProcedureQuery	setHint(java.lang.String hintName, java.lang.Object value) クエリーのプロパティもしくはヒントを設定します。
StoredProcedureQuery	setParameter(int position, java.util.Calendar value, TemporalType temporalType) 位置指定のパラメーターにjava.util.Calendarのインスタンスをバインドします。
StoredProcedureQuery	setParameter(int position, java.util.Date value, TemporalType temporalType) 位置指定のパラメーターにjava.util.Dateのインスタンスをバインドします。
StoredProcedureQuery	setParameter(int position, java.lang.Object value) 位置指定のパラメーターに引数の値をバインドします。
StoredProcedureQuery	setParameter(Parameter<java.util.Calendar> param, java.util.Calendar value, TemporalType temporalType) Parameterオブジェクトにjava.util.Calendarのインスタンスをバインドします。
StoredProcedureQuery	setParameter(Parameter<java.util.Date> param, java.util.Date value, TemporalType temporalType) Parameterオブジェクトにjava.util.Dateのインスタンスをバインドします。
<T> StoredProcedureQuery	setParameter(Parameter<T> param, T value) Parameterオブジェクトの値をバインドします。
StoredProcedureQuery	setParameter(java.lang.String name, java.util.Calendar value, TemporalType temporalType) 名前付きパラメーターにjava.util.Calendarのインスタンスをバインドします。
StoredProcedureQuery	setParameter(java.lang.String name, java.util.Date value, TemporalType temporalType) 名前付きパラメーターにjava.util.Dateのインスタンスをバインドします。
StoredProcedureQuery	setParameter(java.lang.String name, java.lang.Object value) 名前付きパラメーターに引数の値をバインドします。

インタフェースから継承されたメソッド javax.persistence.Query

getFirstResult, getFlushMode, getHints, getLockMode, getMaxResults, getParameter, getParameter, getParameter, getParameter, getParameters, getParameterValue, getParameterValue, getParameterValue, getResultStream, isBound, setFirstResult, setLockMode, setMaxResults, unwrap

メソッドの詳細

setHint

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

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

定義:

setHint インタフェース内 Query

パラメータ:

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

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

戻り値:

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

例外:

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

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

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

value - パラメーターの値

戻り値:

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

例外:

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

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

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

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

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

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

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

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

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

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

name - パラメーターの名前

value - パラメーターの値

戻り値:

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

例外:

java.lang.IllegalArgumentException - パラメーター名に適合するパラメーターがクエリーに存在しないか、引数が不正な型の場合

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

name - パラメーターの名前

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

java.lang.IllegalArgumentException - パラメーター名に適合するパラメーターがクエリーに存在しないか、引数が不正な型の場合

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

name - パラメーターの名前

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

java.lang.IllegalArgumentException - パラメーター名に適合するパラメーターがクエリーに存在しないか、引数が不正な型の場合

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

position - 位置

value - パラメーターの値

戻り値:

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

例外:

java.lang.IllegalArgumentException - 位置に適合する位置指定のパラメーターがクエリーに存在しないか、引数が不正な型の場合

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

position - 位置

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

java.lang.IllegalArgumentException - 位置に適合する位置指定のパラメーターがクエリーに存在しないか、引数が不正な型の場合

setParameter

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

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

定義:

setParameter インタフェース内 Query

パラメータ:

position - 位置

value - パラメーターの値

temporalType - 時制の型

戻り値:

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

例外:

java.lang.IllegalArgumentException - 位置に適合する位置指定のパラメーターがクエリーに存在しないか、引数が不正な型の場合

setFlushMode

StoredProcedureQuery setFlushMode(FlushModeType flushMode)

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

定義:

setFlushMode インタフェース内 Query

パラメータ:

flushMode - フラッシュモード

戻り値:

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

registerStoredProcedureParameter

StoredProcedureQuery registerStoredProcedureParameter(int position,
                                                      java.lang.Class type,
                                                      ParameterMode mode)

位置指定のパラメーターのを登録します。 すべてのパラメーターを登録する必要があります。

パラメータ:

position - パラメーターの位置

type - パラメーターの型

mode - パラメーターの形式

戻り値:

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

registerStoredProcedureParameter

StoredProcedureQuery registerStoredProcedureParameter(java.lang.String parameterName,
                                                      java.lang.Class type,
                                                      ParameterMode mode)

名前付きパラメーターを登録します。

パラメータ:

parameterName - 登録されているかメタデータで指定されているパラメーターの名前

type - パラメーターの型

mode - パラメーターの形式

戻り値:

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

getOutputParameterValue

java.lang.Object getOutputParameterValue(int position)

プロシージャーからINOUTまたはOUTパラメーターを介して戻された値を戻します。 移植性のためには結果セットと更新件数に対応するすべての結果を出力パラメータの値よりも前に取得する必要があります。

パラメータ:

position - パラメーターの位置

戻り値:

パラメーターを介して返された結果

例外:

java.lang.IllegalArgumentException - 位置がクエリーのパラメーターに対応しない場合、またはINOUTまたはOUTパラメータでない場合

getOutputParameterValue

java.lang.Object getOutputParameterValue(java.lang.String parameterName)

プロシージャーからINOUTまたはOUTパラメーターを介して戻された値を戻します。 移植性のためには結果セットと更新件数に対応するすべての結果を出力パラメータの値よりも前に取得する必要があります。

パラメータ:

parameterName - メタデータに登録または指定されたパラメーターの名前

戻り値:

パラメーターを介して返された結果

例外:

java.lang.IllegalArgumentException - パラメーター名がクエリーのパラメーターに対応しない場合、またはINOUTまたはOUTパラメータでない場合

execute

boolean execute()

最初の結果が結果セットに対応する場合はtrueを返し、更新件数の場合や、INOUTおよびOUTパラメーター以外の結果が存在しない場合はfalseを返します。

戻り値:

最初の結果が結果セットに関連する場合はtrue

例外:

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

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

executeUpdate

int executeUpdate()

保留中の結果がない場合や最初の結果が更新件数でない場合は、更新件数-1を返します。 プロバイダは必要に応じてクエリーのexecuteを呼び出します。

定義:

executeUpdate インタフェース内 Query

戻り値:

更新件数か、保留している結果が存在しない場合や次の結果が更新件数でない場合は-1

例外:

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

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

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

getResultList

java.util.List getResultList()

次の結果セットから結果のリストを取得します。 プロバイダは、必要に応じてクエリーのexecuteを呼び出します。 REF_CURSOR結果セットが存在する場合はREF_CURSORパラメーターがクエリーに登録された順に取得されます。

定義:

getResultList インタフェース内 Query

戻り値:

結果のリスト、次のアイテムが結果セットでない場合はnull

例外:

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

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

getSingleResult

java.lang.Object getSingleResult()

次の結果セットから単一の結果を取得します。 プロバイダは、必要に応じてクエリーのexecuteを呼び出します。 REF_CURSOR結果セットが存在する場合はREF_CURSORパラメーターがクエリーに登録された順に取得されます。

定義:

getSingleResult インタフェース内 Query

戻り値:

結果の値、次のアイテムが結果セットでない場合はnull

例外:

NoResultException - 次の結果セットに結果が存在しない場合

NonUniqueResultException - 二つ以上の結果が存在した場合

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

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

hasMoreResults

boolean hasMoreResults()

次の結果が結果セットに対応する場合はtrueを返し、更新件数の場合や、INOUTおよびOUTパラメーター以外の結果が存在しない場合はfalseを返します。

戻り値:

次の結果が結果セットに対応する場合はtrue

例外:

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

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

getUpdateCount

int getUpdateCount()

更新件数を返すか、保留している結果が存在しない場合や次の結果が更新件数でない場合は-1を返します。

戻り値:

更新件数か、保留している結果が存在しない場合や次の結果が更新件数でない場合は-1

例外:

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

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