モジュール java.xml
パッケージ javax.xml.xpath

インタフェースXPath

  • public interface XPath
    XPathはXPath評価環境および式へのアクセスを提供します。 XPath評価は、次の表に示す要因の影響を受けます。
    XPath式の評価
    要因 動作
    context コンテキストの型は実装依存です。 値がnullの場合、操作はコンテキストに依存しない必要があります。そうでない場合は、XPathExpressionExceptionがスローされます。 XPath式を評価するため、DocumentFragmentがドキュメント・ノードと同様に扱われる。
    変数 式に変数の参照が含まれる場合、setXPathVariableResolver(XPathVariableResolver resolver)で設定されたXPathVariableResolverによってその値が見つけられる。 変数リゾルバが定義されていないか、リゾルバから変数に対してnullが返された場合、XPathExpressionExceptionが生成される。 変数の値は、1回の評価の過程を通じて不変でなければならない。
    functions 式に関数の参照が含まれる場合、setXPathFunctionResolver(XPathFunctionResolver resolver)で設定されたXPathFunctionResolverによって関数が見つけられる。 関数リゾルバが定義されていないか、関数リゾルバから関数に対してnullが返された場合、XPathExpressionExceptionが生成される。
    QNames 式の中のQNameはsetNamespaceContext(NamespaceContext nsContext)で設定されたXPath名前空間コンテキストと照らして解決される。
    result 式の評価の結果は目的の戻り値の型のインスタンスに変換される。 有効な戻り値の型は、XPathConstantsに定義する。 戻り値の型への変換はXPath変換規則に従う。

    XPathオブジェクトはスレッドセーフではなく、再入不可能です。 つまり、アプリケーション側で、どのような場合でも1つのXPathオブジェクトが複数のスレッドから使用されることがないようにする必要があります。また、evaluateメソッドが呼び出されている間、アプリケーションは再帰的にevaluateメソッドを呼び出すことができません。

    導入されたバージョン:
    1.5
    関連項目:
    XML Path Language (XPath) Version 1.0

    • メソッドの詳細

      • reset

        void reset()
        このXPathを元の構成にリセットします。

        XPathは、XPathFactory.newXPath()で作成された時点の状態にリセットされます。reset()は、既存のXPathの再使用を許可するように設計されているため、新しいXPathの作成に関連するリソースを節約できます。

        XPathをリセットした場合、同じXPathFunctionResolver、XPathVariableResolverまたはNamespaceContext Object (たとえば、Object.equals(Object obj))を持つことは保証されません。 機能的に同じXPathFunctionResolver、XPathVariableResolverおよびNamespaceContextを持つことは保証されます。

      • setXPathVariableResolver

        void setXPathVariableResolver​(XPathVariableResolver resolver)
        変数リゾルバを設定します。

        resolverがnullの場合、NullPointerExceptionがスローされます。

        パラメータ:
        resolver - 変数リゾルバ。
        例外:
        NullPointerException - resolverがnullの場合。

      • getXPathVariableResolver

        XPathVariableResolver getXPathVariableResolver()
        現在の変数リゾルバを返します。

        有効な変数リゾルバがない場合、nullが返されます。

        戻り値:
        現在の変数リゾルバ。

      • setXPathFunctionResolver

        void setXPathFunctionResolver​(XPathFunctionResolver resolver)
        関数リゾルバを設定します。

        resolverがnullの場合、NullPointerExceptionがスローされます。

        パラメータ:
        resolver - XPath関数リゾルバ。
        例外:
        NullPointerException - resolverがnullの場合。

      • getXPathFunctionResolver

        XPathFunctionResolver getXPathFunctionResolver()
        現在の関数リゾルバを返します。

        有効な関数リゾルバがない場合、nullが返されます。

        戻り値:
        現在の関数リゾルバ。

      • setNamespaceContext

        void setNamespaceContext​(NamespaceContext nsContext)
        名前空間コンテキストを設定します。

        nsContextがnullの場合、NullPointerExceptionがスローされます。

        パラメータ:
        nsContext - 使用する名前空間コンテキスト。
        例外:
        NullPointerException - nsContextがnullの場合。

      • getNamespaceContext

        NamespaceContext getNamespaceContext()
        現在の名前空間コンテキストを返します。

        有効な名前空間コンテキストがない場合、nullが返されます。

        戻り値:
        現在の名前空間コンテキスト。

      • evaluate

        Object evaluate​(String expression,
                Object item,
                QName returnType)
         throws XPathExpressionException
        指定されたコンテキストでXPath式を評価し、結果を指定された型として返します。

        コンテキスト項目の評価、変数、関数、およびQNameの解決と戻り値の型の変換については「XPath式の評価」を参照してください。

        パラメータitemは、XPath式が操作されるコンテキストを表します。 コンテキストの型は実装依存です。 値がnullの場合、操作はコンテキストに依存しない必要があります。そうしないと、XPathExpressionExceptionがスローされます。

        実装上のノート:
        コンテキストの型は通常Nodeです。
        パラメータ:
        expression - XPath式。
        item - XPath式が評価されるコンテキスト。
        returnType - 結果の型は、XPath式によって返されると予想されます。
        戻り値:
        XPath式をreturnTypeのObjectとして評価した結果。
        例外:
        XPathExpressionException - expressionを評価できない場合。
        IllegalArgumentException - returnTypeがXPathConstants (NUMBER、STRING、BOOLEAN、NODEまたはNODESET)で定義されているタイプの1つでない場合。
        NullPointerException - expressionまたはreturnTypeがnullの場合。

      • evaluate

        String evaluate​(String expression,
                Object item)
         throws XPathExpressionException
        指定されたコンテキストでXPath式を評価し、結果をStringとして返します。

        このメソッドは、XPathConstants.STRINGのreturnTypeを指定してevaluate(String expression, Object item, QName returnType)を呼び出します。

        コンテキスト項目の評価、変数、関数、およびQNameの解決と戻り値の型の変換については「XPath式の評価」を参照してください。

        パラメータitemは、XPath式が操作されるコンテキストを表します。 コンテキストの型は実装依存です。 値がnullの場合、操作はコンテキストに依存しない必要があります。そうしないと、XPathExpressionExceptionがスローされます。

        実装上のノート:
        コンテキストの型は通常Nodeです。
        パラメータ:
        expression - XPath式。
        item - XPath式が評価されるコンテキスト。
        戻り値:
        XPath式をStringとして評価した結果。
        例外:
        XPathExpressionException - expressionを評価できない場合。
        NullPointerException - expressionがnullの場合。

      • evaluate

        Object evaluate​(String expression,
                InputSource source,
                QName returnType)
         throws XPathExpressionException
        指定されたInputSourceのコンテキストでXPath式を評価し、結果を指定された型として返します。

        このメソッドはInputSourceのデータ・モデルを構築し、結果として得られるドキュメント・オブジェクトに対してevaluate(String expression, Object item, QName returnType)を呼び出します。

        コンテキスト項目の評価、変数、関数、およびQNameの解決と戻り値の型の変換については「XPath式の評価」を参照してください。

        パラメータ:
        expression - XPath式。
        source - 評価するドキュメントの入力ソース。
        returnType - 目的の戻り値の型。
        戻り値:
        式の評価の結果をカプセル化するObject。
        例外:
        XPathExpressionException - expressionを評価できない場合。
        IllegalArgumentException - returnTypeがXPathConstantsに定義された型でない場合。
        NullPointerException - expression、source、またはreturnTypeがnullの場合。

      • evaluateExpression

        default <T> T evaluateExpression​(String expression,
                                 Object item,
                                 Class<T> type)
                          throws XPathExpressionException
        指定されたコンテキストでXPath式を評価し、結果をclass typeで指定された型で返します

        パラメータitemは、XPath式が操作されるコンテキストを表します。 コンテキストの型は実装依存です。 値がnullの場合、操作はコンテキストに依存しない必要があります。そうしないと、XPathExpressionExceptionがスローされます。

        実装要件:
        XPath APIのデフォルトの実装は、次のものと同等です: 
         
     (T)evaluate(expression, item,
           XPathEvaluationResult.XPathResultType.getQNameType(type));
        evaluateメソッドはANY型をサポートしていないため、XPathEvaluationResultを型として指定するとIllegalArgumentExceptionが発生します。 ANY型をサポートする実装では、このメソッドをオーバーライドする必要があります。
        実装上のノート:
        コンテキストの型は通常Nodeです。
        型パラメータ:
        T - XPath式によって返されるクラスの型。
        パラメータ:
        expression - XPath式。
        item - XPath式が評価されるコンテキスト。
        type - XPath式によって返されると予想されるクラスの型。
        戻り値:
        式を評価した結果。
        例外:
        XPathExpressionException - 式を評価できない場合。
        IllegalArgumentException - typeがXPathEvaluationResult.XPathResultTypeで定義された型に対応する型でないか、型としてXPathEvaluationResultが指定されていますが、ANY型をサポートする実装は使用できません。
        NullPointerException - expression or typeがnullの場合。
        導入されたバージョン:
        9

      • evaluateExpression

        default XPathEvaluationResult<?> evaluateExpression​(String expression,
                                                    Object item)
                                             throws XPathExpressionException
        指定したコンテキストでXPath式を評価します。 これは、型XPathEvaluationResultのevaluateExpression(String expression, Object item, Class type)を呼び出すのと同じです: 
         
     evaluateExpression(expression, item, XPathEvaluationResult.class);

        パラメータitemは、XPath式が操作されるコンテキストを表します。 コンテキストの型は実装依存です。 値がnullの場合、操作はコンテキストに依存しない必要があります。そうしないと、XPathExpressionExceptionがスローされます。

        実装要件:
        XPath APIのデフォルトの実装は、次のものと同等です: 
         
     evaluateExpression(expression, item, XPathEvaluationResult.class);
        evaluateメソッドはANY型をサポートしていないため、このメソッドのデフォルト実装では常にIllegalArgumentExceptionがスローされます。 したがって、ANY型をサポートする実装は、このメソッドをオーバーライドする必要があります。
        実装上のノート:
        コンテキストの型は通常Nodeです。
        パラメータ:
        expression - XPath式。
        item - XPath式が評価されるコンテキスト。
        戻り値:
        式を評価した結果。
        例外:
        XPathExpressionException - 式を評価できない場合。
        IllegalArgumentException - このメソッドの実装がANY型をサポートしていない場合。
        NullPointerException - expressionがnullの場合。
        導入されたバージョン:
        9

      • evaluateExpression

        default <T> T evaluateExpression​(String expression,
                                 InputSource source,
                                 Class<T> type)
                          throws XPathExpressionException
        指定されたsourceのコンテキストでXPath式を評価し、指定されたとおりに結果を返します。

        このメソッドは、InputSourceのデータ・モデルを構築し、結果のドキュメント・オブジェクトに対してevaluateExpression(String expression, Object item, Class type)を呼び出します。 データ・モデルは通常Documentです

        実装要件:
        XPath APIのデフォルトの実装は、次のものと同等です: 
         
           (T)evaluate(expression, source,
                XPathEvaluationResult.XPathResultType.getQNameType(type));
        evaluateメソッドはANY型をサポートしていないため、XPathEvaluationResultを型として指定するとIllegalArgumentExceptionが発生します。 ANY型をサポートする実装では、このメソッドをオーバーライドする必要があります。
        型パラメータ:
        T - XPath式によって返されるクラスの型。
        パラメータ:
        expression - XPath式。
        source - 評価するドキュメントの入力ソース。
        type - XPath式によって返されると予想されるクラスの型。
        戻り値:
        式を評価した結果。
        例外:
        XPathExpressionException - 式を評価できない場合。
        IllegalArgumentException - typeがXPathResultTypeで定義された型に対応する型でないか、型としてXPathEvaluationResultが指定されていますが、ANY型をサポートする実装は使用できません。
        NullPointerException - expression, source or typeがnullの場合。
        導入されたバージョン:
        9

      • evaluateExpression

        default XPathEvaluationResult<?> evaluateExpression​(String expression,
                                                    InputSource source)
                                             throws XPathExpressionException
        指定したコンテキストでXPath式を評価します。 これは、型XPathEvaluationResultのevaluateExpression(String expression, Object item, Class type)を呼び出すのと同じです: 
         
     evaluateExpression(expression, item, XPathEvaluationResult.class);
        実装要件:
        XPath APIのデフォルトの実装は、次のものと同等です: 
         
     evaluateExpression(expression, source, XPathEvaluationResult.class);
        evaluateメソッドはANY型をサポートしていないため、このメソッドのデフォルト実装では常にIllegalArgumentExceptionがスローされます。 したがって、ANY型をサポートする実装は、このメソッドをオーバーライドする必要があります。
        パラメータ:
        expression - XPath式。
        source - 評価するドキュメントの入力ソース。
        戻り値:
        式を評価した結果。
        例外:
        XPathExpressionException - 式を評価できない場合。
        IllegalArgumentException - このメソッドの実装がANY型をサポートしていない場合。
        NullPointerException - expressionまたはsourceがnullの場合。
        導入されたバージョン:
        9