パッケージ jakarta.persistence

インターフェース StoredProcedureQuery

すべてのスーパーインターフェース:
Query
public interface StoredProcedureQuery extends Query
ストアドプロシージャクエリの実行を制御するために使用されるインターフェース。

ストアドプロシージャクエリの実行は、以下に従って制御できます。

  • setParameter(jakarta.persistence.Parameter<T>, T) メソッドは、すべての必須 IN および INOUT パラメーターの値を設定するために使用されます。ストアドプロシージャによってデフォルト値が定義されているストアドプロシージャパラメーターの値を設定する必要はありません。
  • getResultList() および getSingleResult() が StoredProcedureQuery オブジェクトで呼び出される場合、プロバイダーは getResultList または getSingleResult を処理する前に、未実行のストアドプロシージャクエリで execute() を呼び出します。
  • executeUpdate() が StoredProcedureQuery オブジェクトで呼び出される場合、プロバイダーは未実行のストアドプロシージャクエリで execute() を呼び出し、その後に getUpdateCount() を呼び出します。executeUpdate の結果は getUpdateCount の結果になります。
  • execute() メソッドは、スカラー結果が INOUT および OUT パラメーターを介してのみ返される単純なケースと、最も一般的なケース (複数の結果セットおよび / または更新カウント、場合によっては出力パラメーター値との組み合わせ) の両方をサポートします。
  • execute メソッドは、最初の結果が結果セットである場合は true を返し、更新カウントである場合、INOUT および OUT パラメーター（存在する場合）以外の結果がない場合は false を返します。
  • execute メソッドが true を返す場合、保留中の結果セットは getResultList() または getSingleResult() を呼び出すことで取得できます。
  • その後、hasMoreResults() メソッドを使用してさらなる結果をテストできます。
  • execute または hasMoreResults が false を返した場合、更新カウントの場合は、getUpdateCount() メソッドを呼び出して保留中の結果を取得できます。getUpdateCount メソッドは、更新カウント (0 以上) を返すか、更新カウントがない場合 (つまり、次の結果が結果セットであるか、次の更新カウントがない場合) は -1 を返します。
  • 移植性のために、JDBC 結果セットおよび更新カウントに対応する結果は、INOUT または OUT パラメーターの値が抽出される前に処理される必要があります。
  • getResultList() および getUpdateCount() を通じて返された結果を使い果たした後、INOUT および OUT パラメーターを通じて返された結果を取得できます。
  • getOutputParameterValue(int) メソッドは、INOUT および OUT パラメーターを通じてプロシージャから返された値を取得するために使用されます。
  • 結果セットに REF_CURSOR パラメーターを使用する場合は、getResultList() を呼び出して結果セットを取得する前に、更新カウントを使い果たす必要があります。あるいは、REF_CURSOR 結果セットは getOutputParameterValue(int) を通じて取得できます。結果セットのマッピングは、REF_CURSOR パラメーターがクエリに登録された順序で、REF_CURSOR パラメーターに対応する結果に適用されます。
  • INOUT および OUT パラメーターを介してのみ結果が返される最も単純なケースでは、execute の直後に getOutputParameterValue(int) を呼び出すことができます。
