/ /

Trabalhe com dados JSON estendidos

Visão geral

Neste guia, você verá como usar o formato de dados JSON estendido ao interagir com documentos do MongoDB.

JSON é um formato de dados legível por humanos que representa os valores de objetos, arrays, números, strings, booleans e nulos. Este formato suporta apenas um subconjunto de tipos de dados BSON, que é o formato que o MongoDB utiliza para armazenar dados. O formato Extended JSON aceita mais tipos de BSON, definindo um conjunto reservado de chaves prefixadas com "$" para representar informações de tipos de campo que correspondem diretamente a cada tipo em BSON.

Para saber mais sobre JSON, BSON e Extended JSON, consulte o recurso JSON e BSON e a entrada de manual do Extended JSON MongoDB Server.

Formatos Extended JSON

O MongoDB Extended JSON fornece formatos de string para representar dados BSON. Cada formato está em conformidade com o JSON RFC e atende a casos de uso específicos.

A tabela abaixo descreve cada formato de Extended JSON:

Nome	Descrição
Estendido ou Canônico	Um formato de string que evita a perda de informações do tipo BSON durante as conversões de dados. Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos. JsonMode.EXTENDED
Descontraído	Um formato de string que descreve documentos BSON com alguma perda de informações de tipo. Este formato prioriza a legibilidade humana e a interoperabilidade na perda de determinadas informações de tipos. JsonMode.RELAXED
Shell	Um formato de string 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. JsonMode.SHELL

regras especiais para analisar campos $uuid

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")
}

Ler Extended JSON

Esta seção mostra como ler valores de JSON estendido em objetos Java das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonReader

Use as classes de documentos

Para ler uma string de JSON estendida em um objeto de documento Java , chame o método estático parse() da classe Document ou BsonDocument. Este método analisa a string de JSON estendida e armazena seus dados em uma instância da classe de documento especificada.

O exemplo seguinte utiliza o método parse() para ler uma string de Extended JSON em um objeto Document :

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

Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

Usar a classe JsonReader

Para ler uma string de Extended JSON em objetos Java sem usar as classes de documento , use a classe JsonReader da biblioteca BSON. Essa classe contém métodos para analisar sequencialmente os campos e valores da string de Extended JSON e retorná-los como objetos Java . As classes de documento driver também usam esta classe para analisar Extended JSON.

O código abaixo usa métodos fornecidos pela classe JsonReader para converter uma string de Extended JSON em objetos Java :

String string = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\" },"
        + " \"myNumber\": { \"$numberLong\": \"4794261\" } }";
JsonReader jsonReader = new JsonReader(string);
jsonReader.readStartDocument();
// Reads the "_id" field value
jsonReader.readName("_id");
ObjectId id = jsonReader.readObjectId();
// Reads the "myNumber" field value
jsonReader.readName("myNumber");
long myNumber = jsonReader.readInt64();
jsonReader.readEndDocument();
System.out.println(id + " is type: " + id.getClass().getName());
System.out.println(myNumber + " is type: " + Long.class.getName());
jsonReader.close();

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: java.lang.Long

Escrever JSON estendido

Esta seção mostra como gravar valores de JSON estendido a partir de objetos Java das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonWriter

Use as classes de documentos

Para gravar uma string de JSON estendida a partir de um objeto Document ou BsonDocument, chame o método toJson(). Você pode passar a esse método um parâmetro de objeto JsonWriterSettings para especificar o formato de JSON estendido.

O exemplo a seguir grava dados Document como JSON estendido do modo relaxado:

Document doc = new Document()
        .append("_id", new ObjectId("507f1f77bcf86cd799439012"))
        .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
        .append("myNumber", 4794261);
JsonWriterSettings settings = JsonWriterSettings.builder()
        .outputMode(JsonMode.RELAXED)
        .build();
System.out.println(doc.toJson(settings));

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

Usar a classe JsonWriter

Para gerar uma string de Extended JSON a partir de dados armazenados em objetos Java , você pode usar a classe JsonWriter da biblioteca BSON. Para construir um objeto JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Opcionalmente, você 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 documento BSON também usam esta classe para converter BSON para Extended JSON.

O exemplo a seguir usa um objeto JsonWriter para criar valores de string JSON estendido do modo canônico e enviá-los para System.out:

JsonWriterSettings settings = JsonWriterSettings.builder()
        .outputMode(JsonMode.EXTENDED)
        .build();
JsonWriter jsonWriter = new JsonWriter(
        new BufferedWriter(new OutputStreamWriter(System.out)), settings);
jsonWriter.writeStartDocument();
jsonWriter.writeName("_id");
jsonWriter.writeObjectId(new ObjectId("507f1f77bcf86cd799439012"));
jsonWriter.writeName("myNumber");
jsonWriter.writeInt64(11223344L);
jsonWriter.writeEndDocument();
jsonWriter.flush();

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

Conversão personalizada de tipo de BSON

Além de especificar o formato de saída JSON estendido, você pode personalizar ainda mais a saída adicionando conversores ao seu objeto JsonWriterSettings. Esses métodos de conversor especificam a lógica para lidar com diferentes tipos de dados durante o processo de conversão.

O exemplo a seguir converte o mesmo documento que o exemplo Usar classes de documentos. No entanto, este exemplo define os métodos conversores objectIdConverter() e dateTimeConverter() em um objeto JsonWriterSettings para simplificar a saída de Extended JSON do 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));

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

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Codecs

Indexes