Formato de dados do documento: JSON estendido
Nesta página
Visão geral
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.
Formatos Extended JSON
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:
JSON RFC Documentação oficial
MongoDB Extended JSON Entrada manual de servidor
BsonBinary Documentação da API
Especificação do Extended JSON Documentação do GitHub
Exemplos de JSON estendido
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" } }
Ler Extended JSON
Usando as classes de documentos
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 .
Como usar a biblioteca BSON
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.
Escrever JSON estendido
Usando as classes de documentos
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}
Como usar a biblioteca BSON
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:
Conversão personalizada de tipo de BSON
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: