Biblioteca compartilhada JSON do Azure para Java – versão 1.1.0

  • Artigo

Documentação de build

O JSON do Azure fornece primitivos compartilhados, abstrações e auxiliares para JSON.

Introdução

Pré-requisitos

Incluir o pacote

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-json</artifactId>
  <version>1.1.0</version>
</dependency>

Principais conceitos

JsonSerializable

JsonSerializable é usado para definir como um objeto é serializado e desserializado usando a serialização no estilo de fluxo em que o próprio objeto gerencia a lógica de como ele é tratado. A interface fornece uma API baseada em toJson instância que manipula a gravação do objeto em uma JsonWriter API estática fromJson e que as implementações devem fornecer para definir como criar um objeto lendo de um JsonReader, se uma implementação não for fornecida UnsupportedOperationException será gerada.

JsonToken

JsonToken é uma enumeração básica que indica o estado atual em um fluxo JSON.

JsonReader

JsonReader fornece tipos primitivos básicos, de leitura primitivos e em caixa e conveniência, matrizes de leitura, mapas e objetos, APIs para leitura de JSON. JsonReader é fornecido para permitir que qualquer analisador JSON subjacente o implemente, como Jackson ou GSON, desde que a implementação passe nos testes fornecidos pelo test-jar deste pacote (JsonReaderContractTests).

JsonReader não progride no fluxo JSON até nextToken ser chamado, o que significa que JsonReader.getInt pode ser chamado indefinidamente retornando o mesmo inteiro sem erro até nextToken que progrida o fluxo JSON para frente.

JsonReader permite a conversão de tipo entre tipos JSON, como tentar converter uma cadeia de caracteres JSON em um número ou vice-versa, e para valores JSON não padrão comumente usados, como NaN, INF, -INF, Infinitye -Infinity.

JsonReader não se apropria da fonte de entrada JSON e, portanto, não fecha nenhum recurso se o JSON for fornecido usando um InputStream ou Reader.

Limites de aninhamento

JsonReaderA API genérica readUntyped rastreia o quão profundamente aninhado o objeto que está sendo lido. Se o aninhamento passar o limite de 1000, IllegalStateException será gerado para evitar StackOverflowError.

JsonWriter

JsonWriter fornece primitivos básicos, escritas e tipos primitivos em caixa e conveniência, gravando matrizes, mapas e objetos, APIs para escrever JSON. JsonWriter é fornecido para permitir que qualquer gravador JSON subjacente o implemente, como Jackson ou GSON, desde que a implementação passe nos testes fornecidos pelo test-jar do pacote (JsonWriterContractTests).

JsonWriter permite que valores JSON não padrão comumente usados, como NaN, INF, -INF, Infinitye -Infinity, sejam gravados usando writeNumberField ou writeRawValue.

JsonWriternão grava valores nulos , , ou quando gravados como um campo, writeBinaryField, writeBooleanField, writeNumberFieldou writeStringField, se um campo nulo precisar ser gravado, use writeNullField.StringNumberBooleanbyte[]

JsonWriter deve ser liberado periodicamente para garantir que o conteúdo gravado nele seja liberado para o tipo de contêiner subjacente, geralmente um OutputStream ou Writer. A falha na liberação pode resultar na perda de conteúdo. Fechar o JsonWriter conteúdo libera, portanto, é uma prática recomendada usar JsonWriter em um bloco try-with-resources em que o JsonWriter é fechado quando terminar de ser usado.

JsonWriter não se apropria da fonte de saída JSON e, portanto, não fecha nenhum recurso se o JSON estiver sendo gravado em um OutputSteam ou Writer.

Gerenciamento de Estado JSON

Para garantir que o JSON que está sendo gravado seja válido, JsonWriter mantém o estado do JSON usando JsonWriteContext e em cada tentativa de gravá-lo valida se a operação é válida. A implementação de JsonWriter deve garantir que o estado seja rastreado corretamente, por exemplo, quando nada tiver sido escrito, o estado JSON deve ser ROOT e ROOT não permite que nomes de campo JSON sejam gravados.

JsonProvider

JsonProvider é uma interface do provedor de serviços JsonReaderque permite que s e JsonWriters sejam criados usando implementações encontradas no classpath. JsonProvider também poderá criar as implementações padrão fornecidas por esse pacote se uma implementação não for encontrada no classpath.

JsonOptions

JsonOptions contém configurações que devem ser respeitadas por todas as implementações de JsonReaders e JsonWriters. No momento, há apenas uma configuração para determinar se números não numéricos, NaN, , INF-INF, Infinitye -Infinity têm suporte na leitura e gravação JSON com uma configuração padrão de true, que os números não numéricos são permitidos.

Fornecendo uma implementação de SPI

JsonReader e JsonWriter são interfaces do provedor de serviços usadas por JsonProvider e JsonProviders para permitir que as implementações sejam carregadas do caminho da classe. O pacote JSON do Azure fornece uma implementação padrão que é usada se não for possível encontrar no caminho da classe. Para fornecer uma implementação personalizada, implemente JsonReader, JsonWritere JsonProvider em seu próprio pacote e indique que o pacote fornece uma instância do JsonProvider. Para garantir que suas implementações estejam corretas, inclua a test dependência com escopo do JSON do Azure e estenda , JsonReaderContractTestsJsonWriterContractTestse JsonProviderContractTests. Esses testes descrevem todos os requisitos básicos de contrato estabelecidos por JsonReader, JsonWritere JsonProvider testam alguns cenários complexos para fornecer validação de qualquer implementação.

Exemplos

Confira os exemplos README para obter exemplos detalhados sobre como usar o JSON do Azure.

Solução de problemas

Se você encontrar bugs, registre problemas por meio de Problemas do GitHub ou check-out do StackOverflow para o SDK do Java do Azure.

Próximas etapas

Introdução às bibliotecas do Azure criadas usando o Azure Core.

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

  1. Bifurcar
  2. Criar seu branch de recurso (git checkout -b my-new-feature)
  3. Confirmar suas alterações (git commit -am 'Add some feature')
  4. Enviar por push para o branch (git push origin my-new-feature)
  5. Criar nova solicitação de pull

Impressões