Índice

Objetivo

O objetivo deste guia é mostrar ao usuário como realizar chamadas de serviços rest tanto de forma síncrona como assíncrona.

Criação da classe Builder de requisições

A classe base para fazer requisições no SDK é a CallService. Trata-se de um Builder que implementa uma interface (RequestExecutor) responsável por definir a forma de execução da requisição.

A classe Builder do CallService possui 2 construtores:

• CallBackRequsition callBackRequisition: é o CallBack ou o listener responsável para trazer a informação de sucesso ou falha de uma chamada de requisição (mais detalhes nas chamadas assíncronas);
• Class<?> objectClass, HashMap<Class, JsonDeserializer> typeAdapters: Definição do tipo de retorno da requisição e tipo de tratamento que pode ser feito para a conversão do retorno da requisição (mais detalhes em chamadas síncronas).

O Builder pode receber algumas variações de propriedades de acordo com a necessidade do desenvolvedor através de Setters:

• setApiConfigurable: Recebe um objeto do tipo ApiConfigurable que é a base de comunicação de uma requisição. Neste objeto encontra-se o endereço de conexão e as chaves de autenticação. Esta propriedade é necessária caso o desenvolvedor precise realizar alguma requisição para outro servidor que não respeite a configuração padrão.
• setCache_type: Recebe um objeto do tipo CacheType. Esta propriedade gerencia o status de cache da requisição, ou seja, o desenvolvedor poderá dizer se o resultado virá diretamente do servidor, do cache ou do cache recente (atualmente 5 minutos) (mais detalhes em cache de requisições).

O objeto CallService será criado ao dar o comando .build() na criação do Builde. Confira baixo um exemplo de implementação:

CallService callService = new CallService.Builder(callBackGeneric).build();

ou

CallService.Builder callServiceBuild = new CallService.Builder(callBackGeneric);

callServiceBuild.setCache_type(CacheType.CACHE_NO);

CallService callService = callServiceBuild.build();

Chamadas Assíncronas (uso de CallBacks)

O método de chamadas assíncronas baseia-se no uso de callbacks para retornar ao usuário o status de sucesso ou de falha da requisição efetuada.

Definição da estrutura

Ao ser criado e usado como parâmetro no builder do CallService, o CallBackRequisition deve definir os tipos de classe para serem convertidos e (opcionalmente) os adapters para auxílio de conversão de tipos compostos de objetos.

A estrutura se baseia em:

• Conjunto ou unidade do retorno passado na declaração da criação: new CallBackRequisition<ObjectToConvert> ou new CallBackRequisition<ArrayList<ObjectToConvert>>. Nesta etapa o desenvolvedor precisa dizer se a conversão da requisição resultará em um objeto simples ou lista de objetos;
• .Class para a conversão da requisição passado no construtor da criação: new CallBackRequisition<ObjectToConvert>(ObjectToConvert.class): Esta classe é o objeto final da requisição. Com base nesse construtor a requisição será convertida e mudará a assinatura do método de sucesso.
• Hash de tipos de JsonDeserializer para serem aplicados na conversão: Como a conversão se baseia na biblioteca Gson do google, é possível fazer tratamentos em tempo de execução e para isso deve ser criado classes que estendam da classe pai JsonDeserializer do Gson. JsonDeserializer.

O Padrão de retorno do CallBack é baseado em 2 métodos:

• onRequisitionSucess(ObjectToConvert, CacheStatus): Este método é chamado quando a requisição do servidor veio com o código 2xx. O método retorna com o objeto convertido passo no construtor do CallBack e também com o Status do Cache (mais detalhes em cache de requisições);
• onRequisitionFail(FluigException e): Este método é chamado quando a requisição não é completada de alguma forma (erro de conexão, erro do servidor, parâmetros de configuração inválidos)(Para mais detalhes sobre exceções, veja a guia Exceções).  
  
  

Tipos de CallBack

Atualmente suportamos 2 tipos de CallBacks:

• CallBackRequisition: CallBack padrão, onde as informações de unidade do retorno e o tipo de classe a ser convertida é obrigatória.
• CallBackObjectRequisition: CallBack usado com o objetivo de não converter os objetos, ou seja, caso o retorno sejá uma imagem, o campo de objeto no método onRequisitionSucess será byte[], caso contrário será String; Para usar esse CallBack não é preciso definir valor de unidade, classe ou typeAdapters.

