ProgramaDev Blog - RSS Feed

Iniciando com Spring Boot

Thu, 31 Mar 2022 00:00:01 GMT

Introdução

Nesse artigo iremos criar um servidor HTTP utilizando Spring Boot e vamos fazer isso do zero, desde a criação do projeto até a configuração de rotas, verbos HTTP, serialização e desserialização de objetos JSON.

O que é o Spring Boot?

O Spring Boot é um projeto criado pela Pivotal com foco em produtividade, eles perceberam que a maior dificuldade para quem estava criando um projeto novo eram as configurações, tanto de dependências de projeto como da linguagem Java como um todo, o que deixava tudo muito custoso ou frágil a ponto de uma simples alteração quebrar todo o ecossistema daquela aplicação.

Com isso em mente foi criado o Spring Boot que facilita a criação de aplicações independentes, prontas pra rodar na Web pois já vem por padrão com um servidor Tomcat embarcado ou qualquer outro servidor que você queira adicionar sem a necessidade de criar arquivos WAR, além disso aplicações Spring Boot já possuem uma pré-configuração padrão muito bem acabada que atende na maioria dos casos mas caso seja necessário alguma modificação na configuração você não precisará criar arquivos XML que era um outro ponto de falha pois eram complicados de fazer e deixavam os sistemas frágeis e suscetíveis a falhas.

Porém um enorme ganho do Spring Boot é o fato de você conseguir adicionar dependências com grande facilidade bastando adicionar a dependência no projeto e ela já estar disponível para uso, novamente sem precisar criar arquivos verbosos e extensos de configuração.

Para melhor entendimento desse artigo é recomendado que você possua noções de REST e HTTP, caso você não possua poderá acompanhar esse artigo porém alguns conceitos sobre requisições HTTP e REST não serão explicados nesse artigo.

Criando o projeto com Spring Initializr

A Pivotal disponibiliza um site para nos auxiliar a criar uma aplicação com Spring Boot, o Spring Initializr, vamos acessá-lo para criar uma aplicação usando Java 11 e Maven como gerenciador de dependências.

Após isso vamos clicar no botão ADD DEPENDENCIES… e adicionar a dependência SPring Web.

E por fim clicar no botão GENERATE e o projeto será baixado em um .zip

Após isso basta descompactar o arquivo em alguma pasta de sua preferência e abrir com a sua IDE favorita, eu usei o IntelliJ nesse exemplo.

Somente com isso a aplicação já está pronta pra rodar, sem nenhuma configuração necessária da nossa parte, para rodar a aplicação vamos utilizar o comando do maven mvn spring-boot:run no terminal e a saída será:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v2.6.5)

2022-03-28 17:46:38.561  INFO 17452 --- [           main] c.p.webApplication.WebApplication        : Starting WebApplication using Java 17.0.1 on DESKTOP-QSCQPT8 with PID 17452 (C:\Users\guilh\development\repo\webApplication\target\classes started by guilh in C:\Users\guilh\development\repo\webApplication)
2022-03-28 17:46:38.568  INFO 17452 --- [           main] c.p.webApplication.WebApplication        : No active profile set, falling back to 1 default profile: "default"
2022-03-28 17:46:40.311  INFO 17452 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2022-03-28 17:46:40.329  INFO 17452 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-03-28 17:46:40.329  INFO 17452 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.60]
2022-03-28 17:46:40.482  INFO 17452 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-03-28 17:46:40.483  INFO 17452 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1802 ms
2022-03-28 17:46:41.272  INFO 17452 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2022-03-28 17:46:41.293  INFO 17452 --- [           main] c.p.webApplication.WebApplication        : Started WebApplication in 3.505 seconds (JVM running for 4.542)

Caso você não possua o Maven instalado na máquina pode usar o binário que veio junto com o projeto quando criamos no Spring Initializr:

./mvnw spring-boot:run

Perceba que ele iniciou o Tomcat que vem embarcado quando adicionamos a dependência do Spring Web e já está configurado na porta 8080.

Gerenciador de dependências

Estamos utilizando o Maven como gerenciador de dependências, poderíamos utilizar o Gradle sem problema nenhum, se abrirmos o arquivo pom.xml que é onde estão as dependências iremos ver algo do gênero:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.6.5</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>br.com.programadev</groupId>
	<artifactId>webApplication</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>webApplication</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>11</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

Existem várias informações nesse arquivo, porém a que nos interessa é a parte onde temos duas dependências,a primeira do Spring Web e a segunda para testes. Perceba que basta adicionar uma dependência nessa seção e o Maven irá baixar, instalar e o Spring Boot irá plugá-la no projeto.

Para saber onde encontrar dependências para o Spring Boot e projetos Java em geral basta acessar o site do Maven Repository.

Configurando rotas

Agora vamos iniciar com a nossa primeira rota, será um endpoint simples que deve devolver a mensagem HelloWorld. Vou criar uma pasta nova no projeto chamada controller e nela vou criar o arquivo HelloWorld.java.

Você vai perceber que criar uma rota ou qualquer outra configuração é muito mais simples no Spring Boot pois ele utiliza o conceito de usar as Annotations do Java o que deixa mais simples de entender onde as configurações estão.

E para criar uma Controller REST nesse projeto basta adicionar a annotation @RestController que o Spring Boot será capaz de tratar esse arquivo como sendo um endpoint e como ele é especializado em REST por padrão saberá tratar objetos JSON por padrão, tanto pra receber quanto pra devolver nos endpoints.

Outra annotation que iremos adicionar é a @RequestMapping e através dela poderemos configurar qual será a url path que esse controller irá administrar, nesse exemplo será a url /hello:

@RestController
@RequestMapping("/hello")
public class HelloWorld {
}

Agora é necessário que esse controller seja capaz de atender alguma requisição HTTP, como GET, POST e etc. Fazer isso também é muito fácil no Spring Boot e você já deve ter algum palpite que isso será feito com uma annotation.

Vamos criar um mapeamento para o verbo GET que ira devolver a mensagem HelloWorld:

@GetMapping
public String helloWorld(){
    return "Hello World";
}

Pronto o controller está pronto pra uso e vamos subir a aplicação e testar a rota:

curl --location --request GET 'localhost:8080/hello'
Hello World

Pronto a nossa aplicação com Spring Boot está pronta e funcionando.

Trabalhando com JSON

Quando trabalhamos com aplicações REST por padrão trabalhamos com objetos JSON e vamos entender como o Spring Boot lida com esse formato e como trabalhamos com ele.

Explicando rapidamente o que é JSON, é um acrônimo para JavaScript Object Notation e é um estrutura para troca de dados muito leve, de fácil escrita e fácil leitura para humanos. Antigamente haviam outros formatos para comunicação entre sistemas mas eram mais verbosos para escrever e de difícil leitura e interpretação para humanos o que acabava por vezes causando erros que só eram percebidos em tempo de execução.

Mas como o Spring Boot faz para interpretar e transformar um objeto JSON em um objeto Java?

Pra demonstrar como isso é feito no Spring Boot vamos criar um objeto Java e criar outro endpoint para que esse objeto seja mostrado em um GET.

Primeiro criando a classe User:

public class User {                   
                                      
    private String name;              
    private Integer age;              
                                      
    public String getName() {         
        return name;                  
    }                                 
                                      
    public void setName(String name) {
        this.name = name;             
    }                                 
                                      
    public Integer getAge() {         
        return age;                   
    }                                 
                                      
    public void setAge(Integer age) { 
        this.age = age;               
    }                                 
}

Agora vamos criar o endpoint:

@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping
    public User getUser(){
        User user = new User();
        user.setAge(20);
        user.setName("Fulano");
        return user;
    }
}

Note que utilizamos as mesmas annotations @RestController e @RequestMapping porém agora alterando o valor para /user e criamos um método chamado getUser que retorna um User; o que irá acontecer se fizermos um request pra /user? Vamos iniciar o servidor e fazer essa requisição para ver o que acontece:

curl --location --request GET 'localhost:8080/user'

{
    "name": "Fulano",
    "age": 20
}

O próprio Spring Boot através do Spring Web que nós adicionamos no projeto lá no começo é capaz de sozinho entender como manipular e fazer s conversão entre um objeto do Java para um JSON e vice e versa.

Agora vamos ver o outro lado, vamos criar um endpoint para enviar um JSON e transformá-lo em um objeto Java:

@PostMapping
public User postUser(@RequestBody User user){
    return user;
}

O método postUser recebe um objeto Java do tipo User e retorna o mesmo objeto, porém quando vamos fazer o POST não iremos enviar um objeto Java e sim um JSON. Para que seja feita a conversão basta que nós coloquemos a annotation @RequestBody e o Spring Boot será capaz de fazer a conversão por nós.

curl --location --request POST 'localhost:8080/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Beltrano",
    "age": 30
}'

{
    "name": "Beltrano",
    "age": 30
}

Pronto conseguimos manipular e converter objetos JSON com facilidade sem configurações adicionais.

Conclusão

Nesse artigo introdutório ao Spring Boot, vimos como criar um projeto do zero usando a ferramenta do Spring Initializr e entendemos a facilidade que o Spring Boot trouxe para trabalhar com projetos Java uma vez que já vem pré-configurado e também é de fácil configuração e adicionar dependências nele é super fácil bastando adicionar a dependência no gerenciador de dependências, no nosso caso usamos Maven mas também poderia ser Gradle. Também criamos o nosso servidor com Tomcat sem nenhum esforço e mapeamos rotas que recebem e devolvem objetos JSON com uma facilidade incrível, por essas e outras facilidades o Spring Boot ganhou muita força e popularidade.

O código fonte desse artigo você encontra no nosso GitHub

Visite também o nosso canal no Youtube e acompanhe as nossas lives na Twitch

Git para o seu dia a dia

Mon, 21 Mar 2022 00:00:01 GMT

Olá a todos, faz um tempo que não escrevo aqui no blog, os último artigos foram o da série de Java, você pode conferir desde o básico da linguagem até o paradigma de orientação a objetos, porém por hora vou parar com essa série e falar sobre outros conteúdos e tecnologias e para começar irei falar sobre Git e como utilizamos no dia a dia. Git é uma ferramenta fantástica e com muitos recursos porém irei me ater nos pontos que vejo serem mais utilizados no dia a dia de um profissional de tecnologia.

O que é o Git?

O Git é uma solução para essas situações onde o versionamento e repositório de código são necessários, não é a única e nem a primeira ferramenta a fazer isso mas é a mais usada por suas facilidades, segurança e assincronicidade. Foi desenvolvido em 2005 por Linus Torvalds, ele mesmo o criador do kernel do Linux.

Poderia continuar e explicar um monte de detalhes do por que o Git caiu nas graças da comunidade de tecnologia mas o ponto aqui é mostrar como usá-lo no seu dia a dia e como resolver algumas situações que podem ficar um pouco mais complicadas.

Instalação

A instalação do Git é muito fácil e simples, sendo necessário apenas alguns passos.

Para Windows basta baixar o instalador. Para sistemas Linux é possível através de linha de comando por algum gerenciador de pacotes aqui segue a instalação para a maioria das distribuições Linux e para MacOS é possível instalar pelo home brew ou Xcode basta seguir o tutorial

Com o Git instalado vamos utilizá-lo pelo terminal, existem opções gráficas porém vamos focar na linha de comando que é onde passamos a maior parte do nosso dia com o Git.

Iniciando um projeto com Git

Para iniciar o projeto com Git vamos abrir o terminal e criar uma pasta:

mkdir projeto-git && cd projeto-git

Após isso vamos inicializar o Git nessa pasta:

git init

Vai aparecer uma mensagem parecida com isso:

Initialized empty Git repository in <CAMINHO-DA-PASTA>

Pronto, só isso é necessário para iniciar um projeto que terá gerenciamento de versão pelo Git

Configurando usuário e email

Com o projeto Git iniciado vamos antes de mais nada configurar o usuário e email. Isso é importante para que o Git saiba qual usuário está realizando as alterações:

git config --global user.name "Seu nome"
git config --global user.email seuemail@exemplo.br

E depois para confirmar as configurações que foram feitas:

git config --list

user.name=Guilherme Alves
user.email=guilherme.garcia86@gmail.com
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true

Utilizando o GitHub

Antes de continuarmos falando a respeito de Git é importante falarmos sobre GitHub e entender que são duas coisas distintas uma da outra, enquanto o Git é a ferramenta de versionamento de código o GitHub é uma empresa trabalha com o Git para hospedar os seus códigos, existem diversas outas empresas que trabalham com Git como GitLab e Bitbucket cada uma dessas empresas possuem funcionalidades próprias que nos ajudam porém se você usar apenas Git o resultado é o mesmo em todas.

Nesse artigo usaremos o GitHub e vamos mostrar agora como criar uma conta, criar um projeto no GitHub e criar uma chave SSH para podermos enviar o nosso código para lá.

Criar uma conta no GitHub é bem tranquilo, basta acessar o site deles e seguir os passos e após isso você já tem acesso ao dashboard do seu usuário e pode criar seus repositórios, que é a forma como nos referimos aos projetos no Git.

Um último passo é criar um chave SSH para que possamos nos comunicar de forma segura com o GitHub, primeiramente você precisa criar uma chave na sua máquina, se você não sabe como fazer isso segue o link do próprio GitHub de como criar uma chave SSH tanto pra Windows, Mac ou Linux. Feito isso agora podemos ir no GitHub nas configurações (settings):

Estando na tela de configurações, clicar na guia SSH and GPG keys, no meu caso já possuo algumas chaves configuradas:

Depois clicar no botão New SSH Key:

Nos campos que apareceram, basta adicionar um título para sua chave SSH e colar o conteúdo da chave foi gerada e clicar em Add SSH key.

Pronto a chave foi configurada com sucesso e agora você consegue baixar ou enviar seus códigos para os seus repositórios no GitHub.

Criando repositórios no GitHub

Agora vamos criar o nosso repositório no GitHub, o mesmo que iniciamos localmente no início do artigo, para isso vamos ao dashboard do seu usuário no GitHub e clicar no botão New na parte de Repositories:

Após isso vamos adicionar o nome do projeto, manter as configurações de projeto como público e não selecionar mais nada para que seja criado um repositório vazio para nós e clicar em Create Repository.

Pronto com isso o projeto foi criado no GitHub e está pronto para uso.

Branch

O Git trabalha bastante com o conceito de branches que são as ramificações a partir de uma fonte de código, para entender melhor vamos imaginar que o Git é como uma árvore e o tronco dessa árvore é código de alguma aplicação que você está trabalhando:

Essa árvore possui galhos, ou ramificações, saindo do tronco, é a mesma coisa com as branches elas são ramificações que saem de uma parte principal e com isso temos uma cópia do código porém sem afetar a raiz do repositório. O ganho disso é rastreabilidade de saber o que foi feito, por quem foi feito e com isso podemos desfazer alterações de forma mais simplificada se for necessário.

Cada branch possui um nome e geralmente a branch principal se chama main, no passado era comum se chamar master mas este nome caiu em desuso por ser um termo racista, a partir da branch main conseguimos criar outras branches com o seguinte comando:

git checkout -b develop

Com o comando acima eu realizo a operação de checkout para que eu saia da branch atual e vá para outra que será informada, o parâmetro -b é para criar uma branch que não existe no momento do checkout e por fim develop é só um nome qualquer que eu dei para a branch, poderia ser qualquer nome de sua preferência.

Adicionando arquivos no projeto

Após criarmos o projeto GIT agora é hora mostrar como criar um arquivo e adicionar ao GIT.

touch helloWorld.txt

Esse comando irá criar um arquivo pelo terminal do Linux, caso você esteja usando Windows basta criar um arquivo pela interface gráfica.

Com isso o arquivo já passa a ser gerenciado pelo GIT, se quisermos saber o estado das alterações basta executar o comando git status:

git status
On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	helloWorld.txt

nothing added to commit but untracked files present (use "git add" to track)

O resultado desse comando basicamente diz em qual branch o GIT está, veremos o que é isso em breve, se existe algum commit, também veremos em breve isso e que existem arquivos que não são rastreáveis, nesse caso o arquivo helloWorld.txt e termina dando o comando que podemos usar para adicionar esses arquivos para serem gerenciados pelo GIT, o comando git add arquivo faz isso para nós:

git add helloWorld.txt

Também é possível não especificar o arquivo e pedir para que toda alteração seja adicionada:

git add .

O . (ponto) diz para adicionar tudo o que não estiver rastreado pra o GIT.

Commit

Após adicionar os arquivos desejados no projeto usando GIT é necessário enviá-los para algum lugar, pois até o momento nós só adicionamos os arquivos para serem monitorados pelo GIT mas eles continuam somente no seu computador o que pode ser perigoso já que muitas vezes em uma mesma branch pode haver mais de uma pessoa trabalhando ou até mesmo qualquer outro incidente pode acontecer no seu computador e você perder todo o trabalho realizado.

O comando commit do GIT não irá enviar suas alterações para um repositório na nuvem, ex.: GitHub, mas ele é capaz de salvar o estado atual do seu projeto, ele é como um comando Crtl+S que manda salvar a alteração localmente.

Vamos adicionar algum conteúdo ao nosso arquivo helloWorld.txt para que o GIT perceba a alteração e com isso possamos salvar essas alterações com o comando commit:

#helloWorld.txt
Olá Mundo!!!

Vamos adicionar a alteração no GIT:

git add .

E agora vamos salvar a alteração, perceba que é necessário adicionar um título para essa alteração através do parâmetro -m:

git commit -m "Primeiro Commit"

Fazendo isso a saída no terminal será parecida com isso:

[master (root-commit) f447135] Primeiro Commit
 1 file changed, 1 insertion(+)
 create mode 100644 helloWorld.txt

E se quisermos mais detalhes sobre os commits feitos podemos utilizar o comando git log que trás todos os commits feitos no projeto:

commit f447135cc39f81a090e9bbbc91c45bbdbbbbd928 (HEAD -> master)
Author: Guilherme Alves <guilherme.garcia86@gmail.com>
Date:   Tue Mar 8 09:18:31 2022 -0300

    Primeiro Commit

Nesse exemplo como só tem um commit só trouxe essa informação mas um ponto interessante de notarmos é que todo commit possui um hash único isso existe para que seja possível navegar entre commits ou até mesmo ser mais fácil o rollback de versões.

Push

Após fazer o commit e salvar as alterações localmente é necessário enviar essas alterações para o repositório na nuvem, GitHub no nosso exemplo, porém o comando é o mesmo para qualquer repositório que você esteja trabalhado.

Para fazer o envio usamos o comando push, empurrar em inglês, mas antes disso vamos aproveitar para terminar a configuração do GIT, começando pelo nome da branch, por padrão o nome ainda é master, mas como foi dito anteriormente esse nome foi depreciado por ser racista, então vamos renomear para main conforma abaixo:

git branch -M main

Agora vamos configurar a url do repositório no GitHub no projeto local:

git remote add origin git@github.com:guilhermegarcia86/projeto-git.git

E por fim o comando push que irá enviar para o repositório na nuvem:

git push

E a saída no terminal será parecido com isso:

Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 240 bytes | 240.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/guilhermegarcia86/projeto-git.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Sincronizando o seu projeto localmente

Agora pensando que outras pessoas estarão desenvolvendo na mesma branch como fazemos para sincronizar o nosso trabalho com o delas? Antes de falar sobre isso é importante saber algumas coisas sobre como o GIT sincroniza e saber o estado mais atual do projeto, a cada commit é gerado um hash único além das informações sobre o autor do commit, data e hora. E com essa informações o GIT tem condições de saber se o seu projeto local está atualizado ou se está a frente ou atrás em relação ao repositório na nuvem. Por isso caso o repositório na nuvem estiver a frente e você tentar fazer um comando git push o comando irá falhar com uma mensagem parecida com isso:

 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/guilhermegarcia86/projeto-git.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

A informação basicamente diz que não foi possível enviar a sua alteração pois no repositório remoto (nuvem) contém atualizações que você não tem, isso é de extrema importância pois imagine se eu estiver fazendo alterações no mesmo arquivo que a pessoa que fez um commit e como isso seria resolvido pelo GIT? Por isso na própria mensagem de erro já vem com uma dica de que é necessário atualizar primeiramente o se projeto com as alterações da nuvem e resolver possíveis conflitos pra depois subir as suas alterações.

Para atualizar o seu projeto e deixá-lo sincronizado com o repositório remoto, basta executar o comando pull para que trazer as atualizações:

git pull

Conclusão

Esses foram o comandos básicos para começar a entender e trabalhar com o GIT. No dia-a-dia de uma pessoa que usa o GIT como versionador de códigos esses comandos provavelmente serão os mais utilizados. Porém existem outras situações que veremos mais a frente, que será a resolução de conflitos quando fizermos a sincronização do projeto, podemos usar tags e podemos também reverter commits, esse são tópicos um pouco avançados e iremos vê-los nos próximos artigos.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java X

Fri, 10 Dec 2021 00:00:01 GMT

Tratamento de erros antigamente

Em linguagens mais antigas o tratamento de erros tinha que feito de maneira mais manual pois não existia por padrão na linguagem um mecanismo para lidar com essas situações, o que era feito em muitas situações era retornar um booleano que representasse se a chama a algum método foi executada com sucesso ou não, como no exemplo abaixo:

public static boolean metodo(){
    
    //Simulando condição que poderia causar um problema no código
    boolean condicao = true;
    if(condicao){
        //Retorno false para indicar que algo não ocorreu bem
        return false;
    }
    
    //Retorno true para informar que tudo ocorreu bem
    return true;
}

O problema dessa abordagem é que o retorno de uma chamada a um método pode ser ignorado e então a eficácia fica prejudicada, tirando o fato que retornar um booleano não informa nada a respeito de qual foi o problema que ocorreu, se foi falta de memória, falha na lógica ou qualquer outra situação.

A segunda abordagem para tentar ser mais informativa era ter um método que retornava um código de erro, geralmente um numérico, e a partir dele buscar qual foi o problema:

public static int metodo() {
    
    String problema = "banco_de_dados";
    
    switch (problema){
        case ("banco_de_dados"):
            return 233;
        case ("falta_de_memoria"):
            return 567;
        case ("problema_de_comunicacao_externa"):
            return 421;
        default:
            //Problema desconhecido
            return 1;
    }
}

No código acima o método simula um problema de comunicação com o banco de dados e retorna o código 233, o problema do retorno ser ignorado permanece porém mesmo que seja feito uma tratativa do retorno agora será necessário ter um dicionário de erros para fazer a consulta e entender o erro que foi retornado. Para resolver esse problema no Java foi criado o mecanismo de Exceptions.

O que é uma Exception

Quando desenvolvemos aplicações e códigos em linguagens compiladas, como é o caso do Java, o compilador força escrevermos linhas de códigos que contenham a sintaxe correta que a linguagem exige, porém o compilador é incapaz de verificar a lógica que está sendo aplicada, por exemplo se executarmos um programa e em algum ponto tentarmos acessar uma variável que seja nula a execução do programa será interrompida e será exibida uma mensagem que irá conter a seguinte informação: java.lang.NullPointerException ou se tentarmos executar um programa que tenha um loop infinito porém com uma sintaxe correta o compilador não irá avisar e ao executar o programa em algum momento o programa irá ser interrompido e será exibida uma mensagem que contenha o seguinte: java.lang.StackOverflowError.

A primeira mensagem diz respeito a uma Exception e a segunda diz respeito a um Error, é importante entender essa diferença da linguagem.

Uma Exception é uma situação anormal dentro do seu programa, causada por alguma falha de lógica, ou seja por alguma falha no processo de construção do programa, onde por mais que a sintaxe esteja certa o problema ocorre pela forma como o programa será executado, como no exemplo de um NullPointerException onde a sintaxe está correta porém a lógica não está; para ficar claro vamos ver o código abaixo utilizando a mesma aplicação bancária que estamos desenvolvendo ao longo desses artigos:

Conta guilherme = new PessoaFisica("Guilherme");

guilherme = null;

System.out.println(guilherme.getNome());

O código acima irá compilar sem problema porém ao executar será lançada a Exception pois tentamos executar um método de uma variável que é nula.

Um Error no Java é um problema que ocorre em partes onde nós como desenvolvedores de software não deveríamos ter acesso, como por exemplo a JVM ou o gerenciamento de memória, são problemas que ocorreram ou por uma falha interna da linguagem e sendo o caso deve ser corrigido em alguma versão futura ou então são problemas que ocorrem pois alguma lógica causou um problema interno, como no exemplo de um loop infinito, resumindo são problemas que nós como desenvolvedores não iremos atuar a não ser no segundo caso onde podemos corrigir a lógica.

Para ficar mais claro essa distinção entre Exception e Error segue o diagrama de hierarquia de classes:

Throwable é a mãe tanto de Exceptions quanto de Errors, podemos ver no diagrama acima que tanto a classe Exception quanto Error possuem subclasses, isso ocorre através da Herança onde para cada problema existe uma especialização para tratá-lo, essa é uma boa prática pois fica mais claro para a pessoa que ira corrigir o problema conseguir o máximo de detalhes do problema, por essa razão é considerado uma má prática trabalhar diretamente com Throwable pois além de ser uma classe genérica ela também lida com as sub-classes de Error e como dissemos anteriormente os problemas que lançam Error no Java são situações irrecuperáveis que os desenvolvedores não devem lidar no dia-a-dia.

Fora isso existe um outro ponto quando falamos de Exceptions que podemos ver no diagrama que é a sub-classe RuntimeException, é importante saber que essa classe tem um comportamento diferenciado das outras Exceptions, que iremos entender mais abaixo, que é a capacidade de ser uma exceção que pode ser ignorada e não tratada pois se trata de uma Unchecked Exception e iremos entender a diferença entre Checked e Unchecked Exceptions.

Lançando Exceptions

Antes de entender Checked e Unchecked Exceptions vamos ver primeiramente como lançar exceções; voltando para a aplicação bancária imagine o que iria acontecer se alguém tentar sacar um valor maior do que tem no saldo, imaginando que não existe nada referente a limites adicionais para essa conta, esse comportamento é algo que é anormal para a regra de negócio desse programa e queremos que a execução dele pare e o usuário que tentou fazer essa operação seja notificado.

public BigDecimal saca(BigDecimal quantidade) {
    if(quantidade.compareTo(saldo) > 0){
        //Valor do saque é maior do que o saldo
        System.out.println("Você não pode sacar esse valor");
    }
    this.saldo = this.saldo.subtract(quantidade);
    return quantidade;
}

O método compareTo da classe BigDecimal compara valores e retorna 0 caso sejam iguais, 1 se for o valor quantidade, nesse caso, for menor do que o saldo e -1 se o valor da quantidade for maior do que o saldo, se executarmos passando um valor maior que o saldo uma mensagem será exibida, porém o código prosseguirá e será sacado o valor deixando o saldo negativo, com o mecanismo de Exceptions podemos interromper o método e devolver uma mensagem informativa de que algo não ocorreu bem.

public BigDecimal saca(BigDecimal quantidade) {
    if(quantidade.compareTo(saldo) > 0){
        //Valor do saque é maior do que o saldo
        throw new Exception("Valor do saque é maior do que o seu saldo");
    }
    this.saldo = this.saldo.subtract(quantidade);
    return quantidade;
}

Agora o código foi alterado e estamos criando um objeto Exception passando a mensagem no seu construtor, só criar um objeto com new não é o suficiente para que a Exception seja disparada, ou lançada como é o termo usado para esses casos, para isso o Java conta com a palavra throw, lançar em inglês, que fará com que a Exception seja lançada fazendo com que o código seja interrompido.

Se voc6e tentou fazer esse exemplo deve ter percebido que o código não compilou, isso acontece pois quando escrevemos uma clausula throw é necessário indicar ou marcar o método como sendo um método que “perigoso” que pode vir a lançar uma Exception; para isso é necessário adicionar após a declaração dos parâmetros a palavras throws seguido da Exception que pode ser lançada pelo método:

public BigDecimal saca(BigDecimal quantidade) throws Exception {
    if(quantidade.compareTo(saldo) > 0){
        //Valor do saque é maior do que o saldo
        throw new Exception("Valor do saque é maior do que o seu saldo");
    }
    this.saldo = this.saldo.subtract(quantidade);
    return quantidade;
}

Porém esse método ainda não vai compilar nessa aplicação e isso tem a ver com com o fato do método saca ser herdado da classe abstrata Conta e nesse caso teremos que adicionar essa mesma declaração na classe Conta:

public BigDecimal saca(BigDecimal quantidade) throws Exception {
    System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
    return quantidade;
}

E ainda falta um último ajuste que é adicionar essa clausula no próprio método main, agora o método compila e se executarmos da seguinte forma:

public static void main(String[] args) throws Exception {

    Conta guilherme = new PessoaFisica("Guilherme");

    guilherme.saca(new BigDecimal("2000"));
}

A saída será a seguinte:

APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE
SAQUE PARA PESSOA Guilherme COM DOCUMENTO CPF
Exception in thread "main" java.lang.Exception: Você não pode sacar esse valor
	at br.com.company.artigox.PessoaFisica.saca(PessoaFisica.java:22)
	at br.com.company.artigox.Main.main(Main.java:11)

Na saída do console fica explícito que houve uma Exception informando em qual thread ocorreu, qual o tipo dessa Exception, a mensagem customizada e se continuarmos lendo a pilha de log é informado qual foi o método que ocorreu a Exception e como ele foi subindo a pilha de execução até chegar no método main e não havendo nenhuma tratativa o programa encerrou.

Para entender essa pilha de execução e por que foi necessário colocar a clausula throws Exception no método main vamos ver adiante como tratar Exceptions.

Tratando Exceptions

Você já viu como lançar uma Exception porém não queremos que toda exceção pare a execução do programa, as vezes queremos contornar o problema e para isso podemos fazer uso de blocos try-catch, para isso vamos adicionar uma nova funcionalidade na Conta, que é a capacidade de realizar transferências e para essa funcionalidade iremos reaproveitar os métodos saca e deposita, onde iremos ter a conta que irá fazer a transferência, a conta que irá receber e a quantidade da transferência, porém o método saca pode lançar uma Exception caso o valor do saldo não seja suficiente e queremos que para esse caso se o valor não for suficiente será liberado um crédito para essa transação, vamos ver agora como fazer isso:

public void transfere(Conta de, Conta para, BigDecimal quantidade) {

    BigDecimal valor;
    try {
        valor = de.saca(quantidade);
        System.out.println("Valor da transferência %s".formatted(valor));
    } catch (Exception e) {
        //Libera limite especial para transferencias
        System.out.println("Executando código para se recuperar da Exception");
        valor = quantidade;
    }

    para.deposita(valor);
}

Aqui estamos usando o bloco try-catch para fazer o tratamento de um Exception, explicando por partes temos primeiramente o bloco try esse bloco irá lidar com métodos ou trechos de códigos que podem lançar uma Exception e como o nome dele diz try ou tente em tradução direta, irá tentar executar o método saca porém sabendo que pode haver algum imprevisto, se ocorrer uma Exception o bloco try para e “pula” para o bloco catch que antes de ser executado irá fazer a comparação do tipo da Exception lançada com o tipo da Exception que o bloco catch trata se corresponderem o bloco será executado e se no bloco try não ocorrer nenhuma Exception o bloco é finalizado porém o bloco catch nunca será executado e o método continua. Uma ultima coisa que podemos ver é que quando tratamos o erro com um bloco try-catch não é necessário fazer a declaração throws no método, ela só se faz necessária quando não tratamos o possível lançamento da exceção pois nesse caso quem deverá tratar é quem chama o método que pode lançar a Exception e se este não tratar deve declarar throws para que o próximo faça o tratamento, e isso vai subindo na pilha de execução dos métodos até chegar no método main que é o método principal de execução de uma aplicação Java se a Exception não for tratada lá e ocorrer uma Exception o programa vai exibir no console a mensagem da Exception juntamente com o log da pilha de execução e vai terminar.

Agora executando esse código para que seja lançada uma Exception:

public static void main(String[] args) {

    Conta guilherme = new PessoaFisica("Guilherme");

    Conta destino = new PessoaFisica("Conta de Destino");

    guilherme.transfere(guilherme, destino, new BigDecimal("2000"));
}

Perceba que tiramos a declaração throws Exception pois o método transfere já faz a tratativa e quando o código é executado a saída contém:

Executando código para se recuperar da Exception

Não foi executado o print de console que existe após a chamada do método saca pois foi lançado uma Exception e isso interrompeu o fluxo do bloco try que passou para o bloco catch que executou e depois prosseguiu o fluxo do método normalmente.

Foi dito anteriormente que o catch faz checagem se o tipo da Exception lançada é do mesmo tipo que está no bloco catch e isso acontece para que possamos tratar múltiplas Exceptions em um mesmo bloco try-catch, mas para ver isso vamos aprender primeiro como criar as nossas próprias Exceptions.

Criando Exceptions customizadas

Aqui vamos aprender a criar nossas próprias Exceptions, tratar multiplas Exceptions e entender a diferença entre Checked e Unchecked Exceptions.

Primeiramente por que é necessário criar Exceptions customizadas já que existem muitas Exceptions prontas no Java?

Pra responder essa pergunta devemos olhar para a nossa aplicação e entender que tipo de problemas podemos ter no método saca, o método saca pode ter o problema de não haver saldo suficiente porém quando ocorre um problema desse nós tratamos como se fosse uma Exception, uma generalização que não explica muito bem o que ocorreu se não fosse a mensagem que passamos, se olharmos as outras classes de Exceptions vamos entender que elas lidam com aspectos de programação voltados a utilização de recursos como leitura/escrita de arquivos, carregamento de classes na memória, comunicação com serviços externos mas nenhuma delas foi feita para lidar com regras de negócios de projetos, isso foi pensado para que cada projeto pudesse ter a flexibilidade de criar as suas próprias Exceptions. Então dado o nosso cenário podemos criar uma Exception como SaldoInsuficienteException e para fazer isso usaremos Herança para criar essa Exception:

public class SaldoInsuficienteException extends Exception{
    
    public SaldoInsuficienteException(String msg){
        super(msg);
    }
}

Fazendo isso já temos a classe de Exception criada, perceba que herdamos da classe Exception e usamos um construtor para invocar a classe-mãe passando a mensagem de erro e podemos substituir em nosso código:

public BigDecimal saca(BigDecimal quantidade) throws SaldoInsuficienteException {
    if(quantidade.compareTo(saldo) > 0){
        //Valor do saque é maior do que o saldo
        throw new SaldoInsuficienteException("Você não pode sacar esse valor");
    }
    this.saldo = this.saldo.subtract(quantidade);
    return quantidade;
}

E se executarmos o código com um valor maior que o saldo:

Exception in thread "main" br.com.company.artigox.SaldoInsuficienteException: Você não pode sacar esse valor
	at br.com.company.artigox.PessoaFisica.saca(PessoaFisica.java:22)
	at br.com.company.artigox.Main.main(Main.java:15)

A mensagem do erro é mais indicativa ao desenvolvedor que ler esse log pois além da mensagem que foi passada o próprio nome da Exception é indicativo.

Agora temos uma Exception customizada e específica criada e com isso podemos fazer o tratamento de múltiplas exceções com um bloco try-multi-catch:

public void transfere(Conta de, Conta para, BigDecimal quantidade) throws Exception {

    BigDecimal valor;
    try {
        valor = de.saca(quantidade);
        System.out.println("Valor da transferência %s".formatted(valor));
    } catch (SaldoInsuficienteException e) {
        //Libera limite especial para transferencias
        System.out.println("Executando código para se recuperar da Exception");
        valor = quantidade;
    }catch (Exception e) {
        //Erro não previsto
        throw new BusinessException("Problema inesperado no método transfere");
    }

    para.deposita(valor);
}

Entendendo o código acima, no bloco try tentamos executar o método saca e se houver alguma exceção do tipo SaldoInsuficienteException será executado o bloco catch correspondente ou se qualquer outra exceção ocorrer, pelo fato de todas as exceções serem sub-classes de Exception, será re-lançada como uma BusinessException, que tem o mesmo padrão da SaldoInsuficienteException, com uma mensagem mais amistosa.

*Obs: Essa é uma técnica para que a exceção seja manipulada mas continue sendo lançada, provavelmente para adicionar logs importantes ou até mesmo mudar o tipo da exceção lançada.

Além dessa forma também existe uma outra forma de tratar exceções para que o código não fique verboso, que é o aninhamento de exceções em um bloco catch:

BigDecimal valor;
try {
    valor = de.saca(quantidade);
    System.out.println("Valor da transferência %s".formatted(valor));
} catch (SaldoInsuficienteException | BusinessException e) {
    //Libera limite especial para transferencias
    System.out.println("Executando código para se recuperar da Exception");
    valor = quantidade;
}

Nesse caso se ocorrer uma exceção do tipo SaldoInsuficienteException ou BusinessException o tratamento será o mesmo, isso poupa linhas de código e deixa o código mais semântico mas pode ser perigoso pois será a mesma trativa para as exceções declaradas e as vezes não é isso o que queremos.

Porém agora podemos nos perguntar sobre o seguinte, cada método que chamar o método saca tem duas possibilidades ou trata uma possível Exception ou delega para o próximo método, não existe alternativas quando trabalhamos com classes que herdam de Exception, porém existem situações em que o melhor não seria que o programa se recuperasse, talvez fosse melhor ele “quebrar” mas que contenha informações relevantes sobre o motivo se sua interrupção. E para isso existe o conceito de Checked e Unchecked Exceptions.

Começando pelas Checked Exceptions, são as que nós estamos trabalhando desde o início do artigo, são todas as que são sub-classes de Exception, esse tipo de exceção obriga o desenvolvedor a tratar a Exception ou lançar para a próxima chamada a responsabilidade, como vimos nos exemplos anteriores. A ideia por detrás dela é que são situações que o desenvolvedor pode contornar em fluxo lógico, como foi o exemplo do método transfere que era um situação onde mesmo estourando uma Exception havia um desvio lógico possibilitando que o código prosseguisse.

As Unchecked Exceptions são o oposto, são situações onde não queremos que uma atitude seja tomada, se por acaso ocorrer um problema estamos satisfeitos com o fato do programa encerrar mas queremos ter o máximo de informações possíveis para entender o que ocorreu; por essa razão são exceções que não precisam de um try-catch e nem somos obrigados a tratar ou delegar para a próxima chamada tratar. Pensando nisso vamos alterar a classe SaldoInsuficienteException pois se pensarmos bem se o saldo for insuficiente não queremos tratar isso no método saca, queremos que o fluxo seja interrompido e que seja impresso no log o máximo de informações possíveis a respeito do que ocasionou essa falha.

Mas o que precisamos alterar para tornar uma Checked Exception em Unchecked Exception?

Olhando novamente o diagrama de classes das Exceptions podemos encontrar:

Podemos ver na hierarquia que as classes NullPointerException, ArrayIndexOutOfBounds, ArithmeticException entre outras são sub-classes de RuntimeException, ora quando um erro do tipo NullPointerException é lançado não devemos realizar uma tratativa do tipo try-catch para recuperar a aplicação, nós geralmente olhamos o código e encontramos onde está uma referência nula e arrumamos e nem o compilador reclama quando fazemos uma conta dividindo por 0 que causará uma ArithmeticException, só somos avisado da falha no momento de execução do programa ou em Runtime e é por isso que erros do tipo RuntimeException não serão verificados pelo compilador para que sejam tratados, logo para transformar uma Checked Exception em Unchecked Exception basta herdar de RuntimeException ao invés de Exception:

public class SaldoInsuficienteException extends RuntimeException{

    public SaldoInsuficienteException(String msg){
        super(msg);
    }
}

Foi somente essa mudança e com isso podemos alterar o método saca e retirar a declaração throws SaldoInsuficienteException no método e o compilador não irá reclamar mais. E podemos no método saca adicionar informações importantes para gerar a mensagem de erro:

public BigDecimal saca(BigDecimal quantidade) {
    if(quantidade.compareTo(saldo) > 0){
        throw new SaldoInsuficienteException("Saldo insuficiente em conta: %s - Valor do saque: %s".formatted(this.saldo, quantidade));
    }
    this.saldo = this.saldo.subtract(quantidade);
    return quantidade;
}

E se executarmos de uma forma que sabemos que a exceção será lançada:

public static void main(String[] args) {

    Conta guilherme = new PessoaFisica("Guilherme");

    guilherme.saca(new BigDecimal("2000"));
}

Note que não precisamos mais passar a declaração throws SaldoInsuficienteException e nenhum ponto do código e a saída no console será:

Exception in thread "main" br.com.company.artigox.SaldoInsuficienteException: Saldo insuficiente em conta: 1000 - Valor do saque: 2000
	at br.com.company.artigox.PessoaFisica.saca(PessoaFisica.java:21)
	at br.com.company.artigox.Main.main(Main.java:15)

Finally

Como estamos falando sobre blocos try-catch faz sentido falarmos sobre o bloco finally. Este bloco é opcional dentro do bloco try-catch mas muito útil quando queremos que alguma ação tomada independente de uma Exception será lançada ou não.

Para demonstrar o uso do finally vamos imaginar um cenário hipotético onde a nossa aplicação fará acesso ao banco de dados e independente de ocorrer nós queremos que a conexão com o banco seja fechada ao fim do método, pois operações de comunicação com outros serviços consomem muito da capacidade computacional, e queremos garantir que mesmo em um cenário de falha a conexão será fechada. Para demonstrar isso vamos ver o código abaixo:

public void conectaBancoDeDados() throws BusinessException {

    try{
        System.out.println("Conectando...");
        throw new SQLException("Problemas na conexão");
    }catch (SQLException e){
        throw new BusinessException("Problema na conexão com o banco de dados: %s - %s".formatted(e.getClass().getName(), e.getMessage()));
    }finally {
        System.out.println("Fechando conexão com o banco");
    }

}

A parte do bloco try-catch não sofreu alteração a única coisa que foi acrescentada foi o bloco finally após o bloco catch, e se entendermos o código acima vamos perceber que no bloco try é lançada uma exceção do tipo SQLException passando a mensagem Problemas na conexão e na sequência o bloco catch captura essa exceção e faz manipulação para uma exceção do tipo BusinessException, onde encapsulamos a exceção original mas conseguimos extrair algumas informações importantes da exceção original pois o bloco catch recebe uma variável com a instância da SQLException e conseguimos pegar alguns dados como o nome da classe, a mensagem original entre outras coisas. E por fim o bloco finally executa e irá exibir a mensagem no console Fechando conexão com o banco mesmo que no bloco catch tenha sido lançado um exceção, se rodarmos essa código teremos a seguinte saída:

Conectando...
Fechando conexão com o banco
Exception in thread "main" br.com.company.artigox.BusinessException: Problema na conexão com o banco de dados: java.sql.SQLException - Problemas na conexão
	at br.com.company.artigox.Main.conectaBancoDeDados(Main.java:20)
	at br.com.company.artigox.Main.main(Main.java:10)

Então entendemos com isso que se houver ou não um lançamento de exceção o bloco finally sempre será executado e isso é muito útil em cenários onde queremos ter a garantia de uma ação independente de qualquer falha que possa ocorrer. E isso é tão útil que podemos ter até mesmo blocos try-finally sem que aja um catch pois até mesmo tomando o exemplo do código acima, nós não chegamos a fazer uma tratativa de erro, só envelopamos e uma exceção customizada e lançamos pra cima, então nesse caso podemos fazer da seguinte maneira, se não quisermos tratar a exceção mas garantir o fechamento da conexão com o banco:

public static void conectaBancoDeDados() throws SQLException {

    try{
        System.out.println("Conectando...");
        throw new SQLException("Problemas na conexão");
    }finally {
        System.out.println("Fechando conexão com o banco");
    }
    
}

Esse é bloco válido e se executarmos o resultado será:

Conectando...
Fechando conexão com o banco
Exception in thread "main" java.sql.SQLException: Problemas na conexão
	at br.com.company.artigox.Main.conectaBancoDeDados(Main.java:17)
	at br.com.company.artigox.Main.main(Main.java:10)

O que mudou foi a exceção que foi exibida e esse tipo de abordagem vai depender e variar muito de acordo com o tipo de exceção e de regra para tratamento de exceções que você como pessoa desenvolvedora estiver trabalhando.

Try with Resources

Uma novidade que veio a partir do Java7 foi a possibilidade de executarmos o finally automaticamente, pois não era raro a pessoa que estava desenvolvendo esquecer de adicionar o bloco finally e pensando em uma situação de conexão com um banco de dados por exemplo não iria ocorrer um erro logo a princípio mas a cada nova conexão com o banco iria aumentando o número de conexões abertas que não iriam ser fechadas nunca até o ponto que o banco não suportasse mais a quantidade de conexões abertas e o erro iria ocorrer na aplicação, mas nem sempre isso era rápido de ocorrer e quando o erro fosse notado já poderia ser tarde demais e usuários já estariam usando a aplicação e sendo ela quebrando, pensando nisso foi adicionada essa nova funcionalidade.

Para fazer uso do try-with-resources é necessário que a classe que tenha o método que será executado no try implemente a interface AutoCloseable, para ilustrar isso vamos criar uma classe de conexão ao banco de dados, como no exemplo anterior, e implementar essa interface:

public class ConexaBD implements AutoCloseable{

    public void conectaBanco() throws SQLException {
        System.out.println("Conectando...");
        throw new SQLException("Erro na conexão");
    }

    @Override
    public void close() throws SQLException {
        System.out.println("Fechando conexão");
    }
}

A interface AutoCloseable nos obriga a implementar o método close que será invocado ao fim da execução da classe ConexaoDB, o método close lança uma Exception mas nesse caso foi alterado para SQLException já que uma SQLException é também uma Exception por herança.

Para usar o try-with-resources basta que criemos a instância dentro do bloco try, vamos ver no exemplo para esclarecer:

try (ConexaBD conexaBD = new ConexaBD()) {
    conexaBD.conectaBanco();
} catch (SQLException e) {
    System.out.println("Problema na conexão com o banco de dados: %s - %s".formatted(e.getClass().getName(), e.getMessage()));
}

Perceba que após o try abrimos parenteses e criamos um objeto do tipo ConexaoDB, lembrando que isso só será possível se a classe implementar a interface AutoCloseable, e dentro do bloco utilizamos normalmente o método conectaBanco, após isso fazemos o tratamento da possível exceção que pode ser lançada e só, não foi adicionado o bloco finally, porém na classe ConexaoDB possui o método close e ele será invocado ao final do bloco try-catch independente de uma exceção ser lançada ou não:

Conectando...
Fechando conexão
Problema na conexão com o banco de dados: java.sql.SQLException - Erro na conexão

Conclusão

Vimos nesse artigo mas motivações que causaram a criação de Exceptions no Java, também foi mostrado a hierarquia de classes de exceções. Entendemos como utilizar as Exceptions que já existem na linguagem e como criar as nossas exceções customizadas. Como podemos tratá-las através do bloco try-catch e como podemos fazer vários blocos catch ou então blocos aninhados.

Por fim entendemos a diferença entre Checked e Unchecked Exceptions e qual escolher em cada caso, como usar o bloco try-catch-finally, try-finally e como podemos usar o recurso que foi adicionado no Java7, o try-with-resources juntamente com a interface AutoCloseable.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java IX

Tue, 30 Nov 2021 00:00:01 GMT

Nos artigos anteriores estava sendo abordado o tema do básico de Programação Orientada a Objetos no Java; porém existem outros tópicos da linguagem que seria bom serem apresentados. Iniciaremos com Enumerações e no final desse artigo você será capaz de entender o que são, como criá-las e usar.

Enumerações foram introduzidas no Java5 e são uma forma dos desenvolvedores trabalharem melhor com dados que não podem ser alterados do que usando constantes, ela foi introduzida como sendo um tipo novo na linguagem o que significa que os desenvolvedores ganharam uma forma de checagem de tipos em tempo de compilação, o que ajuda muito no desenvolvimento principalmente por que possíveis erros são apontados no momento em que estamos escrevendo o código ao invés de só perceber, se perceber, o erro quando o código já está rodando e sendo usado. Juntamente com a tipagem foi adicionado um pacote novo, o java.lang.Enum e com isso uma série de métodos foram herdados quando uma Enum é criada.

Para entender a motivação para adicionar Enums no Java vamos supor que temos um código que valida o dia da semana, sabemos que os nomes dos dias da semana são imutáveis então podemos criar constantes para isso da seguinte forma:

public class DiaDaSemana {
    
    public static final String DOMINGO = "DOMINGO";
    public static final String SEGUNDA = "SEGUNDA";
    public static final String TERCA = "TERCA";
    public static final String QUARTA = "QUARTA";
    public static final String QUINTA = "QUINTA";
    public static final String SEXTA = "SEXTA";
    public static final String SABADO = "SABADO";
    
}

Tendo em mãos as contantes podemos criar o método que lida com o dia da semana e a partir dele toma alguma decisão:

public static void avaliaDiaDaSemana(String diaDaSemana){
    switch (diaDaSemana){
        case DiaDaSemana.DOMINGO:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DO DOMINGO");
            break;
        case DiaDaSemana.SEGUNDA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA SEGUNDA");
            break;
        case DiaDaSemana.TERCA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA TERCA");
            break;
        case DiaDaSemana.QUARTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA QUARTA");
            break;
        case DiaDaSemana.QUINTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA QUINTA");
            break;
        case DiaDaSemana.SEXTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA SEXTA");
            break;
        case DiaDaSemana.SABADO:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DO SABADO");
            break;
    }
}

No código acima foi feito uso de um switch-case sem uma cláusula default pois o desenvolvedor assumiu que como esse método sempre vai receber dias da semana não haveria o por que adicionar um default pois não seria executado. Agora vamos simular um caso de uso e testar essa hipótese:

public static void main(String[] args) {

    String diaDaSemana = "JANEIRO";
    
    avaliaDiaDaSemana(diaDaSemana);
}

Ao executar esse código nada será impresso pois houve uma falha no dado de entrada e isso não ficou explícito em nenhum ponto do código, uma possível solução aqui seria adicionar o default porém só estaríamos contornando o problema pois esse método permite a entrada de Strings mas no desenvolvimento nós queremos apenas dias da semana como uma entrada válida e se tentassem passar qualquer valor que não seja um dia da semana não poderia ser executado, graças as Enums isso se torna possível.

Criando Enums

Criar uma Enum é como criar uma classe porém utilizamos a palavra reservada enum, para ficar claro o código abaixo é a criação de uma Enum representando os dias da semana:

public enum DiaDaSemana {
    DOMINGO,
    SEGUNDA,
    TERCA,
    QUARTA,
    QUINTA,
    SEXTA
}

Foi criado uma Enum simples e iremos evoluí-la ao passar do artigo e ver outras vantagens que ganhamos com iso. Uma enum carrega consigo um valor que por padrão é o próprio nome do item na Enum, então conseguimos fazer validações do tipo:

System.out.println(DiaDaSemana.valueOf("DOMINGO"));

O método valueOf que vem herdado do pacote java.lang.Enum retorna o item da Enum correspondente se o valor combinar com algum valor da Enum ou lança uma exceção IllegalArgumentException caso não encontre nenhum valor que combine com a String informada, você pode ter notado que bastou adicionar a palavra enum e automaticamente ganhamos vários métodos como o valueOf, name, ordinal e etc.

Usando Enums

Agora vamos alterar o método avaliaDiaDaSemana para trabalhar com a Enum DiaDaSemana:

public static void avaliaDiaDaSemana(DiaDaSemana diaDaSemana){
    switch (diaDaSemana){
        case DOMINGO:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DO DOMINGO");
            break;
        case SEGUNDA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA SEGUNDA");
            break;
        case TERCA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA TERCA");
            break;
        case QUARTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA QUARTA");
            break;
        case QUINTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA QUINTA");
            break;
        case SEXTA:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DA SEXTA");
            break;
        case SABADO:
            System.out.println("EXECUTANDO REGRA DE NEGÓCIO DO SABADO");
            break;
    }
}

Agora o método recebe a Enum DiaDaSemana e não há como passar outro valor que não seja um DiaDaSemana para o método avaliaDiaDaSemana:

avaliaDiaDaSemana(DiaDaSemana.DOMINGO);

Se tentarmos usar outro tipo que não seja um DiaDaSemana o código não irá compilar e se forçarmos o uso de outro valor será lançada uma Exception:

//Não compila
avaliaDiaDaSemana("OutroValor");
        
//IllegalArgumentException
avaliaDiaDaSemana(DiaDaSemana.valueOf("DIA QUE NÃO EXISTE"));

Atributos e métodos com Enums

Vimos o exemplo de como criar uma Enum do jeito mais simples possível, porém Enums podem ter atributos e métodos associados a elas. Isso ocorre pois uma Enumeração se comporta como se fosse uma classe estática, uma classe que não pode ser instanciada, então se é uma classe é possível existir atributos e métodos, a própria utilização de uma Enum se assemelha ao uso de um método estático, exemplo: DiaDaSemana.DOMINGO. Por conta disso caso seja necessário ter métodos ou atributos que auxiliem na execução de Enums podemos adicionar da seguinte maneira, começando pelo atributos:

public enum DiaDaSemana {
    DOMINGO("Domingo"),
    SEGUNDA("Segunda"),
    TERCA("Terça"),
    QUARTA("Quarta"),
    QUINTA("Quinta"),
    SEXTA("Sexta"),
    SABADO("Sábado");

    private String nome;

    DiaDaSemana(String nome){
        this.nome = nome;
    }
}

Como Enums se comportam como classes, com a exceção de que não podem ser instanciadas, podemos criar atributos mas para ligá-los ao itens da Enum DiaDaSemana é necessário que esses itens, da Enum, estejam instanciados dentro da Enum e para isso foi criado um construtor, que não é público, fazendo a ligação do atributo nome para cada item no Enum e por fim foi criado um valor para cada um deles.

Para criar métodos em Enums é o mesmo que criar métodos em classes:

public String getNome(){
    return this.nome;
}

A utilização dos métodos é muito parecido com o que vemos em métodos estáticos:

System.out.println(DiaDaSemana.DOMINGO.getNome());

E o resultado é o atributo nome que está associado ao item DOMINGO:

Domingo

Para esclarecer um pouco mais vamos criar outro método para verificar se o dia é final de semana:

public boolean verificaFinalDeSemana(){
    if(this == SABADO || this == DOMINGO){
        return true;
    }

    return false;
}

O método acima verifica se o dia testado é um sábado ou domingo e retorna um true caso seja e um false caso não seja, perceba que é passado o operador this e ele se refere a instancia do item do Enum que irá chamar o método verificaFinalDeSemana:

System.out.println(DiaDaSemana.SEGUNDA.verificaFinalDeSemana());
System.out.println(DiaDaSemana.SABADO.verificaFinalDeSemana());

Então quando o Enum DiaDaSemana.SEGUNDA chamar o método verificaFinalDeSemana o this se refere a SEGUNDA e assim em todos os itens da Enum, rodando esse código o resultado é:

false
true

Conclusão

Quando se trabalha com Enum na maioria das vezes é por que existe uma coleção de dados que devem constante e queremos que isso seja garantido, Enums suprem muito bem essa necessidade. Existem outras maneiras de trabalhar com Enums como EnumSet e EnumMap porém esses são tópicos mais avançados de Enums e não tão comumente usados no dia-a-dia, porém com o que foi passado você será capaz de entender quando usar Enums e como usá-las para tirar o máximo proveito possivel delas.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java VIII

Wed, 17 Nov 2021 00:00:01 GMT

Polimorfismo e Interface

No último artigo foi mostrado a Herança e como podemos fazer uso de Classes Abstratas, para criar estruturas que podem ser usadas para realizar Herança mas sem que sejam criadas classes a partir delas. Agora vamos abordar o tema Polimorfismo e como é importante esse conhecimento para se trabalhar de forma orientada a objetos com Java.

Polimorfismo significa múltiplas formas e aqui veremos como podemos tirar vantagem de um código que pode assumir muitas formas e deixar todo o processamento mais fluído e flexível.

Ao fim desse artigo você será capaz de saber usar e identificar o Polimorfismo em seu código e também estará ciente das vantagens que esse recurso trás.

Antes mesmo de entrar no assunto de Polimorfismo é extremamente importante entender o que é uma Interface na Java, pois é um recurso muito usado em conjunto com Polimorfismo.

Uma Interface é um contrato que define “esqueletos” de métodos para que sejam implementados por classes. Muito similares com a ideia de Classes Abstratas, é uma estrutura que não pode ser instanciada porém existem diferenças entre Interfaces e Classes Abstratas e iremos ver algumas no decorrer do artigo.

Voltando ao exemplo base que está sendo usado nos outros artigos, a nossa aplicação bancária possui uma Classe Abstrata que se refere a uma Conta e não faz sentido nessa aplicação que seja possível criar uma conta sem dizer se é de pessoa física ou jurídica, então a classe Conta foi definida como uma Classe Abstrata onde através de Herança foi definido classes filhas ou sub-classes de Conta (PessoaFisica e PessoaJuridica), então podemos concluir que as classes PessoaFisica e PessoaJuridica são do mesmo tipo da classe Conta já que são filhas e isso é chamado de relacionamento É-UM onde a classe PessoaFisica é considerada uma Conta. Podemos definir outro tipo de relacionamento no Java onde a classe também será do tipo É-UM porém com uma ideia mais voltada para a capacidade que essa classe irá possuir e fazemos isso com Interface.

Para ficar mais claro vamos criar uma Interface que será responsavel pelos serviços de financiamentos, vamos chamá-la de Financiamento:

public interface Financiamento {

    boolean pegaEmprestimo(Conta conta);

    BigDecimal liberaEmprestimo(Conta conta, BigDecimal valor);
}

No código anterior foi definido dois métodos, um chamado pegaEmprestimo que recebe uma Conta como argumento e devolve um boolean e outro chamado liberaEmprestimo que também recebe uma Conta e devolve um BigDecimal que seria referente ao valor do emprestimo liberado. Podemos ver que uma Interface define os contratos de métodos porém não provê uma implementação, também não foi passado nenhum modificador de acesso, porém no caso de interfaces isso não significa que esses métodos sejam default como vimos em artigos anteriores, nesse caso não precisamos informar mas todo método em uma Interface é automaticamente public e abstract sempre.

Com a Interface criada iremos criar uma classe chamada Banco e iremos fazer com que essa classe possa ter a capacidade de fornecer financiamentos:

public class Banco implements Financiamento{
    
    private String nome;
    private List<Conta> contas;

    public Banco(String nome, List<Conta> contas) {
        this.nome = nome;
        this.contas = contas;
    }
    
    @Override
    public boolean pegaEmprestimo(Conta conta) {
        return new Random().nextBoolean();
    }

    @Override
    public BigDecimal liberaEmprestimo(Conta conta, BigDecimal valor) {
        if (this.pegaEmprestimo(conta)) {
            return valor;
        }
        return valor.divide(new BigDecimal(2));
    }

    public String getNome() {
        return nome;    
    }

    public List<Conta> getContas() {
        return List.copyOf(contas);
    }
}

Nesse exemplo temos a classe Banco e quando queremos usar Interfaces adicionamos a palavra reservada implements que como o próprio nome diz irá implementar aquela Interface e criar um relacionamento entre a Classe e a Interface, também foi necessário implementar os métodos pegaEmprestimo e liberaEmprestimo, onde o pegaEmprestimo só devolve um boolean aleatório e o método liberaEmprestimo que se baseia no retorno do pegaEmprestimo para saber a quantidade que será liberada de crédito, caso a analise de crédito retorne um true ele poderá pegar o valor total solicitado e caso retorne false poderá pegar a metade.

Podemos começar a ver um pouco de Polimorfismo nesse código onde os métodos pegaEmprestimo e liberaEmprestimo recebem como argumento uma Conta sem fazer distinção se é uma conta de pessoa física ou jurídica e se por acaso no futuro existir outro tipo de conta esse código está preparado para recebê-lo, o que torna o nosso código mais flexível e desacoplado das implementações como PessoaFisica ou PessoaJuridica.

Agora podemos criar uma instância de Banco e fazer as operações de Financiamento para as Contas:

public class Main {

    public static void main(String[] args) {

        Conta contaFisicaGuilherme = new PessoaFisica("Guilherme");
        Conta contaJuridicaGuilherme = new PessoaJuridica("Empresa do Guilherme");

        Banco banco = new Banco("MeuBanco", List.of(contaFisicaGuilherme, contaFisicaGuilherme));

        BigDecimal valorLiberado = banco.liberaEmprestimo(contaFisicaGuilherme, new BigDecimal("1000"));
        System.out.println("Valor liberado %s para conta %s".formatted(valorLiberado, contaFisicaGuilherme));

        valorLiberado = banco.liberaEmprestimo(contaJuridicaGuilherme, new BigDecimal("10000"));
        System.out.println("Valor liberado %s para conta %s".formatted(valorLiberado, contaJuridicaGuilherme));
    }
}

Explicando o código acima, primeiramente criamos duas classes, uma para PessoaFisica e outra para PessoaJuridica porém as duas foram atribuídas para variáveis do tipo Conta, isso também é o Polimorfismo em ação pois como foi dito anteriormente tanto a classe PessoaFisica quanto PessoaJuridica são filhas ou sub-classes da classe Conta e por isso podemos referenciar dessa maneira, e podemos passar para o método liberaEmprestimo uma PessoaFisica ou PessoaJuridica que são uma Conta também, porém poderíamos passar uma variável do tipo PessoaFisica ou PessoaJuridica pois como dissemos elas também são do tipo Conta.

Um ponto diferente entre Interfaces e Classes Abstratas é que pode haver múltiplas implementações de Interfaces para uma classe, coisa que não pode acontecer com Classes Abstratas já que não existe Herança múltipla no Java mas com Interfaces podemos adicionar esse comportamento e para exemplificar isso iremos criar outra Interface para serviços de transferências do banco:

public interface Transferencia {
    
    void realizaTransferencia(Conta origem, Conta destino, BigDecimal valor);
}

Criamos uma Interface Transferencia com um método realizaTransferencia que recebe a Conta de origem, a Conta de destino e o valor da transferência, e aqui fica bem claro a ideia de Polimorfismo já que não amarramos uma transferência para uma conta jurídica ou física; vamos adicionar essa funcionalidade na classe Banco:

public class Banco implements Financiamento, Pagamento{

    //TODO O RESTO OMITIDO

    @Override
    public void realizaTransferencia(Conta origem, Conta destino, BigDecimal valor) {
        BigDecimal valorSacado = origem.saca(valor);
        destino.deposita(valorSacado);
    }

}

Como visto no código acima para fazer a implementação de múltiplas Interfaces no Java basta adicioná-las após a palavra implements separadas por vírgula. Nesse exemplo foi implementado a transferência entre contas onde basicamente é feito o saque de uma conta e o depósito em outra, como fazemos uso do Polimorfismo nesse caso não ficamos amarrados ou presos a detalhes de implementação de como as contas fazem esse procedimento, após declararmos o que queremos que seja feito sabemos que as implementações irão executar suas responsabilidades. Foram feitos alguns ajustes para que esse lógica funcionasse, primeiramente olhando a classe Conta:

public abstract class Conta {

    protected  BigDecimal saldo;

    public Conta() {
        this.saldo = new BigDecimal("1000");
    }
}

Foi adicionado o atributo saldo que também foi adicionado ao construtor da classe Conta para que na inicialização aja saldo com valor de 1000 quando uma conta nova é criada, uma observação é que mesmo não podendo criar uma instância de uma Classe Abstrata podemos ter um construtor que será usado pelas classe filhas, já nas classes PessoaFisica e PessoaJuridica foi adicionado ao construtor a chamada para o construtor da classe mãe. E adicionamos a lógica para subtrair ou adicionar ao saldo quando ocorrer um saque ou um depósito, segue o exemplo na classe PessoaFisica:

public class PessoaFisica extends Conta {
    public static final String TIPO_DE_DOCUMENTO = "CPF";

    public PessoaFisica(String nome){
        //CHAMADA AO CONSTRUTOR DA CLASSE MÃE
        super();
        this.documento = TIPO_DE_DOCUMENTO;
        this.nome = nome;
    }

    @Override
    public BigDecimal saca(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        System.out.println("SAQUE PARA PESSOA " + this.nome + " COM DOCUMENTO " +  this.documento);
        //LÓGICA PARA ADICIONAR AO SALDO
        this.saldo = this.saldo.subtract(quantidade);
        return quantidade;
    }

    @Override
    public BigDecimal deposita(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        System.out.println("DEPOSITANDO PARA PESSOA " + this.nome + " COM DOCUMENTO " +  this.documento);
        //LÓGICA PARA SUBTRAIR DO SALDO
        this.saldo = this.saldo.add(quantidade);
        return quantidade;
    }
}

As mudanças no código foram:

No construtor foi adicionado uma chamada ao construtor da classe mãe através do super().
Tanto no método saca quanto no deposita foi chamado o atributo saldo para adicionar fundos, no método saca, ou para subtrair fundos, método deposita.

E agora executando esse código:

public class Main {

    public static void main(String[] args) {

        Conta contaFisicaGuilherme = new PessoaFisica("Guilherme");
        Conta contaJuridicaGuilherme = new PessoaJuridica("Empresa do Guilherme");

        Banco banco = new Banco("MeuBano", List.of(contaFisicaGuilherme, contaFisicaGuilherme));

        banco.realizaTransferencia(contaFisicaGuilherme, contaJuridicaGuilherme, new BigDecimal("10"));

        System.out.println(contaFisicaGuilherme);
        System.out.println(contaJuridicaGuilherme);
    }
}

Teremos como saída o seguinte:

Conta{nome='Guilherme', documento='CPF', saldo=990}
Conta{nome='Empresa do Guilherme', documento='CNPJ', saldo=1010}

Uma novidade que passou a existir a partir do Java 8 foi a possibilidade de haver um método implementado em uma Interface, antes só as Classes Abstratas poderiam possuir métodos implementados. Vamos ver isso em ação criando uma Interface para Auditoria:

public interface Auditoria {

    default void audita(){
        System.out.println("REALIZANDO AUDITORIA");
    };
}

A Interface Auditoria possui um método chamado audita e este método já possui uma implementação e indicamos isso através da palavra default seguido do método e de sua implementação, se quisermos implementar essa Interface na classe Banco não será mais obrigatório fornecer uma implementação para esse método:

public class Banco implements Financiamento, Pagamento, Auditoria{
    //TODO RESTO OMITIDO
}

Não foi obrigatório fornecer uma implementação porém se for necessário podemos sobrescrever o método audita:

@Override
public void audita() {
    Auditoria.super.audita();
    System.out.println("AUDITORIA CUSTOMIZADA");
}

Sobrescrevemos o método audita porém é possível manter a implementação padrão através da chamada Auditoria.super.audita() onde o super serve para invocar o método que está na Interface. Se executarmos esse código agora:

Conta contaFisicaGuilherme = new PessoaFisica("Guilherme");
Conta contaJuridicaGuilherme = new PessoaJuridica("Empresa do Guilherme");

Banco banco = new Banco("MeuBano", List.of(contaFisicaGuilherme, contaFisicaGuilherme));
banco.audita();

O resultado será:

REALIZANDO AUDITORIA
AUDITORIA CUSTOMIZADA

O último ponto entre Interfaces e Classes Abstratas é que não podemos adicionar atributos em Interfaces mas conseguimos fazer isso em Classes Abstratas.

Problema Diamante

No último artigo falamos que não existe Herança múltipla no Java pois se houverem dois métodos com a mesma assinatura em classes diferentes qual método seria executado. Porém o mesmo problema pode ocorrer com Interfaces e é permitido implementar múltiplas Interfaces, como esse problema é contornado nesses casos?

Vamos criar duas Interfaces, Log e Logger e as duas irão conter um método chamado log:

public interface Log {

    default void log(){
        System.out.println("REALIZANDO LOG");
    };
}

public interface Logger {

    default void log(){
        System.out.println("REALIZANDO LOGGER");
    };
}

As duas Interfaces possuem a mesma assinatura e as duas possuem métodos já implementados, se adicionarmos essas Interfaces na classe Banco o código irá parar de compilar. Isso ocorre pois o compilador consegue identificar esse problema e irá nos obrigar a fornecer uma implementação para esse método.

public class Banco implements Log, Logger{

    @Override
    public void log() {
        Log.super.log();
        Logger.super.log();
    }

}

No exemplo acabamos por usar as duas implementações porém poderíamos escolher entre uma delas ou até mesmo criar uma implementação customizada na classe Banco.

Para saber mais sobre o Problema Diamante.

Quando usar Interface ou Classe Abstrata?

Não existe uma resposta padrão para essa pergunta porém podemos analisar qual usar de acordo com alguns critérios:

|---------------------------------------|---------------------------------------------------------|
|              Interface                |                  Classe Abstrata                        |
|---------------------------------------|---------------------------------------------------------|
| Várias implementações que compartilham| Compartilhar código em classes relacionadas que possuem | 
| a mesma assinatura de método          | um comportamento em comum                               |
|---------------------------------------|---------------------------------------------------------|
| Adicionar comportamento mesmo sem     | Compartilhar atributos entre classes                    |
| ter total certeza de como será        |                                                         |
| a implementação                       |                                                         |
|---------------------------------------|---------------------------------------------------------|
| Fazer uso de múltiplas implementações | Controle de acesso através de modificadores de acessos  |
|---------------------------------------|---------------------------------------------------------|

Utilização de Polimorfismo pela linguagem

A própria linguagem Java faz muito uso de Polimorfismo por padrão, um exemplo disso é a Interface List que possui diversas implementações:

List<String> lista = new ArrayList<>();
lista = new LinkedList<>();
lista = new Vector<>();
lista = new Stack<>();

Podemos ver que a variável lista pode carregar várias implementações pois todas essas classes implementam direta ou indiretamente a Interface List.

Conclusão

Neste artigo exploramos Interfaces e como podemos fazer uso delas para criar código Polimórficos.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java VII

Tue, 09 Nov 2021 00:00:01 GMT

No último artigo iniciamos o assunto sobre Herança e neste artigo será concluído o tema e apresentado o assunto de abstração. Você verá formas de usar esses conceitos para construção de códigos mais consistentes e legíveis.

No projeto que foi apresentado existe a seguinte situação, em um sistema bancário podemos ter dois tipos de conta, a conta para pessoa física e a conta para pessoa jurídica, para isso foi criado uma classe chamada Conta que serve de molde para as classes PessoaFisica e PessoaJuridica e fazendo uso de Herança isso é possível, porém no decorrer percebemos que era possível criar uma instância da classe Conta e para a regra dessa aplicação isso não deveria ser possível, mas como podemos fazer uso de Herança sem que aja uma breja que pode ser usada de forma equivocada? Iremos ver nesse artigo como podemos fazer uso de Abstração para suprir isso.

Classes Abstratas

No nosso exemplo de código seria muito útil se houvesse uma forma de ter uma estrutura de dados que guardasse os atributos e métodos em comum de uma Conta mas que não pudesse ser instanciada e que permitisse o uso de Herança. Essa estrutura existe e é chamada de Classe Abstrata, vamos ver como criar e depois entenderemos melhor os seus benefícios:

public abstract class Conta {

    private String nome;
    private String documento;

    public BigDecimal deposita(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
        return BigDecimal.ZERO;
    }

    public BigDecimal saca(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
        return BigDecimal.ZERO;
    }

    //Todo o resto omitido
}

Reaproveitamos a classe Conta e adicionamos o modificador de acesso abstract, isso já serve em partes pois se tentarmos instanciar uma classe Conta não será mais possível:

Conta conta = new Conta();

Isso gera erro de compilação:

'Conta' is abstract; cannot be instantiated

Agora vamos entender um pouco mais o que é uma Classe Abstrata. Uma Classe Abstrata é uma classe que não pode ser instanciada somente herdada, ela também tem a capacidade de definir métodos sem implementação, chamado de métodos abstratos que são métodos que contém somente a assinatura e que a classe que herdar da Classe Abstrata deve se preocupar com a sua implementação, porém também é possível ter métodos implementados em uma Classe Abstrata e através de sobrescrita de métodos customizá-los nas classes que herdarem a Classe Abstrata.

*OBS: Porém qual estratégia é melhor usar? Deixar métodos implementados nas classes abstratas que podem ser sobrescritos ou deixá-los para serem implementados nas classes filhas? Essa pergunta não é tão simples de responder e cabe a você como desenvolvedor pensar no que faz sentido para cada caso.

Para deixar mais claro vamos ver como ficou o código na classe Conta:

public abstract class Conta {

    protected String nome;
    protected String documento;

    public abstract BigDecimal deposita(BigDecimal quantidade);

    public BigDecimal saca(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
        return BigDecimal.ZERO;
    }

    //Restante omitido
}

Tem alguns pontos significativos que foram alterados porém agora vamos focar na alteração do método deposita onde foi adicionado o modificador abstract e removido a implementação do método. Isso significa que esse método deve ter obrigatoriamente uma implementação válida na classe que herdar da classe Conta, essa é uma forma de garantirmos que iremos ter um método customizado sendo implementado na classe que for filha da classe Conta, se tentarmos herdar uma Classe Abstrata com um método abstrato e não implementarmos nada para esse método iremos receber um erro de compilação.

Outro ponto que vimos no código acima é a utilização de atributos com o modificador protected, poderíamos ter atributos private ou até mesmo public em uma Classe Abstrata porém como o conceito de uma Classe Abstrata é ser um “molde” que não pode ser instanciado somente herdado faz muito sentido ser usado o modificador protected pois ele irá garantir que esses campos só poderão ser usados em sub-classes por meio de Herança.

*OBS: Até o Java 7 esse era o único modo de termos métodos concretos e métodos não implementados em um unico arquivo, porém a partir do Java 8 é possível termos métodos implementados em Interfaces porém esse assunto ainda será abordado mais a frente.

Então usando essa ideia podemos fazer da seguinte maneira nas sub-classes de Conta:

public class PessoaFisica extends Conta{
    public static final String TIPO_DE_DOCUMENTO = "CPF";

    public PessoaFisica(String nome){
        this.documento = TIPO_DE_DOCUMENTO;
        this.nome = nome;
    }

    @Override
    public BigDecimal saca(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        System.out.println("SAQUE PARA PESSOA " + this.nome + " COM DOCUMENTO " +  this.documento);
        return quantidade;
    }

    @Override
    public BigDecimal deposita(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        System.out.println("DEPOSITANDO PARA PESSOA " + this.nome + " COM DOCUMENTO " +  this.documento);
        return quantidade;
    }
}

Explicando as alterações que foram feitas acima:

Foi criado um construtor para receber o nome do titular da conta e atribuído ao atributo nome que está na super-classe Conta.
O método saca está sobrescrito na classe PessoaFisica porém como existe uma implementação na super-classe Conta não seria necessário existir aqui, mas podemos fazer uso desse recurso de sobrescrita para customizações.
O método deposita necessita obrigatoriamente de uma implementação na sub-classe pois foi definido como um método abstrato na super-classe.

Agora executando esse código:

Conta conta = new PessoaFisica("Guilherme");
conta.saca(BigDecimal.ZERO);

Antes de ver o resultado desse código reflita um pouco sobre o que deveria acontecer nesse caso? Nós criamos uma instância de PessoaFisica porém atribuímos para uma variável do tipo Conta e depois chamamos o método saca; tanto a classe Conta quanto a classe PessoaFisica possuem implementações desse método, qual será executado então?

Analisando o resultado:

APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE
SAQUE PARA PESSOA Guilherme COM DOCUMENTO CPF

Ele executou o que havia dentro da classe PessoaFisica pois por mais que tenhamos atribuído a uma variável do tipo Conta a instância é do tipo PessoaFisica mas por qual razão foi possível atribuir uma instancia de PessoaFisica em uma variavel do tipo Conta?

Isso acontece graças ao Polimorfismo porém esse assunto será visto no próximo artigo, por enquanto entenda que é possível atribuir uma sub-classe para uma variável do tipo da super-classe.

Conclusão

Nessa segunda parte do artigo de Herança entendemos um pouco mais sobre como podemos fazer uso de Abstração com Classes Abstratas para poder criar “moldes” de classes que não podem ser criadas sozinhas e que dependem de sub-classes herdadas para serem usadas. No próximo artigo iremos iniciar o assunto de Polimorfismo e Interfaces.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java VI

Tue, 26 Oct 2021 00:00:01 GMT

Neste artigo iremos abordar a Herança no Java, sendo esse um dos pilares para a Programação Orientada a Objetos. Iremos ver como se comportam relacionamentos de herança, o que é e para que serve a Sobrescrita de métodos. Por se tratar de um assunto mais extenso primeiramente será abordado os conceitos sobre herança e sobrescrita de métodos e posteriormente iremos nos aprofundar em conceitos como Abstração e entrar em Polimorfismo.

Quando se pesquisa sobre esses temas em alguns tutoriais na internet não é incomum encontrar exemplos explicando Herança com classes como Animal e sub-classes como Humano e Cachorro. Entendo que possa ser didático para quem nunca viu esse assunto antes porém nesse artigo tentaremos ir um pouco além e mostrar exemplos um pouco mais próximos da realidade que uma pessoa desenvolvedora irá encontrar no seu dia-a-dia.

Introdução

Herança é um mecanismo que permite ao desenvolvedor aplicar abstrações no código criando uma classe-mãe que possuem atributos ou métodos que podem ser reutilizados por sub-classes que fazem sentido terem aqueles comportamentos e até mesmo permitindo customizações nessas sub-classes.

Para ficar mais claro vamos pensar que trabalhamos em um banco e que nele existe somente dois tipos de conta, uma para pessoas físicas e outra para pessoas jurídicas, podemos criar duas classes nesse caso:

public class ContaPessoaFisica {

    private String nome;
    private String documento;

    public BigDecimal deposita(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO ESPECÍFICO PARA CONTA FISICA");
        return BigDecimal.ZERO;
    }

    public BigDecimal saca(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO ESPECÍFICO PARA CONTA FISICA");
        return BigDecimal.ZERO;
    }
}

public class ContaPessoaJuridica {

    private String nome;
    private String documento;

    public BigDecimal deposita(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO ESPECÍFICO PARA CONTA JURIDICA");
        return BigDecimal.ZERO;
    }

    public BigDecimal saca(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO ESPECÍFICO PARA CONTA JURIDICA");
        return BigDecimal.ZERO;
    }
}

Podemos perceber que essas duas classes são identicas até o momento, com exceção da lógica que cada uma iria realizar. Mas será que é saudável para um projeto de software ter que lidar com duplicações desse jeito? Imaginando um projeto maior isso logo cresce de uma maneira descontrolada o que vai deixar imprevisível o comportamento do sistema em casos de mudanças pois provavelmente se em algum momento for necessário aplicar uma mesma regra de negócio para contas físicas ou juridicas pode ocorrer desse comportamento não se propagar da forma que foi planejada ou mesmo se for criada outra modalidade de conta nesse projeto será necessário duplicar tudo novamente.

Pensando em resolver essas complicações a Herança foi adotada na linguagem Java onde podemos ter a classe-mãe, nesse caso Conta e suas filhas PessoaFisica e PessoaJuridica:

public class Conta {

    private String nome;
    private String documento;

    public BigDecimal deposita(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
        return BigDecimal.ZERO;
    }

    public BigDecimal saca(BigDecimal quantidade){
        System.out.println("EXECUTA REGRA DE NEGÓCIO GENERALISTA");
        return BigDecimal.ZERO;
    }

}

public class PessoaFisica extends Conta{

    public static final String TIPO_DE_DOCUMENTO = "CPF";
}

public class PessoaJuridica extends Conta{

    public static final String TIPO_DE_DOCUMENTO = "CNPJ";
}

Podemos ver que a classe Conta funciona com a responsabilidade de guardar dados e comportamentos que serão comuns entre as contas físicas e juridicas e por sua vez as classes-filhas guardam atributos e métodos que são específicos para elas. Outro ponto importante é que foi usado a palavra reservada extends, essa palavra é o que irá indicar que está sendo feito um relacionamento do tipo Herança, onde após a palavra extends adicionamos a classe que está sendo herdada. Tem alguns pontos de melhoria em toda essa abordagem e até o fim do artigo iremos explorá-los.

Agora podemos usar tanto uma conta fisica quanto uma jurídica:

public class Main {

    public static void main(String[] args) {

        PessoaFisica contaPessoaFisica = new PessoaFisica();
        contaPessoaFisica.deposita(BigDecimal.valueOf(10));

        PessoaJuridica contaPessoaJuridica = new PessoaJuridica();
        contaPessoaJuridica.saca(BigDecimal.valueOf(10));
    }
}

Mas o que irá acontecer se quiséssemos criar uma instância de Conta? Será que nesse modelo ter uma conta que não é nem física e nem jurídica faz sentido?

Conta conta = new Conta();
conta.deposita(BigDecimal.valueOf(10));

Só não é possível como também é possível depositar e sacar de uma classe que idealmente existe como um molde para outros tipos de conta, porém iremos ver como solucionar esse problema; outro problema que pode ter ficado menos evidente é que agora a regra de negócio para contas físicas e jurídicas é a mesma e não era essa a intenção, precisamos de um jeito melhor de lidar com essas situações e o Java fornece as ferramentas para isso.

Object

Antes mesmo de continuar é bom ter em mente que na linguagem Java tudo, com exceção dos tipos primitivos, tem relação com a classe Object. Então concluímos que tudo no Java herda de Object. Isso significa que no nosso exemplo a classe Conta herda de Object mas como pode isso se a classe Conta não tem uma declaração extends?

Isso acontece pois a própria linguagem se encarrega disso e nos artigos anteriores já havíamos utilizado métodos da classe Object sem perceber, quando usamos métodos como toString, equals ou hashCode estamos fazendo uso de métodos da classe Object:

public class Conta {

    //RESTANTE DO CÓDIGO OMITIDO

    @Override
    public String toString() {
        return "Conta{" +
                "nome='" + nome + '\'' +
                ", documento='" + documento + '\'' +
                '}';
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Conta conta = (Conta) o;
        return Objects.equals(nome, conta.nome) && Objects.equals(documento, conta.documento);
    }

    @Override
    public int hashCode() {
        return Objects.hash(nome, documento);
    }
}

Essa foi uma decisão de projeto dos criadores da linguagem, pois eles entenderam que esses métodos são comuns a todas as classes, o método toString retorna uma String para que nós pessoas possamos entender a representação daquela instância de objeto, o equals e o hashCode são muito importantes quando trabalhamos com coleções de dados e iremos ver a importância deles futuramente.

Uma dúvida que pode ter ficado após ver o código acima, como o toString da classe Conta sabe que precisa ser formatado dessa forma ou como os métodos equals e hashCode sabem que precisam dos atributos nome e documento e o que é esse @Override escrito acima dos métodos? A resposta mais curta é que esses métodos não sabem e cabe a você dizer isso a eles.

O @Override é uma Annotation do Java, não vamos entrar em detalhes agora mas basta entender que Annotations como essa indicam alguma coisa no código, nesse caso ela indica que esse método foi sobrescrito, criando assim um marcador sobre esse método, as Annotations também lidam com outras questões que serão abordadas mais pra frente.

Sobrescrita

Voltando ao problema do nosso projeto, agora a regra de negócio está compartilhada entre as contas e não é isso que queríamos. Como podemos manter a classe Conta com o que queremos mas sem propagar comportamentos que queremos que sejam próprios das classes filhas? Usando sobrescrita de métodos isso é possível, mas o que é sobrescrita de métodos?

Voltando ao exemplo do método toString da classe Object:

public String toString(){
    return getClass().getName() + '@' + Integer.toHexString(hashCode());
}

Na classe Object essa é a declaração do método toString, o nome da classe seguido do hexadecimal da classe indicando o endereço de memória do objeto que chamou o método, agora imagine se em todo objeto que chamássemos o toString fosse essa informação que fosse devolvida, será que seria útil para nós saber onde na memória o objeto está alocado? Pensando nisso existe a sobrescrita de métodos que permite customizações específicas para métodos que são herdados, logo com isso foi possível customizar o toString da classe Conta para que ele devolvesse uma String que seres humanos consigam ler e entender o seu significado.

E como as classes PessoaFisica e PessoaJuridica herdam de Conta é possível customizar os métodos para a realidade de negócio delas, primeiramente mostrando a classe PessoaJuridica:

public class PessoaJuridica extends Conta{

    public static final String TIPO_DE_DOCUMENTO = "CNPJ";

    @Override
    public BigDecimal saca(BigDecimal quantidade) {
        System.out.println("VALIDANDO...");
        if(quantidade.compareTo(BigDecimal.ZERO) <= 0){
            System.out.println("VALIDAÇÃO RETORNA ERRO");
            throw new IllegalArgumentException("VALOR DEVE SER MAIOR DO QUE ZERO");
        }
        return super.saca(quantidade);
    }

    @Override
    public BigDecimal deposita(BigDecimal quantidade) {
        System.out.println("VALIDANDO...");
        if(quantidade.compareTo(BigDecimal.ZERO) <= 0){
            System.out.println("VALIDAÇÃO RETORNA ERRO");
            throw new IllegalArgumentException("VALOR DEVE SER MAIOR DO QUE ZERO");
        }
        return super.deposita(quantidade);
    }
}

Na classe PessoaJuridica sobrescrevemos os métodos saca e deposita e com isso ganhamos mais flexibilidade pois agora podemos executar uma validação, que poderia estar na super classe Conta mas para fins didáticos vou deixar aqui para ficar claro que podemos executar regras diferentes em métodos sobrescritos, perceba também que apesar dos métodos estarem sobrescritos no final de cada um deles é feito uma chamada super.saca(quantidade) e super.deposita(quantidade) esse exemplo foi deixado aí para que você entenda que é possível executar um método na sub-classe e delegar para a super classe o restante da execução, basta usar o operador super que delega para a super classe a chamada do método. Contudo podemos querer, por vários motivos, que a execução do método sobrescrito fique contido somente na classe específica e para isso podemos fazer do jeito como foi feito na classe PessoaFisica:

public class PessoaFisica extends Conta{

    public static final String TIPO_DE_DOCUMENTO = "CPF";

    @Override
    public BigDecimal saca(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        return quantidade;
    }

    @Override
    public BigDecimal deposita(BigDecimal quantidade) {
        System.out.println("APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE");
        return quantidade;
    }
}

Bastou retirar o operador super para que o método fosse isolado dentro da classe, agora executando o código:

PessoaFisica contaPessoaFisica = new PessoaFisica();
contaPessoaFisica.deposita(BigDecimal.valueOf(10));

PessoaJuridica contaPessoaJuridica = new PessoaJuridica();
contaPessoaJuridica.saca(BigDecimal.valueOf(10));

Teremos a seguinte saída:

APLICANDO REGRA MUITO ESPECÍFICA SEM CHAMAR A SUPER CLASSE
VALIDANDO...
EXECUTA REGRA DE NEGÓCIO GENERALISTA

Agora resolvemos o problema de ter regras distribuídas para classes que não fazem sentido ter aquela regra, porém ainda temos o problema de poder criar uma classe Conta e iremos ver agora como solucionar isso com Classes Abstratas no próximo artigo.

Limitações

A Herança é uma grande ferramenta que auxilia o desenvolvimento de sistemas porém existem algumas limitações e a mais importante no que tange a linguagem Java é que só podemos fazer herança de uma única classe pois no Java não existe herança múltipla. Por exemplo vamos supor que no futuro exista um tipo bem especial de Conta onde ela é ao mesmo tempo uma conta de pessoa física e uma conta de pessoa jurídica, eu sei que pode ser estranho isso mas estamos só supondo para explicar o conceito. Agora imagine que você como pessoa desenvolvedora queira utilizar de Herança para resolver esse problema e pensou que poderia criar um classe ContaHibrida que herde de PessoaFisica e de PessoaJuridica ao mesmo tempo e resolveu fazer isso:

public class ContaHibrida extends ContaPessoaFisica, ContaPessoaJuridica{
}

Nesse momento o compilador irá reclamar e exibir uma mensagem parecida com isso:

Class cannot extend multiple classes

Agora vamos ir um passo além na nossa imaginação e pensar que isso não gerasse erro e deu tudo certo na sua classe ContaHibrida e você tentou usá-la assim:

ContaHibrida contaHibrida = new ContaHibrida();
contaHibrida.saca(BigDecimal.valueOf(10));

Qual método saca será executado? O da PessoaFisica ou o da PessoaJuridica? Esse problema é chamado de problema diamante onde teríamos duas classes com o mesmo método, com a mesma assinatura, parâmetros e com uma sub-classe tentando executá-lo, o compilador não tem condições de saber qual executar e por conta disso a herança múltipla não foi adotada na linguagem Java.

Conclusão

Essa é a primeira parte que falamos sobre Herança, nesse artigo foi mostrado o que é Herança no Java e qual tipo de problema ela resolve. Também entendemos mais como a sobrescrita de métodos nos auxilia com classes que herdam métodos que precisam ser customizados. Foi mostrado também uma limitação da Herança no Java que é a questão de heranças múltiplas. No próximo artigo iremos adentrar um pouco mais no conceito É-UM da Herança e serão apresentados as Classes Abstratas.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java V

Wed, 13 Oct 2021 00:00:01 GMT

Para este artigo será mostrado como podemos ter maior flexibilidade através da Sobrecarga de métodos. Também será apresentado as Classes Wrappers e o Autoboxing do Java.

Sobrecarga

A sobrecarga de métodos permite a pessoa que estiver desenvolvendo ter maior flexibilidade sobre um determinado método, onde pode haver vários métodos com o mesmo nome porém com parâmetros diferentes, para exemplificar vamos imaginar que você está desenvolvendo um jogo onde o personagem pode correr com algum veículo ou a pé, para esse caso pode haver várias abordagens mas para explicar sobrecarga de métodos iremos criar classes para cada tipo de veículo, então teremos as classes Carro, Moto e Bicicleta e também iremos criar a classe Personagem que irá conter a ação de acelerar:

public class Carro {

    private String nome;

    public Carro(String nome) {
        this.nome = nome;
    }    

    public String getNome() {
        return nome;
    }

    public void setNome(String nome) {
        this.nome = nome;
    }
}

Esse é o exemplo da classe Carro, onde ela só possui o atributo nome, o construtor recebendo o nome e os métodos getter/setters, as outras classes Moto e Bicicleta seguem o mesmo padrão, e agora vamos ver a classe Personagem:

public class Personagem {

    private String nome;

    public Personagem(String nome) {
        this.nome = nome;
    }

    public String getNome() {
        return nome;
    }

    public void setNome(String nome) {
        this.nome = nome;
    }
}

A classe Personagem possui, por enquanto, apenas o atributo nome e agora vamos implementar o método acelera que irá retornar uma String com a informação que o Personagem está acelerando:

public String acelera(){
    return "Acelerando";
}

O método acelera informa que o Personagem está acelerando mas não diz se é a pé ou com algum veículo. Poderíamos fazer da seguinte maneira:

public String aceleraDeBicicleta(){
    return "Acelerando com bicicleta";
}

public String aceleraComMoto(){
    return "Acelerando com moto";
}

public String aceleraComCarro(){
    return "Acelerando com carro";
}

public String acelera(){
    return "Acelerando a pé";
}

Mas com a sobrecarga podemos criar métodos mais específicos mantendo o mesmo nome, contanto que o parâmetro de entrada seja diferente no método, então podemos fazer da seguinte maneira:

public String acelera(Bicicleta bicicleta){
    return "Acelerando com a bicicleta: " + bicicleta.getNome();
}

public String acelera(Moto moto){
    return "Acelerando com a moto: " + moto.getNome();
}

public String acelera(Carro carro){
    return "Acelerando com o carro: " + carro.getNome();
}

public String acelera(){
    return "Acelerando a pé";
}

Foram criados mais três métodos com o mesmo nome porém com entradas diferentes, cada um recebendo um tipo diferente de veículo e o primeiro método foi melhorado para retornar um texto mais compreensível. Você pode ter notado que para a sobrecarga ocorrer não foi necessário alterar o tipo do retorno mas isso também pode ser feito porém para que isso funcione não pode haver ambiguidade para o compilador, pois pense o que iria acontecer se criássemos um método que recebe os mesmos parâmetros mas tem um retorno diferente?

public String acelera(){
    return "Acelerando a pé";
}

public int acelera(){
    return 1;
}

Aqui temos dois métodos acelera porém com retornos diferentes e se fossemos usar personagem.acelera(); qual dos dois deveria ser executado? O compilador não tem como identificar isso e por isso esse código não compila. Agora se alterarmos:

public String acelera(){
    return "Acelerando a pé";
}

public int acelera(int kmH){
    return kmH;
}

Pensando em um método acelera que recebe a quantidade quilometros por hora que deve ser acelerado; esse código compila pois o compilador já sabe diferenciar pelo parâmetro o que cada método recebe.

Agora exemplificando como usar o código que foi criado:

public static void main(String[] args) {

    Carro ferrari = new Carro("Ferrari");

    Moto harley = new Moto("Harley");

    Bicicleta caloi = new Bicicleta("Caloi");

    Personagem heroi = new Personagem("Heroi");

    System.out.println(heroi.acelera());
    System.out.println(heroi.acelera(10));
    System.out.println(heroi.acelera(harley));
    System.out.println(heroi.acelera(ferrari));
    System.out.println(heroi.acelera(caloi));
}

E a saída será:

Acelerando a pé
10
Acelerando com o moto: Harley
Acelerando com o carro: Ferrari
Acelerando com o bicicleta: Caloi

Classe Wrapper

As classes Wrappers são classes que foram criadas na linguagem Java para representar um tipo primitivo, elas são classes empacotadoras desses tipos primitivos. Quando em um programa usamos um tipo primitivo, por exemplo um int por padrão ele recebe um valor padrão caso nenhum valor seja passado diretamente para ele, no caso de int o valor é 0. Isso é um detalhe do Java, quer seja tipo primitivo ou não tudo recebe um valor padrão, nos casos de classes o valor padrão é null, que significa ausência de valor.

No exemplo abaixo será mostrado a diferença entre o tipo primitivo int e a classe Integer que empacota o tipo int:

public class Wrapper {
    private int numero;
    private Integer numeroWrapper;

    public static void main(String[] args) {
        Wrapper wrapper = new Wrapper();

        System.out.println(wrapper.getNumero());
        System.out.println(wrapper.getNumeroWrapper());
    }
}

Executando esse código teremos a seguinte saída:

0
null

Preste atenção que ao executar o programa é exibido o valor 0 para a variável com nome numero que é um tipo primitivo int e para a variável numeroWrapper o valor exibido é null significando que não existe um valor definido para essa variável.

Pensando nisso foram criadas as classes Wrappers que representam os tipos primitivos, com isso é possível ter uma classe que representa um valor primitivo, como ocorre com int, porém sem ter um valor padrão definido a ele. Fora que por ser uma classe existem vários métodos que podem ser utilizados e que auxiliam a pessoa que estiver desenvolvendo porém não são muito usados no dia-a-dia a vantagem que particularmente eu vejo é a capacidade que uma classe Wrapper tem de não possuir um valor o que também pode ser perigoso pois se tentarmos usar um atributo que for null será lançado uma Exception do tipo NullPointerException então lembre-se de sempre atribuir um valor quando estiver usando uma classe Wrapper.

Autoboxing

Classes Wrappers possuem alguns métodos, como foi citado anteriormente, entre esses métodos existe o valueOf que faz conversão de um valor primitivo para a uma classe Wrapper:

Boolean booleanWrapper = Boolean.valueOf(true);

E o oposto também pode ocorrer com o método booleanValue, no caso da classe Wrapper Boolean mas para cada Wrapper existe o seu método equivalente para conversão de um objeto para o seu tipo primitivo correspondente:

booleanWrapper.booleanValue();

Porém no Java existe o que é chamado Autoboxing e Unboxing que é a capacidade da própria linguagem realizar essas conversões para nós:

boolean falso = Boolean.FALSE;

Boolean verdadeiro = true;

Conclusão

Nesse artigo entendemos um pouco melhor a Sobrescrita de métodos e como ela pode fornecer maior flexibilidade na hora do desenvolvimento, também vimos as Classes Wrappers e o recurso de Autoboxing e Unboxing da linguagem Java.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java IV

Mon, 04 Oct 2021 00:00:01 GMT

Nesse artigo chegamos a Orientação a Objetos, no últimos artigos foi mostrado a parte básica da linguagem e de sua sintaxe e agora será mostrado Classes, que sem isso não haveria Orientação a Objetos no Java, também será mostrado Encapsulamento e como ele é importante na linguagem.

Orientação a Objetos

Antes de iniciarmos qualquer explicação sobre Classes é necessário entender o que é Orientação a Objetos e como esse paradigma é tratado no Java. Antes de existir a Orientação a Objetos o paradigma que dominava o mercado era o paradigma procedural, e resumidamente esse paradigma é sobre escrever métodos ou procedimentos que deveriam ser executados no código enquanto que Orientação a Objetos consiste em criação de Objetos que contém tanto métodos quanto atributos, que são dados referentes aquele Objeto.

O paradigma orientado a objetos trás consigo quatro fundamentos básicos que o torna diferente do paradigma procedural:

Abstração
Encapsulamento
Herança
Polimorfismo

Iremos tratar de cada um desses temas nos próximos artigos.

Classe

Para entender um Objeto é mais fácil explicar o que é uma Classe já que a classe seria o “molde” para um objeto. Para entender melhor vamos pensar em um sistema de Recursos Humanos onde temos o cadastro de Funcionários:

public class Funcionario {

    private String nome;
    private String sobrenome;
    private int idade;
    private String endereco;
    private String departamento;
    
}

Daqui a pouco será explicado o que são as palavras public e private mas por enquanto iremos focar na declaração da classe e seus atributos. No código acima foi criada a classe Funcionário e não um objeto Funcionario mas o que isso significa? Significa que foi criado um “molde” ou um “esqueleto” do que é um funcionário para o nosso código, foi definido que todo Funcionário possui um nome e sobrenome, uma idade, um endereço e um departamento mas ainda não foi criado nenhum funcionário no sistema.

Antes de ver como criar um objeto do tipo Funcionário veremos a sintaxe de uma classe:

class NomeDaClasse {

}

Essa é sintaxe mais básica para existir uma classe, é necessária a palavra reservada class, no nome seguimos o padrão camel case seguido de chaves {}.

Os dados da classe Funcionário são chamados de atributos e possuem e sintaxe básica assim:

String nome;
String sobrenome;
int idade;
String endereco;
String departamento;

É necessário informar qual é o tipo que representa esse atributo no Java então temos o primeiro atributo (nome) do tipo String (texto), idade do tipo int, numérico e etc. A palavra reservada private não é obrigatória porém será entendida mais adiante nesse artigo quando for explicado sobre Encapsulamento.

Para criar um Objeto no Java é usado a palavra reservada new, que irá criar um Objeto na memória e será possível manipular dados desse objeto:

Funcionario funcionario = new Funcionario();

Pronto, só com isso já temos em mãos um objeto do tipo Funcionario, também é possível fazer dessa forma:

var funcionario = new Funcionario();

Como foi dito em artigos anteriores o Java agora é capaz de realizar inferência de tipos, que é capacidade de “saber” qual é o tipo de uma variável mesmo sem declarar explicitamente o seu tipo, como no caso do código acima onde foi criado um objeto do tipo Funcionário e passado para a variável var funcionario sem dizer qual é o seu tipo, o compilador consegue entender que aquela variável é do tipo Funcionario.

Um ponto importante é que foi necessário colocar parenteses () após a palavra new, isso acontece pois Funcionario() é um método. Um método especial do Java que se chama Construtor e ele é responsável pela inicialização dos objetos, por padrão toda classe no Java possui um método construtor sem argumentos então seria como se a classe Funcionario fosse assim:

public class Funcionario {

    public Funcionario(){}

    private String nome;
    private String sobrenome;
    private int idade;
    private String endereco;
    private String departamento;
    
}

O método construtor é um método que tem o mesmo nome da classe e não possui um retorno em sua assinatura e com ele conseguimos criar os objetos.

Agora já sabemos como criar objetos, mas o objeto Funcionario possui atributos que não foram preenchidos, como nome, idade, endereço e departamento. Para lidar com isso é possível criar um método construtor onde passamos esses atributos:

public class Funcionario {

    public Funcionario(String nome, String sobrenome, int idade, String endereco, String departamento) {
        this.nome = nome;
        this.sobrenome = sobrenome;
        this.idade = idade;
        this.endereco = endereco;
        this.departamento = departamento;
    }

    private String nome;
    private String sobrenome;
    private int idade;
    private String endereco;
    private String departamento;

}

Modificamos o método construtor de Funcionario e agora ele recebe todos os dados, porém agora se tentarmos rodar o código como estava antes ele não irá compilar:

Funcionario funcionario = new Funcionario();

'Funcionario(java.lang.String, java.lang.String, int, java.lang.String, java.lang.String)' in 'br.com.company.artigoiv.Funcionario' cannot be applied to '()'

Isso ocorre pois quando explicitamente escrevemos um método construtor o método construtor padrão deixa de existir se por acaso quiséssemos ter os dois construtores, nós podemos mas é necessário escrever isso no código:

public class Funcionario {

    public Funcionario(String nome, String sobrenome, int idade, String endereco, String departamento) {
        this.nome = nome;
        this.sobrenome = sobrenome;
        this.idade = idade;
        this.endereco = endereco;
        this.departamento = departamento;
    }

    public Funcionario() {}
}

Inclusive podemos ter quantos métodos construtores forem necessários porém não é uma boa prática ter muitos métodos construtores, em casos que seja necessário existem outras abordagens e padrões como o Builder.

Outro ponto que é bom mostrar é que dentro do construtor criado foi usado a palavra this. Entender isso é de grande importância pois o this no Java faz referência a própria classe, é ela se auto referenciando e aqui no construtor isso é importante pois as variáveis que são passadas nos argumentos do construtor possuem o mesmo nome das atributos e para saber em qual variável será guardado o valor o this nos auxilia:

private String nome;
private String sobrenome;
private int idade;
private String endereco;
private String departamento;

public Funcionario(String nome, String sobrenome, int idade, String endereco, String departamento) {
    this.nome = nome;
    this.sobrenome = sobrenome;
    this.idade = idade;
    this.endereco = endereco;
    this.departamento = departamento;
}

O this.nome dentro do construtor significa que ela se refere a variável nome da classe Funcionario e não a variável nome do método construtor, se por acaso você retirar o this a variável nome da classe Funcionario não receberá valor e na verdade você estará reatribuindo o valor da variável nome do método construtor para ela mesma. Então conseguimos ver o significado do this dentro de uma classe, sempre que houver this dentro de uma classe significa que está ocorrendo uma referência para ela mesma.

Uma classe também pode ter métodos, o que faz muito sentido pois uma classe que somente tenha atributos não teria conseguiria executar muita coisa dentro do seu código ela serviria como uma objeto de transporte de dados talvez, existe um padrão chamado DTO onde as classes executam esse papel de transporte de dados mas podemos fazer mais com as classes quando adicionamos métodos a elas. Na classe Funcionario podemos adicionar um método para exibir o nome completo de um funcionário:

public String nomeCompleto(){
    return this.nome + " " + this.sobrenome;
}

O método nomeCompleto retorna uma String que é a junção, usamos o termo concatenação nesses casos, do valor da variável nome, uma String vazia para fazer o espaço e o valor da variável sobrenome, se executarmos o programa teremos o resultado:

public static void main(String[] args) {
    Funcionario funcionario = new Funcionario("Guilherme", "Alves", 35, "São Paulo", "Desenvolvimento");
    System.out.println(funcionario.nomeCompleto());
}

Resultado:

Guilherme Alves

Então no código acima foi criado um objeto do tipo Funcionario, usando o método construtor para adicionar valores a ele, atribuído esse objeto para a variável funcionario e executado o método nomeCompleto. Dois pontos são importantes de serem analisados no código acima, o primeiro é que para executarmos um método de uma classe ou até mesmo para acessar os atributos de uma classe usamos o . (ponto) que nesse caso serve como operador de acesso aos elementos de uma classe, então nesse caso foi usado o operador . (ponto) para acessar e executar o método nomeCompleto e o segundo ponto que talvez não possa ter ficado claro é que quando criamos um objeto no Java estamos criando algo que é único, por mais que eu possa criar vários objetos do tipo Funcionario com os mesmos valores eles serão objetos diferentes para o Java pois serão criados e alocados em diferentes espaços de memória, para ficar claro vamos criar dois objetos com os mesmos dados e fazer uma comparação entre eles:

public static void main(String[] args) {
    Funcionario funcionario = new Funcionario("Guilherme", "Alves", 35, "São Paulo", "Desenvolvimento");
    Funcionario funcionarioII = new Funcionario("Guilherme", "Alves", 35, "São Paulo", "Desenvolvimento");
    System.out.println(funcionario.equals(funcionarioII));
    System.out.println(funcionario.toString());
    System.out.println(funcionarioII.toString());
}

Criamos dois objetos do tipo Funcionario e usamos o método equals, logo falaremos sobre ele, para saber se os objetos são iguais, logo após foi executado o método toString, também falaremos sobre ele, para imprimir na tela o valor textual desses objetos, o resultado foi:

false
br.com.company.artigoiv.Funcionario@27f674d
br.com.company.artigoiv.Funcionario@1d251891

O resultado foi false para a verificação de igualdade entre os objetos; o resultado irá variar em cada computador pois o método toString do jeito que está agora exibe o nome da classe completo mais o valor hexadecimal que representa o endereço de memória onde está o objeto e podemos entender que apesar de terem os mesmos valores esses objetos estão em endereços de memória diferentes.

Aproveitando o assunto de classes, no artigo anterior foi comentado sobre o modificador static e que ao usá-lo o atributo ou método passa a pertencer a classe e não mais uma instância, vamos entender um pouco melhor o que isso significa.

Vamos imaginar que todo funcionário possua um CPF, é só um exemplo hipotético para explicar o conceito de static, então como todo funcionário possui esse atributo poderíamos deixar esse tipo de documento como sendo uma constante:

public static final String TIPO_DOCUMENTO = "CPF";

E podemos usar essa constante em qualquer lugar sem ter a necessidade de ter uma instância de Funcionario para funcionar:

public static void main(String[] args) {

    System.out.println("O tipo de documento de todo funcionario é o " + Funcionario.TIPO_DOCUMENTO);

}

Bastando importar essa constante diretamente a partir da classe Funcionario e o mesmo é válido para métodos que também podem ser estáticos, em casos onde algum comportamento independa de um objeto criado, para esse exemplo vamos criar um método estático dessa mensagem que imprimimos na tela:

public class Funcionario {

    public static final String TIPO_DOCUMENTO = "CPF";

    public static String imprimeTipoDeDocumentoDosFuncionarios(){
        return "O tipo de documento de todo funcionario é o " + Funcionario.TIPO_DOCUMENTO;
    }
}

E para usar:

public static void main(String[] args) {

    Funcionario.imprimeTipoDeDocumentoDosFuncionarios();

}

Da mesma forma como foi feito com a constante, não é necessário existir uma instância de Funcionario para esse método funcionar.

Encapsulamento

Após essa introdução às classes, construtores e atributos já é possível entender que uma classe é um container que guarda atributos (dados) sobre um determinado assunto, no nosso exemplo dados de um Funcionário e métodos (ações) que podemos executar a partir de uma instância de um objeto.

No exemplo anterior foi criado um objeto Funcionario usando o construtor e passando todos os dados de um funcionário, porém nem sempre isso está disponível, pense em um empresa onde na contratação de um funcionário ele pode enviar depois alguns documentos como o comprovante de endereço por exemplo e nesse caso o que poderíamos fazer?

Podemos criar mais um construtor sem o atributo endereço por exemplo, mas já temos dois construtores criados e o nosso código pode ficar poluído. Existia um padrão que era chamado de Construtor Telescópio que consistia em criar vários construtores começando desde o construtor sem argumentos e aumentando até o construtor com todos os argumentos, no nosso código ficaria assim:

public Funcionario() {
}

public Funcionario(String nome) {
    this.nome = nome;
}

public Funcionario(String nome, String sobrenome) {
    this.nome = nome;
    this.sobrenome = sobrenome;
}

public Funcionario(String nome, String sobrenome, int idade) {
    this.nome = nome;
    this.sobrenome = sobrenome;
    this.idade = idade;
}

public Funcionario(String nome, String sobrenome, int idade, String endereco) {
    this.nome = nome;
    this.sobrenome = sobrenome;
    this.idade = idade;
    this.endereco = endereco;
}

public Funcionario(String nome, String sobrenome, int idade, String endereco, String departamento) {
    this.nome = nome;
    this.sobrenome = sobrenome;
    this.idade = idade;
    this.endereco = endereco;
    this.departamento = departamento;
}

A classe Funcionario está ficando cada vez maior e até o momento só temos um método, se essa classe adicionar mais um atributo terá que acrescentar mais um construtor e quando tiver mais métodos a leitura e o entendimento vão ficar muito difíceis por conta de um código que só existe para criar um objeto. Então você pode perceber que esse padrão não é mais usado, mas agora ainda temos que resolver o problema de como criar um objeto Funcionario sem o endereço ou outros dados e depois adicioná-los.

Podemos criar um objeto Funcionario com o construtor padrão e depois atribuir os valores a ele:

Funcionario funcionarioIII = new Funcionario();
funcionarioIII.nome = "Jose";
funcionarioIII.sobrenome = "Alves";

Se você tentou fazer isso percebeu que esse código não compila pois o atributo nome e sobrenome não são acessíveis. Mas por que isso acontece? Isso se deve ao fato de que na classe Funcionario os atributos estão com o modificador de acesso private tornando-os inacessíveis para outras classes.

Isso significa que ler esses atributos agora também se tornou impossível:

System.out.println(funcionarioIII.nome);

Esse código também não compila pelo mesmo motivo. Mas como poderemos trabalhar com os atributos e por que usar o modificador private para deixar os atributos inacessíveis?

Antes de mais nada vamos pensar que estamos trabalhando em uma grande equipe e que hoje escrevemos esse código e que não foi colocado o modificador private e depois de um tempo outro desenvolvedor sem saber muito bem as regras de um funcionário no sistema de RH modifica o código que atribui o nome a um funcionário e faz algo assim:

Funcionario funcionarioIII = new Funcionario();
funcionarioIII.nome = null;

O código vai continuar compilando e vai executar sem dar algum problema visível porém estará com uma falha pois agora o nome do funcionário é null. Para impedir esse tipo comportamento de acessar diretamente dados de uma classe é que o encapsulamento foi pensado.

Mas nesses casos como poderá ser resolvido o problema de acesso as variáveis pois é necessário adicionar ou ler valores na classe Funcionario?

Para esses casos existem dois métodos especiais que nos auxiliam que são os chamados métodos getters e setters, onde o get é usado para leitura de dados e o set para adição de valores, então o código da classe Funcionario ficaria assim:

public class Funcionario {

    private String nome;
    private String sobrenome;

    public String getNome() {
        return nome;
    }

    public void setNome(String nome) {
        this.nome = nome;
    }

    public String getSobrenome() {
        return sobrenome;
    }

    public void setSobrenome(String sobrenome) {
        this.sobrenome = sobrenome;
    }

}

No código acima voltamos o modificador private e foi adicionado os métodos get e set para cada atributo; o método getNome oferece acesso ao valor do atributo nome e método setNome recebe uma String e atribui o seu valor para a variável nome da classe, isso já cria uma camada sobre os atributos mas aparentemente nós só movemos o comportamento de ler/adicionar valores para uma complexidade maior porém existe uma vantagem aqui que nem sempre é compreendida, nós conseguimos através dessa camada bloquear ou validar informações de entrada ou saída como no exemplo a seguir:

public String getNome() {
    if(nome == null || nome.isEmpty() || nome.isBlank()){
        System.out.println("Valor do nome não foi preenchido");
        return "";
    }
    return nome;
}

public void setNome(String nome) {
    if(nome == null || nome.isEmpty() || nome.isBlank()){
        System.out.println("Valor deve ser preenchido");
        return;
    }
    this.nome = nome;
}

Foi feita uma validação prévia tanto na entrada como na leitura dos dados e para usar essa nova abordagem podemos fazer da seguinte maneira:

Funcionario funcionarioIII = new Funcionario();
funcionarioIII.setNome(null);
System.out.println(funcionarioIII.getNome());
funcionarioIII.setNome("Guilherme");
System.out.println(funcionarioIII.getNome());

No codigo acima criamos uma instância de Funcionario e atribuímos a variável funcionarioIII, depois usamos o método setNome porém passando null, após isso usamos o método getNome para imprimir na tela o valor que nome possui, e por fim usamos novamente o método setNome porém agora passando um valor real e novamente usamos o getNome para recuperar o seu valor. O resultado é:

Valor deve ser preenchido
Valor do nome não foi preenchido

Guilherme

Então foi possível um certo nível de proteção aos dados da classe Funcionario. Então com encapsulamento podemos ver que temos como proteger e controlar melhor os atributos dentro de uma classe, também existe uma flexibilidade maior caso quiséssemos deixar os valores impedidos de ser escritos, pois poderíamos facilmente retirar os métodos setters e deixar para atribuição de valores apenas no momento da criação da classe através do construtor do objeto e ter os atributos como apenas leitura que é um conceito muito utilizado quando é pensado em objetos imutáveis.

Existem outros modificadores de acesso que são tanto utilizados para controle de acesso quanto para outros comportamentos e irei citá-los aqui porém serão vistos com mais profundidade em outros assuntos mais pra frente:

public: Esse modificador já vimos tanto nas classes, métodos e atributos, quando algo é marcado com esse modificador tem o seu escopo mais abrangente podendo ser usado em todos pacotes ou lugares do código.
protected: Com esse modificador o atributo ou método só será visível em suas subclasses, será visto quando for falado sobre Herança.
default: Quando usado esse modificador o código só é acessível dentro do seu próprio pacote. Para usar esse modificador basta deixar sem nenhuma palavra reservada antes da classe, método ou atributo, se tentar um código default em outro pacote irá ocorrer o mesmo erro de compilação de quando tentamos acessar um atributo private.

Outros modificadores, que alguns já fora abordados, são:

final: Quando utilizado em classes significa que esta não pode ser herdada por outras classes; quando usado em métodos ou atributos significa que os mesmos não podem ser sobrescritos.
abstract: Quando utilizado em classes significa que esta classe é uma Classe Abstrata, um tipo diferente de classe que veremos mais a frente; quando utilizada em métodos dentro de uma Classe Abstrata é para que sua implementação seja realizada na subclasse.
static: Utilizado em métodos ou atributos que são pertencentes a classe e não a instância.
transient: Utilizado em métodos ou atributos faz com que não sejam serializados. Utilizado em alguns casos no contexto de envio de informações para banco de dados onde alguns atributos não devem ser persistidos, mas não se preocupe com isso agora pois mesmo a sua utilização não é tão frequente.
synchronized: Utilizados em métodos quando escrevemos códigos de acesso paralelo, mas novamente não muito utilizado.

Conclusão

Vimos nesse artigo como criar e usar classes, desde a sua sintaxe até como proteger dados com encapsulamento. Vimos que criar métodos getters/setters acaba deixando um voluma alto de código que é usado apenas para cumprir com requisitos da linguagem mas sem lógica para o problema que desejamos resolver, chamados de códigos boilerplate, porém existe hoje muitas ferramentas que auxiliam o desenvolvedor nesse aspecto, as próprias IDEs ajudam muito na geração automática desse código, como é o caso do IntelliJ, Eclipse ou VSCode, porém existem bibliotecas escritas no Java que foram feitas para nos ajudar como é o caso do projeto Lombok.

O código deste artigo se encontra no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java III

Mon, 27 Sep 2021 00:00:01 GMT

Dando continuidade a série de artigos sobre o Java hoje erá abordado métodos, escopo e recursão. Ao fim desse artigo você será capaz de entender esses conceitos e também conseguirá aplicá-los em projetos.

Métodos

Nos artigos anteriores foi mostrado alguns métodos porém não entramos a fundo sobre o que significava aquilo, porém agora chegou a hora de entendê-los a fundo. Um método é uma ação que é desenvolvida porém só deve ser executada em algum momento programado, um método é um bloco de código que deve ser executado em um momento específico do programa.

A vantagem de usar métodos é o reaproveitamento de códigos onde podemos escrever uma vez aquele bloco e ele poderá ser executado em outros pontos sem que aja a necessidade de reescrever sempre a mesma funcionalidade.

No código abaixo será escrito um método simples mas onde poderemos ver a sintaxe de um método no Java:

public String helloWorld(){
    return "Olá Mundo!";
}

O método que foi criado irá exibir a mensagem Olá Mundo!, porém o que é necessário prestar atenção é a sintaxe como isso foi feito. Um método pode ter um modificador de acesso que significa basicamente se esse método pode ser visto por outros arquivos dentro do seu programa, esse assunto será explorado de melhor forma quando for abordado o tema de programação orientada a objetos, mas saiba que são quatro os modificadores de acesso:

public: Com esse modificador queremos dizer que ele é público e pode ser usado em outros pontos e pacotes.
protected: O protected é usado em casos de Herança e veremos mais a frente.
private: Ele só poderá ser usado dentro do arquivo onde foi escrito.
sem modificador: Podemos não colocar nenhum modificador e isso indica que ele é visivel apenas dentro do pacote onde ele foi criado, se tentarmos usar um método em outro pacote ele não estará disponível para uso.

O segundo ponto é que após a palavra public existe a palavra String e esse é um ponto obrigatório na linguagem, todo método necessita de um retorno que indica o que aquele método irá devolver ao final do processamento, nesse caso o código retorna uma String, que pode ser visto com o trecho return “Olá Mundo” onde a palavra return também é obrigatória quando existe algum retorno, pode parecer contraditório estar escrito que é obrigatório haver um retorno de método sempre mas não ser obrigatório a palavra return mas isso acontece pois nem todo método retorna alguma coisa mas todo método precisa de um retorno. Pode ter ficado meio confuso mas já explico, um método por vezes pode ser somente uma execução sem ter um valor para retornar, para ser mais claro segue um exemplo de um método que exibe um texto no console:

public void printHelloWorld(){
    System.out.println("Olá Mundo!");
}

O método printHelloWorld não tem um valor para ser retornado após a sua execução, ele só exibe uma mensagem e acaba, para esses casos ainda assim é necessário informar um retorno na assinatura desse método e pensando nisso é usada a palavra reservada void que indica que esse método é uma execução mas que não retorna nada após o seu fim, sendo assim não é necessário a palavra return dentro do método.

Após isso é necessário definir o nome do método, em Java usamos o que chamamos de camel case para nomenclaturas tanto de métodos como variáveis ou classes onde escrevemos tudo junto em minúsculo e separamos as palavras com letras maiúsculas então nesse caso o nome do método ficou printHelloWorld.

Todo método após o seu nome possui parênteses () isso serve para quando é necessário passar argumentos para um método, você já viu isso antes no método main onde ele possui String[] args, um array de argumentos, porém mesmo que não exista argumentos em um método é necessário ter os parênteses, para deixar claro como é um método onde existem argumentos segue o exemplo abaixo:

public void printHelloWorld(String nome){
    System.out.println("Olá Mundo " + nome + "!");
}

O método acima possui o que é chamado de parâmetros, que é a forma de passar informação para a execução de um método. Nesse caso é passado a variável chamada nome que é do tipo String para que seja executada dentro do método printHelloWorld.

Um método pode ter nenhum ou vários parâmetros como no exemplo abaixo:

public void printHelloWorld(String nome, int idade){
    System.out.println("Olá " + nome + " que tem " + idade + " anos!");
}

Toda essa sintaxe de modificadores de acesso, retorno do método, nomenclatura e argumentos é chamado de assinatura do método.

Em um método que possui um retorno diferente de void é possível que o seu valor seja atribuído a uma variável para que seja usado em outros pontos do programa:

public int soma(int x, int y){
    return x + y;
}

int resultado = soma(1, 2);

System.out.println("O valor da soma é " + resultado);

No exemplo acima foi definido o método soma que recebe dois argumentos como parâmetros do tipo int, executa a soma e retorna o valor. Foi possível capturar o retorno do método e atribuí-lo à variável resultado que foi usada mais abaixo para exibir a mensagem.

Para que os métodos acima sejam executadas e funcionem é necessário uma instância de classe pois todo método ou variável que não for static pertence a uma instância de classe, esse assunto será amplamente abordado em orientação a objetos. Isso significa que é necessário construir um objeto e usar o operador de acesso . (ponto):

public class ExemploMetodos {

    public void helloWorld(){
        System.out.println("Olá Mundo!");
    }

    public static void main(String[] args) {
        ExemploMetodos exemploMetodos = new ExemploMetodos();

        exemploMetodos.helloWorld();
    }

}

No exemplo acima foi criada a classe ExemploMetodos que possui o método helloWorld mas só será possível usar o método se existir uma instância ou objeto criado da classe ExemploMetodos e para acessar o método dessa instância é necessário usar o operador . (ponto).

Escopo

No Java uma variável é acessível dentro do bloco onde ela foi criada e isso é chamado de escopo.

Para entender o que é escopo é necessário ver os códigos que foram feitos até aqui:

public class ExemploEscopo{

    public void mostraIdade(int idade){
        System.out.println("A idade é " + idade);
    }

    public void mostraIdadeII(){
        System.out.println("A idade é " + idade);
    }
}

O código acima não compila no método mostraIdadeII com o erro: Cannot resolve symbol ‘idade’. Mesmo a variável idade existindo no método mostraIdade o escopo dela é pertencente ao método onde ela foi declarada então ela se torna inacessível fora do método mostraIdade. Para o código acima funcionar seria necessário definir a variável idade em um escopo onde ela fosse visível nos dois métodos:

public class ExemploEscopo{

    int idade = 20;

    public void mostraIdade(){
        System.out.println("A idade é " + idade);
    }

    public void mostraIdadeII(){
        System.out.println("A idade é " + idade);
    }
}

Agora a variável idade está em um escopo maior e é visível em dentro da classe ExemploEscopo.

Todos os blocos no Java possuem contexto de escopo, seja classes, métodos, condicionais ou laços de repetição isso significa que uma variável definida dentro de um bloco if/else só existe dentro do bloco, ela nasce e morre dentro do bloco não sendo acessível fora:

public void metodoEscopoIf(){

    if(true){
        int valor = 0;
    }

    System.out.println("O valor é " + valor);
}

O código acima também não compila com o erro: Cannot resolve symbol ‘valor’. Isso ocorre por que mesmo que esse bloco if sempre seja executado, pois é um bloco if com true, a variável valor é inciada dentro do bloco if e “vive” somente dentro do bloco if após encerrar o bloco a variável valor deixa de existir.

O mesmo é válido para laços de repetição:

for (int indice = 0; indice <= 10; indice++){
    System.out.println("O valor do indice é " + indice);
}

System.out.println(indice);

Mais uma vez esse código não compila e o erro é o mesmo, pois a variável indice foi inicializada dentro do bloco for e não existe e não é visível fora do bloco.

O conceito de escopo é aplicável para todos os bloco de códigos sejam eles os outros blocos condicionais, estruturas de repetição ou classes.

Recursão

Recursividade é a capacidade de um código se executar repetidas vezes. Para explicar melhor será mais fácil exemplificar a recursão com exemplos, então imaginando um problema onde desejamos exibir na tela a sequência de um número até 0:

public void exibirSequencia(int numero) {

    if (numero == 0) {
        return;
    }

    System.out.println(numero);

    exibirSequencia(--numero);
}

Esse código usa recursão para exibir a sequência de números. Mas vamos entender linha por linha como a recursão é executada nesse código:

Quando o valor de numero for igual a 0 (zero), para a chamada do método recursivo.
O valor atual da variável número é exibida.
O método exibirSequencia é executado novamente porém agora com o valor da variável numero é pré-decrementado, diminuído, em menos 1.

Um cuidado em chamadas recursivas é que facilmente podem gerar loops infinitos e erros do tipo Estouro de pilha ou StackOverflowError onde a memória de execução do programa estoura, para simular esse erro não é difícil no código que testamos, basta alterar o pré-decremento da variável numero para pós-decremento e testar:

public void exibirSequencia(int numero) {

    if (numero == 0) {
        return;
    }

    System.out.println(numero);

    exibirSequencia(numero--);
}

Esse código irá executar várias vezes com o mesmo resultado mas em algum momento irá quebrar com o seguinte erro:

Exception in thread "main" java.lang.StackOverflowError

Por esses motivos é recomendado só usar recursão em casos pequenos ou fáceis de monitorar, pois algoritmos mais complexos podem causar erros que só podem ser percebidos posteriormente ou que são difíceis de entender.

Conclusão

Nesse artigo foi apresentado métodos, como criá-los e usá-los, também foi mostrado sobre assinatura de métodos, modificadores de acesso, retorno e parâmetros; aprendeu também sobre escopos e como o Java lida com blocos de contexto.

E por fim também foi apresentado recursão que é uma ferramenta muito importante da linguagem mas que deve ser usada com cuidado para não gerar erros inesperados.

No próximo artigo iremos entrar em Programação Orientada a Objetos.

O código dos exemplos está no GitHub

Visite também o nosso canal no Youtube para mais acompanhar essa série de Primeiros passos com o Java e muito mais conteúdos sobre programação.

Primeiros passos com Java II

Mon, 13 Sep 2021 00:00:01 GMT

No artigo anterior foi apresentado a linguagem Java, foi abordado um pouco da história, como criar um projeto Java no IntelliJ, variáveis, contantes, tipos e operadores.

Dando continuidade nesse artigo será abordado as estruturas de controle do Java como condicionais, laços de repetição e arrays. No final desse artigo você será capaz de entender o propósito de cada uma dessas estruturas de controle, saberá como usá-las e também será abordado o tema arrays e como eles se relacionam com laços de repetição.

If/Else

A primeira estrutura de controle a ser abordada será a estrutura de controle condicional If/Else que pode ser traduzido para Se/Senão. Essa estrutura faz uso direto da lógica Booleana que foi vista no primeiro artigo para que alguma decisão seja tomada no código.

A estrutura if/else funciona a partir de um valor booleano onde caso seja verdadeiro entrará na primeira condição e caso não seja verdadeiro entrará na segunda opção:

if(*declaração*){

}else{

}

Para entender melhor vamos explorar um exemplo básico onde temos um software que precisa avaliar se uma pessoa é maior de 18 anos e caso seja irá exibir uma mensagem e caso não seja irá exibir outra, vamos também aproveitar para começar a ver algumas bibliotecas padrão do Java que nos auxiliam como a API java.time:

LocalDate dataNascimento = LocalDate.of(1986, 03, 25);

var dataHoje = LocalDate.now();

Period period = Period.between(dataNascimento, dataHoje);

if(period.getYears() > 18){
    System.out.println("É maior de idade");
}else{
    System.out.println("Não é maior de idade");
}

System.out.println("Fim da execução");

Entendo o código acima temos a utilização da classe LocalDate que vem do pacote java.time que foi inserido no Java 8 e facilita muito o trabalho com datas, fazemos uso do método of, não se preocupe agora em entender o que é um método mas saiba que ele representa uma ação que será executada, onde é passado o ano, mês e dia e então é atribuído a uma variável chamada dataNascimento, logo abaixo é usado novamente a classe LocalDate porém com o método now que é usado quando queremos capturar a data atual e por fim atribuímos ele na variável dataHoje, note que foi utilizado a palavra reservada var ao invés da classe LocalDate que é um recurso do Java 9 e foi deixado aqui pra exemplo, em um caso real é bom manter um padrão onde deixamos todas as variáveis com var ou com o seu retorno para não haver confusão no código. Por fim logo abaixo foi utilizado a classe Period e o método between que faz a comparação entre duas data e conseguimos extrair o período entre elas.

A classe Period possui algumas informações que podemos trabalhar e entre elas trás o período de anos entre as duas datas e com isso conseguimos aplicar a lógica que pretendemos, que é verificar se pela data de nascimento já se passaram 18 anos ou não, então focando no trecho que interessa para entender a estrutura if:

if(period.getYears() > 18)

Se fossemos ler esse trecho poderíamos ler da seguinte forma: Se for verdade que o período de anos é maior do que 18 então…

Dessa forma caso isso seja verdade então o código a ser executado será o que estiver entre as chaves:

if(period.getYears() > 18){
    System.out.println("É maior de idade");
}

E para entender a estrutura else basta entender que caso a condição dentro do bloco if não seja verdadeira quem será executado será o que estiver entre chaves após a palavra else:

if(period.getYears() > 18){
    System.out.println("É maior de idade");
}else{
    System.out.println("Não é maior de idade");
}

Então rodando o exemplo acima de uma pessoa com data de nascimento em 25 de Março de 1986 (35 anos) a saída no terminal será:

É maior de idade
Fim da execução

Repassando mais uma vez passo a passo a execução do código dando foco ao bloco if/else:

1° Dentro do bloco if foi avaliado se 35 é maior do que 18.
2° Isso sendo verdade true ele “entrou” dentro da primeira condição e executou o que tinha lá dentro, nesse caso o print com a frase É maior de idade.
3° Não será executado o que tem dentro do else já que o primeiro bloco foi executado.
4° Prosseguiu com o programa e printou a frase Fim da execução.

Um último ponto importante do if/else no Java é que as chaves {} no if não são obrigatórias porém caso sejam omitidas somente a primeira linha após o if será executada como sendo parte do bloco if, isso facilita a escrita mas pode gerar confusões e bugs onde comportamentos que só deveriam ser executados dentro do if aparentemente estão sendo executados fora:

if(period.getYears() > 40)
    System.out.println("Executa lógica do if");
    System.out.println("Só pode executar se for maior de 40");

System.out.println("Fim da execução");

Olhando para o código acima parece que a intenção é executar os dois prints somente se for maior de 40 anos, porém rodando esse código a saída será:

Só pode executar se for maior de 40
Fim da execução

Isso ocorreu por que somente a primeira linha após o if foi considerada ao bloco, é como se para o compilador o código estivesse assim:

if(period.getYears() > 40){
    System.out.println("Executa lógica do if");
}
System.out.println("Só pode executar se for maior de 40");

System.out.println("Fim da execução");

E nesse caso foi avaliado que 35 não é maior do que 40 e não foi executado a primeira linha porém o programa prosseguiu e executou a linha que o desenvolvedor não queria que fosse executada caso a idade fosse menor do que 40, gerando um bug no código que nem sempre é fácil de entender a primeira vista.

Switch

Agora vamos imaginar que você é um desenvolvedor em uma empresa de pagamentos eletrônicos e você precisa receber os pagamentos de diversas bandeiras de cartão e processá-los, nesse exemplo hipotético você poderia usar uma estrutura if/else if/if para processar essa lógica:

String cartao = "Master";

if(cartao.equals("Master")){
    System.out.println("Processa Master");
}else if(cartao.equals("Visa")){
    System.out.println("Processa Visa");
}else if(cartao.equals("Amex")){
    System.out.println("Processa Amex");
}else if(cartao.equals("Elo")){
    System.out.println("Processa Elo");
}else {
    System.out.println("Não sei o cartão");
}

A estrutura if/else if/else não foi abordada no tópico anterior por um motivo, esse código é difícil de ler e dar manutenção e eu considero uma má prática.

Pensando nisso existe a estrutura switch onde existe um pouco mais de legibilidade do código, apresentando a estrutura switch:

switch(*declaração*){
  case *condição*:
    //Ação
    break;
  default:
    //Ação
    break;
}

A estrutura do switch é maior mas não é complicada, na inicialização do bloco switch informamos o dado que deve ser avaliado, e aqui entra um ponto importante do switch já que ele trabalha com outros tipos de dados diferentemente do if/else que só trabalha com boolean, podendo trabalhar com os tipos primitivos byte, short, char, e int, também trabalha com Enums, ainda não chegamos nesse assunto mas em breve chegaremos, Strings e as classes Wrappers Character, Byte, Short, e Integer, também não chegamos nelas mas logo será abordado.

Voltando ao switch, informamos o que será avaliado e caso seja algum dos valores que determinamos nas cláusulas case o código é executado, por fim caso nenhum dos case seja executado a cláusula default é executada, vamos ver como ficaria o exemplo de cartões utilizando essa abordagem:

String cartao = "Master";
        
switch (cartao){
    case "Master":
        System.out.println("Processa Master");
        break;
    case "Visa":
        System.out.println("Processa Visa");
        break;
    case "Amex":
        System.out.println("Processa Amex");
        break;
    case "Elo":
        System.out.println("Processa Elo");
        break;
    default:
        System.out.println("Não sei o cartão");
}

Executando esse código a saída será:

Processa Master

O código fica mais fácil de ler, você pode estar se perguntando: O que significa o break dentro do switch?

Ele serve como cláusula de escape do bloco switch, isso significa que se não fosse adicionado o break em cada case a partir do momento em que um case fosse executado todos os abaixo seriam executados, vamos tirar o break e executar o código para deixar claro:

String cartao = "Master";

switch (cartao){
    case "Master":
        System.out.println("Processa Master");
    case "Visa":
        System.out.println("Processa Visa");
    case "Amex":
        System.out.println("Processa Amex");
    case "Elo":
        System.out.println("Processa Elo");
    default:
        System.out.println("Não sei o cartão");
}

A saída será:

Processa Master
Processa Visa
Processa Amex
Processa Elo
Não sei o cartão

Como o valor era Master e ele era o primeiro case após ele ser executado todos os outros case foram executados e até mesmo o default foi executado.

Outra combinação possível é a situação onde mais de um case possui o mesmo processamento, vamos imaginar que queremos processar os meses do ano que tem 30 dias ou 31 dias podemos fazer assim:

 int mes = 3;

switch (mes) {
    case 1: case 3: case 5:
    case 7: case 8: case 10:
    case 12:
        System.out.println("Mês com 31 dias");
        break;
    case 4: case 6:
    case 9: case 11:
        System.out.println("Mês com 30 dias");
        break;
    case 2:
        System.out.println("Fevereiro pode ter 28 ou 29 dias");
        break;
    default:
        System.out.println("Mês inválido");
        break;
}

A saída desse programa será:

Mês com 31 dias

É possível aninhar cláusulas case mas tomando cuidado para isso não ferir a legibilidade do código.

While

O bloco while inaugura um tipo diferente de estrutura de controle, pois ele é uma estrutura de repetição e ele pode ser traduzido como enquanto, isso significa que ele irá se repetir enquanto uma condição for verdadeira, então podemos entender que o bloco while trabalha com booleanos. Para ficar mais claro segue a declaração do bloco while:

while(*condição*){

}

Como podemos ver é bem curta a declaração dele.

Então vamos imaginar um problema simples onde queremos mostrar na tela os números de 0 à 5, o while poderia ser usado nesses casos:

int indice = 0;

while (indice <= 5){
    System.out.println(indice);
    indice++;
}

Rodando o código termos como saída:

O interessante nesse código é que foi feito uso de pós-incremento com o operador ++, então analisando passo-a-passo o código:

1° A variável indice começa com o valor 0.
2° O bloco while faz a checagem se o valor de indice é menor ou igual a 5, se for executa o que estiver dentro do bloco while.
3° Dentro do bloco while printa na tela o valor atual da variável indice.
4° Pós-incrementa o valor da variável indice em 1 então nesse momento ela irá valer 1.
5° Retorna para o início do bloco while e verifica se o valor da variável indice é menor ou igual a 5, se for executa tudo de novo e se não for sai do laço de repetição.

O laço while também é muito usado quando se trabalha com Iterators que são coleções de dados no Java ligadas umas as outras onde cada uma sabe se existe um próximo na lista, mas não veremos isso por enquanto pois hoje em dia os Iterators perderam um pouco da força que tinham pois existem outras formas que as versões mais novas do Java lidam com esse tipo de estrutura de dados.

Do/While

Agora iremos entender a estrutura Do/While, que seria algo mais parecido com Faça/Enquanto traduzindo literalmente para o português, apesar da palavra while existir a ideia dele é um pouco diferente da estrutura while do tópico acima. A ideia por trás desse laço de repetição é que uma ação seja executada primeiramente e após isso seja avaliado se deve ser repetida ou não, a declaração dele é assim:

do {
    *declaração*
} while (*expressão*);

No trecho de código acima existe a inicialização do bloco com a palavra do, então o que estiver dentro desse bloco será executado pelo menos uma vez e após isso existe a palavra while onde será avaliada alguma expressão booleana e caso seja true irá repetir o que estiver dentro do bloco do.

Vamos pensar em um exemplo onde queremos mostrar na tela os números de 0 até 10 usando a estrutura do/while:

int contador = 0;
do {
    System.out.println("Contador é: " + contador);
    contador++;
} while (contador < 11);

System.out.println("Finalizado programa");

Rodando esse programa a saída na tela será assim:

Contador é: 0
Contador é: 1
Contador é: 2
Contador é: 3
Contador é: 4
Contador é: 5
Contador é: 6
Contador é: 7
Contador é: 8
Contador é: 9
Contador é: 10
Finalizado programa

Perceba que no início do código o bloco do é executado de primeira, imprime na tela a mensagem, após isso o valor da variável contador é incrementada, na sequência é avaliado dentro do while se o valor da variável contador é menor do que 11 e caso seja verdade (true) é repetido o fluxo dentro do bloco do, quando a variável contador chega o valor 11 o programa sai da estrutura do/while e o programa continua.

Para deixar um exemplo um pouco mais real ao invés de ficar percorrendo por números, vamos imaginar um programa que simule um despertador, ele irá tocar a primeira vez e depois irá verificar se está no modo soneca, caso ainda esteja irá tocar até que a pessoa desligue o alarme.

public static void main(String[] args) throws InterruptedException {

    do{
        System.out.println("SOAR ALARME: dim! drim! alarme de relógio");
    }while (despertadorEstaNaSoneca());

    System.out.println("Finalizado programa");

}

private static boolean despertadorEstaNaSoneca() throws InterruptedException {
    Thread.sleep(1000);
    return new Random().nextBoolean();
}

Explicando o código acima temos o bloco do que inicia o despertador, na sequência temos um método chamado despertadorEstaNaSoneca que verifica se ainda está na soneca e devolve um booleano, ele usa o Thread.sleep(1000); para esperar um segundo e depois executa o new Random().nextBoolean(); que escolhe se será true ou false randomicamente, isso significa que aleatoriamente vai ser escolhido se será true ou false, enquanto o despertadorEstaNaSoneca rodar e for true o bloco do irá se repetir. Não se preocupe muito com toda a sintaxe pois tudo isso será explicado mais pra frente, no momento em que foi rodado esse programa a saída foi:

SOAR ALARME: dim! drim! alarme de relógio
SOAR ALARME: dim! drim! alarme de relógio
Finalizado programa

Se for executado de novo esse programava pode haver mudança pois como é escolhido de forma aleatoria se é true ou false pode ser que demore mais.

For

O laço de repetição for é uma estrutura de repetição para situações onde é conhecido quantas vezes é necessário repetir uma tarefa. Em comparação com while e do/while onde o laço será repetido até que uma condição seja atendida a declaração do for já pede de antemão que seja informado a quantidade de vezes que será executado o código:

for (declaração 1; declaração 2; declaração 3) {
  // código a ser executado
}

Entendendo cada parte da declaração:

A primeira declaração é executada uma vez dentro do bloco for e é a inicialização da variável de controle.
A segunda declaração define a condição que será executada no bloco for.
A terceira declaração será executada sempre que houver uma repetição no bloco for.

Adicionando um exemplo mais prático iremos imprimir na tela os números de 0 até 10:

for (int indice = 0; indice <= 10; indice++){
    System.out.println(indice);
}

E a saída será:

Podemos ver que as três condições do bloco for foram atendidas, primeiro iniciamos uma variável chamada indice com valor 0, depois foi definido a condição de parada desse bloco sendo o valor da variável indice menor ou igual a 10 e por fim declaramos que a cada fez que o bloco for repetido o valor de indice deve ser incrementado em 1 e dentro do bloco mandamos imprimir o valor atual da variável indice.

É muito útil esse laço de repetição quando estamos trabalhando com listas do Java pois essa estrutura de dados já possui formas para sabermos o seu tamanho total, no exemplo abaixo fica um pouco mais claro:

var lista = List.of("Arroz", "Feijão", "Macarrão", "Óleo");

for (int indice = 0; indice < lista.size(); indice++) {
    System.out.println(lista.get(indice));
}

No código acima simulamos que temos uma lita de mercado e no laço for fazemos uso do método size que já diz qual é o tamanho dessa lista e dentro do bloco for mandamos imprimir o valor da lista de acordo com o índice. Valendo ressaltar que ainda não foi abordado listas e coleções de dados mas adiantando que listas no Java são coleções de dados que começam com o seu índice em 0.

Executando esse código a saída será:

Arroz
Feijão
Macarrão
Óleo

Existe outra forma de executar o laço for que é chamado de Enhanced-for ou for melhorado em tradução livre e é assim:

for (String l : lista){
    System.out.println(l);
}

Ele possui uma forma mais curta para escrever o código for porém ele só é possível de ser feito em coleções de dados que tenham o método size implementado pois por debaixo dos panos ele vai executar um for tradicional, ele é mais uma facilidade para o desenvolvedor.

Break/Continue

Agora que foi apresentado as estruturas de controles e repetições iremos ver as cláusulas break e continue, o break foi previamente apresentado na explicação do switch e agora ele será aprofundado em detalhes.

Imagine a seguinte situação onde você, como desenvolvedor, precisa escrever um código onde você possui uma lista e se houver algum valor específico nessa lista você precisa que pare todo o processamento ou dependendo do valor você quer ignorar e ir para o próximo valor, como poderia ser feito isso? É isso que o break e o continue fazem, vamos abordar primeiramente o break.

A cláusula break interrompe um laço de repetição ou no caso do switch para sair do bloco, vamos ver no exemplo:

for (int i = 0; i <= 10; i++){
    System.out.println("i = " + i);
    if(i == 5){
        System.out.println("Vai sair do for no valor 5");
        break;
    }
    System.out.println("proxima iteracao");
}

System.out.println("Finalizou");

E a saída desse programa será:

i = 0
Proxima iteracao
i = 1
Proxima iteracao
i = 2
Proxima iteracao
i = 3
Proxima iteracao
i = 4
Proxima iteracao
i = 5
Vai sair do loop no valor 5
Finalizou

Se não houvesse o break nesse código ele iria imprimir até o valor 10 pra depois finalizar mas o break forçou o encerramento dele, o mesmo podemos fazer com while:

int i = 0;
while (i <= 10){
    System.out.println("i = " + i);
    if(i == 7){
        System.out.println("Vai sair do while no valor 7");
        break;
    }
    i++;
}

E teremos como saída:

i = 0
i = 1
i = 2
i = 3
i = 4
i = 5
i = 6
i = 7
Vai sair do while no valor 7
Finalizou

Mas e se precisarmos somente ignorar algum valor mas sem parar o processamento?

Para esse caso entra a cláusula continue que vai pular aquela iteração e passar para a próxima, vamos ver no exemplo abaixo para ficar mais claro:

for (int i = 0; i <= 10; i++){
    if(i == 5){
        System.out.println("Vai pular no valor 5");
        continue;
    }
    System.out.println("i = " + i);
    System.out.println("Proxima iteracao");
}

System.out.println("Finalizou");

E teremos como saída:

i = 0
Proxima iteracao
i = 1
Proxima iteracao
i = 2
Proxima iteracao
i = 3
Proxima iteracao
i = 4
Proxima iteracao
Vai pular no valor 5
i = 6
Proxima iteracao
i = 7
Proxima iteracao
i = 8
Proxima iteracao
i = 9
Proxima iteracao
i = 10
Proxima iteracao
Finalizou

Aqui podemos ver que no momento em que a variável i estava com valor 5 a cláusula continue pulou para o próximo valor e continuou o processamento.

Arrays

Arrays em Java são uma forma de guardar múltiplos valores em uma única variável e isso é algo muito útil para trabalhar com coleções de dados, conjuntos ou listas.

Existe duas formas de inicializar um array:

int[] array = new int[10];

Aqui podemos ver a sintaxe de um array onde é obrigatório definir o tipo desse array, o seu tamanho inicial e é necessário os colchetes [], podemos também declarar um array da seguinte forma:

int outroArray[] = new int[10];

Onde os colchetes [] estão após o nome da variável mas não é muito usual e também agora podemos declarar um array sem precisar dizer explicitamente o seu tipo:

var arraySemTipoExplicito = new int[10];

Apesar desse array não possuir o seu explicitamente tipado na variável o compilador consegue inferir o seu tipo então apesar da variável arraySemTipoExplicito não ter um tipo declarado o compilador entende que é um array de int com 10 posições.

Um ponto em comum com essas três declarações é que quando criamos um array utilizando a palavra reservada new, que é a palavra usada para criarmos em memória o array, é obrigatório informar o tamanho que esse array vai ter pois é necessário reservar espaços na memória para guardar os valores que podem ser preenchidos.

Após criar um array podemos inserir valores em cada posição dele e para isso temos que entender como um array é indexado. O índice de um array sempre começa em 0 então um array de 10 posições é acessível de 0 até 9, isso é muito importante pois se tentarmos acessar um posição inválida dentro de um array será lançado um erro no programa.

Então para adicionar valores em cada posição do array pode ser feito dessa maneira:

array[0] = 1;
array[1] = 2;
array[2] = 3;
array[3] = 4;
array[4] = 5;
array[5] = 6;
array[6] = 7;
array[7] = 8;
array[8] = 9;
array[9] = 10;

Caso adicionemos valor em um índice que não existe:

array[10] = 10;

No momento da execução será lançado o seguinte erro:

Exception in thread "main" java.lang.ArrayIndexOutOfBoundsException: Index 10 out of bounds for length 10

Porém existe uma outra maneira para inicializar um array e iremos ver agora:

int[] arrayInicializado = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};

A diferença é basicamente que já criamos um array com os valores definidos.

Como todo array possui indices podemos acessar os seus valores através dos indices:

System.out.println(arrayInicializado[3]);

E saída será:

Seguindo a mesma lógica conseguimos alterar um valor dentro de um array pelo índice também:

arrayInicializado[0] = 10;
System.out.println(arrayInicializado[0]);

E agora o valor que inicialmente era 1 agora será 10.

Outra propriedade muito útil dos arrays é que quando nós criamos um array precisamos definir o seu tamanho, seja com new int[10] ou com os valores dentro de chaves {} e como arrays tem tamanho fixo nós temos condições de saber o seu tamanho sendo então muito usado para laços de repetição do tipo for, bastando com que seja usada a propriedade length:

for (int indice = 0; indice < arrayInicializado.length; indice++){
    System.out.println(arrayInicializado[indice]);
}

Ou podemos fazer uso do Enhanced-for também nesses casos:

for (int valor: arrayInicializado) {
    System.out.println(valor);
}

A diferença está no tamanho desse for e que não precisamos acessar o array no índice (arrayInicializado[indice]).

Vimos até o momento o modo mais comum de utilizar arrays, porém arrays podem ser multidimensionais isso significa que são arrays dentro de arrays não é algo muito comum mas dependendo do contexto pode ser utilizado porém sinceramente em minha experiência não é algo que se vê todo dia mas é bom ter esse conhecimento caso necessite resolver problemas ou caso se depare com algo assim em algum momento, então no exemplo iremos criar um array de duas dimensões:

int[][] arrayDimensional = { {1, 2, 3, 4}, {5, 6, 7} };

A primeira coisa que podemos notar é que precisamos adicionar dois colchetes [] na declaração da variável arrayDimensional e para cada array envolvemos com chaves {}, mas também poderíamos ter feito assim:

int[][] outroArrayDimensional = new int[4][3];

Para acessar, inserir ou alterar os valores dentro de um array multidimensional é necessário informar os dois valores, o primeiro para indicar qual array será utilizado e outro valor para informar qual o índice queremos acessar desse array:

System.out.println(arrayDimensional[0][2]);

Então nesse exemplo queremos acessar o primeiro array, lembrando que os índices sempre começam em 0, e dentro do primeiro array queremos o terceiro elemento, nesse caso o valor 3.

Se fosse necessário fazer um for em array multidimensional é possível e ficaria desse jeito:

for (int i = 0; i < arrayDimensional.length; i++) {
    for(int j = 0; j < arrayDimensional[i].length; j++) {
        System.out.println(arrayDimensional[i][j]);
    }
}

Nesse caso não é possível fazer uso do Enhanced-for pois é necessário trabalhar com os índices para acessar os dois arrays.

Podemos ver que é possível então trabalhar com arrays tridimensionais ou até com mais dimensões porém como podemos ver no código acima a legibilidade começa a ficar comprometida e para cada dimensão a mais no array precisaríamos aninhar outro laço for o que pode comprometer também a performance do programa dependendo da quantidade de elementos que cada array contenha.

Conclusão

Nesse artigo foi apresentado as estruturas de controle como if/else e switch vimos como criá-los e como usá-los, também vimos as estruturas de repetição com os laços while, do/while e for como podemos trabalhar com eles e em quais momentos usar cada um. Entendemos também as cláusulas break e continue como elas podem ser úteis quando precisamos interromper um processamento ou então ignorar um processamento mas sem parar o fluxo e por fim foi apresentado a estrutura de dados array e como podemos criá-los, acessar seus valores e percorrer seus dados com o laço for.

O link para o projeto que está no GitHub

Primeiros passos com Java

Mon, 06 Sep 2021 00:00:01 GMT

História

Com sua primeira versão lançada em 1995 por James Gosling pela Sun Microsystems a linguagem Java se popularizou muito pois usava uma síntaxe que tentava se assemelhar com C/C++ porém sem algumas das dificuldades que uma linguagem de nível mais baixo trás consigo. Ela trouxe uma abordagem diferente das linguagens que eram convencionadas à época com o lançamento da JVM (Java Virtual Machine), um ambiente virtual onde o código é executado e a possíbilidade de executar o código em múltiplas plataformas não mais havendo a necessidade de compilar versões específicas, não que seja algo exclusivo do Java o próprio Erlang já fazia isso em 1986 com a sua virtual Machine, JAM e posteriormente com a BEAM, com isso o Java adotou o slogan “Write once, run anywhere” (Escreva uma vez, rode em qualquer lugar). Outro ponto muito importante foi a adoção de um paradigma orientado a objetos (POO), pois era muito mais comum e utilizado o paradigma procedural apesar do C++ já possuir a possibilidade de utilizar o paradigma orientado a objetos, isso trouxe mais flexibilidade e dinâmismo ao código e por fim o terceiro ponto que considero que foi uma grande vantagem foi a utilização de um Garbage Collector, que consiste em um mecânismo que faz o controle de memória do código, era um problema muito comum na linguagem C onde o desenvolvedor precisa lidar com alocação e liberação de memória no código, o que nem sempre é fácil ou trivial de se fazer e que acabava causando “vazamentos” de memória em aplicações. Tudo isso fez com que o Java se tornasse muito popular para desenvolvimento de aplicações que rodassem embarcadas em outras aplicações, os applets, desenvolvimento desktop, mobile e web.

Em 2005 a Oracle adquiriu a Sun por US$7.4 bilhões e prometeu continuar desenvolvendo e melhorando a linguagem, algo que era uma cobrança recorrente da comunidade pois lançamentos de melhorias demoravam muito. Até o momento desse artigo o Java está na versão 11LTS com previsão da versão 17LTS em 14 de setembro de 2021.

Instalação

Para instalar basta seguir essas orientações de acordo com o seu sistema operacional:

Windows

Linux

Mac

Iniciando um projeto

Nesses exemplos eu irei usar a IDE IntelliJ para criar o projeto e rodar os exemplos, a escolha é pela facilidade que essa IDE oferece de configuração e o suporte para o Java.

Poderíamos também criar os arquivos .java e compilá-los diretamente por linha de comando com o javac porém o intuito é fazer da forma mais parecida com o que é feito no dia a dia de um desenvolvedor.

Primeiramente é necessário instalar o IntelliJ, após abrí-lo clique em New Project como na imagem abaixo:

Após isso irá aparecer várias opções mas por enquanto basta deixar selecionado a opção Java e clicar em Next.

Na próxima tela selecione a opção Create project from template e a opção Command Line App ficará disponível para clicar, isso já criará um programa Java executável.

E por fim é necessário nomear o projeto, definir a pasta onde será salvo e o nome do pacote base. Os dois primeiros são simples de entender mas o terceiro é necessário pois todo programa Java é organizado em pacotes onde o código fica e este nome deve ser único por aplicação então foi convencionado de que o nome do pacote deveria ser o a URL da empresa ao contrário nesse caso ficou assim: br.com.company.

E após isso basta clicar em Finish o projeto será criado.

Entendendo o primeiro projeto

Quando um projeto novo é criado automaticamente é criado a classe Main.java com o seguinte código:

package br.com.company;

public class Main {

    public static void main(String[] args) {
    }
}

Essa é a sintaxe básica de um programa Java pois todo programa executável em Java necessita ter um método de entrada chamado main que seja public static void, entenderemos melhor o que isso significa adiante, e que receba um array de String, também entenderemos mais adiante o que isso significa, mas saiba que sem isso o programa não consegue ser executado pois no momento da execução de um programa o Java tenta localizar um método que siga esse modelo para iniciar.

Note também que na primeira linha do código aparece o nome do pacote.

Variáveis

Variáveis são posições de memória que são capazes de reter e representar expressões, elas existem em tempo de execução de um programa e tem nomes que são escolhidos pelo desenvolvedor para as identificar.

Esclarecendo melhor a explicação acima, uma variável nada mais é do que algo onde podemos colocar um valor e depois podemos trocar por outro, no exemplo abaixo fica um pouco mais claro:

int numero = 1;
numero = 2;

No trecho acima foi criado uma variável com nome “numero”, por debaixo dos panos o Java irá reservar um espaço em memória para guardar o valor que foi definido, primeiramente com o número 1 e em seguida foi adicionado outro valor para a variável “numero” com o valor 2. Nesse momento outro espaço de memória é criado e nele é guardado o valor 2. Isso só é possível pois estamos usando uma variável e como o seu nome dá a entender o seu valor pode ser mudado.

Perceba também que antes da a variável “numero” tem a palavra int, isso acontece pois o Java é uma linguagem fortemente tipada, isso significa que tudo deve possuir um identificador de qual tipo é, nesse caso int representa os números inteiros, existem outros tipos e os veremos mais adiante.

Para criar uma variável é necessário informar o seu tipo, um nome e um valor:

tipo  nome     valor
int   numero = 2;

Porém a partir do Java 11 foi adicionado inferência de tipo, que significa que não precisamos dizer qual é o tipo de uma variável que a própria linguagem irá saber o seu tipo:

var numero = 2;

Basta adicionar a palavra reservada var que ele implicitamente irá entender que estamos trabalhando com um tipo numérico.

Porém o Java continua sendo fortemente tipado o que significa que uma variável não pode ser definida de um tipo e depois receber outro:

//Exemplo de código que não funciona
int numero = 1;
numero = "a";

Esse código não será compilado pela linguagem e receberemos uma mensagem de erro.

var numero = 1;
numero = "a";

Esse código também não será compilado e também receberemos uma mensagem de erro pois mesmo sem dizer qual o tipo da variável “numero” quando atribuímos o valor “1” para ela o próprio compilador já sabe que implicitamente essa variável é de um tipo numérico e sendo assim não poderia receber outro valor que não fosse um tipo numérico.

Constantes

Nem sempre teremos valores que são mutáveis e as vezes a intenção é que não seja possível que esse valor se altere. Por exemplo imaginando que exista um programa que faça contas matemáticas e utilize o número π (PI) para calcular a circunferência de um círculo:

double pi = 3.14159265359;
double circunferencia = pi * diametro = 2 * pi * raio;

Agora suponha que por algum descuido alguém mude o valor da variável pi, todos os lugares que usarem essa variável serão afetadas e o resultado estará errado o que pode causar inúmeros problemas como no exemplo abaixo:

double pi = 3.14159265359;
pi = 2;
double circunferencia = pi * diametro = 2 * pi * raio;

Para solucionar esse tipo de situação existem as constantes que são como variáveis porém o seu valor é definido uma única vez e não pode ser alterado. No Java não existe uma declaração explícita para uma constante como existem em outras linguagem, veja abaixo o exemplo de uma constante com JavaScript:

const pi = 3.14159265359;

No exemplo acima a palavra reservada const já indica que aquele valor não pode ser mudado, mas como estamos falando de Java vamos entender como ele lida com isso já que não possui uma palavra reservada para constantes.

No Java existem palavras reservadas que são usadas pela linguagem para alguns fins, entre elas existem duas que iremos destacar, a palavra reservada final e a palavra reservada static. A palavra reservada final é usada quando queremos que algo não possa ser modificado, seja uma variável, método ou classe (mais pra frente será explicado melhor) o que já parece ser um caminho pois com a palavra final uma variável declarada não poderá ser modificada. A palavra reservada static serve para indicar que algo pertence ao seu tipo e não a sua instância, eu sei que essa definição é meio confusa de entender ainda mais por que ainda não foi apresentado classes e instâncias, mas pense que isso significa que esse “algo”, variável, classe ou método pode ser usado em outros pontos do programa sem que aja a necessidade de algumas burocracias que a linguagem exige. Colocando isso em prática uma constante ficaria assim:

static final double PI = 3.14159265359;
double circunferencia = PI * diametro = 2 * PI * raio;

Por convenção toda constante é escrita em letras maiúsculas e agora se por algum motivo alguém tentar alterar o valor da constante PI o compilador irá exibir uma mensagem de erro:

//Exemplo de código que não compila
static final double PI = 3.14159265359;
PI = 2;
double circunferencia = PI * diametro = 2 * PI * raio;

No exemplo acima criamos a constante PI porém no dia a dia podemos fazer uso da constante Math.PI do pacote java.lang.Math.

Tipos primitivos

Como dito anteriormente a linguagem Java é um linguagem fortemente tipada, isso significa que tudo, variáveis, constantes, métodos e classes são um tipo de dado. Existem dois tipos fundamentais no Java, os tipos primitivos e os tipos não primitivos. Aqui iremos ver o que são os dois e qual a controvérsia que existe sobre os tipos primitivos.

Um tipo primitivo é um valor diretamente guardado em memória, não é um objeto e sim o valor em si.

Parece ser contraditório já que a abordagem da linguagem é ser orientada a objetos e haver tipos primitivos, que são valores armazenados diretamente na memória, porém essa foi uma estratégia adotada pela equipe de desenvolvimento do Java, vamos entender quais são os tipos primitivos e quais valores podemos atribuir a eles:

----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------
Tipo                  | Primitivo |              Menor           |             Maior            | Valor Padrão | Tamanho   | Exemplo
----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------
                      |   byte    |              -128            |              127             |      0       |   8 bits  | byte b = (byte) 1;
Inteiro               |   short   |             -32768           |             32767            |      0       |   16 bits | short s = (short) 1;
                      |   int     |          -2.147.483.648      |          2.147.483.647       |      0       |   32 bits | int i = 1;
                      |   long    |  -9.223.372.036.854.770.000  |   9.223.372.036.854.770.000  |      0       |   64 bits | long l = 1l;
----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------
Ponto Flutuante       |   float   |           -1,4024E-37        |         3.40282347E+38       |      0       |   32 bits | float f = 1.1f;
                      |   double  |           -4,94E-307         |   1.79769313486231570E+308   |      0       |   64 bits | double d = 1.1; ou double d = 1.1d;
----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------
Caractere             |   char    |               0              |            65535             |     \0       |   16bits  | char c = 'a'; ou char c = 194;
----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------
Booleano              |   boolean |             false            |             true             |    false     |   1 bit   | boolean b = true;
----------------------|-----------|------------------------------|------------------------------|--------------|-----------|------------------------------------

Tipos não primitivos

Os tipos não primitivos são as classes e com isso é possível usar o paradigma de orientação a objetos, como herança, sobrecarga, sobrescrita e encapsulamento. O Java possui várias classes que podemos usar e no exemplo abaixo iremos ver a classe String que representa um conjunto de caractéres e é usado para textos:

String texto = "Olá Mundo";

Como se trata de uma classe quando criamos uma variável do tipo String é criado um objeto e ganhamos ações (métodos) que podemos usar para trabalhar com textos, exemplo:

String texto = "Olá Mundo";
System.out.println(texto.toUpperCase());
System.out.println(texto.toLowerCase());

E se executarmos esse código a saída será:

OLÁ MUNDO
olá mundo

Foi usado o método println(string) da classe System que é método usado para exibir (printar) um texto no console.

Operadores aritméticos

Operadores aritméticos são usados quando é necessário executar operações matemáticas com variáveis e valores.

----------------------|-----------|------------------------------------|---------------------------------
Operação              | Operador  | Exemplo                            | Descrição                       
----------------------|-----------|------------------------------------|---------------------------------
Adição                |     +     |             x + y                  | Adição de valores               
Subtração             |     -     |             x - y                  | Subtração de valores            
Multiplicação         |     *     |             x * y                  | Multiplicação de valores        
Divisão               |     /     |             x / y                  | Divisão de valores              
Módulo                |     %     |             x % y                  | Retorna o resto de uma divisão  
Incremento            |    ++     |           x++ ou ++x               | Incrementa o valor em 1         
Decremento            |    __     |           x-- ou --x               | Decrementa o valor em 1         
----------------------|-----------|------------------------------------|---------------------------------

Operador de atribuição

Nos exemplos anteriores já foi usado o operador de atribuição e como o próprio nome já diz ele é um operador usado para atribuir algum valor, o operador mais comum de atribuição é o = (igual) onde uma variável recebe um valor mas existem outros operadores e iremos ver os mais usados;

----------|---------------------|------------------------------------------------------------------------------
Operador  | Exemplo             | Descrição          
----------|---------------------|------------------------------------------------------------------------------
=         |  x = 5              | Atribui o valor 5 para variável x
+=        |  x+= 5 ou x = x + 5 | Adiciona o valor 5 para a variável x             
-=        |  x-= 5 ou x = x - 5 | Subtrai o valor 5 para a variável x
*=        |  x*= 5 ou x = x * 5 | Multiplica o valor de x em 5 vezes              
/=        |  x/= 5 ou x = x / 5 | Divide o valor de x pelo número 5 e guarda o resultado na variável x   
%=        |  x%= 5 ou x = x % 5 | Divide o valor de x pelo número 5 e guarda o resto da divisão na variável x             
----------|---------------------|------------------------------------------------------------------------------

Um adendo aqui é que a temos o que é chamado de açúcar sintáxico em alguns operadores onde podemos escrever de forma mais resumida a expressão, onde x+= 5 tem o mesmo resultado que x = x + 5, as duas expressões fazem a mesma coisa mas a primeira é mais sucinta de escrever.

Operadores de comparação

Os operadores de comparação são utilizados para comparar valores e são muito usados em condicionais que serão mostradas mais adiante:

----------|----------------|----------|------------------------------------------------------------
Operador  | Nome           | Exemplo  | Descrição          
----------|----------------|----------|------------------------------------------------------------
==        | Igualdade      |  x == y  | Compara se o valor de x é igual ao valor de y
!=        | Não igualdade  |  x != y  | Operador usado para afirmar que dois valores não são iguais
>         | Maior que      |  x > y   | Compara se o valor de x é maior que o valor de y
<         | Menor que      |  x < y   | Compara se o valor de x é menor que o valor de y
>=        | Maior igual    |  x >= y  | Compara se o valor de x é maior ou igual que o valor de y
<=        | Menor igual    |  x <= y  | Compara se o valor de x é menor ou igual que o valor de y
----------|----------------|----------|------------------------------------------------------------

Existem outros operadores, porém foram demonstrados os mais usados no dia-a-dia.

Operadores Lógicos

Antes de entender os operadores lógicos vale a pena comentar sobre a tabela verdade, que é um dispositivo utilizado no estudo da lógica matemática. Com o uso desta tabela é possível definir o valor lógico de uma proposição, isto é, saber quando uma sentença é verdadeira ou falsa.

----------|----------------|-----------------|--------------------------------------------------------------------
Conectivo | Símbolo        | Operação lógica | Valor lógico          
----------|----------------|-----------------|--------------------------------------------------------------------
não       |       ~        |  negação        | Terá valor falso quando a proposição for verdadeira ou vice-versa
e         |       ^        |  conjunção      | Será verdadeira quando todas as proposições forem verdadeiras
ou        |       v        |  disjunção      | Será verdadeira se pelo menos uma das proposições for verdadeira
----------|----------------|-----------------|--------------------------------------------------------------------

Para ilustrar melhor vamos ao seguinte exemplo:

1 < 2 ^ 2 > 1

A seguinte expressão pode ser lida: O número 1 é menor do que 2 E o número 2 é maior do que 1 o que torna essa expressão como VERDADEIRA.

Uma forma de simplificar a tabela verdade seria desse modo:

--|---|-----|---------     ---|-----
p | q | p^q | p v q         p | ~p
--|---|-----|---------     ---|----
V | V |  V  |   V           V |  F
V | F |  F  |   V           F |  V
F | V |  F  |   V
F | F |  F  |   F
--|---|---------------

Agora trazendo isso para a linguagem Java, o que muda são os símbolos mas a lógica permanece a mesma e ao invés de termos o resultado dessas expressões como verdadeira ou falsa é usado true ou false e esse tipo de variável é do tipo boolean, um adendo que vale ressaltar é que essa lógica se chama Lógica Booleana em homenagem a George Boole que introduziu o tema em 1847.

Porém no Java não são usados os símbolos ~, ^, v para expressões booleanas, com exceção do operador ^ que é usado para outro operador lógico que não veremos aqui mas que para fins de conhecimento é o XOR ou chamado de OU Exclusivo; então para negação é usado o símbolo ! (exclamação), para conjunção é usado o símbolo & (E comercial) e para disjunção é usado o simbolo | (pipe) como no exemplo abaixo:

boolean verdadeiroConjuncao = (1 < 2) & (2 > 1);
boolean falsoConjuncao = (1 == 2) & (2 > 1);
boolean verdadeiroDisjuncao = (1 > 2) | (1 < 2);
boolean falsoDisjuncao = (1 > 2) | (2 > 3);
boolean negacao = !(1 == 1);

Conclusão

Começamos hoje uma série de artigos introdutórios ao Java, foi passado um pouco da história e conceitos básicos da linguagem no próximo artigo será apresentado o tema condicionais e laços de repetição.

Criando uma API com Kotlin e Javalin

Mon, 14 Jun 2021 00:00:01 GMT

Introdução

A linguagem Kotlin é um projeto criado em 2011 pela JetBrains, a criadora de IDEs como IntelliJ, Web Storm e etc., e ganhou fama após ter sido adotado como linguagem oficial para desenvolvimento Android. Misturando conceitos das linguagens Scala e Java o Kotlin se torna uma linguagem muito versátil e descomplicada, principalmente para o desenvolvimento mobile no Android onde antes era desenvolvido unicamente com Java e tinha algumas complicações que o desenvolvedor tinha que adaptar, como manipulação de Threads e implementação interfaces anônimas.

Mas o Kotlin não se limita exclusivamente ao desenvolvimento mobile podendo também ser utilizado para desenvolvimento Web e nesse artigo iremos explorar como criar uma aplicação inteira do zero, desde a criação do projeto, modelagem de domínio, implementação de regras de negócio, persistência de dados, integração com outras aplicações, configuração de endpoints e rotas, testes unitários e start da aplicação.

Junto com o Kotlin será usado o Framework Javalin, esse framework tem como característica ser muito leve e pode ser usado tanto com a linguagem Java quanto com Kotlin, fora o Javalin será usado o Exposed que é um Framework ORM (Object Relational Mapper) da JetBrains para a comunicação com o banco de dados e manipulação dos dados. Como esse projeto irá fazer integração com outra aplicação via protocolo HTTP será usada lib Fuel que é um projeto para fazer o client HTTP.

Pra finalizar também será usado Swagger para documentação das APIs.

O Projeto

O projeto consiste em fazer buscas de Amiibo por nome. Pra quem não sabe Amiibos são estatuetas ou cartões que representam diversos personagens da Nintendo, como Mario, Link, Donkey Kong e etc. A aplicação irá fazer uma consulta no endpoint https://www.amiiboapi.com/api/amiibo que é uma url para fazer as consultas dos Amiibos. A aplicação fará um GET e irá tratar a resposta e exibirá para o usuário, um problema que existe é que esse endpoint é um pouco lento e isso pode causar impactos para o usuário que irá fazer consulta na nossa API, para resolver isso iremos salvar os dados em um banco de dados da nossa aplicação, então quando uma pesquisa for feita primeiramente será consultado a base da aplicação e depois a consulta será feita no endpoint externo se não existir no banco de dados.

Criando o projeto com IntelliJ

Criar um projeto com Kotlin não e complicado bastando criar a estrutura de arquivos mas para facilitar é possível criar pelo IntelliJ ou pelo Eclipse, as duas formas estão listadas abaixo.

IntelliJ

Eclipse

E agora adicionando as dependências que serão usadas no projeto no arquivo build.gradle.kts

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

val exposedVersion = "0.31.1"
val hikariCpVersion = "4.0.3"
val javalinVersion = "3.8.0"
val swagger = "2.0.9"
val swaggerUI = "3.24.3"
val classgraph = "4.8.69"
val jackson = "2.12.3"
val mysql = "8.0.25"
val slf4j = "1.7.28"
val fuel = "2.3.1"
val gson = "2.8.5"

plugins {
    kotlin("jvm") version "1.5.10"
    application
}

group = "com.amiibo.search"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {

    //Javalin Server
    implementation("io.javalin:javalin:$javalinVersion")

    //Swagger
    implementation("io.swagger.core.v3:swagger-core:$swagger")
    implementation("org.webjars:swagger-ui:$swaggerUI")
    implementation("io.github.classgraph:classgraph:$classgraph")

    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:$jackson")

    //Database
    implementation("org.jetbrains.exposed:exposed-core:$exposedVersion")
    implementation("org.jetbrains.exposed:exposed-jdbc:$exposedVersion")
    implementation("org.jetbrains.exposed:exposed-java-time:$exposedVersion")

    implementation("com.zaxxer:HikariCP:$hikariCpVersion")

    implementation("mysql:mysql-connector-java:$mysql")

    //Logging
    implementation( "org.slf4j:slf4j-simple:$slf4j")

    //HTTP Client Fuel
    //core
    implementation("com.github.kittinunf.fuel:fuel:$fuel")
    //packages
    implementation("com.github.kittinunf.fuel:fuel-gson:$fuel")
    implementation("com.google.code.gson:gson:$gson")

    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

tasks.withType<KotlinCompile>() {
    kotlinOptions.jvmTarget = "1.8"
}

tasks.jar {
    manifest {
        attributes["Main-Class"] = "MainKt"
    }
    configurations["compileClasspath"].forEach { file: File ->
        from(zipTree(file.absoluteFile))
    }
}

application {
    mainClass.set("MainKt")
}

Modelando o domínio

Com a estrutura do projeto pronta agora iremos fazer o core da aplicação, o objeto que deve ser transacionado pela aplicação. Lendo a API do AmiiboAPI temos o seguinte retorno para uma busca com sucesso:

{
	"amiibo": [
		{
			"amiiboSeries": "Super Smash Bros.",
			"character": "Mario",
			"gameSeries": "Super Mario",
			"head": "00000000",
			"image": "https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_00000000-00000002.png",
			"name": "Mario",
			"release": {
				"au": "2014-11-29",
				"eu": "2014-11-28",
				"jp": "2014-12-06",
				"na": "2014-11-21"
			},
			"tail": "00000002",
			"type": "Figure"
		},
		{
			"amiiboSeries": "Super Mario Bros.",
			"character": "Mario",
			"gameSeries": "Super Mario",
			"head": "00000000",
			"image": "https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_00000000-00340102.png",
			"name": "Mario",
			"release": {
				"au": "2015-03-21",
				"eu": "2015-03-20",
				"jp": "2015-03-12",
				"na": "2015-03-20"
			},
			"tail": "00340102",
			"type": "Figure"
		}
	]
}

Temos muitas informações mas nem todas queremos exibir pro usuário que chama a nossa API, então fazendo um resumo dos dados retornado pela AmiiboAPI é possível extrar esse domínio:

data class Amiibo(
    val amiiboSeries: String,
    val name: String,
    val gameSeries: String,
    val type: String,
    val imageUrl: String
)

Aqui usamos a estrutura data class que é uma estrutura existente no Kotlin para trafegar dados na aplicação e implementa alguns métodos que são úteis como equals() toString() hashCode() entre outros que auxiliam na manipulação desses objetos na aplicação, ele é relativo ao projeto Lombok que é muito usado em aplicações Java.

Criando casos de uso

Com o domínio modelado e disponível na aplicação é necessário aplicar a lógica de negócio que queremos que seja executada, é nessa parte do código que vive o coração da aplicação e é chamado de casos de uso de uma aplicação.

Essa aplicação a primeiro momento irá somente executar buscas então iremos nomear a classe de serviço com o nome SearchAmiibo e faremos da seguinte forma:

class SearchAmiibo(private val repository: Repository, private val api: Api) {


    fun searchAmiiboByName(amiiboName: String): List<Amiibo>? {
        TODO("Not implemented yet")
    }
}

Dois pontos importantes do código acima, primeiro é necessário criar esses elementos que estão sendo usados pela classe SearchAmiibo, o Repository e a Api e segundo que definimos um método chamado searchAmiiboByName que recebe o nome do Amiibo para fazer a busca e pode retornar um lista de Amiibos.

Um detalhe pode ser visto pelo uso do operador ? do Kotlin que é um operador null-safe para evitar erros do tipo NullPointerException.

Antes de criar uma implementação de Repository e Api vamos criar as suas interfaces, os contratos que queremos que um Repository e uma Api façam na aplicação, a implementação delas virá depois.

Começando pelo Repository:

interface Repository {

    fun findByAmiiboName(amiiboName: String): List<Amiibo>?

    fun insertAmiibo(amiibo: Amiibo): Amiibo?
}

Esse Repository expõe o contrato que será responsável por buscar um Amiibo pelo seu nome e inserir um.

E agora pela Api:

interface Api {

    fun searchAmiiboByName(amiiboName: String): List<Amiibo>?
}

A Api por sua vez só tem uma responsabilidade que é buscar um Amiibo externamente.

Com isso podemos nos concentrar na regra de negócio e conseguimos fazer a regra de negócio sem se preocupar com a implementação agora:

class SearchAmiibo(private val repository: Repository, private val api: Api) {

    private val logger: Logger = LoggerFactory.getLogger(SearchAmiibo::class.java)

    fun searchAmiiboByName(amiiboName: String): List<Amiibo>? {

        logger.info("INIT SEARCH FOR AN AMIIBO OR IT WILL TRY FETCH ON EXTERNAL SERVICE")

        repository.findByAmiiboName(amiiboName)?.takeIf { amiiboList -> !amiiboList.isNullOrEmpty() }
            ?.let { amiiboList ->
                return amiiboList
            } ?: api.searchAmiiboByName(amiiboName)?.let { amiiboList: List<Amiibo> ->

            amiiboList.forEach { amiibo: Amiibo ->
                repository.insertAmiibo(amiibo)
            }

            return amiiboList

        } ?: throw AmiiboNotFoundException("Amiibo $amiiboName not found")

    }
}

No código acima podemos ver alguns utilitários do Kotlin que nos ajudam a construir um código mais legível, fluente e declarativo como takeIf, let e o ?: chamado de Elvis operator.

O takeIf é uma forma idiomática que o Kotlin possui onde seria equivalente ao if de outras linguagens onde dada uma condição sendo verdadeira será repassada, o let está sendo usado após a chamada repository.findByAmiiboName(amiiboName)? que usa o ? como tratativa null-safe para passar para o let o resultado somente se o resultado do método não for nulo, o let irá executar o bloco de código recebendo o valor passado e retornando o mesmo que nesse caso é a lista de Amiibo se existir no banco.

Já o Elvis operator ?: é um operador condicional que executará o código à direita se o código à esquerda for null então se a chamada no Repository não trouxer dados será executada a chamada para a Api que também pode falhar e devolver null e nesse caso o Elvis operator irá executar o último bloco que é o lançamento de uma Exception customizada. Por fim temos uma feature interessante do Kotlin que é a maneira mais simples como é possível interpolar Strings com uso do operador $

Para efeitos didáticos segue o código da Exception criada:

class AmiiboNotFoundException(message: String): Exception(message)

Implementando repositório

Aqui veremos como implementar o Repository, até o momento no projeto existe a interface Repository que serve como uma porta e agora é necessário implementar um adaptador. Nesse exemplo será usado o Exposed que é um framework ORM, isso significa que é necessário mapear no projeto as classes que representam as tabelas no banco de dados. O Exposed é um projeto da JetBrains e nos ajuda a mapear o banco de dados do lado da aplicação, fora que frameworks ORM expõe APIs para melhor manipulação dos dados e segurança contra ataques do tipo SQLInjection entre outros.

No projeto iremos criar a pasta repository.exposed.entity e iremos criar a AmiiboEntity:

object AmiiboEntity : Table(name = "Amiibo") {

    val id = integer("id").autoIncrement()
    val amiiboSeries = varchar("amiiboSeries", 60)
    val name = varchar("name", 60)
    val gameSeries = varchar("gameSeries", 60)
    val imageUrl = varchar("imageUrl", 255)
    val type = varchar("type", 20)

    override val primaryKey = PrimaryKey(id, name = "ID_AMIIBO_KEY")
}

Para que esse classe possa ser usada em conjunto com o Exposed é necessário herdar a classe Table, onde informamos o nome da tabela no banco de dados. Em cada atributo que é equivalente a cada coluna no banco de dados é possível definir o tipo e o seu tamanho, o último ponto importante é que definimos o campo id como sendo auto increment e sobrescrevemos a classe PrimaryKey onde informado que o atributo id será a Primary Key e informamos o nome dela, se não for informado o Exposed se encarregará de criar um nome.

Um ponto bom para explicar do Kotlin é a declaração object para a criação da classe AmiiboEntity, esse tipo de declaração auxilia o desenvolvedor quando for necessário criar classes apenas uma vez, Singletons, e no Kotlin basta usar a declaração object para isso.

Com a Entity definida será criada a classe que irá implementar a interface Repository:

object ExposedAmiiboRepository : Repository {

    private val logger: Logger = LoggerFactory.getLogger(ExposedSuperheroRepository::class.java)

    override fun findByAmiiboName(amiiboName: String): List<Amiibo>? {

        logger.info("[FIND AMIIBO BY NAME ON DATABASE]")

        return transaction {
            addLogger(StdOutSqlLogger)

            AmiiboEntity.select { AmiiboEntity.name eq amiiboName }?.map { row ->
                AmiiboEntity.toAmiibo(row)
            }.toList()
        }
    }

    override fun insertAmiibo(amiibo: Amiibo): Amiibo? {

        logger.info("[INSERT AMIIBO ON DATABASE]")

        transaction {
            addLogger(StdOutSqlLogger)

            AmiiboEntity.insert { entity ->
                entity[name] = amiibo.name
                entity[amiiboSeries] = amiibo.amiiboSeries
                entity[type] = amiibo.type
                entity[gameSeries] = amiibo.gameSeries
                entity[imageUrl] = amiibo.imageUrl
            }.resultedValues?.firstOrNull() ?: error("No key generated")
        }

        return amiibo
    }
}

A classe ExposedAmiiboRepository além de implementar a interface Repository também é usado a declaração object para ela, nos métodos findByAmiiboName e insertAmiibo usamos o bloco transaction do Exposed onde como o nome diz é usado no contexto de transações no banco de dados, fora que é usado o método utilitário addLogger para ajudar na visualização de logs.

Agora olhando um pouco mais detalhadamente para o método findByAmiiboName, dentro do bloco transaction é chamado a AmiiboEntity que por ser do tipo Table possui métodos para acesso ao banco de dados e aqui será usado o método select onde queremos passar um filtro de igualdade e que nesse método é usado para fazer um filtro de igualdade pelo nome do Amiibo no banco. O método select pode não trazer nenhum resultado pois pode não haver nenhum resultado para a pesquisa no banco de dados e por isso é usado o operador ? para caso não encontre valores interrompe o processamento e não corremos o risco de erros do tipo NullPointerException. Mas caso exista o select retorna uma Query que conseguimos iterar os resultados com um map e para cada resultado criar um Amiibo e devolver uma lista de Amiibos.

AmiiboEntity.select { AmiiboEntity.name eq amiiboName }?.map { row ->
    Amiibo(
        amiiboSeries = resultRow[amiiboSeries],
        name = resultRow[name],
        gameSeries = resultRow[gameSeries],
        imageUrl = resultRow[imageUrl],
        type = resultRow[type]
    )
}.toList()

Com isso já temos o Exposed implementado porém é necessário criar a conexão com o banco de dados e para isso foi criado a pasta adapter.repository.exposed.config e a classe DatabaseFactory onde além de conectar no banco, que no projeto será o MySQL, também usará o Hikari para criar um pool de conexões:

class DatabaseFactory {

    companion object {

        private val logger: Logger = LoggerFactory.getLogger(DatabaseFactory::class.java)

        tailrec fun createHikariDataSourceWithRetry(
            jdbcUrl: String, username: String, password: String, driverClassName: String,
            backoffSequenceMs: Iterator<Long> = defaultBackoffSequenceMs.iterator()
        ): HikariDataSource {
            try {
                val config = HikariConfig()
                config.jdbcUrl = jdbcUrl
                config.username = username
                config.password = password
                config.driverClassName = driverClassName
                return HikariDataSource(config)
            } catch (ex: Exception) {
                logger.error("Failed to create data source ${ex.message}")
                if (!backoffSequenceMs.hasNext()) throw ex
            }
            val backoffMillis = backoffSequenceMs.next()
            logger.info("Trying again in $backoffMillis millis")
            Thread.sleep(backoffMillis)
            return createHikariDataSourceWithRetry(jdbcUrl, username, password, driverClassName, backoffSequenceMs)
        }

        private const val maxBackoffMs = 16000L
        private val defaultBackoffSequenceMs = generateSequence(1000L) { min(it * 2, maxBackoffMs) }
    }
}

A classe DatabaseFactory possui apenas uma responsabilidade que é se conectar ao banco de dados delegando ao Hikari a criação do DataSource, porém existem alguns elementos do Kotlin que vale a pena comentar para melhor entendimento de como isso é feito.

O primeiro ponto é o uso do tailrec no método createHikariDataSourceWithRetry onde é uma forma elegante que o Kotlin possui para métodos ou funções recursivas, ao invés de ser usado um loop for ou while o Kolitn expõe essa palavra reservada tailrec onde o compilador é capaz de executar otimizações para recursividade.

O segundo ponto é a declaração companion object que é outra forma de criar Singletons e é usado muito quando se quer usar métodos ou atributos que devem se comportar como atributos ou métodos da classe ao invés da instância, o que é equivalente ao modificador staticdo Java, inclusive se for usado a anotação @JvmStatic a JVM tentará gerar esses campos ou métodos como estáticos.

Um utilitário muito interessante do Exposed é a capacidade dele de gerar as tabelas via código, essa prática não é recomendada em códigos de produção, bastando utilizar o SchemaUtils do Exposed:

fun createDatabase() {

    logger.info("[INIT DATABASE CREATION]")

    transaction {

        addLogger(StdOutSqlLogger)

        SchemaUtils.createMissingTablesAndColumns(AmiiboEntity)

    }
}

Com isso pronto basta chamar o método de criação da conexão, nesse caso usaremos no start da aplicação:

fun main(args: Array<String>) {

    val createHikariDataSourceWithRetry = DatabaseFactory.createHikariDataSourceWithRetry(
        System.getenv("jdbcUrl") ?: "jdbc:mysql://localhost:3306/amiibo?createDatabaseIfNotExist=true",
        System.getenv("username") ?: "user",
        System.getenv("pass") ?: "user",
        System.getenv("driverClassName") ?: "com.mysql.cj.jdbc.Driver"
    )

    val connect = Database.connect(createHikariDataSourceWithRetry)
    connect.useNestedTransactions = true

    ExposedAmiiboRepository.createDatabase()

}

Adicionando o client HTTP

Aqui será mostrado como implementar a interface Api e ela será implementada com a lib Fuel, que é um projeto de um client HTTP para realizarmos chamadas HTTP para serviços externos, ele é bem simples e muito completo, permitindo usar várias libs para desserialização podendo o desenvolvedor utilizar a que estiver mais familiarizado, também possui um bom suporte para requests assíncronos.

Para fazer a request para o serviço externo será executado um GET onde quando houver uma resposta positiva será retornado um objeto json com os dados e quando não encontrar dados irá retornar um erro 404 e um json diferente com a mensagem de erro, iremos começar criando essas classes que só serão usadas para trafegar os dados da API para o domínio da aplicação então será criados objetos com o padrão DTO, Data Transfer Object, primeiramente o response no caso positivo:

@JsonIgnoreProperties(ignoreUnknown = true)
data class AmiiboWrapper(
    val amiibo: List<AmiiboResponse>
)

@JsonIgnoreProperties(ignoreUnknown = true)
data class AmiiboResponse(
    val amiiboSeries: String,
    val character: String,
    val gameSeries: String,
    val head: String,
    val image: String,
    val name: String,
    val type: String
)

E no caso de resposta de erro:

@JsonIgnoreProperties(ignoreUnknown = true)
data class ResponseError(
    val code: String,
    val error: String
)

E agora podemos criar a pasta adapter.api.fuel e a classe FuelClientApi que irá implementar a Api:

object FuelClientApi : Api {

    private val logger: Logger = LoggerFactory.getLogger(FuelClientApi::class.java)

    private val url: String = System.getenv("URL_API") ?: "https://www.amiiboapi.com/api/amiibo"

    override fun searchAmiiboByName(amiiboName: String): List<Amiibo>? {

        var amiibo: List<Amiibo>? = null;

        logger.info("TRYING TO FETCH AMIIBO AT THE URL: [$url]")

        Fuel.get(url, listOf("name" to amiiboName)).responseObject<AmiiboWrapper> { _, _, result ->

            val (apiResult, fuelError) = result

            if (fuelError != null) {
                val error: ResponseError =
                    Gson().fromJson<ResponseError>(
                        fuelError.errorData.toString(Charsets.UTF_8),
                        ResponseError::class.java
                    )

                logger.error("Error to process: ${error.error}")
            }

            amiibo = apiResult?.amiibo?.map { amiiboResponse: AmiiboResponse ->
                Amiibo(
                    amiiboSeries = amiiboResponse.amiiboSeries, name = amiiboResponse.name,
                    gameSeries = amiiboResponse.gameSeries, imageUrl = amiiboResponse.image, type = amiiboResponse.type
                )
            }

        }.get()

        return amiibo

    }
}

Dentro do método searchAmiiboByName é utilizado o método Fuel.get e é passado no primeiro parâmetro a url e no segundo a lista de parâmetros que devem ser passados na url. Utilizamos o método responseObject onde é tipado o response para AmiiboWrapper, esse método tem como retorno a Request, o Response e o Result, como os dois primeiros não serão usados pode ser usado o _ para indicar que esse valor não será usado, mas o Result será usado pois ele é um objeto que envelopa tanto o objeto de sucesso quanto o objeto de erro, sendo que um sempre será nulo quando o outro existir.

Fazendo a desestruturação do retorno val (apiResult, fuelError) = result e é feita a checagem se o fuelError é nulo, caso não seja é feito a desserialização do json utilizando a Gson para o ResponseError. Caso o fuelError seja nulo será feita a desserialização para o AmiiboResponse.

Vale ressaltar que quando é usado o método responseObject deve ser feita alguma tratativa para que seja esperado a execução do GET pois ele é assíncrono então no fim do método foi usado o método get() que é da API Future do Java e que faz com que o método aguarde a execução do código.

Configurando o Javalin e Swagger

Para criar o server HTTP e subir a aplicação será usado o Javalin que é um framework que pode ser usado tanto com Kotlin quanto com Java, é muito leve e de fácil utilização, junto a ele será usado o projeto Swagger para documentação das APIs.

Para iniciar será feita configuração inicial do Javalin e após isso a configuração de rotas e handlers, primeiro será criado a pasta application.http e a função startHttpServer:

fun startHttpServer(port: String = "8080") {
    val httpPort = System.getenv().getOrDefault("PORT", port).toInt()
    val apiVersion = "v1"
    val appContext = "amiibo"

    Javalin.create { config ->
        config.contextPath = "/$appContext/$apiVersion"
        config.showJavalinBanner = false
        config.registerPlugin(getConfiguredOpenApiPlugin())
        config.enableCorsForAllOrigins()
        config.defaultContentType = "application/json"
    }.also { app ->

        //TODO implementar rotas

    }.start(httpPort).apply {
        Runtime.getRuntime().addShutdownHook(Thread { this.stop() })
    }
}

No código acima o primeiro bloco, create, serve para configurar o contexto do Javalin, o path, habilitar o Swagger, que será visto em seguida, desabilitar o CORS e configurar o json como padrão.

Foi registrado um plugin onde é passado o método getConfiguredOpenApiPlugin(), na pasta application.http.openapi será mostrado o que esse método faz:

fun getConfiguredOpenApiPlugin() = OpenApiPlugin(
    OpenApiOptions(
        Info().apply {
            title("Amiibo")
            version("1.0.0")
            description("Amiibo Search API documentation")
        }
    ).apply {
        path("/swagger-docs")
        swagger(SwaggerOptions("/swagger-ui").title("Amiibo Search Documentation"))
    }
)

No código acima foi utilizado a classe OpenApiPlugin do Javalin e passamos as informações que irão aparecer na tela do Swagger e por fim é configurado path para o json /swagger-docs e o path para o ui do Swagger /swagger-ui.

Com isso temos o mínimo para iniciar a aplicação mas ainda é necessário adicionar rotas para a aplicação para que ela seja utilizável, mas antes de definir as rotas será definido as handlers que são as funções que serão chamadas pelas rotas e chamarão os casos de uso. Teremos três handlers ao todo, um para a busca de Amiibo, um para o HealthCheck e outro para manipular os possíveis erros que podem ocorrer e que queremos que seja tratado antes de ser enviado ao usuário que fez a solicitação na API.

Começando pelo handler HealthCheck será criado a pasta application.http.handler e o arquivo HealthCheck.kt:

fun liveness(ctx: Context) {
    ctx.status(200).json(object {
        val message = "OK"
    })
}

Que basicamente devolve um status 200 e a mensagem OK.

O segundo handler é AmiiboHandler.kt:

fun searchAmiibo(ctx: Context){

    val amiiboName: String = ctx.pathParam("amiiboName")

    val amiiboByName: List<Amiibo>? =
        SearchAmiibo(ExposedAmiiboRepository, FuelClientApi).searchAmiiboByName(amiiboName)

    ctx.status(200).json(amiiboByName!!)
}

Onde a função searchAmiibo recebe o Context e extrai do pathParam o nome do Amiibo para pesquisar e delega para a classe SearchAmiibo o método searchAmiiboByName com o nome do Amiibo que devolve uma lista de Amiibos que por sua vez devolve ao Context o status 200 com o json a lista de Amiibos.

Por fim o ErrorHandler.kt:

fun errorHandler(app: Javalin){

    app.exception(AmiiboNotFoundException::class.java) { _, ctx ->
        ctx.json(object {
            val message = "Superhero not found"
        }).status(404)
    }

    app.exception(Exception::class.java) { e, ctx ->
        ctx.json(object {
            val message = e.message
        }).status(500)
    }

}

Onde a função errorHandler diferentemente das duas anteriores não recebe o Context e sim a própria instância do Javalin e usa o método exception que registra o que deve ser feito quando uma Exception ocorrer na aplicação. Então quando a aplicação lançar uma AmiiboNotFoundException irá devolver um status 404 e no json um objeto com a mensagem Superhero not found e se ocorrer qualquer outra Exception irá retornar o status 500 e no body irá mostrar a mensagem de erro da Exception.

Um ponto interessante aqui é que foi feito o uso de uma classe anônima através da sintaxe object {}.

Com os handlers criados podemos criar as rotas na pasta application.http.route no arquivo Routes.kt:

fun mountRoutes(app: Javalin){
    app.before { ctx ->
        val host = ctx.header("Origin") ?: "*"
        ctx.header(Header.ACCESS_CONTROL_ALLOW_ORIGIN, host)
        ctx.header(Header.ACCESS_CONTROL_ALLOW_HEADERS, "Authorization, Content-Type, Accept")
    }

    app.routes {
        ApiBuilder.get("/health", documented(healthDocumentation(), ::liveness))
        ApiBuilder.get(":amiiboName/search", documented(searchAmiiboDocumentation(), ::searchAmiibo))
    }

}

Na função mountRoutes recebemos a instância do Javalin e é utilizado o função before para tratativas que ocorrem antes de qualquer request e na função routes é mapeado o verbo HTTP que será usado, nesse caso são dois GETs, o path e também foi passado o método documented onde é informado o método para montar esse request no Swagger, será visto logo a frente, e a função handler para aquela rota.

Agora para mostrar as funções que serão usadas pelo Swagger será criada no mesmo arquivo que foi criado a função getConfiguredOpenApiPlugin() as funções healthDocumentation e searchAmiiboDocumentation:

const val TAG = "Amiibo"

fun healthDocumentation() = document().operation { operation ->
    operation.summary = "Health Check"
    operation.description = ""
    operation.operationId = "health"
    operation.addTagsItem(TAG)
}.json("200", String::class.java)

fun searchAmiiboDocumentation() = document().operation { operation ->
    operation.summary = "Search Amiibo"
    operation.operationId = "searchAmiibo"
    operation.description = "Search for an amiibo by name"
    operation.addTagsItem(TAG)
}.body<Amiibo>()
    .json("200", Amiibo::class.java).json("404", object {
        val message = "Superhero not found"
    }::class.java)

Nessas funções são passadas as informações relevantes para aquele request e o body em caso de sucesso e de erro.

Pra isso tudo funcionar é necessário chamar essas funções lá na função startHttpServer:

fun startHttpServer(port: String = "8080") {
    val mustServeOpenAPIDocs: Boolean = System.getenv().getOrDefault("ENABLE_OPEN_API_DOCS", "true")!!
        .toBoolean()
    val httpPort = System.getenv().getOrDefault("PORT", port).toInt()
    val apiVersion = "v1"
    val appContext = "amiibo"

    Javalin.create { config ->
        config.contextPath = "/$appContext/$apiVersion"
        config.showJavalinBanner = false
        if (mustServeOpenAPIDocs) {
            config.registerPlugin(getConfiguredOpenApiPlugin())
        }
        config.enableCorsForAllOrigins()
        config.defaultContentType = "application/json"
    }.also { app ->

        //Implementação de rotas
        mountRoutes(app)
        //Implementação de erros
        errorHandler(app)

    }.start(httpPort).apply {
        Runtime.getRuntime().addShutdownHook(Thread { this.stop() })
    }
}

Com isso pronto basta chamar a função startHttpServer no main da aplicação:

fun main(args: Array<String>) {

    startHttpServer()
}

Adicionando testes

Uma das vantagens de uma arquitetura de portas e adaptadores é a facilidade de testar, para ser mais claro essa vantagem será implementado os testes dessa aplicação sem necessidade de usar outra lib de mocks pois basta criar um adaptador que faça esse trabalho.

Vamos criar então o adaptador para a Repository:

object InMemoryDatabase : Repository {

    private val inMemoryDB = HashMap<String, Amiibo>()

    override fun findAll(): Set<Amiibo>? {
        return inMemoryDB.values.toSet()
    }

    override fun findByAmiiboName(amiiboName: String): List<Amiibo>? {
        return inMemoryDB.filterValues { amiibo -> amiibo.name == amiiboName }.values.toList()
    }

    override fun insertAmiibo(amiibo: Amiibo): Amiibo? {
        inMemoryDB[amiibo.name] = amiibo
        return amiibo
    }
}

Foi simulado o acesso ao banco de dados através de um HashMap e isso já basta para cumprir o contrato da Repository.

Agora será criado o adaptador para a Api;

object InMemoryApi : Api {

    override fun searchAmiiboByName(amiiboName: String): List<Amiibo>? {

        if (amiiboName == "mario" || amiiboName == "luigi") {
            return null
        }

        return listOf(
            Amiibo(
                amiiboSeries = "Series",
                name = amiiboName,
                gameSeries = "Game",
                type = "Figure",
                imageUrl = "https://fakeurl.img"
            )
        )
    }
}

Aqui é feito uma checagem simples para emular que a chamada não funcionou e retornou erro.

Agora para criar os testes foi criada a classe SearchAmiiboTest e implementado os métodos:

class SearchAmiiboTest {

    val repository = InMemoryDatabase
    private val searchAmiibo = SearchAmiibo(repository, InMemoryApi)

    @Test
    fun `search amiibo by api`() {
        val searchAmiiboByName = searchAmiibo.searchAmiiboByName("ryu")

        assertTrue(searchAmiiboByName?.any { amiibo: Amiibo -> amiibo.name == "ryu" }!!, "Ryu is found by API")
    }

    @Test
    fun `search amiibo by databse`() {
        repository.insertAmiibo(
            Amiibo(
                amiiboSeries = "Series",
                name = "mario",
                gameSeries = "Game",
                type = "Figure",
                imageUrl = "https://fakeurl.img"
            )
        )

        val searchAmiiboByName = searchAmiibo.searchAmiiboByName("mario")

        assertTrue(searchAmiiboByName?.any { amiibo: Amiibo -> amiibo.name == "mario" }!!, "Mario is found by API")

    }

    @Test
    fun `amiibo not found`() {
        val assertThrows = Assertions.assertThrows(AmiiboNotFoundException::class.java) {
            searchAmiibo.searchAmiiboByName("luigi")
        }

        assertEquals("Amiibo luigi not found", assertThrows.message)
    }
}

Rodando os testes todos passam.

Um ponto importante e ser analisado é o seguinte, apesar de todos os testes passarem se rodarmos um coverage de código nem tudo estará coberto, para alguns isso pode ser um problema, porém quando é analisado com mais cuidado conseguimos ver que toda a regra de negócio e domínio da aplicação está com cobertura de 100%, o que faz muito sentido pois não queremos testar o Javalin, o Exposed ou o Fuel, eles já possuem testes nos seus próprios projetos, queremos testar a nossa implementação e se aplicação se comporta como definimos nos casos de uso.

Subindo a aplicação e testando

Agora com tudo pronto podemos iniciar a aplicação e testar os endpoints.

Se testarmos com um Amiibo que não existe teremos o seguinte resultado:

curl --location --request GET 'http://localhost:8080/amiibo/v1/muahaha/search' | json_pp
{
    "message": "Amiibo not found"
}

E se testarmos um válido:

curl --location --request GET 'http://localhost:8080/amiibo/v1/link/search' | json_pp
[
    {
        "amiiboSeries": "Super Smash Bros.",
        "name": "Link",
        "gameSeries": "The Legend of Zelda",
        "type": "Figure",
        "imageUrl": "https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-00040002.png"
    }
]

E se olharmos os logs veremos:

[qtp708613859-40] INFO com.amiibo.search.useCase.SearchAmiibo - INIT SEARCH FOR AN AMIIBO OR IT WILL TRY FETCH ON EXTERNAL SERVICE
[qtp708613859-40] INFO com.amiibo.search.adapter.repository.exposed.ExposedAmiiboRepository - [FIND AMIIBO BY NAME ON DATABASE]
[qtp708613859-40] INFO com.amiibo.search.adapter.api.fuel.FuelClientApi - TRYING TO FETCH AMIIBO AT THE URL: [https://www.amiiboapi.com/api/amiibo]
SQL: SELECT Amiibo.id, Amiibo.amiiboSeries, Amiibo.`name`, Amiibo.gameSeries, Amiibo.imageUrl, Amiibo.`type` FROM Amiibo WHERE Amiibo.`name` = 'link'
[qtp708613859-40] INFO com.amiibo.search.adapter.repository.exposed.ExposedAmiiboRepository - [INSERT AMIIBO ON DATABASE]
SQL: INSERT INTO Amiibo (amiiboSeries, gameSeries, imageUrl, `name`, `type`) VALUES ('Super Smash Bros.', 'The Legend of Zelda', 'https://raw.githubusercontent.com/N3evin/AmiiboAPI/master/images/icon_01000000-00040002.png', 'Link', 'Figure')

Repetindo o request ele será visivelmente mais rápido e nos logs veremos:

[qtp708613859-32] INFO com.amiibo.search.useCase.SearchAmiibo - INIT SEARCH FOR AN AMIIBO OR IT WILL TRY FETCH ON EXTERNAL SERVICE
[qtp708613859-32] INFO com.amiibo.search.adapter.repository.exposed.ExposedAmiiboRepository - [FIND AMIIBO BY NAME ON DATABASE]
SQL: SELECT Amiibo.id, Amiibo.amiiboSeries, Amiibo.`name`, Amiibo.gameSeries, Amiibo.imageUrl, Amiibo.`type` FROM Amiibo WHERE Amiibo.`name` = 'link'

Trocando o MySQL pelo Mongo

Como estamos usando uma estratégia que prega facilidade de trocar os adaptadores com baixo acoplamento com frameworks será mostrado como poderemos fazer a troca do adaptador por qualquer outro sem grandes esforços contanto que o contrato seja implementado.

Será trocado o MySQL pelo MongoDB noe xemplo a seguir.

Para isso adicionamos a dependência no arquivo build.gradle.kts:

val mongo = "3.12.8"
implementation("org.mongodb:mongodb-driver:$mongo")

E criamos a pasta adapter.repository.mongo.config e o arquivo MongoFactory:

object MongoFactory {

    private val mongoDatabase = System.getenv().getOrDefault("MONGO_DATABASE", "amiibo")
    private val mongoHost = System.getenv().getOrDefault("MONGO_HOST", "mongodb://admin:password@localhost:27017")
    private val uri: MongoClientURI = MongoClientURI(mongoHost)

    val database: MongoDatabase = MongoClient(uri).getDatabase(mongoDatabase)
}

Nesse arquivo é feita a configuração da conexão com o Mongo e agora será feita a implementação da interface Repository na classe MongoAmiiboRepository:

object MongoAmiiboRepository : Repository {

    private val mongoCollection = database.getCollection("amiibo")

    override fun findAll(): Set<Amiibo>? {
        return mongoCollection.find().map {
            mapToAmiibo(it)
        }.toSet()
    }

    override fun findByAmiiboName(amiiboName: String): List<Amiibo>? {
        return mongoCollection.find(Filters.eq("name", amiiboName)).map {
            mapToAmiibo(it)
        }.toList()
    }

    override fun insertAmiibo(amiibo: Amiibo): Amiibo? {
        val document = Document()

        document.let { doc ->
            doc.append("name", amiibo.name)
            doc.append("amiiboSeries", amiibo.amiiboSeries)
            doc.append("gameSeries", amiibo.gameSeries)
            doc.append("imageUrl", amiibo.imageUrl)
            doc.append("type", amiibo.type)
        }

        mongoCollection.insertOne(document)
        return mapToAmiibo(document)
    }

    private fun mapToAmiibo(document: Document) = Amiibo(
        document.getString("amiiboSeries"),
        document.getString("name"),
        document.getString("gameSeries"),
        document.getString("type"),
        document.getString("imageUrl")
    )
}

Após isso é possível trocar o adaptador onde ele é usado:

fun searchAmiibo(ctx: Context){

    val amiiboName: String = ctx.pathParam("amiiboName")

    val amiiboByName: List<Amiibo>? =
        SearchAmiibo(MongoAmiiboRepository, FuelClientApi).searchAmiiboByName(amiiboName)

    ctx.status(200).json(amiiboByName!!)
}

E podemos testar de novo sem problemas.

A vantagem é clara, pois não necessitou de grandes mudanças no projeto, os testes não quebraram e com isso podemos trocar livremente os adaptadores sem que o projeto fique preso a uma tecnologia desde sua criação.

Conclusão

Nesse projeto vimos como criar um projeto com Kotlin e algumas das facilidades dessa linguagem. Também vimos como usar o Javalin e como é fácil a sua configuração e também vimos como usar o framework ORM Exposed com o MySQL e uma outra opção com Mongo e como é fácil trocar as tecnologias quando se usa uma arquitetura de portas e adaptadores e por fim foi mostrado como fazer integrações com outros serviços via HTTP com o Fuel.

Vimos também como testar uma aplicação utilizando adaptadores sem a necessidade de mocks, não que mocks sejam um problemas mas por vezes a má utilização dessas libs podem acarretar mais dificuldades do que benefícios nos testes da aplicação.

Código fonte

O código fonte dessa aplicação encontra-se no GitHub

Criando uma aplicação REST com NestJS, Fastify e TypeORM

Tue, 01 Jun 2021 00:00:01 GMT

Introdução

Nesse artigo iremos criar uma aplicação REST do zero usando o framework NestJS, utilizando a linguagem Typescript, rodando o Fastify e o TypeORM para manipulação no banco de dados.

Iremos usar uma abordagem arquitetural conhecida como Arquitetura Hexagonal que facilita muito o trabalho de desenvolvimento, deixando a aplicação plugável, independente de frameworks e bancos de dados.

Iniciando o projeto

O NestJS é um framework construído em Typescript o que trás elementos de programação orientada a objetos OOP e programação funcional FP, inicialmente ele roda com Express mas nesse artigo será mostrado como é fácil alterar para o Fastify.

Para iniciarmos o projeto podemos usar o cli utilitário do NestJS para isso:

npm i -g @nestjs/cli

E com isso temos o cli do NestJS instalado de forma global no seu computador. E para criar um projeto novo pode ser usado o comando a seguir:

nest new cadastro-api

No comando acima é utilizado o comando nest seguido de new e o nome do projeto que nesse caso será cadastro-api.

Esse projeto será uma aplicação para cadastro de livros e seus autores, onde um autor pode ter vários livros. Mas será exposta somente a inclusão de livros e a aplicação terá inteligência o suficiente para cadastrar o autor caso não exista.

Com isso o projeto está pronto porém ele por padrão vem com o Express e será necessário alterar para o Fastify. O Fastify que é inspirado tanto no Hapi quanto no Express é um framework web com foco na produtividade e performance, para adicionar ele no projeto basta executar o comando abaixo:

npm i --save @nestjs/platform-fastify

E com isso já é instalado o Fastify com os módulos para utilização com o NestJS.

E por fim será adicionado o TypeORM que faz a integração entre a aplicação e o banco de dados, para esse exemplo usaremos o banco de dados MySQL e para instalar usaremos o comando a seguir:

npm install --save @nestjs/typeorm typeorm mysql

E agora temos o projeto com as dependências necessárias para começarmos a parte de construção da aplicação com base na Arquitetura Hexagonal.

Construindo o domínio da aplicação

No modelo de Arquitetura Hexagonal é importante definir primeiramente a camada de domínio pois é partir dela que toda aplicação cresce, é importante também salientar que nesse modelo a camada de domínio não tem acesso as implementações e toda a comunicação é feita a partir de interfaces e adaptadores, por isso esse modelo também é chamado de ports and adapters.

Antes de entrar no código vamos entender o domínio dessa aplicação. Essa aplicação irá fazer o cadastro e a consulta de livros, então o domínio principal dessa aplicação é o Livro.

Um livro é composto aqui por um nome e também por um autor, então existe um segundo domínio chamado Autor e o autor contém o nome e a lista de livros que aquele autor escreveu. Então temos o seguinte diagrama.

Então na raiz do projeto será criado a pasta domain e criaremos duas pastas a livro e a autor e começaremos pelo domínio do Livro no arquivo livro.ts:

export class Livro {

    name: string

    autor: Autor

}

E em seguida o domínio do Autor no arquivo autor.ts:

export class Autor {

    id: string

    name: string

    livros: Livro[]

}

E já iremos adicionar a nossa porta que será a interface de comunicação e nela iremos definir duas operações, a operação de salvar save e outra para buscar todo os livros findAll no arquivos livro.repository.ts:

export interface LivroRepository{

    save(livro: Livro): Promise<Livro>

    findAll(): Promise<Livro[]>
}

E por fim iremos definir o módulo de domínio no arquivo domain.module.ts:

import { Module } from '@nestjs/common';

@Module({})
export default class DomainModule {}

Casos de uso

Quando definimos o módulo de domínio, que é o módulo mais ao centro da Arquitetura Hexagonal também criamos os casos de uso para aquele domínio, aqui vive a regra de negócio da aplicação.

Vamos criar a pasta usecase e vamos criar dois arquivos, um para a regra de inserir um livro create-livro-service.ts:

import { Livro } from "src/domain/livro/livro";
import { LivroRepository } from "src/domain/ports/livro.repository";

export class CreateLivroService{
    constructor(private readonly repository: LivroRepository){}

    async create(livroDTO: Livro): Promise<Livro>{
        return this.repository.save(livroDTO)
    }
}

E outra para buscar todos os livros find-all-livro-service.ts:

import { Livro } from "src/domain/livro/livro";
import { LivroRepository } from "src/domain/ports/livro.repository";

export class FindAllLivroService{
    constructor(private readonly repository: LivroRepository){}

    async findAll(): Promise<Livro[]>{
        return this.repository.findAll()
    }
}

Um ponto importante que deve ser notado é que nas duas classes foram adicionadas ao construtor a interface LivroRepository e com isso é usado um conceito muito importante na Arquitetura Hexagonal que é a Injeção de Dependências e com isso desacoplamos o local onde roda a lógica de negócio na aplicação de frameworks ou tecnologias bastando ser criado um adaptador, seja ele usando um framework como no nosso exemplo com TypeORM ou com qualquer outro framework ou até mesmo codificando a conexão manualmente com o banco de dados, para a nossa porta LivroRepository.

Outro ponto importante é que como essa aplicação é mais simples os casos de uso são menores mas em aplicações mais complexas fica mais nítido a separação entre regras de negócio e implementações de tecnologias e frameworks. Onde a regra de negócio ficaria bem isolada do restante do código.

Adaptadores

Com a definição do domínio e dos casos de uso, que compõe o core da aplicação está na hora de “plugar” os adaptadores que serão as implementações das portas definidas no domínio.

Iniciaremos com o adaptador que irá se comunicar com a camada de persistência de dados, será usado o TypeORM para isso, que é um ORM inspirado no Hibernate, Doctrine e Entity Framework escrito em Javascript. Juntamente ao TypeORM será usado o banco de dados MySQL.

Para adicionar essas dependências na aplicação basta rodar o comando:

npm install --save @nestjs/typeorm typeorm mysql2

Agora criaremos a entidade que representará os dados persistidos no banco de dados. Criamos a pasta adapters/repository/typeorm/entity e dentro dela iremos criar o arquivo livro.entity.ts:

import { Column, Entity, ManyToOne, PrimaryGeneratedColumn } from "typeorm";
import { AutorEntity } from "./autor.entity";

@Entity()
export class LivroEntity {

    @PrimaryGeneratedColumn()
    id: number;

    @Column({length:200})
    name: string;

    @ManyToOne(type => AutorEntity, autor => autor.livros, { cascade: ['insert'], eager: true })
    autor: AutorEntity
}

Aqui fizemos uso de Decorators que é uma feature do Typescript que são formas de adicionar metadados em uma classe, atributo ou método, são equivalentes as annotations do Java e do C#.

Vamos entender uma a uma das annotations que foram adicionadas na classe LivroEntity:

@Entity(): É usada para marcar a classe como sendo uma entidade que será administrada pelo TypeORM e que reflete uma tabela no banco de dados.
@PrimaryGeneratedColumn(): Identifica o atributo que será o id e também delega ao TypeORM a estratégia de geração do id.
@Column(): Usado para mapear as colunas da tabela, nesse caso também é passada o length da coluna.
@ManyToOne(): Definição de relacionamento com outra entidade, nesse caso a AutorEntity, onde deve ser lido como uma relação muitos LivroEntity para um AutorEntity, também definimos o relacionamento bi-direcional através do atributo autor => autor.livros, a propagação através do cascade: ['insert'] onde fica definido que somente o insert irá propagar na entidade AutorEntity e por fim o atributo eager: true onde queremos explicitamente que quando houver uma busca na entidade LivroEntity também fará uma busca na entidade AutorEntity.

Obs: a estratégia eager deve ser evitada nos casos onde a consulta possa retornar muitos resultados pois pode sobrecarregar o banco de dados e causar lentidões e problemas indesejados.

Agora será mostrado o mapeamento realizado na entidade AutorEntity no arquivo autor.entity.ts:

import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from "typeorm";
import { LivroEntity } from "./livro.entity";

@Entity()
export class AutorEntity {

    @PrimaryGeneratedColumn()
    id: number;

    @Column({ length: 100})
    name: string;

    @OneToMany(type => LivroEntity, livro => livro.autor, { cascade: ['remove'] })
    livros: LivroEntity[]

}

A única coisa diferente aqui é o Decorator @OneToMany() onde é definido o relacionamento One-to-Many entre AutorEntity e LivroEntity, a configuração de programação cascade: ['remove'] para que quando um Autor for removido do banco de dados os Livros também sejam removidos.

O mesmo pode ser representado pelo diagrama de modelo entidade relacionamento:

Com as entidades configuradas podemos agora criar efetivamente o adaptador que irá implementar a interface LivroRepository, segue o conteúdo do arquivo livro.repository.typeorm.ts e na sequência será explicado ponto a ponto:

import { Injectable, Logger } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Autor } from "src/domain/autor/autor";
import { Livro } from "src/domain/livro/livro";
import { LivroRepository } from "src/domain/ports/livro.repository";
import { Repository } from "typeorm";
import { AutorEntity } from "./entity/autor.entity";
import { LivroEntity } from "./entity/livro.entity";

@Injectable()
export default class LivroRepositoryTypeORM implements LivroRepository {

    private readonly logger = new Logger(LivroRepositoryTypeORM.name);

    constructor(@InjectRepository(LivroEntity) private readonly livroEntityRepository: Repository<LivroEntity>){}

    async save(livro: Livro): Promise<Livro> {

        const livroEntity: LivroEntity = this.mapToLivroEntity(livro)

        const livroSaved: LivroEntity = await this.livroEntityRepository.save(livroEntity)

        return this.mapToLivro(livroSaved)
    }

    async findAll(): Promise<Livro[]> {

        const livroEntityArray: LivroEntity[] = await this.livroEntityRepository.find()

        const livroArray: Livro[] = livroEntityArray.map((livroEntity) => {
            return this.mapToLivro(livroEntity)
        });

        return livroArray;
    }

    private mapToLivroEntity(livro: Livro): LivroEntity {
        let livroEntity: LivroEntity = new LivroEntity();
        livroEntity.name = livro.name

        let autorEntity = new AutorEntity()
        if(!!livro.autor.id){
            autorEntity.id = Number(livro.autor.id)
        }
        autorEntity.name = livro.autor.name

        livroEntity.autor = autorEntity

        return livroEntity
    }

    private mapToLivro(livroEntity: LivroEntity): Livro{
        let livro: Livro = new Livro()
        
        livro.name = livroEntity.name

        let autor: Autor = new Autor()

        autor.name = livroEntity.autor.name

        livro.autor = autor

        return livro
    }
    
}

O primeiro ponto é que essa classe foi marcada com o Decorator @Injectable(), isso significa que a injeção de dependências ficará sob a responsabilidade do NestJS.

O segundo ponto é que essa classe implementa a interface LivroRepository e com isso somos obrigados a definir uma implementação para s métodos save e findAll.

Um ponto ponto muito interessante de entender é o trecho a seguir de código, onde o construtor utiliza um Decorator diferente que vem do próprio TypeORM:

constructor(@InjectRepository(LivroEntity) private readonly livroEntityRepository: Repository<LivroEntity>){}

Essa é uma forma que podemos usar o TypeORM para fazer a injeção de um Repository que é uma interface que nos auxilia com os métodos para manipulação dos dados da Entidade.

Contamos com ajuda de dois métodos que fazem a transformação dos dados que receberemos, pois iremos receber objetos do domínio da aplicação e queremos transformá-los em entidades e vice e versa, então os métodos mapToLivroEntity e mapToLivro fazem isso e conseguimos tanto salvar um LivroEntity no banco de dados quanto recuperar um Livro do nosso domínio para ser exibido.

E por fim é configurado a conexão entre o TypeORM, o MySQL e o NestJS. Iremos criar a pasta adapters/repository/typeorm/config e dentro dela criaremos o arquivo typeorm-config.module.ts:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { AutorEntity } from "../entity/autor.entity";
import { LivroEntity } from "../entity/livro.entity";
import LivroRepositoryTypeORM from "../livro.repository.typeorm";


@Module({
    imports: [
        TypeOrmModule.forRoot({
            "type": "mysql",
            "host": "localhost",
            "port": 3306,
            "username": "user",
            "password": "user",
            "database": "bookstore",
            "entities": ["dist/**/*.entity{.ts,.js}"],
            "synchronize": true,
            "autoLoadEntities": true
        }),
        TypeOrmModule.forFeature([LivroEntity, AutorEntity])
    ],
    providers: [LivroRepositoryTypeORM],
    exports: [LivroRepositoryTypeORM]

})
export class TypeOrmConfigModule { }

É bom salientar que o NestJS trabalha muito bem com a ideia de módulos e por isso foi a estratégia abordada nesse projeto, então temos agora o módulo TypeOrmConfigModule em que as classes do adaptador TypeORM são “amarradas” e agora vamos entender também parte a parte da definição desse módulo:

TypeOrmModule.forRoot({
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "username": "user",
    "password": "user",
    "database": "bookstore",
    "entities": ["dist/**/*.entity{.ts,.js}"],
    "synchronize": true,
    "autoLoadEntities": true
})

Essa é uma configuração que o TypeORm pede para configurar o driver de conexão correto para o banco, as credenciais de acesso, a porta e o nome do banco que será conectado.

E também possui as seguintes propriedades que merecem um destaque especial:

entities: É passado o padrão de nomenclatura do arquivo que o TypeORM deve observar para reconhecer como sendo uma entidade de banco de dados.
synchronize: Passando true nesse atributo as tabelas são criadas automáticamente. Não é uma boa opção pensando em um código em produção, para isso existem as Migrations que não será abordada nesse artigo mas pode ser visto aqui.
autoLoadEntities: Se for informado true automaticamente serão carregadas todas as entidades que forem encontradas pelo TypeORM.

Em contraponto à configuração autoLoadEntities pode ser informado uma a uma cada entidade com a configuração:

TypeOrmModule.forFeature([LivroEntity, AutorEntity])

Por fim temos o seguinte trecho de código:

providers: [LivroRepositoryTypeORM],
exports: [LivroRepositoryTypeORM]

Onde é definido que nesse módulo será provido a implementação LivroRepositoryTypeORM e que ela também será usada fora do módulo e ficará disponível para o NestJS usar na injeção de dependência.

Controller

Nessa seção será mostrado como será usado tudo o que foi feito até o momento para expor um controller REST e para isso iremos criar um adaptador na pasta src/adapters/controller/rest/config/config-service.module.ts:

import { DynamicModule, Module } from "@nestjs/common";
import { TypeOrmConfigModule } from "src/adapters/repository/typeorm/config/typeorm-config.module";
import LivroRepositoryTypeORM from "src/adapters/repository/typeorm/livro.repository.typeorm";
import { CreateLivroService } from "src/usecase/create-livro-service";
import { FindAllLivroService } from "src/usecase/find-all-livro-service";

@Module({
    imports: [TypeOrmConfigModule]
})
export class ConfigServiceModule{

    static FIND_ALL_LIVRO_SERVICE: string = 'FindAllLivroService';
    static CREATE_LIVRO_SERVICE: string = 'CreateLivroService';
  
    static register(): DynamicModule {
        return {
            module: ConfigServiceModule,
            providers: [
                {
                    inject: [LivroRepositoryTypeORM],
                    provide: ConfigServiceModule.CREATE_LIVRO_SERVICE,
                    useFactory: (livroRepository: LivroRepositoryTypeORM) => new CreateLivroService(livroRepository)
                },
                {
                    inject: [LivroRepositoryTypeORM],
                    provide: ConfigServiceModule.FIND_ALL_LIVRO_SERVICE,
                    useFactory: (livroRepository: LivroRepositoryTypeORM) => new FindAllLivroService(livroRepository)
                }
            ],
            exports: [ConfigServiceModule.FIND_ALL_LIVRO_SERVICE, ConfigServiceModule.CREATE_LIVRO_SERVICE]
        }
    }
}

No trecho acima tem muitas coisas interessantes acontecendo e vamos entender cada uma delas.

Primeiramente importamos o módulo TypeOrmConfigModule pois aqui é onde incluiremos a injeção do adaptador do TypeORM:

@Module({
    imports: [TypeOrmConfigModule]
})

Logo em seguida é definido duas variáveis com os nomes FIND_ALL_LIVRO_SERVICE e CREATE_LIVRO_SERVICE elas serão usadas para fazer o que seria relativo a annotation @Qualifier que é usada no Java em que podemos usar para qualificarmos uma instância para ser injetada via um nome:

static FIND_ALL_LIVRO_SERVICE: string = 'FindAllLivroService';
static CREATE_LIVRO_SERVICE: string = 'CreateLivroService';

Na sequência é feito uso do DynamicModule do NestJS onde podemos criar providers dinâmicamente passando o que deve ser injetado, nesse caso o LivroRepositoryTypeORM, um provider que será o nome pelo o qual iremos injetar a instância onde formos usar, podendo ser CREATE_LIVRO_SERVICE ou FIND_ALL_LIVRO_SERVICE no nosso exemplo e um método chamado useFactory que é um método que irá “fabricar” a instância desejada passando a dependência correta:

    static register(): DynamicModule {
        return {
            module: ConfigServiceModule,
            providers: [
                {
                    inject: [LivroRepositoryTypeORM],
                    provide: ConfigServiceModule.CREATE_LIVRO_SERVICE,
                    useFactory: (livroRepository: LivroRepositoryTypeORM) => new CreateLivroService(livroRepository)
                },
                {
                    inject: [LivroRepositoryTypeORM],
                    provide: ConfigServiceModule.FIND_ALL_LIVRO_SERVICE,
                    useFactory: (livroRepository: LivroRepositoryTypeORM) => new FindAllLivroService(livroRepository)
                }
            ],
            exports: [ConfigServiceModule.FIND_ALL_LIVRO_SERVICE, ConfigServiceModule.CREATE_LIVRO_SERVICE]
        }
    }

E por fim é exportado as duas strings que são usadas para nomear os providers que serão injetados:

exports: [ConfigServiceModule.FIND_ALL_LIVRO_SERVICE, ConfigServiceModule.CREATE_LIVRO_SERVICE]

Com essa configuração feita iremos criar o Controller:

import { Body, Controller, Get, Inject, Post } from "@nestjs/common";
import { Livro } from "src/domain/livro/livro";
import { CreateLivroService } from "src/usecase/create-livro-service";
import { FindAllLivroService } from "src/usecase/find-all-livro-service";
import { ConfigServiceModule } from "../config/config-service.module";

@Controller('livro')
export class LivroController {

    constructor(@Inject(ConfigServiceModule.CREATE_LIVRO_SERVICE) private readonly createLivroService: CreateLivroService,
                @Inject(ConfigServiceModule.FIND_ALL_LIVRO_SERVICE) private readonly findAllLivroService: FindAllLivroService){}

    @Get()
    public findAll(): Promise<Livro[]>{
        return this.findAllLivroService.findAll()
    }

    @Post()
    public createLivro(@Body() livro: Livro): Promise<Livro>{
        return this.createLivroService.create(livro)
    }

}

Os Decorators usados são de dois tipos e primeiramente vamos ver os que são usados para expor a API REST:

@Controller(‘livro’): Decorator usado para indicar que essa classe será usada como um endpoint, é passado uma string para informar qual será o path, no exemplo foi passado a string livro então o path será /livro.
@Get(): Usado para indicar o verbo HTTP GET, no exemplo só passamos um GET na raiz /livro mas caso fosse necessário é possível configurar path, query params e path params.
@Post(): Também usado na raiz /livro para indicar que é possível enviar um POST no endpoint.
@Body(): Usado no método de POST e informa qual o body deve ser aceito por esse endpoint, no exemplo esse endpoint só irá aceitar requests com o formato do objeto Livro.

Fora isso também temos o Decorator @Inject() e nele passamos o nome do qualificador que deve ser carregado para que a injeção de dependência seja feita de forma correta.

Agora temos as duas pontas configuras e para que esse Controller esteja disponível para ser usado pela aplicação é necessário expô-lo como um módulo que será usado pelo NestJS:

@Module({
    imports: [ConfigServiceModule.register()],
    controllers: [LivroController]
})
export class ControllerModule{}

No código acima importamos da classe ConfigServiceModule o método register() para que os providers estejam disponíveis e informamos que esse módulo expõe um Controller que nesse caso é o LivroController.

Application

Para encerrar iremos criar a camada de application, é o módulo responsável pela entrada da aplicação. Criaremos o arquivo no path src/application/app.module.ts:

import { Module } from '@nestjs/common';
import { ControllerModule } from 'src/adapters/controller/rest/controller.module';

@Module({
  imports: [ControllerModule]
})
export class AppModule {}

No código acima basicamente foi criado o módulo AppModule e importamos o ControllerModule sem necessidade de expor nada além para o funcionamento.

A última configuração é necessária no arquivo main.ts na raiz do projeto, esse é o arquivo que será executado pelo NestJS para iniciar a aplicação e é nele que iremos fazer a configuração do Fastify e a inserção do módulo AppModule:

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './application/app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter()
  );

  await app.listen(3000);
}
bootstrap().then((r) => r);

Alteramos o padrão da função bootstrap e adicionamos a dependência do Fastify e é só isso, nenhuma configuração a mais para adicionar o Fastify como motor web da aplicação 😊

Rodando a aplicação

Antes de rodar a aplicação é necessário ter o MySQL rodando, mas para facilitar esse processo de infraestrutura iremos criar o MySQL pelo docker-compose. Na raiz do projeto basta criar o arquivo docker-compose.yml:

version: '3'
services: 

  mysql:
    image: mysql:8.0.17
    cap_add: 
      - SYS_NICE
    environment: 
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: user
      MYSQL_PASSWORD: user
      MYSQL_DATABASE: bookstore
    ports: 
      - "3306:3306"
    volumes: 
      - ./data/cadastro-api.sql:/docker-entrypoint-initdb.d/cadastro-api.sql

Adicionamos a imagem do MySQL, definimos as credenciais, portas, database e o volume que deve ser montado no start do container:

CREATE DATABASE IF NOT EXISTS bookstore;

GRANT ALL PRIVILEGES ON *.* TO 'user'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

ALTER USER 'user' IDENTIFIED WITH mysql_native_password BY 'user';
FLUSH PRIVILEGES;

E depois rodamos o comando na raiz do projeto:

docker compose up

E agora para iniciar a aplicação podemos usar o comando a seguir:

npm run start:dev

E para testar o endpoint podemos fazer um POST para inserir um livro com um autor associado:

curl --location --request POST 'localhost:3000/livro' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Vidas secas",
    "autor": {
        "name": "Graciliano Ramos"
    }
}' | json_pp

E teremos o resultado:

{
    "name": "Vidas secas",
    "autor": {
        "name": "Graciliano Ramos"
    }
}

E fazendo o GET:

curl --location --request GET 'localhost:3000/livro' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Vidas secas",
    "autor": {
        "name": "Graciliano Ramos"
    }
}' | json_pp

Teremos o resultado:

[
    {
        "name": "Vidas secas",
        "autor": {
            "name": "Graciliano Ramos"
        }
    }
]

Conclusão

Aqui aprendemos como usar o NestJS e como ele e o Typescript auxiliam o desenvolvedor a criar aplicações usando a tipagem estática do Typescript e o sistema de módulos e injeção de dependências do NestJS. Também vimos como usar o TypeORM para abstrair a comunicação com banco de dados e como conseguimos tirar vantagem de um padrão arquitetural como a Arquitetura Hexagonal para deixar a aplicação focada nas regras de negócio ao invés de ficar acoplada a tecnologias e frameworks.

Por fim vimos como usar o Fastify na aplicação, o que é extremamente simples e transparante quando estamos usando NestJS.

Código fonte

O código fonte desse projeto está disponível no Github

Validando endpoints com NodeJS

Tue, 27 Apr 2021 00:00:01 GMT

Introdução

No último artigo vimos como integrar a uma aplicação Express com o banco de dados não relacional MongoDB. Porém detectamos que estávamos expondo mais informações do que queríamos na resposta das operações, ex:

{
    "id": 1,
    "name": "Kelly",
    "telephone": "118888888",
    "address": "Rua dos Bobos n 1",
    "_id": "607d805caa972341ebd3e568"
}

A exposição do campo _id não é uma boa pratica pois pode expor detalhes internos que não queremos compartilhar com o mundo externo.

Além disso a API ainda não efetua nenhuma validação sobre os dados que recebe e como queremos manter a consistência dos dados que serão inseridos iremos adicionar ao projeto a biblioteca de validações Joi e o middleware Celebrate para tratamento das respostas da API.

Transformando o modelo

No primeiro artigo criamos a classe Contact mas não chegamos a usá-la, agora iremos revê-la e começaremos a usar o modelo na aplicação.

É muito importante ser definido um domínio para a sua aplicação, um domínio bem estruturado e planejado impede que aplicações que começaram simples cresçam sem controle, agregando mais responsabilidades do que deveriam lidar. Esse é um problema antigo mas com o advento dos microservices ficou explícito o quanto é importante haver um domínio bem estruturado.

Nessa aplicação o domínio é óbvio, contatos, porém nem sempre isso é tão claro e vale a pena investir um bom tempo separando os domínios de uma aplicação e como eles se relacionam e trocam informações uns com os outros.

Olhando para o arquivo na pasta model temos o seguinte:

const Contact = {

    id: 0,
    name: "",
    telephone: "",
    address: ""

}

module.exports = Object.create(Contact)

Um ponto importante sobre domínios de aplicação é que eles não devem guardar informações que não sejam referentes ao seu domínio. Parece óbvio essa ideia porém como visto no exemplo acima temos um objeto Contato porém existe nele um campo chamado id que poderia ser usado por um banco de dados contudo não agrega valor ao domínio Contato, a primeira coisa seria excluí-lo. A segunda coisa que podemos usar para nos ajudar a manipular os dados do nosso domínio é ter uma forma de criarmos o objeto, uma função criadora que receba os dados de um contato e devolva uma instância pronta. Há algumas formas de fazer porém aqui iremos usar um construtor, uma função que toda classe já possui no JavaScript e já é responsável por criar o objeto.

Para podermos usar um construtor é necessário algumas alterações no objeto Contato:

class Contact {

    constructor(name, telephone, address){
        this.name = name
        this.telephone = telephone
        this.address = address
    }

}

module.exports = Contact

Agora tiramos o campo id do domínio e alteramos o objeto Contato para que ele seja uma classe, com um construtor e três variáveis que são informadas no momento da criação.

Vamos usar a classe Contato, porém onde seria o lugar mais apropriado para isso?

Podemos delegar para a camada da nossa aplicação que é responsável por executar a lógica, a camada Service. Faz sentido pois nessa camada executamos as regras que são pertinentes e salvamos no banco de dados, então bem que podemos fazer esse tratamento lá.

const Contact = require('../model')

class Service{

    constructor(repository){
        this.repository = repository
    }

    create(body){
        const contact = new Contact(body.name, body.telephone, body.address)
        this.repository.insert(contact)
    }
    
    async getById(name){
        const contact = await this.repository.selectById(name)

        return new Contact(contact.name, contact.telephone, contact.address)
    }
    
    async getAll(){
        const contactList = await this.repository.selectAll()

        const result = contactList.map((contact) => {
            return new Contact(contact.name, contact.telephone, contact.address)
        })

        return result
    }
    
    async put(name, body){
        const contact = await this.repository.update(name, new Contact(body.name, body.telephone, body.address))

        const result = contact.value

        return new Contact(result.name, result.telephone, result.address)
    }

    async patch(name, body){
        return this.repository.patch(name, body);
    }
    
    remove(name){
        this.repository.remove(name)
    }

}

module.exports = Service

No código acima para cada ponto que precisamos inserir ou recuperar os dados da aplicação iremos usar a classe Contato para mantermos o padrão de domínio.

Para ficar mais claro iremos fazer as requisições para a API e ver as respostas.

curl --location --request POST 'http://localhost:3000/api' \
--header 'Content-Type: application/json' \
--data-raw '{
    
    "name": "Kelly",
    "telephone": "1199999999",
    "address": "Rua dos Bobos n 2"

}' | json_pp

E temos como resposta o seguinte:

{
    "name": "Kelly",
    "telephone": "1199999999",
    "address": "Rua dos Bobos n 2"
}

Podemos notar que não existe mais um campo id, apesar de internamente existir e ser importante para o banco de dados para o nosso domínio e para a nossa resposta ao usuário que fez essa chamada não é.

Adicionando validação

A nossa aplicação ainda não é capaz de validar a entrada de dados. Validar entrada de dados é algo que pode começar simples e logo se torna muito complicado dependendo das regras, para nos ajudar com isso existe uma biblioteca especializada nisso, o JOI, onde conseguimos definir regras a serem seguidas. Validar entrada de dados é algo que pode ser muito complicado e o JOI possui uma vasta documentação para nos ajudar com regras, desde as mais simples até as mais complexas usando Regex.

Em conjunto com o JOI, que faz a validação dos dados que estão entrando na aplicação precisamos devolver uma resposta clara e padronizada ao usuário sobre o erro ocorrido. Para isso usaremos o middleware Celebrate que integra muito bem ao JOI.

Precisamos adicionar somente o Celebrate ao projeto, pois o JOI é usado internamente pelo Celebrate:

npm install --save celebrate

E vamos começar criando a parte da nossa aplicação que será responsável por fazer as validações, vamos criar um pasta chamada validation e nela criamos o arquivo index.js:

const { Joi } = require('celebrate')

const bodySchema = Joi.object().keys({
    name: Joi.string().min(3).required(),
    telephone: Joi.string().required(),  
    address: Joi.string().required()
})

const pathSchema = { name: Joi.string().min(3).required() } 

module.exports = {
    bodySchema,
    pathSchema
}

Definimos as seguintes validações:

Quando for passado um body são obrigatórios todos os campos e o campo name deve ter pelo menos 3 caracteres.
Quando for passado um pathParam de nome name, ele é obrigatório e deve ter pelo menos 3 caracteres.

Agora precisamos adicionar essas validações nas rotas, mas antes disso para que o Celebrate possa lidar com as mensagens de erro é necessário adicioná-lo como middleware para o Express:

const express = require('express')
const app = express()
const bodyParser = require('body-parser')
const router = require('./router')
//Declaração do middleware de erros do Celebrate
const { errors } = require('celebrate')

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))

app.use((req, resp, next) => {
    resp.set('Access-Control-Allow-Origin', '*')
    next()
})

app.use('/api', router)

//Inclusão do middleware
app.use(errors())

const server = app.listen(3000, () => console.log('A API está funcionando!'))

module.exports = server

E após podemos adicionar as validações nas rotas:

const { celebrate, Segments } = require('celebrate')
const validation = require('../validation')

router.post('/', celebrate({[Segments.BODY]: validation.bodySchema }), async (req, res) => {
    const contact = req.body

    service.create(contact)

    res.status(201).json(contact)
})

router.get('/:name', celebrate({[Segments.PARAMS]: validation.pathSchema }), async (req, res) => {

    const id = req.name_from_param

    const result = await service.getById(id)
    if(result !== undefined){
        res.status(200).json(result)
        return
    }
    
    res.sendStatus(204)
    
})

As funções de rotas do Express podem receber um argumento que é um handler e no nosso caso será o Celebrate juntamente com a validação do JOI.

Na função celebrate é passado um objeto onde a chave é o segmento, Segments, que deve ser validado, no nosso exemplo validamos tanto o body com o Segments.BODY e o pathParam com o Segments.PARAMS; e o valor é a validação que deve ser aplicada.

Com isso podemos testar a API, primeiramente com POST:

curl --location --request POST 'http://localhost:3000/api' \
--header 'Content-Type: application/json' \
--data-raw '{
    
    "name": "Kelly",
    "address": "Rua dos Bobos n 2"

}' | json_pp

E teremos a seguinte validação:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "celebrate request validation failed",
    "validation": {
        "body": {
            "source": "body",
            "keys": [
                "telephone"
            ],
            "message": "\"telephone\" is required"
        }
    }
}

E agora com um GET:

curl --location --request GET 'http://localhost:3000/api/k'

E como resposta teremos:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "celebrate request validation failed",
    "validation": {
        "params": {
            "source": "params",
            "keys": [
                "name"
            ],
            "message": "\"name\" length must be at least 3 characters long"
        }
    }
}

Conclusão

Nesse artigo foi apresentado como podemos deixar a nossa aplicação um pouco mais coerente através de uma especificação de domínio e inserir validações que nos ajudam a proteger a aplicação de inserção de dados errados ou consultas desnecessárias.

Código do projeto

O código desse artigo está no GitHub.

Express e MongoDB

Mon, 19 Apr 2021 00:00:01 GMT

Introdução

No último artigo foi apresentado como construir uma API REST do zero usando NodeJS e Express, foi mostrado como usar o príncipio de injeção de dependências para conseguirmos desacoplar detalhes de implementações.

Agora iremos evoluir um pouco mais esse projeto e iremos adicionar um banco de dados real, no caso será usado MongoDB. Vamos configurar o ambiente usando Docker Compose e vamos entrar em detalhes que não foram apresentados no artigo anterior como os verbos HTTP PUT e PATCH.

Adicionando MongoDB

Vamos adicionar o MongoDB no projeto e para isso iremos começar adicionando essa dependência com o comando abaixo:

npm install --save mongodb

Rodando esse comando o NPM irá adicionar e baixar as dependências necessárias.

Como estamos usando o Docker Compose vamos criar o arquivo docker-compose.yml na raiz do projeto (caso não tenha o Dokcer ou o Docker Compose instalados basta seguir esse tutorial):

version: '3'

services:

  mongo:
    image: mongo
    container_name: mongo
    environment: 
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: phonebook
    volumes: 
      - ./data/init.js:/docker-entrypoint-initdb.d/init.js:ro
    ports:
      - 27017:27017

Analisando o arquivo acima além da definição da versão que será usada pelo Docker Compose temos a declaração services que serão os serviços que serão inicializados, que no caso foi chamado de mongo.

Logo após temos a o campo image onde definimos o nome e a versão da imagem Docker que será usada, nesse caso será usada a imagem do MongoDB e como não foi passado uma versão especifica será usado a versão latest.

No campo environment definimos todas as variáveis de ambiente que usaremos nessa imagem. Basicamente definimos um user e password admins do banco e já iniciamos o MongoDB com o database phonebook que usamos na aplicação.

Por fim seria útil além de iniciar o banco já iniciarmos com a collection de contatos, na documentação do MongoDB no DockerHub encontramos uma forma de fazer isso, basta mapearmos um volume contendo um arquivo .sh ou .js e apontarmos para docker-entrypoint-initdb.d que ele será executado. Então aqui é o lugar perfeito para incluirmos a inicialização da collection como mostrado abaixo:

print('---> CONNECTING DATABASE <---');

db = db.getSiblingDB('phonebook');

print('---> CREATING COLLECTION <---');

db.createCollection('contact');

print('---> CREATING INDEX <---');

db.contact.createIndex({ name: 1 }, { unique: true })

print('---> SUCCESS TO RUN SCRIPT <---');

No código acima basicamente nos conectamos no database phonebook e criamos a collection contact e por fim criamos um índice para o campo name.

Se iniciarmos o Docker Compose teremos uma saída que deverá conter entre outras coisas essa informação:

> docker-compose up
>
> mongo    | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/init.js
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.705+00:00"},"s":"I",  "c":"NETWORK",  "id":22943,   "ctx":"listener","msg":"Connection accepted","attr":{"remote":"127.0.0.1:38750","connectionId":3,"connectionCount":1}}
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.705+00:00"},"s":"I",  "c":"NETWORK",  "id":51800,   "ctx":"conn3","msg":"client metadata","attr":{"remote":"127.0.0.1:38750","client":"conn3","doc":{"application":{"name":"MongoDB Shell"},"driver":{"name":"MongoDB Internal Client","version":"4.4.5"},"os":{"type":"Linux","name":"Ubuntu","architecture":"x86_64","version":"18.04"}}}}
> mongo    | ---> CONNECTING DATABASE <---
> mongo    | ---> CREATING COLLECTION <---
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.720+00:00"},"s":"I",  "c":"STORAGE",  "id":20320,   "ctx":"conn3","msg":"createCollection","attr":{"namespace":"phonebook.contact","uuidDisposition":"generated","uuid":{"uuid":{"$uuid":"dfab7eaa-99b0-4b3b-9f41-07b104a27fdb"}},"options":{}}}
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.738+00:00"},"s":"I",  "c":"INDEX",    "id":20345,   "ctx":"conn3","msg":"Index build: done building","attr":{"buildUUID":null,"namespace":"phonebook.contact","index":"_id_","commitTimestamp":{"$timestamp":{"t":0,"i":0}}}}
> mongo    | ---> CREATING INDEX <---
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.739+00:00"},"s":"I",  "c":"INDEX",    "id":20438,   "ctx":"conn3","msg":"Index build: registering","attr":{"buildUUID":{"uuid":{"$uuid":"b8a5db18-ea67-4b2b-aad0-fe81e6f46df6"}},"namespace":"phonebook.contact","collectionUUID":{"uuid":{"$uuid":"dfab7eaa-99b0-4b3b-9f41-07b104a27fdb"}},"indexes":1,"firstIndex":{"name":"name_1"}}}
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.811+00:00"},"s":"I",  "c":"INDEX",    "id":20345,   "ctx":"conn3","msg":"Index build: done building","attr":{"buildUUID":null,"namespace":"phonebook.contact","index":"name_1","commitTimestamp":{"$timestamp":{"t":0,"i":0}}}}
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.812+00:00"},"s":"I",  "c":"INDEX",    "id":20440,   "ctx":"conn3","msg":"Index build: waiting for index build to complete","attr":{"buildUUID":{"uuid":{"$uuid":"b8a5db18-ea67-4b2b-aad0-fe81e6f46df6"}},"deadline":{"$date":{"$numberLong":"9223372036854775807"}}}}
> mongo    | {"t":{"$date":"2021-04-12T19:35:18.812+00:00"},"s":"I",  "c":"INDEX",    "id":20447,   "ctx":"conn3","msg":"Index build: completed","attr":{"buildUUID":{"uuid":{"$uuid":"b8a5db18-ea67-4b2b-aad0-fe81e6f46df6"}}}}
> mongo    | ---> SUCCESS TO RUN SCRIPT <---

Com isso já teremos uma instância do MongoDB rodando e pronta para usar.

Injetando o banco como dependência

Voltando agora para a aplicação precisamos conectar o MongoDB no projeto, para isso iremos começar criando o arquivo mongo_repository.js na pasta repository do projeto:

const MongoClient = require('mongodb').MongoClient

class MongoRepository{

    constructor(connectionString){
        this.connectionString = connectionString
        this.contactCollection = null
    }

    async init(){
        await this._connect(this.connectionString)
    }

    async _connect(connectionString){

        const client = await MongoClient.connect(connectionString, {useUnifiedTopology: true})
        const db = client.db('phonebook')
        this.contactCollection = db.collection('contact')

        return this.contactCollection


    }

    insert(contact){
        this.contactCollection.insertOne(contact)
        .then(result => console.log("Dados inseridos com sucesso", result.result))
        .catch(err => {throw new Error(err)})
    }

    async selectAll(){
        return await this.contactCollection.find().toArray()
    }

    async selectById(name){
        return await this.contactCollection.findOne({name: name})
    }

    async update(name, contact){
        return await this.contactCollection.findOneAndUpdate(
            {name: name},
            {
                $set: {
                    name: contact.name,
                    telephone: contact.telephone,
                    address: contact.address
                }
            },
            {
                upsert: true
            }    
        )
    }
    
    remove(name){
        this.contactCollection.deleteOne({name: name})
        .then(result => console.log(result.result))
        .catch(err => {throw new Error(err)})
    }
}

module.exports = MongoRepository

O código acima é uma classe JavaScript onde no seu construtor definimos que queremos receber a string de conexão com o MongoDB, logo abaixo temos a função init que se conectará ao banco e a collection e na sequência temos os métodos para realizarmos as operações de CRUD no MongoDB.

Com isso podemos trocar a classe InMemoryRepository pela MongoRepository no projeto facilmente de forma transparente para a aplicação:

const router = require('express').Router()
const MongoRepository = require('../repository/mongo_repository.js')
const Service = require('../service')
const MongoRepo = new MongoRepository('mongodb://admin:password@localhost:27017')
MongoRepo.init()
const service = new Service(MongoRepo)

router.param('name', (req, res, next, name) => {
    req.name_from_param = name
    next()
})

router.post('/', async (req, res) => {
    const contact = req.body

    service.create(contact)

    res.status(201).json(contact)
})

router.get('/:name', async (req, res) => {

    const id = req.name_from_param

    const result = await service.getById(id)
    if(result !== undefined){
        res.status(200).json(result)
        return
    }
    
    res.sendStatus(204)
    
})

router.get('/', async (req, res) => {

    const result = await service.getAll()

    if(result.length > 0){
        res.status(200).json(result)
        return
    }

    res.sendStatus(204)
    
})

router.put("/:name", async (req, res) => {

    const name = req.params.name
    const body = req.body

    const result = await service.put(name, body)

    res.status(200).json(result)
})

router.delete("/:name", async (req, res) => {

    const name = req.params.name

    service.remove(name)

    res.sendStatus(204)
})

module.exports = router

Entendo o código acima por partes, primeiramente temos a importação e nela já iniciamos o banco e o injetamos como dependência na Service:

const MongoRepository = require('../repository/mongo_repository.js')
const Service = require('../service')
const MongoRepo = new MongoRepository('mongodb://admin:password@localhost:27017')
MongoRepo.init()
const service = new Service(MongoRepo)

E o restante do código basicamente não se altera, essa é uma das grandes vantagens de não usar um código acoplado, é a facilidade que temos de trocá-lo rápidamente quando necessário, então temos um código com baixo acoplamento mas com alta coesão já que suas funcionalidades estão explicitas e segregadas.

Testando as alterações

Da mesma forma que foi dito anteriormente nada foi alterado com a mudança do banco de dados então para quem estiver usando a aplicação nada deve mudar. Vamos testar isso agora.

Realizando um POST teremos o seguinte resultado:

curl --location --request POST 'http://localhost:3000/api' \
--header 'Content-Type: application/json' \
--data-raw '{

    "id": 1,
    "name": "Kelly",
    "telephone": "118888888",
    "address": "Rua dos Bobos n 1"

}' | json_pp

Teremos o seguinte resultado:

{
    "id": 1,
    "name": "Kelly",
    "telephone": "118888888",
    "address": "Rua dos Bobos n 1",
    "_id": "607d805caa972341ebd3e568"
}

Está muito parecido com o que tínhamos porém temos um detalhe que não havia antes que é o campo _id que está retornando.

Isso é um problema por alguns motivos mas o principal deles é que o nosso modelo está seguindo a implementação do banco de dados e isso causa uma aplicação acoplada, para resolver isso teremos que começar a usar o modelo que foi definido no primeiro artigo, mas não será visto agora pois teremos que fazer algumas alterações para isso e acredito que ficará muito extenso fazer aqui e foge um pouco da temática desse artigo que é de se conectar ao banco do MongoDB; porém para agora vamos deixar assim mas sabendo que é um ponto de alteração também pelo fato de expor um id interno poder ser considerado uma falha de segurança da aplicação.

Obs: Foi realizada uma alteração no módulo de rotas pois as chamadas GET /health e GET /:name estavam conflitando então foi necessário adicionar a seguinte configuração:

router.param('name', (req, res, next, name) => {
    req.name_from_param = name
    next()
})

E após isso o roteamento do GET /health deve ser feito antes do roteamento do GET /:name

router.get('/health', (req, res) => {

    res.status(200).json({status: "Ok"})
})

router.get('/:name', async (req, res) => {

    const id = req.name_from_param

    const result = await service.getById(id)
    if(result !== undefined){
        res.status(200).json(result)
        return
    }
    
    res.sendStatus(204)
    
})

PUT vs PATCH

Temos hoje no projeto configurado as rotas para fazer criação, leitura, escrita e deleção de dados, mas como pode ser visto nós usamos o verbo HTTP PUT quando queremos atualizar um contato, porém o PUT é usado quando queremos realizar atualizações completas em uma entidade, o que devemos fazer nesse caso se quisermos atualizar somente um campo do contato?

Para isso existe o verbo HTTP PATCH e ideia por trás dele é usarmos quando precisamos fazer atualizações parciais em uma entidade. Para isso vamos preparar a partir das rotas até a persistência no banco de dados.

Começando pelo módulo router:

router.patch("/:name", async (req, res) => {

    const name = req.params.name
    const body = req.body

    service.patch(name, body)

    res.sendStatus(204)
})

Não muda muita coisa do que já foi feito nas outras rotas, usamos a função patch do Express e informamos no path que passaremos o name como parâmetro e o body com o objeto que conterá a atualização parcial e chamamos a service que também deverá possuir uma função chamada patch.

Agora no módulo service:

patch(name, body){
    return this.repository.patch(name, body);
}

Aqui é mais simples pois só é usado como um adaptador para a chamada ao módulo de persistência nesse momento.

E por fim no arquivo mongo_repository.js no módulo repository:

async patch(name, contact){
    return await Object.entries(contact).forEach(([key, value]) => {
        let obj = {}
        obj[key] = value
        return this.contactCollection.findOneAndUpdate({name: name}, {$set: obj})
    })
}

Aqui usamos a função Object.entries que itera sobre um objeto e devolve um array onde a chave é o nome do atributo e o valor é o valor daquele atributo e com isso conseguimos iterar por esse array e realizar a operação que atualizará somente os campos que informamos.

Agora conseguimos testar e teremos a atualização parcial:

curl --location --request PATCH 'http://localhost:3000/api/Kelly' \
--header 'Content-Type: application/json' \
--data-raw '{
    "address": "novo endereco novo"
}'

Mas a questão que pode ser discutida é por que usar dois verbos HTTPs diferentes para fazer quase a mesma coisa? Por que não usar o PUT e fazer a atualização do que for passado, seja uma entidade inteira ou apenas parcial?

A resposta pra isso é que os verbos HTTPs são guias de como a sua API funciona então a semântica deles importa e quando entrarmos nos detalhes sobre documentação de APIs vamos conseguir entender melhor que para quem usar a API é melhor se usarmos um padrão do que ter que ter uma longa documentação sobre os detalhes internos do processamento de dados. Mais detalhes sobre o PATCH podem ser encontrados aqui.

Conclusão

Nesse artigo vimos como configurar o MongoDB usando o Docker Compose e como podemos usufruir da inversão de dependências para poder trocar facilmente dependências sem quebrar o nosso código ganhando mais produtividade.

Vimos como conectar a aplicação ao MongoDB e também aprendemos um pouco sobre o verbo HTTP PATCH e saímos com um ponto de melhoria que é a exposição de entidades pela nossa API, veremos como melhorar essa parte no próximo artigo.

Código do projeto

Segue o GitHub com o projeto usado nesse artigo.

NodeJS e Express

Tue, 06 Apr 2021 00:00:01 GMT

Introdução

Neste artigo será mostrado como criar um projeto com NodeJS e Express e vamos expor uma API para podermos realizar as quatro operações básicas de um CRUD (criar, ler, atualizar e deletar dados). Também será mostrado como podemos construir um projeto de forma simples, descomplicada, com baixa acoplamento e alta coesão entre seus componentes por meio de injeção de dependências e inversão de controle.

Fazendo uma breve introdução sobre as tecnologias que serão apresentadas nesse artigo, primeiramente temos o NodeJS que é um projeto open-source criado para ser um ambiente de desenvolvimento backend escrito em JavaScript, ele explora os benefícios que o JavaScript possui, como orientação a eventos e assíncronicidade.

Juntamente com o NodeJS usaremos nesse projeto o Express que é um framework para desenvolvimento de aplicações web minimalista, isso significa que ele é bem leve e simples mas que não trás consigo todas as funcionalidades por padrão de um servidor web e isso é uma grande vantagem do Express pois é um dos motivos pelo qual ele é muito flexível, e por meio de middlewares é possível plugar libs e ferramentas que nos ajudam no desenvolvimento.

Criando o projeto

O projeto consistirá em uma agenda de contatos, onde poderemos criar um contato novo, buscar um contato ou todos, editar um existente e deletar um contato.

Existem algumas maneiras de criar um projeto com Express, o próprio Express possui um cli para criação.

Aqui iremos fazer de uma forma que eu considero mais simples que é criar via command line* com **NPM.

Vamos criar uma pasta chamada phonebook e após isso, criar o projeto usando NPM:

mkdir phonebook && cd phonebook
npm init -y

Com isso temos a estrutura básica do projeto que nada mais é do que um arquivo package.json:

{
  "name": "phonebook",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Vamos aproveitar e instalar as dependências que vamos precisar para iniciar esse projeto:

npm install express body-parser

E também as dependências que usaremos posteriormente para subir o nosso server no ambiente de local de desenvolvimento e testes:

npm install --save-dev nodemon jest supertest

Agora falta criarmos o arquivo que será executado quando iniciarmos a aplicação, vamos chamá-lo de index.js:

const express = require('express')
const app = express()
const bodyParser = require('body-parser')

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))

app.use((req, resp, next) => {
    resp.set('Access-Control-Allow-Origin', '*')
    next()
})

const server = app.listen(3000, () => console.log('A API está funcionando!'))

module.exports = server

Só com isso podemos executar o node chamando o arquivo index.js que deverá funcionar:

npm run dev

> phonebook@1.0.0 dev /Users/guilherme/develop/repo/phonebook
> nodemon index.js

[nodemon] 2.0.7
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node index.js`
A API está funcionando!

Modelando o domínio

Decidi começar pela definição de modelo, porque apesar desse modelo ser simples eu entendo que é sempre bom deixar essa base pronta pois fica mais fácil construir a aplicação em volta de um domínio do que o contrário. Acredito que utilizar outras tecnologias fica mais flexível de mudar do que a mudança no domínio nessa abordagem.

Então iremos criar uma pasta chamada model e nela a index.js:

const Contact = {

    id: 0,
    name: "",
    telephone: "",
    address: ""

}

module.exports = Object.create(Contact)

A definição acima é a representação do que seria um contato em uma agenda de contatos composta pelo id, (aqui entra um discussão sobre Entidades e VO mas para esse exemplo deixei com um id pois acredito que o modelo em um projeto real não deveria possuir um id provavelmente voltaremos a esse ponto em um artigo futuro) name, telephone e address que são Strings e no exports criamos esse objeto com a função create.

Criando a Repository

Após ter criado o domínio vamos criar a nossa Repository que será responsável por lidar com a persistência de dados. Você pode ter percebido que até o momento não adicionamos nenhuma dependência de persistência então como iremos criar o comportamento responsável por isso?

Vamos aqui simplificar um pouco as coisas e iremos criar uma persistência em memória e mais a frente vamos entender como podemos deixar tudo bem simples e desacoplado usando a Injeção de Dependências e Inversão de Controle.

Vamos criar uma pasta chamada repository e dentro dela o nosso arquivo index.js:

class InMemoryRepository{

    constructor(){
        this._data = []
    }

    insert(contact){
        this._data.push(contact)
    }
    
    selectAll(){
        return this._data
    }
    
    selectById(id){
        return this._data.find(c => c.id === id)
    }
    
    update(id, contact){
    
        const elementId = this._data.findIndex(element => element.id === id);
        contact.id = id
    
        const updateContact = Object.assign(this._data[elementId], contact)
    
        this._data[elementId] = updateContact
    
        return this._data[elementId]
    }
    
    remove(id){
    
        const index = this._data.findIndex(element => element.id === id)
    
        this._data.splice(index, 1)
    
    }
}

module.exports = InMemoryRepository

Foi usada uma abordagem de classe aqui justamente para depois podermos usar a Injeção de Dependências, mas podemos ver também que temos uma variável membro chamada _data que é um array e temos as funções que irão fazer as nossas operações de CRUD em cima desse array.

Após isso exportamos a nossa classe InMemoryRepository.

Criando Services

Agora chegou a hora de criar a camada da aplicação que é responsável por executar a lógica de negócios.

Vamos criar uma pasta chamada service e dentro dela o arquivo index.js:

class Service{

    constructor(repository){
        this.repository = repository
    }

    create(body){
        this.repository.insert(body)
    }
    
    getById(id){
        return this.repository.selectById(parseInt(id, 2))
    }
    
    getAll(){
        return this.repository.selectAll()
    }
    
    put(id, body){
        return this.repository.update(parseInt(id, 2), body)
    }
    
    remove(id){
        this.repository.remove(parseInt(id, 2))
    }

}

module.exports = Service

Aqui também usamos a abordagem de classe, mas por que?

Pois assim é possível injetar a dependência do repository no construtor e com isso o controle é invertido já que a Service desconhece qual será a implementação a ser usada, a única coisa que importa para a Service é que a repository que será passada deve possuir as funções de insert, selectById, selectAll, update e remove. Não é responsabilidade da Service saber se a repository é um banco em memória, MongoDB, Postgres ou qualquer outro meio de persistir dados.

Caso seja necessário no futuro implementar alguma outra ação ou mude a lógica de negócios, esta alteração deve ser implementada na Service e caso necessite de outra dependência deve ser adicionado ou injetado no construtor da classe.

Configurando Rotas

Vamos criar as rotas da nossa aplicação, aqui iremos definir quais verbos HTTP iremos deixar disponíveis e que iremos direcionar as requisições quando elas chegarem.

const router = require('express').Router()
const InMemoryRepository = require('../repository')
const Service = require('../service')
const service = new Service(new InMemoryRepository())

router.post('/', (req, res) => {
    const contact = req.body

    service.create(contact)

    res.status(201).json(contact)
})

router.get('/:id', (req, res) => {

    const id = req.params.id

    const result = service.getById(id)
    if(result !== undefined){
        res.status(200).json(result)
        return
    }
    
    res.sendStatus(204)
    
})

router.get('/', (req, res) => {

    const result = service.getAll()

    if(result.length > 0){
        res.status(200).json(result)
        return
    }

    res.sendStatus(204)
    
})

router.put("/:id", (req, res) => {

    const id = req.params.id
    const body = req.body

    const result = service.put(id, body)

    res.status(200).json(result)
})

router.delete("/:id", (req, res) => {

    const id = req.params.id

    service.remove(id)

    res.sendStatus(204)
})

router.get('/health', (req, res) => {

    res.status(200).json({status: "Ok"})
})

router.options('/', (req, res) => {
    res.set('Access-Control-Allow-Methods', 'GET, POST')
    res.set('Access-Control-Allow-Headers', 'Content-Type')
    res.status(204)
    res.end()
})

module.exports = router

Vamos por partes pra entender tudo o que está no código acima:

const router = require('express').Router()
const InMemoryRepository = require('../repository')
const Service = require('../service')
const service = new Service(new InMemoryRepository())

Nesse trecho importamos do próprio Express a dependência do Router que irá disponibilizar aqui os verbos HTTP, importamos aqui as classes InMemoryRepository e Service e em seguida instânciamos a Service e passamos a dependência de uma Repository para ela que nesse caso será a InMemoryRepository.

router.post('/', (req, res) => {
    const contact = req.body

    service.create(contact)

    res.status(201).json(contact)
})

Aqui usamos o router e chamamos o método post e passamos qual será o path ou caminho que será exposta na API, aqui deixamos com '/'para indicar que não queremos passar nada na url só de chamar um POST ele será atendido por esse método.

A função post trás consigo o request e o response e com isso podemos extrair algumas informações importantes no request e adicionar dados no response.

No exemplo acima conseguimos pegar o body que é enviado na requisição e após executar a lógica na Service adicionar o status e o body no response.

Aqui abaixo temos as implementações do GET:

router.get('/:id', (req, res) => {

    const id = req.params.id

    const result = service.getById(id)
    if(result !== undefined){
        res.status(200).json(result)
        return
    }
    
    res.sendStatus(204)
    
})

router.get('/', (req, res) => {

    const result = service.getAll()

    if(result.length > 0){
        res.status(200).json(result)
        return
    }

    res.sendStatus(204)
    
})

O interessante aqui é entender que no request também conseguimos pegar parâmetros passados na url para isso precisamos de um identificador no path que é passado na função get no caso acima é :id a na função pegamos o valor através da sintaxe req.params.id.

A lógica nas requisições GET é que caso não encontre dados na consulta retorne o status 204 - No Content e caso encontre retorna 200 - Ok com os dados solicitados.

Os métodos para PUT e DELETE seguem a mesma lógica.

Configurando o Express e middlewares

Temos a Service e as Rotas configuradas e agora é necessário adicionar o módulo de rotas ao Express para que ele consiga utilizar e assim ficar disponível para ser usado.

No arquivo index.js na raiz do projeto já existe uma configuração:

const express = require('express')
const app = express()
const bodyParser = require('body-parser')

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))

app.use((req, resp, next) => {
    resp.set('Access-Control-Allow-Origin', '*')
    next()
})

const server = app.listen(3000, () => console.log('A API está funcionando!'))

module.exports = server

Com essa configuração já estamos usando os middlewares, onde adicionamos as funções que queremos complementar ao Express, acima estamos usando a lib body-parser para ajudar com o parse da resposta e outro middleware para tratativa de CORS e vamos adicionar o nosso módulo de rotas:

const express = require('express')
const app = express()
const bodyParser = require('body-parser')
const router = require('./router')

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))

app.use((req, resp, next) => {
    resp.set('Access-Control-Allow-Origin', '*')
    next()
})

app.use('/api', router)

const server = app.listen(3000, () => console.log('A API está funcionando!'))

module.exports = server

Acima foi importado o módulo router e adicionado no Express através da função use onde definimos o path raiz da nossa API e no segundo argumento o módulo router.

Iniciando a aplicação

Podemos iniciar a aplicação dessa forma:

nodemon index.js

E fazendo um POST:

curl --location --request POST 'http://localhost:3000/api' \
--header 'Content-Type: application/json' \
--data-raw '{

    "id": 1,
    "name": "Kelly",
    "telephone": "118888888",
    "address": "Rua dos Bobos n 1"

}' | json_pp

Teremos a seguinte resposta:

{
   "id" : 1,
   "name" : "Kelly",
   "address" : "Rua dos Bobos n 1",
   "telephone" : "118888888"
}

Testes

No começo do artigo adicionamos as dependências do jest e supertest e agora vamos implementar um teste.

Na pasta router vamos criar o arquivo router.test.js, seguindo a convenção de nomenclatura do jest para que ele saiba quais arquivos devem ser testados.

Dentro do arquivo vamos criar a nossa primeira suite de testes para testar a rota de POST:

const supertest = require('supertest')
const server = require('../index')

afterAll( async () => {
  server.close()
});

describe('Make requests to the server', () => {

    it('Should create a contact', async () => {
        const resp = await supertest(server).post('/api').send({
            "id": 1,
            "name": "Kelly",
            "telephone": "118888888",
            "address": "Rua dos Bobos n 1"
        });

        expect(resp.statusCode).toEqual(201)
        expect(resp.body.name).toEqual("Kelly")
    })

})

Aqui importamos a lib do supertest e o arquivo index.js da raíz do projeto, primeiramente adicionamos uma função chamada afterAll para que após o testes serem rodados a aplicação seja terminada.

Criamos a suite de testes com a função describe e dentro dela colocamos os testes necessários para testar aquela suite com a função it.

Para fazer o mock da requisição usamos o supertest a passamos para ele o nosso server, invocamos a função HTTP que queremos testar passando o path e com a função send passamos o json que será enviado.

const resp = await supertest(server).post('/api').send({
    "id": 1,
    "name": "Kelly",
    "telephone": "118888888",
    "address": "Rua dos Bobos n 1"
});

Com o retorno do response conseguimos fazer as asserções dos testes, nesse caso queremos testar que a cada POST bem sucedido iremos retornar o status code 201 - Created e o body será devolvido então podemos fazer a asserção de algum campo do response.

expect(resp.statusCode).toEqual(201)
expect(resp.body.name).toEqual("Kelly")

Agora conseguimos rodar o comando a seguir para rodar esse teste:

jest --coverage

E teremos a seguinte resposta:

> jest --coverage --runInBand

 PASS  router/route.test.js
  Make requests to the server
    ✓ Should create a contact (65 ms)

  console.log
    A API está funcionando!

      at Server.<anonymous> (index.js:16:47)

----------------------|---------|----------|---------|---------|----------------------------------
File                  | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                
----------------------|---------|----------|---------|---------|----------------------------------
All files             |   48.68 |        0 |   29.17 |      50 |                                  
 phonebook            |     100 |      100 |     100 |     100 |                                  
  index.js            |     100 |      100 |     100 |     100 |                                  
 phonebook/model      |     100 |      100 |     100 |     100 |                                  
  index.js            |     100 |      100 |     100 |     100 |                                  
 phonebook/repository |      20 |      100 |   22.22 |      25 |                                  
  index.js            |      20 |      100 |   22.22 |      25 | 12-35                            
 phonebook/router     |   39.47 |        0 |   14.29 |   39.47 |                                  
  index.js            |   39.47 |        0 |   14.29 |   39.47 | 16-24,30-37,43-48,53-57,62,66-69 
 phonebook/service    |      50 |      100 |   33.33 |      50 |                                  
  index.js            |      50 |      100 |   33.33 |      50 | 14-26                            
----------------------|---------|----------|---------|---------|----------------------------------
Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.015 s
Ran all test suites.

Além do teste passamos o parâmetro --coverage e com isso é gerado um html com um relatório da cobertura dos testes.

Conclusão

Nesse artigo iniciamos a construção de uma API REST do zero usando NodeJS e Express. Vimos a facilidade de usar o Express e como o mecanismo de middleware torna o desenvolvimento flexível e dinâmico. Também conseguimos ver como deixar uma aplicação desacoplada utilizando o conceito de Injeção de dependências

Código fonte e recursos

Segue o GitHub do projeto e a Collection do Postman

Kafka Sink

Tue, 02 Mar 2021 00:00:01 GMT

Introdução

No último artigo foi mostrado como é possível a partir de uma fonte de dados externa, alimentar um tópico do Kafka através do Kafka Source. Agora será visto como podemos fazer a operação inversa onde as informações de um tópico alimentarão uma fonte de dados externa através do Kafka Sink, nesse exemplo será usado o banco de dados não relacional MongoDB.

Kafka Sink

Como foi visto no artigo passado o Kafka Source é uma ferramenta open source criado pela Apache, essa ferramenta facilita a comunicação em sistemas externos ao Kafka, com isso conseguimos trazer dados de fontes externas e o oposto também pode ocorrer graças ao Kafka Sink, que realiza essa operação de sink (escoar) para sistemas externos.

Data Mountaineer

O Data Mountaineer é uma empresa com foco em BigData e streaming de dados que se juntou com a Landoop e fornece o connector que se liga ao Kafka Connect e realiza a operação de Sink que nesse caso será com o MongoDB.

Projeto

O projeto consistirá na configuração de um connector que irá receber mensagens de um tópico do Kafka e irá salvar essas informações no MongoDB, também será criado um projeto Java que estará conectado ao banco de dados e irá expor via API REST os dados para consulta.

Focando na parte que será apresentada temos um desenho do fluxo:

Onde podemos ver de forma resumida o fluxo de dados que começa com o banco de dados MySQL, onde as alterações são capturadas pelo Debezium e através do Kafka Connect são enviadas ao broker do Kafka e também via Kafka Connect os dados são consumidos de um tópico e enviados ao Data Mountaineer e serão inseridos no MongoDB.

Adicionando o Mongo ao Docker Compose

É necessário adicionar o MongoDB ao docker-compose como abaixo:

  mongo:
    image: mongo
    container_name: mongo
    depends_on: 
    - kafka-cluster    
    ports:
      - 27017:27017
    networks: 
      - kafka-network

Acessando o MongoDB

Vamos acessar o MongoDB via terminal:

docker exec -it mongo mongo

E vamos acessar a collection taxpayer:

use taxpayer

Configurando Kafka Sink

Para configurar o Kafka Sink basta acessar novamente o dashboard, através da imagem landoop/kafka-lenses-dev e clicar em Connectors no lado esquerdo e depois no botão New Connector.

Será exibida a tela com os conectores disponíveis e entre eles o conector do MongoDB basta clicar nele que será aberta a tela para inserir as configurações.

Nessa tela iremos inserir as seguintes configurações:

connector.class=com.datamountaineer.streamreactor.connect.mongodb.sink.MongoSinkConnector
connect.mongo.kcql=UPSERT INTO taxpayer SELECT after FROM irs-conn.decider.complaint_taxpayer PK after.document;UPSERT INTO taxpayer SELECT after FROM irs-conn.decider.defaulted_taxpayer PK after.document
connect.mongo.connection=mongodb://mongo:27017
tasks.max=2
topics=irs-conn.decider.complaint_taxpayer,irs-conn.decider.defaulted_taxpayer
name=mongo
connect.mongo.db=taxpayer

Vamos bater ponto a ponto essa configuração:

name: Nome da conexão.
connector.class: É a classe que é carregada para fazer a conexão com o MongoDB.
connect.mongo.connection: URI de conexão com o banco de dados.
connect.mongo.db: Nome da collection no Mongo.
tasks.max: Máximo de tasks para essa conexão.
topics: Aqui deve ser informado quais são os tópicos que serão “escutados” pelo Kafka Connect para delegar ao Data Mountaineer
connect.mongo.kcql: KCQL é como diz documentação, SQL for Kafka Connect, não é algo incomum a própria Confluent possui algo similar que é o kSQL que nada mais é do que uma forma de simplificar a manipulação de dados e streams através de queries SQL. Como no nosso exemplo iremos capturar dados de dois tópicos precisamos criar duas queries para fazer UPSERT no MongoDB.

Após clicar em Create Connector a nova conexão deve ser listada como mostrado abaixo:

Monitorando o MongoDB

Agora podemos realizar alterações no MySQL e elas serão enviadas para os tópicos correspondentes e serão capturadas pelo Kafka Sink e enviadas ao MongoDB:

> db.taxpayer.find().pretty()
{
        "_id" : "890.955.180-19",
        "after" : {
                "document" : "890.955.180-19",
                "email" : "teste@teste.com",
                "name" : "Sandra Nair Sueli Ribeiro",
                "status" : "DEFAULTED"
        }
}
{
        "_id" : "869.097.474-10",
        "after" : {
                "document" : "869.097.474-10",
                "email" : "fake@fake.com.br",
                "name" : "Joao Alface",
                "status" : "COMPLAINT"
        }
}

Projeto Java

Para iniciar o projeto foi utilizado o Spring Initializr onde foi adicionado as dependências de Web, Lombok e Spring Data Mongo.

Iniciando pelo domínio dessa aplicação temos a Taxpayer:

@Data
@Builder
public class Taxpayer {

    private String document;
    private String email;
    private String name;
    private String status;

}

E nos casos de uso dessa aplicação queremos que seja possível buscar os Taxpayers pelo número de documento, email e listar todos. Para isso foi criado a classe SearchTaxpayer:

@Component
public class SearchTaxpayer {

    private final TaxpayerRepository taxpayerRepository;

    @Autowired
    public SearchTaxpayer(TaxpayerRepository taxpayerRepository){
        this.taxpayerRepository = taxpayerRepository;
    }

    public Taxpayer searchByEmail(String email){
        final Optional<Taxpayer> optionalTaxpayer = taxpayerRepository.findByEmail(email);

        if(!optionalTaxpayer.isPresent()){
            throw new TaxpayerNotFoundException("Taxpayer not found");
        }

        return optionalTaxpayer.get();
    }

    public Taxpayer searchByDocument(String document){
        final Optional<Taxpayer> optionalTaxpayer = taxpayerRepository.findByDocument(document);

        if(!optionalTaxpayer.isPresent()){
            throw new TaxpayerNotFoundException("Taxpayer not found");
        }

        return optionalTaxpayer.get();
    }

    public List<Taxpayer> findAll(){
        return taxpayerRepository.findAll().get();
    }
}

Para ela funcionar é necessário criar a classe TaxpayerRepository que nada mais é que a interface que servirá como port no conceito de ports and adapters:

public interface TaxpayerRepository {

    Optional<Taxpayer> findByEmail(String email);

    Optional<Taxpayer> findByDocument(String document);

    Optional<List<Taxpayer>> findAll();
}

E agora criamos o nosso Adapter para ele, mas primeiro faremos as configurações que o MongoDB necessita, primeiro criando a nossa entidade de banco de dados:

@Data
@Document(collection = "taxpayer")
public class TaxpayerEntity {

    @Id
    private String id;

    private After after;
}

@Data
public class After {

    private String document;
    private String email;
    private String name;
    private String status;

}

Como estamos usando Spring Data o trabalho é muito simplificado bastando criar uma interface que estenda de MongoRepository:

public interface MongoTaxpayerRepository extends MongoRepository<TaxpayerEntity, String> {

    Optional<TaxpayerEntity> findByAfter_Email(String email);

    Optional<TaxpayerEntity> findByAfter_Document(String document);
}

Agora criamos o Adapter implementando a TaxpayerRepository:

@Component
public class MongoTaxpayer implements TaxpayerRepository {

    private final MongoTaxpayerRepository mongoTaxpayerRepository;

    @Autowired
    public MongoTaxpayer(MongoTaxpayerRepository mongoTaxpayerRepository){
        this.mongoTaxpayerRepository = mongoTaxpayerRepository;
    }

    @Override
    public Optional<Taxpayer> findByEmail(String email) {

        final Optional<TaxpayerEntity> optionalTaxpayerEntity = mongoTaxpayerRepository.findByAfter_Email(email);

        if(!optionalTaxpayerEntity.isPresent()){
            return Optional.empty();
        }

        final After after = optionalTaxpayerEntity.get().getAfter();

        return Optional.of(Taxpayer.builder().name(after.getName()).document(after.getDocument()).email(after.getEmail()).status(after.getStatus()).build());
    }

    @Override
    public Optional<Taxpayer> findByDocument(String document) {

        final Optional<TaxpayerEntity> optionalTaxpayerEntity = mongoTaxpayerRepository.findByAfter_Document(document);

        if(!optionalTaxpayerEntity.isPresent()){
            return Optional.empty();
        }

        final After after = optionalTaxpayerEntity.get().getAfter();

        return Optional.of(Taxpayer.builder().name(after.getName()).document(after.getDocument()).email(after.getEmail()).status(after.getStatus()).build());
    }

    @Override
    public Optional<List<Taxpayer>> findAll() {

        final List<TaxpayerEntity> taxpayerEntityList = mongoTaxpayerRepository.findAll();

        if(null == taxpayerEntityList || taxpayerEntityList.isEmpty()){
            return Optional.empty();
        }

        final List<Taxpayer> taxpayerList = taxpayerEntityList.stream().map(taxpayerEntity -> {
            final After after = taxpayerEntity.getAfter();

            return Taxpayer.builder().name(after.getName()).document(after.getDocument()).email(after.getEmail()).status(after.getStatus()).build();
        }).collect(Collectors.toList());

        return Optional.of(taxpayerList);
    }
}

Com o adaptador criado vamos criar o controller que irá receber as requisições REST e delegar para a classe SearchTaxpayer:

@RestController
@RequestMapping("/taxpayer")
public class TaxpayerController {

    @Autowired
    private SearchTaxpayer searchTaxpayer;

    @GetMapping
    public ResponseEntity<List<Taxpayer>> getAllTaxpayers(){
        return ResponseEntity.ok(searchTaxpayer.findAll());
    }

    @GetMapping("document")
    public ResponseEntity<Taxpayer> getTaxpayerByDocument(@RequestParam("document") String document){
        return ResponseEntity.ok(searchTaxpayer.searchByDocument(document));
    }

    @GetMapping("email")
    public ResponseEntity<Taxpayer> getTaxpayerByEmail(@RequestParam("email") String email){
        return ResponseEntity.ok(searchTaxpayer.searchByEmail(email));
    }

}

Após subir a aplicação e fazendo uma requisição para url localhost:8080/taxpayer/ teremos como resultado:

[
    {
        "document": "890.955.180-19",
        "email": "teste@teste.com",
        "name": "Sandra Nair Sueli Ribeiro",
        "status": "DEFAULTED"
    },
    {
        "document": "1234567890",
        "email": "fake@fake.com.br",
        "name": "Joao Alface",
        "status": "COMPLAINT"
    }
]

Conclusão

Aqui vimos a outra ponta do Kafka Connect, o Kafka Sink e foi apresentado um exemplo prático de como podemos ter bases ou até mesmo aplicações que podem receber dados através de streams com as ferramentas que o Kafka disponibiliza.

Código fonte

O código do projeto está no GitHub

Kafka Connector

Tue, 23 Feb 2021 00:00:01 GMT

Introdução

Continuando a sequência de artigos sobre Kafka agora vamos entender o que é o Kafka Connect e iremos criar um listener que capturará mudanças no banco de dados e irá enviar para um tópico no Kafka.

Kafka Connect

O Kafka Connect é uma ferramenta open source criada pela Apache para poder se conectar com sistemas externos e lidar com volumes altíssimos de dados, podendo assim tanto receber quanto enviar dados para essas fontes. No artigo abaixo iremos explorar o Kafka Connect Source API que faz a parte de ingestão de dados mas também há o Kafka Connect Sink API que é o responsável por enviar dados de tópicos do Kafka para sistemas externos.

Debezium

O Debezium é um CDC, abreviação para Change Data Capture, isso significa que ele é uma peça que fica conectada ao Kafka Connect e tem a responsabilidade de capturar alterações no banco de dados. Ele possui vários conectores para bancos de dados como SQL Server, Oracle, PostgreSQL, MongoDB e etc. nesse artigo será usado o connector para MySQL.

Projeto

Para começar vamos analisar o esboço arquitetural abaixo e entender o que está sendo proposto:

Em comparação com os desenhos dos artigos anteriores o ponto que mudou foi na aplicação Decider que possui um banco de dados MySQL e nele está conectado o Debezium e este está conectado ao Kafka Connect que por sua vez está conectado ao broker do Kafka.

Primeiramente olhando para o desenho do banco de dados conseguimos ver que existe o Binlog se conectando ao Debezium, isso por que o Debezium se conecta ao Binlog e através dele consegue ficar “escutando” todas as transações que ocorrem no banco.

Mas o que é esse Binlog?

O Binlog é a abreviação para Binary Logs que é a forma como os bancos de dados tem para guardar os eventos que ocorreram neles, ele guarda muitas métricas como por exemplo quanto tempo uma query demorou para ser executada, quais dados foram criados, alterados, deletados e etc.

Após receber a informação do Binlog o Debezium delega ao Kafka Connect que é quem realmente se conecta ao broker do Kafka e cria ou insere em um tópico já existente.

Configurando o ambiente

Nos artigos anteriores estava usando a imagem landdop/fast-data-dev pois ela já fornecia todo o ambiente do Kafka pronto para o desenvolvimento porém durante os testes com o Kafka Connect ela estava apresentando problemas com os conectores do Debezium e após pesquisar soluções e alternativas encontrei uma nova imagem landoop/kafka-lenses-dev, porém para executar essa imagem é necessário criar uma licença na Lenses.

Após receber a licença basta adicionar como variável de ambiente e acessar localhost:3030 com usuário e senha admin.

Como estou usando Docker Compose o .yml fica assim:

version: '3'

services:
  
  mysql:
    image: mysql:8.0.17
    cap_add: 
      - SYS_NICE
    environment: 
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: user
      MYSQL_PASSWORD: user
      MYSQL_DATABASE: register
    networks: 
      - kafka-network
    ports: 
      - "3306:3306"
    volumes: 
      - ./data/decider.sql:/docker-entrypoint-initdb.d/decider.sql

  kafka-cluster:
    image: landoop/kafka-lenses-dev
    environment:
      EULA: "https://licenses.lenses.io/download/lensesdl?id=idLicenseLenses" 
      CONNECT_HEAP: 3G
      ADV_HOST: 127.0.0.1
      SAMPLEDATA: 0
      RUNTESTS: 0
    networks: 
      - kafka-network
    ports:
      - "2181:2181"                 # Zookeeper
      - "3030:3030"                 # Landoop UI
      - "8081-8083:8081-8083"       # REST Proxy, Schema Registry, Kafka Connect ports
      - "9581-9585:9581-9585"       # JMX Ports
      - "9092:9092"                 # Kafka Broker
    depends_on: 
      - mysql

networks:
  kafka-network: 
    driver: bridge

Configurando Debezium

Vamos iniciar a configuração do Debezium no Kafka Connect.

Quando acessar o dashboard na guia lateral clique em Connectors:

Após isso clique em New Connector:

No dashboard irá aparecer todos os conectores disponíveis (existem dois CDC MySQL mas é por que um é o CDC SQL Server que está com o nome errado):

Irá aparecer o campo text area para inserir as configurações e a aqui vale passar ponto a ponto as configurações:

name=IRS-Connector
connector.class=io.debezium.connector.mysql.MySqlConnector
database.hostname=mysql
database.port=3306
database.user=user
database.password=user
database.allowPublicKeyRetrieval=true
database.server.name=irs-conn-v1
database.include.list=decider
database.exclude.list=register
database.blacklist=register
database.history.kafka.bootstrap.servers=localhost:9092
database.history.kafka.topic=schema-changes.decider
table.exclude.list=decider.flyway_schema_history,register.flyway_schema_history
table.blacklist=decider.flyway_schema_history,register.flyway_schema_history

O campo name é obrigatório e define o nome do conector.
O campo connector.class é obrigatório e é a definição de qual classe que será carregada para esse conector.
Os campos database.hostname, database.port, database.user e database.password são obrigatórios e são os dados de conexão do banco de dados.
O campo database.allowPublicKeyRetrieval é opcional e eu adicionei para permitir o client executar o request da public key.
O campo database.server.name é obrigatório, pode ser qualquer nome mas será usado como prefixo para os tópicos que serão criados no Kafka.
O campo database.include.list é opcional e serve para informar qual database deve ficar escutando as alterações, como nesse exemplo temos dois databases adicionei qual queria.
O campo database.exclude.listé opcional e é o oposto do campo acima e eu adicionei o database que eu não quero ficar observando as alterações.
O campo database.blacklist está depreciado pelo campo database.exclude.list segundo a documentação do Debezium, mas não sei se por questão de versão ou bug o campo database.exclude.list não estava funcionando; mas ele é exatamente a mesma ideia de excluir um database específico.
O campo database.history.kafka.bootstrap.servers é obrigatório e basicamente é o host/port do cluster do Kafka.
O campo database.history.kafka.topic é obrigatório e serve para nomear o tópico no Kafka onde o conector guarda o histórico de schemas do database.
O campo table.exclude.list é opcional e indica uma tabela que não deve ter as suas alterações observadas, deve estar no formato nome do database + nome da tabela, nesse caso como o projeto utiliza Flyway para gerenciamento das versões do banco de dados eu o adicionei.
O campo table.blacklist também está depreciado porém como ocorreu com o campo database.exclude.list não estava funcionando.

Após adicionar as configurações basta clicar em Create Connector:

Obs: Esse comando também pode ser feito via cURL pois ele é executado via Kafka REST e ficaria dessa foram:

cat << EOF > IRS-Connector.json
{
  "name": "IRS-Connector",
  "config": {
    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
    "database.hostname": "mysql",
    "database.port": "3306",
    "database.user": "user",
    "database.password": "user",
    "database.allowPublicKeyRetrieval": "true",
    "database.server.name": "irs-conn-v1",
    "database.include.list": "decider",
    "database.exclude.list": "register",
    "database.blacklist": "register",
    "database.history.kafka.bootstrap.servers": "localhost:9092",
    "database.history.kafka.topic": "schema-changes.decider",
    "table.exclude.list": "decider.flyway_schema_history,register.flyway_schema_history",
    "table.blacklist": "decider.flyway_schema_history,register.flyway_schema_history"
  }
}
EOF
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d @IRS-Connector.json http://localhost:3030/api/proxy-connect/dev/connectors

Se tudo estiver certo deverá aparecer a tela de status com o conector rodando:

Se clicarmos em Explore na guia lateral iremos ver que foram criados os tópicos e também foi criado os schemas no Schema Registry:

Capturando mudanças no banco de dados

Após todas essas configurações o conector está pronto e o Debezium já está escutando as alterações, sendo assim se fizermos um INSERT no banco Decider ele irá capturar esse evento através do Binlog e irá adicionar ao tópico do Kafka como na imagem abaixo:

Aqui conseguimos ver alguns detalhes, primeiro a key passa a ser o id da tabela no banco de dados e segundo que o nosso value trás algumas informações mas o que chama mais a atenção é que ele consegue trazer o valor anterior e o valor atual que foi alterado, nesse exemplo como é um INSERT o campo before é nulo.

Agora se atualizarmos o valor dessa linha na tabela:

Isso gerará uma mensagem no tópico do Kafka onde no campo value poderá ser visto o valor do campo before com os dados antes da atualização e no campo after o valor atual daquela linha nesta tabela.

Com isso agora temos o conector em pleno funcionamento capturando qualquer alteração realizada nas tabelas que configuramos para monitorar.

Conclusão

No artigo foi apresentado como podemos usar um conector para “pegar” os dados em um banco de dados ou qualquer sistema externo e trazer para um tópico no Kafka; o oposto também pode ser feito que é capturar dados em um tópico e inserir em um sistema externo, essa é a responsabilidade do Connector Sink API e aqui deixo o link para um exemplo onde é usado o Connector Sink API para inserir dados em um banco de dados PostgreSQL.

Código fonte

Segue o código feito no GitHub

Testes no Kafka com JUnit

Thu, 11 Feb 2021 00:00:01 GMT

Introdução

Nos artigos anteriores vimos como criar um Produtor e um Consumidor utilizando Kafka, agora vamos entender como podemos criar testes usando JUnit utilizando uma abordagem mais simplificada onde através do conceito de Ports and Adapters conseguimos injetar as dependências sem a necessidade de usar outras libs para “mockar” as classes.

Criar testes para as aplicações nem sempre é algo trivial, principalmente em cenários onde há injeção de dependências, pensando nisso existem libs para lidar com isso, as mais utilizadas são Mockito e PowerMock porém mesmo usando essas libs as vezes nos encontramos com problemas de injeção de dependências ou dependências cíclicas que atrapalham em muito a criação e a manutenção de testes.

Uma abordagem que simplificaria esses cenários seria a utilização de Ports and Adapters onde através de interfaces conseguimos criar os Adaptadores para as classes que são utilizadas na aplicação e também ganhamos flexibilidade para implementar os nossos Adaptadores que serão usados nos testes, ganhando assim desacoplamento e coesão.

Também iremos utilizar a API de Mocks que o próprio Kafka fornece para fazer o mock de um cluster.

Testando o Producer

No projeto Producer será utilizado a classe MockProducer para simular o cluster Kafka que irá enviar a mensagem. Para começar iremos criar a classe de teste TaxpayerServiceTest.

Para que possamos criar e manipular a injeção de dependência no teste é necessário alguns ajustes na classe TaxpayerService, primeiro será removido a anotação @Autowired do atributo private Producer<String, TaxPayer> producer; e passaremos para o construtor:

private final Producer<String, TaxPayer> producer;

@Autowired
public TaxpayerService(@Qualifier("taxpayerProducer") Producer<String, TaxPayer> producer) {
    this.producer = producer;
}

Essa alteração já basta para o nosso teste.

Agora na classe de teste vamos nos concentrar em como usar a classe MockProducer:

final MockProducer<String, TaxPayer> mockProducer = new MockProducer(true, new StringSerializer(), new KafkaAvroSerializer());

Com essa configuração já temos em mãos uma instância de um Producer que a classe TaxpayerService necessita.

Agora conseguimos chamar o método send da nossa classe de serviço passando o objeto TaxpayerDTO.

public class TaxpayerServiceTest {

    private TaxpayerService taxpayerService;

    private MockProducer<String, TaxPayer> mockProducer;

    @Test
    void sendMessage(){

        final MockProducer<String, TaxPayer> mockProducer = new MockProducer(true, new StringSerializer(), new KafkaAvroSerializer());

        taxpayerService = new TaxpayerService(mockProducer);

        final TaxpayerDTO taxpayerDTO = new TaxpayerDTO();
        taxpayerDTO.setDocument("12345678901");
        taxpayerDTO.setEmail("fake@email.com");
        taxpayerDTO.setName("John Doe");

        taxpayerService.send(taxpayerDTO);

    }

}

O teste passa com sucesso e temos a saída no console:

14:20:24.700 [main] INFO com.irs.sender.business.consumer.KafkaConsumerService - Recebendo TaxPayer
Mandando mensagem para pessoa :: Person(name=Guilherme, email=meuemail@email.com)

Testando o Consumer

Para realizar o teste no projeto Consumer será necessários algumas modificações mais profundas.

A princípio nesse projeto havia um loop while(true) para ficar sempre processando as mensagens que estavam sendo recebidas porém essa abordagem é pouco problemática pois o processamento ficará sempre atrelado à thread main, um ponto levantado pelo Pedro Alves. Para resolver isso há várias abordagens mas como estamos usando um projeto Spring Boot podemos criar uma tarefa agendada e com isso teremos uma thread em paralelo sendo executada periodicamente.

Para isso é necessário criar a configuração de um ThreadPoolTaskSchedulerConfig:

@Configuration
@ComponentScan(basePackages = "com.irs.sender.business.consumer", basePackageClasses = KafkaConsumerService.class)
public class ThreadPoolTaskSchedulerConfig {

    @Bean
    public ThreadPoolTaskScheduler threadPoolTaskScheduler() {
        ThreadPoolTaskScheduler threadPoolTaskScheduler = new ThreadPoolTaskScheduler();
        threadPoolTaskScheduler.setPoolSize(1);
        threadPoolTaskScheduler.setThreadNamePrefix("KafkaScheduleService");
        return threadPoolTaskScheduler;
    }
}

Na classe KafkaConsumerService vamos alterar a injeção de dependência de atributo para construtor e adicionaremos a classe ThreadPoolTaskScheduler:

private final Consumer<String, TaxPayer> kafkaConsumer;

private final Email email;

private final ThreadPoolTaskScheduler taskScheduler;

@Autowired
public KafkaConsumerService(@Qualifier("taxpayerConsumer") Consumer<String, TaxPayer> kafkaConsumer, Email email, ThreadPoolTaskScheduler taskScheduler) {
    this.kafkaConsumer = kafkaConsumer;
    this.email = email;
    this.taskScheduler = taskScheduler;
}

E removeremos a anotação @PostConstruct e o laço while(true) do método receive que ficará assim:

@Override
public void receive() {

    Consumer<String, TaxPayer> consumer = kafkaConsumer;

    consumer.subscribe(Collections.singleton(this.topic()));

    try {

        consumer.poll(Duration.ofMillis(1000)).forEach(record -> {

            log.info("Recebendo TaxPayer");

            TaxPayer taxpayer = record.value();

            Person person = Person.builder().email(taxpayer.getEmail()).name(taxpayer.getName()).build();

            email.sendMessage(person);

        });

        consumer.commitSync();

    } catch (Exception ex) {
        log.error("Erro ao processar mensagem", ex);
    }

}

E agora para que a tarefa seja agendada e rode do mesmo jeito como era executava antes em que estava sempre buscando as mensagens no Kafka iremos criar o método init com o Schedule e um CronTrigger indicando de quanto em quanto irá rodar:

@PostConstruct
public void init() {
    taskScheduler.schedule(() -> {
        this.receive();
    }, new CronTrigger("* * * * * *"));
}

Após isso foi criada a classe de teste KafkaConsumerServiceTest e nela iremos configurar a classe MockConsumer que irá simular o cluster Kafka que irá receber a mensagem.

MockConsumer<String, TaxPayer> consumer = new MockConsumer<>(OffsetResetStrategy.EARLIEST);

consumer.schedulePollTask(() -> {
    consumer.rebalance(Collections.singletonList(new TopicPartition("taxpayer-avro", 0)));
    consumer.addRecord(new ConsumerRecord<String, TaxPayer>("taxpayer-avro", 0, 0l, "key", new TaxPayer("Guilherme", "11122233344", "meuemail@email.com", true)));
});

HashMap<TopicPartition, Long> beginningOffsets = new HashMap<>();
beginningOffsets.put(new TopicPartition(TOPIC, 0), 0l);
consumer.updateBeginningOffsets(beginningOffsets);

consumer.subscribe(Collections.singleton("taxpayer-avro"));

Basicamente essa configuração é para simular um cluster Kafka, criar um Tópico, adicionar uma mensagem e subscrever no tópico.

Fora isso a nossa classe de serviço possui em sua regra o envio de emails e podemos simular o envio de email bastando fazer um adaptador para a nossa interface Email:

private Email email;

void prepareEmailMock() {
		email = person -> System.out.println("Mandando email teste :: " + person);
	}

E com isso podemos criar o nosso teste:

@Test
void testConsumer(){
    service.receive();
}

Executando o teste termos como saída no console:

20:29:45.000 [main] INFO com.irs.sender.business.consumer.KafkaConsumerService - Recebendo TaxPayer
Mandando email teste :: Person(name=Guilherme, email=meuemail@email.com)

O teste completo:

public class KafkaConsumerServiceTest {
	
	private MockConsumer<String, TaxPayer> consumer;
	
	private KafkaConsumerService service;
	
	private Email email;

	private ThreadPoolTaskScheduler taskScheduler = new ThreadPoolTaskScheduler();
	
	private static final String TOPIC = "taxpayer-avro";

	@BeforeEach
	void prepareConsumer() {

		consumer = new MockConsumer<>(OffsetResetStrategy.EARLIEST);
		this.prepareEmailMock();
		
		consumer.schedulePollTask(() -> {
			consumer.rebalance(Collections.singletonList(new TopicPartition(TOPIC, 0)));
			consumer.addRecord(new ConsumerRecord<String, TaxPayer>(TOPIC, 0, 0l, "key", this.prepareTaxpayerMock()));
		});
		
		HashMap<TopicPartition, Long> beginningOffsets = new HashMap<>();
		beginningOffsets.put(new TopicPartition(TOPIC, 0), 0l);
		consumer.updateBeginningOffsets(beginningOffsets);
		
		consumer.subscribe(Collections.singleton(TOPIC));
		service = new KafkaConsumerService(consumer, email, taskScheduler);
		
	}
	
	void prepareEmailMock() {
		email = person -> System.out.println("Mandando email teste :: " + person);
	}
	
	
	TaxPayer prepareTaxpayerMock() {
		return new TaxPayer("Guilherme", "11122233344", "meuemail@email.com", true);
	}

	@Test
	void testConsumer(){
		service.receive();
	}

}

Conclusão

Aqui foi mostrado uma maneira de como podemos escrever alguns testes para os nossos consumidores e produtores de mensagens com Kafka. Também vimos que foi necessária algumas alterações no projeto para deixar mais fácil a escrita de testes e isso deve ser um ponto positivo na evolução de qualquer aplicação. O intuito desse artigo não é dizer que não é mais necessário usar frameworks para testes como Mockito mas sim mostrar que em muitos casos o uso indiscriminado deles acaba por deixar o projeto extremamente acoplado e dependente pois na maioria das vezes não é pensado em como fazer uma boa injeção de independência.

Código fonte

O projeto está no GitHub

Kafka Streams com Java

Tue, 02 Feb 2021 00:00:01 GMT

Introdução

Na documentação do Kafka Streams temos a seguinte descrição: “Kafka Streams é uma biblioteca cliente para construir aplicações e microserviços onde a entrada e saída de dados são armazenados nos clusters do Kafka. Ele combina a simplicidade de escrever e subir aplicações Java e Scala no lado do cliente com os benefícios da tecnologia de clusters do lado do servidor do Kafka”

Isso significa que o Kafka Streams é uma ferramenta para processamento de fluxo de dados (streams) em tempo real que é integrada ao ambiente do Kafka. Possibilitando o processamento, transformação e persistência de dados em novos tópicos.

Nesse artigo será mostrado um exemplo onde uma aplicação conectada ao Kafka utiliza a biblioteca do Kafka Streams para executar o processamento dos dados.

O Projeto

Anteriormente em artigos passados foi mostrado como produzir mensagens com Kafka e como consumir mensagens com Kafka e agora vamos continuar com esse modelo onde o produtor irá enviar esses dados e tanto o consumidor simples quanto o nosso consumidor com Streams irá processar e para esse exemplo não iremos persistir em um novo tópico iremos apenas chamar um Processor que irá persistir em um banco de dados. A visão geral de como os projetos se comunicam com o Kafka seria algo assim:

Iniciando o projeto

O projeto foi criado no site Spring Initializr como um projeto Maven e para usarmos o Kafka Streams precisamos adicionar as dependências do Apache e também foi adicionado as dependências da Confluent para poder ser usado o suporte que existe para Schema Registry como Serialização e Deserialização (SerDe):

<!-- https://mvnrepository.com/artifact/org.apache.avro/avro -->
<dependency>
    <groupId>org.apache.avro</groupId>
    <artifactId>avro</artifactId>
    <version>1.10.1</version>
</dependency`

<!-- https://mvnrepository.com/artifact/org.apache.kafka/kafka-streams -->
<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-streams</artifactId>
</dependency>

<!--dependencies needed for the kafka part -->
<!-- https://mvnrepository.com/artifact/org.apache.kafka/kafka-clients -->
<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
</dependency>

<!-- https://mvnrepository.com/artifact/io.confluent/kafka-avro-serializer -->
<dependency>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-avro-serializer</artifactId>
    <version>5.3.0</version>
</dependency>

<dependency>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-streams-avro-serde</artifactId>
    <version>5.3.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
        </exclusion>
    </exclusions>
</dependency>

E também é necessário adicionar a tag que indica de onde deve ser baixado as dependências da Confluent:

<repositories>
    <repository>
        <id>confluent</id>
        <url>https://packages.confluent.io/maven/</url>
    </repository>
</repositories>

Configurando Kafka Properties

O Kafka é todo baseado em configurações que passamos via Properties como no exemplo:

@Configuration
public class KafkaConfiguration implements MessageConfiguration {

	@Autowired
	private KafkaProperties kafkaProperties;

	@Override
	public Properties configureProperties() {

		Properties properties = new Properties();

		properties.put(APPLICATION_ID_CONFIG, kafkaProperties.getApplicationId());
		properties.put(GROUP_ID_CONFIG, kafkaProperties.getGroupId());
		properties.put(BOOTSTRAP_SERVERS_CONFIG, kafkaProperties.getBootstrapServers());
		properties.put(CLIENT_ID_CONFIG, kafkaProperties.getClientId());

		properties.put(PROCESSING_GUARANTEE_CONFIG, kafkaProperties.getProcessingGuaranteeConfig());
		properties.put(AUTO_OFFSET_RESET_CONFIG, kafkaProperties.getOffsetReset());
		properties.put(DEFAULT_TIMESTAMP_EXTRACTOR_CLASS_CONFIG, kafkaProperties.getTimeStampExtarctor());

		properties.put(SCHEMA_REGISTRY_URL_CONFIG, kafkaProperties.getSchemaRegistryUrl());
		properties.put(DEFAULT_KEY_SERDE_CLASS_CONFIG, kafkaProperties.getDefaultKeySerde());
		properties.put(DEFAULT_VALUE_SERDE_CLASS_CONFIG, kafkaProperties.getDefaultValueSerde());
		properties.put(SPECIFIC_AVRO_READER_CONFIG, kafkaProperties.isSpecficAvroReader());

		return properties;
	}

}

Das configurações acima vale ressaltar as seguintes:

APPLICATION_ID_CONFIG: Um identificador único do processo no cluster do Kafka.
GROUP_ID_CONFIG: O identificador do grupo de consumidores.
BOOTSTRAP_SERVERS_CONFIG: Pode ser uma lista de url’s de conexão com o cluster do Kafka.
SCHEMA_REGISTRY_URL_CONFIG: Url de conexão do Schema Registry.
DEFAULT_KEY_SERDE_CLASS_CONFIG: Definição do Serializador/Deserializador padrão para as chaves das mensagens.
DEFAULT_VALUE_SERDE_CLASS_CONFIG: Definição do Serializador/Deserializador padrão para as mensagens.
SPECIFIC_AVRO_READER_CONFIG: Indica que será usado uma classe específica para ler a mensagem Avro

Configurando o processamento

Quando recebermos os nossos dados de Taxpayer há uma informação sobre a situation do contribuinte. Podemos usar isso e definir um processador específico para cada situação do contribuinte; caso seja true será processado pela classe TaxpayerProcessorSituationTrue e caso seja false pela TaxpayerProcessorSituationFalse. Para esse exemplo vamos processar cada contribuinte, de acordo com a sua situation e salvar em um banco de dados para cada tipo de situação do contribuinte.

A API do Kafka Streams fornece uma interface chamada Processor para implementarmos um processador de dados e ainda temos uma abstração chamada AbstractProcessor que facilita ainda mais esse trabalho, então as classes ficam dessa forma para situation igual a true:

@Component
@Slf4j
public class TaxpayerProcessorSituationTrue extends AbstractProcessor<String, TaxPayer>{
	
	@Autowired
	private TaxpayerPort repository;

	@Override
	public void process(String key, TaxPayer value) {
		log.info("Processing Taxpayer with situation :: " + value.getSituation());
		ComplaintTaxpayer complaintTaxpayer = ComplaintTaxpayer.createDefaultedTaxpayer(value);
		repository.save(complaintTaxpayer);
		
	}

}

E para situation igual a false:

@Component
@Slf4j
public class TaxpayerProcessorSituationFalse extends AbstractProcessor<String, TaxPayer> {

	@Autowired
	private TaxpayerPort repository;

	@Override
	public void process(String key, TaxPayer value) {
		log.info("Processing Taxpayer with situation :: " + value.getSituation());
		DefaultedTaxpayer defaultedTaxpayer = DefaultedTaxpayer.createDefaultedTaxpayer(value);
		repository.save(defaultedTaxpayer);

	}

}

Configurando o Stream

Para configurar a Stream é necessário ser passado as Properties do cluster do Kafka, o nome do tópico e a configuração de SerDe:

StreamsBuilder streamsBuilder = new StreamsBuilder();

Serde<TaxPayer> taxpayerAvroSerde = new SpecificAvroSerde<>();

taxpayerAvroSerde.configure(getSerdeProperties(), false);

KStream<String, TaxPayer> stream = streamsBuilder.stream(getTopic(), Consumed.with(Serdes.String(), taxpayerAvroSerde));

Nesse trecho de código podemos ver que o Kafka possui um Builder para as nossas Streams, ela recebe o tópico e a combinação chave/valor da mensagem que será recebida. Como estamos trabalhando com Schema Registry definimos que o valor dessa mensagem será um Serde.

Com o objeto KStream<String, TaxPayer> podemos fazer várias manipulações dos dados que irão chegar aqui para podermos filtrá-los e encaminhar para o Processor certo vamos usar o método branch que nos devolverá o um Array:

KStream<String, TaxPayer>[] branch = stream.branch(
				(id, tax) -> tax.getSituation() == false,
				(id, tax) -> tax.getSituation() == true
				);

No código acima usamos o método branch para fazer o nosso filtro por situation e podemos delegar para os Processors:

branch[0].process(() -> processorFalse);
branch[1].process(() -> processorTrue);

O exemplo completo dessa configuração:

@Autowired
private TaxpayerProcessorSituationTrue processorTrue;

@Autowired
private TaxpayerProcessorSituationFalse processorFalse;

private KafkaStreams kafkaStreams;

@Override
public String getTopic() {
    return "taxpayer-avro";
}

@SuppressWarnings("unchecked")
@Override
public StreamsBuilder creataStream() {
    
    StreamsBuilder streamsBuilder = new StreamsBuilder();
    
    Serde<TaxPayer> taxpayerAvroSerde = new SpecificAvroSerde<>();
    
    taxpayerAvroSerde.configure(getSerdeProperties(), false);
    
    KStream<String, TaxPayer> stream = streamsBuilder.stream(getTopic(), Consumed.with(Serdes.String(), taxpayerAvroSerde));
    
    KStream<String, TaxPayer>[] branch = stream.branch(
            (id, tax) -> tax.getSituation() == false,
            (id, tax) -> tax.getSituation() == true
            );
    
    branch[0].process(() -> processorFalse);
    branch[1].process(() -> processorTrue);
    
    return streamsBuilder;
}

private Map<String, String> getSerdeProperties() {
    return Collections.singletonMap(SCHEMA_REGISTRY_URL_CONFIG, (String)kakfaConfiguration.configureProperties().get(SCHEMA_REGISTRY_URL_CONFIG));
}

Configurando o start

Com o Stream configurado é necessário fazer o start, onde será passado o Stream, as configurações do cluster Kafka, um handler de Exceptions e um hook para podermos lidar o shutdown da aplicação.

@PostConstruct
@Override
public void start() {
    
    StreamsBuilder streamsBuilder = this.creataStream();
    
    kafkaStreams = new KafkaStreams(streamsBuilder.build(), kakfaConfiguration.configureProperties());
    kafkaStreams.setUncaughtExceptionHandler(this.getUncaughtExceptionHandler());
    kafkaStreams.start();
    
    this.shutDown();
}

@Override
public void shutDown() {
    Runtime.getRuntime().addShutdownHook(new Thread(kafkaStreams::close));
}

private UncaughtExceptionHandler getUncaughtExceptionHandler() {
    return (thread, exception) -> exception.printStackTrace();
}

Produzindo em um novo tópico

Um ponto muito utilizado quando se trabalha com Streams é o processamento, transformação e produção de novos fluxos de dados, então podemos simular o recebimento de uma mensagem de Taxpayer e transformamos o name pra lower case e enviamos para um novo tópico chamado name-lower-case-topic:

KStream<String, String> nameLowerCase = stream.mapValues(taxpayer -> taxpayer.getName().toLowerCase());
nameLowerCase.to("name-lower-case-topic");

Conclusão

Aqui foi mostrado uma forma de usar Kafka Streams porém essa biblioteca é muito extensa e tem muitos recursos, para mais informações consultar as documentações do Apache Kafka Streams e da Confluent Kafka Streams

Código fonte

O código fonte desse projeto pode ser encontrado no GitHub

Validando requisições com Spring Boot

Tue, 26 Jan 2021 00:00:01 GMT

Erros ocorrem e sempre irão ocorrer, seja por mal requisito de negócio, seja por mal desenvolvimento ou qualquer outra razão. O fato é que erros acontecem e precisamos saber lidar com eles.

Mas como vamos apresentar o erro para o usuário ou cliente que chamam as nossas APIs?

O Spring já fornece todo um mecanismo para tratativa de erros que é muito válido e auxilia, e muito, o desenvolvimento mas aqui eu irei apresentar uma outra forma de realizar essa tratativa através de uma lib que descobri recentemente que facilita ainda mais o trabalho e padronização de erros e mensagens na resposta.

Projeto

Seguindo com os conteúdos dos artigos anteriores vamos reaproveitar o projeto que já foi usado pra Criar um endpoint com Spring Security e token JWT e vamos adicionar nele a validação.

Este projeto também está sendo usado nos artigos sobre o Kafka aqui do blog e nessa aplicação temos como premissa que seja enviado os dados de um contribuinte como nome, documento e email.

No nosso projeto hoje não há validação alguma se os dados enviados estão corretos, para esse exemplo queremos que o número do documento (CPF), seja um número válido e caso não seja deve retornar uma mensagem indicando isso.

Para isso iremos usar uma lib muito interessante que ajuda muito no desenvolvimento com Spring Boot, a Errors Spring Boot Starter é um projeto que visa facilitar ainda mais a manipulação de erros e validação de dados de entrada.

Adicionado ao Maven

O projeto register é um projeto Java que utiliza o Maven então basta adicionar a dependência no pom.xml:

<dependency>
    <groupId>me.alidg</groupId>
    <artifactId>errors-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>

E para auxiliar nas validações também incluir a dependência do spring-boot-starter-validation:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Criando annotation para validação

O nosso objeto de entrada no POST contém um campo documento que será onde usuário irá enviar o CPF:

{
    "name": "User",
    "document": "XXX.XXX.XXX-XX",
    "email": "email@fake.com"
}

E a ideia seria que no momento do POST fosse realizada a validação e caso não seja um CPF válido retorna um erro informando isso.

Para isso será criado uma Annotation @Cpf que nos auxiliará:

@Documented
@Constraint(validatedBy = CpfValidator.class)
@Target( { ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface Cpf {
	
    String message() default "Documento Inválido";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

}

Na annotation @Cpf é definida a mensagem que será devolvida para o usuário e também adicionamos @Constraint(validatedBy = CpfValidator.class) que é classe que contém a lógica para executar a validação.

É necessário criar a classe CpfValidator que contém a regra de validação:

public class CpfValidator implements ConstraintValidator<Cpf, String>{
	
	private final int[] PESO_CPF = { 11, 10, 9, 8, 7, 6, 5, 4, 3, 2 };

	@Override
	public boolean isValid(String cpf, ConstraintValidatorContext context) {
		
		String cpfSomenteDigitos = cpf.replaceAll("\\D", "");
		
		if ((cpfSomenteDigitos == null) || (cpfSomenteDigitos.length() != 11) || cpfSomenteDigitos.equals("00000000000")
				|| cpfSomenteDigitos.equals("11111111111") || cpfSomenteDigitos.equals("22222222222")
				|| cpfSomenteDigitos.equals("33333333333") || cpfSomenteDigitos.equals("44444444444")
				|| cpfSomenteDigitos.equals("55555555555") || cpfSomenteDigitos.equals("66666666666")
				|| cpfSomenteDigitos.equals("77777777777") || cpfSomenteDigitos.equals("88888888888")
				|| cpfSomenteDigitos.equals("99999999999")) {
			return false;
		}
		
		Integer digito1 = calcularDigito(cpfSomenteDigitos.substring(0, 9), PESO_CPF);
		Integer digito2 = calcularDigito(cpfSomenteDigitos.substring(0, 9) + digito1, PESO_CPF);

		return cpfSomenteDigitos.equals(cpfSomenteDigitos.substring(0, 9) + digito1.toString() + digito2.toString());
	}
	
	private int calcularDigito(String str, int[] peso) {
		int soma = 0;
		for (int indice = str.length() - 1, digito; indice >= 0; indice--) {
			digito = Integer.parseInt(str.substring(indice, indice + 1));
			soma += digito * peso[peso.length - str.length() + indice];
		}
		soma = 11 - soma % 11;
		return soma > 9 ? 0 : soma;
	}

}

A primeira coisa a se notar nessa classe é que ela implementa a interface do javax.validation ConstraintValidator<A extends Annotation, T> que recebe uma Annotation como parâmetro.

E aqui executamos o algoritmo para validarmos se um CPF é válido ou não.

Para que a validação tenha efeito é necessário adicionar no Controller que recebe o nosso objeto a anotação @Valid para que surja efeito.

public ResponseEntity<TaxpayerDTO> postTaxpayer(@Valid @RequestBody TaxpayerDTO taxpayer)

Com isso nós podemos adicionar essa Annotation ao atributo document no DTO TaxpayerDTO.

@Cpf
private String document;

Se tentarmos agora fazer um POST com um número que não seja um CPF válido será lançado o erro com status 400.

{
    "errors": [
        {
            "code": "Documento invalido",
            "message": null
        }
    ]
}

Já retorna uma mensagem de erro mais padronizada porém um tanto quanto estranha já que a message está com valor null e no campo code está com a mensagem que definimos na Annotation CPF.

Isso ocorre pois a nossa dependência de validação usa o mecanismo do Spring MessageSource para buscar as mensagens que serão exibidas, então precisamos criar o nosso arquivo messages.properties na pasta Resources do projeto e lá adicionamos as mensagens.

invalid.document=Documento invalido

E alteramos também na annotation com chave da mensagem.

String message() default "invalid.document";

Fazendo isso a tentando novamente com um CPF que é inválido o retorno será esse:

{
    "errors": [
        {
            "code": "invalid.document",
            "message": "Documento invalido"
        }
    ]
}

Criando um Exception customizada

Outra feature interessante dessa biblioteca é a capacidade de poder fazer a tratativa dos erros nas Exceptions que criamos na aplicação.

Vamos criar uma Exception para simular um cenário e poder ficar mais claro, imaginemos que há uma regra na nossa aplicação onde não seja aceito pessoas com o nome Guilherme e vamos verificar isso na nossa classe que executa as regras de negócio:

	@Override
	public void send(CommonDTO taxpayerDTO) {
		

		TaxPayer taxPayer = TaxPayer.newBuilder().setName(((TaxpayerDTO) taxpayerDTO).getName())
				.setDocument(((TaxpayerDTO) taxpayerDTO).getDocument()).setSituation(false).setEmail(((TaxpayerDTO) taxpayerDTO).getEmail()).build();
		
		
        // Aqui está o lançamento da Exception
		if(taxPayer.getName().contains("Guilherme")) {
			throw new BadTaxpayerUser(taxPayer.getName());
		}
		
		
		producer.send(this.createProducerRecord(taxPayer), (rm, ex) -> {
			if (ex == null) {
				log.info("Data sent with success!!!");
			} else {
				log.error("Fail to send message", ex);
			}
		});

		producer.flush();

	}

No trecho de código acima temos uma Exception que recebe o nome do taxpayer, e será nessa classe de Exception que será feita a manipulação do erro para o retorno da API:

@Getter
@ExceptionMapping(statusCode = HttpStatus.I_AM_A_TEAPOT, errorCode = "bad.user.message")
public class BadTaxpayerUser extends RuntimeException {
	
    @ExposeAsArg(value = 0, name = "user")
    private final String key;

    public BadTaxpayerUser(String key) {
        super(key);
        this.key = key;
    }

}

Na BadTaxpayerUser bastou adicionarmos uma anotação @ExceptionMapping e nela passamos no campo statusCode o código HTTP que deve ser retornado e no campo errorCode é passado a chave da mensagem, que está em resources, que deve ser exibida.

Antes de vermos a anotação @ExposeAsArg iremos adicionar ao arquivo message.properties a mensagem que deve ser exibida e vamos customizá-la dessa forma:

bad.user.message=O user {user} nao pode!!!

Com isso quando adicionarmos a anotação @ExposeAsArg no atributo key da Exception temos que informar que o primeiro argumento que está entre chaves, {user}, deve ser interpolado pelo valor a ser recebido na exceção.

Agora fazendo o teste e enviando um POST com essas informações, que foram geradas pelo Gerador de pessoas da 4Devs:

{
    "name": "Guilherme Paulo Carlos Eduardo Dias",
    "document": "893.475.166-51",
    "email": "guilhermepaulocarloseduardodias-89@3dmaker.com.br"
}

Teremos como retorno o erro com status 418 I’m a teapot com o corpo da mensagem:

{
    "errors": [
        {
            "code": "bad.user.message",
            "message": "O user Guilherme Paulo Carlos Eduardo Dias nao pode!!!"
        }
    ]
}

Conclusão

Bom espero nesse artigo ter apresentando um pouco mais sobre a biblioteca Errors Spring Boot Starter e suas facilidades. Lembrando que essa é apenas uma outra maneira para lidar com validações.

O código desse projeto pode ser encontrado no GitHub

Consumindo mensagens do Kafka sem dor de cabeça

Mon, 18 Jan 2021 00:00:01 GMT

No artigo Produzindo mensagens com Kafka vimos como podemos usar o Kafka para enviar mensagens e agora vamos ver como podemos receber essas mensagens de forma simples, sem dor de cabeça e com a vantagem de termos a segurança que o Schema Registry trás com a validação de contratos.

Projeto

Esse projeto consistirá em receber as mensagens no formato Avro do Kafka e irá enviar um email para o usuário. Para iniciar o projeto foi utilizado o Spring Boot mas sem a dependência do spring kafka. Nesse projeto utilizaremos o Spring para subir a aplicação mas queremos ter mais controle sobre os processos do Kafka.

Criando projeto

Segue o pom.xml do projeto com os plugins e dependências utilizadas:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.4.1</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.irs</groupId>
	<artifactId>sender</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>sender email</name>
	<description>Send email</description>

	<properties>
		<java.version>11</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-mail</artifactId>
		</dependency>

		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>

		<!-- https://mvnrepository.com/artifact/org.apache.avro/avro -->
		<dependency>
			<groupId>org.apache.avro</groupId>
			<artifactId>avro</artifactId>
			<version>1.10.1</version>
		</dependency>

		<!--dependencies needed for the kafka part -->
		<!-- https://mvnrepository.com/artifact/org.apache.kafka/kafka-clients -->
		<dependency>
			<groupId>org.apache.kafka</groupId>
			<artifactId>kafka-clients</artifactId>
		</dependency>

		<!-- https://mvnrepository.com/artifact/io.confluent/kafka-avro-serializer -->
		<dependency>
			<groupId>io.confluent</groupId>
			<artifactId>kafka-avro-serializer</artifactId>
			<version>5.3.0</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-mail</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-configuration-processor</artifactId>
			<optional>true</optional>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>

			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
			<!--for specific record -->
			<plugin>
				<groupId>org.apache.avro</groupId>
				<artifactId>avro-maven-plugin</artifactId>
				<version>1.10.1</version>
				<executions>
					<execution>
						<phase>generate-sources</phase>
						<goals>
							<goal>schema</goal>
							<goal>protocol</goal>
							<goal>idl-protocol</goal>
						</goals>
						<configuration>
							<sourceDirectory>${project.basedir}/src/main/resources/avro</sourceDirectory>
							<stringType>String</stringType>
							<createSetters>false</createSetters>
							<enableDecimalLogicalType>true</enableDecimalLogicalType>
							<fieldVisibility>private</fieldVisibility>
						</configuration>
					</execution>
				</executions>
			</plugin>
			<!--force discovery of generated classes -->
			<plugin>
				<groupId>org.codehaus.mojo</groupId>
				<artifactId>build-helper-maven-plugin</artifactId>
				<version>3.0.0</version>
				<executions>
					<execution>
						<id>add-source</id>
						<phase>generate-sources</phase>
						<goals>
							<goal>add-source</goal>
						</goals>
						<configuration>
							<sources>
								<source>target/generated-sources/avro</source>
							</sources>
						</configuration>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>

	<repositories>
		<repository>
			<id>confluent</id>
			<url>https://packages.confluent.io/maven/</url>
		</repository>
	</repositories>

</project>

Atualizando Schema

Antes de iniciar o projeto precisamos atualizar o nosso Schema pois na primeira versão não havia a informação de email e agora precisamos disso para que o serviço funcione corretamente, o novo Schema irá manter os campos que já possuía e será adicionado o campo de email:

{
     "type": "record",
     "namespace": "com.irs.register.avro.taxpayer",
     "name": "TaxPayer",
     "version": "2",
     "fields": [
       { "name": "name", "type": "string", "doc": "Name of TaxPayer" },
       { "name": "document", "type": "string", "doc": "Document of TaxPayer" },
       { "name": "email", "type": "string", "doc": "Email of TaxPayer" },
       { "name": "situation", "type": "boolean", "default": false, "doc": "Legal situation of TaxPayer" }
     ]
}

Configurando consumidor

Vamos começar as configurações de propriedades para quando a aplicação for se conectar ao Kafka:

@Configuration
public class KafkaConfiguration implements MessageConfiguration<TaxPayer> {
	
	@Autowired
	private KafkaProperties kafkaProperties;

	@Bean(name = "taxpayerConsumer")
	@Override
	public KafkaConsumer<String, TaxPayer> configureConsumer() {
		
		Properties props = new Properties();
		
		props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, kafkaProperties.getBootstrapServers());
		props.put(ConsumerConfig.GROUP_ID_CONFIG, kafkaProperties.getGroupId());
		props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, kafkaProperties.getAutoCommit());
		props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, kafkaProperties.getOffsetReset());
		
		props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, kafkaProperties.getKeyDesserializer());
		props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, kafkaProperties.getValueDesserializer());
		
		props.put(KafkaAvroDeserializerConfig.SCHEMA_REGISTRY_URL_CONFIG, kafkaProperties.getSchemaRegistryUrl());
		props.put(KafkaAvroDeserializerConfig.SPECIFIC_AVRO_READER_CONFIG, kafkaProperties.isSpecificAvroReader());
		
		return new KafkaConsumer<String, TaxPayer>(props);
	}

}

Basicamente configuramos as urls de conexão com o Kafka e Schema Registry, definimos o nosso group id para identificação do nosso consumidor no Consumer Group, também configuramos o Auto Commit do Offset juntamente com o Auto Offset Reset, que indica se queremos sempre buscar as mensagens desde o inicio, do último offset commitado e etc. e por fim definimos que queremos usar um leitor específico do nosso Avro com a configuração SPECIFICAVROREADER_CONFIG.

Feito isso basta instanciarmos a classe KafkaConsumer passando as nossas props.

Implementando o consumidor

Com as configurações prontas agora basta que criemos a classe de serviço que irá utilizar o KafkaConsumer e irá buscar as mensagens no Kafka:

@Service
@Slf4j
public class KafkaConsumerService implements Consumer<TaxPayer> {

	@Autowired
	@Qualifier("taxpayerConsumer")
	private KafkaConsumer<String, TaxPayer> kafkaConsumer;

	@Override
	public String topic() {
		return "taxpayer-avro";
	}

	@PostConstruct
	@Override
	public void receive() {

		kafkaConsumer.subscribe(Collections.singleton(this.topic()));

		while (true) {

			try {

				kafkaConsumer.poll(Duration.ofMillis(1000)).forEach(record -> {

					log.info("Recebendo TaxPayer");

					TaxPayer taxpayer = record.value();

					Person person = Person.builder().email(taxpayer.getEmail()).name(taxpayer.getName()).build();

					log.info(person.toString());

				});

				kafkaConsumer.commitSync();

			} catch (Exception ex) {
				log.error("Erro ao processar mensagem", ex);
			}

		}

	}

}

Na classe KafkaConsumerService temos o método receive e nele usamos o KafkaConsumer para nos subscrevermos no tópico, que é o taxpayer-avro e entramos em um loop while para sempre ficarmos buscando as mensagens no Kafka e após isso commitamos o offset para as partições em caso de sucesso ou lançamos uma Exception em caso de falha.

Serviço de Email

Para configurar o serviço de envio de mensagem de email vamos usar a classe JavaMailSender que o Spring fornece:

@Configuration
public class MailConfigurer {
	
	@Bean
	public JavaMailSender getJavaMailSender() {
	    JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
	    mailSender.setHost("smtp.gmail.com");
	    mailSender.setPort(587);
	    
	    mailSender.setUsername("fake@gmail.com");
	    mailSender.setPassword("senha secreta");
	    
	    Properties props = mailSender.getJavaMailProperties();
	    props.put("mail.transport.protocol", "smtp");
	    props.put("mail.smtp.auth", "true");
	    props.put("mail.smtp.starttls.enable", "true");
	    props.put("mail.debug", "true");
	    
	    return mailSender;
	}

}

Após isso podemos criar uma classe de serviço especializada em enviar os emails:

@Service
@Slf4j
public class EmailService implements Email{
	
	@Autowired
    private JavaMailSender emailSender;

	@Override
	public void sendMessage(Person person) {
		
		try {
			
			log.info("Try to send email for : " + person.getEmail());
            SimpleMailMessage message = new SimpleMailMessage();
            message.setFrom("noreply@irs.com");
            message.setTo(person.getEmail());
            message.setSubject("Confirmação de recebimento");
            message.setText(person.getName() + " seus dados foram recebidos com sucesso");

            emailSender.send(message);
            
        } catch (MailException ex) {
        	log.error("Error to send email", ex);
        }
		
	}

}

O método sendMessage recebe um objeto do tipo Person e envia o email com a nossa mensagem.

Agora podemos injetar a classe de email no consumidor para enviar o email a cada mensagem recebida:

@Service
@Slf4j
public class KafkaConsumerService implements Consumer<TaxPayer> {

	@Autowired
	@Qualifier("taxpayerConsumer")
	private KafkaConsumer<String, TaxPayer> kafkaConsumer;

	@Autowired
	private Email email;

	@Override
	public String topic() {
		return "taxpayer-avro";
	}

	@PostConstruct
	@Override
	public void receive() {

		kafkaConsumer.subscribe(Collections.singleton(this.topic()));

		while (true) {

			try {

				kafkaConsumer.poll(Duration.ofMillis(1000)).forEach(record -> {

					log.info("Recebendo TaxPayer");

					TaxPayer taxpayer = record.value();

					Person person = Person.builder().email(taxpayer.getEmail()).name(taxpayer.getName()).build();

					email.sendMessage(person);

				});

				kafkaConsumer.commitSync();

			} catch (Exception ex) {
				log.error("Erro ao processar mensagem", ex);
			}

		}

	}

}

Agora a cada mensagem que for recebida ele irá enviar um email.

Código fonte

O código desse projeto se encontra no GitHub

Alternativa com Spring Boot

No exemplo desse artigo foi mostrado como consumir as mensagens do Kafka sem utilizar as libs do Spring Bot, caso tenha interesse em ver como seria a configuração de um consumidor utilizando a implementação do Spring Boot esses dois artigos mostram como fazer isso, a primeira usando annotations e outra sem usar annotations:

Versionando o banco de dados com Flyway

Mon, 11 Jan 2021 00:00:01 GMT

Bancos de dados são ferramentas importantíssimas que são utilizadas na construção de aplicações, existem muitas opções de bancos de dados disponíveis e cada uma atende a uma necessidade específica. Com o advento dos microsserviços e a ideia de cada aplicação administrar o seu próprio estado, os bancos de dados confirmam a sua importância.

Mas criar, atualizar e deletar colunas e tabelas não é uma tarefa das mais simples em grandes aplicações ou com cenários complexos, o Flyway surge como uma ferramenta para facilitar as migrações e o versionamento nos bancos de dados.

Contudo o Flyway não é um bala de prata e nem tem a intenção de substituir a função de um DBA, o FLyway é uma ferramenta para nos ajudar no dia-a-dia.

Adicionando o Flyway no projeto

Vou adicionar o Flyway em um projeto que já existe e utiliza o MySQL como repositório de dados.

É uma aplicação Java com Maven então é só adicionar a dependência no pom.xml:

<!-- Flyway -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

Configurando Properties

É necessário configurar os dados de conexão do banco no Flyway. Como estamos usando Spring Boot podemos adicionar isso no arquivo application.yml:

spring:
  flyway:
    url: jdbc:mysql://${DATABASE_HOST:localhost}:${DATABASE_PORT:3306}/${DATABASE:register}?createDatabaseIfNotExist=true
    user: ${DATABASE_USER:root}
    password: ${DATABASE_PASSWD:root}
    schemas:
    - ${DATABASE:register}

Aqui configuramos a url, user, password e o schema que o Flyway irá usar para se conectar no banco de dados.

Adicionando os Scripts

Vamos adicionar os scripts que o Flyway irá rodar, para isso precisamos criar a pasta dentro de resources na nossa aplicação, por padrão o Flyway irá procurar pelo caminho resources/db/migration então basta criar os diretórios e adicionar os scripts.

Outro padrão do Flyway para gerenciamento de versão dos scripts é a convenção de nomenclatura dos arquivos, eles seguem o padrão V seguido do número da versão acompanhado de underline exemplo:

V1_1__meu-script.sql

Para essa aplicação vamos ter dois scripts iniciais, um para criar as tabelas e outro para executar a carga inicial:

V1_0__create_tables.sql:

create table perfil (
    id integer not null auto_increment,
    name varchar(255),
    primary key (id)
) engine=InnoDB;

create table user (
    id integer not null auto_increment,
    email varchar(255),
    pass varchar(255),
    primary key (id)
) engine=InnoDB;

create table user_perfis (
    user_id integer not null,
    perfis_id integer not null,
    primary key (user_id, perfis_id)
) engine=InnoDB;

alter table user_perfis add constraint perfil_id_constraint foreign key (perfis_id) references perfil (id);

alter table user_perfis add constraint user_id_constraint foreign key (user_id) references user (id);

V1_1__init.sql:

INSERT INTO register.`user`
(email, pass)
VALUES('jonhdoe@email.com', '$2a$10$JgDI7KttG8BX9AO.3mGTref9mjDxHKtx3sjqnaP3Vq88BzUNxA38S');

INSERT INTO register.perfil
(name)
VALUES('USER');

INSERT INTO register.perfil
(name)
VALUES('ADMIN');

INSERT INTO register.user_perfis
(user_id, perfis_id)
VALUES(1, 1);

Executando o Flyway

Quando iniciamos a nossa aplicação o Flyway é automaticamente iniciado e executa os scripts, a saída no console da aplicação é parecido com isso:

INFO 77800 --- [  restartedMain] o.f.c.internal.license.VersionPrinter    : Flyway Community Edition 7.1.1 by Redgate
INFO 77800 --- [  restartedMain] o.f.c.i.database.base.DatabaseType       : Database: jdbc:mysql://localhost:3306/register (MySQL 8.0)
INFO 77800 --- [  restartedMain] o.f.core.internal.command.DbValidate     : Successfully validated 2 migrations (execution time 00:00.152s)
INFO 77800 --- [  restartedMain] o.f.c.i.s.JdbcTableSchemaHistory         : Creating Schema History table `register`.`flyway_schema_history` ...
INFO 77800 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Current version of schema `register`: << Empty Schema >>
INFO 77800 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Migrating schema `register` to version "1.0 - create tables"
INFO 77800 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Migrating schema `register` to version "1.1 - init"
INFO 77800 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Successfully applied 2 migrations to schema `register` (execution time 00:00.625s)

Aqui podemos ver a mensagem de que o script foi executado com sucesso, mas o que acontece se executarmos a nossa aplicação novamente?

INFO 78443 --- [  restartedMain] o.f.c.internal.license.VersionPrinter    : Flyway Community Edition 7.1.1 by Redgate
INFO 78443 --- [  restartedMain] o.f.c.i.database.base.DatabaseType       : Database: jdbc:mysql://localhost:3306/register (MySQL 8.0)
INFO 78443 --- [  restartedMain] o.f.core.internal.command.DbValidate     : Successfully validated 2 migrations (execution time 00:00.115s)
INFO 78443 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Current version of schema `register`: 1.1
INFO 78443 --- [  restartedMain] o.f.core.internal.command.DbMigrate      : Schema `register` is up to date. No migration necessary.

Podemos ver que os scripts são validados porém o Flyway consegue gerenciar se o script já foi executado, isso acontece graças a tabela flywayschemahistory que guarda as informações dos scripts executados:

| instaled_rank | version | description   | type | script                  | checksum    | installed_by | installed_on        | execution_time | success |
|---------------|---------|---------------|------|-------------------------|-------------|--------------|---------------------|----------------|---------|
| 1             | 1.0     | create tables | SQL  | V1_0__create_tables.sql | 1225588812  | root         | 2021-01-11 17:57:36 | 460            | 1       |
| 2             | 1.1     | init          | SQL  | V1_1__init.sql          | -1406395169 | root         | 2021-01-11 17:57:36 | 27             | 1       |

Essa tabela trás informações que servem para o Flyway se gerenciar e gerenciar os scripts.

Flyway em um banco já populado

Se adicionarmos o Flyway em uma aplicação que já possui um banco de dados populado ocorrerá um erro, mas podemos resolver isso com uma configuração simples no application.yml:

spring:
  flyway:
    baseline-on-migrate: true

Código fonte

Segue o código no GitHub

Produzindo mensagens com Kafka e Schema Registry

Fri, 01 Jan 2021 00:00:01 GMT

Vamos iniciar uma série de artigos sobre Kafka, a intenção será mostrar a criação de diversas aplicações que irão se comunicar de forma assíncrona utilizando o Apache Kafka.

Trabalhar com assincronicidade não é uma tarefa simples e fácil, mas extremamente importante em grandes sistemas que precisam manipular grandes volumes de dados.

Pensando nisso o LinkedIn desenvolveu uma ferramenta para comunicação de mensagens assíncronas, levando em consideração contextos onde o grande volume de dados seja algo impactante, posteriormente se tornando Open Source pela Apache o Kafka é uma ferramente robusta, rápida e escalável.

Existem muitas ferramentas de mensageria disponíveis e não entraremos aqui no mérito de qual é melhor ou pior, vamos demonstrar que apesar de ser uma ferramenta com suas peculiaridades o Kafka pode ser configurado e utilizado de forma rápida, produtiva e sem grandes dores de cabeça para isso. Nesse artigo criaremos um produtor de mensagens com Kafka, também iremos mostrar a vantagem de usarmos um validador para as nossas mensagens através de contratos com Schema Registry e utilizaremos Spring Boot.

Também não vamos nos alongar muito nos conceitos sobre o que é o Kafka e suas específicidades caso tenha interesse sugerimos os seguintes artigos:

Criando o ambiente

Antes de mais nada vamos montar a nossa infra estrutura com o Kafka, mas nesse exemplo não iremos instalar o Kafka e todos os outros serviços dele pois além de ser custoso para a máquina que vai rodá-lo não é necessário com a abordagem que faremos. Ao invés disso usaremos Docker e Docker Compose para levantar o nosso ambiente.

Utilizaremos a imagem disponibilizada pela Landoop que nos fornece todo o ambiente de desenvolvimento necessário para utilizarmos as funcionalidades do Kafka, além disso vamos utilizar em conjunto com Docker Compose para termos controle sobre as configurações de variáveis de ambiente, portas e rede.

O nosso docker-compose.yml ficará assim:

version: '2'

services:
  # this is our kafka cluster.
  kafka-cluster:
    image: landoop/fast-data-dev:cp3.3.0
    environment:
      ADV_HOST: 127.0.0.1         # Change to 192.168.99.100 if using Docker Toolbox
      RUNTESTS: 0                 # Disable Running tests so the cluster starts faster
      FORWARDLOGS: 0              # Disable running 5 file source connectors that bring application logs into Kafka topics
      SAMPLEDATA: 0               # Do not create sea_vessel_position_reports, nyc_yellow_taxi_trip_data, reddit_posts topics with sample Avro records.
    ports:
      - 2181:2181                 # Zookeeper
      - 3030:3030                 # Landoop UI
      - 8081-8083:8081-8083       # REST Proxy, Schema Registry, Kafka Connect ports
      - 9581-9585:9581-9585       # JMX Ports
      - 9092:9092                 # Kafka Broker

Para rodar basta abrirmos o terminal onde está localizado o nosso arquivo docker-compose.yml e executar:

docker-compose up -d

Após fazer isso podemos acessar http://localhost:3030/ e conseguiremos abrir o dashboard que a Landoop disponibiliza e teremos algo parecido com isso:

Schema Registry

Antes de iniciarmos o projeto vamos entender o que é o Schema Registry e por que ele é importante.

O Kafka envia e recebe mensagens porém não faz validação sobre o que está sendo enviado ou recebido até que a aplicação consumidora tente realizar a desserialização da mensagem e caso o contrato da aplicação consumidora não seja compatível ocorrerá um erro. Para evitar isso a Confluent criou o Schema Registry para fazer a validação de contratos e metadados das mensagens que são trafegadas.

A grosso modo o Schema Registry valida se a mensagem que está sendo enviada por uma aplicação é compatível. Podemos usar vários formatos de arquivos para criar os nossos schemas como XML, CSV, JSON mas aqui usaremos Apache Avro que é um formato desenvolvido para criação de schemas com tipagem.

O Schema Registry é um componente apartado do Kafka como na imagem abaixo:

Avro

Para começarmos a criar o nosso produtor de mensagens vamos aproveitar o projeto do artigo sobre Spring Security com JWT.

Essa aplicação é usada para simular o envio de dados para receita federal, a princípio fazemos um POST com os dados de um contribuinte contendo o nome e o CPF.

Vamos começar criando o nosso Avro, dentro da pasta resources/avro criamos o arquivo taxpayer-v1.avsc contendo o nosso schema:

{
     "type": "record",
     "namespace": "com.irs.register.avro.taxpayer",
     "name": "TaxPayer",
     "version": "1",
     "fields": [
       { "name": "name", "type": "string", "doc": "Name of TaxPayer" },
       { "name": "document", "type": "string", "doc": "Document of TaxPayer" },
       { "name": "situation", "type": "boolean", "default": false, "doc": "Legal situation of TaxPayer" }
     ]
}

O nosso Avro contém os metadados de type, namespace, name e version. Também adicionamos os campos da nossa entidade no array fields e nele conseguimos além do name colocar outros atributos como tipagem com o type e valores padrão com o campo default.

Vamos adicionar as dependências no projeto:

<dependency>
    <groupId>org.apache.avro</groupId>
    <artifactId>avro</artifactId>
    <version>1.10.1</version>
</dependency>

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
</dependency>

<dependency>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-avro-serializer</artifactId>
    <version>5.3.0</version>
</dependency>

E também precisamos adicionar o plugin que irá interpretar o nosso Avro e vai gerar a classe Java correspondente.

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>

        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <!--for specific record -->
        <plugin>
            <groupId>org.apache.avro</groupId>
            <artifactId>avro-maven-plugin</artifactId>
            <version>1.10.1</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>schema</goal>
                        <goal>protocol</goal>
                        <goal>idl-protocol</goal>
                    </goals>
                    <configuration>
                        <sourceDirectory>${project.basedir}/src/main/resources/avro</sourceDirectory>
                        <stringType>String</stringType>
                        <createSetters>false</createSetters>
                        <enableDecimalLogicalType>true</enableDecimalLogicalType>
                        <fieldVisibility>private</fieldVisibility>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        <!--force discovery of generated classes -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>3.0.0</version>
            <executions>
                <execution>
                    <id>add-source</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>target/generated-sources/avro</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Com isso feito podemos rodar o comando mvn generate-sources e a nossa classe será gerada em target/generated-sources/avro/TaxPayer.java.

Configurando o Kafka

Precisamos configurar a nossa aplicação para se conectar com o Kafka. O Kafka contém uma série de configurações customizáveis e para deixar mais flexível vamos usar algumas delas via properties.

Vamos criar a nossa classe de configuração dos nossos properties:

@Configuration
@ConfigurationProperties(
    prefix = "kafka"
)
@Data
@NoArgsConstructor
public class KafkaProperties {
	
	private List<String> bootstrapServers;
	private String acksConfig;
	private String retriesConfig;
	private Class<?> keySerializer = StringSerializer.class;
	private Class<?> valueSerializer = KafkaAvroSerializer.class;
	private String schemaRegistryUrl;

}

E no nosso arquivo application.yml:

kafka:
  bootstrapServers: 127.0.0.1:9092 
  acksConfig: all
  retriesConfig: 10
  schemaRegistryUrl: "http://127.0.0.1:8081"

Aqui temos as configurações para conectar no Kafka, no Schema Registry, como iremos fazer serialização e desserialização, também temos a configuração de Acks que é a confirmação do envio da mensagem, nesse caso queremos que todas as mensagens enviadas informem que foram enviadas positivamente e por fim temos a configuração de Retries que irá indicar o reenvio de mensagens que falharem. Existem muitas outras configurações que podemos adicionar mas por hora essas atendem muito bem a nossa aplicação.

Com o nosso properties criado podemos fazer a configuração do Kafka injetando a classe KafkaProperties e configurando o nosso Bean do produtor do Kafka:

@Configuration
public class MessagingConfigTaxPayer implements MessagingConfigPort<TaxPayer> {
	
	@Autowired
	private KafkaProperties kafkaProperties;

	@Bean(name = "taxpayerProducer")
	@Override
	public KafkaProducer<String, TaxPayer> configureProducer() {

		Properties properties = new Properties();
		
        properties.put(BOOTSTRAP_SERVERS_CONFIG, kafkaProperties.getBootstrapServers());
        properties.put(ACKS_CONFIG, kafkaProperties.getAcksConfig());
        properties.put(RETRIES_CONFIG, kafkaProperties.getRetriesConfig());
        properties.put(KEY_SERIALIZER_CLASS_CONFIG, kafkaProperties.getKeySerializer());
        properties.put(VALUE_SERIALIZER_CLASS_CONFIG, kafkaProperties.getValueSerializer());
        properties.put(SCHEMA_REGISTRY_URL_CONFIG, kafkaProperties.getSchemaRegistryUrl());
		
		return new KafkaProducer<String, TaxPayer>(properties);
		
	}

}

Configurando o Produtor

Agora vamos criar o nosso produtor que implementa a interface MessagingPort que possui três métodos:

String topic()
ProducerRecord<String, T> createProducerRecord(T t)
void send(CommonDTO dto)

Esses três métodos fornecem o que precisamos para conseguir enviar uma mensagem pelo Kafka e no nosso exemplo será uma classe tipada para a nossa classe TaxPayer:

@Service
@Slf4j
public class TaxpayerService implements MessagingPort<TaxPayer> {

	@Autowired
	@Qualifier("taxpayerProducer")
	private KafkaProducer<String, TaxPayer> producer;

	@Override
	public String topic() {
		return "taxpayer-avro";
	}
		
	@Override
	public ProducerRecord<String, TaxPayer> createProducerRecord(TaxPayer taxPayer) {

		return new ProducerRecord<String, TaxPayer>(this.topic(), taxPayer);
		
	}

	@Override
	public void send(CommonDTO taxpayerDTO) {
		

		TaxPayer taxPayer = TaxPayer.newBuilder().setName(((TaxpayerDTO) taxpayerDTO).getName())
				.setDocument(((TaxpayerDTO) taxpayerDTO).getDocument()).setSituation(false).build();
		
		
		producer.send(this.createProducerRecord(taxPayer), (rm, ex) -> {
			if (ex == null) {
				log.info("Data sent with success!!!");
			} else {
				log.error("Fail to send message", ex);
			}
		});

		producer.flush();
		producer.close();

	}

}

Detalhando cada método.

No método topic nós setamos o nome do tópico no Kafka.

O método createProducerRecord recebe como parâmetro o nosso TaxPayer e devolve um ProducerRecord.

O método send recebe um CommonDTO, que nada mais é do que uma interface de marcação para os DTOs da aplicação, nele podemos ver que usamos o Builder que a TaxPayer fornece, passando os dados que iremos receber no POST da API.

Também é nesse método que fazemos o envio da mensagem para o Kafka, podemos ver que o método send do KafkaProducer recebe o nosso TaxPayer mas também executa uma função de callback onde fazemos uma simples verificação de sucesso ou erro e logamos o resultado. Após isso “atualizamos” a transação e fechamos.

Controller

Precisamos criar a porta de entrada da aplicação, o lugar que irá receber os dados e repassar para a nossa Service.

@RestController
@RequestMapping("/taxpayer")
public class TaxpayerController {
	
	@Autowired
	private TaxpayerService taxpayerService;
	
	@PostMapping
	public ResponseEntity<TaxpayerDTO> postTaxpayer(@RequestBody TaxpayerDTO taxpayer){
		
		taxpayerService.send(taxpayer);
		
		return ResponseEntity.ok(taxpayer);
	}

}

Criamos o endpoint /taxpayer que recebe um TaxpayerDTO e chama a TaxpayerService que é a responsável por enviar a nossa mensagem.

A nossa classe TaxpayerDTO:

@Data
public class TaxpayerDTO implements CommonDTO{
	
	private String name;
	
	private String document;

	@Override
	public String getType() {
		return "TaxPayerDTO";
	}

}

Executando

Vamos executar a aplicação e enviar um POST para conferir o funcionamento, para enviar os dados foi utilizado o Gerador de Pessoas e também é necessário enviar o token JWT para autorização a esse recurso, para saber mais sobre isso consultar o artigo sobre Spring Security com JWT.

E como estamos usando o dashboard da Landoop podemos acessar e ver que o nosso Schema foi criado e que o nosso tópico também foi criado e que ele possui os dados enviados.

A cima vemos o nosso schema criado.

E aqui temos o nosso tópico criado e vemos a informação que foi enviada.

Consumindo via Terminal

Podemos produzir, consumir, criar e fazer todas as operações do Kafka via terminal, agora para fins de exemplo vamos consumir a mensagem que enviamos via terminal.

Podemos fazer isso acessando o nosso Schema Registry via Docker:

docker run -it --rm --net=host confluentinc/cp-schema-registry:3.3.1 bash

E para consumir a mensagem usaremos o utilitário de linha de comando kafka-avro-console-consumer:

kafka-avro-console-consumer --topic taxpayer-avro \
     --bootstrap-server localhost:9092 \
     --from-beginning \
     --property schema.registry.url=http://127.0.0.1:8081

Que irá produzir o resultado:

{"name":"Luís Marcelo da Conceição","document":"216.172.648-06","situation":false}

Código fonte

Segue o código completo no GitHub

Spring Security e JWT

Mon, 14 Dec 2020 00:00:01 GMT

Implementar segurança em aplicações não é algo simples e requer atenção em muitos detalhes.

Pensando nisso o Spring Security surgiu para descomplicar muitos pontos e juntamente com o Spring Boot deixou o desenvolvimento de aplicações seguras muito mais produtivo e descomplicado, nesse post iremos implementar em uma aplicação uma API REST para autenticação e geração de um token JWT para completar as requisições de forma segura.

Criando o projeto

Usando o site spring initializr criamos um projeto base e já adicionamos as dependências do Spring Security, Spring Web e adicionamos a dependência do Json Web Token; como estamos criando um projeto Maven o pom.xml ficará assim:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.4.0</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.irs.register</groupId>
	<artifactId>register</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>register</name>
	<description>Register Service</description>

	<properties>
		<java.version>11</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-actuator</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-security</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>
		<!-- https://mvnrepository.com/artifact/mysql/mysql-connector-java -->
		<dependency>
			<groupId>mysql</groupId>
			<artifactId>mysql-connector-java</artifactId>
			<version>8.0.22</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.security</groupId>
			<artifactId>spring-security-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>io.jsonwebtoken</groupId>
			<artifactId>jjwt</artifactId>
			<version>0.9.1</version>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

No nosso pom.xml podemos ver além das dependências que foram mencionadas a cima, as dependências do Lombok, Spring Data, Actuator e DevTools que irão ajudar no desenvolvimento.

Habilitando o contexto de segurança

Para começarmos a configurar o Spring Security vamos criar uma classe e adicionaremos as anotações @EnableWebSecurity e @Configuration para que ela seja carregada e esteja configurada no inicio da aplicação. Além disso estendemos a classe WebSecurityConfigurerAdapter que expõe três métodos para fazer as configurações necessárias:

public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
	
    //Configurations for authentication
    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    }

    //Configuration for authorization
    @Override
    protected void configure(HttpSecurity http) throws Exception {
    }

    //Configuration for static resources
    @Override
    public void configure(WebSecurity web) throws Exception {
    }
}

Podemos observar que temos três métodos chamados configure mas que recebem parâmetros diferentes:

O primeiro configure que recebe AuthenticationManagerBuilder é o método que será usado para configurar a autenticação.
O segundo configure que recebe HttpSecurity é para a autorização das requisições.
O terceiro configure que recebe WebSecurity é para arquivos estáticos como CSS, JS, HTML, mas não usaremos nesse exemplo pois estamos criando uma API REST.

Como estamos usando o Actuator já recebemos alguns endpoints para monitorar a saúde da nossa aplicação, entre eles temos o /actuator/health que retorna se a aplicação está no ar ou instável, se iniciarmos a aplicação e tentarmos acessar esse endpoint receberemos a seguinte mensagem:

{
    "timestamp": "2020-12-11T22:29:51.654+00:00",
    "status": 403,
    "error": "Forbidden",
    "message": "Access Denied",
    "path": "/actuator/health"
}

Recebemos o status code 403 Forbidden nos indicando que a url não pode ser acessada pois o acesso foi negado.

Configurando Endpoint de Autenticação

Já temos as urls protegidas, agora vamos configurar a autenticação. Primeiramente vamos criar um Controller que receba uma requisição de login de um usuário:

@RestController
@RequestMapping("/auth")
public class AuthenticationController {
	
	@Autowired
	private AuthenticationManager authenticationManager;
	
	@Autowired
	private TokenService tokenService;
	
	@PostMapping
	public ResponseEntity<TokenDTO> auth(@RequestBody @Validated LoginDTO loginDTO){
		UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(loginDTO.getUser(), loginDTO.getPass());
		
		Authentication authentication = authenticationManager.authenticate(usernamePasswordAuthenticationToken);
		
		String token = tokenService.generateToken(authentication);
		
		return ResponseEntity.ok(TokenDTO.builder().type("Bearer").token(token).build());
		
	}

}

Esse Controller é um endpoint REST mapeado para /auth que tem uma entrada do tipo POST que recebe um objeto do tipo LoginDTO que possui o email e a senha e realiza a autenticação e devolve o token de acesso, podemos ver que já existem as classes de serviço do token e de autenticação, mais detalhes a diante.

Se tentarmos fazer um requisição do tipo POST com um usuário e senha vamos tomar um erro 403 Forbidden mas por que isso acontece?

Bom antes de mais nada devemos voltar para a nossa classe SecurityConfiguration e precisamos configurar quais rotas serão protegidas e quais rotas podem estar disponíveis, como é o caso da rota de login que deve estar aberta pois sem ela não há como um usuário se autenticar, vamos colocar também a configuração de sessão. Como estamos estamos usando a estratégia de token a configuração de sessão será STATELESS que significa que não será guardado estado como era feito antigamente, onde um usuário logado ficava com seus dados guardados no servidor e era enviado algum tipo de identificador, Cookie, para o client ou front-end para que nas próximas requisições fosse enviado esse Cookie para o servidor e ele saber quem é aquele usuário.

    //Configuration for authorization
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
        	.antMatchers(HttpMethod.POST, "/auth").permitAll()
        	.anyRequest().authenticated()
        	.and().csrf().disable()
        	.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
    }

O objeto HttpSecurity possui uma API fluída o que significa que os métodos podem ser chamados em sequência e essa sequência forma uma frase explícita da intenção.

Lendo o código a cima temos a seguinte intenção: Autorize, os requests com o padrão /auth são permitidos, qualquer outro é necessário estar autenticado, desabilite a política CSRF e no gerenciamento de sessão use a política STATELESS

Obs: CSRF (Cross-site request forgery) ou XSRF é tipo de ataque na web porém para o tipo de autenticação com web token estamos livre desse tipo de problema.

Configuração de autenticação

Feito isso podemos chamar o nosso endpoint porém ainda é necessário fazer mais configurações pois temos que criar as classes de serviços para fazer a autenticação.

Voltando para o Controller temos duas classes sendo injetadas

    @Autowired
	private AuthenticationManager authenticationManager;
	
	@Autowired
	private TokenService tokenService;

A primeira é uma classe do próprio Spring Security e só injetaremos ela aqui mas precisamos fazer as configurações pertinentes a ela lá na nossa classe de configuração no método configure que recebe um objeto do tipo AuthenticationManagerBuilder e é o método responsável por lidar com a autenticação:

    @Autowired
	private AuthenticationService authenticationService;

    //Configurations for authentication
    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    	auth.userDetailsService(authenticationService).passwordEncoder(new BCryptPasswordEncoder());
    }

Esse método será chamado durante a autenticação e para validação dos dados de usuário irá chamar a classe AuthenticationService, importante também verificar que estamos usando um encoder para o nosso password pois não queremos ser capazes de armazenar o password em texto simples, mas para entender melhor precisamos entrar nessa classe de serviço e verificar o que é feito.

@Service
public class AuthenticationService implements UserDetailsService{
	
	@Autowired
	private UserRepositoryPort repository;

	@Override
	public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
		Optional<User> optional = repository.findByEmail(username);
		
		if(optional.isPresent()) {
			return optional.get();
		}
		
		throw new UsernameNotFoundException("User not found");
	}	

}

A primeira coisa que percebemos é que essa classe implementa a interface UserDetailsService que possui o método loadUserByUsername e devolve um objeto do tipo UserDetails.

O que basicamente acontece aqui é que ele vai buscar em algum repositório por esse usuário e verificar se ele existe e devolver para o processo de autenticação, mas ainda não temos nada disso criado, então vamos criar o nosso repositório agora.

Criando Repositório para autenticação

O repositório será um banco de dados que armazena os usuários dessa aplicação, então segue o mapeamento da classe User que implementa a classe UserDetails do Spring Security:

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity
@Table(name = "User")
public class User implements UserDetails{
	
	/**
	 * 
	 */
	private static final long serialVersionUID = 1L;

	@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
	private Integer id;
	
	private String email;
	
	private String pass;
	
	@ManyToMany(fetch = FetchType.EAGER)
	private Set<Perfil> perfis;

	@Override
	public Collection<? extends GrantedAuthority> getAuthorities() {
		return this.perfis;
	}

	@Override
	public String getPassword() {
		return this.pass;
	}

	@Override
	public String getUsername() {
		return this.email;
	}

	@Override
	public boolean isAccountNonExpired() {
		return true;
	}

	@Override
	public boolean isAccountNonLocked() {
		return true;
	}

	@Override
	public boolean isCredentialsNonExpired() {
		return true;
	}

	@Override
	public boolean isEnabled() {
		return true;
	}

}

O fato de implementarmos UserDetails faz com que implementemos alguns métodos para fazer a checagem se o usuário existe e se ele pode se autenticar. Também é necessário informar as permissões de acesso para esse usuário através do método getAuthorities e para fazer esse mapeamento foi criado a classe Perfil:

@Data
@AllArgsConstructor
@NoArgsConstructor
@Entity
@Table(name = "Perfil")
public class Perfil implements GrantedAuthority{
	

	private static final long serialVersionUID = 1L;

	@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
	private Integer id;
	
	private String name;

	@Override
	public String getAuthority() {
		return this.name;
	}

}

Essa classe por sua vez implementa a interface GrantedAuthority que representa as permissões concedidas para um usuário.

Agora criamos a interface que será o serviço de Repository para buscar essas informações:

@Repository
public interface UserRepository extends CrudRepository<User, Integer>{
	
	Optional<User> findByEmail(String email);

}

Com isso agora a nossa classe AuthenticationService vai funcionar quando for chamada em uma requisição com usuário e senha.

Devolvendo JSON Web Token

Após a autenticação ser efetuada o nosso Controller irá retornar o JWT para que seja usado em próximas requisições, precisamos agora fazer a configuração para retornar esse token para o usuário.

No Controller temos o seguinte trecho de código:

	@PostMapping
	public ResponseEntity<TokenDTO> auth(@RequestBody @Validated LoginDTO loginDTO){
		UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(loginDTO.getUser(), loginDTO.getPass());
		
		Authentication authentication = authenticationManager.authenticate(usernamePasswordAuthenticationToken);
		
		String token = tokenService.generateToken(authentication);
		
		return ResponseEntity.ok(TokenDTO.builder().type("Bearer").token(token).build());
		
	}

Aqui usamos a classe TokenService para gerar o token, essa classe recebe um objeto do tipo Authentication que é retornado após realizar todos os passos de autenticação.

@Service
public class TokenService {

	@Value("${jwt.expiration}")
	private String expiration;

	@Value("${jwt.secret}")
	private String secret;

	public String generateToken(Authentication authentication) {

		User usuario = (User) authentication.getPrincipal();

		Date now = new Date();
		Date exp = new Date(now.getTime() + Long.parseLong(expiration));

		return Jwts.builder().setIssuer("MinhaAplicacao")
                             .setSubject(usuario.getId().toString())
                             .setIssuedAt(new Date())
				             .setExpiration(exp)
                             .signWith(SignatureAlgorithm.HS256, secret).compact();
	}

}

Aqui recebemos o objeto Authentication e dentro dele temos o método getPrincipal onde temos o nosso User e vamos devolver o nosso JWT com algumas informações:

Issuer: Nome da aplicação que está retornando o JWT.
Subject: Aqui iremos retornar o id do usuário.
IssuedAt: Data de geração do token.
Expiration: Data de expiração do token.
SignWith: Assinatura do token com o algoritmo HmacSHA256 juntamente com o secret.
Compact: Método que serializa o token.

As variáveis expiration e secret foram definidas no arquivos *application.yml *

Com isso já teremos o retorno do JWT que pode ser usado nas próxima requests.

Autorizando JWT

Agora já conseguimos autenticar com usuário e senha e devolver um token para ser usado nas próximas requisições, mas precisamos configurar essa parte na aplicação.

Como estamos usando gerenciamento de sessão Stateless cada requisição é “nova” para a aplicação, a aplicação não tem conhecimento que o usuário já realizou anteriormente a autenticação. Por isso usamos o token que contém informações para permitir o acesso do usuário aos recursos da aplicação.

O que podemos fazer é verificar se uma requisição que está tentando acessar algum recurso possui um token e se esse token é válido.

Podemos fazer isso interceptando uma requisição.

public class TokenAuthenticationFilter extends OncePerRequestFilter {
	
	@Override
	protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
			throws ServletException, IOException {

		filterChain.doFilter(request, response);
	}

}

Criamos a classe TokenAuthenticationFilter que estende de OncePerRequestFilter que já faz a interceptação das requisições e temos o método doFilterInternal onde podemos manipular vários dados.

Fora isso temos que informar para o Spring Security que temos um Filter e que ele deve ser processado em ordem, vamos voltar na classe SecurityConfiguration e adicionar no método configure:

    //Configuration for authorization
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
        	.antMatchers(HttpMethod.POST, "/auth").permitAll()
        	.anyRequest().authenticated()
        	.and().csrf().disable()
        	.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            //Configuração do Filtro
        	.and().addFilterBefore(new TokenAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
    }

Aqui adicionamos a configuração de filtro e que ele deve ser antes do filtro do Spring Security UsernamePasswordAuthenticationFilter, agora voltando para a classe de filtro precisamos configurá-la para extrair o token da requisição e validar:

	@Override
	protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
			throws ServletException, IOException {

		String token = request.getHeader("Authorization");
		if(token == null || token.isEmpty() || !token.startsWith("Bearer ")) {
			token = null;
		}
		
		token = token.substring(7, token.length());

		filterChain.doFilter(request, response);
	}

No código a cima conseguimos extrair o token do cabeçalho Authorization e verificamos se ele existe e se ele é um token do tipo Bearer, agora precisamos verificar se ele é válido. Para isso precisamos da secret que foi usada quando geramos o token então essa lógica vai ficar na classe TokenService no método isValid que recebe a String do token e retorna um boolean.

	public boolean isTokenValid(String token) {
		try {
			Jwts.parser().setSigningKey(secret).parseClaimsJws(token);
			return true;
		} catch (Exception e) {
			return false;
		}
	}

Esse método faz uso da biblioteca jsonwebtoken e aqui fazemos uso do método parseClaimsJws, caso não consiga fazer o parse do token com a secret irá lançar uma Exception, caso não dê erro é por que o token é válido.

	@Override
	protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
			throws ServletException, IOException {
		
		String tokenFromHeader = getTokenFromHeader(request);
		boolean tokenValid = tokenService.isTokenValid(tokenFromHeader);
		if(tokenValid) {
			this.authenticate(tokenFromHeader);
		}

		filterChain.doFilter(request, response);
	}

	private void authenticate(String tokenFromHeader) {
		Integer id = tokenService.getTokenId(tokenFromHeader);
		
		Optional<User> optionalUser = repository.findById(id);
		
		if(optionalUser.isPresent()) {
			
			User user = optionalUser.get();
			
			UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(user, null, user.getPerfis());
			SecurityContextHolder.getContext().setAuthentication(usernamePasswordAuthenticationToken);
		}
	}

	private String getTokenFromHeader(HttpServletRequest request) {
		String token = request.getHeader("Authorization");
		if(token == null || token.isEmpty() || !token.startsWith("Bearer ")) {
			return null;
		}
		
		return token.substring(7, token.length());
	}

Aqui acima temos o uso dos dois métodos e de mais um novo que é o authenticate que usa o método getTokenId para extrair o id que é enviado no token, no Subject e após isso faz uma busca por esse id no repositório. Caso encontre instânciamos um objeto UsernamePasswordAuthenticationToken passando o user, null no parâmetro da senha pois não precisamos dela nesse ponto e a lista de perfis. Passamos ele para o objeto SecurityContextHolder que é objeto que lida com o contexto de segurança da aplicação.

Analisando a TokenService no método getTokenId:

	public Integer getTokenId(String token) {
		Claims body = Jwts.parser().setSigningKey(secret).parseClaimsJws(token).getBody();
		return Integer.valueOf(body.getSubject());
	}

Vemos que aqui novamente fazemos uso da biblioteca jsonwebtoken mas agora pegamos o body para recuperar o Subject.

Após iniciarmos a aplicação e autenticarmos com um usuário já cadastrado conseguimos acessar a rota que o Actuator expõe e até o momento estava inacessível.

Aqui fazemos a autenticação e recebemos o token na resposta.

E agora com o JWT no Header de Authorization fazemos o GET para a url protegida.

Código fonte

Segue o código completo no GitHub.

Padrões de projeto com JavaScript

Thu, 01 Oct 2020 00:00:01 GMT

Introdução

JavaScript é uma linguagem moderna e dinâmica onde temos muita flexibilidade pois sua tipagem é fraca, possibilitando com que possamos fazer muitas manipulações em nosso código, é uma linguagem multiparadigma o que significa que possui elementos de POO (Programação Orientada a Objetos) e também de programação funcional.

No exemplo vamos entender como usamos os mecanismos internos do JavaScript para fazer herança, por meio de Prototypes, como podemos adicionar comportamentos em um objeto já existente e como podemos criar um histórico das transformações que ocorreram em nosso código.

Definição do projeto

Então vamos ao nosso projeto, vamos supor que trabalhamos em um empresa de tecnologia e temos três tipos de funcionários, o dev. Júnior, o Pleno e o Sênior e que cada um pode realizar uma tarefa distinta, o Júnior pode fazer commit do seu código em um repositório da empresa, o Pleno pode fazer commit e revisar o código e o Sênior faz tudo isso e ainda faz o deploy.

Isso é só um exemplo prático não refletindo a realidade ou enviesando como deve ser um fluxo de trabalho no dia-a-dia

Prototype

Aqui vamos abordar o padrão criacional Prototype, esse padrão serve para criar objetos a partir de outros existentes, criando uma cópia do objeto e podendo adicionar mais atributos nele.

No JavaScript a idéia de protótipos é muito forte, pois todo objeto em JS possui propriedades internas, que são chamados de Prototype que é uma referência para outro objeto; resumindo é a forma como o JS faz herança.

*Tem muito mais conteúdo sobre o assunto de Prototype e pode ser encontrado aqui*

Para o nosso exemplo vamos começar criando a estrutura base do que seria um funcionário, na pasta prototype no arquivo index.js vamos criar a nossa function Developer que recebe name e registration. Com isso temos a base (protótipo) para a criação de novos objetos, mais abaixo vamos começar a criar os nossos objetos especializados e adicionar neles a propriedade position onde é informado a senioridade do funcionário:

function Developer(name, registration) {

    this.name = name;
    this.registration = registration;

}

exports.createJunior = function (name, registration) {
    return Object.create(new Developer(name, registration), { position: { value: 'Junior' } })
}

exports.createPleno = function (name, registration) {
    return Object.create(new Developer(name, registration), { position: { value: 'Pleno' } })
}

exports.createSenior = function (name, registration) {
    return Object.create(new Developer(name, registration), { position: { value: 'Senior' } })
}

Com isso feito agora quando quisermos criar um funcionário basta que chamemos a função criadora respectiva e nos será devolvido o funcionário com sua position correta como no exemplo de uso abaixo:

const {createJunior, createPleno, createSenior} = require('./prototype');

const junior = createJunior("junior", "123");

const pleno = createPleno("pleno", "456");

const senior = createSenior("senior", "789");

Decorator

O padrão Decorator nos permite adicionar comportamentos em um objeto de forma dinâmica. Pensando em como isso pode nos ajudar nesse projeto podemos imaginar que temos ações que cada desenvolvedor pode ou não fazer e podemos adicionar esse comportamento em tempo de execução, tornando o nosso código mais flexível. Podemos aproveitar isso fazendo as nossas validações do que cada desenvolvedor poderá fazer, em nossa pasta decorator iremos adicionar o seguinte código.

exports.commit = function (Developer) {
    let c = Developer.commit();
    return c + `Developer ${Developer.position} can committing\n`
}

exports.codeReview = function (Developer) {
    let cr = Developer.codeReview();
    let test = Developer.position === 'Junior' ? `Developer ${Developer.position} can not make code review` : `Developer ${Developer.position} can make code review`;
    return cr + test + '\n';
}

exports.deploy = function (Developer) {
    let d = Developer.deploy();
    let test = Developer.position !== 'Senior' ? `${Developer.position} can not deploy` : `Only Developers ${Developer.position} can deploy`;
    return d + test + '\n';
}

Também adicionamos as funções no nosso arquivo onde temos a definição de Developer:

function Developer(name, registration) {

    this.name = name;
    this.registration = registration;

    this.commit = function () {
        return "Can I to commit?\n";
    };
    this.codeReview = function () {
        return "Can I to do code review?\n";
    };
    this.deploy = function () {
        return "Can I to do a deploy?\n";
    };

}

E podemos usar da seguinte forma:

const {createJunior, createPleno, createSenior} = require('./prototype');
const {commit, codeReview, deploy} = require('./decorator');

const junior = createJunior("junior", "123");

console.log(commit(junior));
console.log(codeReview(junior));
console.log(deploy(junior));

const pleno = createPleno("pleno", "456");

console.log(commit(pleno));
console.log(codeReview(pleno));
console.log(deploy(pleno));

const senior = createSenior("senior", "789");

console.log(commit(senior));
console.log(codeReview(senior));
console.log(deploy(senior));

Executando esse código temos o resultado:

Can I to commit?
Developer Junior can committing

Can I to do code review?
Developer Junior can not make code review

Can I to do a deploy?
Junior can not deploy

Can I to commit?
Developer Pleno can committing

Can I to do code review?
Developer Pleno can make code review

Can I to do a deploy?
Pleno can not deploy

Can I to commit?
Developer Senior can committing

Can I to do code review?
Developer Senior can make code review

Can I to do a deploy?
Only Developers Senior can deploy

Memento

Agora veremos o padrão Memento, esse padrão comportamental nos permite salvar os estados dos nossos objetos, criando uma lista como um histórico das ações realizadas. No nosso cenário seria muito útil se pudéssemos ter um histórico de tudo o que cada desenvolvedor tentou fazer em nossa aplicação.

Para isso vamos precisar ter a representação do nosso Memento que é o nosso Snapshot, uma fotografia do nosso objeto naquele momento exato. Precisamos também da representação do objeto que é nosso Originador que salva e recupera os nossos Mementos e por fim a nossa classe “cuidadora” que é quem mantem os registros.

O código ficaria assim:

function Memento(state) {
    this.state = state;
    this.getState = function() {
        return this.state;
    }
}

function Originator() {
    this.state = null;
    
    this.add = function(state) {
        this.state = state;
    }
    this.save = function() {
        return new Memento(this.state);
    }
    this.restore = function(memento) {
        return memento.getState();
    }
}

function Historic() {
    this.states = [];

    this.originator = new Originator();
    
    this.add = function(state) {
        this.originator.add(state);
        this.states.push(this.originator.save());
    }
    this.getByIndexOrLast = function(i) {
        if (!this.states.length) {
            return;
        }

        if (!i && i !== 0) {
            i = this.states.length - 1;
        }

        return this.originator.restore(this.states[i]);
    }
    this.countSteps = function() {
        return this.states.length;
    }
    this.getStates = function() {
        return this.states;
    }

}

module.exports = {
    Historic: Historic
};

E aqui temos o nosso Memento que é somente a classe do nosso estado, a Originator que é quem produz e o Historic que é quem adiciona, recupera e lista os nossos estados.

Com isso podemos executar o seguinte código e poder recuperar o histórico de cada desenvolvedor:

const Historic = require('./memento').Historic;

let juniorHistoric = new Historic();
juniorHistoric.add("Created Junior\n");

juniorHistoric.add("Junior trying to commit\n");

juniorHistoric.add("Junior trying to do code review\n");

juniorHistoric.add("Junior trying to deploy\n");

juniorHistoric.getStates().forEach((memento) => {
    console.log(memento.state);
});

let plenoHistoric = new Historic();
plenoHistoric.add("Created Pleno\n");

plenoHistoric.add("Pleno trying to commit\n");

plenoHistoric.add("Pleno trying to do code review\n");

plenoHistoric.add("Pleno trying to deploy\n");

plenoHistoric.getStates().forEach((memento) => {
    console.log(memento.state);
});

let seniorHistoric = new Historic();
seniorHistoric.add("Created Senior\n");

seniorHistoric.add("Senior trying to commit\n");

seniorHistoric.add("Senior trying to do code review\n");

seniorHistoric.add("Senior trying to deploy\n");

seniorHistoric.getStates().forEach((memento) => {
    console.log(memento.state);
});

E temos a seguinte saída:

Created Junior

Junior trying to commit        

Junior trying to do code review

Junior trying to deploy        

Created Pleno

Pleno trying to commit

Pleno trying to do code review

Pleno trying to deploy

Created Senior

Senior trying to commit

Senior trying to do code review

Senior trying to deploy

Temos o histórico e podemos navegar nessa “linha do tempo”.

Código fonte

O código fonte pode ser encontrado aqui

Padrões de projeto com Python

Mon, 28 Sep 2020 00:00:01 GMT

Definição do projeto

Continuando essa série de posts sobre design patterns, já foi mostrado como usar em Java e Go e agora vamos mostrar como usar com Python também, vamos ver como padrões de projeto nos ajudam a ter um código limpo, reutilizável e de fácil manutenção e alterações caso necessário. Então vamos pensar no cenário, temos uma aplicação que vai salvar Notas Fiscais (Invoices), nesse caso vamos ter entrada de vários tipos diferentes de notas e precisamos processar diferentemente cada nota, precisamos descobrir então qual o tipo de nota está chegando e executar a lógica de cálculo de taxas, após isso precisamos salvar essa informação mas de antemão nós não sabemos onde isso será salvo, se vai ser em banco de dados ou em um bucket ou até mesmo um arquivo txt simples salvo na máquina e por fim recebemos a demanda de que para cada nota salva o departamento fiscal e o financeiro querem ser notificados disso.

Factory

Esse padrão está no grupo dos padrões criacionais e nos ajuda quando precisamos criar objetos baseados em uma superclasse, no nosso exemplo temos um domínio que seria a Nota Fiscal mas não sabemos que tipo de nota seria essa, será um ICMS, ISS ou outra que ainda nem definimos e que pode vir a aparecer por alguma exigência legal ou fiscal. (Não sei nada sobre notas fiscais pra dizer se ICMS é uma nota sozinha mas o exemplo aqui é para entender que existem notas diferentes mas no fim são todas Notas Fiscais). Então com essa ideia vamos criar o super tipo ou interface ou classe abstrata, isso vária um pouco de linguagem pra linguagem mas a ideia aqui é ter um “molde” para as nossas notas, vamos criar a classe Invoice:

from abc import ABC, abstractmethod


class Invoice(ABC):

    @abstractmethod
    def calculate_rate(self) -> str:
        pass

Aqui temos a nossa classe Invoice e ela é uma classe abstrata com um método não implementado chamado calculate_rate então aqui temos uma classe que nos obriga a implementar esse método para quem herdar dela. Vamos então criar as suas filhas que serão as classes InvoiceIcms e InvoiceIss:

from factory.invoice import Invoice


class InvoiceIss(Invoice):
    def calculate_rate(self) -> str:
        return "Processing Iss tax"

As duas seguem o mesmo modelo para o nosso exemplo, pra simplificar temos a classe que herda uma Invoice então essa classe é uma Invoice e a implementação do método calculate_rate. Então até aqui temos só o que seria a estrutura ainda nada referente a como iremos criar esses objetos, vamos então criar a nossa fábrica especializada em criar tipos Invoice e que saiba é uma InvoiceIcms ou uma InvoiceIss:

from factory.invoice import Invoice
from factory.invoice_iss import InvoiceIss
from factory.invoice_icms import InvoiceIcms


class InvoiceFactory:

    @staticmethod
    def create_invoice(name: str) -> Invoice:
        if name == "ICMS":
            return InvoiceIcms()
        else:
            return InvoiceIss()

A primeira vista uma factory desse tipo não parece ser algo tão vantajoso e que não tem nada de mais com o que vemos no nosso dia-a-dia mas para esses casos eu gosto de citar o que disse o Uncle Bob a respeito disso no livro Clean Code: “A solução é inserir a estrutura switch no fundo de uma ABSTRACT FACTORY e jamais deixar que alguém a veja. A factory usará o switch para criar instâncias apropriadas derivadas… Minha regra geral para estruturas switch é que são aceitáveis se aparecerem apenas uma vez, como criação de objetos polimórficos, e se estiverem escondidas, atrás de uma relação de herança de mode que o resto do sistema não possa enxergá-la.”

Como não temos switch em Python vamos usar a estrutura if/else. Por fim temos como criar os nossos objetos de uma forma mais centralizada e quem chama a factory não se preocupa com a forma que os objetos são criados mas se preocupam somente na ideia de usar os objetos criados:

invoice_icms = "ICMS"
invoice_iss = "ISS"


invoice = InvoiceFactory.create_invoice(invoice_icms)

print(invoice.calculate_rate())

invoice = InvoiceFactory.create_invoice(invoice_iss)

print(invoice.calculate_rate())

Agora temos a nossa Invoice certa sendo construída e o cálculo correto pra cada tipo.

Adapter

Agora vamos pensar na seguinte situação, temos o nosso cálculo sendo feito e o processamento acontecendo mas precisamos guardar esse dado em algum lugar, mas onde? Em um banco de dados, mas em qual? Enviar esse dado em um sistema de mensageria, mas qual? Kafka? RabbitMQ? Será que isso é algo devemos nos preocupar agora?

Pensando na ideia de implementação tardia, onde os detalhes serão pensados no futuro e que a nossa solução tem que ser pensada no negócio e não nas tecnologias envolvidas o padrão Adapter nos ajuda e muito com isso.

A ideia aqui é que eu exponha um contrato do que eu preciso que seja feito e posteriormente será implementada a solução, vamos começar a criar para exemplificar melhor:

from abc import ABC
from factory.invoice import Invoice


class Repository(ABC):
    def save(self, invoice: Invoice):
        pass

    def get_one(self, identity: int) -> str:
        pass

Aqui nós temos a nossa Repository que funciona como o nosso contrato declarando a assinatura dos nossos métodos sem implementação. Vamos então para a nossa implementação e aqui vamos supor que para o nosso desenvolvimento e testes somente salvando os dados em um .txt é o suficiente para nós, então criamos assim:

from adapter.repository import Repository
from factory.invoice import Invoice


class FileSystemStorage(Repository):

    def save(self, invoice: Invoice):
        print(f"Saving with class {type(invoice).__name__}")

    def get_one(self, identity: int) -> str:
        return f'FileSystemStorage#get_one'

Aqui é só um exemplo básico onde no método save eu exibo o nome da classe que foi passado e no get_one é devolvido uma string fixa, mas mesmo essa implementação é aderente ao contrato do nosso Adapter. Ainda vamos criar mais uma camada aqui só para emular o caso em que precisamos fazer alguma preparação pro nosso Repository:

from adapter.repository import Repository
from factory.invoice import Invoice


def save(repository: Repository, invoice: Invoice) -> None:
    print("Preparing to save")
    repository.save(invoice)


def get_one(repository: Repository, identity: int) -> str:
    print("Preparing to get from storage")
    repository.get_one(identity)

Pronto, com isso já podemos usar o nosso Adapter e a vantagem que temos é que conseguimos seguir o nosso desenvolvimento sem ficar acoplado ou preso a nenhuma tecnologia, se depois da nossa entrega for definido que vão usar o banco de dados X ou Y o trabalho que temos é criar outra classe que use esse banco de dados mas que implemente a nossa Repository e com isso fica transparente pra quem usa esses detalhes de implementação, aqui abaixo segue um exemplo caso usasse um banco de dados:

from adapter.repository import Repository
from factory.invoice import Invoice


class Database(Repository):

    def save(self, invoice: Invoice):
        print(f"Loading specifics configs for the Database X")
        print(f"Saving with class {type(invoice).__name__}")

    def get_one(self, identity: int) -> str:
        print(f"Loading specifics configs for the Database X")
        return f'Database#get_one'

E a utilização do nosso Adapter:

repository = Database()

save(repository, invoice)

get_one(repository, 1)

repository = FileSystemStorage()

save(repository, invoice)

get_one(repository, 1)

Observer

Agora já podemos criar as nossas Invoices dependendo da sua entrada e conseguimos salvar sem nos preocupar com os detalhes de implementação mas ainda falta o último requisito que é enviar para os departamentos interessados a notificação de que salvamos as Invoices. Podemos ao fim de cada método save fazer algo como:

sendEmail("dpt_financial")
sendEmail("dpt_fiscal")

E isso vai funcionar mas vamos pensar que entrou mais um departamento interessado na criação de Invoices ou então mudou a regra e agora cada pessoa desses departamentos irão receber e são 50 pessoas em cada departamento.

Vamos ficar entrando sempre no código e aumentar o método ou fazer um for em uma lista de emails ou departamentos? E se tivesse como eu me inscrever como interessado nesse assunto e toda vez que eu um save ocorrer eu seja notificado? Acredito que seria mais simples até mesmo caso onde eu não queira mais receber notificações eu só iria me desinscrever nesse assunto sem nenhum problema.

Esse seria o padrão Observer onde eu crio um objeto que fica literalmente observando e recebe notificações nos assuntos que eu me inscrevi.

Então vamos começar criando a nossa classe Observer que vai ser responsável por criar propriamente dito os observadores e que tem o método que diz o que deve acontecer quando uma notificação for enviada:

class EmailObserver:

    def __init__(self, email):
        self.__email = email

    def update(self, invoice):
        print(f'For {self.__email}, send report about {invoice}')

Aqui só temos o nosso inicializador que recebe o email e o método update que recebe o a Invoice para montar a mensagem. E agora vamos criar o nosso Subject que representa o nosso assunto a ser inscrito e que contém os métodos para se inscrever, desinscrever e notificar:

class EmailSubject:

    def __init__(self):
        self.__subscribers = []

    def add_email(self, subject):
        self.notify_subscribers(subject)

    def subscribe(self, subscriber):
        self.__subscribers.append(subscriber)

    def unsubscribe(self, subscriber):
        return self.__subscribers.remove(subscriber)

    def subscribers(self):
        return self.__subscribers

    def notify_subscribers(self, subject):
        for sub in self.__subscribers:
            sub.update(subject)

O estado interno dessa classe contém um array de subscribers onde eu adiciono um novo ou removo com os métodos subscribe e unsubscribe e o método para notificar todos os inscritos com notify_subscribers. E para fazer uso dele podemos fazer o seguinte:

fiscal = EmailObserver("dept_fiscal")
financial = EmailObserver("dept_financial")
subject.subscribe(fiscal)
subject.subscribe(financial)
subject.add_email("ICMS")

E com isso temos o ganho de inscrever somente uma vez e toda vez que o add_email for invocado irá notificar a todos.

Projeto completo

Segue abaixo o projeto completo e o projeto no Github:

from adapter.database import Database
from adapter.file_system_storage import FileSystemStorage
from adapter.adapter import save, get_one
from factory.factory import InvoiceFactory
from observer.email_observer import EmailObserver
from observer.email_subject import EmailSubject

invoice_icms = "ICMS"
invoice_iss = "ISS"

subject = EmailSubject()
fiscal = EmailObserver("dept_fiscal")
financial = EmailObserver("dept_financial")
subject.subscribe(fiscal)
subject.subscribe(financial)

invoice = InvoiceFactory.create_invoice(invoice_icms)

print(invoice.calculate_rate())

repository = Database()

save(repository, invoice)

subject.add_email(type(invoice).__name__)

get_one(repository, 1)

invoice = InvoiceFactory.create_invoice(invoice_iss)

print(invoice.calculate_rate())

repository = FileSystemStorage()

save(repository, invoice)

subject.add_email(type(invoice).__name__)

get_one(repository, 1)

Como me organizo para estudar?

Thu, 24 Sep 2020 20:20:03 GMT

Antes de começar esse artigo falando sobre como me organizo para estudar, preciso fazer um adendo aqui próceis.

A alguns dias eu venho lendo o livro “Use a cabeça - Javascript”, e fiquei me perguntando o porque não li ele assim que comecei a estudar. Ele ensina a linguagem de uma forma muito didática e é de fácil compreensão, recomendo a todos os iniciantes que desejam aprender JS. Apesar da linguagem abordada nele estar um pouco desatualizada, você consegue compreender muito bem a base.

Mas vamos ao que interessa, como eu me organizo para estudar? Vou listar aqui os métodos que utilizo e depois explicarei o caminho que percorri até chegar a algo que funcionasse para mim.

Basicamente eu uso tudo o que tem ao meu alcance:

Vídeo aulas;
Livros/Artigos/Fóruns;
Anotações

Até eu descobrir que TUDO isso funcionava para mim, bati um pouquinho a cabeça. No início, eu SÓ estudava por vídeo aula, achava que este era o único caminho para aprender já que não tinha o habito de ler e achava que não ia conseguir absorver nada. O que depois se mostrou ser uma grande bobagem.

Então eu fui alternando os dias. Em um dia, estudava um assunto por vídeo aula, no dia seguinte procurava artigos sobre o mesmo tema para ler, depois partia para os livros, escrevia os pontos principais daquele determinado assunto e pendurava no memory board (tá lotado o bichinho, preciso de um maior hehe). E aí repetia todo o processo.

E quais plataformas utilizei/utilizo para estudar? Os principais são estes:

Com todas essas informações disponíveis na mão, o meu maior desafio se tornou o horário que eu iria estudar pois além da Laboratória que era praticamente em período integral, eu tinha filho, marido e casa para cuidar, mas eu tive muito apoio dos meninos que compreenderam o meu momento e me ajudaram muito com os demais afazeres da casa. Então eu comecei a acordar cedinho, estudava até a hora do almoço, depois ia pra Lab e só parava depois das 18h. Foi bastante puxado mas essencial para que eu evoluísse conforme o bootcamp avançava.

Eu experimentei por um período estudar a noite, mas não gostei. Estava tão cansada do dia todo de trabalho que mal conseguia prestar atenção nas coisas. Para mim, estudar logo nas primeiras horas do dia é muito bom, pois estou descansada do dia anterior, com a mente tranquila. Produzo muito mais assim.

Bem, escolhido os métodos também utilizei alguns macetes que me ajudam a aproveitar este tempo com qualidade. São conselhos que eu considero valiosos para que sua experiência com os estudos seja o mais prazerosa possível. São eles:

Ambiente tranquilo e com boa iluminação

Estude em um ambiente com luz branca pois ela proporciona uma situação de atenção, de foco,melhor visibilidade, deixa o ambiente sempre mais em alerta. Já a amarela, traz uma certa sonolência porque remete ao aconchego, como se fosse um descanso para os olhos.

Música

(OPCIONAL) Para quem gosta, ouvir música enquanto lê um livro/artigo ajuda bastante. Inclusive estendo essa dica para as horas em que for codar. O ritmo vai do seu gosto, por aqui rola desde música clássica até pop dos anos 2000 (It’s Britney, bitch <3).

Pausa

Muito importante! Pois quando você estuda durante uma carga horária pesada, o cérebro acaba não entregando o seu maior potencial. As pausas são, portanto, momentos para você arejar o seu cérebro e conseguir aumentar a produtividade do seu estudo. Não pule esta etapa, ela é extremamente importante ;)

Constância

Não desistir na primeira dificuldade é crucial para sua evolução. Parece meio óbvio, mas muita gente desiste da programação na primeira dificuldade, e ela não demora a aparecer pois programar realmente não é algo fácil de se aprender. Mas eu posso te garantir que também não é impossível. Vá aos passinhos de tartaruga, mas não desista!

Pratique

Pratique, pratique e pratique, teoria é bom, mas a pratica é melhor ainda.

Alongue-se

Alongar antes e depois de terminar de estudar (sua lombar agradece!). A gente acaba não percebendo, mas passamos muito tempo sentados estudando e codando e nessas horas a nossa lombar, pulsos e cervical sofrem. Então antes de começar o dia, de aquela alongada, quando fizer a pausa, ande um pouco pela casa, e ao terminar o dia, dê aquela alongada caprichada antes de um banho relaxante! Acredite, você vai se sentir muito bem.

Beba água

Hidratem-se bichinhos, seus rins e pele merecem esse carinho. Conselhos de uma senhora que já teve muuuuuuuuita pedra no rim, tomem água! Se não tem esse habito, baixe aqueles apps que te lembrem de tomar. Vai te deixar hidratadinha(o) e sem pedrinhas, vocês não vão querer ter uma crise renal. Acreditem na tia, é pior que parto! E eu já tive os dois haha

Com tudo isso, cheguei a conclusão de que não existe um jeito correto para aprender, o que você pode fazer é ir tentando vários métodos até achar um que te satisfaça. Para mim, todos funcionam. E se eu puder te dar um conselho é: experimente todos eles só não desista!

Até o próximo post ;)

Padrões de projeto com GO

Fri, 18 Sep 2020 18:04:01 GMT

Padrões de projeto

São padrões já consagrados com técnicas que nos ajudam no dia-a-dia para solucionar alguns problemas em comum ou fazem com que a nossa aplicação seja mais fácil de mudar no futuro. Aqui vamos propor um exemplo onde eu tenho uma aplicação que recebe dados que representem uma pessoa, mas uma pessoa aqui pode ser tanto uma pessoa física quanto uma pessoa jurídica. Então temos que decidir qual é o tipo da pessoa que está sendo informada, executar algumas validações e depois salvar os dados em um banco de dados.

Builder

Vamos entender primeiramente o que é esse padrão e como ele nos ajudar aqui. O padrão Builder é um padrão para criação de objetos onde são informados os passos necessários para a sua criação. Vamos imaginar que recebemos os nossos dados no seguinte padrão:

{
    "name": "Pessoa",
    "document": "1234567890",
    "type": "PF"
}

Aqui temos uma representação mais ou menos do que seria uma entrada de dados e temos que montar o nosso objeto, conseguimos saber que é uma pessoa do tipo pessoa física pelo campo type então vamos começar criando nosso arquivo personBuilder.go:

package builder

type PersonBuilder interface {
	SetName(name string)
	SetDocument(document string)
	Build() Person
}

func GetBuilder(tyeName string) PersonBuilder {
	if tyeName == "PF" {
		return &NaturalPerson{
			Type: "PF",
		}
	}
	if tyeName == "PJ" {
		return &LegalPerson{
			Type: "PJ",
		}
	}
	return nil
}

Aqui definimos a nossa interface PersonBuilder com as funções para adicionar o nome, o documento e a função encarregada por realizar a construção. Temos também a função GetBuilder que recebe o type e decide qual é o tipo que deve ser criado, caso seja pessoa física retorna um NaturalPerson caso seja pessoa jurídica retorna um LegalPerson já com um atributo Type.

O que significa esses tipos NaturalPerson e LegalPerson e por que eles são considerados de um tipo PersonBuilder? Vamos ver o arquivo naturalPerson.go para entender:

package builder

type NaturalPerson struct {
	Name     string
	Document string
	Type     string
}

func (person *NaturalPerson) SetName(name string) {
	person.Name = name
}

func (person *NaturalPerson) SetDocument(document string) {
	person.Document = document
}

func (person *NaturalPerson) Build() Person {
	return Person{
		Name:     person.Name,
		Document: person.Document,
		Type:     person.Type,
	}
}

Uma coisa interessante no GO é a forma como ele implementa interfaces que é diferente de outras linguagens que são mais orientadas a objetos pois não fica explícito que estamos implementando uma interface e sim ocorre o que se chama Duck Typing que nada mais é do que: se o seu pacote, arquivo ou classe implementar os métodos de uma interface ele passa a ser daquele tipo. Isso segue a idéia de que se um animal anda como um pato, nada como um pato e voa como um pato então esse animal é um pato.

É o que vemos na NaturalPerson que implementa as funções que estão na interface PersonBuilder então concluímos que qualquer arquivo que implemente as funções de PersonBuilder é do mesmo tipo dele.

Podemos ver que a função Build retorna um Person e nessa função são atribuídos Name, Document e Type. Vamos ver esse arquivo:

package builder

type Person struct {
	Name               string
	Document           string
	Type               string
}

Person nada mais é do que uma struct, relativo ao que seria uma classe em outras linguagens, onde temos a representação do que é uma pessoa para a nossa aplicação.

Temos as peças soltas e agora vamos ver como juntar isso para fazer o nosso Builder funcionar:

	//Build a PersonBuilder, set values and build a NaturalPerson
	personBuilder := builder.GetBuilder("PF")

	personBuilder.SetName("John Doe")
	personBuilder.SetDocument("21368063004")
	naturalPerson := personBuilder.Build()

Aqui basicamente estamos passando como se fosse uma receita de como construir esse objeto e no fim chamamos a nossa função Build que vai construir o nosso objeto e devolvê-lo.

Chain of Responsibility

Então agora temos uma forma de construir os nossos objetos, mas vamos pensar que eu queira executar uma série de passos com esses objetos, sejam validações, transformações e etc. como podemos fazer isso?

Com Chain of Responsibility nós conseguimos criar uma cadeia de responsabilidades onde cada passo consegue processar e decide se passa pro próximo ou não. Aqui vamos supor que conseguimos criar o objeto e queremos persistir em um banco de dados mas antes disso vamos validar se os dados estão certos, por exemplo se o documento é um CPF ou CNPJ correto para aquele tipo de pessoa e etc.

Vamos executar esse processo em passos, vamos validar se o nome está preenchido e depois vamos validar se o CPF/CNPJ está no formato correto. Vamos criar a nossa interface Validation:

package chain

import (
	"github.com/guilhermegarcia86/go-patterns/builder"
)

//Validation interface has functions for Chain of Responsability Pattern
type Validation interface {
	Execute(builder.Person)
	SetNext(Validation)
}

Criamos a nossa interface e ela tem duas funções, uma pra executar a nossa lógica, Execute, que recebe um objeto do tipo Person e executa a nossa lógica e outra que vai chamar a próxima validação, SetNext.

Vamos então criar as nossas validações, primeiro com a ValidationType:

package chain

import (
	"log"

	"github.com/guilhermegarcia86/go-patterns/builder"
)

//ValidationType struct
type ValidationType struct {
	Next Validation
}

//Execute a function to implement the user type validation execution
func (validationType *ValidationType) Execute(user builder.Person) {

	if user.ValidationTypeDone {
		log.Println("Validation type already done " + user.Type)
		validationType.Next.Execute(user)
		return
	}

	log.Println("Validation type user starting " + user.Type)
	user.ValidationTypeDone = true
	log.Println("Execute next validation")
	validationType.Next.Execute(user)
}

//SetNext a function that set the next call
func (validationType *ValidationType) SetNext(next Validation) {
	validationType.Next = next
}

Aqui é somente uma prova de conceito onde poderíamos refinar e fazer tratativas de erros e outras validações mais efetivas, mas o importante aqui é que o nosso Execute recebe um objeto do tipo Person e verifica se validação já ocorreu com o atributo user.ValidationTypeDone e se já aconteceu chama o próximo, caso não tenha ocorrido a validação vai ser executada e chamará o próximo na cadeia.

Para poder ter esse controle de estado, se já executou a validação, precisamos atualizar a nossa Person:

type Person struct {
	Name               string
	Document           string
	Type               string
	ValidationNameDone bool
	ValidationTypeDone bool
}

Pronto temos os campos que controlam esse estado e eles são do tipo bool (booleanos). Uma coisa muito importante para esse padrão funcionar é que deve ser definido quem será o último elo dessa corrente e no nosso caso como estamos fazendo só duas validações isso ficará na ValidationName:

package chain

import (
	"log"

	"github.com/guilhermegarcia86/go-patterns/builder"
)

//ValidationName struct
type ValidationName struct {
	Next Validation
}

//Execute a function to implement the user name validation execution
func (validationName *ValidationName) Execute(user builder.Person) {

	if user.ValidationNameDone {
		log.Println("Validation name already done " + user.Name)
		validationName.Next.Execute(user)
		return
	}

	log.Println("Validation name user starting " + user.Name)
	user.ValidationNameDone = true
	log.Println("Validation finished")
}

//SetNext a function that set the next call
func (validationName *ValidationName) SetNext(next Validation) {
	validationName.Next = next
}

Agora vamos ver como seria o funcionamento das validações:

	//Begin a Validation chain
	validationName := &chain.ValidationName{}
	validationType := &chain.ValidationType{}

	validationType.SetNext(validationName)

	validationType.Execute(naturalPerson)

Proxy

Agora pensando que nós já temos o nosso objeto criado e que já validamos e tratamos ele, precisamos seguir o nosso fluxo proposto que seria salvar essa informação em algum lugar, porém essa tarefa pode se tornar muito custosa dependendo de como será implementada.

Por exemplo se formos salvar em um banco de dados temos todo o custo que é se conectar com o banco de dados, abrir uma transação, commitar e depois fechar, pensando em casos assim existe o padrão Proxy.

Mas antes de explorá-lo vamos entender alguns pontos, se abrir a conexão com um banco é tão difícil por que então eu não tento fazer um código mais performático pra abrir a conexão e fazer todo o resto?

A resposta é que nem sempre nós temos acesso ao código que vai ser executado, pensando nessa ideia de acesso ao banco de dados, geralmente temos bibliotecas prontas onde nós só fazemos as chamadas às suas funções sem que o código de como isso é feito seja exposto pra quem chamou. Porém se tivéssemos alguém que vai chamar uma vez o código “pesado” e vai guardar isso para nós e depois só usa a parte mais fácil sem chamar a parte pesada de novo, mas quem está chamando acha que está chamando o código pesado?

A ideia de proxy vem de alguém que seja representante de outra pessoa e é isso o que ele vai fazer aqui, vamos criar uma interface chamada Database:

package proxy

// Database interface to access
type Database interface {
	Access(url string, port string, user string, pass string) (string, error)
}

Aqui temos a definição de um acesso à um banco de dados onde são passado os dados de conexão, agora vamos criar o Proxy:

package proxy

import (
	"log"
	"time"
)

//Proxy struct
type Proxy struct {
	application *Application
	url         string
	port        string
	user        string
	pass        string
}

//OpenConnection a function that simulates a heavy call to create a database connection
func OpenConnection(url string, port string, user string, pass string) *Proxy {
	log.Println("A heavy process to create my connection with database")
	time.Sleep(2 * time.Second)
	return &Proxy{
		application: &Application{},
		url:         url,
		port:        port,
		user:        user,
		pass:        pass,
	}
}

//Access a function that receives params and verifies if has connection opened and do access
func (p *Proxy) Access(url string, port string, user string, pass string) (string, error) {

	if *p == (Proxy{}) {
		p = OpenConnection(url, port, user, pass)
	}

	msg, err := p.application.Access(url, port, user, pass)

	if err != nil {
		log.Fatalln("ERROR")
	}

	return msg, nil
}

Aqui é onde iríamos esconder a parte difícil da operação, temos a implementação de Access a função que irá abrir a conexão com o banco e a struct que irá controlar se a conexão já foi criada.

A fim de explicar esse conceito a função OpenConnection tem um Sleep que vai aguardar 2 segundos e depois vai chamar o que seria o nosso acesso através do trecho:

msg, err := p.application.Access(url, port, user, pass)

Então aqui podemos ver que quem usar o proxy tem a impressão de que está acessando a função real Access sendo que na verdade está passando pelo proxy.

E por fim o nosso Application que é a representação do que seria a biblioteca do terceiro:

package proxy

import (
	"fmt"
)

//Application struct
type Application struct {
}

//Access a function that will do the access
func (a *Application) Access(url string, port string, user string, pass string) (string, error) {

	return fmt.Sprintf("Success to connect database in url: %s port: %s user: %s", url, port, user), nil
}

E aqui temos a utilização completa do proxy:

const (
		url  = "urlDatabase"
		port = "3306"
		user = "user"
		pass = "pass"
	)

	//Open connection, heavy process
	conn := proxy.OpenConnection(url, port, user, pass)

	//Access database
	msgI, err := conn.Access(url, port, user, pass)
	if err != nil {
		log.Fatalln("ERROR ", err)
	}
	log.Println(msgI)

	//Do not open connection again
	msgII, err := conn.Access(url, port, user, pass)
	if err != nil {
		log.Fatal("ERROR ", err)
	}
	log.Println(msgII)

A parte interessante aqui é que executando esse código teremos duas chamadas para função Access porém só a primeira vai demorar 2 segundos pois na próxima chamada o proxy já guardou a conexão.

Código completo

Aqui temos a nossa main.go onde temos a entrada de dados, construímos os nossos objetos, fazemos as nossas validações e depois simulamos a abertura com o banco de dados e acessamos:

package main

import (
	"log"

	"github.com/guilhermegarcia86/go-patterns/builder"
	"github.com/guilhermegarcia86/go-patterns/chain"
	"github.com/guilhermegarcia86/go-patterns/proxy"
)

func main() {

	//Build a PersonBuilder, set values and build a NaturalPerson
	personBuilder := builder.GetBuilder("PF")

	personBuilder.SetName("John Doe")
	personBuilder.SetDocument("21368063004")
	naturalPerson := personBuilder.Build()

	//Build a PersonBuilder, set values and build a LegalPerson
	personBuilder = builder.GetBuilder("PJ")
	personBuilder.SetName("Cool Company")
	personBuilder.SetDocument("47902850000149")
	legalPerson := personBuilder.Build()

	//Begin a Validation chain
	validationName := &chain.ValidationName{}
	validationType := &chain.ValidationType{}

	validationType.SetNext(validationName)

	validationType.Execute(naturalPerson)

	validationType.Execute(legalPerson)

	const (
		url  = "urlDatabase"
		port = "3306"
		user = "user"
		pass = "pass"
	)

	//Open connection, heavy process
	conn := proxy.OpenConnection(url, port, user, pass)

	//Access database
	msgI, err := conn.Access(url, port, user, pass)
	if err != nil {
		log.Fatalln("ERROR ", err)
	}
	log.Println(msgI)

	//Do not open connection again
	msgII, err := conn.Access(url, port, user, pass)
	if err != nil {
		log.Fatal("ERROR ", err)
	}
	log.Println(msgII)

}

E temos a saída no console assim:

Validation type user starting PF
Execute next validation
Validation name user starting John Doe
Validation finished
Validation type user starting PJ
Execute next validation
Validation name user starting Cool Company
Validation finished
A heavy process to create my connection with database
Success to connect database in url: urlDatabase port: 3306 user: user
Success to connect database in url: urlDatabase port: 3306 user: user

O código completo pode ser encontrado aqui

Usando padrões de projeto em uma aplicação

Mon, 14 Sep 2020 18:04:01 GMT

Introdução Design Patterns

Padrões de projeto são formas mais padronizadas para solucionar problemas em comum…

Ok tentando ser mais claro; quando precisamos organizar o nosso código, deixá-lo flexível às mudanças, adaptável e reutilizável podemos seguir dois caminhos:

1°: Podemos fazer tudo na unha e criar a nossa própria forma de fazer as coisas e quem ver esse código que entenda ou leia alguma documentação se houver.
2°: Podemos usar um jeito que outras empresas já fizeram, testaram e validaram seus prós e contras.

Pensando assim nasceram os padrões de projeto (Design Patterns). A idéia de padrões de projetos não é nova (anos 70), já que na maioria das vezes os problemas são muito parecidos, mas em 1995 é que essa ideia se tornou mais tangível com o livro Design Patterns: Elements of Reusable Object-Oriented Software (Padrões de Projetos: Soluções Reutilizáveis de Software Orientados a Objetos) onde eram catálogados e descritos. Foram divididos em três grupos de padrões:

Criacionais (criação de objetos de forma eficiente, reutilizável e flexível)
Estruturais (como organizar a montagem de objetos para estruturas maiores)
Comportamentais (comunicação, responsabilidade e execução)

Com isso foram catálogados 23 padrões que ficaram conhecidos como padrões GoF, Gang of Four, uma referência aos criadores do livro, Erich Gamma, Richard Helm, Ralph Johnson e John Vlissides.

Projeto prático

Vamos fazer um projeto prático, a intenção aqui não será abordar todos os padrões mas sim como podemos analisar um problema e definir qual padrão poderia ser usado.

Problema

Vamos pensar que temos uma aplicação que recebe o nome de uma cerveja e a partir disso deve executar algo para cada tipo de cerveja. Como poderíamos resolver isso? Acho que a solução de primeira e mais simples poderia ser um if/else assim:

if(cerveja.getName() == "IPA"){
    //faça algo
}else {
    //faça outra coisa
}

Essa implementação parece ser razoável a primeira vista mas aqui temos um problema que pode ser considerado, e se amanhã surgir outro tipo de cerveja? Ou se eu tiver um catálogo com mais de 100 tipos de cervejas? Vou colocar mais um if ou então vou substituir por um block switch case? As duas abordagens na verdade mascaram o mesmo problema que é o problema de sua implementação poder crescer infinitamente. Isso gera um código gigante, difícil de dar manutenção e difícil de entender e ainda mais existe um princípio que esse tipo de implementação fere que é o princípio Open/Close (Aberto/Fechado) do S.O.L.I.D. que diz: “entidades de software (classes, módulos, funções, etc.) devem ser abertas para extensão, mas fechadas para modificação”. Trocando em miúdos isso quer dizer que você ter várias extensões de uma interface, classe e etc. sem mudar nada neles. Mas como trazer isso pro nosso caso?

Strategy

Aqui veremos o primeiro padrão de projeto que pode resolver essa situação. O padrão Strategy é um padrão comportamental, isso quer dizer que usando ele você pode definir comportamentos diferentes dependendo do que for passado, isso casa bem com o esse problema mas como implementar? A primeira coisa que vamos fazer é criar uma interface que represente pra nós a nossa ação, vou criar com o nome Beer:

package com.example.demo.beer;

public interface Beer {
	
	void drink();
	
	String label();

}

Então aqui temos o contrato (interface) do que eu quero que toda cerveja tenha, quero que ela tenha a ação de drink e que ela tenha um rótulo label, essa parte da label vai ficar mais claro daqui a pouco. E agora eu vou implementar as nossa cervejas vou criar três tipos aqui, IPA, ALE e STOUT todas vão seguir esse mesmo exemplo:

public class Ale implements Beer{

	@Override
	public void drink() {
		System.out.println("Drink a ale beer");
	}

	@Override
	public String label() {
		return "Ale";
	}

}

Com isso se eu já instânciar qualquer cerveja ele já vai ser capaz de chamar a implementação correta mais ou menos assim:

public class Test {

    public void callCorrectBeer(){
        Beer beer = new Ale();
        beer.drink();
    }
}

Isso já ajuda bastante por que imaginando que eu tenho um dado de entrada para a minha aplicação eu poderia fazer algo assim:

public class Main {

    public static void main(String... args){
        //dado de entrada
        String beerAle = "Ale";
        
        Beer beer = //de alguma forma eu descobrir que se trata de uma Ale
        beer.drink();
    }
}

Se eu mudar o tipo pra STOUT por exemplo o que mudaria é comportamento mas fica transparente pra quem está chamando.

Factory

Precisamos agora ter um jeito de saber qual é a cerveja que eu quero criar para chamar a nossa Strategy certa. Um jeito é tendo uma classe que tenha como especialidade criar instâncias de Beer corretas, é um factory (fábrica) que irá se preocupar em criar as instâncias corretas pra nós. Esse padrão entra como sendo um padrão criacional, a única preocupação dele é criar objetos de forma correta pra gente, vamos fazer com que seja o mais genérico possível, então antes vamos criar uma interface que vai ser responsável por criar objetos pra gente se baseando no tipo que vamos passar pra ele:

package com.example.demo.beer.factory;

public interface AbstractFactory<T> {
	
	T create(String type);

}

Aqui usamos o recurso de Generics do Java pra deixar o mais genérico possível, então a nossa interface receberá o tipo terá o método create que devolve pra gente esse tipo definido. E agora vamos fazer a implementação dessa factory:

public class FactoryBeer implements AbstractFactory<Beer> {
	
	@Override
	public Beer create(String type) {

        if(type == "Ale"){
            return new Ale();
        }if else(type == "Stout"){
            return new Stout();
        }else {
            return Ipa();
        }
	}
}

Aqui pode parecer que demos uma grande volta pra cair num if/else de novo mas na verdade estamos deixando em um único ponto, que é na nossa classe especializada em fabricar objetos, mas podemos melhorar isso, nesse projeto eu uso Spring Boot e ele trabalha com o conceito de IoC (Inversão de Controle) e nos fornece uma interface que é a ApplicationContext que gerencia os nossos Beans, pra não entrar muito dentro dos detalhes a grosso modo tudo o que usar as annotations @Bean, @Component, @Controller, @Service, @Repository, @Autowired, e @Qualifier serão objetos que o Spring vai gerenciar e ele é que vai decidir quando eles estarão disponíveis pra uso. Então depois de toda essa explicação é pra dizer que podemos então delegar essa responsabilidade pro ApplicationContext pra gente assim:

@Component
public class FactoryBeer implements AbstractFactory<Beer> {
	
	@Autowired
	private ApplicationContext context;

	@Override
	public Beer create(String type) {
		
		return context.getBean(type);
	}

}

O que muda aqui é que adicionamos a anotação @Component e isso faz com que automaticamente o Spring comece a gerenciar a injeção das nossas dependências, injetamos com a anotação @Autowired a nossa interface ApplicationContext e no nosso método chamamos o getBean e ele vai trazer pra gente a instância certa. Só tem um problema aqui, caso seja passada uma String type errada que não exista ele vai lançar uma BeansException, inclusive o próprio método getBean faz parte da API da interface BeanFactory que é fábrica de Beans do Spring. Vamos então criar um jeito onde eu passe um tipo que existe e ele irá chamar o tipo existente, vamos criar uma enumeração Enum onde conseguimos registrar as nossas classes de serviço e um método de busca:

public enum BeerType {
	
	ALE("Ale", Ale.class),
	IPA("Ipa", Ipa.class),
	STOUT("Stout", Stout.class);
	
	private String name;
	private Class<? extends Beer> type;
	
	BeerType(String name, Class<? extends Beer> type){
		this.name = name;
		this.type = type;
	}
	
    public static BeerType of(String value) {

        return Arrays.stream(values()).filter(type -> type.name.equalsIgnoreCase(value)).findFirst().get();
    }
	
	public String getName() {
		return name;
	}
	
	public Class<? extends Beer> getType(){
		return type;
	}

}

Um ponto muito importante é que as nossas três classes de serviço devem ser anotadas com algumas das anotações citadas anteriormente para gerenciamento do Spring, no caso iremos anotar com @Component para ficar mais semântico. Então o resultado final da nossa factory ficaria assim:

@Component
public class FactoryBeer implements AbstractFactory<Beer> {
	
	@Autowired
	private ApplicationContext context;

	@Override
	public Beer create(String type) {
		
		return context.getBean(BeerType.of(type).getType());
	}

}

Service

Agora vamos criar a classe que vai amarrar tudo pra gente:

@Service
public class BeerService {
	
	@Autowired
	private AbstractFactory<Beer> factory;
	
	public void process(String beer) {
		Beer beerBean = factory.create(beer);
		beerBean.drink();
	}

}

Ela é só a chamada dos serviços, injetamos a nossa factory do tipo Beer e chamamos o seu create passando o tipo como parâmetro e depois chamamos o método drink.

Rodando a aplicação

Rodando a nossa aplicação na nossa main:

@SpringBootApplication
public class DemoApplication implements CommandLineRunner{
	
	@Autowired
	private BeerService service;

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

	@Override
	public void run(String... args) throws Exception {
		
		service.process(BeerType.ALE.getName());
		service.process(BeerType.IPA.getName());
		service.process(BeerType.STOUT.getName());
	}

}

Temos a saída:

Drink a ale beer
Drink a ipa beer
Drink a stout beer

Finalizando

A decisão de usar design patterns e quais usar não é uma escolha tão fácil, leva tempo pra saber qual é o melhor caso e como combinar padrões, como por exemplo nesse projeto não foi usado explícitamente nenhum padrão estrutural mas a finalidade dos design patterns é facilitar e padronizar os nossos códigos pensando em reutilização, refatoração, manutenção e flexibilidade. Vimos aqui alguns padrões que podem ser usados, como pôde ser visto nós temos um maior custo de desenvolvimento para criar o código da nossa aplicação porém o custo ao longo do tempo compensa pois nesse código temos maior flexibilidade caso surja uma regra nova ou precisarmos trocar alguma implementação do que já existe, então temos um código reutilizável, com menor custo de manutenção e como estamos usando um padrão de mercado caso algum dia outro desenvolvedor ou equipe precise dar suporte ou fazer alguma coisa nova não perderá tanto tempo se eles souberem os padrões ficará mais fácil o entendimento do código. Aqui temos o GitHub do projeto.

Comunicação assíncrona com Feign

Tue, 08 Sep 2020 20:47:01 GMT

Muitas vezes precisamos fazer comunicação com outros serviços externos, seja um GET, um POST ou etc. e por diversas vezes podemos fazer esse processamento de forma assíncrona, sem precisar esperar pela resposta. E se ocorre uma falha nessa requisição HTTP o que fazer? As vezes a resposta pode ser simples as vezes não, mas seria bom poder ter uma forma de poder retentar fazer essa chamada ou então guardar isso para poder fazer essa requisição mais tarde. Vamos fazer uma requisição para buscar no site do Correios e ver aqui uma alternativa a isso usando Feign para fazer as chamadas assíncronas e primeira retentativa e o mecanismo de Scheduling que o Spring nos provê para fazer o agendamento de requisições que falharam. Para esse projeto estou usando Spring Boot e com Gradle para gerenciar as dependências.

Client

Vamos começar com o nosso client que irá fazer a buscar:

@FeignClient(name = "cepClient", url = "${externalUrl}")
public interface CepClient {

    @GetMapping(value = "/v1/cep/{cep}")
    Cep get(@PathVariable("cep") String cep);
}

Aqui usamos o FeignClient e criamos uma interface onde temos um método chamado get que anotamos com um @GetMapping com o path do CEP. A nossa interface é anotada com o @FeignClient onde passamos um name para ele e a url que está no nossa arquivo de properties. E mapeamos o retorno com o objeto Cep que contém as informações:

@Data
public class Cep {

    private String logradouro;
    private String bairro;
    private String cidade;
    private String estado;

}

Até aqui se usarmos esse client teremos uma requisição HTTP do tipo GET síncrona e para deixar ela de forma assíncrona devemos fazer a nossa configuração:

@Configuration
@EnableAsync
public class ThreadPoolTaskAsyncConfig {

    @Bean(name = "threadPoolTaskAsyncExecutor")
    public Executor threadPoolTaskExecutor() {
        ThreadPoolTaskExecutor threadPoolTaskExecutor = new ThreadPoolTaskExecutor();
        threadPoolTaskExecutor.setMaxPoolSize(50);
        threadPoolTaskExecutor.setCorePoolSize(50);
        threadPoolTaskExecutor.setQueueCapacity(50);
        return threadPoolTaskExecutor;
    }

}

Aqui criamos a nossa classe de configuração com a anotação @Configuration e também adicionamos a @EnableAsync que nos permite fazer essa comunicação assíncrona. Temos o nosso @Bean nomeado threadPoolTaskAsyncExecutor e nele definimos um novo ThreadPoolTaskExecutor e configuramos para que tenha uma capacidade de processar até 50 threads, se por acaso tiver um número maior o processo fica em espera. Com isso temos o serviço podendo ser usado de forma assíncrona mas vamos ver agora como podemos tratar eventuais falhas quando formos fazer esse GET, caso a API esteja fora por exemplo, como podemos resolver isso? Por padrão o Feign lida com nas requisições com a interface Retryer então podemos implementar essa interface:

@Slf4j
@Component
@NoArgsConstructor
public class CustomRetryer implements Retryer {

    @Value("${retryMaxAttempt}")
    private int retryMaxAttempt;

    @Value("${retryInterval}")
    private long retryInterval;

    private int attempt = 1;

    public CustomRetryer(int retryMaxAttempt, Long retryInterval) {
        this.retryMaxAttempt = retryMaxAttempt;
        this.retryInterval = retryInterval;
    }

    @Override
    public void continueOrPropagate(RetryableException e) {
        log.info("Feign retry attempt {} due to {} ", attempt, e.getMessage());

        if(attempt++ == retryMaxAttempt){
            throw e;
        }
        try {
            Thread.sleep(retryInterval);
        } catch (InterruptedException ignored) {
            Thread.currentThread().interrupt();
        }

    }

    @Override
    public Retryer clone() {
        return new CustomRetryer(retryMaxAttempt, retryInterval);
    }
}

Explicando o código acima. Implementando essa interface Retryer temos os métodos clone e continueOrPropagate, no nosso clone instanciamos o nosso CustomRetryer onde passamos a quantidade máxima de tentativas para o retry e o intervalo para cada solicitação. No continueOrPropagate recebemos a Exception e checamos se já estouramos o limite de retentativas e caso seja isso propagamos a Exception caso não esperamos o tempo que configuramos e Feign irá fazer o retry. O último detalhe que falta é que precisamos da anotação @EnableFeignClients que podemos colocar junto da nossa classe main:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.openfeign.EnableFeignClients;

import java.util.Optional;

@SpringBootApplication
@EnableFeignClients
public class DemoApplication {


	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}
}

Service

Com o nosso client criado vamos fazer a nossa camada de serviço que é quem irá fazer uso o do client de forma assíncrona, vamos começar criando a classe ConsultService:

@Service
public class ConsultService {

    @Autowired
    private CepClient client;

    public Optional<Cep> consultCep(String cep){

        try {
            Cep cepResponse = this.getByCep(cep).get();

            return Optional.of(cepResponse);

        }catch (RetryableException | InterruptedException | ExecutionException e){
            //TODO
        }

        return Optional.empty();
    }

    @Async("threadPoolTaskAsyncExecutor")
    public CompletableFuture<Cep> getByCep(String cep){
        return CompletableFuture.completedFuture(client.get(cep));
    }

}

O ponto a ser observado é o método getByCep que faz a chamada ao client usamos a anotação @Async(“threadPoolTaskAsyncExecutor”) referenciando o nosso Bean que configuramos anteriormente e isso já nos permite fazer a chamada de forma assíncrona. O método getByCep está envolto em um bloco try/catch que o nosso CustomRetryer captura em caso de excessão e faz as retentativas.

Schedule

Até agora temos as nossas chamadas de forma assíncrona e um mecanismo de retentativas mas pense na seguinte situação e se a url estiver fora do ar? Não é uma situação que conseguimos resolver mas acreditamos que esse serviço eventualmente será reestabelecido então podemos guardar em algum lugar essa informação que deu errado e depois tentamos fazer a requisição. O Java já nos provê mecanismos para isso e o framework Spring Boot facilita aida mais esse processo, então vamos comçar criando a nossa classe de configuração para o serviço agendado (schedule):

package com.example.demo.config;

import com.example.demo.service.ScheduleService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;

@Configuration
@ComponentScan(basePackages = "com.example.demo.service", basePackageClasses = {ScheduleService.class})
public class ThreadPoolTaskSchedulerConfig {

    @Bean
    public ThreadPoolTaskScheduler threadPoolTaskScheduler() {
        ThreadPoolTaskScheduler threadPoolTaskScheduler = new ThreadPoolTaskScheduler();
        threadPoolTaskScheduler.setPoolSize(5);
        threadPoolTaskScheduler.setThreadNamePrefix("ScheduleService");
        return threadPoolTaskScheduler;
    }
}

Aqui temos o código onde temos a classe de configuração anotada com Configuration e adicionado o caminho do pacote e a classe que irá fazer o agendamento que ainda não criamos. No nosso Bean criamos uma instância de ThreadPoolTaskScheduler com um pool de 5 threads e nomeamos com o prefixo ScheduleService. Antes de continuar com as próximas configurações de schedule vamos fazer o mecanismo onde guardamos os dados das requisições que falharam e que deverão ser reprocessadas, vamos usar para fins de exemplo um banco de dados em memória, H2, e Spring Data para fazer o gerenciamento do banco. Vamos começar criando a nossa model que iserá a representação da nossa tabela de banco de dados:

@Data
@Entity
@NoArgsConstructor
public class Response {

    @Id
    private String cep;
    private Date create_at;
    private Date update_at;
    private String logradouro;
    private String bairro;
    private String cidade;
    private String estado;
    private boolean success;

}

O campo que usaremos para fazer o nosso controle é o success que é um booleano. Vamos criar agora a nossa interface de comunicação que extende da interface JpaRepository:

@Repository
public interface ResponseRepository extends JpaRepository<Response, Integer> {

    Optional<List<Response>> findAllBySuccessIsFalse();

    Optional<Response> findByCep(String cep);
}

Com essa herança de interface passamos a ter os métodos de gerenciamento que o JpaRepository nos dá mas ainda precisamos adicionar mais alguns um pouco mais específicos, graças ao Spring Data podemos fazer nossas querys usando query methods onde definimos a nossa busca, nesse caso, pela nomenclatura do método mais explicações estão aqui Query Methods. Vamos criar nossa classe de serviço agendado:

@Component("scheduleService")
public class ScheduleService {

    @Value("${cronTimer.reprocess}")
    private String reprocess;

    @Autowired
    private ThreadPoolTaskScheduler taskScheduler;

    @Autowired
    private ResponseRepository repository;

    @Autowired
    private ConsultService consultService;

    @PostConstruct
    public void init() {
        taskScheduler.schedule(() -> {
            repository.findAllBySuccessIsFalse().ifPresent(cepList -> cepList.forEach(cep -> consultService.consultCep(cep.getCep())));
        }, new CronTrigger(reprocess));
    }
}

Explicando o código acima temos nossa classe que é um Component do Spring e nele injetamos o nosso Scheduler, Repository e Service ainda temos a variável reprocess onde definimos uma expressão Cron: 0 */1 * * * * (Para saber mais sobre Cron Expressions)

Onde ele vai rodar a cada minuto a nossa taskScheduler e faz uma busca na nossa repository todos os registros onde o campo success for false e vai chamar a nossa service. Para finalizar a nossa única alteração será na nossa service onde vamos começar a salvar os registros das nossas requisições e no campo success definimos se foi sucesso true ou falha false:

@Service
public class ConsultService {

    @Autowired
    private CepClient client;

    @Autowired
    private ResponseRepository repository;

    public Optional<Cep> consultCep(String cep){

        try {
            Cep cepResponse = this.getByCep(cep).get();

            Response response = new Response();
            response.setCep(cep);
            response.setCreate_at(new Date());
            response.setLogradouro(cepResponse.getLogradouro());
            response.setBairro(cepResponse.getBairro());
            response.setCidade(cepResponse.getCidade());
            response.setEstado(cepResponse.getEstado());

            repository.save(response);

            return Optional.of(cepResponse);

        }catch (RetryableException | InterruptedException | ExecutionException e){

            Optional<Response> repositoryById = repository.findByCep(cep);
            Response response;

            if(repositoryById.isPresent()){
                response = repositoryById.get();
                response.setUpdate_at(new Date());
            }else {
                response = new Response();
                response.setCep(cep);
                response.setCreate_at(new Date());

            }

            repository.save(response);
        }

        return Optional.empty();
    }

    @Async("threadPoolTaskAsyncExecutor")
    public CompletableFuture<Cep> getByCep(String cep){
        return CompletableFuture.completedFuture(client.get(cep));
    }

}

Então aqui temos a nossa chamada assíncrona onde caso dê algum erro o nosso CustomRetryer vai tentar algumas vezes e após isso vai salvar como falha para ser processado posteriormente e caso dê certo nós gravamos como um registro de sucesso.

Executando o serviço

Agora vamos rodar tudo junto, pra isso vou usar a interface CommandLineRunner para ser executada no momento em que aplicação subir:

@SpringBootApplication
@EnableFeignClients
@EnableScheduling
public class DemoApplication implements CommandLineRunner {

	@Autowired
	private ConsultService service;

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

	@Override
	public void run(String... args) throws Exception {
		Optional<Cep> cep = service.consultCep("01032000");
		cep.ifPresent(System.out::println);
	}
}

Coloquei na classe main mesmo; então no momento da execução ele irá fazer a busca com o CEP informado.

Conclusão

Vimos aqui uma dentre outras mil formas que podemos pensar em fazer chamadas HTTP com um client de forma assíncrona, pensando em possíveis cenários de falha e com uma tentativa de reprocessamento agendado. Segue o link do projeto no GitHub

Minha experiência com a Laboratória

Tue, 08 Sep 2020 18:08:03 GMT

Minha história com a Laboratória começou em Abril de 2019, onde fiz a minha primeira inscrição para o Bootcamp da turma 003. Como já relatei no meu post anterior, desisti por achar que não conseguiria uma chance de entrar para a turma, mas voltei a me inscrever em Outubro do mesmo ano decidida a encarar o desafio mesmo com o maior medo do mundo.

Para minha surpresa, consegui passar em todas as etapas online, e após mais ou menos dois meses, fui chamada para a entrevista pessoal, que é um bate papo, onde pude conhecer mais sobre a Lab e eles sobre mim. A entrevista foi bem tranquila, apesar de todo o meu nervosismo, afinal faziam pelo menos uns 9 anos que eu não sabia mais o que era uma entrevista.

Ficaram de me dar o retorno indepedente de passar ou não para a última fase. Nem preciso dizer que já fiquei esperando pelo pior, porque tinha certeza absoluta que não tinha passado da entrevista (enfiou a confiança aonde minha filha???). Segui a minha vida normalmente, até que no dia 05/02/20 recebi o e-mail informando que tinha sido selecionada para a pré-admissão, a última fase antes de ingressar de fato no bootcamp.

A pré-admissão rolou no inicio de Março/20. Eu estava meio sem saber o que esperar mas quando cheguei lá pude perceber que teríamos uma mini vivencia de como seria o bootcamp. Foram três dias de pré admissão, passei mal em todos eles de tão ansiosa, não consegui dar nem 50% de mim por conta das dores de cabeça, febrões e idas constantes ao banheiro para “chamar o hugo” (Aloww ansiedade!!!). No último dia, saí decidida a não tentar mais caso eu não passasse, porém para a minha surpresa, no dia 09/03 recebi o e-mail dizendo que eu tinha sido aprovada para a turma 004 (tapão na cara da sindrome da impostora pliiis!!!), eu estava no meio da aula de inglês, e simplesmente não consegui mais continuar tamanha era a minha emoção. Eu sabia que seria algo que mudaria toda a minha vida.

E mudou!

Conheci tanta, mas tanta mulher incrível que eu poderia dedicar outro post somente a elas! Jamais pensei que em um ambiente só de mulheres houvesse tanta empatia e zero competitividade! Todas elas mudaram a minha vida, eu me desconstruí todo santo dia, com certeza sou uma pessoa melhor depois da Lab. Eu pude presenciar o PODER que uma união de mulheres pode fazer! Era lindo ver o quanto todas estavam dispostas a evoluir juntas. Eu realmente poderia ficar o dia todinho exaltando essas mulheres incríveis para vocês.

Entrando um pouquinho no nosso dia a dia, aprendemos a trabalhar em squads que sempre trocava a cada final de projeto, fazíamos todas as cerimonias da metodologia ágil Scrum, e a cada projeto, avançávamos um pouco mais sobre tudo o que precisávamos saber para nos tornarmos Frontends Jr. Fizemos projetos incríveis, era lindo ver a evolução de cada um deles.

Por falar em evolução, eu digo que a Lab me ajudou a confiar mais em mim mesma, a ser protagonista da minha vida e a procurar evoluir sempre. Além do amparo técnico, não só eu mas todas tivemos amparo sócio emocional, e eu tenho certeza de que foi essencial para nós, principalmente em época de pandemia e isolamento social. Infelizmente não tivemos o prazer de fazer o bootcamp presencialmente por conta da Covid, na semana em que iríamos começar, foi decretado o isolamento social. Foi mega desafiador, tanto para nós alunas, como para a Lab enquanto organização. Tivemos que nos adaptar juntos e de certa forma creio que isto nos uniu mais. Com certeza a nossa turma será lembrada, não só porque fizemos coisas incríveis, mas porque encaramos todos os desafios juntos.

Outra coisa muito importante que aprendi na Lab foi a desenvolver minhas softskills, eu pude perceber a importância do trabalho em equipe, dos frutos que uma boa comunicação pode causar na equipe e também o quanto uma escuta ativa pode evitar atritos desnecessários. Hoje vejo que sem essas habilidades, é praticamente impossível manter um ambiente de trabalho saudável e produtivo.

O que mais posso falar da Lab? Ahhh, sim… dos nossos queridos Mentores! Pessoas incríveis que estavam sempre dispostas a nos ajudar, sempre nos dando feedbacks construtivos. A Lab sempre nos disse que o feedback é um presente, e eu concordo! Não fossem eles, eu jamais saberia onde poderia melhorar, cresci muito por conta disso e com certeza irei valorizar o feedback em qualquer empresa que for trabalhar.

Por fim, vou falar um pouquinho sobre a questão de empregabilidade, ao final do bootcamp temos o Talent Fest que é um hackathon organizado pela Laboratória para conectar as alunas formadas no bootcamp com empresas parceiras que buscam talentos, e quem sabe rolar a tão sonhada contratação! Essa fase tão esperada por todas nós acontece sempre após o encerramento do bootcamp. Apesar de ansiosas, ficamos muito seguras, pois são empresas incríveis e é praticamente impossível não dar match com todas.

Bom, num balanço geral, esta foi a minha experiência com a Lab, foram meses intensos, por muitas vezes estressante, afinal aprender uma nova profissão do zero não foi fácil, mas passar por todas as etapas, ver a minha evolução, e os frutos que consegui colher me dá a certeza de que todo esforço valeu a pena.

Quer saber um pouquinho mais sobre a Lab e seu processo seletivo? Acesse o site da Laboratória ou então acesse através das Redes Sociais: Instagram e Facebook

Até o próximo post ;)

Experimentando o jamstack da Vercel

Sat, 05 Sep 2020 18:30:00 GMT

Criando uma simples aplicação com jamstack da Vercel com um encurtador de URLs

Vamos ver na prática o uso dessa nova stack web

Ultimamente tenho visto em muitos lugares os seguintes nomes: jamstack, Netlify e Vercel. Como a curiosidade procurei alguns canais e blogs para saber mais a respeito.

Sendo breve o termo jamstack foi criado por Matt Biilmann (CEO da Netlify) onde ele diz ”A modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup”

Javascript
- Funcionalidades dinâmicas tratadas pelo javascript, sem restrições de framework ou bibliotecas.
APIs
- Operações executadas no servidor para serem reutilizáveis e acessadas por HTTPS podendo ser de terceiros ou a sua própria função customizada.
Markup
- Websites entregues tanto em HTML estáticos, podendo ser gerados dos seus arquivos fonte, Markdown e geradores de site estáticos.

Tanto Netlify quanto Vercel, oferecem um rápido ambiente de desenvolvimento e infraestrutura para deploy de projetos em poucos passos. Sem a necessidade configurações de servidores, sem uma complexa esteira de devops e tudo isso a baixo custo.

Resultando em sites mais rápidos, melhoria na experiência do usuário e também na classificação do Google.

Alguns exemplos em ambas plataformas:

O Projeto Chiwawer 🐶

Com base no git flow podemos entregar sites rapidamente e globalmente. 🙌

Como exemplo, me aventurei criando um encurtador de URLs utilizando javascript, mongodb e VueJS para uma simples interface.

Cadastrando uma URL e associando um “apelido” (alias) que servirá como o identificador para a aplicação realizar o redirect.

Links:

Site
Github

Aqui vemos uma estrutura básica do projeto:

Vamos aproveitar e focar na estrutura das pastas de API , pela documentação do Vercel, para criarmos nossa camada de REST, basta incluir nossos arquivos diretamente na pas API. Dentro da pasta API, criamos o arquivo index.js ele será a chamada raiz do nosso REST e cada arquivo funcionará com um serviço servless.

Como por exemplo fazendo um GET em https://chiwawer.vercel.app/api o index.js irá responder com uma mensagem como na imagem abaixo.

Então para estruturar a sua camada de API, as pastas serão os paths, a pasta URLS será associada ao path /urls e quem irá responder será o index.js pertencente a ela.

E como ficam a passagem de parâmetros?

Nos nossos arquivos js podemos pegar os parâmetros de algumas formas:

Query Parameters
Body Parameters
Path Segments

Query Parameters e Body Parameters

module.exports = (req, res) => {
  res.json({
    body: req.body,
    query: req.query,
    cookies: req.cookies,
  });
};

No arquivo index.js da nossa API, podemos receber os parâmetros req e res manipularmos conforme a nossa necessidade. Dentro do objeto req temos os objetos body e query são respectivos das chamadas REST, sendo uma query parameter https://.../api?name=Leo e assim temos o valor name = "Leo" e para o body, em um POST por exemplo, podemos ter { "sobrenome" : "Yassuda" } .

Aqui contém um exemplo na prática, teste também fazendo um POST passando um body json para ver o resultado.

Path Segment

Passando parametros pelo path da API exige um passo a mais mas nada complicado.

https://.../api/name/Leo - Request de exemplo.

Para receber esse valor, basta criar a estrura de pastas /api/name/ e nela o nosso js com o nome [name].js e sim, o arquivo tem nome entre colchetes pois na abstração de roteamento da vercel saberá encaminha a requisição para este arquivo.

E no arquivo:

module.exports = (req, res) => {
  const {
    query: { name },
  } = req;

  res.send(`Hello ${name}!`);
};

Aqui um link para o teste prático.

Site

Para o front utilizei uma simples app em VueJs com as CDNs diretamente no HTML.

Toda estrutura do VueJs e arquivos estáticos deverão ser alocadas na pasta public.

Sem dores de cabeça e gastos com SSL para o seu site, por de baixo dos panos a Vercel usa o Let’s Encrypt para adicionar o certificados aos sites e com renovação automática. Portanto desde o primeiro dia em produção com HTTPS habilitado. 😎

Github + Vercel

Para linkar seu repo com a conta na Vercel, vá em import

Insira a url do seu repo, nas próximas etapas de projeto é onde feita a configuração do framework usado, build e a localização da pasta do código.

Nas variáveis de ambiente, podemos configurar informações para o usa na aplicação como a conexão do mongoDB e node_env.

Feito deploy, já é possível acessar o dashboard com o projeto em execução.

Ao acessar o projeto já temos uma pré-visualização do deploy.

Como o projeto está associado ao repo do github, a cada atualização na branch master, automaticamente será feito o build e deploy em produção.

Um bom jeito para o desenvolvimento é seguir um git flow e fazendo os pull request, a cada pull request é possível realizar testes do que foi alterado um uma url pertencente a essa etapa do flow. Após essa verificação e realizando merge em master, o procedimento de produção será inciado.

Para os detalhes do projeto, visite o repo no github 😊

👉 chiwawer 🐶

Como decidi virar Desenvolvedora

Wed, 02 Sep 2020 21:09:03 GMT

Quem me vê toda feliz falando sobre ser Dev, nem imagina o tanto de vez que já quis desistir no caminho.

Mas bem, comecemos pelo começo…

Eu trabalhei com Turismo quase que a minha vida profissional inteira, tinha na cabeça que me aposentaria nessa profissão e que ficar naquela empresa até o fim dos meus dias era o certo.

Aí você deve estar se perguntando: “Tá Kelly, mas se você estava tão bem na sua empresa, porque decidiu migrar de área?“. Você vai descobrir logo mais, prometo 🙃

A minha curiosidade pela programação começou quando o maridão começou a trabalhar como desenvolvedor. Eu achava muito dahora ver ele colocando um monte de palavra esquisita numa tela preta, ficava admirando ele me contar o que fazia no dia a dia com aqueles termos técnicos. Queria aprender, mas não tinha coragem, de cara já falava que não era pra mim (olha a síndrome da impostora aí) enfim, arrumava milhões de desculpas para sequer tentar.

Passados uns anos, as coisas na empresa que eu trabalhava já não eram as mesmas, eu já não tinha mais aquele brilho nos olhos, fazia absolutamente a mesma coisa o dia todo. Sentia falta do desafio, de aprender coisas novas. E então eu decidi pedir as contas e ir atrás de algo em que me fizesse sentir útil de novo. Engana-se quem pensou que fui correndo pra tecnologia, eu tinha acabado de concluir a Pós Graduação em Comunicação e Mídias Sociais, então fiz mais alguns cursos de especialização na área e fui atrás de um trampo, mas em vão. Cheguei a mandar uns 30 currículos, estou esperando “retorno” até hoje (risos).

Preciso nem dizer que fiquei muito mal, me questionando se tinha feito a coisa certa em pedir as contas depois de quase 10 anos na empresa antiga. Mas como diz minha avó, o que não tem remédio, remediado está! Decidi tirar um ano sabático para ir estudando e descobrindo outros caminhos que pudesse percorrer. Aí sim, entrou a tecnologia, comecei a fazer alguns cursos livres da Alura (alô Alura, sou sua fã ♥️) e fui me aprofundando cada vez mais nesse mundo, até que comecei a procurar por referencias femininas na área, porque sei que ainda é uma área predominantemente masculina, e para a minha surpresa, não só tinha muita mina foda na área como iniciativas muito fodas voltadas para mulheres.

E dentre essas iniciativas, a Laboratória me chamou muito a atenção, não só pela sua história, como pela sua didática de ensino. Resolvi me inscrever para a turma 3, mas desisti no meio do caminho, por achar que não teria capacidade de enfrentar o processo seletivo (hello again, síndrome da impostora).

Aí já dei aquela senhora desanimada, decretando que o meu destino era ser dona de casa pra sempre, que não tinha o menor potencial pra nada. Até que depois de muita terapia e do apoio do Gui, fiquei esperando pelo próximo processo seletivo da Lab, quando abriu, corri para me inscrever e decidi ir até o fim, independente de passar ou não, eu faria a minha parte. Cêis não tem noção da minha alegria quando recebi o e-mail de que tinha sido aprovada! Começaria ali um bootcamp que mudaria a minha vida.

Foram os seis meses mais loucos e intensos da minha vida. Aprendi demais, chorei de mais, tive bugs demais mas eu me apaixonei por programação, e eu não me vejo mais fazendo outra coisa da vida se não codar e passar ódius o dia todo kkkk. E esta semana, eu pude comemorar mais uma conquista, a minha primeira contratação como Desenvolvedora em uma empresa parceira da Laboratória. Inclusive em outro post, vou me aprofundar mais sobre a Lab e tudo o que eu aprendi lá. Em resumo é isso, estou muito feliz e empolgada com essa nova fase.

E para finalizar, aí vai uma frase bem clichê mas muito real: “Nunca, jamais desista dos seus objetivos e nunca, jamais duvide da sua capacidade”. Vai ter mulher na tecnologia sim 💪🏼

Spring Boot e MongoDB

Wed, 02 Sep 2020 10:51:33 GMT

O objetivo desse post é criar uma aplicação de geolocalização, dizer quais pontos estão próximos de você por exemplo isso é muito útil se você uma empresa de entregas e precisa saber qual fornecedor está mais próximo para a entrega e várias aplicações do gênero. Para isso usarei aqui Spring Boot, pois tem toda uma facilidade para criação do projeto e uma comunidade e documentações muito ativas, MongoDB além de ser uma boa opção por toda a flexibilidade que ele trás também é muito útil nesse cenário onde vamos precisar fazer cálculos de geolocalização e ele nativamente possui isso. Aqui faremos só o backend da aplicação e futuramente desenvolveremos o frontend.

Criando a aplicação Spring Boot

Para isso vamos usar o Spring Initalizr, entrando na página escolhemos como queremos iniciar o projeto, aqui eu irei usar o Spring Web para poder fazer requisições Rest, também estou usando Lombok e Spring DevTools mas são mais pela facilidade que o Lombok fornece quando criarmos os nossos POJOs e o DevTools para podermos usar em desenvolvimento e termos o live reload da aplicação. Então fica mais ou menos assim o projeto:

Após isso também precisamos adicionar ao projeto a dependência do google-service-maps, como estou usando Maven

<!-- https://mvnrepository.com/artifact/com.google.maps/google-maps-services -->
<dependency>
    <groupId>com.google.maps</groupId>
    <artifactId>google-maps-services</artifactId>
    <version>0.11.0</version>
</dependency>

Também adicione o driver do Mongo ao pom.

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongo-java-driver</artifactId>
</dependency>

Descrição da aplicação

Vamos emular uma rede entregas de alimentos, onde os estabelecimentos estão cadastrados e quando um usuário digitar o seu endereço e ele irá exibir os mais próximos dele.

Model

Vamos começar o nosso model com o que seria então o Estabelecimento ele possuirá nome, email e a sua localização. Então vou começar criando a classe Localizacao.

package com.challenge.geolocation.model;

import java.util.List;

import lombok.Data;

@Data
public class Localizacao {
	
	private String endereco;
    private List<Double> coordinates;    
    private String type = "Point";

}

Aqui temos o endereço mas também temos dois atributos que podem parecer um pouco estranhos o coordinates e o type. Os dois são necessários quando estamos trabalhando com geolocalização com o Mongo, o primeiro valor coordinates é uma lista de double contendo a latitude e longitude e o type diz respeito a um ponto no mapa, podemos ter outros types como Polygon. Agora criando a nossa classe do estabelecimento propriamente dita.

package com.challenge.geolocation.model;

import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.geo.GeoJsonPoint;
import org.springframework.data.mongodb.core.mapping.Document;

import lombok.Data;

package com.challenge.geolocation.model;
import org.

import lombok.Data;

@Datapublic class Estabelecimento

	private ObjectId id;

	private String nome;
	private String email;
	private Localizacao localizacao;	
	
}

Temos aqui a classe Estabelecimento composta pela classe Localizacao e com os atributos id lombok nos ajuda a reduzir um pouco a verbozidade.

Codecs

Agora temos o Model criado mas precisamos fazer de alguma forma pra que a nossa aplicação se comunique com o Mongo. Aí entra os codecs, ele vai ser o responsável por fazer tanto o envio como o recebimento dos objetos do Mongo. Então vamos criar a classe EstabelecimentoCodec que implementa a interface CollectibleCodec do tipo Estabelecimento:

package com.challenge.geolocation.codec;

import org.bson.BsonReader;
import org.bson.BsonValue;
import org.bson.BsonWriter;
import org.bson.codecs.CollectibleCodec;
import org.bson.codecs.DecoderContext;
import org.bson.codecs.EncoderContext;

import com.challenge.geolocation.model.Estabelecimento;

public class EstabelecimentoCodec implements CollectibleCodec<Estabelecimento>{

	@Override
	public void encode(BsonWriter writer, Estabelecimento value, EncoderContext encoderContext) {
		// TODO Auto-generated method stub
		
	}

	@Override
	public Class<Estabelecimento> getEncoderClass() {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public Estabelecimento decode(BsonReader reader, DecoderContext decoderContext) {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public Estabelecimento generateIdIfAbsentFromDocument(Estabelecimento document) {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public boolean documentHasId(Estabelecimento document) {
		// TODO Auto-generated method stub
		return false;
	}

	@Override
	public BsonValue getDocumentId(Estabelecimento document) {
		// TODO Auto-generated method stub
		return null;
	}

}

Agora precisamos começar a implementar o codec a nossa maneira para ele poder fazer o encod e o decode, para isso vamos adicionar a classe Codec do pacote bson que nos ajuda, vamos tipa-la como um Document e vamos adicioná-lo ao construtor para ele ficar como dependência do nosso codec:

import org.bson.Document;
import org.bson.codecs.Codec;

import com.challenge.geolocation.model.Estabelecimento;


public class EstabelecimentoCodec implements CollectibleCodec<Estabelecimento>{
	
	private Codec<Document> codec;
	
	public EstabelecimentoCodec(Codec<Document> codec) {
		this.codec = codec;
	}

Agora vamos implementar o método responsável por fazer o encode. Aqui é onde dizemos como serão salvo os nossos objetos em Java para um objeto do Mongo:

@Override
public void encode(BsonWriter writer, Estabelecimento estabelecimento, EncoderContext encoder) {
    Document document = new Document();
    
    document.put("_id", estabelecimento.getId());
    document.put("nome", estabelecimento.getNome());
    document.put("email", estabelecimento.getEmail());
    
    Localizacao localizacao = estabelecimento.getLocalizacao();
    
    List<Double> coordinates = new ArrayList<>();
    localizacao.getCoordinates().forEach(coordinates::add);
    
    document.put("localizacao", new Document()
            .append("endereco", localizacao.getEndereco())
            .append("coordinates", coordinates)
            .append("type", localizacao.getType()));
    
    codec.encode(writer, document, encoder);
}

E aqui é onde impletamos o decode, como o Java vai interpretar o objeto retornado do Mongo:

@Override
public Estabelecimento decode(BsonReader reader, DecoderContext decoderContext) {
    
    Document document = codec.decode(reader, decoderContext);
    
    Estabelecimento estabelecimento = new Estabelecimento();
estabelecimento.
    estabelecimento.setNome(document.getString("nome"));
    estabelecimento.setEmail(document.getString("email"));
    
    Document localizacao = (Document) document.get("localizacao");
    if(localizacao != null) {
        String endereco = localizacao.getString("endereco");
        @SuppressWarnings("unchecked")
        List<Double> coordinates = (List<Double>) localizacao.get("coordinates");
        
        Localizacao localizacaoEntity = new Localizacao();
        localizacaoEntity.setEndereco(endereco);
        localizacaoEntity.setCoordinates(coordinates);
        
        estabelecimento.setLocalizacao(localizacaoEntity);
    }
    
    return estabelecimento;
}

E temos os outros métodos que implementamos para que o codec consiga fazer a gerência dos objetos:

@Override
public Class<Estabelecimento> getEncoderClass() {
    return Estabelecimento.class;
}

@Override
public Estabelecimento generateIdIfAbsentFromDocument(Estabelecimento estabelecimento) {
    return documentHasId(estabelecimento) ? estabelecimento.generateId() : estabelecimento;
}

@Override
public boolean documentHasId(Estabelecimento estabelecimento) {
    return estabelecimento.getId() == null;
}

@Override
public BsonValue getDocumentId(Estabelecimento estabelecimento) {
    if (!documentHasId(estabelecimento)) {
        throw new IllegalStateException("This Document do not have a id");
    }
    
    return new BsonString(estabelecimento.getId().toHexString());
}

A única coisa aqui a ressaltar foi a criação do método generateId no model Estabelecimento que fica assim:

package com.challenge.geolocation.model;
import org.

import lombok.Data;

@Datapublic class Estabelecimento

	private ObjectId id;

	private String nome;
	private String email;
	private Localizacao localizacao;	
	
	public Estabelecimento generateId() {
	this
		return this;
	}
	
}

Repository

Agora temos o Model e o Codec agora podemos criar o nosso Repository que irá fazer o acesso ao banco e ficará responsável por toda a gerência no Mongo.

package com.challenge.geolocation.repository;

import org.springframework.stereotype.Repository;

import com.mongodb.MongoClient;
import com.mongodb.client.MongoDatabase;

@Repository
public class EstabelecimentoRepository {

	private MongoClient client;
	private MongoDatabase mongoDataBase;

Aqui criei a classe EstabelecimentoRepository e utilizei a annotation @Repository que diz ao Spring que essa classe fará a administração com o banco, aqui já adicionei o MongoClient que fará o registro do Codec e fará a conexão ao banco e o MongoDatabase que é quem será responsável por nos trazer a instância onde poderemos buscar nas nossos collections e fazer as transações. Agora vamos abrir a conexão com o banco de dados:

	@Value("${host}")
	private String host;

	@Value("${port}")
	private String port;

	@Value("${database}")
	private String database;

	@Value("${collection.estabelecimento}")
	private String estabelecimento;

	private MongoCollection<Estabelecimento> openConnetion() {
		Codec<Document> codec = MongoClient.getDefaultCodecRegistry().get(Document.class);

		EstabelecimentoCodec estCodec = new EstabelecimentoCodec(codec);

		CodecRegistry registry = CodecRegistries.fromRegistries(MongoClient.getDefaultCodecRegistry(),
				CodecRegistries.fromCodecs(estCodec));

		MongoClientOptions options = MongoClientOptions.builder().codecRegistry(registry).build();

		this.client = new MongoClient(host + ":" + port, options);
		this.mongoDataBase = client.getDatabase(database);

		return this.mongoDataBase.getCollection(this.estabelecimento, Estabelecimento.class);
	}

    private void closeConnection() {
        this.client.close();
	}

Fazendo uso da annotation @Valeu do Spring conseguimos recuperar o valor que está no application.yml contendo o host, a port, o database e o nome da collection. Então basicamente registramos o Codec e conectamos no Mongo e já pegamos a nossa collection e já deixamos pronto o método para fechar a conexão. Agora vamos ao método que vai fazer a busca e agregação desses dados se baseando na proximidade.

	public List<Estabelecimento> searchByGeolocation(Filter filter) {
		try {
			MongoCollection<Estabelecimento> estabelecimentoCollection = openConnetion();

			estabelecimentoCollection.createIndex(Indexes.geo2dsphere("localizacao"));

			Point referencePoint = new Point(new Position(filter.getLat(), filter.getLng()));

			MongoCursor<Estabelecimento> resultados = estabelecimentoCollection
					.find(Filters.nearSphere("localizacao", referencePoint, filter.getDistance(), 0.0)).limit(filter.getLimit()).iterator();

			List<Estabelecimento> estabelecimentos = fillEstabelecimento(resultados);

			return estabelecimentos;
		} finally {
			closeConnection();
		}
	}

    private List<Estabelecimento> fillEstabelecimento(MongoCursor<Estabelecimento> resultados) {
        List<Estabelecimento> estabelecimentos = new ArrayList<>();
        while (resultados.hasNext()) {
            estabelecimentos.add(resultados.next());
        }
        return estabelecimentos;
	}

Então aqui abrimos a conexão com o método openConnetion() que nos devolve a nossa collection e como queremos fazer uma busca por proximidade adicionamos um índice e dizemos que o campo localizacao é do tipo 2dsphere se tivessemos usando Mongo ficaria assim:

db.estabelcimento.createIndex({
    localizacao : "2dsphere"
})

Isso o que fizemos é o que o Mongo nos obriga a fazer se quisermos fazer a busca por geolocalização. Em seguida criamos uma classe Point que recebe a latitude e a longitude e que será a baseado no nosso endereço quando passarmos. Como pegar a nossa latitude e longitude? Não se preocupe que iremos ver mais a seguir no momento só entenda que teremos esses valores pois é assim que poderemos trabalhar com geolocalização. Agora podemos disparar a nossa pesquisa:

MongoCursor<Estabelecimento> resultados = estabelecimentoCollection
					.find(Filters.nearSphere("localizacao", referencePoint, filter.getDistance(), 0.0)).limit(filter.getLimit()).iterator();

Aqui está a nossa busca, temos a nossa collection e usamos o método find só que passamos dentro dele os nossos filtros para a agregação com a classe Filter e seu método estático nearSphere que ele recebe o campo onde ele vai fazer a busca que no caso é localizacao o ponto de referencia que é o nosso referencePoint que nós criamos com a latitude e longitude, a máxima distância, em metros, da nossa pesquisa e a mínima distância; também passamos o limit de resultados e chamamos o iterator para podermos percorrers o que nos voltar do Mongo. Com um Iterator de resultados em mão podemos então percorrer o resultado, aqui separei no método fillEstabelecimento que devolve uma lista de Estabelecimento:

    private List<Estabelecimento> fillEstabelecimento(MongoCursor<Estabelecimento> resultados) {
        List<Estabelecimento> estabelecimentos = new ArrayList<>();
        while (resultados.hasNext()) {
            estabelecimentos.add(resultados.next());
        }
        return estabelecimentos;
	}

Service

Agora faremos a classe de serviço, que irá executar a nossa consulta ao banco através do Repository e que irá ser chamada pela nossa Controller que nos passará o endereço e nós iremos fazer a transformação dele em latitude e longitude, para isso usaremos a dependência Google Maps mas antes disso teremos que nos registrar no GCP - Google Cloud Platform, para isso será necessário criar um conta lá, não se preocupe com isso pois o Google dará um valor em créditos caso seja seu primeiro registro e após isso não cobrará nada sem seu consentimento prévio, após criar a conta acesse o Console habilitar a API Geocoding API:

Após isso é necessário criar uma Apikey para que a sua aplicação possa se comunicar com o serviço que foi habilitado:

Agora a nossa apikey em mão já podmos começar a criar a classe EstabelecimentoService:

package com.challenge.geolocation.service;

import java.io.IOException;
import java.util.List;
import java.util.stream.Collectors;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import com.challenge.geolocation.dto.EstabelecimentoDTO;
import com.challenge.geolocation.filter.Filter;
import com.challenge.geolocation.model.Estabelecimento;
import com.challenge.geolocation.repository.EstabelecimentoRepository;
import com.google.maps.GeoApiContext;
import com.google.maps.GeocodingApi;
import com.google.maps.GeocodingApiRequest;
import com.google.maps.errors.ApiException;
import com.google.maps.model.GeocodingResult;
import com.google.maps.model.Geometry;
import com.google.maps.model.LatLng;

@Service
public class EstabelecimentoService {

	@Autowired
	private EstabelecimentoRepository repository;

	@Value("${apikey}")
	private String apikey;

	public List<EstabelecimentoDTO> procuraEstabelecimentosProximoAMim(String endereco, String distance, String limit) {

		GeoApiContext context = new GeoApiContext.Builder().apiKey(apikey).build();

		GeocodingApiRequest request = GeocodingApi.newRequest(context).address(endereco);

		try {
			GeocodingResult[] results = request.await();
			GeocodingResult resultado = results[0];
			
			Geometry geometry = resultado.geometry;
			
			LatLng location = geometry.location;
			
			List<Estabelecimento> estabelecimentoList = repository.searchByGeolocation(
					Filter.toFilter(location.lat, location.lng, Double.valueOf(distance), Integer.valueOf(limit)));
			
			List<EstabelecimentoDTO> dtoList = estabelecimentoList.stream().map(estabelecimento -> {
				return EstabelecimentoDTO.toDTO(estabelecimento);
			}).collect(Collectors.toList());
			
			return dtoList;
		} catch (ApiException | InterruptedException | IOException e) {
			e.printStackTrace();
		}

		return List.of();
	}
}

Criamos o método procuraEstabelecimentosProximoAMim que recebe o endereco, a distance e o limit, em seguida criamos GeoApiContext usando a nossa apikey fazemos a nossa requisição para a o serviço do Google passando o nosso endereço como estamos fazendo tudo isso de forma síncrona ficamos esperando o retorno do serviço externo, isso por si só pode ocasionar muitos problema então todo o método await lança Exceptions que aqui não vamos nos aprofundar tratando-as. Após o retorno pegamos o resultado e navegamos no objeto de retorno até chegarmos onde queremos que é na location que é onde ele guarda a latitude e a longitude e agora podemos chamar o nosso Repository que irá executar a nossa busca.

Filter

Um ponto de observação, você deve ter notado a classe Filter e o método toFilter na nossa Service e na Repository o Filter com getLat, getLng, getDistance e getLimit. Ele nos ajuda a não passar um valor muito grande variáveis na chamada de um método, segue:

@Getter
public class Filter {
	
	private Filter() {}
	
	private double lat;
	private double lng;
	private double distance;
	private int limit;
	
	public static Filter toFilter(double latitude, double longitude, double distance, int limit) {
		Filter filter = new Filter();
		filter.lat = latitude;
		filter.lng = longitude;
		filter.distance = distance == 0 ? 1000.0 : distance;
		filter.limit = limit == 0 ? 10 : limit;		
		
		return filter;
	}

}

Controller

Agora iremos criar a nossa Controller onde receberemos a requisição e devolveremos o resultado da pesquisa.

package com.challenge.geolocation.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.challenge.geolocation.dto.EstabelecimentoDTO;
import com.challenge.geolocation.service.EstabelecimentoService;

@RestController
@RequestMapping("api")
public class EstabalecimentoController {

	@Autowired
	private EstabelecimentoService service;

	@GetMapping("estabelecimento")
	public List<EstabelecimentoDTO> pegaEstabelecimentosProximosPeloEndereco(
			@RequestParam(name = "limit", defaultValue = "10") String limit,
			@RequestParam(name = "distancia", defaultValue = "1000.00") String distancia,
			@RequestParam("endereco") String endereco) {
		return service.procuraEstabelecimentosProximoAMim(endereco, distancia, limit);
	}

}

Temos aqui a nossa EstabalecimentoController com unm método pegaEstabelecimentosProximosPeloEndereco e os parâmetros limit com um valor default de 10 caso não seja específicado na url, distancia com o valor de 1000.00, valor em metros e endereco. Uma coisa interessante é que a nossa Controller não devolve o nosso Model pois não é considerado uma boa prática e até mesmo um falha de segurança dependedo da situação então o que devolvemos? Devolvemos um DTO (Data Transfer Object) que é um objeto POJO que só trafega dados como no exemplo:

package com.challenge.geolocation.dto;

import com.challenge.geolocation.model.Estabelecimento;
import com.fasterxml.jackson.annotation.JsonAutoDetect;
import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;

import lombok.Getter;

@JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE)
@Getter
public class EstabelecimentoDTO {
	
	private EstabelecimentoDTO() {}
	
	private String nome;
	private String email;
	private String endereco;

	public static EstabelecimentoDTO toDTO(Estabelecimento estabelecimento) {
		EstabelecimentoDTO dto = new EstabelecimentoDTO();
		
		dto.nome = estabelecimento.getNome();
		dto.email = estabelecimento.getEmail();
		dto.endereco = estabelecimento.getLocalizacao().getEndereco();		
		
		return dto;
	}
}

A única responsabilidade desse DTO é transformar um Estabelecimento em um DTO para ser retornado para a Controller e isso é feito dentro da nossa classe de Service no retorno da nossa Repository.

Resultado final

Antes de testarmos precisamos fazer a inclusão de dados, então podemos inserir no Mongo os dados:

{
    "nome" : "Mercado I",
    "email" : "contato@mercadoI.com",
    "localizacao" : {
        "endereco" : "Rua Brigadeiro Tobias n 780",
        "coordinates" : [ 
            -23.53624, 
            -46.63395
        ],
        "type" : "Point"
    }
}

{    
    "nome" : "Estabelecimento II",
    "email" : "contato@mercadoII.com",
    "localizacao" : {
        "endereco" : "R. Brg. Tobias, 206 - Santa Ifigênia, São Paulo - SP, 01032-000",
        "coordinates" : [ 
            -23.54165, 
            -46.63583
        ],
        "type" : "Point"
    }
}

{    
    "nome" : "Estabelecimento III",
    "email" : "contato@mercadoIII.com",
    "localizacao" : {
        "endereco" : "Av. Cásper Líbero, 42 - Centro Histórico De São Paulo, São Paulo - SP, 01033-000",
        "coordinates" : [ 
            -23.54132, 
            -46.63643
        ],
        "type" : "Point"
    }
}

{    
    "nome" : "Estabelecimento IV",
    "email" : "contato@mercadoIV.com",
    "localizacao" : {
        "endereco" : "Av. Rio Branco, 630 - República, São Paulo - SP, 01205-000",
        "coordinates" : [ 
            -23.53984, 
            -46.64008
        ],
        "type" : "Point"
    }
}

{    
    "nome" : "Estabelecimento V",
    "email" : "contato@mercadoV.com",
    "localizacao" : {
        "endereco" : "Alameda Barão de Limeira, 425 - Campos Elíseos, São Paulo - SP, 01202-900",
        "coordinates" : [ 
            -23.53386, 
            -46.6482
        ],
        "type" : "Point"
    }
}

{    
    "nome" : "Estabelecimento VI",
    "email" : "contato@mercadoVI.com",
    "localizacao" : {
        "endereco" : "R. Canuto do Val, 41 - Santa Cecilia, São Paulo - SP, 01224-040",
        "coordinates" : [ 
            -23.54062, 
            -46.65114
        ],
        "type" : "Point"
    }
}

Agora vamos fazer um teste manual usando o Insomnia um client para requisições HTTP, mas você usar qualquer um de sua prefência, PostMan, PostWoman, cUrl e etc.

Então fazendo a requisição http://localhost:8080/api/estabelecimento?endereco=R. Brg. Tobias, 247 Temos a reposta:

[
  {
    "nome": "Estabelecimento II",
    "email": "contato@mercadoII.com",
    "endereco": "R. Brg. Tobias, 206 - Santa Ifigênia, São Paulo - SP, 01032-000"
  },
  {
    "nome": "Estabelecimento III",
    "email": "contato@mercadoIII.com",
    "endereco": "Av. Cásper Líbero, 42 - Centro Histórico De São Paulo, São Paulo - SP, 01033-000"
  },
  {
    "nome": "Mercado I",
    "email": "contato@mercadoI.com",
    "endereco": "Rua Brigadeiro Tobias n 780"
  },
  {
    "nome": "Estabelecimento IV",
    "email": "contato@mercadoIV.com",
    "endereco": "Av. Rio Branco, 630 - República, São Paulo - SP, 01205-000"
  }
]

Projeto Final

O projeto final você pode encontrar aqui aqui

15 conselhos

Thu, 20 Aug 2020 10:51:33 GMT

Esses conselhos foram compilados seguindo as minhas próprias experiências de vida e aprendizado que tive durante essas mais de 3 décadas de existência. Não sou dono da verdade. Não houve uma ciência aplicada ou validada para esse compilado de conselhos que eu quis fazer por livre e espontânea vontade. Você que esta lendo isso, sinta se a vontade para desistir da leitura a qualquer momento, você é totalmente livre para discordar de tudo aqui apresentado e seguir a sua vida, então por favor não venha reclamar ou repudiar a iniciativa aqui apresentada. Esse texto pode sofrer alterações ou ser removido a qualquer momento sem ter que dar satisfação a qualquer pessoa ou organização.

Objetivo 1:

Compartilhar publicamente 15 conselhos que eu fiz e me aconselharia a seguir se estivesse começando hoje na carreira de tecnologia.

Objetivo 2:

Colaborar para no mínimo uma pessoa com o seu crescimento, evolução, amadurecimento(ou de qualquer outra maneira possível, quiçá causando revolta na leitura e o incentivando a escrever algo melhor)

1. Aprenda Inglês

2. Instale e use Linux!

Existem milhões de distros(versões) de linux e como você faz pra saber qual a melhor opção pra ti? Simples! Experimente de um em um até encontrar a versão ideal para você! Eu sugiro que você comece pelo Debian: https://www.debian.org/distrib/ ou https://www.ubuntu.com/

3. Aprenda a usar o linux e o terminal

Vasculha a internet sobre comandos no terminal usando linux! Aprenda apt-get, nano e vi! Assine esse canal e veja TODOS os videos sobre linux: https://www.youtube.com/user/linuxtipscanal

4. GIT

Aprenda a usar o git, versionador de código fonte. Leia na wikipedia, na internet e na própria documentação o que é o git! http://git-scm.com/ dentro do site tem um ebook gratuito, leia! Existe treinamento online de git aqui: https://try.github.io/levels/1/challenges/1 Faça e refaça quantas vezes necessário

5. github/gitlab/bitbucket

É uma plataforma onde você pode publicar seus códigos fonte e projetos open source ou privado(tem q pagar $). Hoje em dia é utilizado como rede social para desenvolvedores. USE a plataforma como seu portfolio! Tudo quanto for código que você fizer na faculdade, em casa, cursos, na VIDA coloque no github! Aproveita e me da follow: https://github.com/pedrualves/

6. Rotina

Autodidata: “adjetivo e substantivo de dois gêneros que ou quem se instrui por esforço próprio, sem a ajuda de mestres.”

Disciplina: ordem, regulamento, conduta que assegura o bem-estar dos indivíduos ou o bom funcionamento (p.ex., de uma organização).

Organização: É a forma como se dispõe um sistema para atingir os resultados pretendidos, através de funções de modo controlado e coordenado com a missão de atingir um objetivo em comum com eficácia.

7. Linkedin

Para se encontrar emprego, você precisa de um CV de respeito. O linkedin como plataforma para encontrar empresas e empregos serve com grande êxito esse propósito! Faça seu linkedin em pt-br e en-us, sim nos 2 idiomas! Aproveita e me da follow: https://www.linkedin.com/in/pedrualves/

8. APINFO

É simplesmente um local mais que perfeito para encontrar uma vaga na área de programação! Se cadastre, cadastre seu CV e visite o site TODOS OS DIAS para procurar emprego! http://apinfo.com.br/

9. Google/Youtube/Wikipedia/Documentação

Faça dos mecanismos de pesquisa os seus melhores amigos! Aprenda a buscar tudo nele! Faça e refaça pesquisas sempre que um novo assunto surgir!

10. Stackoverflow

Muitas dúvidas surgiram e nada melhor do que o maior “site-de-pergunta-e-responde” para que outras pessoas possam te ajudar. Aproveite e faça do mundo um lugar melhor e ajude ao próximo esclarecendo eventuais dúvidas.

11. Cursos/Faculdades

Presencial ou online, faça cursos, aprenda com quem tem experiência, quanto mais melhor no inicio, o leque de possíveis caminhos tende ao infinito! Entre tantas tecnologias, metodologias, inovações, tendências é impossível definir um único caminho de sucesso, trilhe o seu, acompanhe as tendências do mercado. Então faça cursos pelo youtube, udemy, codeschool, codecademy, khancademy, pluralsight, alura, caelum, globalcode, etc

12. Eventos/Meetups/Palestras/Workshops

Um ótimo ponto para conhecimento, conhecimento free, acompanhar tendências, networking. Toda essa socialização podem te dar uma bandeja de novidades interessantes(ou não rs).

13. Redes sociais

Cuidado! Facebook, linkedin(até tu brutus?!), twitter, instagram, snapchat, fliker, orkut, google plus, ou seja lá o raio que o for. Cuidado! Vejo lado positivo a possibilidade de você pode encontrar pessoas, grupos, informações, opiniões e outros frutos da socialização que venham a contribuir muito em sua jornada e formação, além de te inspirar, motivar e dar chance para seu lado criativo, inovador ajudarem a você mesmo e outras pessoas. Cuidado! Vejo lado negativo a possibilidade de você pode encontrar pessoas, grupos, informações, opiniões e outros frutos da socialização que venham a não contribuir nada em sua jornada e formação, além de te frustrar, desmotivar, irritar e dar espaço para síndrome do impostor ou outras coisas mais que possam te surtar ou deprimir. Cuidado!

14. Tempo(clichezão)

“E eu não tenho nada a te dizer Mas não me critique como eu sou Cada um de nós é um universo, Pedro”

Penso que as experiências, ambiente, oportunidades, alinhamento dos planetas, o tropeçar de uma formiga e tantas outras coisas afetam a maneira como somos, pensamos e agimos. O que parece fácil e simples para você, pode ser bem o oposto para outra pessoa e vice-versa. A sua timeline por mais que tenha pontos em comuns com dos seus amigos, irmãos, pais, colegas e outros 6 bilhões de pessoas que vivem no mundo, cada um tem o seu tempo de aprendizagem, evolução, amadurecimento e diversão. Então minha dica é: dê tempo ao tempo; aprenda a usar o tempo a seu favor; valorize o tempo atual; o tempo que passou passou; tudo tem o seu tempo;

15. Paciência/Confiança/Otimismo/Bom humor

É óbvio que todo caminho tem obstáculos, dificuldades, inúmeras falhas, stress, discussões e confusões. Essas virtudes tem sido os pilares que me ajudam a manter a cabeça no lugar, assim ficou fácil continuar evoluindo como pessoa, como profissional, como eterno aprendiz…

Arquitetura limpa

Wed, 19 Aug 2020 12:57:37 GMT

Arquitetura e Arquitetura limpa

O que é Arquitetura?

Resumindo arquitetura de software pode ser descrito da seguinte forma: ”… a arquitetura envolve: decisões sobre as estruturas que formarão o sistema, controle, protocolos de comunicação, sincronização e acesso a dados, atribuição de funcionalidade a elementos do sistema, distribuição física dos elementos escalabilidade e desempenho e outros atributos de qualidade.”

Quebrando um pouco mais essa explicação e tentando deixá-la mais suscinta eu diria que a arquitetura de software é a ideia que trata da relação entre o mapeamento de componentes de um software e os detalhes que são levados em conta na hora de implementar esses elementos na forma de código.

Resumindo ainda mais a arquitetura consiste em um modelo de alto nível que possibilita um entendimento e uma análise mais fácil do software a ser desenvolvido.

Como o nome diz e levando pro mundo real é como ver um arquiteto de uma casa onde ele desenha a planta e todas as partes da construção se encaixam e como elas devem interagir uma com a outra.

Por que existe?

A ideia de arquitetura de software surgiu nos anos 60 e se tornou popular nos anos 90.

A ideia era enfatizar a importância de estruturar um sistema antes de seu desenvolvimento.

O que resolve?

A ideia é que uma boa arquitetura resolva parafrasenado Robert Martin (Uncle Bob):

“O objetivo da arquitetura de software é minimizar os recursos humanos necessários para construir e manter um determinado sistema.”

A ideia é que com uma boa arquitetura o custo para mudanças não seja alto, que uma simples mudança não entrave a aplicação.

Arquitetura limpa

Com esses conceitos em mente por volta de 2012 Robert C. Martin (Uncle Bob) criou a Arquitetura Limpa, um estilo com similaridades com a Arquitetura Cebola e a Arquitetura Hexagonal.

O que resolve?

A arquitetura limpa tem como ideia principal, a modulação das informações que serão codificadas, facilitando a manutenção; os módulos precisam ser independentes o suficiente para que possam ser trabalhados pelos desenvolvedores em equipes diferentes

Independência entre componentes, quer dizer cada módulo não conhece o outro, então mudanças em cada módulo não quebram ou necessitam de ajustes nos demais.
Independência de framework, os frameworks que tanto gostamos aqui são tratados como meros detalhes, as aplicações não são mais amarradas ao framework, podendo assim haver substituição rápida de um framework por outro sem nenhum impacto na aplicação.
Independência de banco de dados, assim como os frameworks o banco de dados é tratado como um detalhe.
Testabilidade aqui vale um ponto importante, quanto mais fácil for pro seu sistema ser testado menos acoplamento ele terá isso significa que mudanças serão faceis de ocorrer e de serem testadas.
Independência de interface de usuário, seja um GUI, API ou que quer que seja deve haver independência e não deve interferir no funcionamento do sistema.
Independência de agentes externos, a nossa regra de negócio não deve depender de nada externo.

Como funciona?

Neste modelo proposto por Robert C. Martin, Uncle Bob, a arquitetura é representada por camadas circulares concêntricas passando a proposta de baixo acoplamento e alta coesão:

Acoplamento

Dizemos sobre acoplamento em um software quando as partes que o compõe são altamente dependentes umas das outras o que dificulta a manutenção os testes e ainda mais mudanças.

Coesão

Dizemos sobre baixa coesão em um software quando uma parte dele realiza diversas tarefas ou possui multiplas responsabilidades.

Buscamos sempre um sistema que tenha baixo acoplamento e alta coesão. Na imagem abaixo vemos como a Arquitetura Limpa demonstra como resolver essas questões:

Começando do centro pra fora:

Entidades

A Entidade é a camada mais ao centro e mais alta na Arquitetura Limpa, é aqui onde devem ficar os objetos de domínio da aplicação, as regras de negócio cruciais e que não irão mudar com facilidade.

Casos de Uso

Casos de uso contém regras de negócio mais específicas referente à aplicação, ele especifíca a entrada a ser fornecida, a saída a ser retornada e os passos de processamento envolvidos.

Adaptadores de Interface

Camada que tem como finalidade converter dados da maneira mais acessível e conveniente possível para as camadas Entidades e Casos de Uso. Um exemplo seria o uso de Mapper’s, onde eu poderia controlar as estruturas transmitidas entre Casos de Uso e Entidades com o interface do usuário, por exemplo.

Frameworks e Drivers

Contém qualquer frameworks ou ferramentas para poder rodar na aplicação.

Exemplo prático

Ápos toda a teoria vamos mostrar na prática com um projeto simples onde teremos três pontos de entrada da aplicação.

Com o desenrolar do projeto vamos perceber que nesse modelo arquitetural o mais importante são as camadas mais internas e as mais externas serão tratados como detalhe e é aí que mora a quebra de tabu da Arquitetura Limpa, pois o foco é no negócio e não nas tecnologias; mas ainda estamos trabalhando com um sistema automatizado e precisamos seguir alguns paradigmas, mas só o que é realmente indispensável.

Vamos fazer um projeto de cadastro de Power Rangers, nele um usuário vai enviar os seus dados e a aplicação irá criar um Ranger de uma cor dependendo de algumas características.

Vamos usar a linguagem Java como um projeto modular Maven e a partir dele conseguimos modularizar as nossas camadas.

Criando projeto

Dentro do nosso diretória vmos criar um arquivos pom.xml, esse arquivos vai ser o raiz da nossa aplicação, é nele que teremos as dependências declaradas com suas versões que usuaremos e também teremos aqui a declaração dos nossos módulos, segue o exemplo:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>com.gogo.powerrangers</groupId>
	<artifactId>clean-architecture-example</artifactId>
	<packaging>pom</packaging>
	<version>1.0</version>
	<modules>
		<module>entity</module>
	</modules>

	<properties>
		<revision>1.0</revision>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>11</java.version>
		<lombok-version>1.18.10</lombok-version>
		<maven.compiler.source>${java.version}</maven.compiler.source>
		<maven.compiler.target>${java.version}</maven.compiler.target>
		<junit-jupiter.version>5.5.1</junit-jupiter.version>
		<junit-platform>1.5.1</junit-platform>
	</properties>

	<dependencyManagement>
		<dependencies>

			<!-- Jupiter -->
			<dependency>
				<groupId>org.junit.jupiter</groupId>
				<artifactId>junit-jupiter-api</artifactId>
				<version>${junit-jupiter.version}</version>
				<scope>test</scope>
			</dependency>
			<dependency>
				<groupId>org.junit.jupiter</groupId>
				<artifactId>junit-jupiter-engine</artifactId>
				<version>${junit-jupiter.version}</version>
				<scope>test</scope>
			</dependency>
			<dependency>
				<groupId>org.junit.platform</groupId>
				<artifactId>junit-platform-launcher</artifactId>
				<version>${junit-platform}</version>
				<scope>test</scope>
			</dependency>
			<dependency>
				<groupId>org.junit.platform</groupId>
				<artifactId>junit-platform-runner</artifactId>
				<version>${junit-platform}</version>
				<scope>test</scope>
			</dependency>

		</dependencies>
	</dependencyManagement>


</project>

Aqui temos o mínimo para começar, temos a declaração da versão do java, o JUnit que será o nosso framework de testes unitários e temos a declaração do nosso primeiro módulo chamado entity.

Entidade

Agora vamos para a nossa entidade, esse é o ponto mais ao centro e mais acima do nosso projeto, dentro dele devemos ter os nossos objetos de domínio e regras de negócio que podem viver sem um sistema automatizado. Esse é o módulo que será visto por todos os outros mas não conhece os demais, ele é totalmente isolado de dependências externas.

Então pensando no nosso projeto aqui modelamos o nosso domínio de ususários, onde vamos ter o nome, email, idade, personalidade e o nome do ranger que será criado.

Vamos criar um diretório onde está o nosso pom raiz com o nome de entity e dentro dele vamos criar o pom.xml da nossa entity:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<parent>
		<artifactId>clean-architecture-example</artifactId>
		<groupId>com.gogo.powerrangers</groupId>
		<version>1.0</version>
	</parent>

	<modelVersion>4.0.0</modelVersion>

	<artifactId>entity</artifactId>
	<version>${revision}</version>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>11</source>
					<target>11</target>
				</configuration>
			</plugin>
		</plugins>
	</build>

	<dependencies>

		<!-- Jupiter -->
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-api</artifactId>
		</dependency>
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-engine</artifactId>
		</dependency>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-launcher</artifactId>
		</dependency>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-runner</artifactId>
		</dependency>

	</dependencies>

</project>

Podemos ver que nesse pom temos somente a versão do Java e o JUnit que nos ajudará a fazer os testes unitários.

Vamos criar a nosso primeira classe de domínio que chamaremos de User e vamos ter os atributos que definimos do nosso usuários:

package com.gogo.powerrangers.entity;

public class User {

    private final String name;
    private final String email;
    private final int age;
    private final Personality personality;
    private final String ranger;

    User(String name, String email, int age, Personality personality, String ranger) {
        this.name = name;
        this.email = email;
        this.age = age;
        this.personality = personality;
        this.ranger = ranger;
    }

    public String getRanger() {
        return ranger;
    }
    public String getName() {
        return name;
    }
    public String getEmail() {
        return email;
    }
    public int getAge() {
        return age;
    }
    public Personality getPersonality() {
        return personality;
    }
}

Temos aqui a nossa entidade e colocamos um Enum pra Personalidade e um construtor com acessibilidade package default que é um construtor que só pode ser acessado dentro do pacote onde ele foi declarado e criamos apenas os getters.

Agora temos a nossa entidade que é um POJO e vamos adicionar nesse projeto a regra de negócio que pode viver sem existir uma aplicação.

No universo dos Power Rangers cada ranger é escolhido de acordo com a sua personalidade, pra cada tipo de personalidade uma cor diferente e essa regra é independente de existir um software ou não, é uma regra dos Power Rangers então essa regra pertence a Entidade.

Pra isso eu vou separar essa definição para acontecer no momento em que um usuário for criado, então vamos usar um padrão de Builder para criar o nosso usuário e definir qual a cor do ranger de acordo com a sua pernsonalidade:

package com.gogo.powerrangers.entity;

public final class UserBuilder {

    private String name;
    private String email;
    private int age;
    private Personality personality;
    private String ranger;

    UserBuilder() {
    }

    public UserBuilder name(String name) {
        this.name = name;
        return this;
    }

    public UserBuilder email(String email) {
        this.email = email;
        return this;
    }

    public UserBuilder age(int age) {
        this.age = age;
        return this;
    }

    public UserBuilder personality(String personality) {
        this.personality = Personality.of(personality);
        this.ranger = this.discoverRanger(this.personality);
        return this;
    }

    public User build() {
        return new User(this.name, this.email, this.age, this.personality, this.ranger);
    }

    private String discoverRanger(Personality personality) {
        switch (personality) {
            case LIDERANCA:
                return "Vermelho";

            case ENTUSIASMO:
                return "Preto";

            case TRANQUILIDADE:
                return "Amarelo";

            case INTELIGENCIA:
                return "Azul";

            case RIQUEZA:
                return "Rosa";

            case PERSISTENCIA:
                return "Verde";

            case FORCA:
                return "Branco";

            default:
                return "";
        }
    }
}

Aqui temos a criação de um User e já temos a definição da cor do ranger de acordo com a personalidade, vamos também adicionar o nosso builder dentro da nossa classe User:

    public static UserBuilder builder() {
        return new UserBuilder();
    }

Casos de uso

Agora que criamos a nossa entidade vamos criar a próxima camada que são os Casos de Uso. Nem toda regra de negócio é pura como a regra de negócio que está na Entidade, algumas regras de negócio fazem sentido existirem em um sistema automatizado, software, e é aqui que eles são usados, nos Casos de Uso, aqui faremos validações, controle de fluxo e temos as portas de comunicação com os adapatadores, como no caso de persistência de dados.

Então vamos criar um novo diretório chamado usecase e nele teremos um arquivo pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>clean-architecture-example</artifactId>
        <groupId>com.gogo.powerrangers</groupId>
        <version>1.0</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>usecase</artifactId>
    <version>${revision}</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>entity</artifactId>
            <version>${revision}</version>
        </dependency>

        <!-- Unit Test -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-launcher</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-runner</artifactId>
        </dependency>
    </dependencies>
</project>

Aqui temos a dependência da entity e vamos criar o nosso primeiro caso de uso, a criação de um usuário. Criamos uma classe com nome CreateUser com um método create que irá receber um User e irá aplicar as validações necessárias para criar um usuário e iremos persistir essa informação em algum lugar. Não especificamos onde iremos persistir pois aqui isso é um mero detalhe que não é da preocupação dos Casos de Uso, podemos usar JDBC puro, Spring Data, cache em memória ou arquivo de texto essa responsabilidade não nos interessa aqui.

package com.gogo.powerrangers.usecase;

import com.gogo.powerrangers.entity.User;

public class CreateUser {

    public CreateUser() {

    }

    public User create(final User user) {


        return user;
    }
}

Vamos adicionar primeiramente a nossa validação, aqui vamos imaginar que o usuário não pode ser menor de 18 anos e não pode ser repetido e iremos verificar pelo email essa informação. Vamos criar uma classe chamada UserValidator:

package com.gogo.powerrangers.usecase.validator;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.usecase.exception.PowerRangerNotFoundException;
import com.gogo.powerrangers.usecase.exception.UserValidationException;

import static java.util.Objects.isNull;

public class UserValidator {

    public static void validateCreateUser(final User user) {
        if(isNull(user)) {
            throw new UserValidationException("Usuario nao pode ser null");
        }
        if(user.getAge() < 18) {
            throw new UserValidationException("Usuario deve ser maior de 18 anos");
        }
        if(user.getPersonality().getPersonality().isEmpty()){
            throw new PowerRangerNotFoundException("Power Ranger não localizado com personalidade informada");
        }
    }
}

Aqui temos a nossa validação e customizamos as nossas Exceptions com a UserValidationException e a PowerRangerNotFoundException, em seguida acionamos o nosso método estático a nossa classe de criação de usuário:

package com.gogo.powerrangers.usecase;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.usecase.exception.UserAlreadyExistsException;
import com.gogo.powerrangers.usecase.validator.UserValidator;

public class CreateUser {

    private final UserRepository repository;

    public CreateUser(UserRepository repository) {
        this.repository = repository;
    }

    public User create(final User user) {

        UserValidator.validateCreateUser(user);
        if (repository.findByEmail(user.getEmail()).isPresent()) {
            throw new UserAlreadyExistsException(user.getEmail());
        }

        return user;
    }
}

Pronto temos a nossa validação e agora precisamos de alguma forma informar que queremos persistir essa informação, porém como fazer isso se os drivers e frameworks estão na camada mais externa e a ideia aqui é deixar o Caso de Uso desacoplado de deles?

Usaremos interfaces e inversão de controle, trocando em miúdos vamos dizer na nossa classe CreateUser que queremos salvar um usuário mas como ele será salvo já não nos importa.

Então vamos criar a interface UserRepository com os métodos que queremos:

package com.gogo.powerrangers.usecase.port;

import com.gogo.powerrangers.entity.User;

import java.util.List;
import java.util.Optional;

public interface UserRepository {

    User create(User user);

    Optional<User> findByEmail(String email);

    Optional<List<User>> findAllUsers();
}

O resultado final da CreateUser fica:

package com.gogo.powerrangers.usecase;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.usecase.exception.UserAlreadyExistsException;
import com.gogo.powerrangers.usecase.port.UserRepository;
import com.gogo.powerrangers.usecase.validator.UserValidator;

public class CreateUser {

    private final UserRepository repository;

    public CreateUser(UserRepository repository) {
        this.repository = repository;
    }

    public User create(final User user) {

        UserValidator.validateCreateUser(user);
        if (repository.findByEmail(user.getEmail()).isPresent()) {
            throw new UserAlreadyExistsException(user.getEmail());
        }

        var createdUser = repository.create(user);

        return createdUser;
    }
}

Adaptadores de interface

Nessa camada podemos ver que exitem os nossos Controllers, Gateways e Presenters, aqui temos a comunicação pra dentro das nossa Entidades mas também a comunicação externa e representação do objeto de retorno que será exposto.

Vamos criar um diretório chamado adapter e dentro dele outro diretório chamado controller e um arquivos pom.xml que terá como dependência a entity e aa usecase:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>clean-architecture-example</artifactId>
        <groupId>com.gogo.powerrangers</groupId>
        <version>1.0</version>
        <relativePath>../../../clean-architecture-example/pom.xml</relativePath>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>controller</artifactId>
    <version>${revision}</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>entity</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>usecase</artifactId>
            <version>${revision}</version>
        </dependency>
</project>

Vamos começar aqui criando o nosso objeto de resposta da nossa aplicação, não queremos que a nossa entidade seja retornada aqui pois caso a apresentação seja alterada temos um ponto único de alteração e podemos ainda aqui realizar qualquer transformação que seja importante para exibição. Então criamos a classe UserModel:

package com.gogo.powerrangers.model;

import com.gogo.powerrangers.entity.User;

public class UserModel {

    private String name;
    private String email;
    private int age;
    private String personality;
    private String ranger;

    public static UserModel mapToUserModel(User user) {

        var userModel = new UserModel();
        userModel.name = user.getName();
        userModel.email = user.getEmail();
        userModel.age = user.getAge();
        userModel.personality = user.getPersonality().getPersonality();
        userModel.ranger = user.getRanger();

        return userModel;
    }

    public static User mapToUser(UserModel userModel) {
        //@formatter:off
        return User.builder().name(userModel.getName())
                             .age(userModel.getAge())
                             .email(userModel.getEmail())
                             .personality(userModel.getPersonality())
                             .build();
        //@formatter:on
    }

    @Override
    public String toString() {
        return "UserModel{" +
                "name='" + name + '\'' +
                ", email='" + email + '\'' +
                ", age=" + age +
                ", personality='" + personality + '\'' +
                ", ranger='" + ranger + '\'' +
                '}';
    }

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getEmail() {
		return email;
	}

	public void setEmail(String email) {
		this.email = email;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public String getPersonality() {
		return personality;
	}

	public void setPersonality(String personality) {
		this.personality = personality;
	}

	public String getRanger() {
		return ranger;
	}

	public void setRanger(String ranger) {
		this.ranger = ranger;
	}
}

Aqui temos os métodos que fazem a mudança de Model-to-User e User-to-Model e agora vamos criar o nosso controlador:

package com.gogo.powerrangers;

import com.gogo.powerrangers.model.UserModel;
import com.gogo.powerrangers.usecase.CreateUser;

public class UserController {

    private final CreateUser createUser;

    public UserController(CreateUser createUser){
        this.createUser = createUser;
    }

    public UserModel createUser(UserModel userModel){

        var user = createUser.create(UserModel.mapToUser(userModel));

        return UserModel.mapToUserModel(user);
    }
}

Frameworks e Drivers

Aqui é a nossa última camada, aqui temos os Drivers, Frameworks, UI e qualquer Dispositivo ou chamada externa em nossa aplicação é a camada mais “suja” pois é aqui que temos a entrada da nossa aplicação, ela conhece todas as outras camadas porém não é conhecida por nenhuma.

Qual o benefício disso?

O benefício é que com isso temos uma aplicação altamente desacoplada, as camadas mais internas não tem conhecimento de como a aplicação é executada, se estamos usando uma aplicação Web, linha de comando, desktop e etc, isso torna a aplicação plugável a qualquer framework ou driver, contanto que ele siga a contrato, interface, que definimos na camada de Caso de Uso.

Aqui vamos criar três pontos de entrada, um com Java puro executando por terminal e com um banco em memória, outro com Spring Boot e persistência com JDBC Template e outro com VertX e Hibernate.

Aplicação Java executada pelo terminal

Começando pela aplicação Java puro executado pelo terminal. Dentro do diretório adapter vamos criar um outro diretório chamado repository e dentro dele outro diretório chamado in-memory-db e dentro dele um arquivo pom.xm:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>clean-architecture-example</artifactId>
        <groupId>com.gogo.powerrangers</groupId>
        <version>1.0</version>
        <relativePath>../../../../clean-architecture-example/pom.xml</relativePath>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>in-memory-db</artifactId>
    <version>${revision}</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>entity</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>usecase</artifactId>
            <version>${revision}</version>
        </dependency>

        <!-- Unit Test -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-launcher</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-runner</artifactId>
        </dependency>
    </dependencies>
</project>

E vamos criar a classe InMemoryUserRepository que implementa UserRepository:

package com.gogo.powerrangers.db;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.usecase.port.UserRepository;

import java.util.*;

public class InMemoryUserRepository implements UserRepository {

    private final Map<String, User> inMemoryDb = new HashMap<>();

    @Override
    public User create(User user) {
        inMemoryDb.put(user.getEmail(), user);
        return user;
    }

    @Override
    public Optional<User> findByEmail(String email) {
        return inMemoryDb.values().stream().filter(user -> user.getEmail().equals(email)).findAny();
    }

    @Override
    public Optional<List<User>> findAllUsers() {
        return Optional.of(new ArrayList<>(inMemoryDb.values()));
    }
}

E aqui temos um Map e simulamos em cache as operações de persistência.

Agora vamos criar um diretório a partir do nosso diretório raiz chamada application e dentro desse repositório um diretórioa chamadp manual-app e dentro dele um pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>clean-architecture-example</artifactId>
        <groupId>com.gogo.powerrangers</groupId>
        <version>1.0</version>
        <relativePath>../../../clean-architecture-example/pom.xml</relativePath>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>manual-app</artifactId>
    <version>${revision}</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
            <plugin>
                <!-- Build an executable JAR -->
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <classpathPrefix>lib/</classpathPrefix>
                            <mainClass>com.gogo.powerrangers.Main</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>entity</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>usecase</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>controller</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>in-memory-db</artifactId>
            <version>${revision}</version>
        </dependency>

        <!-- Unit Test -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-launcher</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-runner</artifactId>
        </dependency>
    </dependencies>
</project>

Aqui podemos verificar que nas dependências temos acesso as outras camadas, agora precisamos criar a classe Main que irá executar essa aplicação, mas antes vamos precisar fazer o controle e injeção das dependências, pra vamos criar uma classe de configuração chamada ManualConfig:

package com.gogo.powerrangers.config;

import com.gogo.powerrangers.db.InMemoryUserRepository;
import com.gogo.powerrangers.usecase.CreateUser;
import com.gogo.powerrangers.usecase.SearchUser;

public class ManualConfig {

    private final InMemoryUserRepository dataBase = new InMemoryUserRepository();

    public CreateUser createUser(){
        return new CreateUser(dataBase);
    }
}

Aqui temos a criação da instância do InMemoryUserRepository e a injeção dessa dependência na classe CreateUser que irá usar essa instância para realizar a persistência.

Vamos criar agora a classe Main:

package com.gogo.powerrangers;

import com.gogo.powerrangers.config.ManualConfig;
import com.gogo.powerrangers.model.UserModel;

public class Main {

    public static void main(String[] args) {

        var config = new ManualConfig();
        var createUser = config.createUser();
        var controller = new UserController(createUser);

        var userModel = new UserModel();
        userModel.setName(args[0]);
        userModel.setEmail(args[1]);
        userModel.setAge(Integer.parseInt(args[2]));
        userModel.setPersonality(args[3]);

        final var userCreated = controller.createUser(userModel);

        System.out.println(userCreated);
    }
}

Se executarmos essa aplicação pelo terminal:

java -jar target/manual-app-1.0.jar Guilherme fake@mail.com 34 Persistência

Temos o retorno:

UserModel{name='Guilherme', email='guiherme@gmail.com', age=34, personality='Persistência', ranger='Verde'}

Spring Boot e JDBC Template

Agora vamos fazer a aplicação com um frameworks web e outro pra banco de dados.

Antes de mais nada vamos adicionar ao nosso pom raiz as dependências dos frameworks:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.3.0.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <version>2.3.0.RELEASE</version>
    <scope>test</scope>
</dependency>

<!-- https://mvnrepository.com/artifact/org.springframework/spring-jdbc -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>5.2.6.RELEASE</version>
</dependency>

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.4.200</version>
</dependency>

Agora vamos usar o JDBC Template, vamos então criar um diretório em repository chamado spring-jdbc e vamos criar o nosso pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>clean-architecture-example</artifactId>
        <groupId>com.gogo.powerrangers</groupId>
        <version>1.0</version>
        <relativePath>../../../../clean-architecture-example/pom.xml</relativePath>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>spring-jdbc</artifactId>
    <version>${revision}</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>11</source>
                    <target>11</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>entity</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>com.gogo.powerrangers</groupId>
            <artifactId>usecase</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-jdbc</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
        </dependency>
</project>

O nosso pom agora tem as dependências das camadas da nossa aplicação e a dos drivers e framework jdbc, vamos criar o objeto que será persistido no nosso banco de dados chamado UserEntity:

package com.gogo.powerrangers.entity;

public class UserEntity {

    private String id;
    private String name;
    private String email;
    private int age;
    private String personality;
    private String ranger;

    public static User toUser(UserEntity entity){
        var user = User.builder().name(entity.getName()).age(entity.getAge())
                .email(entity.getEmail()).personality(entity.getPersonality()).build();

        return user;
    }

	public String getId() {
		return id;
	}

	public void setId(String id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getEmail() {
		return email;
	}

	public void setEmail(String email) {
		this.email = email;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public String getPersonality() {
		return personality;
	}

	public void setPersonality(String personality) {
		this.personality = personality;
	}

	public String getRanger() {
		return ranger;
	}

	public void setRanger(String ranger) {
		this.ranger = ranger;
	}

}

O JDBC Template pede para implementarmos uma interface RowMapper que nos auxilia no mapeamento do objeto que retorna do banco para o objeto UserEntity:

package com.gogo.powerrangers.mapper;

import java.sql.ResultSet;
import java.sql.SQLException;

import org.springframework.jdbc.core.RowMapper;

import com.gogo.powerrangers.entity.UserEntity;

public class UserRowMapper implements RowMapper<UserEntity> {

    @Override
    public UserEntity mapRow(ResultSet resultSet, int i) throws SQLException {

        UserEntity entity = new UserEntity();

        entity.setId(resultSet.getString("ID"));
        entity.setAge(resultSet.getInt("AGE"));
        entity.setEmail(resultSet.getString("EMAIL"));
        entity.setRanger(resultSet.getString("RANGER"));
        entity.setName(resultSet.getString("NAME"));
        entity.setPersonality(resultSet.getString("PERSONALITY"));

        return entity;
    }
}

Agora vamos implementar a nossa UserRepository numa classe chamada SpringJdbcUserRepository:

package com.gogo.powerrangers;

import java.util.List;
import java.util.Optional;
import java.util.UUID;
import java.util.stream.Collectors;

import javax.sql.DataSource;

import org.springframework.dao.EmptyResultDataAccessException;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseBuilder;
import org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.entity.UserEntity;
import com.gogo.powerrangers.mapper.UserRowMapper;
import com.gogo.powerrangers.usecase.port.UserRepository;

public class SpringJdbcUserRepository implements UserRepository {

	private JdbcTemplate jdbcTemplate;

    public DataSource dataSource(){
        return new EmbeddedDatabaseBuilder().setType(EmbeddedDatabaseType.H2)
                .addScript("classpath:schema.sql").build();
    }

    public JdbcTemplate jdbcTemplate(){
        return new JdbcTemplate(this.dataSource());
    }

    public SpringJdbcUserRepository() {
    	this.jdbcTemplate = this.jdbcTemplate();
    }

    @Override
    public User create(User user) {

        //@formatter:off
        String sql = new StringBuilder().append("INSERT INTO  ")
                                        .append(" USER(id, name, age, email, personality, ranger) ")
                                        .append(" VALUES(?, ?, ?, ?, ?, ?)").toString();
        //@formatter:on

        jdbcTemplate.update(sql, UUID.randomUUID().toString(), user.getName(), user.getAge(), user.getEmail(), user.getPersonality().getPersonality(), user.getRanger());

        return user;
    }

    @Override
    public Optional<User> findByEmail(String email) {

        String sql = "SELECT id, name, age, email, personality, ranger FROM USER WHERE email = ?";

        try {
            UserEntity userEntity = jdbcTemplate.queryForObject(sql, new UserRowMapper(), email);

            User user = UserEntity.toUser(userEntity);

            return Optional.of(user);
        } catch (EmptyResultDataAccessException e) {
            return Optional.empty();
        }
    }

    @Override
    public Optional<List<User>> findAllUsers() {

        String sql = "SELECT id, name, age, email, personality, ranger FROM USER";

        List<UserEntity> userEntityList = jdbcTemplate.query(sql, new UserRowMapper());

        List<User> userList = userEntityList.stream().map(entity -> {
            return UserEntity.toUser(entity);
        }).collect(Collectors.toList());

        return Optional.of(userList);
    }
}

Temos a nossa implementação da parte de persistência de dados e agora precisamos criar a aplicação web com Spring Boot.

No diretório application criamos outro diretório chamado spring-boot e dentro dele um arquivo pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<parent>
		<artifactId>clean-architecture-example</artifactId>
		<groupId>com.gogo.powerrangers</groupId>
		<version>1.0</version>
		<relativePath>../../../clean-architecture-example/pom.xml</relativePath>
	</parent>
	<modelVersion>4.0.0</modelVersion>

	<artifactId>spring-boot</artifactId>
	<version>${revision}</version>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>11</source>
					<target>11</target>
				</configuration>
			</plugin>
		</plugins>
	</build>

	<dependencies>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>entity</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>usecase</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>controller</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>spring-jdbc</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<!-- Unit Test -->
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-api</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-engine</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-launcher</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.junit.platform</groupId>
			<artifactId>junit-platform-runner</artifactId>
		</dependency>
	</dependencies>
</project>

Aqui temos as dependências das camadas da nossa aplicação e as dependências do framework.

Quando usamos Spring Boot precisamos de uma classe principal que chamaremos de Application:

package com.gogo.powerrangers;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

    public static void main(String[] args){
        SpringApplication.run(Application.class, args);
    }
}

Essa classe possui a annotation @SpringBootApplication e tudo o que é necessário para uma aplicação Spring Boot ser iniciada.

Mas agora precisamos fazer a nossa configuração de injeção de dependências e nisso o SPring Boot nos ajuda através dos Beans, então vamos criar uma classe de configuração chamada SpringBootConfig:

package com.gogo.powerrangers.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.gogo.powerrangers.SpringJdbcUserRepository;
import com.gogo.powerrangers.UserController;
import com.gogo.powerrangers.usecase.CreateUser;
import com.gogo.powerrangers.usecase.port.UserRepository;

@Configuration
public class SpringBootConfig {

    @Bean
    public UserRepository dataBase(){
        return new SpringJdbcUserRepository();
    }

    @Bean
    public CreateUser createUser(){
        return new CreateUser(this.dataBase());
    }

    @Bean
    public UserController userController(){
        return new UserController(this.createUser();
    }
}

Aqui temos a annotation @Configuration que nos auxilia e indica ao Spring que aqui temos os nossos Beans que serão processados pelo container do Spring e deixarão esses Beans disponíveis para serem injetados na aplicação. Também temos os nosso Beans própriamente ditos e prontos para serem usados, então vamos a criação do nosso endpoint com a classe AddUserController:

package com.gogo.powerrangers.endpoint;

import com.gogo.powerrangers.UserController;
import com.gogo.powerrangers.model.UserModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/powerrangers")
public class AddUserController {

    @Autowired
    private UserController userController;

    @PostMapping("add")
    public ResponseEntity<UserModel> addUser(@RequestBody UserModel userModel){
        return ResponseEntity.ok(userController.createUser(userModel));
    }
}

Aqui temos a nossa injeção através da annotation @Autowired da UserController e as declarações necessárias para a criação de um endpoint que recebe um UserModel através de um POST e faz a criação e persistência desse usuário.

VertX e Hibernate

Agora vamos criar uma aplicação com o framework VertX e com persistência de dados com o Hibernate. Para isso vamos começar com o Hibernate, criaremos um diretório dentro de repository com nome hibernate e nele criamos um arquivo pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<parent>
		<artifactId>clean-architecture-example</artifactId>
		<groupId>com.gogo.powerrangers</groupId>
		<version>1.0</version>
		<relativePath>../../../../clean-architecture-example/pom.xml</relativePath>
	</parent>
	<modelVersion>4.0.0</modelVersion>

	<artifactId>hibernate</artifactId>
	<version>${revision}</version>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>11</source>
					<target>11</target>
				</configuration>
			</plugin>
		</plugins>
	</build>

	<dependencies>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>entity</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>usecase</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.h2database</groupId>
			<artifactId>h2</artifactId>
		</dependency>

		<dependency>
				<groupId>org.hibernate</groupId>
				<artifactId>hibernate-core</artifactId>
			</dependency>
			<dependency>
				<groupId>org.hibernate</groupId>
				<artifactId>hibernate-jpamodelgen</artifactId>
			</dependency>

			<!--Compile time JPA API -->
			<dependency>
				<groupId>javax.persistence</groupId>
				<artifactId>javax.persistence-api</artifactId>
			</dependency>

			<!--Runtime JPA implementation -->
			<dependency>
				<groupId>org.eclipse.persistence</groupId>
				<artifactId>eclipselink</artifactId>
			</dependency>
</project>

No nosso pom temos nossas dependências e também adicionamos as dependências que são necessárias para o Hibernate funcionar. O Hibernate precisa de um arquivo de configuração dentro da pasta META-INF em resources chamado persistence.xml e dentro dele ficam as configurações das propriedades que o Hibernate usa:

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd"
	version="2.2">

	<persistence-unit name="jpa-h2">
		<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
		<class>com.gogo.powerrangers.entity.UserEntity</class>
		<exclude-unlisted-classes>true</exclude-unlisted-classes>
		<properties>
			<property name="hibernate.show_sql" value="true" />
			<property name="hibernate.format_sql" value="true" />
			<property name="javax.persistence.jdbc.driver"
				value="org.h2.Driver" />
			<property name="javax.persistence.jdbc.url"
				value="jdbc:h2:mem:test" />
			<property name="javax.persistence.jdbc.user" value="sa" />
			<property name="javax.persistence.jdbc.password" value="" />
			<property name="hibernate.dialect"
				value="org.hibernate.dialect.H2Dialect" />
			<property name="hibernate.hbm2ddl.auto" value="update" />
			<property name="show_sql" value="true" />
			<property name="hibernate.temp.use_jdbc_metadata_defaults"
				value="false" />
		</properties>
	</persistence-unit>

</persistence>

Agora precisamos mapear o nosso objeto que vai representar a tabela no banco de dados:

package com.gogo.powerrangers.entity;

import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "USER")
public class UserEntity {

	@Id
	private String id;
    private String name;
    private String email;
    private int age;
    private String personality;
    private String ranger;

    public static User toUser(UserEntity entity) {
        var user = User.builder().name(entity.getName()).age(entity.getAge())
                .email(entity.getEmail()).personality(entity.getPersonality()).build();

        return user;
    }

	public String getId() {
		return id;
	}
	public void setId(String id) {
		this.id = id;
	}
	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public String getEmail() {
		return email;
	}
	public void setEmail(String email) {
		this.email = email;
	}
	public int getAge() {
		return age;
	}
	public void setAge(int age) {
		this.age = age;
	}
	public String getPersonality() {
		return personality;
	}
	public void setPersonality(String personality) {
		this.personality = personality;
	}
	public String getRanger() {
		return ranger;
	}
	public void setRanger(String ranger) {
		this.ranger = ranger;
	}
}

Aqui na UserEntity temos todas as anotações necessárias para o Hibernate. E agora vamos criar a nossa classe que irá implementar a UserRepository que chamaremos de HibernateUserRepository onde vamos criar a nossa instância do EntityManager para gerenciar as nossas transações com o banco de dados:

package com.gogo.powerrangers;

import java.util.List;
import java.util.Optional;
import java.util.UUID;
import java.util.stream.Collectors;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.NoResultException;
import javax.persistence.Persistence;
import javax.persistence.TypedQuery;

import com.gogo.powerrangers.entity.User;
import com.gogo.powerrangers.entity.UserEntity;
import com.gogo.powerrangers.usecase.port.UserRepository;

public class HibernateUserRepository implements UserRepository{

	private EntityManagerFactory emf = null;

	public HibernateUserRepository() {
		emf = Persistence.createEntityManagerFactory("jpa-h2");
	}

	@Override
	public User create(User user) {
		EntityManager entityManager = emf.createEntityManager();
		entityManager.getTransaction().begin();

		UserEntity entity = new UserEntity();
		entity.setId(UUID.randomUUID().toString());
		entity.setName(user.getName());
		entity.setEmail(user.getEmail());
		entity.setAge(user.getAge());
		entity.setPersonality(user.getPersonality().getPersonality());
		entity.setRanger(user.getRanger());

		entityManager.persist(entity);
		entityManager.getTransaction().commit();
		entityManager.close();

		return user;
	}

	@Override
	public Optional<User> findByEmail(String email) {
		EntityManager entityManager = emf.createEntityManager();

		//@formatter:off
		TypedQuery<UserEntity> query = entityManager.createQuery(new StringBuilder()
				.append("SELECT user ")
				.append("	FROM UserEntity user ")
				.append(" WHERE user.email = :email").toString(), UserEntity.class);
		// @formatter:on

		try {
			UserEntity userEntity = query.setParameter("email", email).getSingleResult();

			return Optional.of(UserEntity.toUser(userEntity));
		} catch (NoResultException e) {
			return Optional.empty();
		}
	}

	@Override
	public Optional<List<User>> findAllUsers() {
		EntityManager entityManager = emf.createEntityManager();

		List<UserEntity> userEntityList = entityManager.createQuery("SELECT user FROM UserEntity user", UserEntity.class).getResultList();

		List<User> userList = userEntityList.stream().map(UserEntity::toUser).collect(Collectors.toList());

        return Optional.of(userList);
	}

}

Agora vamos criar a nossa aplicação com o framework VertX, vamos no diretório application e criar uma pasta chamada vertx e adicionar o pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<parent>
		<artifactId>clean-architecture-example</artifactId>
		<groupId>com.gogo.powerrangers</groupId>
		<version>1.0</version>
		<relativePath>../../../clean-architecture-example/pom.xml</relativePath>
	</parent>
	<modelVersion>4.0.0</modelVersion>

	<artifactId>vertx</artifactId>
	<version>${revision}</version>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>11</source>
					<target>11</target>
				</configuration>
			</plugin>
		</plugins>
	</build>

	<dependencies>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>entity</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>usecase</artifactId>
			<version>${revision}</version>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>controller</artifactId>
			<version>${revision}</version>
		</dependency>

		<!-- https://mvnrepository.com/artifact/io.vertx/vertx-web -->
		<dependency>
			<groupId>io.vertx</groupId>
			<artifactId>vertx-web</artifactId>
		</dependency>

		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-core</artifactId>
		</dependency>

		<dependency>
			<groupId>com.gogo.powerrangers</groupId>
			<artifactId>hibernate</artifactId>
			<version>${revision}</version>
		</dependency>
</project>

Temos as nossas dependências das camadas internas, as dependências do VertX e a dependência do jackson-core que nos ajuda com o nosso endpoint. E agora vamos criar a nossa classe de configuração onde teremos a injeção das nossas dependências:

package com.gogo.powerrangers.config;

import com.gogo.powerrangers.HibernateUserRepository;
import com.gogo.powerrangers.usecase.CreateUser;
import com.gogo.powerrangers.usecase.port.UserRepository;

public class VertxConfig {

	public final UserRepository repository() {
		return new HibernateUserRepository();
	}

	public final CreateUser createUser() {
		return new CreateUser(this.repository());
	}
}

E criaremos agora o nosso controller que utiliza a instâncai que foi injetada do nosso UserController

package com.gogo.powerrangers.endpoint;

import io.vertx.core.buffer.Buffer;
import io.vertx.core.http.HttpServerResponse;
import io.vertx.core.json.JsonObject;

public abstract class Controller {

    public boolean isNull(final Buffer buffer) {
        return buffer == null || "".equals(buffer.toString());
    }

    public void sendError(int statusCode, HttpServerResponse response) {
        response
                .putHeader("content-type", "application/json")
                .setStatusCode(statusCode)
                .end();
    }

    public void sendSuccess(JsonObject body, HttpServerResponse response) {
        response
                .putHeader("content-type", "application/json")
                .end(body.encodePrettily());
    }

}

package com.gogo.powerrangers.endpoint;

import com.gogo.powerrangers.UserController;
import com.gogo.powerrangers.model.UserModel;

import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.RoutingContext;

public class AddUserController extends Controller{

	private final UserController controller;

	public AddUserController(UserController controller) {
        this.controller = controller;
    }

	public void createUser(final RoutingContext routingContext) {
        var response = routingContext.response();
        var body = routingContext.getBody();
        if (isNull(body)) {
            sendError(400, response);
        } else {
            var userModel = body.toJsonObject().mapTo(UserModel.class);
            var user = controller.createUser(userModel);
            var result = JsonObject.mapFrom(user);
            sendSuccess(result, response);
        }
    }

}

Temos aqui uma classe abstrata Controller que serve apenas como utilitário que outros controllers podem usar.

Agora precisamos o nosso ponto de entrada da aplicação e fazer as configurações do VertX:

package com.gogo.powerrangers;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.gogo.powerrangers.config.VertxConfig;
import com.gogo.powerrangers.endpoint.AddUserController;s

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Launcher;
import io.vertx.core.json.Json;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.BodyHandler;

public class VertxApplication extends AbstractVerticle{

	private final VertxConfig config = new VertxConfig();
	private final UserController userController = new UserController(config.createUser(), config.searchUser());
    private final AddUserController addUserController = new AddUserController(userController);

    @Override
    public void start() {
        Json.mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
        var router = Router.router(vertx);
        router.route().handler(BodyHandler.create());
        router.post("/add").handler(addUserController::createUser);

        vertx.createHttpServer().requestHandler(router::accept).listen(8080);
    }

    public static void main(String[] args) {
        Launcher.executeCommand("run", VertxApplication.class.getName());
    }
}

Aqui temos as configurações do VertX e rotas no método start e o main que é o ponto de entrada.

Conclusão

Podemos ver que com esse modelo de arquitetura temos uma aplicação plugável, quer dizer essa aplicação pode usar outras camadas sem que isso tenha impacto direto nas camadas mais internas. Vimos também que o foco está na regra de negócio e a facilidade em fazer testes é maior.

Prós

Independente de Framework
Altamente testável
Independente de UI
Independente de Banco de Dados
Independente de qualquer agente externo

Contras

Maior curva de aprendizado
Mais classes, pacotes e mais sub-projetos

link do projeto