パッケージ jakarta.persistence

インターフェース StoredProcedureQuery

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

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

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

    • メソッドの詳細

      • 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

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

      • setParameter

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

      • setParameter

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

      • setParameter

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

      • setParameter

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

      • setParameter

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

      • setParameter

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

      • setParameter

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

      • setFlushMode

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

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

      • hasMoreResults

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

      • getUpdateCount

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