IXC-ORM

Esse ORM visa facilitar a manipulação de registros do sistema IXC Provedor, através de sua API Oficial. Não precisa mais se preocupar com a construção das queries de busca, com a manipulação dos cabeçalhos, ou validação das requisições HTTP. Já está tudo aqui, a poucas linhas de código de "distância"! 😀

Download

Note

Requer a versão 21 ou superior do Java

<dependency>
    <groupId>br.dev.fscarmo</groupId>
    <artifactId>ixcorm</artifactId>
    <version>1.1.0</version>
</dependency>

Configuração das variáveis de ambiente

Você poderá optar por configurar as variáveis nas propriedades do seu projeto, no arquivo application.properties.
Ou no ambiente Docker, declarando cada uma delas no seu docker-compose.yaml. (sugestão: combinar com arquivo .env)

Particularmente falando, eu utilizo as duas configurações, sendo application.properties para testes e docker-compose.yaml para produção. 🙂

Propriedades

# .env
IXC_ACCESS_TOKEN=conteúdo_do_token_gerado_no_ixc_provedor
IXC_SERVER_DOMAIN=www.domínio_do_seu_servidor_ixc_provedor.com.br

# application.properties
ixc.access.token=conteúdo_do_token_gerado_no_ixc_provedor
ixc.server.domain=www.domínio_do_seu_servidor_ixc_provedor.com.br

Também funciona se você optar por carregar os valores a partir de um .env

# application.properties
ixc.access.token=${IXC_ACCESS_TOKEN}
ixc.server.domain=${IXC_SERVER_DOMAIN}

Docker

# docker-compose.yaml
environment:
  - IXC_ACCESS_TOKEN=${IXC_ACCESS_TOKEN}
  - IXC_SERVER_DOMAIN=${IXC_SERVER_DOMAIN}

Como utilizar

Da forma mais simples, será necessário manipular diretamente apenas quatro classes que estão no pacote br.dev.fscarmo.ixcorm.*
São elas as classes: IxcContext, IxcOrm, IxcResponse e IxcRecord. Sendo que as classes IxcOrm e IxcResponse só poderão ser manipuladas através de subclasses.

1 - Definição do método de carregamento das variáveis de ambiente

A biblioteca já possui duas classes (DockerEnv e PropertiesEnv) que irão facilitar o trabalho, caso você escolha declarar as variáveis de ambiente no arquivo application.properties, ou no ambiente Docker, através do arquivo docker-compose.yaml. O exemplo a seguir mostra como informar ao contexto da biblioteca que as variáveis deverão ser carregadas do application.properties:

import br.dev.fscarmo.ixcorm.IxcContext;
import br.dev.fscarmo.ixcorm.config.envs.PropertiesEnv;

public class Main {

    public static void main(String[] args) {
        PropertiesEnv environment = new PropertiesEnv();
        IxcContext.INSTANCE.setEnv(environment);
    }
}

A declaração das variáveis no arquivo application.properties deverá seguir o exemplo 1, assim como em ambiente Docker, você deverá seguir o exemplo 2, na sessão de Configuração das variáveis de ambiente.

2 - Declaração das classes manipuladoras

Para enviar requisições HTTP para a API do IXC Provedor, será necessário implemenrtar classes que representarão as tabelas que você deseja manipular. Essas classes deverão herdar da "superclasse" IxcOrm, como no exemplo a seguir, que simula a intenção de manipular os registros dos clientes:

package br.dev.fscarmo.ixcorm;

public class Cliente extends IxcOrm {

    public Cliente() {
        super("cliente");
    }

    public static Cliente newCliente() {
        return new Cliente();
    }
}

3 - Declaração das classes "Record"

As classes Record são como DTOs que irão mapear automaticamente as propriedades de cada registro retornado pela API do IXC Provedor. Para isso basta criar uma classe Record sendo ela uma "subclasse" de IxcRecord e declarar as propriedades que você deseja manipular, como no exemplo a seguir:

import br.dev.fscarmo.ixcorm.IxcRecord;
import com.google.gson.annotations.SerializedName;

public class ClienteRecord extends IxcRecord {

    @SerializedName("cnpj_cpf")
    private String cnpjCpf;
    private String razao;
    private String endereco;
    
    /* getter's e setter's */
}

Note

Você pode observar que a propriedade cnpjCpf está anotada com @SerializedName, da biblioteca Gson. Isso é necessário caso você queira "extrair" corretamente a propriedade que deseja, da resposta do IXC Provedor, sem "ferir" o padrão de conversão de nomes de variáveis do Java.

4 - Enviando uma requisição de listagem de clientes

Utilizando as classes criadas no exemplo 2 e no exemplo 3, para simular uma requisição de listagem dos registros de clientes cadastrados a partir de Janeiro de 2025:

import br.dev.fscarmo.ixcorm.IxcResponse;
import java.util.List;

IxcResponse response = Cliente.newCliente()
        .where("data_cadastro")
        .greaterThanEquals("2025-01-01")
        .GET();

List<ClienteRecord> clientes = response.getBody().getRegistros(ClienteRecord.class);

clientes.forEach(c -> {
    System.out.println();
    System.out.println("CNPJ/CPF: " + c.getCnpjCpf());
    System.out.println("Razão social: " + c.getRazao());
    System.out.println("Endereço: " + c.getEndereco());
});

Contribuições

Contribuições são sempre bem-vindas!
Se você conhece uma maneira melhor de fazer algo, por favor, me avise! Caso contrário, é sempre melhor fazer um PR na branch master.

At.te,
Felipe S. Carmo.