導入:
2.1
関連事項:

  • メソッドの詳細

    • setHint

      StoredProcedureQuery setHint(StringSE hintName, ObjectSE value)
      クエリプロパティまたはヒントを設定します。ヒント要素は、クエリのプロパティとヒントを指定するために使用できます。この仕様で定義されたプロパティは、プロバイダーによって監視される必要があります。プロバイダーによって認識されないベンダー固有のヒントは、確認なしで無視する必要があります。ポータブルアプリケーションは、標準のタイムアウトヒントに依存しないでください。使用中のデータベースに応じて、このヒントは観測される場合と観測されない場合があります。
      次で指定:
      インターフェース Query の setHint 
      パラメーター:
      hintName - プロパティまたはヒントの名前
      value - プロパティまたはヒントの値
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - 2 番目の引数が実装に有効でない場合

    • setParameter

      <T> StoredProcedureQuery setParameter(Parameter<T> param, T value)
      Parameter オブジェクトの値をバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      param - パラメーターオブジェクト
      value - パラメーター値
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーターがクエリのパラメーターに対応していない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(Parameter<CalendarSE> param, CalendarSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      CalendarSE のインスタンスを Parameter オブジェクトにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      param - パラメーターオブジェクト
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーターがクエリのパラメーターに対応していない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(Parameter<DateSE> param, DateSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      DateSE のインスタンスを Parameter オブジェクトにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      param - パラメーターオブジェクト
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーターがクエリのパラメーターに対応していない場合

    • setParameter

      StoredProcedureQuery setParameter(StringSE name, ObjectSE value)
      引数値を名前付きパラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      name - パラメーター名
      value - パラメーター値
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーター名がクエリのパラメーターに対応していない場合、または引数の型が正しくない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(StringSE name, CalendarSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      java.util.Calendar のインスタンスを名前付きパラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      name - パラメーター名
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーター名がクエリのパラメーターに対応していない場合、または値の引数の型が正しくない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(StringSE name, DateSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      java.util.Date のインスタンスを名前付きパラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      name - パラメーター名
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - パラメーター名がクエリのパラメーターに対応していない場合、または値の引数の型が正しくない場合

    • setParameter

      StoredProcedureQuery setParameter(int position, ObjectSE value)
      引数値を定位置パラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      position - 位置
      value - パラメーター値
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - 位置がクエリの位置パラメーターに対応していない場合、または引数の型が正しくない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(int position, CalendarSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      java.util.Calendar のインスタンスを定位置パラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      position - 位置
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - 位置がクエリの位置パラメーターに対応していない場合、または値の引数の型が正しくない場合

    • setParameter

      @DeprecatedSE(since="3.2") StoredProcedureQuery setParameter(int position, DateSE value, TemporalType temporalType)
      使用すべきではありません。
      新しく作成したコードでは、java.timeSE で定義された日付 / 時刻型を使用する必要があります。
      java.util.Date のインスタンスを定位置パラメーターにバインドします。
      次で指定:
      インターフェース Query の setParameter 
      パラメーター:
      position - 位置
      value - パラメーター値
      temporalType - 時間型
      戻り値:
      同じクエリインスタンス
      例外:
      IllegalArgumentExceptionSE - 位置がクエリの位置パラメーターに対応していない場合、または値の引数の型が正しくない場合

    • setFlushMode

      StoredProcedureQuery setFlushMode(FlushModeType flushMode)
      クエリの実行に使用するフラッシュモード型を設定します。フラッシュモード型は、エンティティマネージャーで使用されているフラッシュモード型に関係なく、クエリに適用されます。
      次で指定:
      インターフェース Query の setFlushMode 
      パラメーター:
      flushMode - フラッシュモード
      戻り値:
      同じクエリインスタンス

    • setCacheRetrieveMode

      StoredProcedureQuery setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)
      クエリ実行時に有効なキャッシュ取得モードを設定します。このキャッシュ取得モードは、エンティティマネージャーが使用しているキャッシュ取得モードをオーバーライドします。
      次で指定:
      インターフェース Query の setCacheRetrieveMode 
      パラメーター:
      cacheRetrieveMode - キャッシュ取得モード
      戻り値:
      同じクエリインスタンス
      導入:
      3.2

    • setCacheStoreMode

      StoredProcedureQuery setCacheStoreMode(CacheStoreMode cacheStoreMode)
      クエリ実行時に有効なキャッシュストレージモードを設定します。このキャッシュストレージモードは、エンティティマネージャーが使用しているキャッシュストレージモードをオーバーライドします。
      次で指定:
      インターフェース Query の setCacheStoreMode 
      パラメーター:
      cacheStoreMode - キャッシュストレージモード
      戻り値:
      同じクエリインスタンス
      導入:
      3.2

    • setTimeout

      StoredProcedureQuery setTimeout(IntegerSE timeout)
      クエリのタイムアウトをミリ秒単位で設定します。これはヒントであり、ヒント jakarta.persistence.query.timeout を設定する代わりに使用できます。
      次で指定:
      インターフェース Query の setTimeout 
      パラメーター:
      timeout - タイムアウト（ミリ秒単位）、またはタイムアウトなしを示す場合は null
      戻り値:
      同じクエリインスタンス
      導入:
      3.2

    • registerStoredProcedureParameter

      StoredProcedureQuery registerStoredProcedureParameter(int position, ClassSE<?> type, ParameterMode mode)
      位置パラメーターを登録します。すべてのパラメーターを登録する必要があります。
      パラメーター:
      position - パラメーターの位置
      type - パラメーターの型
      mode - パラメーターモード
      戻り値:
      同じクエリインスタンス

    • registerStoredProcedureParameter

      StoredProcedureQuery registerStoredProcedureParameter(StringSE parameterName, ClassSE<?> type, ParameterMode mode)
      名前付きパラメーターを登録します。
      パラメーター:
      parameterName - メタデータに登録または指定されているパラメーターの名前
      type - パラメーターの型
      mode - パラメーターモード
      戻り値:
      同じクエリインスタンス

    • getOutputParameterValue

      ObjectSE getOutputParameterValue(int position)
      INOUT または OUT パラメーターを介してプロシージャから返された値を取得します。移植性のために、結果セットと更新カウントに対応するすべての結果は、出力パラメーターの値の前に取得する必要があります。
      パラメーター:
      position - パラメーターの位置
      戻り値:
      パラメーターを介して返される結果
      例外:
      IllegalArgumentExceptionSE - 位置がクエリのパラメーターに対応していないか、INOUT または OUT パラメーターではない場合

    • getOutputParameterValue

      ObjectSE getOutputParameterValue(StringSE parameterName)
      INOUT または OUT パラメーターを介してプロシージャから返された値を取得します。移植性のために、結果セットと更新カウントに対応するすべての結果は、出力パラメーターの値の前に取得する必要があります。
      パラメーター:
      parameterName - メタデータに登録または指定されているパラメーターの名前
      戻り値:
      パラメーターを介して返される結果
      例外:
      IllegalArgumentExceptionSE - パラメーター名がクエリのパラメーターに対応していないか、INOUT または OUT パラメーターではない場合

    • execute

      boolean execute()
      最初の結果が結果セットに対応する場合は true を返し、それが更新カウントである場合、INOUT および OUT パラメーターを介して以外に結果がない場合は false を返します。
      戻り値:
      最初の結果が結果セットに対応する場合は true
      例外:
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • executeUpdate

      int executeUpdate()
      保留中の結果がない場合、または最初の結果が更新カウントでない場合は、更新カウント -1 を返します。プロバイダーは、必要に応じてクエリで execute を呼び出します。
      次で指定:
      インターフェース Query の executeUpdate 
      戻り値:
      更新カウント。保留中の結果がない場合、または次の結果が更新カウントでない場合は -1。
      例外:
      TransactionRequiredException - トランザクションがないか、永続コンテキストがトランザクションに参加していない場合
      QueryTimeoutException - ステートメントの実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • getResultList

      ListSE getResultList()
      次の結果セットから結果のリストを取得します。プロバイダーは、必要に応じてクエリに対して execute を呼び出します。REF_CURSOR 結果セット (存在する場合) は、REF_CURSOR パラメーターがクエリに登録された順序で取得されます。
      次で指定:
      インターフェース Query の getResultList 
      戻り値:
      結果のリストまたは null が次の項目である場合は結果セットではありません
      例外:
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • getSingleResult

      ObjectSE getSingleResult()
      次の結果セットから 1 つの結果を取得します。プロバイダーは、必要に応じてクエリに対して execute を呼び出します。REF_CURSOR 結果セット (存在する場合) は、REF_CURSOR パラメーターがクエリに登録された順序で取得されます。
      次で指定:
      インターフェース Query の getSingleResult 
      戻り値:
      結果、または次の項目が結果セットでない場合は null
      例外:
      NoResultException - 次の結果セットに結果がない場合
      NonUniqueResultException - 複数の結果の場合
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • getSingleResultOrNull

      ObjectSE getSingleResultOrNull()
      次の結果セットから 1 つの結果を取得します。プロバイダーは、必要に応じてクエリに対して execute を呼び出します。REF_CURSOR 結果セット (存在する場合) は、REF_CURSOR パラメーターがクエリに登録された順序で取得されます。
      次で指定:
      インターフェース Query の getSingleResultOrNull 
      戻り値:
      結果、または次の項目が結果セットでない場合、次の結果セットに結果がない場合は null
      例外:
      NonUniqueResultException - 複数の結果の場合
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • hasMoreResults

      boolean hasMoreResults()
      次の結果が結果セットに対応する場合は true を返し、更新カウントである場合、INOUT パラメーターと OUT パラメーターを介して以外に結果がない場合は false を返します。
      戻り値:
      次の結果が結果セットに対応する場合は true
      例外:
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合

    • getUpdateCount

      int getUpdateCount()
      更新カウントを返すか、保留中の結果がない場合、次の結果が更新カウントでない場合は -1 を返します。
      戻り値:
      更新カウントまたは保留中の結果がない場合、または次の結果が更新カウントでない場合は -1
      例外:
      QueryTimeoutException - クエリ実行が設定されたクエリタイムアウト値を超え、ステートメントのみがロールバックされる場合
      PersistenceException - クエリ実行が設定されたクエリタイムアウト値を超え、トランザクションがロールバックされた場合