Exemplo de código

Para executar o CallService no modo assíncrono basta chamar a função executeCallBack:

CallService callService = new CallService.Builder(new CallBackRequisition<PaginatedItemUsersVO>(PaginatedItemUsersVO.class) {

    @Override
    public void onRequisitionSuccess(PaginatedItemUsersVO obj, CacheStatus cacheStatus) {
    }

    @Override
    public void onRequisitionFail(FluigException e) {
    }

}).build();

callService.getCurrentUser().executeCallBack();

Para usar o CallBackObjectRequisition:

CallService callService = new CallService.Builder(new CallBackObjectRequisition() {

    @Override
    public void onRequisitionSuccess(Object obj, CacheStatus cacheStatus) {

		byte[] byteArray = (byte[]) obj;

		Bitmap bitmap = BitmapFactory.decodeByteArray(byteArray, 0, byteArray.length);

		imageView.setImageBitmap(bitmap);

	 }

    @Override
    public void onRequisitionFail(FluigException e) {
    }

}).build();

callService.getPicture("adm", PictureWidth.SIZE_34).executeCallBack();

Chamadas Síncronas

O método de chamadas síncronas se baseia na chamada direta de requisições.

Definição da estrutura

O método de chamadas síncronas baseia-se na execução das requisições em Threads criadas pelo próprio desenvolvedor ou em AsyncTasks. Através desse método o desenvolvedor pode gerenciar como as requisições são criadas, executadas e talvez canceladas.

O objeto CallService precisa ser criado passando no construtor do Builder:

• .Class para a conversão da requisição. Caso seja passado null, o objeto de retorno deverá ser convertido pelo próprio desenvolvedor;
• Hash de tipos de JsonDeserializer para auxiliar na conversão de tipos compostos de objetos (parâmetro opcional).

Para executar chamadas síncronas, o desenvolvedor precisa chamar o serviço executeSynchronized que retornará o objeto convertido ou não dependendo do que foi passado pelo construtor do CallService.Builder(). Além disso, requisições síncronas precisam tratar cláusula Throws ou circundar a chamada com Try Catch.

Exemplo de código

Thread thread = new Thread(new Runnable() {

    @Override
    public void run() {

        try {

            CallService callService = new CallService.Builder(PaginatedItemUsersVO.class, null).build();

            PaginatedItemUsersVO paginatedItemUsersVO = (PaginatedItemUsersVO) callService.getCurrentUser().executeSynchronized();

        } catch (Exception ex){
            ex.printStackTrace();
        }

    }
});

thread.start();

Cancelamento de Requisições

O método de cancelamento permite interromper a execução de uma determinada requisição antes de devolver o status de sucesso ou falha.

Definição da estrutura

O método de cancelamento só funciona para chamadas assíncronas, ou seja, só conseguirá ser cancelada a requisição que for criada por Thread interna usando o CallBack definido no construtor do CallService.

O cancelamento de requisições feitas pelo método síncrono só pode ser feito pelo próprio desenvolvedor já que é o mesmo que cria a Thread que controla a execução.

Para realizar o cancelamento de uma requisição do CallService, o modo é diferente da execução:

• Toda requisição do CallService retorna uma interface de execução chamada RequestExecutor.
• Para ter acesso à essa interface, deve- chamar o serviço sem executá-lo. Por exemplo, callService.Method();
• De posse da interface, é possível realizar a chamada para a execução e posterior cancelamento. Por exemplo, requestExecutor.executeCallBack e requestExecutor.cancelRequest;

Exemplo de código

CallService callService = new CallService.Builder(new CallBackRequisition<PaginatedItemUsersVO>(PaginatedItemUsersVO.class) {

    @Override
    public void onRequisitionSuccess(PaginatedItemUsersVO obj, CacheStatus cacheStatus) {
    }

    @Override
    public void onRequisitionFail(FluigException e) {
    }

}).build();

RequestExecutor requestExecutorCurrentUser = callService.getCurrentUser();

requestExecutorCurrentUser.executeCallBack();

requestExecutorCurrentUser.cancelRequest();