Menu Docs

Formato de dados do documento: JSON estendido

Neste guia, você verá como usar o formato Extended JSON no driver Java do MongoDB.

JSON é um formato de dados que representa os valores de objetos, arrays, números, strings, booleans e nulos. O formato Extended JSON define um conjunto reservado de chaves prefixadas com "$" para representar informações de tipos de campos que correspondem diretamente a cada tipo em BSON, o formato usado pelo MongoDB para armazenar dados.

Este guia explica os seguintes tópicos:

  • Os diferentes formatos do MongoDB Extended JSON

  • Como usar a biblioteca BSON para converter entre objetos JSON estendidos e Java

  • Como criar uma conversão personalizada de tipos de BSON

Para obter mais informações sobre a diferença entre estes formatos, consulte nosso artigo sobre JSON e BSON.

O MongoDB Extended JSON oferece diferentes formatos de string para representar dados BSON. Cada um dos formatos está em conformidade com o JSON RFC e atende a casos de uso específicos. O formato estendido, também conhecido como o formato canônico, oferece representações específicas para cada tipo de BSON para fazer conversão bidirecional sem perda de informações. O formato modo Relaxed é mais conciso e semelhante ao JSON comum, mas não representa todas as informações de tipo, como o tamanho de byte específico de campos numéricos.

Consulte a tabela a seguir para ver uma descrição de cada formato:

Nome
Descrição

Extended

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.

Modo relaxado

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.

Strict

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.

Observação

O driver analisa o tipo de JSON estendido $uuid de uma string para um objeto BsonBinary de subtipo binário 4. Para obter mais informações sobre $uuid análise do campo , consulte as regras especiais para analisar campos $uuid na especificação de JSON estendida.

Para obter informações mais detalhadas sobre esses formatos, consulte os seguintes recursos:

Os exemplos abaixo mostram um documento contendo um campo de ObjectId, data e número longo representado em cada formato Extended JSON. Clique na aba correspondente ao formato do exemplo que deseja ver:

{
"_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" }
}

Você pode ler uma string de JSON estendida em um objeto de documento Java chamando o método estático parse() da classe Document ou BsonDocument, dependendo do tipo de objeto que você precisa. Esse método analisa a string de JSON estendida em qualquer um dos formatos e retorna uma instância dessa classe contendo os dados.

O exemplo a seguir mostra como você pode usar a classe Document para ler um exemplo de string de JSON estendida em um objeto Document usando o método parse():

String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," +
"\"myNumber\": {\"$numberLong\": \"4794261\" }}}";
Document doc = Document.parse(ejsonStr);
System.out.println(doc);
Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

Para obter mais informações, consulte nossa página Fundamentos emDocumentos .

Você também pode ler uma string de Extended JSON em objetos Java sem usar as classes de documentos do driver Java do MongoDB, basta usar a classe JsonReader. Essa classe contém métodos para analisar sequencialmente os campos e valores em qualquer formato de string de Extended JSON, sendo gerado objetos Java. As classes de documentos driver também usam esta classe para analisar Extended JSON.

O seguinte exemplo de código mostra como usar a classe JsonReader para converter uma string de Extended JSON em objetos 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

Para obter mais informações, consulte a documentação da API do JsonReader.

Você pode gravar uma string de JSON estendida a partir de uma instância de Document ou BsonDocument chamando o método toJson(), opcionalmente passando uma instância de JsonWriterSettings para especificar o formato de JSON estendido.gra

Nesse exemplo, produzimos o JSON estendido no formato de modo relaxado.

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}

Você também pode gerar uma string de Extended JSON a partir de dados em objetos Java usando a biblioteca BSON com a classe JsonWriter . Para construir uma instância de JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Você também pode passar uma instância do JsonWriterSettings para especificar opções como o formato do Extended JSON. Por padrão, o JsonWriter usa o formato de modo Relaxed. As classes de documentos de driver Java do MongoDB também usam esta classe para converter BSON para Extended JSON.

O exemplo de código abaixo mostra como usar o JsonWriter para criar uma string de Extended JSON e fazer sua saída para System.out. Especificamos o formato passando o método construtor outputMode() para a constante 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"}}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

Além de especificar o outputMode() para formatar a saída JSON, você pode personalizar ainda mais a saída adicionando conversores ao JsonWriterSettings.Builder. Esses métodos de conversores detectam os tipos Java e executam a lógica definida pelo Converter passado para eles.

O seguinte código de amostra exibe como anexar conversores, definidos como expressões lambda, para simplificar a saída JSON no modo Relaxed.

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)));

A saída deste código se assemelha ao seguinte texto:

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}

Sem especificar os conversores, a saída JSON do modo relaxado se assemelha ao seguinte texto:

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API: