Usando Componentes no LumisXP
Introdução
Tipicamente em serviços customizados será criado uma tabela no banco de dados para armazenamento de dados. Este artigo irá abordar como tais tabelas podem ser criadas, atualizadas e excluídas através de componentes e em quais arquivos você deve alterar para cada caso. Também será explicitado a diferença fundamental do upgrade x install e a utilização do databasedefinition.xml. Por fim, será explicado uma forma de você utilizar os componentes para realizar deploy de recursos estáticos no apache, um recurso interessante e útil para projetos em angular/react/vue ou que utilizam pwa.
Definição de componentes
Componentes são partes de uma aplicação instaláveis (através de módulos), ou até mesmo de uma aplicação completa, que podem conter:
- Serviços
- Temas
- Contextos de negócio
- Observadores
- Arquivos públicos
- Estrutura
Um componente deve, necessariamente, pertencer a um módulo. Dada uma estrutura de pastas e arquivos pertencentes a um dado módulo, um componente é demarcado por um arquivo de definição de componentes. Toda a árvore a partir da pasta que contém o arquivo pertence a esse componente, a menos as subpastas que também contém arquivos de definição de componentes. Nesse último caso, um outro componente é definido.
Neste artigo, iremos criar um componente que será responsável pela criação, atualização e remoção de tabelas do nosso serviço customizado. Para isso, devemos criar um arquivo chamado componentdefinition.xml na raiz do nosso serviço customizado
<?xml version="1.0" encoding="UTF-8"?>
<lumis-component xmlns="http://www.lumis.com.br/lumisportal/xsd/component" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.lumis.com.br/lumisportal/xsd/component http://www.lumis.com.br/lumisportal/xsd/component">
<version>1.0.0.0</version>
<description>Esta é a descrição do nosso serviço customizado</description>
</lumis-component>Estrutura de arquivos padrão
Para criar uma tabela em um serviço customizado você deve ter basicamente a seguinte estrutura:
component-install-script.xml
Responsável por realizar a criação de todas as tabelas do serviço. É importante frisar que o LumisXP irá executar as queries definidas neste arquivo somente na instalação do componente. Exemplo:
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 16445 $ $Date: 2014-09-18 21:21:12 +0000 (Thu, 18 Sep 2014) $ -->
<component-install xmlns="http://www.lumis.com.br/lumisportal/xsd/component-install-script" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<run-sql>
<sql>
CREATE TABLE my_custom_table
(
id CHAR(32) NOT NULL PRIMARY KEY,
title VARCHAR(255) NOT NULL,
description VARCHAR(500)
)
</sql>
</run-sql>
</component-install>component-upgrade-script.xml
Responsável por realizar criação de novas tabelas e alterações de tabelas já existentes após o componente já ter sido instalado. O LumisXP irá executar os steps desse arquivo na atualização do componente. Exemplo:
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 16582 $ $Date: 2014-11-07 13:18:31 +0000 (Fri, 07 Nov 2014) $ -->
<component-upgrade xmlns="http://www.lumis.com.br/lumisportal/xsd/component-upgrade-script" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<display-message step="1">
<message>Ok</message>
</display-message>
<run-sql step="2">
<sql>
ALTER TABLE my_custom_table ADD COLUMN priority int(11) DEFAULT NULL;
</sql>
</run-sql>
</component-upgrade>component-uninstall-script.xml
Responsável por realizar a remoção das tabelas criadas pelo serviço. O LumisXP irá executar os comandos deste arquivo na desinstalação do componente. Exemplo:
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 16445 $ $Date: 2014-09-18 21:21:12 +0000 (Thu, 18 Sep 2014) $ -->
<component-uninstall xmlns="http://www.lumis.com.br/lumisportal/xsd/component-uninstall-script" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<run-sql>
<sql>drop table my_custom_table</sql>
</run-sql>
</component-uninstall>Tudo que o componente criar no component-install-script.xml deve ser removido neste arquivo.
Databasedefinition.xml
Uma boa prática no arquivo component-install-script.xml é associá-lo ao arquivo databasedefinition.xml como demonstrado abaixo:
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 16445 $ $Date: 2014-09-18 21:21:12 +0000 (Thu, 18 Sep 2014) $ -->
<component-install xmlns="http://www.lumis.com.br/lumisportal/xsd/component-install-script" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<execute-database-file>
<file>databasedefinition.xml</file>
</execute-database-file>
</component-install>O databasedefinition.xml que irá criar a mesma tabela "my_custom_table" pode ser criado da seguinte forma:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- $Revision: 16445 $ $Date: 2014-09-18 21:21:12 +0000 (Thu, 18 Sep 2014) $ -->
<databaseDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.lumis.com.br/lumisportal/xsd/databasedefinition.xsd">
<table name="my_custom_table">
<fields>
<field name="id" type="guid" isNotNull="true"/>
<field name="title" type="string" isNotNull="true"/>
<field name="description" type="string" size="500"/>
</fields>
<constraints>
<constraint name="my_custom_table_PK" type="primaryKey">
<fields>
<field name="id"/>
</fields>
</constraint>
</constraints>
</table>
</databaseDefinition>Esse arquivo é uma especificação de como a tabela deve ser criada. Ou seja, ao invés de utilizar um comando SQL como feito no component-install-script.xml anteriormente, você irá definir a tabela utilizando um padrão de tags XML que serão interpretadas e processadas pelo LumisXP para realizar a criação de tabelas.
O principal benefício desta utilização é que o LumisXP ao processar este arquivo irá criar as tabelas considerando o banco configurado no lumishibernate.cfg.xml. Portanto a sintaxe definida aqui não está relacionada a nenhum banco de dados e ao ser processada será criada como o padrão do banco utilizado. Por exemplo, teríamos um problema se a tabela criada diretamente no component-install-script.xml criasse uma coluna de um tipo que só existe no MySQL, se precisássemos trocar de banco de dados teríamos que reescrever o create desta tabela.
Dessa forma, seu serviço customizado deve incluir a seguinte estrutura:
Upgrade x Install
Considere a seguinte situação hipotética: Um desenvolvedor criou um componente com a estrutura de arquivos padrões descritas acima, mas considerando que o component-upgrade-script.xml ainda não possui nenhum step definido. Ele realiza o deploy deste novo componente no ambiente de desenvolvimento e o LumisXP irá executar o component-install-script.xml criando as tabelas.
Em seguida foi identificado um bug que exigiu que fosse criado uma nova coluna "prioridade" no banco de dados. Nesta situação, o desenvolvedor irá adicionar um step no arquivo component-upgrade-script.xml para adicionar tal coluna. Após isso, ele irá realizar o deploy novamente no ambiente de desenvolvimento e o LumisXP irá executar o component-upgrade-script.xml que irá atualizar a tabela incluindo a nova coluna. Neste momento, é importante relatar como o LumisXP sabe que no próximo deploy ele não deve executar tal step. Na tabela lum_decomponent que armazena todos os componentes existe uma coluna chamada lastUpgradeStepExecuted que armazena o último step executado.
Por fim, com a demanda validada, o desenvolvedor realiza o deploy em produção. Neste momento ocorre uma situação interessante, conforme dito anteriormente, o componente será instalado em produção e o arquivo a ser executado será component-install-script.xml. Contudo, o arquivo component-upgrade-script.xml não foi executado. Então nosso banco será criado sem a coluna "prioridade"? A resposta é não, isso porque assume-se que a atualização que você colocou em component-upgrade-script.xml esteja presente no databasedefinition.xml. Sendo assim, a nova coluna prioridade também deveria estar no arquivo de criação das tabelas. Por esta premissa, o LumisXP ao executar o install irá criar o componente salvando-o em tabela com o valor da coluna lastUpgradeStepExecuted preenchido com 2, pois foi considerado que a instalação já ocorreu com a estrutura mais atualizada.
Gerando script a partir do databasedefinition.xml
A partir do databasedefinition.xml é possível visualizar o script que o LumisXP irá gerar. Por exemplo, no eclipse clique com o botão direito neste arquivo Run as / XSL Transformation e clique em Add Files. Selecione lumisportal/setup/bin/lumis/database/<arquivo do banco utilizado>. Isso irá gerar um arquivo com o script de criação considerando o banco escolhido.
Utilizando componentes para realizar deploy de recursos estáticos no apache
Geralmente os arquivos estáticos ficam contidos dentro da pasta tema do projeto. Ao atualizar o módulo deste projeto, o LumisXP irá transferir os estáticos do tema para <diretorio-estático>/lumis-theme/<diretório-tema>. Mas existem algumas situações em que se deseja incluir arquivos na raiz do apache. Por exemplo, se a aplicação for PWA você precisará que o service work possua escopo de todos os recursos que irão ser gerenciados por este. Nesta situação, caso o arquivo esteja na raiz do apache, o escopo deste service work será a pasta atual e todas as suas subpastas, ou seja, o apache inteiro.
Referência: https://pt.stackoverflow.com/questions/291937/escopo-de-service-worker
Para isso podemos utilizar os componentes da seguinte forma:
Tudo que estiver dentro do diretório componentfiles.www será realizado deploy posteriormente na raiz do apache.
Autor: Rodrigo Santana