JSON pode ser definido como um modelo para o armazenamento e troca de informações no formato texto. Suas principais características conceituais foram apresentadas em um recente artigo do portal Devmedia.

Este artigo aborda a manipulação de JSON na linguagem Java através da biblioteca org.json. Esta biblioteca foi desenvolvida pelo próprio “mentor” do modelo JSON, Douglas Crockford, e se tornou uma das mais conhecidas e utilizadas pelos desenvolvedores Java. Trata-se de um pacote composto por um conjunto classes / interfaces Java que podem ser estudadas, adaptadas e utilizadas livremente por qualquer desenvolvedor. A principal característica da org.json é que ela trabalha lendo todo o documento JSON para a memória, em um processo similar ao feito pela API DOM para processamento de XML.

O restante do artigo está dividido da seguinte forma. A Seção 2 descreve os passos para a obtenção e configuração da biblioteca. A Seção 3 é a principal do artigo, abordando a utilização da org.json em programas Java. Por fim, a Seção 4 apresenta as conclusões e comentários finais.

Download e Configuração

Para obter o pacote org.json, execute as etapas a seguir:

Passo 1: acesse o site JSON, será exibida uma tabela relacionando todas as classes que compõem o pacote (Figura 1). Clique em qualquer link da primeira coluna (Source), como por exemplo JSONObject.java.

Web site do pacote “org.json”
Figura 1. Web site do pacote org.json

Passo 2: você será levado para uma página do github, onde poderá fazer download de um arquivo compactado contendo todos os fontes que compõem o pacote. Para isto, basta clicar no link Downloads, destacado na Figura 2 (ele fica localizado no canto direito da tela, mais ou menos na parte superior).

Link para download
Figura 2. Link para download

Passo 3: A seguir será apresentada uma tela para que você escolha o formato do arquivo que deseja receber (zip ou tar.gz). Basta clicar no botão correspondente e o download será efetuado.

Após realizar o download, você pode criar um ambiente para testar o pacote. Se você utiliza o Eclipse ou Netbeans, basta criar um package chamado org.json em seu projeto e descompactar os arquivos .java que compõem a biblioteca dentro desse package.

Se você ainda tem pouca experiência em Java ou não utiliza nenhuma IDE, execute os passos descritos a seguir para criar o ambiente de teste.

Passo 1: Crie uma pasta para servir como pasta do projeto (por exemplo: C:\TESTE). Dentro desta pasta, crie uma pasta chamada org. Dentro da pasta org, crie uma pasta chamada json. A estrutura completa é mostrada na Figura 3.

Estrutura de pastas
Figura 3. Estrutura de pastas

Passo 2: Descompacte os arquivos da biblioteca para a pasta C:\TESTE\org\json.

Nota: Você pode descompactar todos os arquivos contidos no zip, porém apenas os sete arquivos relacionados a seguir é que realmente compõem a biblioteca (os outros arquivos contidos no zip são apenas utilitários)
  • JSONArray.java
  • JSONException.java
  • JSONObject.java
  • JSONString.java
  • JSONStringer.java
  • JSONTokener.java
  • JSONWriter.java

Utilizando o Pacote org.json

Após a criação do ambiente de teste, estamos prontos para escrever programas que utilizem o pacote org.json. A classe principal, ou seja, a que você mais irá utilizar, é a JSONObject. Uma variável deste tipo armazena um objeto JSON. Segundo a definição do Javadoc desta classe, um objeto JSON é uma coleção não ordenada de pares nome/valor. Os métodos get() e opt() podem ser utilizados para acessar os valores por nome, enquanto o método put() serve para modificar valores. Na Listagem 1 apresentamos um exemplo de programa que cria um JSONObject para armazenar dados de um filme. Os campos (ou pares nome/valor) “titulo”, “ano” e “genero” são inseridos um por um, com o uso do método put(). Em seguida, o objeto é serializado para uma string com o uso do método toString() (um dos que você mais vai usar na prática). O programa também mostra como usar o método put() para modificar o valor de um campo e como utilizar o get() para recuperar um determinado valor. É importante observar que é necessário importar as classes JSONObject e JSONException, além de ser preciso tratar uma exceção do tipo JSONException.

import org.json.JSONException;
import org.json.JSONObject;

public class TesteOrgJson1 {

	public static void main(String[] args) throws JSONException {
		
		/* -------------------------------------------------------
		 * TESTE 1 
		 * cria um JSONObject para armazenar dados de um filme
		 * -------------------------------------------------------*/
		
		//instancia um novo JSONObject
		JSONObject my_obj = new JSONObject();

		//preenche o objeto com os campos: titulo, ano e genero
		my_obj.put("titulo", "JSON x XML: a Batalha Final");
		my_obj.put("ano", 2012);
		my_obj.put("genero", "Ação");
		
		//serializa para uma string e imprime
		String json_string = my_obj.toString();
		System.out.println("objeto original -> " + json_string);
		System.out.println();
		
		//altera o titulo e imprime a nova configuração do objeto
		my_obj.put("titulo", "JSON x XML: o Confronto das Linguagens");
		json_string = my_obj.toString();
		System.out.println("objeto com o título modificado -> " + json_string);
		System.out.println();
		
		//recupera campo por campo com o método get() e imprime cada um
		String titulo = my_obj.getString("titulo");
		Integer ano = my_obj.getInt("ano");
		String genero = my_obj.getString("genero");
		
		System.out.println("titulo: " + titulo);
		System.out.println("ano: " + ano);
		System.out.println("genero: " + genero);		
	}
}
Listagem 1. Criando um objeto JSON e utilizando os métodos put(), get() e toString()

Alguns comentários adicionais sobre o programa. O método toString() converte o conteúdo do JSONObject para uma string JSON: uma string envolta em chaves, com dois pontos separando os nomes e valores e vírgulas separando cada para nome/valor. Com relação ao método get(), observe que existem métodos específicos para recuperar valores do tipo String (getString) e inteiro (getInt). Não mostramos no programa exemplo, mas vale comentar que também existem métodos getFloat(), getBoolean(), getJSONArray() e outros, para lidar com todos esses diferentes tipos.

Para executar o programa, basta gravá-lo com o nome TesteOrgJson1.java na pasta raiz de seu ambiente de teste (C:\TESTE). Compile e execute o programa (observe a Listagem 2 caso esteja em dúvida).

C:\TESTE>javac TesteOrgJson1.java

C:\TESTE>java TesteOrgJson1

objeto original -> {"genero":"Ação","titulo":"JSON x XML: a 
Batalha Final","ano":2012}

objeto com o título modificado -> {"genero":"Ação","titulo":"JSON x XML: 
o Confronto das Linguagens","ano":2012}

titulo: JSON x XML: o Confronto das Linguagens
ano: 2012
genero: Ação
Listagem 2. Compilando e Executando o programa

Na maioria das situações práticas, o desenvolvedor precisa preencher um objeto a partir de uma string codificada em JSON (ex: uma mensagem JSON recebida por uma aplicação Web). Isto não é problema, pois a classe JSONObject possui um construtor específico para lidar com esse caso. Sua utilização é mostrada na Listagem 3.

import org.json.JSONException;
import org.json.JSONObject;

public class TesteOrgJson2 {

  public static void main(String[] args) throws JSONException {
		
	/* -------------------------------------------------------
	 * TESTE 2
	 * cria um JSONObject a partir de uma string 
	 * -------------------------------------------------------*/
		
	//string json
	String json_str = "{\"titulo\":\"Os Arquivos JSON\",\"ano\":1998, 
	\"genero\":\"Ficção\"}";
		
	//instancia um novo JSONObject passando a string como entrada
	JSONObject my_obj = new JSONObject(json_str);

	//recupera campo por campo com o método get() e imprime cada um
	String titulo = my_obj.getString("titulo");
	Integer ano = my_obj.getInt("ano");
	String genero = my_obj.getString("genero");
		
	System.out.println("titulo: " + titulo);
	System.out.println("ano: " + ano);
	System.out.println("genero: " + genero);
		
	}
}
Listagem 3. Criando um objeto JSON a partir de uma String

A Listagem 4 mostra a compilação e o resultado da execução do programa.

C:\TESTE>javac TesteOrgJson2.java

C:\TESTE>java TesteOrgJson2
titulo: Os Arquivos JSON
ano: 1998
genero: Ficção
Listagem 4: Compilando e Executando o programa

Agora vamos tratar de outra classe importantíssima do pacote “org.json”, a classe JSONArray. Em JSON, um array é uma sequência ordenada de valores. Estes valores podem ser de um tipo básico (string, inteiro, float, etc.) ou podem ser objetos (JSONObject). No exemplo da Listagem 5, mostramos como utilizar um array para representar os gêneros de um filme. Para trabalhar com arrays é preciso realizar o import da classe JSONArray.

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class TesteOrgJson3 {

	public static void main(String[] args) throws JSONException {
		
		/* ----------------------------------------------
		 * TESTE 3
		 * Trabalhando com um array de strings 
		 * ---------------------------------------------*/
		
		//instancia um novo JSONObject
		JSONObject my_obj = new JSONObject();

		//preenche o objeto
		my_obj.put("titulo", "JSON x XML: a Batalha Final");
		my_obj.put("ano", 2012);
		
		//cria um JSONArray e preenche com valores string
		JSONArray my_genres = new JSONArray();
		
		my_genres.put("aventura");
		my_genres.put("ação");
		my_genres.put("ficção");
		
		//insere o array no JSONObject com o rótulo "generos"
		my_obj.put("generos", my_genres);
		
		//serializa para uma string e imprime
		String json_string = my_obj.toString();
		System.out.println(json_string);
	}	
}
Listagem 5. Criando um objeto JSON que contém um Array

A compilação e o resultado da execução do programa são mostrados na Listagem 6. Veja que a sintaxe JSON para representação do array consiste em uma string envolvida por colchetes, com vírgulas sendo utilizadas para separar cada valor do array.

 
C:\TESTE>javac TesteOrgJson3.java

C:\TESTE>java TesteOrgJson3
{"titulo":"JSON x XML: a Batalha Final","generos":["aventura","ação","ficção"],"
ano":2012} 
Listagem 6. Compilando e Executando o programa

A classe JSONArray oferece o método get() para que você possa acessar os valores do array por índice, o método put() para adicionar ou substituir valores e o método remove() para remover elementos do array. O programa da Listagem 7 demonstra o uso destes métodos. Neste programa, incialmente criamos um JSONObject a partir de uma string JSON. Essa string possui a representação de um array que contém o elenco de um filme. Originalmente, o elenco é composto por três atores: “Json Leigh”, “Mary Stylesheet” e “David Markupovny”. No corpo do programa, utilizamos o método getJSONArray(), da classe JSONObject, para recuperar o elenco em um JSONArray. Depois disso, são realizadas diversas operações sobre os elementos do array com o intuito de modificar o elenco (ex: adicionar ator, modificar nome de ator, remover ator).

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class TesteOrgJson4 {

	public static void main(String[] args) throws JSONException {
		
		/* -------------------------------------------------------
		 * TESTE 4
		 * manipulação de array 
		 * -------------------------------------------------------*/
		
		//string json: contém array com três elementos
		String json_str = "{\"elenco\":[\"Json Leigh\", 
		\"Mary Stylesheet\", \"David Markupovny\"]}";
		
		//instancia um novo JSONObject passando a string como entrada
		JSONObject my_obj = new JSONObject(json_str);

		//recupera o array "elenco"  
		JSONArray elenco = my_obj.getJSONArray("elenco");
		
		//imprime cada ator/atriz do elenco com o uso dos métodos 
		length() e get()
		System.out.println("Elenco Original");
		for (int i = 0; i < elenco.length(); i++) {
			System.out.println("(" + i + ") " + elenco.get(i));
		}
		System.out.println();
		
		//-- insere um novo ator no array 
		elenco.put("Michael Java Fox");
		
		System.out.println("Elenco com o novo ator");
		for (int i = 0; i < elenco.length(); i++) {
			System.out.println("(" + i + ") " + elenco.get(i));
		}
		System.out.println();
		
		//-- troca o nome da primeira atriz
		elenco.put(0, "Jennifer Json Leigh");
		
		System.out.println("Elenco com o nome da primeira atriz modificado");
		for (int i = 0; i < elenco.length(); i++) {
			System.out.println("(" + i + ") " + elenco.get(i));
		}
		System.out.println();
		
		//-- remove o terceiro ator
		elenco.remove(2);
		
		System.out.println("Elenco com o ator David Makupovny removido");
		for (int i = 0; i < elenco.length(); i++) {
			System.out.println("(" + i + ") " + elenco.get(i));
		}
	}
	
}
Listagem 7. Manipulando um Array com os métodos get(), put() e remove()

A compilação e o resultado da execução do programa são mostrados na Listagem 8.

C:\TESTE>javac TesteOrgJson4.java

C:\TESTE>java TesteOrgJson4

Elenco Original
(0) Json Leigh
(1) Mary Stylesheet
(2) David Markupovny

Elenco com o novo ator
(0) Json Leigh
(1) Mary Stylesheet
(2) David Markupovny
(3) Michael Java Fox

Elenco com o nome da primeira atriz modificado
(0) Jennifer Json Leigh
(1) Mary Stylesheet
(2) David Markupovny
(3) Michael Java Fox

Elenco com o ator David Makupovny removido
(0) Jennifer Json Leigh
(1) Mary Stylesheet
(2) Michael Java Fox
Listagem 8. Compilando e Executando o programa

Conclusões e Comentários Finais

Este artigo apresentou a biblioteca org.json que permite o processamento de JSON em programas Java. O artigo descreveu os passos para a sua obtenção e instalação e apresentou exemplos básicos de utilização.

Embora ainda não exista uma biblioteca adotada como padrão para trabalhar com JSON em Java, a org.json pode ser considerada uma forte candidata a tornar-se um padrão, uma vez que ela foi desenvolvida e é disponibilizada pelo próprio web site do projeto json: www.json.org. A documentação javadoc da biblioteca pode ser consultada no mesmo endereço.

O pacote org.json foi criado com o intuito de servir como modelo para todos os que desejarem criar bibliotecas para parsing de JSON em diferentes linguagens. A principal característica da biblioteca org.json é que ela trabalha lendo todo o documento JSON para a memória, em um processo similar ao feito pela API DOM para processamento de XML. No entanto, a forma de acessar e manipular o objeto em memória é muito mais simples do que quando trabalhamos com a API DOM. Os exemplos envolvendo a manipulação de JSONArray’s evidenciaram este fato, uma vez que demonstram que é bem mais simples trabalhar com um JSONArray do que trabalhar com uma árvore DOM. Com a org.json você consegue fazer muita coisa escrevendo código simples!

A principal desvantagem da org.json é a mesma da API DOM: como ela trabalha importando todo o documento para a memória, ela se torna inadequada para o processamento de documentos muito volumosos. Se você precisar trabalhar com arquivos JSON contendo milhares ou milhões de informações, recomenda-se o uso da API Jackson, que é mais complexa, porém eficiente para este tipo de situação.