JsonParser (Jakarta EE 8 Specification API)

すべてのスーパーインターフェース:
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

ネストされたクラスの要約
ネストされたクラス
修飾子と型インターフェースと説明
static class JsonParser.Event
JsonParser からのイベント。

ネストされたクラス
修飾子と型	インターフェースと説明
`static class`	`JsonParser.Event` `JsonParser` からのイベント。

メソッドのサマリー

すべてのメソッドインスタンスメソッド抽象メソッドデフォルトメソッド
修飾子と型	メソッドと説明
`void`	`close()` このパーサーを閉じ、パーサーに関連付けられているすべてのリソースを解放します。
`default JsonArray`	`getArray()` `JsonArray` を返し、対応する `END_ARRAY` にパーサーを進めます。
`default StreamSE<JsonValue>`	`getArrayStream()` `JsonArray` 要素のストリームを返します。
`BigDecimalSE`	`getBigDecimal()` JSON 番号を `BigDecimal` として返します。
`int`	`getInt()` JSON 番号を整数として返します。
`JsonLocation`	`getLocation()` JSON 入力ソース内のパーサーの現在の状態に対応する場所を返します。
`long`	`getLong()` JSON 番号を long として返します。
`default JsonObject`	`getObject()` `JsonObject` を返し、パーサーを対応する `END_OBJECT` に進めます。
`default StreamSE<Map.EntrySE<StringSE, JsonValue>>`	`getObjectStream()` `JsonObject` の名前と値のペアのストリームを返します。
`StringSE`	`getString()` 文字列値または数値の場合、名前 / 値ペアの名前の `String` を返します。
`default JsonValue`	`getValue()` 現在のパーサーの位置にある `JsonValue` を返します。
`default StreamSE<JsonValue>`	`getValueStream()` JSON 値のシーケンスから `JsonValue` のストリームを返します。
`boolean`	`hasNext()` さらに解析状態がある場合は、`true` を返します。
`boolean`	`isIntegralNumber()` 現在のパーサー状態の JSON 番号が整数である場合、true を返します。
`JsonParser.Event`	`next()` 次の解析状態のイベントを返します。
`default void`	`skipArray()` パーサーを `END_ARRAY` に進めます。
`default void`	`skipObject()` パーサーを `END_OBJECT` に進めます。

- メソッドの詳細
  - 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 - 解析状態がなくなった場合。
  - getString
```
StringSE getString()
```
    文字列値または数値の場合、名前 / 値ペアの名前の String を返します。このメソッドは、パーサーの状態が JsonParser.Event.KEY_NAME、JsonParser.Event.VALUE_STRING、JsonParser.Event.VALUE_NUMBER の場合にのみ呼び出す必要があります。
    戻り値:
    パーサーの状態が JsonParser.Event.KEY_NAME である場合の名前パーサーの状態が JsonParser.Event.VALUE_STRING である場合の文字列値パーサーの状態が JsonParser.Event.VALUE_NUMBER である場合の数値
    例外:
    IllegalStateExceptionSE - パーサーの状態が KEY_NAME、VALUE_STRING、VALUE_NUMBER でない場合
  - 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()SE
  - getLong
```
long getLong()
```
    JSON 番号を long として返します。戻り値は new BigDecimal(getString()).longValue() と同じです。この変換では、数値の全体的な大きさと精度に関する情報が失われ、反対の符号で結果が返される可能性があることに注意してください。このメソッドは、パーサーの状態が JsonParser.Event.VALUE_NUMBER の場合にのみ呼び出されます。
    戻り値:
    JSON 番号の long
    例外:
    IllegalStateExceptionSE - パーサーの状態が VALUE_NUMBER ではない場合
    関連事項:
    BigDecimal.longValue()SE
  - 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
    例外:
    IllegalStateExceptionSE - パーサーの状態が START_OBJECT ではない場合
    導入:
    1.1
  - getValue
```
default JsonValue getValue()
```
    現在のパーサーの位置にある JsonValue を返します。パーサーの状態が START_ARRAY の場合、動作は getArray() と同じです。パーサーの状態が START_OBJECT の場合、動作は getObject() と同じです。他のすべてのケースでは、該当する場合、JSON 値が読み取られて返されます。
    戻り値:
    現在のパーサーの位置にある JsonValue
    例外:
    IllegalStateExceptionSE - パーサーの状態が END_OBJECT または END_ARRAY の場合
    導入:
    1.1
  - getArray
```
default JsonArray getArray()
```
    JsonArray を返し、対応する END_ARRAY にパーサーを進めます。
    戻り値:
    現在のパーサーの位置にある JsonArray
    例外:
    IllegalStateExceptionSE - パーサーの状態が START_ARRAY ではない場合
    導入:
    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 の closeSE
    次で指定:
    インターフェース CloseableSE の closeSE
    例外:
    JsonException - I/O エラーが発生した場合 (IOException は JsonException の原因となる)

インターフェース JsonParser

ネストされたクラスの要約

メソッドのサマリー

メソッドの詳細

hasNext

next

getString

isIntegralNumber

getInt

getLong

getBigDecimal

getLocation

getObject

getValue

getArray

getArrayStream

getObjectStream

getValueStream

skipArray

skipObject

close