Skip to content

Changes

Page history
feat: migra do MySQL para o PostgreSQL nas instruções específicas para a plataforma Jakarta EE. authored by Vítor E. Silva Souza's avatar Vítor E. Silva Souza
Hide whitespace changes
Inline Side-by-side
plataformas/Java,-Jakarta-EE-(WildFly),-PostgreSQL-e-Maven.md 0 → 100644
View page @ ea65f553
Esta página descreve uma plataforma para o Desenvolvimento Web em Java com Jakarta EE (WildFly), PostgreSQL e Maven, e faz parte do [Catálogo do LabES](../home).
## O que é?
Esta plataforma de desenvolvimento é formada pelos seguintes componentes:
* [Jakarta EE](https://jakarta.ee/), anteriormente (até a versão 8) conhecida como [Java EE](https://www.oracle.com/br/java/technologies/java-ee-glance.html) ou Java Enterprise Edition, é um conjunto de padrões que definem uma plataforma de desenvolvimento de aplicações escaláveis e distribuídas (_cloud-native_) em [Java](https://dev.java/). Cada padrão trata da infraestrutura para lidar com um problema comum de aplicações deste gênero (ex.: [JAX-RS](https://jakarta.ee/specifications/restful-ws/) especifica a API para implementação de serviços Web RESTful) e pode ser implementado por diferentes _frameworks_ (ex.: JAX-RS é implementado por [RESTEasy](https://resteasy.dev/) e [Jersey](https://eclipse-ee4j.github.io/jersey/)). O desenvolvedor da aplicação não precisa conhecer as implementações, apenas a API padronizada;
* [WildFly](https://www.wildfly.org/) é um servidor de aplicação Java, ou seja, um software que implementa as especificações do Jakarta EE e, portanto, pode hospedar aplicações _cloud-native_ desenvolvidas nesta plataforma como, por exemplo, aplicações Web Java. Ele combina as implementações de cada padrão definido pelo Jakarta EE (ex.: para atender à especificação [JAX-RS](https://jakarta.ee/specifications/restful-ws/), ele inclui o framework [RESTEasy](https://resteasy.dev/)), de modo que desenvolvedores possam implantar (_deploy_) suas aplicações _cloud-native_ Jakarta EE no WildFly;
* [PostgreSQL](https://www.postgresql.org/) é um sistema gerenciador de bancos de dados (SGBD) relacional, compatível com o padrão SQL. Nesta plataforma, é responsável por armazenar os dados do sistema, ou seja, pela persistência das classes de domínio;
* [Maven](https://maven.apache.org/) é uma _"ferramenta de gerenciamento e compreensão de projetos de software"_ muito popular no desenvolvimento Java. A partir de um modelo de objeto do projeto (_project object model_ ou POM) baseado em estruturas padronizadas, o Maven pode compilar, empacotar, implantar, produzir documentação, etc., em outras palavras, construir (_build_) o seu projeto de software Java. O uso do Maven facilita o compartilhamento de projetos com outras pessoas, que conseguirão mais facilmente navegar pelos diretórios do projeto e construi-lo a partir dos padrões desta ferramenta.
## Quando se aplica?
O uso desta plataforma se aplica quando se deseja desenvolver aplicações _cloud-native_ utilizando Java e de forma independente de fornecedor (_vendor neutral_), pois tanto o servidor de aplicação (WildFly) quanto o de banco de dados (PostgreSQL) podem ser substituídos por outros que funcionem dentro do mesmo padrão (Jakarta EE e SQL, respectivamente). Além disso, deseja-se ainda padronizar a estrutura do projeto (com Maven) de modo a facilitar seu entendimento e construção por parte de outros desenvolvedores.
## Como instalar?
Para utilizar esta plataforma, é necessário instalar as ferramentas listadas na tabela abaixo. A coluna **Versão** indica a última versão da ferramenta no momento da escrita desta página do catálogo, porém é possível que as instruções se apliquem também a versões mais recentes destas ferramentas.
**Tecnologia** | **Ferramenta** | **Versão** | **Download**
--------------------- | ---------------------------- | ---------- | ----------------------------------------------------------------
SDK Java | OpenJDK | 19 | [jdk.java.net](https://jdk.java.net/)
Gestão do Projeto | Maven | 3.8 | [maven.apache.org](https://maven.apache.org/download.cgi)
Banco de Dados | PostgreSQL | 15 | [postgresql.org](https://www.postgresql.org/download/)
Servidor Jakarta EE | WildFly Preview Distribution | 27.0 | [wildfly.org](https://wildfly.org/downloads/)
A tabela acima lista apenas o servidor PostgreSQL, sem especificar um _front-end_ para administrá-lo (conectar ao banco, criar usuários, criar _schemas_, etc.). O servidor PostgreSQL pode ser administrado por meio de uma ferramenta de linha de comando chamada `psql`. Caso se deseje uma interface gráfica mais amigável, existem ferramentas que permitem a administração de diversos servidores de bancos de dados diferentes como, por exemplo, o [DBeaver](https://dbeaver.io/download/). A instalação do Windows, no entanto, inclui a ferramenta **pgAdmin**, que pode ser usada para administrar o PostgreSQL.
Além das ferramentas acima, algumas ferramentas como [Git](ferramentas/git), [GitLab](ferramentas/gitlab) e [Slack](ferramentas/slack) são utilizadas por todos os projetos do LabES. Instruções de uso do [GitLab](ferramentas/gitlab) e de instalação do [Git](ferramentas/git) e do [Slack](ferramentas/slack) encontram-se em suas respectivas páginas do catálogo.
A seguir damos algumas dicas de instalação para diferentes plataformas em que já experimentamos. Em seguida, na seção **Como usar/aplicar**, há instruções sugeridas/a serem feitas após a instalação das ferramentas para um bom funcionamento desta plataforma de desenvolvimento.
### MacOs
Recomendamos que desenvolvedores(as) que usam MacOS instalem o gerenciador de pacotes [Homebrew](https://brew.sh/) e se familiarizem com os procedimentos de atualização e instalação de fórmulas (nome dado pelo Homebrew a softwares que podem ser instalados por ele).
A instalação das ferramentas acima no MacOS pode dar-se da seguinte maneira:
- **OpenJDK**: instalar a [fórmula `openjdk` do Homebrew](https://formulae.brew.sh/formula/openjdk);
- **Maven**: instalar a [fórmula `maven` do Homebrew](https://formulae.brew.sh/formula/maven);
- **PostgreSQL**: instalar a [fórmula `postgresql@15` do Homebrew](https://formulae.brew.sh/formula/postgresql@15);
- **WildFly**: obter o arquivo ZIP disponível (link na tabela acima), descompactá-lo e colocar em algum lugar de sua preferência (sugestão: criar uma pasta _Development_ dentro da pasta _Applications_).
### Ubuntu Linux
A instalação das ferramentas acima no Ubuntu Linux pode dar-se da seguinte maneira:
- **OpenJDK**, **Maven** e **WildFly**: obter a versão `.tar.gz` disponível (link na tabela acima), descompactar em um diretório a sua escolha, criar links simbólicos para facilitar e configurar variáveis de ambiente:
> Um diretório comumente escolhido para que todos os usuários da máquina possam usar a ferramenta é o `/opt`. No entanto, é necessário ter acesso de `root` ou `sudo` para usá-lo. Considerando que os arquivos `.tar.gz` encontram-se em `/opt`, os seguintes comandos descompactam os arquivos e criam links simbólicos para facilitar o acesso (os nomes dos arquivos podem mudar dependendo da versão obtida):
>
> ```shell
> cd /opt
> tar -zxf openjdk-19.0.1_linux-x64_bin.tar.gz
> tar -zxf apache-maven-3.8.6-bin.tar.gz
> tar -zxf wildfly-preview-27.0.0.Final.tar.gz
> ln -s jdk-19 jdk
> ln -s apache-maven-3.8.6 maven
> ln -s wildfly-preview-27.0.0.Final wildfly
> ```
>
> Ainda como `root`/`sudo`, vá ao diretório `/etc/profile.d` e crie um arquivo chamado `javadev.sh` (ou qualquer outro nome que preferir, na verdade) com o conteúdo abaixo. Isso configura o diretório _home_ de cada ferramenta e também adiciona Java e Maven ao `PATH` para poderem ser utilizados de qualquer diretório do sistema (passam a valer a partir da próxima ver que o usuário entrar em sua conta):
>
> ```shell
> export JAVA_HOME=/opt/jdk
> export MAVEN_HOME=/opt/maven
> export M2_HOME=/opt/maven
> export WILDFLY_HOME=/opt/wildfly
> export WILDFLY_DEPLOY=$WILDFLY_HOME/standalone/deployments
> export PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin
> ```
>
> Observação: o usuário que irá desenvolver a aplicação nesta plataforma precisará de acesso de escrita ao diretório do WildFly (`$WILDFLY_HOME`) e seus subdiretórios. Se apenas um usuário for usar o WildFly, o mais simples é torná-lo dono dos arquivos, executando como `root`/`sudo` o comando `chown -R usuario:usuario /opt/wildfly*` (substituindo o nome do usuário). Outra solução talvez mais simples seja cada usuário instalar em seu diretório _home_ o WildFly que irá utilizar, não utilizando o diretório `/opt` para o WildFly. Neste caso, o comando `export WILDFLY_HOME=/opt/wildfly` deverá ser adaptado e preferencialmente incluído (juntamente com o comando que define `WILDFLY_DEPLOY`) nas configurações locais de cada usuário (ex.: adicionados ao arquivo `~/.profile`).
- **PostgreSQL**: instalar (como `root`/`sudo`) com `apt install postgresql postgresql-contrib`.
### Windows 10
A instalação das ferramentas acima no Windows 10 pode dar-se da seguinte maneira:
- **OpenJDK**: obter a versão Windows disponível (link na tabela acima), descompactar em algum local (ex.: `C:\Development`), configurar a variável de ambiente `JAVA_HOME` apontando para o diretório da JDK e adicionar `%JAVA_HOME%\bin` ao _PATH_ (fonte: [tutorials24x7.com](https://java.tutorials24x7.com/blog/how-to-install-openjdk-17-on-windows));
- **Maven**: obter a versão binária disponível (link na tabela acima), descompactar em algum local (ex.: `C:\Development`), configurar as variáveis de ambiente `MAVEN_HOME` e `M2_HOME` apontando para o diretório do Maven e adicionar `%M2_HOME%\bin` ao _PATH_ (fonte: [charlesmms.azurewebsites.net](http://charlesmms.azurewebsites.net/2017/09/04/instalando-maven-no-windows-10/));
- **PostgreSQL**: obter o instalador para Windows disponível (link na tabela acima) e executá-lo. Em seguida executar o **pgAdmin** (ou outro _front-end_ à sua escolha) e criar o usuário `labes` e o banco de dados desejado, indicando `labes` como proprietário;
- **WildFly**: obter o arquivo ZIP disponível (link na tabela acima), descompactá-lo e colocar em algum lugar de sua preferência (ex.: `C:\Development`).
O _deploy_ de aplicações construídas com Maven no WildFly pode ser agilizado com o uso de links simbólicos (vide **Implantação no WildFly utilizando links simbólicos**, mais abaixo nesta página), recurso que o Windows não tem suporte (até onde eu saiba). Neste caso, pode ser interessante instalar o Ubuntu dentro do Windows utilizando o [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/pt-br/windows/wsl/install):
1. Abra o menu Iniciar, procure por Windows PowerShell e execute como adminsitrador;
2. Execute o comando `wsl --install`;
3. Ao final da instalação, reinicie o computador conforme instruções;
4. Ao retornar, o Windows vai retomar a instalação, eventualmente iniciar o Ubuntu, pedir pra que você indique um nome de usuário e senha (memorize, este usuário é _sudoer_, i.e., pode agir como `root` a partir do comando `sudo`) e te deixar no terminal do Linux;
5. Siga as instruções para Ubuntu Linux acima para instalar JDK e WildFly (Maven não é necessário, mas pode instalar também se quiser). Para localizar os arquivos `.tar.gz` obtidos pelo navegador Web no Windows, o diretório de downloads do Windows dentro do WSL é `/mnt/c/Users/usuario/Downloads` (substitua `usuario` pelo nome do seu usuário);
6. Use este mesmo caminho (`/mnt/c/Users/usuario/`) para localizar os arquivos do projeto que você obteve do repositório Git e está desenvolvendo. A obtenção do código, abertura na IDE (ex.: [Visual Studio Code](ferramentas/visual-studio-code)) e construção com Maven continua sendo feita no Windows. Apenas o _deploy_ no WildFly seria feito no WSL/Ubuntu (conforme explicado mais abaixo nesta página).
## Como usar/aplicar?
Além dos procedimentos de instalação acima, há algumas configurações que devem ou sugerimos que sejam feitas, bem como dicas para o desenvolvimento nesta plataforma. Seguem também instruções básicas de uso das ferramentas:
### Execução das ferramentas instaladas
Para testar se Java e Maven estão bem instalados, abra um terminal e execute:
```shell
java -version
mvn -version
```
Se você já estiver trabalhando num projeto que use o Maven, na raiz do projeto deve existir um arquivo chamado `pom.xml`. Com o terminal aberto na raiz do projeto, você pode fazer uma construção completa (prepará-lo para implantação) com o comando:
`mvn package`
Para limpar os arquivos gerados pela construção do programa, utilize:
`mvn clean`
Para testar se o WildFly está bem instalado, vá ao diretório `$WILDFLY_HOME/bin` e execute o script `standalone.sh` (`.bat` no Windows). Depois que aparecer mensagens como `WildFly Preview 26.1.2.Final (WildFly Core 18.1.2.Final) started` e `Admin console listening on http://127.0.0.1:9990`. abra um navegador e acesse http://localhost:8080. Para interromper o WildFly, na janela em que estas mensagens de log aparecem, pressione Ctrl+C.
Já para verificar a execução do PostgreSQL, depende do sistema operacional:
- No MacOS, o comando `brew services start postgresql` inicia o PostgreSQL e configura para que seja iniciado automaticamente nas próximas vezes que o computador for ligado. Ao invés de `start`, pode-se usar `run` para iniciar sem configurar reinício automático, `stop` para interromper, `restart` para reiniciar e `status` para saber se está executando;
- No Ubuntu Linux, o comando `sudo systemctl status postgresql.service` deve indicar se o servidor está rodando (substitua `status` por `start`, `stop` e `restart` para gerenciar o serviço);
- No Windows, abra o aplicativo Serviços e procure o PostgreSQL na lista para saber seu status. Selecione o item correspondente para poder gerenciá-lo (iniciar, parar ou reiniciar o serviço).
Para usar o PostgreSQL pela linha de comando no MacOS ou Linux, os passos abaixo podem ser seguidos:
- Entrar na conta do admin do PostgreSQL: `sudo -i -u postgres`;
- Na conta `postgres`, acessar o banco via linha de comando: `psql`;
- Para alterar a senha da conta `postgres` no `psql`: `\password postgres`;
- Para criar um usuário no `psql`: `CREATE USER labes WITH PASSWORD 'labes';`;
- Para criar um _schema_ (banco de dados) no `psql`: `CREATE DATABASE nome_do_banco OWNER labes;`.
Observação: em projetos nesta plataforma, o nome do banco de dados (_schema_) e o login e a senha usados para acessá-lo geralmente encontram-se configurados no arquivo `src/main/webapp/WEB-INF/web.xml` (procure pela _tag_ `<data-source>`).
### Configuração do WildFly
Um _bug_ no WildFly (ao menos nas versões 25 e 26) faz com que o _framework_ que implementa o padrão Jakarta Security não funcione "de fábrica", precisando modificar uma configuração do servidor para que ele passe a funcionar e sua aplicação Web consiga usar este padrão para efetuar autenticação e autorização de usuários.
Se seu projeto não usa Jakarta Security, não é necessário fazer esta etapa. No entanto, recomendamos fazê-la logo após a instalação do WildFly para não ser surpreendido por este bug no futuro e não se lembrar destas instruções.
As instruções, conforme documentado [neste repositório do GitHub](https://github.com/vitorsouza/jakarta-security-example), são as seguintes (considere que `$WILDFLY_HOME` é o diretório onde você instalou o WildFly):
1. Com o servidor desligado, execute `$WILDFLY_HOME/bin/add-user.sh` (`.bat` no Windows) e adicione um usuário administrador (você pode usar o usuário existente `admin`, indicando uma nova senha pra ele);
2. Criado o usuário, execute o servidor por meio do script `$WILDFLY_HOME/bin/standalone.sh` (`.bat` no Windows);
3. Num navegador Web, abra o console de administração do WildFly em [http://localhost:9990/](http://localhost:9990/) e entre com as credenciais do usuário que foi adicionado no primeiro passo;
4. Nos menus do console de administração, acesse _Configuraion > Subsystems > Web > Application Security Domain > Other > View_;
5. Clique no botão _Edit_, modifique o valor do campo _Integrated JASPI_ para _OFF_ e clique em _Save_;
6. Clique no botão _Reload_ para recarregar o servidor.
### Configuração do Visual Studio Code
Caso utilize o [Visual Studio Code](ferramentas/visual-studio-code) para desenvolver projetos nesta plataforma de desenvolvimento (assim como as demais [ferramentas](ferramentas/índice-ferramentas), instruções de instalação do [Visual Studio Code](ferramentas/visual-studio-code) encontram-se em sua página do catálogo), siga as instruções abaixo.
Primeiro, instale os seguintes plug-ins:
- [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) (instruções em [Java in Visual Studio Code](https://code.visualstudio.com/docs/languages/java)).
Depois, faça as seguintes configurações (clicando no botão de configurações -- a engrenagem na parte inferior esquerda da janela):
- `java.format.settings.url` = `https://raw.githubusercontent.com/google/styleguide/gh-pages/eclipse-java-google-style.xml` (configura o formatador do plug-in Java para usar o [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html));
- `editor.formatOnSave`: `true` (faz com que o código seja formatado automaticamente quando for salvo).
### Implantação no WildFly com o Maven
Existe um _plug-in_ do Maven chamado [wildfly-maven-plugin](https://docs.jboss.org/wildfly/plugins/maven/latest/) que permite que a implantação (_deploy_) no WildFly seja feita a partir do Maven. Para utilizá-lo, basta listá-lo em seu `pom.xml` na seção `<project><build><pluginManagement><plugins>` como, por exemplo, no projeto [Marvin](https://gitlab.labes.inf.ufes.br/marvin/marvin/-/blob/main/pom.xml):
```xml
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<version>2.1.0.Beta1</version>
</plugin>
```
Com o plug-in listado, no diretório base do seu projeto e o servidor WildFly executando, você pode fazer a implantação (_deploy_) e reimplantação (_redeploy_) com o comando:
`mvn wildfly:deploy`
Analogamente, para fazer a remoção (_undeploy_) da aplicação no servidor, execute:
`mvn wildfly:undeploy`
### Implantação no WildFly utilizando links simbólicos
Há uma forma mais "manual", porém possivelmente mais rápida, de fazer a implantação de aplicações no WildFly a partir do uso de links simbólicos, portanto funciona apenas no Linux, MacOS ou no WSL dentro do Windows.
Em primeiro lugar, é preciso ter a variável de ambiente `$WILDFLY_DEPLOY` apontando para o diretório `$WILDFLY_HOME/standalone/deployments`, conforme instruções acima para Ubuntu Linux. Caso você use MacOS, pode configurar as mesmas variáveis de ambiente do Linux para o seu usuário do MacOS editando o arquivo `~/.bash-profile`.
Com um terminal aberto (no Linux e no MacOS pode ser o do [Visual Studio Code](ferramentas/visual-studio-code), no Windows deve ser um terminal do WSL), após ter construído a aplicação com o Maven (`mvn package`, como visto acima), primeiro crie uma variável de ambiente temporária que armazena o nome do _build_ seu projeto, indicado na _tag_ `<project><build><finalName>` no arquivo `pom.xml` do seu projeto. Vamos usar como exemplo o [Marvin](https://gitlab.labes.inf.ufes.br/marvin/marvin/-/blob/main/pom.xml):
`export PROJECT=marvin`
Com esta variável definida, os comandos para implantação, remoção, reimplantação, etc. ficam os mesmos, independente do projeto:
- Implantação (_deploy_):
> ``ln -s `pwd`/target/$PROJECT $WILDFLY_DEPLOY/$PROJECT.war``
>
> `touch $WILDFLY_DEPLOY/$PROJECT.war.dodeploy`
- Reimplantação (_redeploy_) se o último _deploy_ falhou:
> `mv $WILDFLY_DEPLOY/$PROJECT.war.failed $WILDFLY_DEPLOY/$PROJECT.war.dodeploy`
- Reimplantação (_redeploy_) se o último _deploy_ foi bem sucedido:
> `mv $WILDFLY_DEPLOY/$PROJECT.war.deployed $WILDFLY_DEPLOY/$PROJECT.war.dodeploy`
- Remoção (_undeploy_) e remoção dos arquivos relacionados:
> `mv $WILDFLY_DEPLOY/$PROJECT.war.deployed $WILDFLY_DEPLOY/$PROJECT.war.undeploy`
>
> `rm -rf $WILDFLY_DEPLOY/$PROJECT.war*`
Pelos comandos acima, nota-se que é possível fazer implantação no WildFly copiando sua aplicação Web para uma pasta de nome `$PROJECT.war` para `$WILDFLY_DEPLOY`. Então, criar um arquivo com o mesmo nome desta pasta e extensão `.dodeploy` faz a primeira implantação. Se bem-sucedida, é criado um arquivo com extensão `.deployed`, se mal sucedida, `.failed` (sempre com o mesmo nome da pasta, só muda a extensão). Renomear a extensão destes arquivos para `.dodeploy` refaz a implantação (_redeploy_) e renomear para `.undeploy` desfaz a implantação (_undeploy_). Os comandos acima apenas automatizam este processo via terminal, que você pode também fazer abrindo a pasta $WILDFLY_DEPLOY no navegador de arquivos do seu sistema operacional.
A grande vantagem desta forma de implantação, no entanto, é quando modificações foram feitas no código Web do projeto (arquivos abaixo de `src/main/webapp`) e não há modificações na parte Java do projeto (arquivos abaixo de `src/main/java` ou `src/main/resources`) a serem testadas. Nestes casos, não é necessário fazer o _redeploy_ da aplicação, que demora um tempo para o servidor WildFly executar. Basta reconstruir a aplicação com `mvn package` e atualizar a página Web que estiver sendo testada.
Se as modificações foram num arquivo específico, você pode copiar apenas este arquivo, o que é ainda mais rápido do que reconstruir toda a aplicação. Por exemplo, para copiar a página `index.xhtml` da raiz da parte Web do projeto para o _build_ do projeto, você pode executar o seguinte comando:
`cp src/main/webapp/index.xhtml target/$PROJECT/`
Uma outra forma de trabalhar é abrir diretamente os arquivos Web no diretório do _build_ (`target/$PROJECT`), fazer as modificações neles, salvá-los e atualizar o navegador. Atenção, no entanto, para ao final do processo copiar as alterações para o arquivo na pasta de código-fonte (`src/main/webapp`), do contrário no próximo _build_ (`mvn package`) você perderá suas alterações!
## Referências
- [Jakarta EE](https://jakarta.ee/);
- [WildFly](https://www.wildfly.org/);
- [PostgreSQL](https://www.postgresql.org/);
- [Maven](https://maven.apache.org/).
## Autores(as)
- @luanaalmeida (formatação);
- @vitorsouza (conteúdo).
\ No newline at end of file