Webservices no 4biz



Este documento descreve a implementação do WebService no 4biz ESP. Chamado Citrest, o serviço da Web usa a implementação RESTEasy do padrão RESTFul. Através de exemplos práticos, os conceitos básicos, estruturas de dados e padrões a serem seguidos na implementação de novos serviços serão apresentados.

Representational State Transfer (REST) descreve as arquiteturas que usam o protocolo HTTP ou protocolos semelhantes, restringindo a interface a um conjunto de operações HTTP conhecidas: GET, POST, PUT e DELETE.

O Citrest usa o RESTEasy, que é uma implementação da especificação JAX-RS que fornece uma API Java para serviços da Web RESTful por meio do protocolo HTTP.

Este documento não tem a intenção de apresentar detalhes sobre a implementação RESTful ou RESTEasy, já que existe extensa documentação na Internet sobre o assunto, como no site http://www.jboss.org/resteasy.

Uma estrutura foi criada no banco de dados para armazenar os dados necessários para o funcionamento do Citrest. O modelo de dados rest_v2.pdm está localizado no diretório CitCorporeWeb/Model .

Todas as tabelas mantidas no Citrest possuem o prefixo Rest_ e possuem relacionamento com outras tabelas no modelo 4biz: ObjetoNegocio, Grupo, Usuário e ProcessamentoBatch.

As Classes de Recursos são classes simples, POJO, contendo anotações JAX-RS para indicar mapeamentos e operações existentes.

As classes Resources devem estar no pacote br.com.centralit.4biz.rest.resource e seguir o padrão de nomenclatura usado nas outras classes Resources, Rest \ <NomeDoUC > Resources.java.

A Classe de Recurso que intercepta a chamada http para o webservice deve ser mapeada para o arquivo web.xml. Por exemplo:

Uma nova instância da Classe de Recurso é criada para cada solicitação do recurso. Cada método de recurso recebe como um parâmetro uma instância filho da classe CtMessage.java e retorna um objeto do tipo CtMessageResp. Nesta instância é atribuído o valor do atributo MessageID. Essa instância é passada como um parâmetro para o método Execute da classe de utilitário RestOperationUtil.java.

A classe RestOperationUtil.java é responsável por realizar as validações e o direcionamento da solicitação de recurso para a classe responsável pela Operação.

O método Execute (entrada CtMessage) é o método chamado pelas classes de Recursos e recebe como parâmetro uma instância de CtMessage com o atributo MessageID atribuído.

A classe RestOperationUtil obtém junto à classe RestUtil.java uma instância de cada Serviço e executa as seguintes verificações:

Depois que essas validações são feitas, a classe executa a Inicialização da Operação, registrando os atributos na tabela Rest_Execution. A tabela RestExecution funciona como uma tabela de Log de Execução. Observe que a execução é criada com o status NotInitiated, ou seja, a operação ainda não foi inicializada. Esse status será atualizado posteriormente de acordo com o resultado da execução da operação.

Depois de executar o log de execução, a classe RestOperationUtil instancia a classe Operation obtida do atributo JavaClass da tabela Rest_Operation e executa a chamada para o método execute.

O método Execute é uma condição do contrato da Interface IRestOperation. As classes que implementam essa interface precisam implementar o método de execução.

Para cada messageID, é feita uma chamada para um método específico para tratamento.

Cada um desses métodos pode fazer chamadas para o 4biz Services Layer para reutilização de serviços.

Todas as classes responsáveis pela operação do serviço da web devem ser registradas na tabela Rest_Operation.

Cada operação possui uma classe associada que obedece a uma interface padrão RestOperation e é responsável por sua execução.

A classe que executa a operação pode ser do tipo Java ou JavaScript (atributo ClassType). Atualmente, apenas o tipo Java é suportado.

Uma operação pode ser síncrona ou assíncrona (atributo OperationType). Uma operação síncrona é executada imediatamente quando é chamada. Uma operação assíncrona aponta para o processamento em lote. Atualmente, somente operações síncronas são suportadas.

Para que um determinado usuário possa executar uma operação, pelo menos um grupo de usuários deve estar associado à operação na tabela Rest_Permission.

A tabela Rest_Parameter armazena os parâmetros que podem ser usados para executar operações. Exemplos de parâmetros são:

Cada operação pode ter um ou mais domínios de parâmetros na tabela Rest_Domain.

Cada execução de uma operação específica é registrada na tabela Rest_Execution. Essa tabela registra a data e a hora da solicitação, o ID do usuário que está solicitando a execução, a classe de entrada, os dados de entrada e o status atual da execução.

Cada resultado de uma execução é registrado na tabela Rest_Log. Essa tabela registra a data e hora de execução, a classe de saída, os dados de saída e o status de execução.

Para a criação de um novo recurso, o desenvolvedor deve seguir as seguintes etapas de parametrização:

Todas as classes usadas pelo Citrest devem ser definidas por .XSD específico. A partir de .XSD, as classes podem ser geradas automaticamente pelo plug-in do eclipse ou pelo xjc.jar, disponível na iniciativa 0015 no SharePoint. Para gerar as classes do xjc, você deve usar a seguinte linha de comando:

O .XSD deve estar no pacote br.com.centralit.4biz.rest.xsd e as classes geradas devem estar no pacote br.com.centralit.4biz.rest.schema. Nesses pacotes já existem várias classes .XSD e várias usadas pelo Mobile que podem ser usadas como exemplo.

A classe CtError é referenciada pelas outras classes usadas para executar as operações do Citrest.

Toda operação em execução no Citrest requer um SessionID retornado pelo login. O login é implementado na classe br.com.centralit.4biz.rest.resource.RestOperationResources e tem como entrada um objeto da classe CtLogin.

Como resultado do login, o objeto SessionID ou CtError é retornado pelo login por meio da classe CtLoginResp.

O tratamento de erros de qualquer método de execução deve obedecer ao padrão de encapsulamento do objeto CtError implementado na classe RestOperationUtil.

Para facilitar a compreensão, esta seção detalha a implementação e a operação do serviço GetByUser usado no Mobile. É responsável por retornar a lista de requisições e incidentes no portfólio de trabalho de um determinado usuário.

As seguintes etapas foram seguidas para sua implementação:

Essas entradas especificam que existe uma nova classe de recurso para o RESTEasy e qualquer URL que contenha / mobile / será interceptada pelo servlet de serviço da web.

A configuração e implementação web.xml acima determinam que As chamadas http: //.../mobile/notification/getByUser serão interceptadas pela classe RestMobileResources.