Overview
このガイドでは、MongoDB Java ドライバーで拡張 JSON 形式を使用する方法を学習できます。
JSON は、オブジェクト、配列、数値、string、ブール値、null の値を表すデータ形式です。 拡張 JSON形式では、BSON の各型に直接対応するフィールド型情報を表すために「 $ 」というプレフィックスが付いたキーの予約セットが定義されます。BSON は MongoDB がデータを保存するために使用する形式です。
このガイドでは、次のトピックについて説明します。
さまざまな MongoDB 拡張 JSON 形式
BSON ライブラリを使用して拡張 JSON と Java オブジェクトを変換する方法
BSON types のカスタム変換の作成方法
これらの形式の違いの詳細については、 JSON と BSON に関する記事を参照してください。
拡張 JSON 形式
MongoDB 拡張 JSON は、BSON データを表すためのさまざまな string 形式を機能します。 異なる形式はそれぞれ JSON RFC に準拠し、特定のユースケースを満たしています。 拡張形式は標準形式とも呼ばれますが、情報を失うことなく双方向変換を行うためにすべての BSON 型に特定の表現を備えています。 緩和モード形式は、より簡潔で通常の JSON に近いものですが、数値フィールドの特定のバイトサイズなどのすべての型情報を表すものではありません。
各形式の説明については、次の表を参照してください。
名前 | 説明 |
|---|---|
拡張 | 標準形式とも呼ばれるこの JSON 表示では、BSON 型情報の損失が避けられます。 |
緩和モード | 何らかのタイプ情報が失われたBSONドキュメントを記述するJSON表現。 |
Shell | MongoDB shell で使用される構文に一致する JSON 表示。 |
厳密 | 非推奨。この表現は、JSON RFCに完全に準拠したレガシー形式であり、すべての JSON パーサーで型情報を読み取ることができます。 |
注意
ドライバーは、$uuid拡張JSONタイプを string からバイナリ サブタイプ 4 の BsonBinaryオブジェクトに解析します。$uuidフィールド解析の詳細については、拡張JSON仕様の $uuid フィールドを解析するための特別なルール セクションを参照してください。
これらの形式の詳細については、次のリソースを参照してください。
JSON RFC 公式ドキュメント
MongoDB 拡張 JSON Server マニュアル エントリ
BsonBinary APIドキュメント
拡張JSON仕様 Githubドキュメント
拡張 JSON の例
次の例は、それぞれの拡張 JSON 形式で表される ObjectId、date、long 数値フィールドを含むドキュメントを示しています。 表示する例の形式に対応するタブをクリックします。
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": { "$numberLong": "1601499609" }}, "numViews": { "$numberLong": "36520312" } }
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": "2020-09-30T18:22:51.648Z" }, "numViews": 36520312 }
{ "_id": ObjectId("573a1391f29313caabcd9637"), "createdAt": ISODate("2020-09-30T18:22:51.648Z"), "numViews": NumberLong("36520312") }
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": 1601499609 }, "numViews": { "$numberLong": "36520312" } }
拡張 JSON の読み取り
ドキュメント クラスの使用
必要なオブジェクトタイプに応じて、 クラスまたは クラスから 静的メソッドを呼び出すと、拡張 JSON string を Java ドキュメント オブジェクトに読み込むことができます。parse()DocumentBsonDocumentこのメソッドは、いずれかの形式の拡張 JSON string を解析し、データを含むそのクラスのインスタンスを返します。
次の例は、 Documentクラスを使用してサンプルの拡張 JSON string をparse() Documentオブジェクトに読み込む方法を示しています。
String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," + "\"myNumber\": {\"$numberLong\": \"4794261\" }}}"; Document doc = Document.parse(ejsonStr); System.out.println(doc);
Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}
詳細については、ドキュメント の「基礎」ページを参照してください。
BSON ライブラリの使用
また、 JsonReaderクラスを使用すると、MongoDB Java ドライバーのドキュメント クラスを使用せずに、拡張 JSON string を Java オブジェクトに読み込むことができます。 このクラスには、拡張 JSON string の任意の形式のフィールドと値を順番に解析し、それらを Java オブジェクトとして返すメソッドが含まれています。 ドライバーのドキュメント クラスは、拡張 JSON を解析するためにこのクラスも使用します。
次のコード例は、 JsonReaderクラスを使用して拡張 JSON string を Java オブジェクトに変換する方法を示しています。
String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," + "\"myNumber\": {\"$numberLong\": \"4794261\" }}}"; JsonReader jsonReader = new JsonReader(ejsonStr); jsonReader.readStartDocument(); jsonReader.readName("_id"); ObjectId id = jsonReader.readObjectId(); jsonReader.readName("myNumber"); Long myNumber = jsonReader.readInt64(); jsonReader.readEndDocument(); System.out.println(id + " is type: " + id.getClass().getName()); System.out.println(myNumber + " is type: " + myNumber.getClass().getName()); jsonReader.close();
507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId 4794261 is type: java.lang.Long
詳細については、JsonReader APIドキュメント を参照してください。
拡張 JSON の書込み (write)
ドキュメント クラスの使用
拡張 JSON 文字列は、 toJson()メソッドを呼び出し、オプションでJsonWriterSettingsのインスタンスを渡して拡張 JSON 形式を指定することで、 DocumentまたはBsonDocumentのインスタンスから拡張 JSON string を作成できます。
この例では、拡張 JSON を Relaxed モード形式で出力します。
Document myDoc = new Document(); myDoc.append("_id", new ObjectId("507f1f77bcf86cd799439012")).append("myNumber", 11223344); JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED).build(); System.out.println(doc.toJson(settings));
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": 11223344}
BSON ライブラリの使用
JsonWriterクラスの BSON ライブラリを使用して、Java オブジェクト内のデータから拡張 JSON string を出力することもできます。 JsonWriterのインスタンスを構築するには、Java Writerのサブクラスを渡して、拡張 JSON の出力方法を指定します。 オプションで、 JsonWriterSettingsインスタンスを渡して、拡張 JSON 形式などのオプションを指定できます。 デフォルトでは、 JsonWriterは 緩和 モード形式を使用します。 MongoDB Java ドライバーのドキュメント クラスも、このクラスを使用して BSON を拡張 JSON に変換します。
次のコード例は、 JsonWriterを使用して拡張 JSON string を作成し、それをSystem.outに出力する方法を示しています。 outputMode()ビルダ メソッドにJsonMode.EXTENDED定数を渡して形式を指定します。
JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build(); try (JsonWriter jsonWriter = new JsonWriter(new BufferedWriter(new OutputStreamWriter(System.out)), settings)) { jsonWriter.writeStartDocument(); jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012")); jsonWriter.writeInt64("myNumber", 11223344); jsonWriter.writeEndDocument(); jsonWriter.flush(); }
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}
このセクションで説明されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。
カスタム BSON 型変換
JSON 出力の形式を設定するには を指定するだけでなく、 に フィルターoutputMode()JsonWriterSettings.Builder を追加して出力をさらにカスタマイズできます。これらの変換メソッドは Java 型を検出し、それに渡されたConverterによって定義されたロジックを実行します。
次のサンプル コードは、緩和モードの 出力を簡素化するために、LambdaJSON 式として定義される変換子を追加する方法を示しています。
JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED) .objectIdConverter((value, writer) -> writer.writeString(value.toHexString())) .dateTimeConverter( (value, writer) -> { ZonedDateTime zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC); writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime)); }) .build(); Document doc = new Document() .append("_id", new ObjectId("507f1f77bcf86cd799439012")) .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L))) .append("myNumber", 4794261); System.out.println(doc.toJson(settings)));
このコードの出力は、次のテキストのようになります。
{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}
変換ツールを指定しない場合、緩和モードの JSON 出力は次のテキストのようになります。
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}
このセクションで説明されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。