문서 데이터 형식: 확장 JSON

이 페이지의 내용

개요

확장 JSON 형식
확장 JSON 예시
확장 JSON 읽기
문서 클래스 사용
BSON 라이브러리 사용
확장 JSON 쓰기
문서 클래스 사용
BSON 라이브러리 사용
사용자 지정 BSON 유형 변환

개요

이 가이드에서는 MongoDB Java 드라이버에서 확장 JSON 형식을 사용하는 방법을 배울 수 있습니다.

JSON은 객체, 배열, 숫자, 문자열, 부울 및 null 값을 나타내는 데이터 형식입니다. 확장 JSON 형식은 '$' 접두사가 붙은 예약된 키 집합을 정의하여 MongoDB가 데이터를 저장하는 데 사용하는 형식인 BSON의 각 유형에 직접적으로 대응하는 필드 유형 정보를 표현합니다.

이 가이드에서는 다음 주제에 대해 설명합니다.

다양한 MongoDB 확장 JSON 형식
BSON 라이브러리를 사용하여 확장 JSON과 Java 객체 간에 변환하는 방법
BSON 유형의 사용자 지정 변환을 만드는 방법

이러한 형식의 차이점에 대한 자세한 내용은JSON 및 BSON에대한 문서를 참조하세요.

확장 JSON 형식

MongoDB 확장 JSON은 BSON 데이터를 표현하는 다양한 문자열 형식을 제공합니다. 각기 다른 형식은 JSON RFC를 준수하며 특정 사용 사례를 충족합니다. 표준(canonical) 형식이라고도 하는 확장(extended) 형식은 정보 손실 없는 양방향 변환을 위해 모든 BSON 유형에 대해 특정 표현을 제공합니다. 릴렉스(Relaxed) 모드 형식은 더 간결하고 일반 JSON에 가깝지만 숫자 필드의 특정 바이트 크기 등 모든 유형 정보를 나타내지는 않습니다.

각 형식에 대한 설명을 보려면 다음 표를 참조하세요.

이름	설명
확장	Also known as the canonical format, this JSON representation avoids loss of BSON type information. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats.
완화 모드	JSON representation that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of certain type information.
Shell	JSON representation that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell which often uses JavaScript functions to represent types.
엄격한	Deprecated. This representation is the legacy format that fully conforms to the JSON RFC which allows any JSON parser to read the type information. The legacy API uses this format.

참고

드라이버는 $uuid 에서 확장 JSON 유형을 바이너리 string BsonBinary 하위 유형 의 4 객체로 구문 분석합니다. $uuid 필드 구문 분석에 대한 자세한 내용은 $uuid 필드 구문 분석을 위한 특별 규칙을 JSON 참조하세요. 섹션을 참조 .

이러한 형식에 대한 자세한 내용은 다음 리소스를 참조하세요.

JSON RFC 공식 설명서
MongoDB 확장 JSON 서버 수동 입력
BsonBinary API 문서
확장 JSON 사양 GitHub 설명서

확장 JSON 예시

다음 예시에서는 각 확장 JSON 형식으로 표시되는 ObjectId, 날짜, 긴 숫자 필드가 포함된 문서를 보여 줍니다. 원하는 형식의 예시 탭을 클릭합니다.

{
  "_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 읽기

문서 클래스 사용

필요한 객체 유형에 따라 Document 또는 BsonDocument 클래스에서 parse() 정적 메서드를 호출하여 확장 JSON 문자열을 Java 문서 객체로 읽을 수 있습니다. 이 메서드는 모든 형식의 확장 JSON 문자열을 구문 분석하고 데이터가 포함된 해당 클래스의 인스턴스를 반환합니다.

다음 예시에서는 Document 클래스를 활용해 예시 확장 JSON 문자열을 Document 객체로 읽는 방법을 보여 줍니다. parse() 메서드를 사용합니다:

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 문자열을 Java 객체로 읽을 수도 있습니다. 이 클래스에는 모든 형식의 확장 JSON 문자열에서 필드와 값을 순차적으로 구문 분석하고 이를 Java 객체로 반환하는 메서드가 포함되어 있습니다. 드라이버의 문서 클래스도 이 클래스를 사용하여 확장 JSON을 구문 분석합니다.

다음 코드 예에서는 JsonReader 클래스를 사용하여 확장 JSON 문자열을 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 쓰기

문서 클래스 사용

Document 또는 BsonDocument에서 toJson() 메서드를 호출하여 확장된 JSON 문자열을 작성할 수 있습니다. 선택적으로 JsonWriterSettings 인스턴스를 전달하여 확장된 JSON 형식을 지정할 수 있습니다.

이 예시에서는 확장 JSON을 릴렉스 모드 형식으로 출력합니다.

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 문자열을 출력할 수도 있습니다. JsonWriter 인스턴스를 생성하려면 Java Writer의 서브클래스를 전달하여 확장 JSON을 출력할 방법을 지정합니다. 선택적으로 JsonWriterSettings 인스턴스를 전달하여 확장 JSON 형식과 같은 옵션을 지정할 수 있습니다. 기본적으로 JsonWriter은(는) 완화 모드 형식을 사용합니다. MongoDB Java 드라이버의 문서 클래스도 이 클래스를 사용하여 BSON을 확장 JSON으로 변환합니다.

다음 코드 예시는 JsonWriter를 사용하여 확장 JSON 문자열을 만들고 이를 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 유형 변환

outputMode()를 지정하여 JSON 출력 형식을 지정하는 것 외에도 JsonWriterSettings.Builder에 변환기를 더해 출력을 추가로 사용자 지정할 수 있습니다. 이러한 변환기 메서드는 Java 유형을 감지하고 전달된 Converter에 의해 정의된 로직을 실행합니다.

다음 샘플 코드에서는 Lambda 표현식으로 정의된 변환기를 추가하여 완화 모드 JSON 출력을 간소화하는 방법을 보여 줍니다.

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 문서를 참조하세요.

돌아가기

BSON

문서