A Fonte de Dados é um recurso disponível no lado servidor dos projetos Cronapp e possibilita a comunicação bidirecional entre uma origem de dados, como um banco de dados, e diversas ferramentas no Cronapp, como páginas ou relatórios. Essa comunicação é realizada através do protocolo OData e possui diversos recursos como filtros, tratamento de dados, eventos, tratamento de segurança, geração de recurso REST e a possibilidade de reutilização da mesma Fonte de Dados em várias ferramentas do Cronapp. Esses aspectos garantem a interoperabilidade e integração entre as diferentes camadas do sistema.
Figura 1 - Fluxo de comunicação da Fonte de dados
A Fonte de dados e o componente visual fonte de dados, utilizado no Editor de views, são ferramentas diferentes. A Fonte de dados é um recurso criado no lado servidor do projeto e serve a todos os recursos que necessitam de uma Fonte de dados, já o componente visual fonte de dados é utilizado apenas nas páginas web e telas mobile (lado cliente) e tem o objetivo de referenciar uma Fonte de dados, fazendo a comunicação entre os demais componentes visuais (exemplo Grade) e a Fonte de dados referenciada. |
O Cronapp possui algumas variações (tipos) de Fonte de dados, essas variações fazem referências a origem dos dados e a possibilidade de personalização dos dados obtidos.
Figura 2 - Tipos de Fonte de dados
Personalizável
Para utilizar um dos tipos abaixo, primeiro será necessário criar e configurar uma Fonte de dados.
*.wsdl
).Não personalizável
Para utilizar o tipo abaixo, basta selecioná-la a partir de alguma ferramenta como Editor de view ou Relatório.
É possível acessar a lista das Fontes de dados do projeto a partir da árvore de recursos, no diretório Fontes de Dados (Localização: /Fontes de Dados/
Endereço: |
) (destaque 2 na árvore de recursos), ou através da janela Buscar Fonte de Dados. Para abrir a janela, acesse no menu do sistema: Projeto > Fonte de dados.
O diretório Fontes de Dados (destaque 2 na árvore de recursos) permite criar subdiretórios para organizar as Fontes de dados do sistema (3). Ao abrir a janela Buscar Fonte de Dados, a lista estará agrupada pelo tipo da Fonte de dados (Bloco de programação, Consulta a Entidades, SQL Nativo ou Web Services) e por diretório (3).
Figura 3 - Acesso a lista de Fontes de dados
Acesse o tópico Drag and Drop a ações da Fonte de dados para conhecer outras funções geradas pelos arquivos da Fonte de dados. |
É possível criar uma Fonte de dados por vários caminhos:
Na estrutura de arquivos, posicione o mouse sobre o diretório Fontes de Dados (destaque 2 da figura 3) (Localização: /Fontes de Dados/
Endereço: |
), clique no ícone (+) ao lado e selecione Fonte de dados.
Na estrutura de arquivos, abra o menu de contexto do diretório Fontes de Dados (destaque 2 da figura 3) (Localização: /Fontes de Dados/
Endereço: |
) e acesse Novo > Fonte de dados.
A janela de edição possui diversos recursos para personalizar a Fonte de dados. A configuração mais básica necessita apenas dos campos: Nome da consulta (destaque 5 da Figura 4), Tipo da Fonte de dados (6) e Origem dos dados (7).
Figura 4 - Janela de edição da Fonte de dados
Essa aba permite definir as consultas JPQL e SQL para as Fontes de dados Consulta a Entidades e SQL Nativo, respectivamente. Já os filtros/parâmetros (destaque 3 da figura 4.1) possuem diferenças a depender do tipo de Fonte de dados:
where
da consulta JPQL (destaque 1 da figura 4.1) ou ao utilizar a expressão ":<parâmetro>
" (dois pontos + nome do parâmetro) em outras partes da consulta.:<parâmetro>
" (dois pontos + nome do parâmetro) no endereço do endPoint (ex: http://www.ws.com/usuario/:idusuario/dados
), um filtro ("idusuario
") será criado na lista de parâmetros da aba Filtro (3).where
da consulta SQL (destaque 1 da figura 4.1) ou ao utilizar a expressão ":<parâmetro>
" (dois pontos + nome do parâmetro) em outras partes da consulta.No exemplo da Figura 4.1, a Fonte de dados retornará todos os usuários que possuem e-mails com algum valor definido no Valor do parâmetro (4), obtido a partir da função "ServidorEmail" do bloco de programação.
Figura 4.1 - Exemplo de filtro para uma entidade
Na aba Ações é possível definir o que será executado dos verbos HTTP (get, post, put, delete) e das ações filtrar e contar, além dos permissionáveis que terão acesso. A forma como a ação será executada vai depender do tipo da Fonte de dados.
O verbo Para Contar é usado internamente para paginar os registros retornados, porém, para funcionar, as ações Para Obter e Para Contar devem possuir as mesmas configurações. |
Figura 4.2 - Aba Ações da Fonte de dados
Bloco de Programação: ("Método do bloco a utilizar") permite selecionar funções existentes no arquivo do bloco de programação (blockly) que alimenta a Fonte de dados, essas funções podem ser selecionadas para substituir a execução padrão de cada ação.
Com exceção das ações "Para Obter" e "Para Contar", as demais ações não permitem configurar o que será passado via parâmetro para as funções selecionadas, a lógica das funções devem se adaptar a esse formato:
$orderby
"). A função deve retornar uma lista de objetos.{"id":"123456"}
).$filter
"). A função deve retornar uma lista de objetos.Permissão: define quais permissionáveis podem executar a ação configurada.
As permissões aplicadas na aba Ações serão herdadas para todos os atributos nas abas Campos e Campos calculados. Por exemplo, ao selecionar a permissão "Administradores" do verbo Para Obter na aba Ações, todos os atributos terão os seus campos Permitir Obter (destaques 11 da figura 4.4 e 9 da figura 4.5) configurados automaticamente para "Administradores". |
Se o campo "Entidade base" (destaque 8 da figura 4) estiver configurado, será possível selecionar a opção "Padrão" na caixa de seleção de cada ação. Essa opção faz com que a ação seja executada da mesma forma como ocorre nas Fontes de dados do tipo Consulta a Entidades. Assim, a lista de dados pode ser obtida via bloco de programação, mas as demais ações (inserir, atualizar e remover) serão executadas no banco de dados através da classe selecionada no campo "Entidade base". Acesse a documentação Tratar recurso REST de terceiros no Cronapp e veja exemplos de como tratar recursos de paginação, ordenação e filtro com Fonte de dados do tipo Bloco de programação. |
A aba Eventos permite rodar alguma função antes ou após a Fonte de dados executar uma ação. Os eventos "Antes" costumam ser muito úteis, pois, caso uma validação não seja atendida, uma exceção pode ser lançada.
Existem diferenças entre os eventos da Fonte de dados (Figura 4.3) e os eventos do componente visual fonte de dados. O componente visual trata os dados do lado cliente (JavaScript) e seus eventos não podem ser interrompidos, já os Eventos da Fonte de dados (Java) podem ser paralisados a partir de exceções em seu processo. Essas exceções são eventos que quebram o fluxo normal das instruções, assim, ao lançar uma exceção, uma mensagem será exibida na saída do console e uma notificação de erro na aplicação (veja mais detalhes sobre exceções em Validação da fonte de dados usando Eventos). |
Figura 4.3 - Aba Eventos da Fonte de dados
Colunas
Eventos
A aba Campos é responsável por mapear os objetos manipulados pela Fonte de dados, permitindo configurar cada atributo individualmente. Algumas características dessa aba mudam a depender do tipo de Fonte de dados:
select
serão automaticamente incluídos, mas também é possível selecionar uma classe no campo "Entidade base" (destaque 8 da figura 4) para adicionar todos os seus atributos automaticamente.Figura 4.4 - Aba campos e as várias configurações de seus atributos
data.<nome_atributo>
ou data
para enviar o objeto completo.$.data[0].id
).CASE WHEN
", caso o campo não possua expressão, exibirá apenas o nome do campo no formato: <tabela ou alias>.<nome_campo>
. (Veja mais detalhes na documentação Fonte de dados tipo SQL Nativo)Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.
As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo. Após a herança de permissões, ainda será possível ajustar as permissões individualmente em cada atributo. |
A aba Campos calculados permite incluir campos temporários nos objetos manipulados pela Fonte de dados. Diferentemente da aba Campos, aqui os atributos e seus valores não são persistidos, existem apenas durante o tempo de execução, na memória na aplicação.
Os campos calculados não suportam filtros, pois as requisições de filtros são encaminhadas ao banco de dados ou a outro recurso que alimenta a Fonte de dados e lá, os campos calculados não existem.
Os campos calculados podem não funcionar em recursos que rodem internamente no Cronapp (como é o caso da aba Pré-visualizar do Relatório e Dashboard), sendo exibidos somente ao executar a aplicação. |
Exemplo de uso: Em uma Fonte de dados vinculada a entidade usuários, podemos criar um campo calculado idadeAtual
, ela chamará uma função Servidor que obtém o campo dataNascimento
do usuário e retornará a sua idade baseado na data atual. Dessa forma, sempre que precisar exibir a idade atual dos usuários, basta chamar o campo calculado idadeAtual
da Fonte de dados.
Figura 4.5 - Aba de campos calculados
data.<nome_atributo>
ou data
para enviar o objeto completo.Permissões: define restrições para cada verbo aos permissionáveis cadastrados no sistema.
As configurações das permissões feitas na aba Ações serão herdadas automaticamente para cada atributo de campo calculado. Após a herança de permissões, ainda será possível ajustar as permissões individualmente em cada campo. |
Os campos calculados permitem referenciar atributos da própria entidade ou os atributos de outras entidades que possuam relacionamento 1 para N. Podemos utilizar esse recurso em diversas situações, por exemplo, em um relacionamento entre as entidades Cidade, Estado e País, no qual a Fonte de dados da entidade Cidade pode ter acesso a qualquer atributo das entidades Estado ou País. Na Figura 4.5.1, a Fonte de dados tem acesso ao atributo "região" da entidade Estado e ao atributo "nome" da entidade País. O termo this
representa a entidade atual.
Como não existem limites de relacionamentos que podem ser feitos em um banco de dados, o Cronapp limita a lista de atributos (via caixa de seleção) até o terceiro relacionamento. Porém, é possível inserir manualmente relacionamentos maiores - Exemplo: this.estado.pais.continente.planeta.distanciaSolemKm
.
Além da Fonte de dados do tipo Consulta a Entidades, esse recurso também estará disponível para os tipos Bloco de programação e Web Services, desde que tenha uma Entidade vinculada no campo Entidade base (destaque 8 da figura 4). |
Figura 4.5.1 - Campos calculados referenciando atributos de outras entidades relacionadas
Essa aba é utilizada apenas para as Fontes de dados do tipo Web services e permite configurar os cabeçalhos das requisições HTTP do endPoint configurado. Por padrão, os campos Accept e Content-Type já vem definidos ao criar uma Fonte do tipo Web Services, porém é possível alterar e adicionar novos.
Os cabeçalhos da janela "Obter campos do serviço" (destaque a da figura 4.6) não aceitam valores dinâmicos (função de blocos de programação ou expressão), dessa forma, ao configurar um cabeçalho com valor dinâmico na aba Cabeçalhos e depois acessar a janela "Obter campos do serviço" (destaque a), o cabeçalho estará vazio e será necessário informar o valor estático. Veja mais detalhes em Fonte de dados tipo Web Service (REST / SOAP). |
Figura 4.6 - Aba Cabeçalhos de uma Fonte de dados Web Services
Essa aba é utilizada para exibir uma mensagem amigável para o usuário caso ocorra algum erro ou a Fonte de dados não encontre chaves primárias e estrangeiras dos objetos manipulados. Essas mensagens podem ser internacionalizadas.
Esse recurso ainda não está disponível para as Fontes de dados do tipo SQL Nativo. |
Figura 4.7- Aba tratamento de erro
Colunas
Opções de tratamento
Neste tópico veremos mais detalhes da Fonte de dados.
Os arquivos da Fonte de dados (Localização: /Fonte de Dados/
Endereço: |
) na árvore de recursos podem ser arrastados (drag and drop) até o Editor de views para gerar componentes visuais já vinculados com o componente visual fonte de dados. Ao arrastar, o menu de contexto Criar Componente exibirá as opções abaixo, variando se o Editor selecionado for web ou mobile:
Figura 5 - Adicionando componentes visuais no Editor de Formulários a partir da Fonte de dados
Outro recurso interessante gerado a partir dos arquivos da Fonte de dados é o item Ação do seu menu de contexto, ele exibe opções para gerar páginas CRUDs com o Assistente de CRUD ou gerar um relatório, com os atributos da Fonte de dados (veja mais detalhes no tópico "Criar relatórios" da documentação Relatório).
Figura 5.1 - Item Ação do menu de contexto dos arquivos da Fonte de dados
A janela de configurações de parâmetros (Figura 6) está disponível em diversos locais dentro do Cronapp e também nas abas Filtro, Ações, Eventos, Campos, Campos calculados e Cabeçalhos da Fonte de dados. Ela permite definir os parâmetros que serão passados e seus valores.
A depender do local em que essa janela for aberta, algumas características podem mudar. Por exemplo, a possibilidade de incluir novos parâmetros a partir dessa janela ou selecionar as opções "Bloco" ou "Parâmetro" na coluna Valor do campo. Abaixo vemos a janela de seleção de Parâmetros da Aba Ações da Fonte de dados do tipo Web Services, em que é possível personalizar os parâmetros (QueryString) passados por cada ação.
Figura 6 - Exemplos de tipos de parâmetros da janela de configuração das ações
Os 4 itens abaixo representam as opções da coluna Valor do campo (destaque a da figura 6) e o que muda nos campos da coluna Conteúdo (essa coluna não possui um nome, mas está destaca pela letra b na figura 6):
:minhaVar
"). Os parâmetros destacados no item 2 da figura 6 possuirão o mesmo resultado.A opção Expressão na coluna Valor do campo (destaque a da figura 6) dará acesso a uma caixa de seleção editável onde é possível selecionar constantes Cronapp ou incluir uma expressões FTL (FreeMarker Template Language).
Com o uso de expressões FTL é possível incluir pequenos cálculos ou gerar pequenos templates diretamente no campo Conteúdo (destaque b da figura 6). Esse recurso pode ser bem útil no caso de parâmetros simples, porém, ao necessitar de algo um pouco mais complexo, recomendamos fortemente utilizar uma função de bloco de programação servidor.
Expressões FTL são criadas inserindo o termo "expression:
" e os caracteres "${ <conteúdo> }
" em cada expressão (destaque 4 da figura 6).
expression: ${page - 1} |
O resultado da expressão contida no bloco acima será o valor da constante "page" subtraído de 1.
Fique atento aos pontos abaixo ao trabalhar com expressões FTL e constantes Cronapp:
|
Para fazer conversões simples dentro de expressões FTL, como converter tipo string para number, basta incluir "?number
" e forçar a conversão.
expression: ${skip?number + 2} |
Se o retorno da constante "skip" no exemplo do bloco acima for "3" e não for utilizado o recurso "?number", o resultado final será "32" ao invés de "5", pois a expressão irá concatenar os 2 valores. Já ao utilizar o "?number", o resultado será "5", como esperado.
Clique aqui e veja mais detalhes sobre conversões FTL.
As constantes Cronapp são selecionáveis nos campos da coluna Valor do campo (destaque a da figura 6) em várias janelas, como as de configuração dos parâmetros query String, filtros e parâmetros de funções, elas retornam o valor do que foi selecionado. Algumas dessas constantes também são aceitas dentro de expressões FTL (veja exemplos de uso no tópico Expressão).
Veja a lista de Constantes:
:<chave>
no jpql ou parâmetros de entrada de bloco).data.idade
para obter o valor de "idade").data.idade
para obter o valor de "idade").data.idade
para obter o valor de "idade").token.name
para obter o valor do atributo "name" do token de autenticação).expression:${1 + 2}
" o valor retornado será "3".top
do OData (máximo de registros).skip
do OData (quantidade de registros ignorados).page: (paginação, único que retorna um valor inteiro) facilitador que traz o cálculo (top / skip + 1). Alguns serviços RESTs usam page
ao invés de top
e skip
.
Por padrão, ao requisitar a primeira página, a constante |
Exclusivo nos campos da aba Eventos:
Exclusivos do campo Ao gerar Erro (destaque 1 da figura 4.3) da aba Eventos:
As 3 constantes retornaram o objeto manipulado antes de ser inserido, atualizado ou removido. Após inserir ou modificar, o atributo pode sofrer modificações por eventos da Fonte de dados ou ações no banco de dados (ex.: valores default, triggers, auto incrementos etc).
A constante rawEntry
retorna o mapa completo da requisição enviada pela Fonte de dados (ex.: POST), possui o objeto da entidade vinculada com a Fonte de dados, campos calculados, metadatas, URI da requisição e outras informações. Já as constantes formData
e o data
funcionam de forma parecida, retornando apenas o objeto da entidade vinculada com a Fonte de dados. A constante data
é mais antiga e apenas consta na lista de constantes para manter compatibilidade com projetos mais antigos.
Imagine uma Fonte de dados vinculada a classe Application
do Diagrama de dados que possui apenas 2 atributos (id
e name
), essa Fonte de dados teve sua consulta personalizada (bloco de código abaixo) e foi incluído um campo calculado de nome "campoCalculado
".
select a.id, a.name, concat('Techne - ', a.name) as fullName from Application a |
O retorno das 3 constantes na chamada do evento Antes de Inserir será:
{"mediaMetadata": {"sourceLink":null, "etag":null, "contentType":null, "editLink":null}, "expandSelectTree": {"properties":[], "links":{}, "explicitlySelected":false, "expanded":false, "allKind":"IMPLICITLYTRUE", "all":true}, "metadata":{"id":null, "etag":null, "uri":null}, "properties":{"campoCalculado":"conteúdo do campo calculado", "_objectKey":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp", "fullName":null, "id":"6F01513D-9953-43F7-ADEF-B08CC7763252"}}
{"id":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp"}
{"id":"6F01513D-9953-43F7-ADEF-B08CC7763252", "name":"Cronapp"}
A Fonte de dados trabalha em cima do padrão OData, dessa forma, os recursos dessa tecnologia (filtro, conversão, paginação, ordenação e outros) funcionarão com a Fonte de dados. Veja na documentação oficial mais detalhes sobre os parâmetros utilizados pelo OData.
Os parâmetros apresentados nesse tópico são úteis, por exemplo, quando se quer obter os dados de uma Fonte para alimentar um sistema desenvolvido fora do Cronapp. Os Componentes visuais e demais recursos do Cronapp já são preparados para trabalhar de forma integrada, sem a necessidade desse nível de configuração. |
É possível obter os parâmetros passados em uma transação com a Fonte de dados utilizando o bloco de programação Obter parâmetro da query string. Veja um exemplo de uso desse recurso no tutorial Tratar recurso REST de terceiros no Cronapp.
<URI_da_FonteDados>?$filter=Price gt 20
<URI_da_FonteDados>?$filter=Price gt 20 and year(ReleaseDate) eq 2006
<URI_da_FonteDados>?$format=json
<URI_da_FonteDados>?$top=2&$inlinecount=allpages
<URI_da_FonteDados>?$orderby=price desc
<URI_da_FonteDados>?$orderby=price
<URI_da_FonteDados>?$select=name,price
<URI_da_FonteDados>?$skip=9
<URI_da_FonteDados>?$top=5
Nesta página
Assista sobre o tema no Cronapp Academy
Caso seja seu primeiro acesso ao Cronapp Academy, crie antes uma conta gratuita e matricule-se no curso abaixo. |