パッケージ jakarta.json.stream

インターフェース JsonParser

  • すべてのスーパーインターフェース:
    AutoCloseableSE, CloseableSE
    public interface JsonParser
extends CloseableSE
    ストリーミング方式で JSON データへの前方読み取り専用アクセスを提供します。これは、JSON データを読み取る最も効率的な方法です。これは、大きすぎてメモリにロードできない JSON データを解析および処理する唯一の方法です。

    クラス Json には、入力ソース（InputStreamSE および ReaderSE）からパーサーを作成するためのメソッドが含まれています。

    次の例は、空の JSON 配列を含む文字列からパーサーを作成する方法を示しています。

     
 JsonParser parser = Json.createParser(new StringReader("[]"));

    クラス JsonParserFactory には、JsonParser インスタンスを作成するためのメソッドも含まれています。複数のパーサーインスタンスを作成する場合は、JsonParserFactory が推奨されます。次の例に使用例を示します。

     
 JsonParserFactory factory = Json.createParserFactory();
 JsonParser parser1 = factory.createParser(...);
 JsonParser parser2 = factory.createParser(...);

    JsonParser は、プル解析プログラミングモデルを使用して JSON を解析します。このモデルでは、クライアントコードがスレッドを制御し、メソッド next() を呼び出して、各要素の処理後にパーサーを次の状態に進めます。パーサーは次のイベントを生成できます: START_OBJECT、END_OBJECT、START_ARRAY、END_ARRAY、KEY_NAME、VALUE_STRING、VALUE_NUMBER、VALUE_TRUE、VALUE_FALSE、VALUE_NULL。

    たとえば、空の JSON オブジェクト（{}）の場合、パーサーはメソッド next() への最初の呼び出しでイベント START_OBJECT を生成し、メソッド next() への 2 番目の呼び出しでイベント END_OBJECT を生成します。次のコードは、これらのイベントにアクセスする方法を示しています。

     
 Event event = parser.next(); // START_OBJECT
 event = parser.next();       // END_OBJECT

    たとえば、次の JSON の場合:

     {
   "firstName": "John", "lastName": "Smith", "age": 25,
   "phoneNumber": [
       { "type": "home", "number": "212 555-1234" },
       { "type": "fax", "number": "646 555-4567" }
    ]
 }

    メソッド next() を呼び出すと、以下の指定された場所（太字でマークされている）で解析イベントが発生します。

     {START_OBJECT
   "firstName"KEY_NAME: "John"VALUE_STRING, "lastName"KEY_NAME: "Smith"VALUE_STRING, "age"KEY_NAME: 25VALUE_NUMBER,
   "phoneNumber"KEY_NAME : [START_ARRAY
       {START_OBJECT "type"KEY_NAME: "home"VALUE_STRING, "number"KEY_NAME: "212 555-1234"VALUE_STRING }END_OBJECT,
       {START_OBJECT "type"KEY_NAME: "fax"VALUE_STRING, "number"KEY_NAME: "646 555-4567"VALUE_STRING }END_OBJECT
    ]END_ARRAY
 }END_OBJECT
    メソッド next() および hasNext() を使用すると、パーサーイベントを反復して JSON データを処理できます。JsonParser は、パーサーの現在の状態で値を取得する get メソッドを提供します。例: 次のコードは、上記の JSON から値 "John" を取得する方法を示しています。
     
 Event event = parser.next(); // START_OBJECT
 event = parser.next();       // KEY_NAME
 event = parser.next();       // VALUE_STRING
 parser.getString();          // "John"
    バージョン 1.1 以降では、現在のパーサー位置で、ストリームから部分的な JSON オブジェクトモデルを構築できます。メソッド getArray() および getObject() を使用すると、JsonArray または JsonObject を読み込むことができます。例: 次のコードは、上記の JSON から JsonArray の phoneNumber を取得する方法を示しています。
    
 while (parser.hasNext() {
     Event event = parser.next();
     if (event == JsonParser.Event.KEY_NAME ) {
         String key = getString();
         event = parser.next();
         if (key.equals("phoneNumber") {
             JsonArray phones = parser.getArray();
         }
     }
 }
    getArrayStream() および getObjectStream() メソッドは、JsonArray または JsonObject の要素のストリームを取得するために使用できます。例: 次のコードは、JsonArray で John の phoneNumber を取得する別の方法を示しています。
    
 Event event = parser.next(); // START_OBJECT
 JsonArray phones = (JsonArray)
     parser.getObjectStream().filter(e->e.getKey().equals("phoneNumber"))
                             .map(e->e.getValue())
                             .findFirst()
                             .get();
    メソッド skipArray() および skipObject() を使用して、トークンをスキップし、パーサーを END_ARRAY または END_OBJECT に配置できます。

    JsonParser は、JSON 配列に含まれていない一連の JSON 値を解析するために使用できます。{} {}。次のコードは、そのようなシーケンスを解析する方法を示しています。

    
 JsonParser parser = Json.createParser(...);
 while (parser.hasNext) {
     parser.next(); // advance parser state
     JsonValue value = parser.getValue();
 }
    関連事項:
    Json, JsonParserFactory

    • メソッドの詳細

      • hasNext

        boolean hasNext()
        さらに解析状態がある場合は、true を返します。このメソッドは、パーサーが JSON テキストの最後に到達した場合に false を返します。
        戻り値:
        true : 解析状態がさらにある場合。
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)
        JsonParsingException - パーサーが次の状態に進むときに無効な JSON を検出した場合。

      • next

        JsonParser.Event next()
        次の解析状態のイベントを返します。
        戻り値:
        次の解析状態のイベント
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)
        JsonParsingException - パーサーが次の状態に進むときに無効な JSON を検出した場合。
        NoSuchElementExceptionSE - 解析状態がなくなった場合。

      • currentEvent

        default JsonParser.Event currentEvent()
        現在の解析状態のイベントを返します。
        戻り値:
        現在の解析状態のイベント
        導入:
        2.1

      • isIntegralNumber

        boolean isIntegralNumber()
        現在のパーサー状態の JSON 番号が整数である場合、true を返します。BigDecimalSE を使用して値を内部的に格納することができ、このメソッドのセマンティクスは scale() を使用して定義されます。スケールがゼロの場合、整数型と見なされます。次の例のように、この整数型情報を使用して、適切なアクセサーメソッドを呼び出して数値を取得できます。
         
 JsonParser parser = ...
 if (parser.isIntegralNumber()) {
     parser.getInt();     // or other methods to get integral value
 } else {
     parser.getBigDecimal();
 }
        戻り値:
        この数値が整数の場合は true、それ以外の場合は false
        例外:
        IllegalStateExceptionSE - パーサーの状態が VALUE_NUMBER ではない場合

      • getInt

        int getInt()
        JSON 番号を整数として返します。戻り値は new BigDecimal(getString()).intValue() と同じです。この変換では、数値の全体的な大きさと精度に関する情報が失われ、反対の符号で結果が返される可能性があることに注意してください。このメソッドは、パーサーの状態が JsonParser.Event.VALUE_NUMBER の場合にのみ呼び出す必要があります。
        戻り値:
        JSON 番号の整数
        例外:
        IllegalStateExceptionSE - パーサーの状態が VALUE_NUMBER ではない場合
        関連事項:
        BigDecimal.intValue()

      • getLong

        long getLong()
        JSON 番号を long として返します。戻り値は new BigDecimal(getString()).longValue() と同じです。この変換では、数値の全体的な大きさと精度に関する情報が失われ、反対の符号で結果が返される可能性があることに注意してください。このメソッドは、パーサーの状態が JsonParser.Event.VALUE_NUMBER の場合にのみ呼び出されます。
        戻り値:
        JSON 番号の long
        例外:
        IllegalStateExceptionSE - パーサーの状態が VALUE_NUMBER ではない場合
        関連事項:
        BigDecimal.longValue()

      • getBigDecimal

        BigDecimalSE getBigDecimal()
        JSON 番号を BigDecimal として返します。BigDecimal は new BigDecimal(getString()) を使用して作成されます。このメソッドは、パーサーの状態が JsonParser.Event.VALUE_NUMBER の場合にのみ呼び出す必要があります。
        戻り値:
        JSON 番号の BigDecimal 
        例外:
        IllegalStateExceptionSE - パーサーの状態が VALUE_NUMBER ではない場合

      • getLocation

        JsonLocation getLocation()
        JSON 入力ソース内のパーサーの現在の状態に対応する場所を返します。ロケーション情報は、現在のパーサー状態（またはパーサーが次の状態に進むまで）でのみ有効です。
        戻り値:
        JSON 入力ソースの現在のパーサーの状態に対応する null 以外の場所

      • getObject

        default JsonObject getObject()
        JsonObject を返し、パーサーを対応する END_OBJECT に進めます。
        戻り値:
        現在のパーサーの位置にある JsonObject 
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)
        IllegalStateExceptionSE - パーサーの状態が START_OBJECT ではない場合
        JsonParsingException - パーサーが次の状態に進むときに無効な JSON を検出した場合。
        NoSuchElementExceptionSE - 解析状態がなくなった場合。
        導入:
        1.1

      • getValue

        default JsonValue getValue()
        現在のパーサーの位置にある JsonValue を返します。パーサーの状態が START_ARRAY の場合、動作は getArray() と同じです。パーサーの状態が START_OBJECT の場合、動作は getObject() と同じです。他のすべてのケースでは、該当する場合、JSON 値が読み取られて返されます。
        戻り値:
        現在のパーサーの位置にある JsonValue 
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)
        IllegalStateExceptionSE - パーサーの状態が END_OBJECT または END_ARRAY の場合
        JsonParsingException - パーサーが次の状態に進むときに無効な JSON を検出した場合。
        NoSuchElementExceptionSE - 解析状態がなくなった場合。
        導入:
        1.1

      • getArray

        default JsonArray getArray()
        JsonArray を返し、対応する END_ARRAY にパーサーを進めます。
        戻り値:
        現在のパーサーの位置にある JsonArray 
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)
        IllegalStateExceptionSE - パーサーの状態が START_ARRAY ではない場合
        JsonParsingException - パーサーが次の状態に進むときに無効な JSON を検出した場合。
        NoSuchElementExceptionSE - 解析状態がなくなった場合。
        導入:
        1.1

      • getArrayStream

        default StreamSE<JsonValue> getArrayStream()
        JsonArray 要素のストリームを返します。パーサーの状態は START_ARRAY でなければなりません。要素は、ストリーム操作の必要に応じて、必要に応じて遅延して読み取られます。ストリーム操作がすべての配列要素を消費しない場合、skipArray() を使用して未処理の配列要素をスキップできます。
        戻り値:
        JsonArray の要素のストリーム
        例外:
        IllegalStateExceptionSE - パーサーの状態が START_ARRAY ではない場合
        導入:
        1.1

      • getObjectStream

        default StreamSE<Map.EntrySE<StringSE,​JsonValue>> getObjectStream()
        JsonObject の名前と値のペアのストリームを返します。パーサーの状態は START_OBJECT でなければなりません。名前と値のペアは、ストリーム操作の必要に応じて、必要に応じて遅延して読み取られます。ストリーム操作がオブジェクトの名前と値のペアのすべてを消費しない場合、skipObject() を使用して未処理の要素をスキップできます。
        戻り値:
        JsonObject の名前 / 値ペアのストリーム
        例外:
        IllegalStateExceptionSE - パーサーの状態が START_OBJECT ではない場合
        導入:
        1.1

      • getValueStream

        default StreamSE<JsonValue> getValueStream()
        JSON 値のシーケンスから JsonValue のストリームを返します。値は、ストリーム操作の必要に応じて、必要に応じて遅延して読み取られます。
        戻り値:
        JsonValue のストリーム
        例外:
        IllegalStateExceptionSE - パーサーが配列またはオブジェクト内にある場合。
        導入:
        1.1

      • skipArray

        default void skipArray()
        パーサーを END_ARRAY に進めます。パーサーが配列コンテキストにある場合、つまり、対応する END_ARRAY に遭遇することなく START_ARRAY に以前に遭遇した場合、パーサーは対応する END_ARRAY に進みます。パーサーが配列コンテキストにない場合、何も起こりません。
        導入:
        1.1

      • skipObject

        default void skipObject()
        パーサーを END_OBJECT に進めます。パーサーがオブジェクトコンテキスト内にある場合、つまり、対応する END_OBJECT に遭遇することなく START_OBJECT に以前に遭遇した場合、パーサーは対応する END_OBJECT に進みます。パーサーがオブジェクトコンテキストにない場合、何も起こりません。
        導入:
        1.1

      • close

        void close()
        このパーサーを閉じ、パーサーに関連付けられているすべてのリソースを解放します。このメソッドは、基になる入力ソースを閉じます。
        次で指定:
        インターフェース AutoCloseableSE 内の close 
        次で指定:
        インターフェース CloseableSE 内の close 
        例外:
        JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)