Página inicial do Docs → Desenvolver aplicações → MongoDB Drivers → Java síncrono
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, leia 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 | Também conhecido como o formato canônico, essa representação do JSON evita a perda de informações do tipo de BSON. Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos. |
Modo relaxado | Representação JSON que descreve documentos BSON com algum tipo de perda de informação. Este formato prioriza a legibilidade humana e a interoperabilidade na perda de determinadas informações de tipos. |
Shell | Representação JSON que corresponde à sintaxe usada no MongoDB shell. Esse formato prioriza a compatibilidade com o shell do MongoDB, que frequentemente usa funções JavaScript para representar tipos. |
Strict | Obsoleto. Esta representação é o formato legado que está totalmente em conformidade com o JSON RFC que permite a qualquer analisador JSON ler as informações do tipo. A API legada usa este formato. |
Observação
O driver analisa o $uuid
tipo de JSON estendido de uma string para um BsonBinary
objeto 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:
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);
Para obter mais informações, consulte nossa página Fundamentos em Documentos.
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();
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));
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(); }
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: