Telescope (core)

T2 - Como serializar e desserializar uma entidade em um objeto JSON?

ADS.FAQ-12896
A T2 possui alguns métodos que facilitam muito a serialização e deseralização de entidades em objetos JSON.
Objetos JSON são menores que XML e, na maioria das vezes, mais simples de serem utilizados.

Digamos que temos um entidade CupomFiscal que precisamos serializar em um JSON juntamente com seus itens e pagamentos. Para serializar, bastaria excecutar o seguinte: 
EntCuponsFiscais cf = ...
...
JSONObject json = cf.toJSON();
json.put("ITENS", cf.findAllItensCuponsFiscaisCupomFiscal().toJSONList());
json.put("PAGAMENTOS", cf.findAllPagamentosCuponsFiscaisCupomFiscal().toJSONList());
String stringJson = json.toString();

Note que foi necessário nomear duas propriedades para receber os arrays com os itens e com os pagamentos do cupom.
O JSON resultante é algo tipo: 
{
   "CUPOM_FISCAL": 1,
   "DATA_ABERTURA": "2013-07-16 11:16:31.432",
   "DATA_EMISSAO": "2013-07-16 11:17:52.725",
   "ECF_ESTABELECIMENTO_ID": 612,
   "EMITIR_DOCUMENTO_FISCAL": "N",
   "ENVIADO_ERP": "N",
   "ID": 103997,
   "ITENS": [
       {
           "ALIQUOTA_APROXIMADA_TRIBUTOS": 35,
           "ALIQUOTA_ICMS": 17,
           "CODIGO_PRODUTO": "10696",
           "CUPOM_FISCAL_ID": 103997,
           "DESCRICAO_PRODUTO": "LUBRAX HYDRA INDUSTRIAL SH-AD 68 BD 20 L",
           "ID": 103998,
           "PERCENTUAL_BASE_ICMS": 0,
           "PRECO_INFORMADO": "N",
           "PRECO_UNITARIO": 122.75,
           "PRECO_UNITARIO_LISTA": 122.75,
           "PRODUTO_ID": 95363,
           "QUANTIDADE": 1,
           "SEQUENCIA_ECF": 1,
           "SITUACAO": "N",
           "SITUACAO_TRIBUTARIA": "30",
           "UNIDADE_MEDIDA": "BD",
           "VALOR_BASE_ICMS": 0,
           "VALOR_ICMS": 0,
           "VALOR_ISENTOS_ICMS": 0,
           "VALOR_OUTROS_ICMS": 122.75,
           "VALOR_TOTAL": 122.75
       },
       {
           "ALIQUOTA_APROXIMADA_TRIBUTOS": 35,
           "ALIQUOTA_ICMS": 17,
           "CODIGO_PRODUTO": "10696",
           "CUPOM_FISCAL_ID": 103997,
           "DESCRICAO_PRODUTO": "LUBRAX HYDRA INDUSTRIAL SH-AD 68 BD 20 L",
           "ID": 103999,
           "PERCENTUAL_BASE_ICMS": 0,
           "PRECO_INFORMADO": "N",
           "PRECO_UNITARIO": 122.75,
           "PRECO_UNITARIO_LISTA": 122.75,
           "PRODUTO_ID": 95363,
           "QUANTIDADE": 1,
           "SEQUENCIA_ECF": 2,
           "SITUACAO": "N",
           "SITUACAO_TRIBUTARIA": "30",
           "UNIDADE_MEDIDA": "BD",
           "VALOR_BASE_ICMS": 0,
           "VALOR_ICMS": 0,
           "VALOR_ISENTOS_ICMS": 0,
           "VALOR_OUTROS_ICMS": 122.75,
           "VALOR_TOTAL": 122.75
       }
   ],
   "NOME_CLIENTE": "CONSUMIDOR FINAL",
   "PAGAMENTOS": [{
       "CUPOM_FISCAL_ID": 103997,
       "FORMA_PAGAMENTO": "Dinheiro",
       "ID": 104001,
       "VALOR_PAGAMENTO": 500
   }],
   "REINICIOS_ECF": 1,
   "SITUACAO": "E",
   "TROCO": 80.63,
   "VALOR_APROXIMADO_TRIBUTOS": 85.92,
   "VALOR_DESCONTO_ACRESCIMO": 0,
   "VALOR_TOTAL_CUPOM_FISCAL": 419.37,
   "VALOR_TOTAL_MERCADORIAS": 419.37
}

Para fazer o processo inverso, ou seja, recuperar os valores das entidades a partir de um objeto JSON, seria necessário utilizar o código abaixo: 

JSONObject json = new JSONObject(stringJson);
EntCuponsFiscais cf = new EntCuponsFiscais(ctx);
cf.readFrom(json);

Para ler os itens e/ou pagamentos do cupom, é necessário utilizar algo como: 

List<EntItensCuponsFiscais> itens = JSONUtil.toEntityList(json.getJSONArray("ITENS"), EntItensCuponsFiscais.class, ctx);
List<EntPagamentosCuponsFiscais> pagamentos = JSONUtil.toEntityList(json.getJSONArray("PAGAMENTOS"), EntPagamentosCuponsFiscais.class, ctx);

Note que estes métodos não salvam os objetos na base de dados, eles apenas reconstroem os objetos. Exemplo: 
for (EntItensCuponsFiscais item : itens) {
    item.nullifyId();
    item.setCupomFiscalId(cf.valueOfId());
    item.ins();
}