JSON-P: A API padrão para processamento de JSON em Java

A JSR 353, que trata da API para processamento de JSON em Java (JSON-P), atingiu o estágio de votação final no mês de abril. O JSON-P (similar ao JAXP) consiste em uma API de streaming (similar ao StAX) e uma API de modelo de objetos (similar ao DOM). A implementação de referência, denominada jsonp, atualmente está em fase beta e é open source sob a licença CDDL v1.1 e GPL v2. O JSON-P será parte do Java EE 7 e utilizado pela API JAX-RS como sua implementação padrão para JSON. Observe que a API não inclui a funcionalidade de data binding (similar ao JAXB), e não é relacionada ao popular JSONP ou "JSON with padding".

O JSON (JavaScript Object Notation) é um formato leve para troca de dados e é utilizado em aplicações Web, serviços REST e bancos de dados NoSQL. Com a popularidade do formato JSON e a existência de várias bibliotecas JSON para a plataforma Java (org.json, Jackson, google-gson, etc.), existe a necessidade de padronizar como os desenvolvedores criam e consomem JSON. O JSON-P é o futuro padrão e pode ser usado de forma independente ou como parte de containers Java EE 7.

O JSON-P é dividido em duas APIs: a API de streaming (javax.json.stream) e a API de modelo de objetos (javax.json). A API de streaming (Streaming API) fornece uma maneira eficiente e de baixo nível para fazer parsing e gerar JSON. Ela consiste de duas abstrações básicas: JsonParser e JsonGenerator. A interface JsonParser é um pull parser que fornece acesso de leitura em uma fonte de entrada em formato JSON. JsonGenerator fornece métodos para escrever JSON para um stream e também possibilita o encadeamento de chamadas de métodos. O gerador escreve pares de nome/valor em objetos JSON e valores em arrays JSON.

A seguir serão apresentados alguns exemplos de código que mostram o uso das interfaces JsonParser e JsonGenerator. O primeiro trecho mostra o dado em formato JSON que será lido ou criado pela API nos demais exemplos.

[
  {
    "type" : "home",
    "number" : "(800) 111-1111"
  },
  {
    "type" : "cell",
    "number" : "(800) 222-2222"
  }
]

O exemplo a seguir mostra o uso da interface JsonParser e sua saída no final.

JsonParserFactory factory = Json.createParserFactory(null);
JsonParser parser = factory.createParser(new StringReader(json));

while (parser.hasNext()) {
  Event event = parser.next();

  switch (event) {
    case KEY_NAME: {
      System.out.print(parser.getString() + "="); break;
    }
    case VALUE_STRING: {
      System.out.println(parser.getString()); break;
    }
  }
}

type=home
number=(800) 111-1111
type=cell
number=(800) 222-2222

A seguir, temos o exemplo com JsonGenerator, o qual imprime o objeto JSON no System.out.

JsonGeneratorFactory factory = Json.createGeneratorFactory(null);
JsonGenerator generator = factory.createGenerator(System.out);

generator.writeStartArray().
  writeStartObject().
    write("type", "home").
    write("number", "(800) 111-1111").writeEnd().
  writeStartObject().
    write("type", "cell").
    write("number", "(800) 222-2222").writeEnd().
  writeEnd().close();

A API de modelo de objetos (Object Model API) é uma API de alto nível, simples e fácil de usar e implementada no topo da API de streaming. Ela cria uma estrutura em árvore para representar o objeto JSON em memória, o qual pode ser facilmente navegado e consultado. As abstrações básicas na API são: JsonObject e JsonArray, ambas imutáveis. A interface JsonObject fornece uma visão em mapa (Map) para acessar a coleção não-ordenada de pares nome/valor no modelo. A interface JsonArray fornece uma visão em lista (List) para acessar a sequência ordenada de valores. Para criar esses objetos de modelo, pode-se utilizar o padrão builder (JsonObjectBuilder e JsonArrayBuilder) ou fazer leitura a partir de uma fonte de entrada (InputStream ou Reader) usando a interface JsonReader. Os modelos de objetos podem ser escritos para um stream de saída (OutputStream ou Writer) usando a interface JsonWriter.

Abaixo, segue um exemplo de criação de JsonArray usando JsonArrayBuilder. Apenas para lembrar, estamos trabalhando com o dado em formato JSON mostrado inicialmente.

JsonBuilderFactory factory = Json.createBuilderFactory(null);
JsonArray jsonArray = factory.createArrayBuilder()
    .add(factory.createObjectBuilder().
        add("type", "home").
        add("number", "(800) 111-1111"))
    .add(factory.createObjectBuilder().
        add("type", "cell").
        add("number", "(800) 222-2222")).build();

Agora, um exemplo usando o JsonReader.

try (JsonReader jsonReader = Json.createReader(new StringReader(json))) {
  JsonArray array = jsonReader.readArray();
  System.out.println(array);
}

A seguir, um exemplo usando JsonWriter.

try (JsonWriter jsonWriter = Json.createWriter(System.out)) {
  jsonWriter.writeArray(jsonArray);
}

Para experimentar a versão beta da API, baixe o jsonp ou utilize os artefatos Maven javax.json:javax.json-api:1.0-b06 e org.glassfish:javax.json:1.0-b06. É necessário instalar o Java SE 6 ou superior. Para mais informações, visite o site official da API JSON-P e leia os Javadocs. Há também um vídeo disponível no YouTube mostrando a apresentação da API JSON-P no JavaOne.