--- title: Webservices no 4biz slug: developer/webservices-no-4biz description: This document provides a comprehensive guide to implementing the Citrest WebService in the 4biz ESP system. It covers the fundamental principles, data structures, and recommended patterns for creating new services. The document focuses on the RESTEasy imp createdAt: 2022-02-09T16:49:44.000Z --- :::hint{type="info"} 🖊 **Nota****: **O Web Service é uma solução usada na integração de sistemas e comunicação entre diferentes aplicativos. Com essa tecnologia é possível que novas aplicações possam interagir com aquelas que já existem e que sistemas desenvolvidos em diferentes plataformas sejam compatíveis. ::: :::hint{type="success"} ✅ **Regra****: **Web Services são componentes que permitem que os aplicativos enviem e recebam dados no formato XML. Cada aplicativo pode ter sua própria "**linguagem**", que é traduzida em uma linguagem universal, o formato XML. ::: 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. ## O padrão RestEasy 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](http://www.jboss.org/resteasy). ## Modelo de dados 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. ## Classes de Recursos 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 \ Resources.java.` A Classe de Recurso que intercepta a chamada http para o webservice deve ser mapeada para o arquivo web.xml. Por exemplo: :::BlockQuote \\resteasy-resources2\\br.com.centralit.4biz.rest.resource.RestOperationResources​\\ ::: 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. ## Classes de Utilidade 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: - Verifica se o SessionId existe e não está expirado. - Retorna um objeto RestSessionDTO associado ao SessionId. - Verifica se a operação existe na tabela Rest\_Operation e retorna o objeto RestOperationDTO. - Verifica se algum grupo de usuários associado à sessão tem permissão na tabela Rest\_Permission. 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. ## Regras Específicas 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: | **idrestparameter** | **Identificador** | **Descrição** | | ------------------- | ------------------ | --------------------------- | | **1** | CONTRACT\_ID | Contract ID | | **2** | ORIGIN\_ID | Source ID | | **3** | REQUEST\_ID | Demand type ID for requests | | **4** | INCIDENT\_ID | Incident demand type ID | | **5** | DEFAULT\_DEPTO\_ID | Unit Default ID | Cada operação pode ter um ou mais domínios de parâmetros na tabela Rest\_Domain. | **idrestparameter** | **idrestoperation** | **valor** | | ------------------- | ------------------- | --------- | | **1** | 1 | 1 | | **1** | 6 | 1 | | **2** | 1 | 7 | | **2** | 6 | 10 | | **3** | 1 | 1 | | **3** | 6 | 1 | | **4** | 1 | 3 | | **4** | 6 | 3 | | **5** | 1 | 3 | | **5** | 6 | 3 | 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: - Registre uma operação na tabela Rest\_Operation e diga qual classe Java irá executá-la. - Conceda permissões de execução de operação para um ou mais grupos na tabela Rest\_Permission. - Registre os parâmetros na tabela Rest\_Parameter. - Associe os domínios do parâmetro de operação na tabela Rest\_Domain. ## Estrutura de Classe 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: :::BlockQuote xjc "\{path and name of xsd}" -d "\{absolute path to src} eg: D:\Ambiente\jboss\server\default\deploy\CitCorpore.war\WEB-INF\src}" -p \{pakage name} eg: {br.com.centralit.4biz.rest.schema} ::: 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. ## Classe CtError A classe CtError é referenciada pelas outras classes usadas para executar as operações do Citrest. ## Classe CtLogin E CtLoginResp 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. ## Tratamento de Erro 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. :::BlockQuote CtNotificationGetReasonsResp resp = **new** CtNotificationGetReasonsResp();CtNotificationGetReasons input = (CtNotificationGetReasons) message;**if** (input.getTaskId() == **null**) \{resp.setError(RestOperationUtil.*buildError*( RestEnum.*INPUT\_ERROR*, "Id da tarefa não informado"));**return** resp;}...} **catch** (Exception e) \{e.printStackTrace();resp.setError(RestOperationUtil.*buildError*(e));**return** resp;} ::: ## Exemplo Prático 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: 1. O XSD das classes CtNotificationGetByUser e CtNotificationGetByUserResp foi definido no arquivo br.com.centralit.4biz.rest.xsd.MobileNotification.XSD 2. As classes foram geradas no pacote br.com.centralit.4biz.rest.schema por xjc.jar 3. As entradas a seguir foram incluídas no arquivo Web.xml do projeto 4biz: :::BlockQuote \\resteasy-resources3\\br.com.centralit.4biz.rest.resource.RestMobileResources\\\\resteasy-servlet\\/mobile/\*\\ ::: 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. 1. A classe RestMobileResources foi criada da seguinte forma: :::BlockQuote @Path("/mobile")**public** **class** RestMobileResources \{@POST\@Path("/notification/getByUser")**public** Response getnotificationByUser(CtNotificationGetByUser input) \{input.setMessageID("notification\_getByUser");**return** RestOperationUtil.*execute*(input);} ::: A configuração e implementação web.xml acima determinam que As chamadas http: //.../mobile/notification/getByUser serão interceptadas pela classe RestMobileResources. 1. A execução da classe RestOperationUtil direciona a execução para a classe RestMobile porque é a classe associada à operação notification\_getByUser na tabela Rest\_Operation. Na classe RestMobile, existe o método execute que obedece à interface padrão: :::BlockQuote public CtMessageResp execute(RestSessionDTO restSessionDto, RestExecutionDTO restExecutionDto, RestOperationDTO restOperationDto, CtMessage message) throws AXBException :::