Skip to content

12. Programação web

Pré-requisitos: a versão 8 da aplicação [Tax], descrita no final deste capítulo, reutiliza os [tax-dao], [tax-business] e [tax-ui] módulos da versão 5 (Capítulo 6). Antes de compilar ou abrir seus projetos, é preciso ter instalado a versão 5 no repositório Maven local com o comando [mvn install] executado na pasta [06-architectures/TaxV5] (veja o Capítulo 6, seção sobre [mvn install]).

12.1. Informações gerais

12.1.1. Protocolos da Internet

Apresentamos aqui uma introdução aos protocolos de comunicação da Internet, também conhecidos como a pilha de protocolos TCP/IP (Transmission Control Protocol / Internet Protocol), nome derivado dos dois principais protocolos. É útil que o leitor tenha uma compreensão geral do funcionamento das redes — e em particular dos protocolos TCP/IP — antes de abordar o desenvolvimento de aplicações distribuídas. Esta apresentação baseia-se em um texto do guia de administração “Lan Workplace for DOS” da Novell (início dos anos 1990), mantendo sua estrutura e seu espírito, mas atualizado: a Internet de 2026 já não é exatamente a de 1990.

O conceito geral de criar uma rede de computadores heterogêneos nasceu de pesquisas conduzidas pela DARPA (Defense Advanced Research Projects Agency) nos Estados Unidos. A DARPA desenvolveu o conjunto de protocolos conhecido como TCP/IP, que permite que máquinas heterogêneas se comuniquem entre si. Esses protocolos foram testados em uma rede chamada ARPAnet, que mais tarde se tornou a Internet (a ARPAnet adotou o TCP/IP em 1º de janeiro de 1983). Os protocolos TCP/IP definem formatos e regras de transmissão e recepção que são independentes da arquitetura da rede e do hardware utilizado.

A rede projetada pela DARPA e gerenciada pelos protocolos TCP/IP é uma rede de comutação de pacotes. Uma rede desse tipo transmite informações em pequenos pedaços chamados pacotes. Assim, se um computador transmite um arquivo grande, ele será dividido em pequenos pedaços que são enviados pela rede para serem remontados no destino. O TCP/IP define o formato desses pacotes, incluindo, em particular:

  • a origem do pacote;
  • seu destino;
  • seu tamanho;
  • seu tipo.

Os protocolos da Internet são descritos em documentos públicos chamados RFC (Request for Comments), publicados pela IETF (Internet Engineering Task Force) e disponíveis em www.rfc-editor.org. Citaremos alguns desses documentos ao longo deste capítulo.

12.1.2. O modelo OSI

Os protocolos TCP/IP seguem, em linhas gerais, o modelo aberto de rede conhecido como OSI (Open Systems Interconnection Reference Model), definido pela ISO (International Organization for Standardization). Esse modelo descreve uma rede ideal em que a comunicação entre máquinas pode ser representada por um modelo de sete camadas:

Image

Cada camada recebe serviços da camada inferior e fornece seus próprios serviços à camada superior. Suponha que duas aplicações situadas em máquinas diferentes, A e B, queiram se comunicar: elas o fazem na camada de Aplicação. Não precisam conhecer todos os detalhes do funcionamento da rede: cada aplicação repassa a informação que deseja transmitir à camada inferior, a camada de Apresentação. A aplicação só precisa, portanto, conhecer as regras de interface com a camada de Apresentação. Uma vez que a informação está na camada de Apresentação, ela é repassada, segundo outras regras, à camada de Sessão, e assim por diante, até que a informação chegue ao meio físico e seja transmitida fisicamente à máquina de destino. Lá, ela sofrerá o processo inverso ao que sofreu na máquina de origem.

Em cada camada, o processo emissor responsável por enviar a informação a envia a um processo receptor da outra máquina que pertence à mesma camada. Isso é feito segundo certas regras conhecidas como protocolo da camada. A comunicação real desce pelas camadas da Máquina A, atravessa a rede física e depois sobe pelas camadas da Máquina B; no entanto, cada camada percebe que está se comunicando diretamente com a camada correspondente da outra máquina.

Os papéis das diferentes camadas são os seguintes:

Camada
Papel
Física
Garante a transmissão de bits por um meio físico (cabo de cobre, cabo de fibra óptica, ondas de rádio). As principais questões nesse nível incluem a codificação da informação em sinais e o método de transmissão.
Enlace de dados
Abstrai as características físicas da camada Física. Divide a informação em quadros, detecta (e às vezes corrige) erros de transmissão e gerencia o acesso ao meio compartilhado.
Rede
Gerencia o caminho que a informação enviada pela rede deve seguir. Isso é chamado de roteamento: determinar a rota que a informação deve percorrer para chegar ao destino.
Transporte
Permite a comunicação entre duas aplicações, enquanto as camadas anteriores permitiam apenas a comunicação entre máquinas. Um serviço fornecido por essa camada é a multiplexação: a camada de transporte usa um único enlace de rede (de máquina a máquina) para transmitir dados pertencentes a várias aplicações.
Sessão
Fornece serviços que permitem a uma aplicação abrir e manter uma sessão de trabalho em uma máquina remota.
Apresentação
Padroniza a representação dos dados entre máquinas diferentes. Os dados da máquina A são “formatados” pela camada de Apresentação da máquina A segundo um formato padrão antes de serem enviados pela rede. Ao chegar à camada de Apresentação da máquina de destino B — que os reconhece com base em seu formato padrão —, os dados são reformatados para que a aplicação da máquina B possa reconhecê-los.
Aplicação
Nesse nível estão as aplicações geralmente mais próximas do usuário, como o e-mail, a Web ou a transferência de arquivos.

12.1.3. O modelo TCP/IP

O modelo OSI é um modelo de referência que nunca foi implementado tal como é. A pilha de protocolos TCP/IP, que se tornou o padrão, é organizada em apenas quatro camadas:

Image

As camadas de Sessão e de Apresentação não existem como tais no TCP/IP: suas funções, quando necessárias, são tratadas pelas próprias aplicações ou por protocolos intermediários como o TLS (criptografia das trocas de dados), que se insere entre o TCP e a aplicação.

A camada de acesso à rede

Nas redes locais, a tecnologia dominante hoje é a Ethernet para conexões com fio e o Wi-Fi (padrões IEEE 802.11) para conexões sem fio. Outras tecnologias, como o Token Ring, desapareceram.

Ethernet é o nome dado a uma tecnologia de rede local de comutação de pacotes inventada na Xerox no início dos anos 1970 e padronizada pela Xerox, Intel e Digital Equipment em 1980 e, depois, pelo IEEE (padrão 802.3). A Ethernet original consistia em um cabo coaxial ao qual todas as máquinas estavam conectadas (topologia em barramento), com uma taxa de transmissão de 10 megabits por segundo:

Image

Era uma rede de difusão (broadcast): uma máquina transmissora enviava pelo cabo uma informação que incluía o endereço da máquina receptora; todas as máquinas conectadas a recebiam, e apenas o destinatário a retinha. Como várias máquinas podiam decidir transmitir ao mesmo tempo, era preciso detectar colisões: era o método de acesso CSMA/CD (Carrier Sense Multiple Access / Collision Detect). Cada transmissor escutava o cabo antes de transmitir (CSMA) e, durante a transmissão, verificava se o que passava pelo cabo era de fato o que havia transmitido; se não fosse, ocorria uma colisão (CD): cada um parava de transmitir e tentava novamente após um atraso aleatório.

A Ethernet moderna evoluiu bastante: os dispositivos são conectados por cabos de par trançado ou de fibra óptica a um switch, que encaminha cada quadro à porta específica do destinatário. As conexões são full-duplex (transmissão e recepção simultâneas): não há mais colisões, e o CSMA/CD tornou-se obsoleto. As taxas típicas variam de 1 a 10 gigabits por segundo, e são muito mais altas em data centers.

O que não mudou foi o endereçamento de 48 bits: cada placa de rede tem um endereço, chamado endereço físico ou endereço MAC (Media Access Control), geralmente escrito como seis bytes hexadecimais (por exemplo, [00:1A:2B:3C:4D:5E]). Ele é gravado na placa pelo fabricante, mas — ao contrário do que se afirmou por muito tempo — pode ser modificado por software: os sistemas operacionais modernos chegam a usar endereços MAC aleatórios em redes Wi-Fi para impedir que um dispositivo seja rastreado de rede em rede.

A camada de Internet (camada de rede)

Nessa camada, encontramos os seguintes protocolos:

Protocolo
Papel
IP (Internet Protocol)
entrega pacotes entre dois nós da rede, na versão 4 (IPv4) ou 6 (IPv6)
ICMP (Internet Control Message Protocol)
facilita a comunicação entre o programa do protocolo IP de uma máquina e o de outra máquina. É, portanto, um protocolo de troca de mensagens de controle dentro do próprio protocolo IP
ARP (Address Resolution Protocol)
associa o endereço IP de uma máquina ao endereço físico da máquina (no IPv6, esse papel é desempenhado pelo protocolo NDP, o Neighbor Discovery Protocol)

Também se menciona, às vezes, o RARP (Reverse Address Resolution Protocol), que realizava o mapeamento inverso. Há muito tempo ele foi substituído pelo DHCP, do qual trataremos mais adiante.

A camada de transporte

Essa camada inclui os seguintes protocolos:

Protocolo
Papel
TCP (Transmission Control Protocol)
garante a entrega confiável e ordenada de informações entre duas aplicações
UDP (User Datagram Protocol)
realiza a entrega não confiável de informações entre duas aplicações

O protocolo QUIC (2021), no qual o HTTP/3 se baseia, é um protocolo de transporte confiável e criptografado construído sobre o UDP.

A camada de aplicação

Aqui encontramos diversos protocolos, que detalharemos um pouco mais adiante:

Protocolo
Papel
HTTP, HTTPS (HyperText Transfer Protocol)
O protocolo da Web: um cliente (navegador, aplicação) solicita recursos a um servidor web. O HTTPS é o HTTP criptografado com TLS
DNS (Domain Name System)
converte um nome de host em um endereço IP
SMTP (Simple Mail Transfer Protocol)
permite o envio de e-mails
POP3, IMAP
permitem ler e-mails armazenados em um servidor
SSH (Secure Shell)
permite conectar-se a uma máquina remota e executar comandos nela, usando criptografia. Substituiu o TELNET, que desempenhava a mesma função sem criptografia
FTP (File Transfer Protocol), SFTP
permitem a transferência de arquivos
DHCP (Dynamic Host Configuration Protocol)
permite que uma máquina obtenha automaticamente seu endereço IP e sua configuração de rede

12.1.4. Como funcionam os protocolos da Internet

As aplicações desenvolvidas no ambiente TCP/IP geralmente usam vários dos protocolos desse ambiente. Um programa de aplicação se comunica com a camada mais alta dos protocolos. Essa camada repassa a informação à camada inferior, e assim por diante, até chegar ao meio físico. Ali, a informação é transferida fisicamente para a máquina receptora, onde passará pelas mesmas camadas — desta vez no sentido oposto — até chegar à aplicação destinatária da informação enviada. O diagrama a seguir mostra o caminho da informação:

Image

Vejamos um exemplo: uma aplicação que envia um arquivo a outra máquina usando TCP.

  • A aplicação entrega à camada de transporte uma sequência de bytes a transmitir;
  • a camada de transporte divide essa sequência de bytes em segmentos TCP e adiciona ao início de cada segmento um cabeçalho contendo, entre outras coisas, os números das portas de origem e de destino, bem como um número de sequência. Os segmentos são repassados à camada de rede, regida pelo protocolo IP;
  • A camada IP cria um pacote que encapsula o segmento TCP recebido. No cabeçalho desse pacote, ela coloca os endereços IP das máquinas de origem e de destino. Ela também determina o endereço físico da máquina à qual o pacote deve ser entregue (o próprio destino ou um roteador). O pacote inteiro é repassado à camada de acesso à rede, isto é, à placa de rede que conecta a máquina à rede física;
  • ali, o pacote IP é por sua vez encapsulado em um quadro físico e enviado ao destinatário pelo meio;
  • Na máquina de destino, a camada de acesso à rede realiza o processo inverso: ela desencapsula o pacote IP do quadro físico e o repassa à camada IP;
  • a camada IP verifica se o pacote é válido: ela calcula um checksum de seu cabeçalho, que deve coincidir com o presente no cabeçalho do pacote. Se não for o caso, o pacote é descartado;
  • se o pacote for considerado válido, a camada IP desencapsula o segmento TCP nele contido e o repassa para cima, à camada de transporte;
  • a camada TCP também verifica um checksum do segmento. Se estiver correto, ela envia uma confirmação à máquina de origem; caso contrário, o segmento é ignorado (e será reenviado pela origem);
  • Usando os números de sequência, a camada TCP reordena os segmentos na ordem correta;
  • resta à camada TCP apenas transmitir a parte de dados dos segmentos à aplicação de destino, identificada pelo número da porta de destino.

12.1.5. Questões de endereçamento na Internet

Um nó de rede pode ser um computador, uma impressora, um telefone, um dispositivo conectado — enfim, qualquer coisa que possa se comunicar usando os protocolos TCP/IP. Cada nó tem um endereço físico cujo formato depende do tipo de rede. Em uma rede Ethernet ou Wi-Fi, o endereço físico é codificado em 6 bytes.

O endereço de Internet (IP) de um nó é um endereço lógico: ele é independente do hardware e da rede utilizados. No IPv4, é um endereço de 4 bytes que identifica ao mesmo tempo uma rede e um nó dessa rede. Costuma ser representado como quatro números — os valores dos quatro bytes — separados por um ponto. Por exemplo, o endereço da máquina chamada “Lagaffe”, da Faculdade de Ciências de Angers, foi por muito tempo 193.49.144.1, e o da máquina chamada “Liny” era 193.49.144.9. A partir disso, podia-se deduzir que o endereço da rede local era 193.49.144.0 e que poderia haver até 254 nós nessa rede.

Como os endereços IP são independentes da rede física, uma máquina da rede A pode se comunicar com uma máquina da rede B sem se preocupar com o tipo de rede em que esta se encontra: basta conhecer seu endereço IP. O protocolo IP de cada rede cuida da conversão entre endereços IP e endereços físicos nos dois sentidos.

Todos os endereços IP públicos devem ser únicos. Sua alocação segue uma estrutura hierárquica: a IANA (Internet Assigned Numbers Authority) distribui blocos de endereços a cinco registros regionais, entre eles o RIPE NCC para a Europa, que os redistribuem a operadoras e grandes organizações. Essas entidades os atribuem então a seus clientes. O administrador de uma rede que recebeu o bloco de 193.49.144.0 a 193.49.144.255 pode atribuir os endereços de 193.49.144.1 a 193.49.144.254 como achar melhor. Na França, o INRIA foi por muito tempo responsável pela atribuição de endereços; isso já não ocorre há bastante tempo.

12.1.5.1. As classes de endereços IP e a notação CIDR

Um endereço IPv4 é uma sequência de 4 bytes denotada I1.I2.I3.I4, que na verdade contém duas informações:

  • o endereço da rede (os bits mais significativos);
  • o endereço de um nó dentro dessa rede (os bits menos significativos).

Originalmente, o tamanho desses dois campos era determinado pelo valor do primeiro byte. Os endereços IP eram divididos em três classes principais:

Classe
Primeiro byte
Rede / Nó
Número de redes e de nós
A
1 a 126 (bit mais significativo 0)
R1.N1.N2.N3: rede de 1 byte (7 bits significativos), nó de 3 bytes
126 redes de 2²⁴ - 2 nós (aproximadamente 16 milhões)
B
128 a 191 (10 bits mais significativos)
R1.R2.N1.N2: rede de 2 bytes (14 bits significativos), nó de 2 bytes
2¹⁴ = 16.384 redes de 2¹⁶ - 2 = 65.534 nós
C
192 a 223 (110 bits mais significativos)
R1.R2.R3.N1: rede de 3 bytes (21 bits significativos), nó de 1 byte
2²¹ redes (aproximadamente 2 milhões) com 254 nós

Como o endereço da máquina Lagaffe é 193.49.144.1, o byte mais significativo é 193, que é 11000001 em binário: a rede era uma rede de classe C.

Essa classificação mostrou-se rígida demais: uma organização com 300 máquinas era obrigada a usar uma rede de classe B, desperdiçando mais de 65.000 endereços. Desde 1993 (RFC 1518 e 1519), as classes foram abandonadas em favor do roteamento sem classes (CIDR, Classless Inter-Domain Routing). A fronteira entre a parte de rede e a parte de nó pode ser fixada em qualquer bit; ela é indicada pelo tamanho do prefixo de rede, após uma barra:

  • 193.49.144.0/24: os primeiros 24 bits designam a rede e os últimos 8 bits designam o nó. Essa rede contém os endereços de 193.49.144.0 a 193.49.144.255;
  • 10.0.0.0/8: uma rede com 2²⁴ endereços;
  • 192.168.1.0/26: uma rede de 2⁶ = 64 endereços, de 192.168.1.0 a 192.168.1.63.

Ainda se usa a notação antiga da máscara de sub-rede, que expressa a mesma coisa: o prefixo /24 corresponde à máscara 255.255.255.0. Os termos "classe A, B, C" continuam de uso corrente, mas já não correspondem a nenhum mecanismo real.

12.1.5.2. Endereços reservados, endereços privados e NAT

Certos endereços têm uma finalidade específica:

  • um endereço cuja parte de host é formada inteiramente por 0s designa a própria rede: 193.49.144.0 é o endereço da rede 193.49.144.0/24;
  • um endereço cuja parte de host é formada inteiramente por 1s é um endereço de broadcast: 193.49.144.255 designa todos os hosts da rede 193.49.144.0/24. Esses dois endereços não podem, portanto, ser atribuídos a um nó: uma rede /24 com 256 endereços oferece apenas 254 endereços utilizáveis;
  • os endereços 127.0.0.0/8 e, na prática, 127.0.0.1, são endereços de loopback: uma máquina os usa para se referir a si mesma sem passar pela rede. O nome [localhost] está associado a eles;
  • os blocos 10.0.0.0/8, 172.16.0.0/12 e 192.168.0.0/16 (RFC 1918) são reservados para redes privadas: podem ser usados livremente dentro de uma empresa ou de uma residência, mas não são roteados na Internet;
  • os blocos 192.0.2.0/24, 198.51.100.0/24 e 203.0.113.0/24 (RFC 5737) são reservados para documentação e exemplos.

O número de endereços IPv4 (2³², pouco mais de 4 bilhões) é insuficiente para todas as máquinas conectadas. O estoque central de endereços da IANA se esgotou em 2011, e o do RIPE NCC, em 2019. A escassez foi contornada pela tradução de endereços de rede (NAT, Network Address Translation): os dispositivos de uma residência têm endereços privados (como 192.168.1.x), e o roteador que os conecta à Internet os "traduz" para o seu próprio endereço público, único. A solução de longo prazo é o IPv6.

12.1.5.3. Os endereços IPv6

O IPv6 (RFC 2460 em 1998, hoje RFC 8200) codifica os endereços em 128 bits, o que oferece 2¹²⁸ endereços possíveis, aproximadamente 3,4 × 10³⁸, de modo que não há mais motivo para se preocupar com escassez. Um endereço IPv6 é escrito como oito grupos de quatro dígitos hexadecimais separados por dois-pontos:

2001:0db8:0000:0000:8a2e:0000:0370:7334

Os zeros à esquerda de cada grupo podem ser omitidos, e uma única sequência de grupos de zeros pode ser substituída por [::]. O endereço anterior é, portanto, escrito como [2001:db8::8a2e:0:370:7334]. O endereço de loopback, equivalente a 127.0.0.1, é [::1]. Em uma URL, o endereço IPv6 é colocado entre colchetes para evitar que seus dois-pontos sejam confundidos com o que precede a porta: [http://[::1]:8080/].

O IPv6 traz outras simplificações: o cabeçalho do pacote tem tamanho fixo, a configuração automática de endereços é nativa e a tradução de endereços NAT deixa de ser necessária. Sua adoção tem sido lenta, mas uma parcela significativa e crescente do tráfego da Internet já passa pelo IPv6 (o Google, por exemplo, publica a proporção de seus usuários que o acessam via IPv6), e os principais provedores de acesso franceses o oferecem a seus assinantes. As duas versões coexistem: a maioria das máquinas tem endereços IPv4 e IPv6 (fala-se em "dual stack"), e os programas devem ser capazes de lidar com ambos.

12.1.5.4. Protocolos de conversão de endereços: IP ↔ endereço físico

Vimos que, quando dados são transmitidos de uma máquina para outra, ao passar pela camada IP eles são encapsulados em pacotes. Esses pacotes têm a seguinte forma:

Image

O pacote IP contém, portanto, os endereços IP das máquinas de origem e de destino. Quando esse pacote é repassado à camada responsável por enviá-lo pela rede física, são acrescentadas informações adicionais para formar o quadro físico que será enviado, de fato, pela rede. Por exemplo, o formato de um quadro em uma rede Ethernet é o seguinte:

Image

Os primeiros 8 bytes (preâmbulo) servem para sincronização; o campo de 2 bytes que precede os dados indica, na forma mais comum do quadro Ethernet, o tipo de protocolo transportado (IPv4, IPv6, ARP…) em vez do comprimento do pacote. No quadro final, estão os endereços físicos das máquinas de origem e de destino (no quadro real, o endereço de destino precede o de origem, ao contrário da ordem mostrada no diagrama). Como obtê-los?

A máquina emissora, conhecendo o endereço IP da máquina com a qual quer se comunicar, obtém o endereço físico dessa máquina por meio do protocolo ARP (Address Resolution Protocol):

  • ela envia um tipo especial de pacote, chamado pacote ARP, contendo o endereço IP da máquina cujo endereço físico se procura. O pacote inclui também o próprio endereço IP da emissora, bem como o seu endereço físico;
  • esse pacote é enviado a todos os nós da rede local (broadcast);
  • esses nós reconhecem a natureza especial do pacote. O nó que reconhece o seu endereço IP no pacote responde enviando ao emissor o seu endereço físico. Ele consegue fazer isso porque encontrou no pacote o endereço IP e o endereço físico do emissor;
  • O emissor recebe, assim, o endereço físico que procurava. Ele o guarda em um cache para poder usá-lo depois, caso outros pacotes precisem ser enviados ao mesmo destinatário.

No IPv6, o mesmo serviço é fornecido pelo protocolo NDP (Neighbor Discovery Protocol), que se baseia em mensagens ICMPv6.

Resta a questão: como uma máquina conhece o seu próprio endereço IP? Ele pode ser informado em um arquivo de configuração da máquina, o que ainda é a prática para servidores. Mas, quando um administrador precisa reorganizar a rede, modificar um a um os arquivos de configuração de todas as máquinas é trabalhoso e sujeito a erros. O protocolo RARP permitia que uma máquina solicitasse a um servidor o seu endereço IP a partir do seu endereço físico. Ele foi substituído pelo DHCP (Dynamic Host Configuration Protocol, RFC 2131): ao iniciar, a máquina envia uma solicitação em broadcast pela rede; um servidor (como um roteador doméstico ou um servidor dedicado em uma empresa) lhe atribui um endereço por um tempo limitado (uma concessão, ou lease), junto com o restante da sua configuração: prefixo de rede, endereço do roteador e endereços dos servidores DNS. O administrador só precisa, então, configurar o servidor DHCP. No IPv6, uma máquina também pode construir o seu próprio endereço a partir do prefixo anunciado pelo roteador (autoconfiguração SLAAC).

12.1.6. A camada de rede, chamada de camada IP, da Internet

O protocolo IP define o formato que os pacotes devem ter e como devem ser tratados ao serem enviados ou recebidos. Esse tipo particular de pacote é chamado de datagrama IP. Já falamos sobre ele:

Image

O ponto importante é que, além dos dados a transmitir, o datagrama IP contém os endereços IP das máquinas de origem e de destino. Assim, a máquina de destino sabe quem lhe está enviando uma mensagem.

Ao contrário de um quadro de rede, cujo comprimento é determinado pelas características físicas da rede pela qual ele trafega, o comprimento do datagrama IP é definido pelo software e será, portanto, o mesmo em diferentes redes físicas. Vimos que, ao descer da camada de rede para a camada física, o datagrama IP é encapsulado em um quadro físico.

Os quadros físicos trafegam de nó em nó em direção ao destino, que pode não estar na mesma rede física que a máquina emissora. O pacote IP pode, portanto, ser encapsulado sucessivamente em diferentes quadros físicos nos nós que conectam duas redes de tipos diferentes. Também é possível que o pacote IP seja grande demais para ser encapsulado em um quadro físico (a carga útil de um quadro Ethernet é limitada a 1.500 bytes). No IPv4, o nó em que esse problema ocorre divide então o pacote IP em fragmentos, que só serão remontados no destino final. No IPv6, os roteadores não fragmentam mais os pacotes: cabe ao emissor determinar o tamanho máximo aceito ao longo do caminho e ajustar de acordo com ele o tamanho de seus pacotes.

12.1.6.1. Roteamento

Roteamento é o método de encaminhar pacotes IP até o destino. Há dois métodos: roteamento direto e roteamento indireto.

Roteamento direto

O roteamento direto consiste na transmissão de um pacote IP diretamente do emissor ao destinatário dentro da mesma rede:

  • a máquina que envia um datagrama IP possui o endereço IP do destinatário;
  • ela obtém o endereço físico do destinatário por meio do protocolo ARP, ou do seu cache, se esse endereço já tiver sido obtido;
  • ela envia o pacote pela rede a esse endereço físico.

Roteamento indireto

O roteamento indireto consiste na transmissão de um pacote IP a um destino localizado em uma rede diferente daquela a que o emissor pertence. Nesse caso, as partes de "rede" dos endereços IP das máquinas de origem e de destino são diferentes; a máquina de origem detecta isso comparando o endereço de destino com o seu próprio prefixo de rede. Ela envia então o pacote a um nó especial chamado roteador, que conecta a rede local a outras redes e cujo endereço IP é conhecido pela máquina de origem (é o chamado gateway padrão, normalmente fornecido pelo DHCP). Um roteador é conectado a pelo menos duas redes e tem um endereço IP em cada uma delas:

Image

No nosso exemplo acima:

  • A rede nº 1 tem o endereço 193.49.144.0/24 e a rede nº 2 tem o endereço 193.49.145.0/24;
  • na rede nº 1, o roteador tem o endereço 193.49.144.6 e, na rede nº 2, tem o endereço 193.49.145.3.

O papel do roteador é pegar o pacote IP que recebe, contido em um quadro físico da rede nº 1, e colocá-lo em um quadro físico que possa trafegar pela rede nº 2. Se o endereço IP de destino do pacote estiver na rede nº 2, o roteador envia o pacote diretamente a ele; caso contrário, envia-o a outro roteador que conecta a rede nº 2 à rede nº 3, e assim por diante. Os roteadores da Internet trocam constantemente informações sobre as redes que conseguem alcançar (protocolos de roteamento, como o BGP entre operadoras) para construir suas tabelas de roteamento.

12.1.6.2. Mensagens de erro e de controle

Também na camada de rede, e portanto no mesmo nível do protocolo IP, está o protocolo ICMP (Internet Control Message Protocol). Ele serve para enviar mensagens sobre o funcionamento interno da rede: nó inacessível, pacote que atravessou roteadores demais etc. As mensagens ICMP são encapsuladas em pacotes IP e enviadas pela rede. As camadas IP dos diversos nós tomam as medidas apropriadas com base nas mensagens ICMP que recebem. Assim, uma aplicação nunca vê esses problemas específicos da rede. Os comandos [ping] (que enviam mensagens ICMP "Echo Request" e aguardam mensagens "Echo Reply") e [traceroute] / [tracert] (que exibe os roteadores atravessados) se baseiam no ICMP.

12.1.7. A camada de transporte: os protocolos UDP e TCP

12.1.7.1. O protocolo UDP: User Datagram Protocol

O protocolo UDP permite uma troca de dados não confiável entre dois pontos; ou seja, não há garantia de que um pacote seja entregue com sucesso ao destino, nem da ordem em que os pacotes chegam. A aplicação, se quiser, pode cuidar disso por conta própria, por exemplo aguardando uma confirmação depois de enviar uma mensagem antes de enviar a seguinte.

Até aqui, no nível da rede, falamos de endereços de máquinas como o IP. No entanto, em uma mesma máquina podem coexistir diferentes processos ao mesmo tempo, e todos eles podem se comunicar entre si. Portanto, ao enviar uma mensagem, é preciso especificar não só o endereço IP da máquina de destino, mas também o "nome" do processo de destino. Esse nome é, na verdade, um número de 16 bits (de 1 a 65.535), chamado de número de porta. Certos números são reservados para aplicações padrão: porta 53 para DNS, 80 para HTTP, 443 para HTTPS, 25 para SMTP e assim por diante. As portas abaixo de 1024 são chamadas de "bem conhecidas" (well-known); no Linux, são necessários privilégios especiais para iniciar um serviço em uma delas. Os exemplos deste capítulo usam portas nas faixas 27100–27199 e 27200–27299.

Os pacotes tratados pelo protocolo UDP são chamados de datagramas. Eles têm a seguinte forma:

Image

Esses datagramas são encapsulados em pacotes IP e, depois, em quadros físicos. O UDP é usado quando a velocidade é mais importante que a confiabilidade, ou quando a aplicação trata ela mesma as perdas: DNS (uma pergunta, uma resposta), streaming de áudio e vídeo ao vivo, jogos online e o protocolo QUIC do HTTP/3.

12.1.7.2. O protocolo TCP: Transmission Control Protocol

Para comunicações seguras, o protocolo UDP é insuficiente: o desenvolvedor da aplicação precisa criar por conta própria um protocolo para verificar se os pacotes são encaminhados corretamente. O protocolo TCP evita esses problemas. Suas características são as seguintes:

  • O processo que deseja transmitir dados primeiro estabelece uma conexão com o processo que receberá as informações a serem transmitidas. Essa conexão é estabelecida entre uma porta da máquina emissora e uma porta da máquina receptora por meio da troca de três segmentos (SYN, SYN-ACK, ACK: o "handshake de três vias"). Cria-se assim um circuito virtual entre as duas portas, reservado exclusivamente aos dois processos que estabeleceram a conexão;
  • todos os bytes transmitidos pelo processo de origem chegam ao destino na ordem em que foram enviados, o que não é garantido pelo protocolo UDP, já que os pacotes podem seguir caminhos diferentes;
  • As informações transmitidas aparecem de forma contínua: trata-se de um fluxo de bytes. O processo emissor transmite as informações em seu próprio ritmo. Essas informações não são necessariamente enviadas imediatamente: o protocolo TCP pode esperar até ter dados suficientes para enviar. Elas são colocadas em uma estrutura chamada segmento TCP. Quando esse segmento está cheio, ele é transmitido à camada IP, onde é encapsulado em um pacote IP. Uma implicação importante para o programador: uma "linha" enviada de uma só vez pode chegar em vários pedaços, e várias linhas podem chegar juntas. Cabe à aplicação identificar os limites de suas mensagens (usaremos o caractere de fim de linha para isso);
  • Cada segmento enviado pelo protocolo TCP é numerado. O protocolo TCP receptor verifica se está recebendo os segmentos em sequência. Para cada segmento recebido corretamente, ele envia uma confirmação (acknowledgment) ao emissor;
  • se, após um certo tempo, o protocolo TCP que enviou um segmento não receber uma confirmação, ele retransmite o segmento em questão, garantindo assim a qualidade do serviço de entrega das informações;
  • O circuito virtual estabelecido entre os dois processos que se comunicam é full-duplex: as informações podem trafegar nos dois sentidos simultaneamente. Assim, o processo de destino pode enviar confirmações mesmo enquanto o processo de origem continua enviando informações. Isso permite, por exemplo, que o protocolo TCP de origem envie vários segmentos sem esperar confirmações. Se, após um certo tempo, ele perceber que não recebeu a confirmação de um segmento específico nº n, retomará o envio dos segmentos a partir desse ponto;
  • O TCP também regula a sua taxa de dados para evitar sobrecarregar o destinatário (controle de fluxo) ou a rede (controle de congestionamento).

12.1.8. A camada de aplicação

Acima dos protocolos UDP e TCP há diversos protocolos padrão:

TELNET e SSH

O TELNET permite que um usuário da máquina A se conecte à máquina B (frequentemente chamada de máquina host) como se tivesse um terminal conectado a ela. O TELNET se baseia no TCP. Suas trocas de dados, inclusive senhas, são transmitidas em texto puro: ele foi substituído pelo SSH (Secure Shell), que fornece o mesmo serviço de forma criptografada e também é usado para a transferência segura de arquivos (SFTP, SCP) e para a criação de túneis. O programa cliente [telnet] há muito tempo é uma ferramenta conveniente para se comunicar "manualmente" com um servidor TCP: veremos como substituí-lo.

FTP (File Transfer Protocol)

Esse protocolo permite a troca de arquivos entre duas máquinas remotas, bem como operações com arquivos, como a criação de diretórios. Ele se baseia no protocolo TCP. Como o TELNET, transmite senhas em texto puro; está sendo abandonado em favor do SFTP e do HTTPS.

TFTP (Trivial File Transfer Protocol)

Esse protocolo é uma variante simplificada do FTP. Ele se baseia no protocolo UDP. Ainda é usado para inicializar máquinas pela rede.

DNS (Domain Name System)

Quando um usuário quer trocar informações com uma máquina remota, precisa conhecer o endereço IP dessa máquina. É muito mais conveniente referir-se a uma máquina por um nome do que pelo seu endereço IP. Surge então a questão da unicidade dos nomes: há bilhões de máquinas interconectadas. Poderíamos imaginar uma autoridade centralizada atribuindo os nomes, mas isso seria muito pesado. O controle sobre os nomes foi distribuído por domínios. Cada domínio é gerenciado por uma organização que tem plena liberdade para escolher nomes dentro do seu domínio. Assim, as máquinas na França costumam pertencer ao domínio [fr], gerenciado pela AFNIC (o INRIA o gerenciava até a criação da AFNIC em 1997). Para simplificar ainda mais, o controle é descentralizado em níveis adicionais: criam-se domínios dentro do domínio [fr]. Por exemplo, a Universidade de Angers possui o domínio [univ-angers.fr]; o departamento que o administra tem plena liberdade para nomear os computadores da rede da universidade e para criar subdomínios.

O nome completo de uma máquina (FQDN, Fully Qualified Domain Name) especifica a hierarquia de domínios a que ela pertence, do mais específico ao mais geral: [www.univ-angers.fr]. Dentro de um domínio, muitas vezes é possível usar nomes relativos, que são completados automaticamente pelo sistema.

Uma aplicação pode, portanto, referir-se a uma máquina pelo nome. No fim das contas, porém, ainda é preciso obter o endereço IP dessa máquina. Suponha que você queira se comunicar da máquina A com a máquina B:

  • A máquina A consulta primeiro um arquivo de mapeamento local ([/etc/hosts] no Linux e no macOS, [C:\Windows\System32\drivers\etc\hosts] no Windows) e, depois, o seu cache;
  • caso contrário, consulta o servidor DNS, cujo endereço consta em sua configuração (normalmente fornecido pelo DHCP). Ela envia uma solicitação DNS contendo o nome da máquina procurada. Se o servidor consultado souber a resposta ou a tiver em cache, devolve o endereço IP correspondente à máquina A. Caso contrário, ele consulta por sua vez, a partir dos servidores raiz, os servidores responsáveis pelo domínio [fr], depois por [univ-angers.fr] e assim por diante, até obter a resposta, que será então repassada de volta até a máquina A.

O domínio DNS associa vários tipos de registros a um nome: A (endereço IPv4), AAAA (endereço IPv6), CNAME (alias para outro nome), MX (servidores de e-mail do domínio) etc.

HTTP e HTTPS (HyperText Transfer Protocol)

Este é o protocolo da Web e, de longe, o mais usado hoje: não só pelos navegadores, mas também por aplicações que trocam dados (os serviços web tratados no próximo capítulo). Vamos examiná-lo em detalhe. O HTTPS é o HTTP transmitido por uma conexão criptografada por TLS (Transport Layer Security); essa é hoje a forma padrão da Web.

SMTP, POP3 e IMAP

O SMTP serve para enviar e-mails, enquanto o POP3 e o IMAP servem para ler e-mails armazenados em um servidor. Também falaremos sobre eles.

XDR, RPC, NFS

Por fim, vamos mencionar três protocolos definidos pela Sun Microsystems, a empresa que criou o Java: o XDR (eXternal Data Representation), que especifica uma representação de dados padrão, independente da máquina; o RPC (Remote Procedure Call), um protocolo de chamada de procedimento remoto baseado no XDR; e o NFS (Network File System), que permite que uma máquina "enxergue" o sistema de arquivos de outra e se baseia no RPC. O NFS continua em uso no mundo Unix. O conceito de chamada de procedimento remoto foi adotado por muitos sucessores; hoje, estes incluem os serviços web REST (baseados em HTTP) e o gRPC (baseado em HTTP/2).

12.1.9. Conclusão

Nesta introdução, apresentamos algumas das principais características dos protocolos da Internet. Para explorar esse campo com mais profundidade, o leitor pode consultar a obra de referência de Douglas Comer, *Internetworking with TCP/IP, Volume 1 ” (Pearson, 6ª edição), cujas edições anteriores foram traduzidas para o francês, bem como as RFCs citadas neste capítulo. Para o HTTP, a documentação da Mozilla em developer.mozilla.org/en-US/docs/Web/HTTP é uma excelente introdução.

12.2. Classes Java para o gerenciamento de endereços IP

Uma máquina na Internet é identificada por um endereço IP, que pode assumir duas formas:

  • IPv4: codificado em 32 bits e representado por uma string da forma "I1.I2.I3.I4", em que In é um número entre 0 e 255;
  • IPv6: codificado em 128 bits e representado por uma string de oito grupos de dígitos hexadecimais separados por dois-pontos, como "2001:db8::8a2e:370:7334". Hoje não podemos mais ignorar esses endereços: nossos programas os aceitarão.

Uma máquina também pode ser identificada por um nome. Esse nome não é obrigatório, pois as aplicações usam, no fim das contas, sempre os endereços IP das máquinas. Os nomes existem para facilitar a vida dos usuários: é mais fácil pedir a um navegador a URL [https://dev.java] do que a URL formada a partir de um dos endereços IP desse site, que, aliás, muda conforme o local de onde a solicitação é feita.

Uma máquina pode ter vários endereços IP: um endereço de loopback, um endereço por rede à qual está conectada, e endereços IPv4 e IPv6.

Um endereço IP pode ser representado de duas maneiras em Java:

  • como uma string como "I1.I2.I3.I4" ou "2001:db8::1";
  • como um objeto do tipo [InetAddress] (pacote [java.net], importado automaticamente em um arquivo-fonte compacto, pois faz parte do módulo [java.base]).

A classe InetAddress

A classe [InetAddress] não tem construtor público: suas instâncias são criadas por métodos estáticos construtores. Ela tem duas classes derivadas, [Inet4Address] e [Inet6Address], uma para cada versão do IP. Entre seus métodos estão os seguintes:

Método
Função
static InetAddress ofLiteral(String string)
(Java 22) converte um endereço IPv4 ou IPv6 escrito em dígitos em um objeto [InetAddress], sem nunca consultar o DNS; lança uma [IllegalArgumentException] se a string não for um endereço IP. [Inet4Address.ofLiteral] e [Inet6Address.ofLiteral] aceitam apenas uma das duas versões
static InetAddress getByName(String nameOrAddress)
retorna o endereço de uma máquina identificada pelo seu nome ou pelo seu endereço IP. Se a string não for um endereço IP, o nome é procurado no DNS; lança uma [UnknownHostException] se a máquina não for encontrada
static InetAddress[] getAllByName(String nameOrAddress)
Igual ao anterior, mas retorna todos os endereços IP da máquina
static InetAddress getLocalHost()
o endereço da máquina em que o programa está sendo executado, junto com o seu nome
static InetAddress getLoopbackAddress()
o endereço de loopback (127.0.0.1 ou ::1). Um serviço associado a esse endereço aceita apenas clientes situados na mesma máquina que ele
byte[] getAddress()
retorna os bytes do endereço (4 no IPv4, 16 no IPv6)
String getHostAddress()
retorna o endereço em forma de texto
String getHostName(), String getCanonicalHostName()
o nome da máquina; se o objeto foi criado a partir de um endereço IP, esse nome é obtido por uma consulta "reversa" no DNS (se essa consulta falhar, retorna-se o próprio endereço)
boolean isLoopbackAddress(), isSiteLocalAddress(), isAnyLocalAddress()…
retornam [true] se o endereço for um endereço de loopback, um endereço privado (10.x.y.z, de 172.16.x.y a 172.31.x.y, 192.168.x.y), o endereço "curinga" (wildcard) 0.0.0.0 ou :: …

Duas outras classes complementam [InetAddress]:

  • [InetSocketAddress] representa um ponto de conexão: um endereço IP e um número de porta. Seus métodos [getAddress] e [getPort] fornecem essas duas informações. O construtor [InetSocketAddress(int port)] associa a porta ao endereço curinga 0.0.0.0, que designa todos os endereços da máquina;
  • [NetworkInterface] representa uma interface de rede da máquina (uma placa Ethernet, uma placa Wi-Fi, a interface de loopback etc.), junto com os seus endereços IP.

O Java, porém, não tem uma classe que represente uma rede em notação CIDR, como 193.49.144.0/24: nós mesmos a escreveremos. O programa [Internet01.java] ilustra essas classes:

// as classes InetAddress e InetSocketAddress; uma rede em notação CIDR

void main() {
    // endereços IPv4 e IPv6, corretos ou não
    List<String> addresses = List.of("193.49.144.1", "127.0.0.1", "192.168.1", "::1",
            "2001:db8::8a2e:370:7334", "256.1.1.1", "machine");
    for (String string : addresses) {
        try {
            // ofLiteral (Java 22): análise de um endereço IP escrito em algarismos, sem consultar o DNS
            InetAddress address = InetAddress.ofLiteral(string);
            String family = address instanceof Inet4Address ? "IPv4" : "IPv6";
            byte[] bytes = address.getAddress();
            String hex = HexFormat.of().withUpperCase().formatHex(bytes);
            IO.println("[%s] -> %s (%s, %d bytes: %s, loopback: %b, private: %b)".formatted(string,
                    address.getHostAddress(), family, bytes.length, hex,
                    address.isLoopbackAddress(), address.isSiteLocalAddress()));
        } catch (IllegalArgumentException e) {
            IO.println("[" + string + "] is not an IP address");
        }
    }

    // getByName aceita um endereço IP ou um nome de máquina: este último é procurado no DNS
    try {
        InetAddress.getByName("256.1.1.1");
    } catch (UnknownHostException e) {
        IO.println("getByName(\"256.1.1.1\") : " + e.getClass().getSimpleName() + " : " + e.getMessage());
    }

    // o endereço de loopback e o endereço curinga (todos os endereços da máquina)
    IO.println("Loopback=" + InetAddress.getLoopbackAddress());
    IO.println("Wildcard=" + new InetSocketAddress(27100).getAddress());

    // um ponto de conexão = um endereço IP + uma porta
    var point = new InetSocketAddress(InetAddress.getLoopbackAddress(), 27100);
    IO.println("InetSocketAddress: %s (address=%s, port=%d)".formatted(point,
            point.getAddress().getHostAddress(), point.getPort()));
    var point6 = new InetSocketAddress(InetAddress.ofLiteral("::1"), 27100);
    IO.println("InetSocketAddress IPv6: %s (address=%s, port=%d)".formatted(point6,
            point6.getAddress().getHostAddress(), point6.getPort()));

    // uma rede em notação CIDR: endereço da rede / comprimento do prefixo
    Network network = Network.parse("193.49.144.0/24");
    for (String string : List.of("193.49.144.1", "193.49.145.3")) {
        boolean belongs = network.contains(InetAddress.ofLiteral(string));
        IO.println(string + " belongs to " + network + ": " + belongs);
    }
}

// uma rede IP: o endereço da rede e o comprimento de seu prefixo (o Java não tem classe para isso)
record Network(InetAddress address, int prefix) {

    // análise de uma string da forma address/prefix
    static Network parse(String cidr) {
        String[] fields = cidr.split("/");
        return new Network(InetAddress.ofLiteral(fields[0]), Integer.parseInt(fields[1]));
    }

    // um endereço pertence à rede se seus primeiros [prefix] bits forem os da rede
    boolean contains(InetAddress machine) {
        byte[] r = address.getAddress();
        byte[] m = machine.getAddress();
        if (r.length != m.length) {
            return false;
        }
        for (int bit = 0; bit < prefix; bit++) {
            // bit nº [bit] do endereço, a partir do bit mais significativo do primeiro byte
            int mask = 0x80 >> (bit % 8);
            if ((r[bit / 8] & mask) != (m[bit / 8] & mask)) {
                return false;
            }
        }
        return true;
    }

    @Override
    public String toString() {
        return address.getHostAddress() + "/" + prefix;
    }
}

Resultados:

> java Internet01.java
[193.49.144.1] -> 193.49.144.1 (IPv4, 4 bytes: C1319001, loopback: false, private: false)
[127.0.0.1] -> 127.0.0.1 (IPv4, 4 bytes: 7F000001, loopback: true, private: false)
[192.168.1] -> 192.168.0.1 (IPv4, 4 bytes: C0A80001, loopback: false, private: true)
[::1] -> 0:0:0:0:0:0:0:1 (IPv6, 16 bytes: 00000000000000000000000000000001, loopback: true, private: false)
[2001:db8::8a2e:370:7334] -> 2001:db8:0:0:0:8a2e:370:7334 (IPv6, 16 bytes: 20010DB80000000000008A2E03707334, loopback: false, private: false)
[256.1.1.1] is not an IP address
[machine] is not an IP address
getByName("256.1.1.1") : UnknownHostException : 256.1.1.1: Name or service not known
Loopback=localhost/127.0.0.1
Wildcard=0.0.0.0/0.0.0.0
InetSocketAddress: localhost/127.0.0.1:27100 (address=127.0.0.1, port=27100)
InetSocketAddress IPv6: /[0:0:0:0:0:0:0:1]:27100 (address=0:0:0:0:0:0:0:1, port=27100)
193.49.144.1 belongs to 193.49.144.0/24: true
193.49.145.3 belongs to 193.49.144.0/24: false

Comentários:

  • linhas 5–6: as strings a serem analisadas;
  • linha 10: [InetAddress.ofLiteral] (Java 22) converte a string em um objeto [InetAddress] se for um endereço IPv4 ou IPv6 e lança uma [IllegalArgumentException] caso contrário (linha 17);
  • linha 11: o operador [instanceof] distingue as duas versões do IP: o objeto retornado é uma instância de [Inet4Address] ou de [Inet6Address];
  • linhas 12–13: [getAddress] devolve os bytes do endereço, que a classe [HexFormat] (Java 17) exibe em hexadecimal. Vemos (linha 2 dos resultados) que 193.49.144.1 é formado pelos quatro bytes C1, 31, 90, 01 e (linha 5) que ::1 é formado por 15 bytes zero seguidos de um byte com valor 1;
  • linha 16: [isLoopbackAddress] e [isSiteLocalAddress] reconhecem os endereços de loopback e os endereços privados da RFC 1918;
  • linha 4 dos resultados: uma surpresa. A string "192.168.1" foi aceita e convertida em 192.168.0.1. [ofLiteral] aceita, de fato, as formas abreviadas históricas dos endereços IPv4 (nas quais o último número ocupa todos os bytes restantes). Para verificar que uma entrada é um endereço IPv4 completo, é preciso, portanto, verificar também que ela contém quatro números;
  • linhas 5–6 dos resultados: os endereços IPv6 são reexibidos por [getHostAddress] na forma completa, sem a abreviação [::] nem os zeros à esquerda: [0:0:0:0:0:0:0:1] para [::1]. O prefixo 2001:db8::/32 é, como 192.0.2.0/24 no IPv4, reservado para documentação;
  • linhas 23–27: o método mais antigo [getByName] aceita um endereço IP ou um nome de host. Como a string "256.1.1.1" não é um endereço IP válido (256 não cabe em um único byte), [getByName] a interpreta como um nome de máquina e consulta o DNS, que não a reconhece: o resultado é uma [UnknownHostException] (linha 9 dos resultados). [ofLiteral] foi acrescentado no Java 22 para evitar essa consulta inesperada ao DNS. A mensagem da exceção aqui vem da biblioteca de sistema do Linux;
  • linha 30: o endereço de loopback. Quando um objeto [InetAddress] é exibido por [toString], ele assume a forma [name/address], com o nome vazio se for desconhecido;
  • linha 31: o endereço curinga 0.0.0.0, obtido aqui por um [InetSocketAddress] sem endereço;
  • linhas 34–39: objetos [InetSocketAddress] que associam um endereço e uma porta. Eles são exibidos (linhas 12–13 dos resultados) na forma [name/address:port]; no IPv6, o endereço é colocado entre colchetes;
  • linhas 50–79: um record ([record], Capítulo 4) que representa uma rede em notação CIDR. Em um arquivo-fonte compacto, ele pode ser declarado logo após o método [main];
  • linhas 53–56: o método estático [parse] analisa uma string da forma [address/prefix];
  • linhas 59–73: um endereço pertence à rede se os seus primeiros [prefix] bits coincidirem com os do endereço da rede. O bit de número [bit] está no byte de número [bit / 8]; a máscara [0x80 >> (bit % 8)] o isola dentro desse byte. As linhas 14–15 dos resultados mostram que 193.49.144.1 pertence à rede 193.49.144.0/24 e que 193.49.145.3 (o endereço do roteador em nosso diagrama, em sua segunda rede) não pertence a ela. Esse é exatamente o teste que uma máquina realiza para escolher entre roteamento direto e indireto.

O DNS e as interfaces de rede

A correspondência entre o identificador IP e o nome da máquina é tratada pelo DNS. Ele é consultado pelos métodos estáticos [getByName] e [getAllByName] de [InetAddress], já descritos; no sentido inverso, [getHostName] e [getCanonicalHostName] realizam uma consulta reversa. Esses métodos são bloqueantes: uma solicitação DNS pode levar várias dezenas de milissegundos, ou até vários segundos se um servidor não responder, e durante esse tempo a thread chamadora fica bloqueada. O Java não oferece uma versão assíncrona desses métodos; desde o Java 21, a solução é simplesmente chamá-los em uma thread virtual (Capítulo 8), o que quase não gera custo durante a espera. Desde o Java 18, também é possível substituir o mecanismo de resolução de nomes usado por *[InetAddress] fornecendo a sua própria implementação da interface *[InetAddressResolver] , o que é útil para testes.

A classe [NetworkInterface], com o seu método estático [networkInterfaces], retorna um stream ([Stream]) das interfaces de rede da máquina; para cada uma, [getName] retorna o seu nome, [isUp] indica se ela está ativa e [inetAddresses] retorna um stream de seus endereços (IP).

O programa [Internet02.java] exibe o nome e as interfaces de rede da máquina em que está sendo executado e, em seguida, fornece de forma interativa as correspondências entre o nome da máquina e os endereços IP:

// exibe o nome e as interfaces de rede da máquina local
// depois fornece, de forma interativa, informações sobre as máquinas da rede
// identificadas por um nome ou um endereço IP

void main() throws IOException {
    // máquina local
    InetAddress local = InetAddress.getLocalHost();
    IO.println("Local machine = " + local.getHostName() + " (" + local.getHostAddress() + ")");
    // suas interfaces de rede ativas, com seus endereços
    for (NetworkInterface card : NetworkInterface.networkInterfaces().filter(this::active).toList()) {
        String ips = card.inetAddresses().map(InetAddress::getHostAddress).collect(Collectors.joining(", "));
        IO.println("Interface " + card.getName() + " : " + ips);
    }

    // perguntas e respostas interativas
    while (true) {
        // entrada do nome ou do endereço IP da máquina procurada
        String input = IO.readln("Machine looked for (nothing to stop): ");
        String machine = input == null ? "" : input.strip().toLowerCase();
        // terminou?
        if (machine.isEmpty()) {
            break;
        }
        try {
            // consulta ao DNS: todos os endereços IP da máquina
            InetAddress[] addresses = InetAddress.getAllByName(machine);
            // o nome da máquina: consulta reversa se um endereço IP foi informado
            IO.println("Machine: " + addresses[0].getHostName());
            // seus endereços IP
            String ips = Arrays.stream(addresses).map(InetAddress::getHostAddress)
                    .collect(Collectors.joining(", "));
            IO.println("IP addresses: " + ips);
        } catch (UnknownHostException e) {
            // a máquina não foi encontrada
            IO.println("Unable to find the machine [" + machine + "] : " + e.getMessage());
        }
    }
}

// uma interface de rede está ativa? (isUp pode lançar uma SocketException)
boolean active(NetworkInterface card) {
    try {
        return card.isUp();
    } catch (SocketException e) {
        return false;
    }
}

Resultados:

> java Internet02.java
Local machine = vm (127.0.0.1)
Interface eth0 : 192.0.2.2
Interface lo : 127.0.0.1
Machine looked for (nothing to stop): localhost
Machine: localhost
IP addresses: 127.0.0.1
Machine looked for (nothing to stop): vm
Machine: vm
IP addresses: 127.0.0.1
Machine looked for (nothing to stop): 127.0.0.1
Machine: localhost
IP addresses: 127.0.0.1
Machine looked for (nothing to stop): ::1
Machine: 0:0:0:0:0:0:0:1
IP addresses: 0:0:0:0:0:0:0:1
Machine looked for (nothing to stop): xx
Unable to find the machine [xx] : xx: Name or service not known
Machine looked for (nothing to stop): 

Comentários:

  • linhas 7–8: o nome e o endereço da máquina local. Nossa máquina de teste é uma máquina virtual Linux chamada [vm]; para o leitor, será, naturalmente, o nome do seu próprio computador;
  • linhas 10–13: as interfaces de rede ativas e seus endereços. O filtro [filter(this::active)] usa uma referência ao método [active] do objeto atual (Capítulo 7); não é possível escrever [isUp] diretamente em uma referência de método, porque ele lança uma exceção verificada ([SocketException]), que a interface funcional [Predicate] não permite: o método [active] (linhas 41–47) a intercepta;
  • linha 18: [IO.readln] (Java 25) exibe o prompt e lê uma linha do teclado; retorna [null] se a entrada padrão estiver fechada;
  • linha 26: a consulta ao DNS. Se o nome (ou endereço) for desconhecido, uma [UnknownHostException] é lançada (linha 33);
  • linha 28: o nome da máquina. Se um endereço IP foi fornecido, [getHostName] realiza uma consulta reversa;
  • linhas 30–31: os endereços da máquina são combinados em uma única string pela API Stream.

Os resultados merecem alguns comentários. Eles dependem da configuração da máquina: não espere obter exatamente os mesmos resultados em seu próprio sistema.

  • Linhas 2–4: a máquina de teste tem duas interfaces ativas: [eth0], conectada à rede, e [lo], a interface de loopback. O nome da máquina está associado ao endereço 127.0.0.1 pelo arquivo [/etc/hosts];
  • linhas 5–7: o nome [localhost] corresponde ao endereço de loopback 127.0.0.1. Em uma máquina em que o IPv6 esteja ativo, ::1 também seria retornado;
  • linha 12: com o endereço IP, [getHostName] realizou uma consulta reversa e retornou o nome associado ao endereço;
  • linha 15: a consulta reversa de ::1 falhou porque o arquivo [/etc/hosts] de nossa máquina de teste não associa nenhum nome a esse endereço; [getHostName] retornou o próprio endereço. No Windows, o nome da máquina seria retornado;
  • linha 18: o nome [xx] é desconhecido. A mensagem da exceção vem da biblioteca de sistema do Linux; seria diferente no Windows.

Em uma máquina conectada à Internet, também é possível consultar um nome público como [dev.java]. Isso retorna endereços que variam conforme o local e o momento da consulta. Não reproduzimos esse resultado, pois nossa máquina de teste não tem acesso à Internet.

12.3. Noções básicas de programação web

12.3.1. Informações gerais

Considere a comunicação entre duas máquinas remotas, A e B:

Image

Quando uma aplicação AppA da máquina A quer se comunicar com uma aplicação AppB da máquina B na Internet, ela precisa saber várias coisas:

  • o endereço IP ou o nome da máquina B;
  • o número da porta usada pela aplicação AppB. Isso porque a máquina B pode hospedar muitas aplicações que funcionam pela Internet. Quando recebe informações da rede, ela precisa saber a qual aplicação elas se destinam. As aplicações da máquina B acessam a rede por meio de interfaces chamadas portas de comunicação. O número da porta de destino está contido no segmento recebido pela máquina B, para que ela possa entregá-lo à aplicação correta;
  • os protocolos de comunicação compreendidos pela máquina B. Em nosso estudo, usaremos apenas os protocolos TCP/IP;
  • o protocolo de comunicação aceito pela aplicação AppB. De fato, as máquinas A e B "conversarão" entre si. O que elas trocam será encapsulado nos protocolos TCP/IP. No entanto, quando a aplicação AppB, no fim da cadeia, recebe as informações enviadas pela aplicação AppA, ela precisa ser capaz de interpretá-las. É como em uma situação em que duas pessoas, A e B, se comunicam por telefone: a conversa é transportada pelo telefone, mas, se A fala francês e B não entende esse idioma, A e B não conseguirão ter uma conversa com sentido. As duas aplicações que se comunicam precisam, portanto, concordar sobre o tipo de comunicação que usarão. Por exemplo, a comunicação com um servidor web não é a mesma que a comunicação com um servidor de e-mail: esses dois serviços não aceitam os mesmos comandos. Eles têm protocolos de comunicação diferentes.

12.3.2. Características do protocolo TCP

Aqui nos concentraremos apenas nas comunicações de rede que usam o protocolo de transporte TCP. Vamos rever suas principais características para os programadores:

  • Primeiro se estabelece uma conexão entre uma porta da máquina cliente e uma porta da máquina servidora. Ela é identificada por quatro informações: o endereço IP e a porta do cliente, e o endereço IP e a porta do servidor;
  • a conexão transporta dois fluxos de bytes, um em cada sentido (full-duplex). Os bytes chegam na ordem em que foram transmitidos, sem perda nem duplicação;
  • o TCP não conhece o conceito de mensagem: cabe ao protocolo de comunicação da aplicação delimitar as solicitações e as respostas (por uma quebra de linha, um comprimento especificado, o fechamento da conexão etc.);
  • Uma das duas partes fecha a conexão; a outra detecta isso ao chegar ao fim do fluxo de leitura.

12.3.3. A relação cliente-servidor

A comunicação pela Internet costuma ser assimétrica: a máquina A inicia uma conexão para solicitar um serviço à máquina B. Ela especifica que deseja estabelecer uma conexão com o serviço SB1 da máquina B. A máquina B aceita ou recusa a solicitação. Se aceitar, a máquina A pode enviar suas solicitações ao serviço SB1. Essas solicitações devem respeitar o protocolo de comunicação compreendido pelo serviço SB1. Estabelece-se assim um diálogo de solicitação e resposta entre a máquina A, chamada de máquina cliente, e a máquina B, chamada de máquina servidora. Um dos dois parceiros fechará a conexão.

12.3.4. Arquitetura do cliente

A arquitetura de um programa de rede que solicita os serviços de uma aplicação servidora será a seguinte:

open the connection with the service SB1 of machine B
if successful then
    while it is not finished
        prepare a request
        send it to machine B
        wait for and retrieve the response
        process it
    end while
end if
close the connection

12.3.5. Arquitetura do servidor

A arquitetura de um programa que oferece serviços será a seguinte:

1
2
3
4
5
6
open the service on the local machine
while the service is open
    listen for connection requests on a so-called listening port
    when there is a request, accept it and have the resulting connection
        (service connection) handled by another thread
end while

O programa servidor trata de modo diferente a solicitação inicial de conexão de um cliente e as solicitações de serviço subsequentes. O programa que fica à escuta não presta o serviço ele mesmo: se o fizesse, deixaria de escutar as solicitações de conexão enquanto o serviço estivesse em andamento, e os outros clientes não seriam atendidos. Por isso ele age de outra forma: assim que uma solicitação de conexão é recebida na porta de escuta e depois aceita, o servidor delega a outra thread a tarefa de prestar o serviço solicitado pelo cliente, pela conexão de serviço que acabou de ser estabelecida. Isso permite atender vários clientes ao mesmo tempo:

Image

Às vezes se afirma que, no lado do servidor, a conexão de serviço usa uma porta diferente, escolhida aleatoriamente. Isso é incorreto: todas as conexões de serviço usam a porta de escuta do servidor; elas se distinguem umas das outras pelo endereço e pela porta do cliente, que são diferentes. Veremos isso na saída do nosso servidor de eco.

Uma thread de serviço terá a seguinte estrutura:

1
2
3
4
5
6
while the service has not been fully provided
    wait for a request on the service connection
    when there is one, build the response
    send the response over the service connection
end while
close the service connection

12.4. Explorando os protocolos de comunicação da Internet

12.4.1. Introdução

Quando um cliente se conecta a um servidor, estabelece-se um diálogo entre eles. A natureza desse diálogo constitui o que se chama de protocolo de comunicação do servidor. Entre os protocolos mais comuns da Internet estão os seguintes:

  • HTTP: HyperText Transfer Protocol, o protocolo de comunicação com um servidor web (servidor HTTP);
  • SMTP: Simple Mail Transfer Protocol, o protocolo de comunicação com um servidor de envio de e-mails (servidor SMTP);
  • POP: Post Office Protocol, o protocolo de comunicação com um servidor de armazenamento de e-mails (servidor POP). Ele serve para recuperar os e-mails recebidos, não para enviá-los. O IMAP tem a mesma finalidade;
  • FTP: File Transfer Protocol, o protocolo de comunicação com um servidor de armazenamento de arquivos (servidor FTP).

Esses protocolos, em suas versões históricas, caracterizam-se por serem baseados em texto: o cliente e o servidor trocam linhas de texto terminadas pelos dois caracteres \r\n (retorno de carro, avanço de linha). Se você tiver um cliente capaz de:

  • estabelecer uma conexão com um servidor TCP;
  • exibir no console as linhas de texto enviadas pelo servidor;
  • enviar ao servidor as linhas de texto que um usuário digita no teclado,

então poderá se comunicar com um servidor TCP que use um protocolo baseado em texto, desde que conheça as regras desse protocolo.

O programa [telnet], que antigamente estava disponível em máquinas Unix e Windows, é um desses clientes; a ferramenta PuTTY, configurada no modo de conexão raw, é outro. O cliente [telnet] não é mais instalado por padrão no Windows, e a maioria dos servidores públicos não aceita mais comunicação sem criptografia. Vamos proceder de outra forma:

  • para o HTTP, usaremos a ferramenta [curl], disponível por padrão no Windows 10 e 11, no macOS e no Linux, que exibe os detalhes das trocas, seguida do cliente TCP genérico que escreveremos mais adiante neste capítulo. No Windows, no PowerShell, [curl] é um alias do comando [Invoke-WebRequest]: é preciso digitar [curl.exe];
  • como não temos acesso a servidores reais, consultaremos um pequeno servidor web que nós mesmos escrevemos e que é executado na máquina local;
  • Para SMTP, POP e FTP, apresentaremos exemplos de diálogos conformes às RFCs que definem esses protocolos.

12.4.2. Um servidor web de teste

Nosso servidor web de teste usa o pequeno servidor HTTP fornecido com o JDK, no módulo [jdk.httpserver] (pacote [com.sun.net.httpserver]). Apesar do nome do pacote, trata-se de uma API pública e bem documentada, disponível desde o Java 6; ela basta para escrever um servidor de teste em um único arquivo, sem nenhuma biblioteca. Os serviços web reais costumam usar um servidor completo como o Tomcat, que exploraremos com o Spring Boot no próximo capítulo. Você não precisa entender este programa em detalhes por enquanto: basta saber o que ele retorna. O programa [Internet03.java] é o seguinte:

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;

import static java.nio.charset.StandardCharsets.UTF_8;

// um pequeno servidor web local que será o alvo de nossos clientes HTTP
// ele usa o servidor HTTP fornecido pelo JDK (módulo jdk.httpserver)
// chamada: java Internet03.java [port]   (porta 27110 por padrão); parar com Ctrl-C

// a página inicial: um documento HTML
final String HOME = """
        <!DOCTYPE html>
        <html lang="en">
        <head><meta charset="utf-8"><title>Test server</title></head>
        <body><h1>Welcome to the test server of the Java course</h1></body>
        </html>
        """;

int port;

void main(String[] args) throws IOException {
    port = args.length == 1 ? Integer.parseInt(args[0]) : 27110;
    // o servidor escuta no endereço de loopback: ele só é acessível a partir da própria máquina
    HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), port), 0);
    // todas as URLs são tratadas pelo método [process]
    server.createContext("/", this::process);
    server.start();
    IO.println("Web server started on http://localhost:" + port);
}

// tratamento de uma requisição: escolha da resposta de acordo com a URL e depois trace no console
void process(HttpExchange exchange) throws IOException {
    try (exchange) {
        String method = exchange.getRequestMethod();
        String path = exchange.getRequestURI().getPath();
        if (!method.equals("GET") && !method.equals("HEAD")) {
            // as URLs aceitam apenas os métodos GET e HEAD
            exchange.sendResponseHeaders(405, -1);
        } else {
            switch (path) {
                // a página inicial, com seu tamanho
                case "/" -> send(exchange, HOME, "text/html; charset=utf-8", true);
                // um documento de texto construído a partir de um parâmetro da URL, enviado em partes
                case "/hello" -> send(exchange, "Hello " + parameter(exchange, "name", "unknown") + "!",
                        "text/plain; charset=utf-8", false);
                // redirecionamento temporário (302) para um endereço relativo
                case "/old" -> redirect(exchange, 302, "/hello?name=visitor");
                // redirecionamento permanente (301) para um endereço absoluto
                case "/moved" -> redirect(exchange, 301, "http://localhost:" + port + "/");
                // um redirecionamento que entra em loop sobre si mesmo
                case "/loop" -> redirect(exchange, 302, "/loop");
                // qualquer outra URL: 404 Not Found, sem documento (-1)
                default -> exchange.sendResponseHeaders(404, -1);
            }
        }
        // trace no console: a requisição e o código de status de sua resposta
        IO.println("%s %s %s -> %d".formatted(method, exchange.getRequestURI(), exchange.getProtocol(),
                exchange.getResponseCode()));
    }
}

// envio de um documento de texto: com seu tamanho (Content-length) ou em partes (chunked)
void send(HttpExchange exchange, String text, String type, boolean withSize) throws IOException {
    byte[] bytes = text.getBytes(UTF_8);
    exchange.getResponseHeaders().set("Content-Type", type);
    if (exchange.getRequestMethod().equals("HEAD")) {
        // HEAD: somente os cabeçalhos; o tamanho que o documento teria é informado
        exchange.getResponseHeaders().set("Content-Length", String.valueOf(bytes.length));
        exchange.sendResponseHeaders(200, -1);
        return;
    }
    // tamanho 0: documento enviado em partes, de tamanho desconhecido de antemão
    exchange.sendResponseHeaders(200, withSize ? bytes.length : 0);
    exchange.getResponseBody().write(bytes);
}

// um redirecionamento: código 301 ou 302 e cabeçalho Location, sem documento
void redirect(HttpExchange exchange, int code, String address) throws IOException {
    exchange.getResponseHeaders().set("Location", address);
    exchange.sendResponseHeaders(code, -1);
}

// o valor de um parâmetro da URL (?name=value&...), decodificado
String parameter(HttpExchange exchange, String name, String defaultValue) {
    String query = exchange.getRequestURI().getRawQuery();
    if (query == null) {
        return defaultValue;
    }
    for (String pair : query.split("&")) {
        String[] fields = pair.split("=", 2);
        if (fields[0].equals(name) && fields.length == 2) {
            return URLDecoder.decode(fields[1], UTF_8);
        }
    }
    return defaultValue;
}

Comentários:

  • Linhas 1–2: o módulo [jdk.httpserver] não faz parte do módulo [java.base], que é importado automaticamente em um arquivo-fonte compacto; suas classes precisam ser importadas. A linha 4 é um import estático: ele permite escrever [UTF_8] em vez de [StandardCharsets.UTF_8];
  • linhas 11–17: a página inicial, um pequeno documento HTML escrito com um bloco de texto [""" ... """] (Java 15), que dispensa o uso de caracteres de escape nas aspas;
  • linha 22: a porta de escuta, 27110 por padrão;
  • linha 24: o servidor escuta no endereço de loopback 127.0.0.1: ele só é acessível a partir da própria máquina. O segundo parâmetro de [create] é o tamanho da fila de conexões (0: padrão do sistema);
  • linha 26: todas as URLs que começam com [/], e portanto todas as URLs, são atribuídas ao método [process]. O segundo parâmetro de [createContext] é um [HttpHandler], uma interface funcional cujo único método, [handle(HttpExchange)], recebe a troca atual: a solicitação do cliente e a resposta a ser construída;
  • linha 27: o servidor começa a ser executado em suas próprias threads; o método [main] termina, mas o programa continua em execução até ser interrompido com Ctrl-C;
  • linha 33: um [HttpExchange] precisa ser fechado depois que a resposta é enviada: o [try] com recursos cuida disso;
  • linhas 36–38: apenas os métodos [GET] e [HEAD] são aceitos; os demais recebem uma resposta 405 (método não permitido);
  • linha 42: a URL [/] retorna a página inicial;
  • linha 44: a URL [/hello?name=xx] retorna o texto [Hello xx!];
  • linha 47: a URL [/old] provoca um redirecionamento temporário (código de status 302) para o endereço relativo [/hello?name=visitor];
  • linha 49: a URL [/moved] provoca um redirecionamento permanente (código de status 301) para o endereço absoluto [http://localhost:27110/];
  • linha 51: a URL [/loop] redireciona para si mesma: um cliente que seguisse os redirecionamentos às cegas nunca pararia;
  • linha 53: qualquer outra URL recebe uma resposta 404 (página não encontrada). O método [sendResponseHeaders(code, size)] envia a linha de status e os cabeçalhos; um tamanho igual a -1 significa que nenhum documento se segue;
  • linhas 57–58: cada solicitação processada é exibida no console junto com o código de status da resposta;
  • linhas 63–75: envio de um documento de texto. Os cabeçalhos da resposta são definidos com [getResponseHeaders().set] (linha 65); em seguida, [sendResponseHeaders] os envia junto com o tamanho do documento; o documento é então escrito no fluxo por meio de [getResponseBody()] (linha 74). Um tamanho 0 (linha 73) significa "tamanho desconhecido": o documento é então enviado em blocos (chunks), como veremos mais adiante. Para uma solicitação [HEAD], nenhum documento é enviado, mas se informa o tamanho que ele teria (linhas 66–71);
  • linhas 78–81: um redirecionamento, formado por um código de status e por um cabeçalho [Location] que fornece o novo endereço;
  • linhas 84–96: o valor de um parâmetro na URL. [getRawQuery] retorna a parte da URL que vem depois de [?], ainda codificada; [URLDecoder.decode] decodifica cada valor (veremos mais adiante por que os valores são codificados).

O servidor é iniciado em uma primeira janela de comando. Ele exibe:

1
2
3
4
> java Internet03.java
Web server started on http://localhost:27110
GET / HTTP/1.1 -> 200
GET /unknown HTTP/1.1 -> 404

As linhas 3–4 apareceram durante os testes descritos no parágrafo seguinte. O servidor pode ser interrompido pressionando Ctrl-C.

12.4.3. O protocolo HTTP (HyperText Transfer Protocol)

Com o servidor em execução, solicitamos, em uma segunda janela de comando, a raiz [/] do site [http://localhost:27110] usando a ferramenta [curl]. Sua opção [-v] (verbose) exibe todo o diálogo HTTP; a opção [-s] (silent) suprime a exibição do progresso da transferência:

> curl -sv http://localhost:27110/
* Host localhost:27110 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27110...
* Connected to localhost (127.0.0.1) port 27110
> GET / HTTP/1.1
> Host: localhost:27110
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Date: Sat, 03 Oct 2026 17:40:04 GMT
< Content-type: text/html; charset=utf-8
< Content-length: 171
< 
{ [171 bytes data]
* Connection #0 to host localhost left intact
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the test server of the Java course</h1></body>
</html>

Comentários:

  • As linhas que começam com [*] contêm informações do [curl]; as linhas que começam com [>] foram enviadas ao servidor; as que começam com [<] foram recebidas do servidor; a linha [{ [171 bytes data]] indica a chegada dos 171 bytes do documento, que é exibido no final;
  • Linhas 2–6: [curl] obteve os endereços de [localhost] (::1 no IPv6 e 127.0.0.1 no IPv4) e se conectou à porta 27110 do endereço 127.0.0.1;
  • linhas 7–11: a solicitação do cliente. Ela é formada por uma primeira linha com a sintaxe [method URL version] (aqui, o método [GET] é usado para solicitar o documento [/], isto é, a raiz do site, em HTTP/1.1), seguida de cabeçalhos HTTP na forma [Name: value], e termina com uma linha em branco;
  • linha 8: o cabeçalho [Host] especifica a máquina e a porta consultadas; ele é obrigatório no HTTP/1.1 porque um mesmo servidor pode hospedar vários sites;
  • linha 9: o identificador do software cliente;
  • linha 10: os tipos de documento aceitos pelo cliente, neste caso, todos;
  • Linhas 12–16: a resposta do servidor: uma linha de status e cabeçalhos, também seguidos de uma linha em branco;
  • linha 12: a linha de status, com a sintaxe [version code message]. O código 200 indica que o documento solicitado foi encontrado;
  • linha 13: a data e a hora do servidor, sempre em Tempo Universal Coordenado (GMT);
  • linha 14: o tipo do documento (um documento HTML) e sua codificação (UTF-8);
  • linha 15: o tamanho do documento em bytes. É assim que o cliente sabe onde o documento termina. Observe que o servidor do JDK escreve os nomes dos cabeçalhos com uma única letra maiúscula ([Content-type], [Content-length]): isso é irrelevante, pois os nomes dos cabeçalhos HTTP não diferenciam maiúsculas de minúsculas. Ele também não envia o cabeçalho opcional [Server], que a maioria dos servidores usa para se identificar ([Server: Apache], [Server: nginx]…);
  • linha 18: no HTTP/1.1, a conexão permanece aberta por padrão após a resposta (modo "keep-alive"), para que outras solicitações possam ser atendidas; [curl] a deixa aberta e depois a fecha ao terminar;
  • linhas 19–23: o documento enviado pelo servidor.

Agora vamos solicitar um documento que não existe:

> curl -sv http://localhost:27110/unknown
* Host localhost:27110 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27110...
* Connected to localhost (127.0.0.1) port 27110
> GET /unknown HTTP/1.1
> Host: localhost:27110
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 404 Not Found
< Date: Sat, 03 Oct 2026 17:40:04 GMT
< Content-length: 0
< 
* Connection #0 to host localhost left intact
  • linha 7: solicitamos um documento inexistente;
  • linha 12: o servidor respondeu com o código de status 404, o que significa que o documento solicitado não foi encontrado;
  • linha 14: o documento enviado está vazio. Nosso servidor, como muitos outros, não anexa nenhum documento a uma resposta 404; outros servidores enviam uma breve página explicativa. Um navegador que recebe uma resposta 404 sem documento exibe a sua própria página de erro.

Os códigos de status se dividem em cinco categorias: 1xx (informação), 2xx (sucesso, 200 OK), 3xx (redirecionamento, 301 e 302, que veremos mais adiante), 4xx (erro do cliente: 404 Not Found, 401 Unauthorized, 403 Forbidden…), 5xx (erro do servidor: 500 Internal Server Error…).

O navegador faz a mesma coisa que o [curl]: envia uma solicitação HTTP, recebe os cabeçalhos e o documento e, em seguida, exibe o documento. As ferramentas de desenvolvedor do navegador (tecla F12, aba Rede) permitem visualizar os cabeçalhos trocados.

Algumas observações sobre o estado atual do HTTP:

  • O HTTPS é hoje o padrão: os navegadores sinalizam um site que usa HTTP simples como "não seguro". Com o HTTPS, uma negociação TLS precede o diálogo HTTP, e tudo o que vem depois é criptografado. Já não é, portanto, possível se comunicar "manualmente" com um servidor HTTPS usando um cliente TCP simples. Ainda é possível, porém, observar o diálogo com o [curl], que realiza o handshake TLS e depois exibe os cabeçalhos em texto puro. Apenas a título ilustrativo (não reproduzimos o resultado, pois nossa máquina de teste não tem acesso à Internet), o comando seria [curl -v https://dev.java/];
  • O HTTP/1.1 (hoje RFC 9112) é um protocolo baseado em texto, o que estamos estudando. O HTTP/2 (2015, hoje RFC 9113) mantém os mesmos métodos, cabeçalhos e códigos de status, mas os transmite em um formato binário comprimido e envia várias solicitações simultaneamente por uma única conexão TCP. O HTTP/3 (2022, RFC 9114) faz o mesmo sobre o QUIC e, portanto, sobre o UDP. Navegadores e servidores escolhem automaticamente a versão mais recente que têm em comum; o [curl], sem nenhuma opção específica, usa o HTTP/1.1 para uma URL [http://].

12.4.4. O protocolo SMTP (Simple Mail Transfer Protocol)

Os servidores SMTP trocam e-mails entre si na porta 25. Um cliente de e-mail que envia uma mensagem a submete ao servidor SMTP de seu provedor na porta 587 (submissão, com passagem para o modo criptografado pelo comando [STARTTLS]) ou 465 (conexão criptografada desde o início), após se autenticar. Os provedores de acesso à Internet costumam bloquear as conexões de saída para a porta 25 nos roteadores de seus assinantes, para limitar o spam enviado por máquinas infectadas: a comunicação sem criptografia com um servidor SMTP é hoje praticamente impossível a partir de um computador pessoal.

Eis um exemplo de diálogo SMTP conforme a RFC 5321. Não se trata de uma execução: as linhas prefixadas com [C:] são enviadas pelo cliente, as prefixadas com [S:] pelo servidor, e os domínios [example.org] e [example.com] são reservados para exemplos:

S: 220 mail.example.com ESMTP ready
C: EHLO poste.example.org
S: 250-mail.example.com
S: 250-SIZE 10240000
S: 250-STARTTLS
S: 250 8BITMIME
C: MAIL FROM:<alice@example.org>
S: 250 2.1.0 Ok
C: RCPT TO:<bob@example.com>
S: 250 2.1.5 Ok
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: From: alice@example.org
C: To: bob@example.com
C: Subject: test
C:
C: line1
C: line2
C: .
S: 250 2.0.0 Ok: queued as 4F2A81C0
C: QUIT
S: 221 2.0.0 Bye
  • Linha 1: mensagem de boas-vindas do servidor. Cada resposta do servidor começa com um código de três dígitos: 2xx indica sucesso, 3xx significa "continue" e 4xx e 5xx indicam erro;
  • linha 2: o cliente se identifica. O comando [EHLO] substituiu o antigo comando [HELO]: ele pede ao servidor a lista das extensões que ele suporta;
  • Linhas 3–6: a resposta do servidor, em várias linhas. O hífen que segue o código indica que a resposta continua; a última linha tem um espaço no lugar dele. Aqui, o servidor informa que aceita mensagens de até 10 MB, suporta o modo criptografado e aceita caracteres de 8 bits;
  • linha 7: o endereço do remetente;
  • linha 9: o endereço do destinatário (o comando pode ser repetido para vários destinatários);
  • linha 11: o cliente anuncia a mensagem;
  • linha 12: o servidor convida o cliente a enviar a mensagem e lembra como terminá-la;
  • linhas 13–19: a mensagem, formada por cabeçalhos ([From], [To], [Subject]…), uma linha em branco e o corpo, e terminando com uma linha contendo apenas um ponto;
  • linha 20: o servidor aceitou a mensagem e a colocou em sua fila;
  • Linhas 21–22: o cliente sinaliza que terminou; o servidor fecha a conexão.

12.4.5. O protocolo POP (Post Office Protocol)

Os servidores POP3 funcionam na porta 110 ou, para uma conexão criptografada com TLS, na porta 995, a única opção oferecida atualmente pela maioria dos provedores, já que a senha é transmitida pela conexão. Eis um diálogo POP3 típico, conforme a RFC 1939, apresentado com as mesmas convenções do anterior:

S: +OK POP3 server ready
C: USER bob
S: +OK
C: PASS ********
S: +OK Logged in.
C: LIST
S: +OK 2 messages:
S: 1 1205
S: 2 1916
S: .
C: RETR 2
S: +OK 1916 octets
S: Return-Path: <alice@example.org>
S: Delivered-To: bob@example.com
S: ...
S: Date: Sat, 03 Oct 2026 10:59:25 +0200
S: From: alice@example.org
S: To: bob@example.com
S: Subject: test
S:
S: line1
S: line2
S: .
C: QUIT
S: +OK Logging out.
  • Linha 1: mensagem de boas-vindas do servidor. As respostas começam com [+OK] (sucesso) ou [-ERR] (erro);
  • linha 2: o cliente informa o seu nome de usuário, isto é, o nome que usa para ler os seus e-mails;
  • linha 4: a senha do cliente (ocultada aqui);
  • linha 6: o cliente solicita uma lista de seus e-mails;
  • linhas 7–10: a lista das mensagens da caixa de correio do cliente, no formato [message number, size in bytes], terminando com uma linha contendo apenas um ponto;
  • linha 11: a mensagem nº 2 é solicitada;
  • linhas 12–23: a mensagem nº 2, com seus cabeçalhos, uma linha em branco e o seu corpo, também terminando com um ponto;
  • linhas 24–25: o cliente indica que terminou; o servidor fecha a conexão.

O POP3 foi concebido para baixar os e-mails para o computador do usuário. Hoje ele enfrenta forte concorrência do IMAP (porta 143, ou 993 com TLS; RFC 9051), que deixa as mensagens no servidor e permite consultá-las e organizá-las a partir de vários dispositivos, bem como por meio de clientes de e-mail baseados na web.

12.4.6. O protocolo FTP (File Transfer Protocol)

O protocolo FTP (RFC 959) é mais complexo que os descritos anteriormente: o diálogo (comandos e respectivas respostas) ocorre em uma conexão de controle aberta na porta 21 do servidor, e cada transferência de arquivo ou de lista de arquivos usa uma segunda conexão, aberta especificamente para essa finalidade. Eis um diálogo típico na conexão de controle:

S: 220 FTP service ready
C: USER anonymous
S: 331 Please specify the password.
C: PASS guest@example.org
S: 230 Login successful.
C: PWD
S: 257 "/" is the current directory
C: EPSV
S: 229 Entering Extended Passive Mode (|||40312|)
C: RETR readme.txt
S: 150 Opening BINARY mode data connection for readme.txt (1250 bytes).
S: 226 Transfer complete.
C: QUIT
S: 221 Goodbye.
  • linha 2: conexão anônima, como a oferecida por servidores públicos de download;
  • linha 8: o cliente pede ao servidor que abra uma porta para a conexão de dados. O servidor responde (linha 9) que está aguardando essa conexão na porta 40312;
  • linha 10: o cliente solicita o arquivo [readme.txt]. O arquivo chega pela conexão de dados, e a conexão de controle recebe as respostas 150 (início da transferência) e 226 (fim da transferência).

Esses comandos podem ser vistos no log de um cliente como o FTP ou o FileZilla. No entanto, o FTP está se tornando obsoleto: ele transmite as senhas em texto puro, tem dificuldade para funcionar com firewalls por causa de sua segunda conexão, e os navegadores deixaram de suportá-lo em 2021 (Chrome 88, Firefox 90). É preferível usar o SFTP, a transferência de arquivos via SSH, e o simples download via HTTPS.

12.5. Classes Java para programação web

12.5.1. Escolhendo a classe certa

O Java oferece diversas classes para trabalhar com a rede:

Image

  • A classe [Socket] (pacote [java.net]) representa uma extremidade de uma conexão TCP. O termo inglês "socket" designa uma tomada elétrica; seu sentido foi ampliado para designar um soquete de rede em software. Em uma comunicação TCP/IP entre duas máquinas, A e B, dois sockets se comunicam entre si. Um cliente cria um [Socket] para se conectar a um servidor; um servidor cria um [ServerSocket], que aguarda solicitações de conexão e, para cada cliente aceito, fornece um [Socket] ligado a esse cliente. Uma vez estabelecida a conexão, um [Socket] fornece dois fluxos de bytes, um para leitura e outro para escrita, que são usados como fluxos de arquivo. É o caso da aplicação A acima;
  • a classe [DatagramSocket] permite enviar e receber datagramas UDP. Não a usaremos neste curso;
  • As classes [SSLSocket] e [SSLServerSocket] (pacote [javax.net.ssl]) acrescentam a criptografia TLS a [Socket]: concluída a negociação TLS, são usadas exatamente como sockets comuns (aplicação B acima);
  • O Java também fornece uma classe especializada em um protocolo: [HttpClient] (pacote [java.net.http], Java 11), que trata o protocolo HTTP nas versões 1.1 e 2, inclusive a criptografia TLS do HTTPS (aplicação C acima). Ela substitui a classe [HttpURLConnection] do Java 1.1; voltaremos a ela na segunda parte deste capítulo. O JDK não tem uma classe para e-mail; a biblioteca Jakarta Mail é usada para essa finalidade.

As classes [Socket] e [ServerSocket] existem desde o Java 1.0. Suas operações são bloqueantes: [accept] bloqueia a thread chamadora até que um cliente chegue; uma operação de leitura a bloqueia até que cheguem dados. O Java 1.4 acrescentou o pacote [java.nio.channels] ([SocketChannel], [ServerSocketChannel], [Selector]), que permite operações não bloqueantes, e o Java 7 introduziu os canais assíncronos ([AsynchronousSocketChannel]). Voltaremos a isso no final deste capítulo, antes da aplicação de exemplo: desde a introdução das threads virtuais (Java 21), as classes mais simples [Socket] e [ServerSocket] bastam na maioria dos casos. São as que usaremos.

12.5.2. A classe Socket

A classe [Socket] é a escolha adequada na maioria dos casos para criar um cliente de um serviço TCP. Entre seus construtores e métodos, estão os seguintes:

Membro
Tipo
Função
Socket(String machine, int port)
C
Estabelece uma conexão TCP com o serviço em execução na porta [port] da máquina [machine]. Por exemplo, [new Socket("localhost", 27100)]. Lança uma [UnknownHostException] se a máquina for desconhecida e uma [ConnectException] se a conexão for recusada (são duas [IOException])
Socket(), void connect(SocketAddress address, int timeout)
C, M
cria um socket não conectado e depois o conecta, aguardando no máximo [timeout] milissegundos: sem um timeout, conectar-se a uma máquina que não responde pode levar várias dezenas de segundos
InputStream getInputStream(), OutputStream getOutputStream()
M
os fluxos de bytes de leitura e de escrita da conexão. São eles que viabilizam a comunicação cliente-servidor
SocketAddress getLocalSocketAddress(), getRemoteSocketAddress()
M
as duas extremidades da conexão (endereço e porta)
void setSoTimeout(int delay)
M
tempo máximo de espera de uma operação de leitura, em milissegundos: se for excedido, a operação de leitura dispara uma [SocketTimeoutException] (0, o valor padrão, significa "sem timeout")
void shutdownOutput()
M
Fecha apenas o fluxo de escrita: o parceiro percebe o fim do fluxo, mas a sua resposta ainda pode ser lida
void close(), boolean isClosed()
M
fecha a conexão e seus dois fluxos; [Socket] implementa [AutoCloseable] e é, portanto, usado dentro de um [try] com recursos. Qualquer operação de leitura em andamento em outra thread termina então com uma [SocketException]

Os fluxos de [getInputStream] e [getOutputStream] leem e escrevem bytes. Muitas aplicações cliente-servidor trocam linhas de texto. Por isso, é útil envolvê-los em objetos [BufferedReader] e [PrintWriter] , apresentados no Capítulo 5, para ler e escrever essas linhas. Eis como o cliente de eco que escreveremos mais adiante ([Internet05.java]) se conecta e cria seus fluxos:

1
2
3
4
5
    // conexão ao serviço e depois streams de leitura e escrita na conexão
    try (var client = new Socket(server, port);
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         // autoFlush: cada linha escrita por println é enviada imediatamente pela rede
         var writer = new PrintWriter(client.getOutputStream(), true, UTF_8)) {
  • Linha 2: conexão com o servidor. O [try] com recursos fechará a conexão e os fluxos ao sair do bloco, aconteça o que acontecer;
  • Linha 3: o fluxo de rede é convertido em um fluxo de caracteres ([InputStreamReader]), que é então envolvido em um [BufferedReader], capaz de ler uma linha. O conjunto de caracteres é sempre especificado: as duas partes precisam concordar sobre a codificação dos caracteres que trocam. Desde o Java 18, o UTF-8 é o conjunto de caracteres padrão, mas especificá-lo explicitamente torna o programa independente da configuração da máquina;
  • Linha 5: o segundo parâmetro ([true]) do construtor de [PrintWriter] ativa a descarga automática ("autoFlush"): cada chamada a [println] transmite imediatamente a linha à rede, sem esperar que o buffer interno se encha. Isso é importante. Em geral, quando um cliente envia uma linha de texto ao seu parceiro, espera uma resposta. Essa resposta nunca chegará se a linha ficar no buffer da máquina emissora sem ser enviada. Sem o autoFlush, é preciso chamar explicitamente [flush] depois de escrever uma solicitação completa.

Para enviar uma linha de texto ao servidor, escreve-se [writer.println("some text");] e, para ler a resposta do servidor, escreve-se [String response = reader.readLine();]. [readLine] retorna [null] quando o parceiro fechou a conexão e tudo o que ele enviou foi lido: isso marca o fim do fluxo.

Três pontos merecem atenção:

  • o fim da linha. [println] termina a linha com o separador de linha do sistema ([System.lineSeparator()]), que é \r\n no Windows, mas apenas \n no Linux e no macOS. Os protocolos da Internet (HTTP, SMTP, POP, FTP) exigem \r\n. Alguns servidores toleram um simples \n, enquanto outros não; portanto, um programa portável que use um desses protocolos deve escrever ele mesmo os fins de linha: [writer.write(line + "\r\n")]. Na leitura, [readLine] aceita \r\n, \n e \r indistintamente;
  • erros de escrita. Os métodos de [PrintWriter] nunca lançam uma [IOException]: um erro é simplesmente registrado, e o método [checkError] indica se algum ocorreu. Para um diálogo de "uma solicitação, uma resposta", isso não é um problema: uma conexão interrompida será detectada na leitura da resposta. Quando os erros de escrita precisam ser informados, usamos [BufferedWriter] ou [OutputStreamWriter], cujos métodos [write] e [flush] disparam uma [IOException];
  • operações bloqueantes. [new Socket(...)], [readLine], e [println] bloqueiam a thread que as executa até que a operação termine. Para um cliente que não tem nada a fazer além de esperar a resposta do servidor, é exatamente o que se precisa. Quando ele precisa fazer duas coisas ao mesmo tempo (ler do teclado e da rede, por exemplo), uma dessas tarefas é delegada a outra thread, como faremos no cliente TCP genérico.

A arquitetura básica de um cliente TCP com o seguinte protocolo básico de comunicação com o servidor:

  • o cliente envia uma solicitação contida em uma única linha;
  • o servidor envia uma resposta contida em uma única linha;

é, portanto, a seguinte: abrir o socket e seus dois fluxos em um [try] com recursos e depois repetir "enviar uma solicitação por [println], ler a resposta por [readLine]" até o fim do diálogo, interceptando as mensagens [IOException]: uma [UnknownHostException] ou uma [ConnectException] indica uma conexão que falhou (máquina desconhecida, nenhum serviço na porta solicitada etc.), enquanto uma [IOException] indica um erro durante a comunicação (conexão perdida etc.). Essa é a estrutura do cliente de eco que descreveremos na seção [A Client for the Echo Server].

12.5.3. A classe ServerSocket

A classe [ServerSocket] é a classe adequada na maioria dos casos para criar um serviço TCP. Entre seus construtores e métodos, estão os seguintes:

Membro
Tipo
Função
ServerSocket(int port)
C
cria um serviço TCP que escuta as solicitações dos clientes na porta [port], chamada de porta de escuta, em todos os endereços da máquina (IPv4 e IPv6). Lança uma [BindException] se a porta já estiver em uso
ServerSocket(int port, int backlog, InetAddress address)
C
Igual ao anterior, mas escutando apenas no endereço [address] (por exemplo, o endereço de loopback, para aceitar apenas clientes da máquina local). [backlog] é o número máximo de solicitações de conexão aguardando para serem aceitas (50 por padrão)
Socket accept()
M
espera uma solicitação de cliente e a aceita. Retorna o [Socket] associado, no lado do servidor, à conexão de serviço aberta com esse cliente
void close()
M
deixa de escutar as solicitações dos clientes; um [accept] em execução em outra thread é encerrado por uma [SocketException]
SocketAddress getLocalSocketAddress()
M
o endereço e a porta de escuta

Eis, extraída do servidor de eco que escreveremos mais adiante ([Internet04.java]), a estrutura básica de um servidor TCP:

    // o serviço de escuta, em todas as interfaces de rede da máquina
    try (var listener = new ServerSocket(port);
         // uma thread virtual por cliente; close() espera o fim de todos os serviços
         var services = Executors.newVirtualThreadPerTaskExecutor()) {
        // Ctrl-C: o servidor para de forma limpa
        stopOnCtrlC(listener);
        IO.println("Echo server started on " + listener.getLocalSocketAddress());
        try {
            // laço de espera por clientes - interrompido por Ctrl-C
            for (int clientNum = 0; ; clientNum++) {
                // espera (bloqueante) por um cliente
                Socket client = listener.accept();
                connections.add(client);
                // o cliente é atendido por uma thread virtual; voltamos imediatamente a esperar o próximo
                int number = clientNum;
                services.submit(() -> serve(client, number));
            }
  • Linha 2: o serviço de escuta é criado para uma porta específica. Uma máquina tem pelo menos dois endereços IP: o endereço de loopback 127.0.0.1 e o endereço que ela tem na rede à qual está conectada. Pode ter outros se estiver conectada a várias redes. A menos que um endereço seja especificado, o serviço escuta em todos esses endereços. Assim que é criado, o serviço começa a escutar, isto é, a aguardar solicitações de conexão dos clientes;
  • linha 4: um [ExecutorService] (Capítulo 8) que cria uma thread virtual para cada tarefa submetida a ele. Ele também é declarado no [try] com recursos: seu método [close] espera a conclusão de todas as tarefas submetidas;
  • Linhas 10–17: o laço que espera um cliente e inicia seu serviço, repetido para cada novo cliente;
  • linha 12: a requisição de um cliente é aceita. [accept] retorna um [Socket] chamado de serviço:
    • o cliente fez sua requisição usando seu próprio [Socket], que chamaremos de [RequestSocket];
    • o servidor aceita essa requisição com [accept], que cria um [Socket] no lado do servidor, que chamaremos de [ServiceSocket]. Temos então uma conexão TCP aberta, com os sockets [RequestSocket] ↔ [ServiceSocket] nas duas extremidades;
    • a comunicação cliente/servidor que ocorre em seguida acontece por essa conexão. O serviço de escuta não participa mais dela;
  • Linha 16: para permitir que o servidor atenda vários clientes ao mesmo tempo, o serviço é tratado por uma thread virtual. O servidor não espera por ela; ele volta imediatamente a esperar o próximo cliente. A lambda passada a [submit] só pode usar variáveis locais cujos valores não mudam mais (“efetivamente final”): a variável de laço [clientNum] é, portanto, copiada para a variável [number] (linha 15).

O método [serve], executado pela thread virtual, recebe o [Socket] já conectado ao cliente a ser atendido. O código aqui é semelhante ao do cliente TCP: criação dos fluxos de dados, seguida de um laço que “lê uma requisição com [readLine] e escreve a resposta com [println]”, até que [readLine] retorne [null], ou seja, até que o cliente feche a conexão. As exceções devem ser capturadas nesse método: ninguém espera o resultado da thread de serviço, e uma exceção não capturada ali passaria despercebida (seria apenas exibida na saída de erro).

12.5.4. Uma thread por cliente: threads de plataforma ou threads virtuais?

Antes do Java 21, um servidor atribuía cada cliente a uma thread de plataforma, isto é, uma thread do sistema operacional, ou a uma thread de um pool de tamanho fixo ([Executors.newFixedThreadPool]). Essa thread executava leituras e escritas bloqueantes: enquanto o cliente pensava, sua thread permanecia ociosa em [readLine]. Cada thread de plataforma consome memória (uma pilha reservada de aproximadamente 1 MB) e tempo de processador do sistema, que precisa alternar entre elas. Com algumas dezenas de clientes, isso não é problema; com milhares de conexões simultâneas, um cenário comum para um servidor real, o servidor entra em colapso. Com um pool limitado a 10 threads, o décimo primeiro cliente precisa esperar que um dos dez primeiros se desconecte.

Para contornar essa limitação, durante muito tempo foi preciso abrir mão das operações bloqueantes: os canais não bloqueantes de [java.nio] e seus [Selector], que permitem a uma única thread monitorar várias conexões, ou os canais assíncronos do Java 7, que chamam um método de callback ao fim de cada operação. Essas técnicas são eficazes, mas difíceis de programar: a lógica do diálogo fica espalhada por vários métodos. Elas formam a base de bibliotecas como o Netty, usadas por muitos servidores.

As threads virtuais (Java 21, Capítulo 8) mudaram o jogo. Uma thread virtual é gerenciada pela Máquina Virtual Java, não pelo sistema operacional. Quando ela executa uma operação de rede bloqueante, é “desacoplada” de sua thread transportadora, que pode então executar outra thread virtual; ela é reacoplada a uma thread transportadora quando os dados chegam. Algumas threads transportadoras, tantas quantos forem os núcleos do processador, bastam, portanto, para atender milhares de clientes, e um cliente que não envia nada consome quase nada: apenas algumas centenas de bytes de pilha. O código em si continua sendo o mesmo código simples e sequencial do modelo “uma thread por cliente”. Esse é o modelo que usaremos em todos os servidores deste capítulo: [ServerSocket.accept] na thread principal, com uma thread virtual por cliente.

12.6. Exemplos de clientes e servidores TCP

Os programas desta seção são arquivos-fonte compactos localizados na pasta [12-internet], executados pelo iniciador de código-fonte ([java Internet04.java ...]). Os servidores e os clientes são iniciados em janelas de comando separadas, na mesma máquina; as portas usadas têm a forma 271xx.

12.6.1. Um servidor de eco

Vamos escrever um servidor de eco, que será iniciado a partir de uma janela de comando com:

java Internet04.java port

O servidor roda na porta passada como argumento. Ele simplesmente devolve ao cliente cada linha que o cliente lhe envia, entre colchetes. O programa [Internet04.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// servidor de eco: devolve a cada cliente as linhas que o cliente lhe envia
// cada cliente é atendido por uma thread virtual
// chamada: java Internet04.java port; parar com Ctrl-C

final String SYNTAX = "Syntax: java Internet04.java port";

// as conexões de serviço em andamento, fechadas quando o servidor para
final Set<Socket> connections = ConcurrentHashMap.newKeySet();
// foi solicitada a parada do servidor?
volatile boolean stop = false;

void main(String[] args) {
    // um argumento é obrigatório: uma porta entre 1 e 65535
    int port = args.length == 1 ? integer(args[0]) : -1;
    if (port < 1 || port > 65535) {
        IO.println(SYNTAX);
        return;
    }
    // o serviço de escuta, em todas as interfaces de rede da máquina
    try (var listener = new ServerSocket(port);
         // uma thread virtual por cliente; close() espera o fim de todos os serviços
         var services = Executors.newVirtualThreadPerTaskExecutor()) {
        // Ctrl-C: o servidor para de forma limpa
        stopOnCtrlC(listener);
        IO.println("Echo server started on " + listener.getLocalSocketAddress());
        try {
            // laço de espera por clientes - interrompido por Ctrl-C
            for (int clientNum = 0; ; clientNum++) {
                // espera (bloqueante) por um cliente
                Socket client = listener.accept();
                connections.add(client);
                // o cliente é atendido por uma thread virtual; voltamos imediatamente a esperar o próximo
                int number = clientNum;
                services.submit(() -> serve(client, number));
            }
        } catch (SocketException e) {
            // accept falha quando Ctrl-C fecha o serviço de escuta
            if (!stop) {
                throw e;
            }
            IO.println("Server stop requested");
            // as conexões em andamento são fechadas: os serviços param
            for (Socket connection : connections) {
                connection.close();
            }
        }
    } catch (IOException e) {
        IO.println("The following error occurred on the server: " + e.getMessage());
    }
}

// Ctrl-C: fechamento do serviço de escuta e depois espera pelo fim do programa principal
void stopOnCtrlC(ServerSocket listener) {
    Thread main = Thread.currentThread();
    Runtime.getRuntime().addShutdownHook(new Thread(() -> {
        stop = true;
        try {
            listener.close();
            // a máquina virtual para no fim desta thread: esperamos o fim da thread principal
            main.join();
        } catch (IOException | InterruptedException e) {
            // paramos assim mesmo
        }
    }));
}

// o serviço prestado a um cliente
void serve(Socket client, int clientNum) {
    IO.println("Start of service to client " + clientNum + " (" + client.getRemoteSocketAddress() + ")");
    // a conexão e seus streams são fechados ao sair do try
    try (client;
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var writer = new PrintWriter(client.getOutputStream(), true, UTF_8)) {
        // laço de leitura da requisição / escrita da resposta
        // readLine retorna null quando o cliente fecha a conexão
        String request;
        while ((request = reader.readLine()) != null) {
            IO.println("<--- client " + clientNum + " : " + request);
            // eco da requisição ao cliente, entre colchetes
            writer.println("[" + request + "]");
            IO.println("---> client " + clientNum + " : [" + request + "]");
        }
    } catch (IOException e) {
        if (stop) {
            IO.println("Service to client " + clientNum + " interrupted by the server stop");
        } else {
            IO.println("The following error occurred while serving client " + clientNum + ": "
                    + e.getMessage());
        }
    } finally {
        connections.remove(client);
        IO.println("End of service to client " + clientNum);
    }
}

// um inteiro, ou -1 se a string não for um
int integer(String string) {
    try {
        return Integer.parseInt(string);
    } catch (NumberFormatException e) {
        return -1;
    }
}

A estrutura do servidor de eco segue a arquitetura básica dos servidores TCP descrita anteriormente, com alguns acréscimos:

  • linhas 10 e 12: dois campos da classe implícita do arquivo-fonte compacto. O conjunto [connections] contém as conexões de serviço atuais; várias threads adicionam e removem elementos dele simultaneamente, portanto é um conjunto projetado para acesso concorrente, obtido por meio de [ConcurrentHashMap.newKeySet()] (Capítulo 8). O booleano [stop] indica se foi solicitado o encerramento do servidor; ele é declarado como [volatile] porque é modificado por uma thread e lido por outras;
  • linhas 16–20: a porta deve ser um inteiro entre 1 e 65.535. O método [integer] (linhas 99–105) retorna -1 se o argumento não for um inteiro;
  • linhas 22–24: o serviço de escuta e o método [ExecutorService], que cria uma thread virtual para cada cliente;
  • linha 26: o servidor é encerrado. Ctrl-C não aciona um método escolhido pelo programa, como faria um tratador de eventos; em vez disso, ele encerra a máquina virtual. No entanto, antes de encerrar, a máquina virtual executa os “shutdown hooks” registrados por [Runtime.getRuntime().addShutdownHook]. Nosso hook (linhas 55–67) é uma thread que detecta que um encerramento foi solicitado (linha 58), fecha o serviço de escuta (linha 60) e então espera a thread principal terminar (linha 62): a máquina virtual só é de fato encerrada quando os hooks terminam;
  • linha 32: fechar o serviço de escuta faz a espera por um cliente falhar, o que dispara uma [SocketException], interceptada na linha 38. Se o encerramento não foi solicitado, trata-se de um erro genuíno: ela é relançada (linha 41) para ser tratada pelo [catch] da linha 49;
  • Linhas 43–47: todas as conexões de serviço ativas são fechadas: as threads de serviço, bloqueadas em uma operação de leitura, recebem uma [SocketException] e terminam. Na saída do [try] com recursos, o método [close] do [ExecutorService] espera todos os serviços terminarem antes que o método [main] termine.

A parte do “atendimento ao cliente”:

  • linha 71: o endereço e a porta do cliente;
  • linhas 73–75: o socket do cliente, declarado no início do [try] com recursos (o Java 9 aceita uma variável declarada anteriormente), e os fluxos de leitura e escrita na conexão;
  • linha 79: a requisição do cliente é lida. [readLine] retorna [null] quando o cliente fecha a conexão: o laço e o serviço então terminam;
  • linha 82: a requisição é devolvida ao cliente, entre colchetes;
  • linhas 85–91: uma [IOException] sinaliza que o servidor foi encerrado, tendo fechado a conexão durante a leitura, ou que o cliente encerrou a conexão;
  • linhas 92–95: o [finally] remove a conexão da lista de conexões ativas e sinaliza o fim do serviço, qualquer que seja a causa.

Para ver o servidor em ação, precisamos de um cliente. Vamos escrevê-lo na próxima seção e apresentar os resultados em seguida.

12.6.2. Um cliente para o servidor de eco

Vamos agora escrever um cliente para o servidor anterior. Ele será chamado assim:

java Internet05.java machine port

Ele se conecta à máquina [machine] na porta [port]e então envia ao servidor as linhas de texto digitadas no teclado, e o servidor as devolve como eco. O programa [Internet05.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// cliente de eco: envia ao servidor as linhas digitadas no teclado
// e exibe as respostas do servidor
// chamada: java Internet05.java machine port

final String SYNTAX = "Syntax: java Internet05.java machine port";

void main(String[] args) {
    int port = args.length == 2 ? integer(args[1]) : -1;
    if (port < 1 || port > 65535) {
        IO.println(SYNTAX);
        return;
    }
    String server = args[0];

    // conexão ao serviço e depois streams de leitura e escrita na conexão
    try (var client = new Socket(server, port);
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         // autoFlush: cada linha escrita por println é enviada imediatamente pela rede
         var writer = new PrintWriter(client.getOutputStream(), true, UTF_8)) {
        IO.println("Connected to the server " + client.getRemoteSocketAddress() + " from "
                + client.getLocalSocketAddress());
        // laço requisição - resposta
        while (true) {
            // a requisição vem do teclado
            String request = IO.readln("Request (bye to stop): ");
            // terminou?
            if (request == null || request.strip().equalsIgnoreCase("bye")) {
                break;
            }
            // a requisição é enviada ao servidor
            writer.println(request);
            // esperamos sua resposta
            String response = reader.readLine();
            if (response == null) {
                IO.println("The server closed the connection");
                break;
            }
            IO.println("Response: " + response);
        }
    } catch (IOException e) {
        IO.println("The following error occurred: " + e.getClass().getSimpleName()
                + " (" + e.getMessage() + ")");
    }
}

// um inteiro, ou -1 se a string não for um
int integer(String string) {
    try {
        return Integer.parseInt(string);
    } catch (NumberFormatException e) {
        return -1;
    }
}

A estrutura deste cliente segue a arquitetura básica proposta para clientes TCP:

  • linhas 18–21: conexão com o servidor e criação dos fluxos de dados, já comentadas;
  • linhas 22–23: as duas extremidades da conexão são exibidas: [getRemoteSocketAddress] (o servidor) e [getLocalSocketAddress] (o cliente). A porta do cliente foi escolhida pelo sistema;
  • linha 27: a requisição é digitada no teclado. [IO.readln] retorna [null] se a entrada padrão for fechada (Ctrl-D no Linux, Ctrl-Z seguido de Enter no Windows);
  • linha 29: a comparação com [bye] não diferencia maiúsculas de minúsculas;
  • linha 33: a requisição é enviada ao servidor;
  • linhas 35–39: a resposta é aguardada; [null] indica que o servidor fechou a conexão;
  • linhas 42–45: erros de conexão e de troca de dados.

Estes são os resultados obtidos com a seguinte configuração:

  • o servidor está rodando na porta 27100 em uma janela de comando;
  • na mesma máquina, dois clientes, A e B, estão rodando em outras duas janelas; B foi iniciado enquanto A ainda se comunicava com o servidor.

Na janela do cliente A:

1
2
3
4
5
6
7
8
9
> java Internet05.java localhost 27100
Connected to the server localhost/127.0.0.1:27100 from /127.0.0.1:47902
Request (bye to stop): line1A
Response: [line1A]
Request (bye to stop): line2A
Response: [line2A]
Request (bye to stop): line3A
Response: [line3A]
Request (bye to stop): bye

O cliente A enviou três linhas, que foram devolvidas como eco, e então digitou [bye]: ele fechou a conexão sem enviar nada ao servidor.

Na janela do cliente B:

1
2
3
4
5
6
7
8
> java Internet05.java localhost 27100
Connected to the server localhost/127.0.0.1:27100 from /127.0.0.1:45096
Request (bye to stop): line1B
Response: [line1B]
Request (bye to stop): line2B
Response: [line2B]
Request (bye to stop): line3B
The server closed the connection

O cliente B enviou duas linhas e, então, antes de digitar a terceira, o servidor foi encerrado com Ctrl-C. A linha [line3B] foi enviada por uma conexão que já havia sido fechada pelo servidor: a leitura da resposta (linha 8 dos resultados) retornou [null].

Na janela do servidor:

> java Internet04.java 27100
Echo server started on 0.0.0.0/0.0.0.0:27100
Start of service to client 0 (/127.0.0.1:47902)
<--- client 0 : line1A
---> client 0 : [line1A]
Start of service to client 1 (/127.0.0.1:45096)
<--- client 0 : line2A
---> client 0 : [line2A]
<--- client 1 : line1B
---> client 1 : [line1B]
<--- client 0 : line3A
---> client 0 : [line3A]
<--- client 1 : line2B
---> client 1 : [line2B]
End of service to client 0
Server stop requested
Service to client 1 interrupted by the server stop
End of service to client 1
  • linha 2: o servidor está escutando na porta 27100 a partir de todos os endereços da máquina, representados pelo endereço curinga 0.0.0.0;
  • Linhas 3 e 6: os dois clientes se conectaram a partir da mesma máquina (127.0.0.1) usando portas diferentes, atribuídas pelo sistema. Essas portas distinguem as duas conexões, que terminam ambas na porta 27100 do servidor;
  • linha 6: o cliente 1 (B) está sendo atendido enquanto o cliente 0 (A) ainda está sendo atendido, e as linhas 7–14 mostram que suas requisições são processadas à medida que chegam: o servidor realmente atende vários clientes simultaneamente;
  • linha 15: o servidor detectou que o cliente A fechou a conexão;
  • Linhas 16–18: Ctrl-C foi pressionado na janela do servidor. A tentativa de esperar um novo cliente falhou e, em seguida, o atendimento ao cliente 1, que esperava uma linha, foi interrompido quando sua conexão foi fechada. O servidor foi encerrado corretamente.

Veja o que acontece quando se tenta conectar a uma porta em que nenhum serviço está escutando:

> java Internet05.java localhost 27199
The following error occurred: ConnectException (Connection refused)

O construtor de [Socket] lançou uma [ConnectException]: a máquina respondeu, mas nenhum programa está escutando na porta 27199. A mensagem vem do sistema operacional; no Windows ela é diferente.

Por fim, se você iniciar o servidor em uma porta que já está em uso, por exemplo, em uma segunda janela enquanto o primeiro servidor ainda está rodando, a criação do [ServerSocket] falha:

> java Internet04.java 27100
The following error occurred on the server: Address already in use

12.6.3. Um cliente TCP genérico

Vamos escrever um cliente TCP genérico, que será iniciado assim:

java Internet06.java machine port

Ele funcionará de forma semelhante aos clientes [telnet] e PuTTY: permitirá a comunicação com qualquer servidor TCP baseado em texto.

No aplicativo anterior, o protocolo de comunicação era conhecido: o cliente enviava uma única linha e o servidor respondia com uma única linha. Cada serviço tem seu próprio protocolo específico, e também podem surgir as seguintes situações:

  • o cliente deve enviar várias linhas de texto antes de receber uma resposta (uma requisição HTTP);
  • a resposta de um servidor pode consistir em várias linhas de texto (a resposta [EHLO] de um servidor SMTP, um documento HTML);
  • o servidor pode falar primeiro (a mensagem de boas-vindas dos servidores SMTP e POP).

O ciclo “enviar uma única linha ao servidor / receber uma única linha enviada pelo servidor” nem sempre é adequado. Para tratar protocolos mais complexos que o protocolo de eco, o cliente TCP genérico executa duas atividades em paralelo, em duas threads:

  • uma thread virtual lê as linhas de texto digitadas no teclado e as envia ao servidor;
  • a thread principal lê as linhas de texto enviadas pelo servidor. Assim que recebe uma, ela a exibe no console. Ela só para quando a conexão é fechada.

O programa [Internet06.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// cliente TCP genérico
// - conecta-se ao serviço (machine, port)
// - uma thread virtual envia ao servidor cada linha digitada no teclado
// - a thread principal exibe continuamente as linhas enviadas pelo servidor
// chamada: java Internet06.java machine port

final String SYNTAX = "Syntax: java Internet06.java machine port";
// fim solicitado no teclado (bye)?
volatile boolean end = false;

void main(String[] args) {
    int port = args.length == 2 ? integer(args[1]) : -1;
    if (port < 1 || port > 65535) {
        IO.println(SYNTAX);
        return;
    }
    String server = args[0];

    // conexão ao serviço
    Socket client;
    try {
        client = new Socket(server, port);
    } catch (IOException e) {
        IO.println("Unable to connect to the service (" + server + ", " + port + "): "
                + e.getMessage());
        return;
    }
    try (client;
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var writer = new OutputStreamWriter(client.getOutputStream(), UTF_8)) {
        IO.println("Type your commands (bye to stop):");
        // a leitura dos comandos do teclado é confiada a uma thread virtual
        Thread.ofVirtual().start(() -> input(client, writer));
        // a thread principal exibe as linhas do servidor até que a conexão seja fechada
        String response;
        while ((response = reader.readLine()) != null) {
            IO.println("<-- " + response);
        }
        IO.println("[the server closed the connection]");
    } catch (IOException e) {
        // uma conexão fechada pela thread de entrada (bye) não é um erro
        if (!end) {
            IO.println("The following error occurred while reading: " + e.getMessage());
        }
    }
    // fim da thread principal: a thread virtual de entrada, se ainda estiver esperando o teclado, é abandonada
}

// envia ao servidor as linhas digitadas no teclado, até bye
void input(Socket client, Writer writer) {
    try {
        while (true) {
            String command = IO.readln();
            // terminou?
            if (command == null || command.strip().equalsIgnoreCase("bye")) {
                break;
            }
            // as linhas enviadas terminam com \r\n, como exigem HTTP, SMTP, POP, FTP...
            writer.write(command + "\r\n");
            writer.flush();
        }
    } catch (IOException e) {
        IO.println("The following error occurred while writing: " + e.getMessage());
    } finally {
        // a conexão é fechada: a leitura em andamento na thread principal termina
        end = true;
        try {
            client.close();
        } catch (IOException e) {
            // nada a fazer
        }
    }
}

// um inteiro, ou -1 se a string não for um
int integer(String string) {
    try {
        return Integer.parseInt(string);
    } catch (NumberFormatException e) {
        return -1;
    }
}
  • linhas 23–29: o cliente se conecta ao servidor;
  • linhas 30–32: o socket e seus fluxos são fechados na saída do [try]. O fluxo de escrita é um simples [OutputStreamWriter], cujos métodos lançam uma [IOException] em caso de erro;
  • linha 35: a entrada do teclado é tratada por uma thread virtual, criada e iniciada por [Thread.ofVirtual().start] (Java 21), que executa o método [input] (linhas 52–75);
  • linhas 37–41: enquanto isso, a thread principal exibe cada linha enviada pelo servidor, precedida de [<--], até o fim do fluxo (linha 41);
  • Linhas 42–47: quando o usuário digita [bye], a thread de entrada fecha a conexão (linha 70); a operação de leitura em andamento na thread principal termina então com uma [SocketException]. Isso não é um erro: o campo [end], definido pela thread de entrada (linha 68), confirma isso;
  • linha 48: quando o servidor fecha a conexão, a thread principal termina, enquanto a thread de entrada ainda pode estar esperando uma linha do teclado. Isso não é um problema: uma thread virtual é sempre uma “thread daemon”, e a máquina virtual para quando todas as threads não daemon terminam (neste caso, apenas a thread principal). Ao contrário do que seria necessário com uma thread comum, não há necessidade de parar a thread de entrada;
  • Linhas 55–63: a thread de entrada lê as linhas digitadas no teclado e as envia ao servidor. As linhas enviadas terminam com \r\n, como exigem os protocolos que queremos explorar, e são transmitidas imediatamente pela rede por [flush].

Agora podemos enviar manualmente uma requisição HTTP ao nosso servidor web de teste ([Internet03.java]), que está rodando em outra janela. As linhas precedidas de [<--] são as enviadas pelo servidor; as demais foram digitadas no teclado:

> java Internet06.java localhost 27110
Type your commands (bye to stop):
GET /hello?name=Serge HTTP/1.1
Host: localhost:27110
Connection: close

<-- HTTP/1.1 200 OK
<-- Date: Sat, 03 Oct 2026 17:40:20 GMT
<-- Transfer-encoding: chunked
<-- Content-type: text/plain; charset=utf-8
<-- 
<-- c
<-- Hello Serge!
<-- 0
<-- 
[the server closed the connection]
  • linhas 3–5: a requisição, digitada no teclado: estamos solicitando o documento [/hello?name=Serge]. O cabeçalho [Connection: close] instrui o servidor a fechar a conexão depois de enviar sua resposta;
  • Linha 6: a linha em branco encerra a requisição. Ela dispara a resposta do servidor;
  • linha 7: o documento foi encontrado;
  • linha 9: o servidor não especificou o tamanho do documento ([Content-length]); ele o envia em blocos (chunks), cada um precedido de seu tamanho em hexadecimal;
  • linha 10: desta vez, o documento é texto simples;
  • linhas 12–14: um único bloco de 0x0c = 12 bytes, o texto [Hello Serge!], seguido de um bloco de tamanho zero que marca o fim do documento;
  • linha 16: conforme solicitado, o servidor fechou a conexão. O cliente detectou isso e parou por conta própria, sem esperar que o usuário digitasse [bye].

Vamos tentar de novo sem o cabeçalho [Connection: close], solicitando o diretório raiz do site:

> java Internet06.java localhost 27110
Type your commands (bye to stop):
GET / HTTP/1.1
Host: localhost:27110

<-- HTTP/1.1 200 OK
<-- Date: Sat, 03 Oct 2026 17:40:23 GMT
<-- Content-type: text/html; charset=utf-8
<-- Content-length: 171
<-- 
<-- <!DOCTYPE html>
<-- <html lang="en">
<-- <head><meta charset="utf-8"><title>Test server</title></head>
<-- <body><h1>Welcome to the test server of the Java course</h1></body>
<-- </html>
bye
  • linha 9: o documento é anunciado junto com seu tamanho, 171 bytes. O cliente sabe, portanto, onde ele termina;
  • Linhas 15–16: o documento foi totalmente recebido, mas o servidor não fechou a conexão: no HTTP/1.1, ela permanece aberta por padrão para novas requisições. O servidor espera uma nova requisição; o usuário então digita [bye] para fechar a conexão.

Quando o servidor está indisponível, a conexão falha:

> java Internet06.java localhost 27199
Unable to connect to the service (localhost, 27199): Connection refused

O leitor pode usar esse cliente TCP genérico com o servidor de eco ou, se tiver um servidor SMTP ou POP3 que aceite conexões não criptografadas (como um servidor de teste instalado localmente), para reproduzir os diálogos de exemplo mostrados acima.

12.6.4. Um servidor TCP genérico

Vamos agora nos concentrar em um servidor:

  • que exibe na tela as linhas enviadas por seus clientes;
  • que devolve como respostas as linhas de texto digitadas no teclado por um usuário. O usuário, portanto, faz o papel do servidor.

O programa é iniciado em uma janela de comando por [java Internet07.java port], onde [port] é a porta à qual os clientes devem se conectar. Os clientes são atendidos um após o outro, não em paralelo: o console não pode ser usado por dois clientes simultaneamente. Os clientes que se conectam nesse intervalo têm suas conexões estabelecidas pelo sistema, mas precisam esperar que o programa os aceite. Três atividades ocorrem em paralelo:

  • uma thread virtual lê as linhas digitadas no teclado durante toda a execução do programa;
  • para cada cliente, uma thread virtual lê as linhas enviadas pelo cliente e as exibe;
  • a thread principal aceita os clientes e envia as linhas digitadas no teclado ao cliente atual. O usuário sinaliza com o comando [bye] que está fechando a conexão com o cliente.

A thread principal deve, portanto, esperar dois tipos de eventos: uma linha digitada no teclado ou a saída do cliente. As outras duas threads sinalizam esses eventos a ela colocando-os em uma fila bloqueante ([BlockingQueue], Capítulo 8), da qual ela os retira um a um. O servidor só para quando o usuário pressiona Ctrl-C no teclado ou quando a entrada padrão é fechada. O programa [Internet07.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// servidor TCP genérico
// - exibe as linhas enviadas pelo cliente
// - envia a ele, como respostas, as linhas digitadas no teclado pelo usuário
// os clientes são atendidos um após o outro (um único console)
// chamada: java Internet07.java port; parar com Ctrl-C

final String SYNTAX = "Syntax: java Internet07.java port";

// os eventos aguardados pelo programa principal
sealed interface Event permits Input, EndOfInput, ClientLeft {
}

// uma linha digitada no teclado
record Input(String line) implements Event {
}

// fim da entrada padrão (Ctrl-D, Ctrl-Z)
record EndOfInput() implements Event {
}

// o cliente nº [clientNum] fechou a conexão
record ClientLeft(int clientNum) implements Event {
}

// a fila de eventos, alimentada por duas threads virtuais: o teclado e a leitura do cliente
final BlockingQueue<Event> events = new LinkedBlockingQueue<>();

void main(String[] args) throws InterruptedException {
    int port = args.length == 1 ? integer(args[0]) : -1;
    if (port < 1 || port > 65535) {
        IO.println(SYNTAX);
        return;
    }
    // o serviço de escuta
    try (var listener = new ServerSocket(port)) {
        IO.println("Generic server started on " + listener.getLocalSocketAddress());
        // uma thread virtual lê o teclado durante toda a duração do programa
        Thread.ofVirtual().start(this::readKeyboard);
        // laço de serviço - o servidor é parado por Ctrl-C
        for (int clientNum = 0; ; clientNum++) {
            // esperando um cliente
            IO.println("Waiting for the next client...");
            Socket client = listener.accept();
            IO.println("Client " + client.getRemoteSocketAddress());
            // uma thread virtual exibe as linhas enviadas pelo cliente
            int number = clientNum;
            Thread reception = Thread.ofVirtual().start(() -> receive(client, number));
            IO.println("Type your responses (bye to close the connection with the client):");
            boolean carryOn = true;
            // a conexão com o cliente é fechada ao sair do try
            try (client; var writer = new OutputStreamWriter(client.getOutputStream(), UTF_8)) {
                // os eventos são tratados até o fim da conexão com este cliente
                carryOn = serve(writer, clientNum);
            } catch (IOException e) {
                IO.println("The following error occurred while writing: " + e.getMessage());
            }
            // esperamos o fim da thread de recepção
            reception.join();
            // fim da entrada padrão: o servidor para
            if (!carryOn) {
                return;
            }
        }
    } catch (IOException e) {
        IO.println("The following error occurred on the server: " + e.getMessage());
    }
}

// o diálogo com o cliente nº [clientNum]; retorna false se a entrada padrão foi fechada
boolean serve(Writer writer, int clientNum) throws IOException, InterruptedException {
    while (true) {
        // esperamos ou uma linha digitada no teclado, ou a saída do cliente
        switch (events.take()) {
            case ClientLeft(int number) when number == clientNum -> {
                IO.println("[the client closed the connection]");
                return true;
            }
            case ClientLeft _ -> {
                // saída de um cliente anterior, já tratada: ela é ignorada
            }
            case EndOfInput _ -> {
                return false;
            }
            case Input(String response) when response.strip().equalsIgnoreCase("bye") -> {
                IO.println("[connection closed by the server]");
                return true;
            }
            case Input(String response) -> {
                // a resposta é enviada ao cliente
                writer.write(response + "\r\n");
                writer.flush();
            }
        }
    }
}

// lê o teclado e coloca cada linha digitada na fila de eventos
void readKeyboard() {
    String line;
    while ((line = IO.readln()) != null) {
        events.add(new Input(line));
    }
    events.add(new EndOfInput());
}

// exibe as linhas enviadas pelo cliente até que a conexão seja fechada
void receive(Socket client, int clientNum) {
    try {
        var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
        String request;
        while ((request = reader.readLine()) != null) {
            IO.println("<-- " + request);
        }
    } catch (IOException e) {
        // a conexão foi fechada pelo servidor durante a leitura
    }
    // a saída do cliente é informada ao programa principal
    events.add(new ClientLeft(clientNum));
}

// um inteiro, ou -1 se a string não for um
int integer(String string) {
    try {
        return Integer.parseInt(string);
    } catch (NumberFormatException e) {
        return -1;
    }
}
  • linhas 12–25: os três tipos de eventos, records que implementam uma interface selada ([sealed], Java 17): a cláusula [permits] fornece uma lista exaustiva de suas implementações. Em um arquivo-fonte compacto, esses tipos são membros da classe implícita;
  • linha 28: a fila de eventos. [LinkedBlockingQueue] pode ser usada concorrentemente por várias threads sem nenhuma precaução especial;
  • linha 37: o serviço de escuta, em todas as interfaces de rede da máquina;
  • linha 40: a thread virtual de leitura do teclado, que executa o método [readKeyboard] (linhas 100–106). Ela coloca cada linha lida na fila e depois dispara um evento [EndOfInput] quando a entrada padrão é fechada. Ela é iniciada apenas uma vez: quando um cliente fecha a conexão, a operação de leitura do teclado em andamento será usada pelo cliente seguinte. Iniciar uma nova operação de leitura para cada cliente faria duas operações de leitura competirem pelas mesmas teclas digitadas;
  • linha 42: laço infinito de espera por clientes. O usuário vai parar o servidor pressionando Ctrl-C;
  • Linha 45: espera por um cliente. Quando o cliente chega, o [Socket] retornado por [accept] representa o lado do servidor da conexão aberta com o cliente;
  • linha 49: a leitura das linhas enviadas pelo cliente é tratada por uma thread virtual, que executa o método [receive] (linhas 109–121). Quando a conexão é fechada, essa thread coloca na fila um evento [ClientLeft] contendo o número do cliente;
  • Linhas 53–58: a comunicação com o cliente é tratada pelo método [serve]. A conexão é fechada na saída do [try] com recursos;
  • linha 60: o programa espera a thread de recepção terminar usando [join];
  • linhas 62–64: se a entrada padrão foi fechada, o servidor é encerrado;
  • linhas 72–97: o método [serve] retira eventos da fila (linha 75) e os processa usando um [switch] sobre padrões de record (Java 21). Como a interface é selada, o compilador verifica se todos os casos são tratados:
    • linha 76: o padrão [ClientLeft(int number)] decompõe o record e armazena seu campo na variável [number]; o guard [when] verifica se se trata do cliente atual;
    • linha 80: um evento [ClientLeft] de outro cliente se origina de uma conexão fechada pelo próprio servidor (comando [bye]): ele é ignorado. O padrão anônimo [_] (Java 22) indica que o objeto não é necessário;
    • linhas 83–85: fim da entrada padrão;
    • linhas 86–89: o comando [bye] fecha a conexão com o cliente atual;
    • linhas 90–94: qualquer outra linha digitada é enviada ao cliente, terminada por \r\n.

Vamos usar este servidor para simular um servidor web consultado por um cliente HTTP, neste caso o [curl]. O servidor genérico está rodando na porta 27101. Em outra janela, pedimos ao [curl] a URL [http://localhost:27101/example.html]. O [curl] então se conecta à porta 27101 da máquina [localhost] e solicita o documento [/example.html]. Esta é a janela do servidor:

> java Internet07.java 27101
Generic server started on 0.0.0.0/0.0.0.0:27101
Waiting for the next client...
Client /127.0.0.1:60386
Type your responses (bye to close the connection with the client):
<-- GET /example.html HTTP/1.1
<-- Host: localhost:27101
<-- User-Agent: curl/8.5.0
<-- Accept: */*
<-- 
HTTP/1.1 200 OK
Server: generic tcp server
Connection: close
Content-Type: text/html; charset=utf-8

<html><head><title>Generic server</title></head>
<body><h1>Response of the generic server</h1></body></html>
bye
[connection closed by the server]
Waiting for the next client...
  • linha 4: um cliente chegou;
  • linhas 6–10: vemos a requisição HTTP enviada pelo [curl], terminando com uma linha em branco. Um navegador enviaria muitos outros cabeçalhos (idiomas e formatos aceitos, compressão, cookies etc.): o leitor pode testar isso solicitando a mesma URL em seu navegador;
  • Linhas 11–17: o usuário ao teclado é aqui o servidor de verdade, e ele monta a resposta manualmente. Ele se limita ao mínimo: uma linha de status, três cabeçalhos, uma linha em branco e o documento HTML. Ele não especifica o tamanho do documento ([Content-Length]), mas indica que fechará a conexão depois de enviá-lo ([Connection: close]). Isso basta: quando o cliente vê a conexão se fechar, sabe que a resposta está completa;
  • linhas 18–19: o usuário digitou [bye]: o servidor fecha a conexão com o cliente;
  • linha 20: o servidor espera um novo cliente. Nós o paramos com Ctrl-C.

E aqui está o que o [curl] exibiu:

> curl -sv http://localhost:27101/example.html
* Host localhost:27101 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying 127.0.0.1:27101...
* Connected to localhost (127.0.0.1) port 27101
> GET /example.html HTTP/1.1
> Host: localhost:27101
> User-Agent: curl/8.5.0
> Accept: */*
> 
< HTTP/1.1 200 OK
< Server: generic tcp server
< Connection: close
< Content-Type: text/html; charset=utf-8
< 
{ [50 bytes data]
* Closing connection
<html><head><title>Generic server</title></head>
<body><h1>Response of the generic server</h1></body></html>

O [curl] recebeu exatamente o que foi digitado na janela do servidor (linhas 12–16 e 19–20) e detectou que a conexão foi fechada (linha 18). Um navegador teria exibido a página HTML recebida, com o título [Generic server] na aba.

12.6.5. Um cliente web

No exemplo anterior, vimos os cabeçalhos HTTP enviados pelo [curl]. Vamos escrever um cliente web que recebe uma URL como parâmetro e exibe na tela tudo o que o servidor lhe envia. Vamos supor que o servidor suporte o protocolo HTTP/1.1. Nosso cliente enviará a seguinte requisição:

1
2
3
4
GET /document HTTP/1.1
Host: machine:port
User-Agent: web-client-java-course
Connection: close
  • a primeira linha especifica o documento desejado;
  • o cabeçalho [Host] especifica o servidor consultado;
  • o cabeçalho [User-Agent] identifica nosso cliente;
  • o cabeçalho [Connection] indica que queremos que o servidor feche a conexão depois de nos responder: leremos sua resposta até o fim do fluxo;
  • a linha vazia encerra a requisição.

Se, na primeira linha, substituirmos [GET] por [HEAD], o servidor nos enviará apenas os cabeçalhos HTTP de sua resposta, e não o documento.

Nosso cliente web será chamado assim: [java Internet08.java URL command], onde [URL] é a URL desejada e [command] é uma das duas palavras-chave [GET] ou [HEAD]. O programa [Internet08.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// cliente web: solicita uma URL com uma requisição HTTP/1.1 escrita "à mão"
// e exibe tudo o que o servidor devolve (cabeçalhos HTTP e documento)
// chamada: java Internet08.java URL GET|HEAD

final String SYNTAX = "Syntax: java Internet08.java http://machine[:port][/document] GET|HEAD";

void main(String[] args) {
    if (args.length != 2) {
        IO.println(SYNTAX);
        return;
    }
    // verificação da URL: ela deve ser absoluta e usar o esquema http
    URI uri = parse(args[0]);
    if (uri == null) {
        IO.println("Incorrect URL [" + args[0] + "]. " + SYNTAX);
        return;
    }
    // verificação do comando
    String command = args[1].toUpperCase();
    if (!command.equals("GET") && !command.equals("HEAD")) {
        IO.println("The second parameter must be GET or HEAD. " + SYNTAX);
        return;
    }

    // conexão ao servidor web: a porta 80 é a porta padrão do HTTP
    int port = uri.getPort() == -1 ? 80 : uri.getPort();
    try (var client = new Socket(uri.getHost(), port);
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var writer = new BufferedWriter(new OutputStreamWriter(client.getOutputStream(), UTF_8))) {
        // a requisição: linha de comando, cabeçalhos HTTP, linha vazia; o HTTP exige o fim de linha \r\n
        writer.write(command + " " + pathAndQuery(uri) + " HTTP/1.1\r\n");
        writer.write("Host: " + uri.getRawAuthority() + "\r\n");
        writer.write("User-Agent: web-client-java-course\r\n");
        writer.write("Connection: close\r\n");
        writer.write("\r\n");
        // a requisição é enviada de uma só vez pela rede
        writer.flush();
        // a resposta é lida até que o servidor feche a conexão
        String line;
        while ((line = reader.readLine()) != null) {
            IO.println(line);
        }
    } catch (IOException e) {
        IO.println("The following error occurred: " + e.getClass().getSimpleName()
                + " (" + e.getMessage() + ")");
    }
}

// uma URL http absoluta correta, ou null
URI parse(String url) {
    try {
        URI uri = new URI(url);
        return uri.isAbsolute() && uri.getScheme().equals("http") && uri.getHost() != null ? uri : null;
    } catch (URISyntaxException e) {
        return null;
    }
}

// o caminho do documento e os possíveis parâmetros, por exemplo /hello?name=Serge
String pathAndQuery(URI uri) {
    String path = uri.getRawPath().isEmpty() ? "/" : uri.getRawPath();
    return uri.getRawQuery() == null ? path : path + "?" + uri.getRawQuery();
}

A novidade neste programa é o uso da classe [URI] (pacote [java.net]). O programa recebe uma URL (Uniform Resource Locator), uma forma específica de URI (Uniform Resource Identifier), no formato [http://server:port/path?param1=val1&param2=val2]. A classe [URI] é usada para decompor essa cadeia em seus vários componentes:

  • linhas 52–59: o construtor [URI(String)] analisa a cadeia e lança uma [URISyntaxException] (uma exceção verificada) se ela não for uma URI válida; o método estático [URI.create] faz o mesmo lançando uma [IllegalArgumentException]. Em seguida, verificamos que a URI é absoluta (começa com um esquema), que o esquema é [http] (nosso cliente não consegue realizar a negociação TLS do [https]) e que ela se refere a uma máquina. Uma vez construído o objeto [URI], temos acesso aos vários elementos da URI. Assim, se o objeto [uri] foi construído a partir da cadeia [http://localhost:27110/hello?name=Serge], temos:
    • [uri.getScheme()]: http;
    • [uri.getHost()]: localhost;
    • [uri.getPort()]: 27110 (-1 se a porta não for especificada na URL; nesse caso, é a porta padrão do esquema: 80 para HTTP, 443 para HTTPS);
    • [uri.getRawAuthority()]: localhost:27110;
    • [uri.getRawPath()]: /hello;
    • [uri.getRawQuery()]: name=Serge;
    • Os métodos [getPath], [getQuery]… retornam os mesmos elementos, mas decodificados (veremos adiante o que é a codificação de uma URL): para construir uma consulta, é preciso usar as versões “raw” ([getRawXxx]);
  • linhas 62–65: o caminho e os parâmetros, como devem aparecer na requisição; um caminho vazio se refere à raiz do site ([/]);
  • linha 21: o comando deve ser [GET] ou [HEAD];
  • linhas 28–29: conexão com o servidor designado pela URL, na porta 80 se a URL não especificar nenhuma;
  • linha 31: o fluxo de escrita é um [BufferedWriter] sem descarga automática;
  • linhas 33–37: a requisição HTTP. O HTTP exige terminações de linha \r\n, que devem ser escritas explicitamente;
  • linha 39: a requisição é enviada de uma só vez, depois de totalmente escrita;
  • linhas 41–44: a resposta é exibida até o servidor fechar a conexão.

Vamos solicitar apenas os cabeçalhos da raiz do nosso servidor de teste:

1
2
3
4
5
> java Internet08.java http://localhost:27110/ HEAD
HTTP/1.1 200 OK
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-type: text/html; charset=utf-8
Content-length: 171

Recebemos a linha de status e os cabeçalhos, seguidos de uma linha em branco, mas não o documento. O cabeçalho [Content-length] indica o tamanho que o documento teria com o comando [GET]. Com o comando [GET] e um documento enviado em blocos:

1
2
3
4
5
6
7
8
9
> java Internet08.java "http://localhost:27110/hello?name=Serge" GET
HTTP/1.1 200 OK
Date: Sat, 03 Oct 2026 17:40:36 GMT
Transfer-encoding: chunked
Content-type: text/plain; charset=utf-8

c
Hello Serge!
0

Observe as aspas em torno da URL no comando: sem elas, alguns interpretadores de comandos atribuiriam um significado especial ao caractere [?]. O documento ([Hello Serge!]) é cercado pelos tamanhos de seus blocos, como já vimos. Nosso cliente exibe a resposta bruta; um verdadeiro cliente HTTP, por outro lado, deve reconstruir o documento a partir dos blocos.

Um documento inexistente:

1
2
3
4
> java Internet08.java http://localhost:27110/unknown GET
HTTP/1.1 404 Not Found
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-length: 0

Uma URL sujeita a um redirecionamento:

1
2
3
4
5
> java Internet08.java http://localhost:27110/old GET
HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-length: 0
Location: /hello?name=visitor
  • Linha 2: o código 302 indica um redirecionamento: o documento solicitado está temporariamente em outro endereço. A mensagem que segue o código pode ser qualquer uma: o servidor do JDK escreve [Temporary Redirect], enquanto outros servidores podem escrever [Found] (a mensagem da RFC) ou [Moved Temporarily];
  • Linha 5: esse endereço é fornecido pelo cabeçalho [Location]. Aqui ele é relativo: o endereço completo é [http://localhost:27110/hello?name=visitor].

Nosso cliente parou aí. Um navegador, por outro lado, teria solicitado automaticamente o novo endereço. É o que o nosso próximo cliente fará.

Por fim, uma URL [https] é rejeitada:

> java Internet08.java https://www.oracle.com/java/ GET
Incorrect URL [https://www.oracle.com/java/]. Syntax: java Internet08.java http://machine[:port][/document] GET|HEAD

12.6.6. Um cliente web que trata redirecionamentos

O cliente web anterior não trata um possível redirecionamento da URL que ele solicitou. Os códigos de status de redirecionamento são os seguintes:

Código
Significado
301 Moved Permanently
O documento foi movido permanentemente para um novo endereço; um navegador pode salvar o novo endereço
302 Found
O documento está temporariamente em outro endereço
303 See Other
A resposta deve ser solicitada de outro endereço usando o método [GET] (usado após o envio de um formulário)
307 Temporary Redirect, 308 Permanent Redirect
Igual a 302 e 301, mas o cliente deve reenviar a requisição usando o mesmo método ([POST] continua sendo [POST])

Em todos os casos, o novo endereço é fornecido pelo cabeçalho [Location], em forma absoluta ou relativa. Detectar um redirecionamento pela presença de uma palavra como [moved] na linha de status não seria confiável: a mensagem que segue o código é arbitrária, e acabamos de ver que o servidor do JDK responde com [302 Temporary Redirect]. Baseamo-nos no próprio código de status.

O programa [Internet09.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// cliente web que segue os redirecionamentos (códigos 301, 302, 303, 307, 308)
// chamada: java Internet09.java URL GET|HEAD

final String SYNTAX = "Syntax: java Internet09.java http://machine[:port][/document] GET|HEAD";
// os códigos de status HTTP que sinalizam um redirecionamento
final Set<Integer> REDIRECTION_CODES = Set.of(301, 302, 303, 307, 308);
// número máximo de redirecionamentos seguidos
final int MAX_REDIRECTIONS = 3;

void main(String[] args) {
    if (args.length != 2) {
        IO.println(SYNTAX);
        return;
    }
    URI uri = parse(args[0]);
    if (uri == null) {
        IO.println("Incorrect URL [" + args[0] + "]. " + SYNTAX);
        return;
    }
    String command = args[1].toUpperCase();
    if (!command.equals("GET") && !command.equals("HEAD")) {
        IO.println("The second parameter must be GET or HEAD. " + SYNTAX);
        return;
    }

    try {
        // uma iteração por URL solicitada
        for (int nbRedirections = 0; ; nbRedirections++) {
            // a URL é solicitada e o possível endereço de redirecionamento é recuperado
            Optional<String> location = request(uri, command);
            // sem redirecionamento: terminou
            if (location.isEmpty()) {
                break;
            }
            // redirecionamentos demais: desistimos
            if (nbRedirections == MAX_REDIRECTIONS) {
                IO.println("<-- Giving up: more than " + MAX_REDIRECTIONS + " redirections -->");
                break;
            }
            // a nova URL: o endereço de redirecionamento pode ser absoluto ou relativo à URL atual
            uri = uri.resolve(location.get());
            IO.println("<-- Redirection to " + uri + " -->\n");
        }
    } catch (IOException | IllegalArgumentException e) {
        IO.println("The following error occurred: " + e.getClass().getSimpleName()
                + " (" + e.getMessage() + ")");
    }
}

// solicita a URL [uri], exibe a resposta do servidor
// retorna o endereço de redirecionamento, ou um Optional vazio se não houver redirecionamento
Optional<String> request(URI uri, String command) throws IOException {
    int port = uri.getPort() == -1 ? 80 : uri.getPort();
    try (var client = new Socket(uri.getHost(), port);
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var writer = new BufferedWriter(new OutputStreamWriter(client.getOutputStream(), UTF_8))) {
        // a requisição HTTP
        writer.write(command + " " + pathAndQuery(uri) + " HTTP/1.1\r\n");
        writer.write("Host: " + uri.getRawAuthority() + "\r\n");
        writer.write("User-Agent: web-client-java-course\r\n");
        writer.write("Connection: close\r\n");
        writer.write("\r\n");
        writer.flush();

        // a linha de status, por exemplo: HTTP/1.1 302 Found
        String statusLine = Objects.requireNonNullElse(reader.readLine(), "");
        IO.println(statusLine);
        String[] fields = statusLine.split(" ");
        boolean redirection = fields.length >= 2 && REDIRECTION_CODES.contains(integer(fields[1]));

        // os cabeçalhos HTTP, até a linha vazia
        String location = null;
        String header;
        while ((header = reader.readLine()) != null && !header.isEmpty()) {
            IO.println(header);
            // o nome de um cabeçalho HTTP não diferencia maiúsculas de minúsculas
            if (redirection && header.regionMatches(true, 0, "Location:", 0, "Location:".length())) {
                location = header.substring("Location:".length()).strip();
            }
        }
        IO.println();
        // o possível documento
        String line;
        while ((line = reader.readLine()) != null) {
            IO.println(line);
        }
        return Optional.ofNullable(location);
    }
}

// uma URL http absoluta correta, ou null
URI parse(String url) {
    try {
        URI uri = new URI(url);
        return uri.isAbsolute() && uri.getScheme().equals("http") && uri.getHost() != null ? uri : null;
    } catch (URISyntaxException e) {
        return null;
    }
}

// o caminho do documento e os possíveis parâmetros, por exemplo /hello?name=Serge
String pathAndQuery(URI uri) {
    String path = uri.getRawPath().isEmpty() ? "/" : uri.getRawPath();
    return uri.getRawQuery() == null ? path : path + "?" + uri.getRawQuery();
}

// um inteiro, ou -1 se a string não for um
int integer(String string) {
    try {
        return Integer.parseInt(string);
    } catch (NumberFormatException e) {
        return -1;
    }
}

Em comparação com a versão anterior, as mudanças são as seguintes:

  • linha 8: os códigos de status que indicam um redirecionamento, em um conjunto fixo criado por [Set.of] (Capítulo 5);
  • linha 10: o número máximo de redirecionamentos permitidos. Sem um limite, um servidor mal configurado poderia prender nosso cliente em um laço infinito (os navegadores desistem depois de cerca de vinte redirecionamentos);
  • linha 30: o código que antes era executado para uma única URL agora pode ser executado sucessivamente para várias entradas de URL;
  • linha 32: o método [request] solicita a URL atual, exibe a resposta e retorna o endereço de redirecionamento na forma de um [Optional<String>] (Capítulo 3), que fica vazio se não houver redirecionamento;
  • linhas 38–41: o processo é abortado se o número máximo de redirecionamentos for atingido;
  • linha 43: o método [resolve] da classe [URI] calcula a nova URL. Se [location] for um endereço absoluto, ele é usado como está; se for relativo, é completado com base na URL atual, [uri]. [resolve] lança uma [IllegalArgumentException] se o endereço estiver incorreto: ela é interceptada na linha 46;
  • linhas 54–91: a requisição de uma URL:
    • linha 68: a linha de status é lida, por exemplo, [HTTP/1.1 302 Temporary Redirect]. [Objects.requireNonNullElse] substitui [null] (conexão fechada pelo servidor antes de qualquer resposta) por uma cadeia vazia;
    • linhas 70–71: extraem o código (o segundo campo da linha) e verificam se ele é um dos códigos de redirecionamento;
    • linhas 76–82: leem os cabeçalhos até a linha vazia. Se houver um redirecionamento, procuram o cabeçalho [Location], ignorando maiúsculas e minúsculas, pois os nomes de cabeçalho no HTTP não diferenciam maiúsculas de minúsculas: [regionMatches(true, ...)] compara o início do cabeçalho com [Location:], ignorando maiúsculas e minúsculas;
    • linhas 85–89: o restante da resposta é exibido, seguido do endereço de redirecionamento encontrado.

Vamos examinar novamente a URL [/old]:

> java Internet09.java http://localhost:27110/old GET
HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-length: 0
Location: /hello?name=visitor

<-- Redirection to http://localhost:27110/hello?name=visitor -->

HTTP/1.1 200 OK
Date: Sat, 03 Oct 2026 17:40:36 GMT
Transfer-encoding: chunked
Content-type: text/plain; charset=utf-8

e
Hello visitor!
0
  • linhas 2–6: o redirecionamento temporário para um endereço relativo;
  • linha 7: a nova URL, completada por [uri.resolve(location)];
  • linhas 9–17: a resposta à nova URL. O documento, que tem 0xe = 14 bytes, foi enviado em blocos.

A URL [/moved] é redirecionada permanentemente para um endereço absoluto:

> java Internet09.java http://localhost:27110/moved GET
HTTP/1.1 301 Moved Permanently
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-length: 0
Location: http://localhost:27110/

<-- Redirection to http://localhost:27110/ -->

HTTP/1.1 200 OK
Date: Sat, 03 Oct 2026 17:40:36 GMT
Content-type: text/html; charset=utf-8
Content-length: 171

<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the test server of the Java course</h1></body>
</html>

A URL [/loop] redireciona para si mesma:

> java Internet09.java http://localhost:27110/loop HEAD
HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:37 GMT
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:37 GMT
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:37 GMT
Location: /loop

<-- Redirection to http://localhost:27110/loop -->

HTTP/1.1 302 Temporary Redirect
Date: Sat, 03 Oct 2026 17:40:37 GMT
Location: /loop

<-- Giving up: more than 3 redirections -->

Nosso cliente seguiu três redirecionamentos e então desistiu (linha 24). Com o comando [HEAD], nenhum documento foi enviado.

O log do servidor web registrou todas as requisições das seções [A web client] and [A web client that handles redirects]:

> java Internet03.java
Web server started on http://localhost:27110
HEAD / HTTP/1.1 -> 200
GET /hello?name=Serge HTTP/1.1 -> 200
GET /unknown HTTP/1.1 -> 404
GET /old HTTP/1.1 -> 302
GET /old HTTP/1.1 -> 302
GET /hello?name=visitor HTTP/1.1 -> 200
GET /moved HTTP/1.1 -> 301
GET / HTTP/1.1 -> 200
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302
HEAD /loop HTTP/1.1 -> 302

Para cada redirecionamento, ele mostra a requisição que o disparou, seguida da requisição ao novo endereço (linhas 7–8 e 9–10), e as quatro requisições do laço interrompido (linhas 11–14).

Escrever um cliente HTTP sobre TCP ajuda a entender o protocolo, mas um cliente real precisa tratar muitas outras coisas: criptografia TLS, transmissão em blocos, compressão, conexões persistentes, HTTP/2… A segunda parte deste capítulo apresenta a classe Java [HttpClient], que cuida de tudo isso para nós.

12.7. Classes Java especializadas em um protocolo

Nos exemplos anteriores, o protocolo HTTP foi tratado usando um cliente TCP: tivemos de construir as requisições nós mesmos, analisar as linhas de status e os cabeçalhos e acompanhar os redirecionamentos. Poderíamos ter construído um cliente SMTP ou POP da mesma forma. Existem classes especializadas nesses protocolos: elas entendem o protocolo de comunicação entre o cliente e o servidor e poupam o desenvolvedor de ter de gerenciá-lo. Para o HTTP, o JDK fornece a classe [HttpClient]; para e-mail, usa-se a biblioteca Jakarta Mail. Vamos apresentá-las agora.

Os programas desta segunda parte, como os da primeira, são arquivos-fonte compactos na pasta [12-internet], numerados em sequência ([Internet10] a [Internet19]). Os que exigem uma biblioteca (Jackson para JSON, Jakarta Mail para e-mail) são projetos Maven, organizados em uma pasta de mesmo nome ([Internet10/], [Internet14/], [Internet19/]). A aplicação de exemplo no final do capítulo é um projeto Maven separado, [TaxV8]. As portas usadas têm a forma 272xx.

12.7.1. As classes URL e HttpURLConnection, agora obsoletas

Antes do Java 11, um programa Java que quisesse usar HTTP dispunha de duas classes, disponíveis desde as primeiras versões do Java:

  • a classe [URL], cujo método [openStream] retornava, em uma única instrução, um fluxo de leitura do documento designado pela URL;
  • a classe [HttpURLConnection], obtida pelo método [openConnection] de [URL], que era mais flexível: permitia ao usuário escolher o método HTTP ([GET], [HEAD], [POST]), adicionar cabeçalhos e ler o código de status e os cabeçalhos da resposta.

Essas classes ainda existem no Java 25, mas não envelheceram bem: [HttpURLConnection] é inteiramente síncrona, suporta apenas HTTP/1.1, é usada por meio de uma sequência de chamadas com ordem fixa (definir os cabeçalhos antes de escrever o documento, ler o código de status antes do documento…) e sinaliza códigos de erro por meio de exceções. Quanto aos construtores da classe [URL], que não analisavam corretamente todas as URLs, eles foram declarados obsoletos desde o Java 20: agora você cria um objeto [URI] e, se necessário, o converte usando seu método [toURL]. Um pequeno programa [Old.java] contendo a instrução [var url = new URL("http://localhost:27210/");] gera o seguinte aviso de compilação:

1
2
3
4
5
> javac -Xlint:all Old.java
Old.java:2: warning: [deprecation] URL(String) in URL has been deprecated
    var url = new URL("http://localhost:27210/");
              ^
1 warning

O Java 11 introduziu a classe [HttpClient] (no pacote [java.net.http]), projetada desde o início para HTTP/1.1 e HTTP/2, tanto para requisições síncronas quanto assíncronas, e capaz de reutilizar suas conexões e de ser usada por várias threads simultaneamente. É essa a que você deve usar hoje. Não trataremos mais de [URL] e [HttpURLConnection] , pois o leitor ainda as encontrará em código legado.

12.7.2. A classe HttpClient

12.7.2.1. Um servidor web de teste

Para ilustrar os recursos de [HttpClient], precisamos de um servidor web com mais funcionalidades que o da Parte 1 ([Internet03.java]): ele deve aceitar formulários, trocar JSON e ser capaz de lidar com atrasos. Vamos, portanto, escrever um segundo servidor de teste, [Internet10], que também se baseia no servidor HTTP do JDK. Para trocar JSON, ele usa a biblioteca Jackson (Capítulo 5): trata-se, portanto, de um projeto Maven. Mais uma vez, não é necessário entender esse programa em detalhes; basta saber com o que cada URL responde. O projeto tem a estrutura de diretórios usual do Maven:

1
2
3
4
5
12-internet/Internet10/
  pom.xml
  src/main/java/internet/
    Internet10.java      the server
    Person.java          a person, exchanged in JSON format

O arquivo [pom.xml] é o seguinte:

<?xml version="1.0" encoding="UTF-8"?>
<!-- um servidor web de teste local para os clientes java.net.http.HttpClient -->
<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>

    <groupId>examples.internet</groupId>
    <artifactId>internet10</artifactId>
    <version>1.0</version>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Jackson 3 para as trocas em formato JSON -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.15.0</version>
                <configuration>
                    <parameters>true</parameters>
                    <compilerArgs>
                        <arg>-Xlint:all</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <!-- mvn exec:java executa a classe principal -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <mainClass>internet.Internet10</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
  • linhas 8–10: o identificador do projeto;
  • linhas 12–15: a versão do Java e a codificação dos arquivos-fonte;
  • linhas 19–23: a única dependência, o Jackson 3;
  • linhas 28–38: o compilador, com todos os avisos ([-Xlint:all]);
  • linhas 40–47: o plugin que executa a classe principal com o comando [mvn exec:java].

O tipo [Person] é um record:

1
2
3
4
5
package internet;

// uma pessoa, trocada em formato JSON
public record Person(int id, String name, int age) {
}

A classe [Internet10] é a seguinte:

package internet;

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.net.InetAddress;
import java.net.InetSocketAddress;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.concurrent.Executors;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import tools.jackson.databind.json.JsonMapper;

// um servidor web local que será o alvo dos clientes java.net.http.HttpClient
// chamada: mvn exec:java [-Dexec.args="port"]   (porta 27210 por padrão); parar com Ctrl-C
public class Internet10 {

    // a página inicial: um documento HTML
    private static final String HOME = """
            <!DOCTYPE html>
            <html lang="en">
            <head><meta charset="utf-8"><title>Test server</title></head>
            <body><h1>Welcome to the HttpClient test server</h1></body>
            </html>
            """;
    // os tipos dos documentos enviados
    private static final String TEXT = "text/plain; charset=utf-8";
    private static final String JSON = "application/json";
    // GET /api/persons/n: uma pessoa designada por seu número
    private static final Pattern PERSON = Pattern.compile("GET /api/persons/(\\d+)");

    // um pequeno "banco de dados" de pessoas, trocadas em formato JSON, e seu lock
    private final List<Person> persons = new ArrayList<>(List.of(
            new Person(1, "Dupont", 42), new Person(2, "Durand", 35)));
    private final Object lock = new Object();
    // o conversor objetos <-> JSON
    private final JsonMapper mapper = JsonMapper.builder().build();

    public static void main(String[] args) throws IOException {
        int port = args.length == 1 ? Integer.parseInt(args[0]) : 27210;
        var address = new InetSocketAddress(InetAddress.getLoopbackAddress(), port);
        HttpServer server = HttpServer.create(address, 0);
        server.createContext("/", new Internet10()::process);
        // cada requisição é tratada por uma thread virtual: uma requisição lenta não bloqueia as outras
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        server.start();
        IO.println("Web server started on http://localhost:" + port);
    }

    // tratamento de uma requisição e depois trace no console: a requisição, a porta do cliente e o código de status
    private void process(HttpExchange exchange) {
        String start = "%s %s %s (client port %d)".formatted(exchange.getRequestMethod(),
                exchange.getRequestURI(), exchange.getProtocol(), exchange.getRemoteAddress().getPort());
        try (exchange) {
            respond(exchange);
            IO.println(start + " -> " + exchange.getResponseCode());
        } catch (IOException e) {
            // a conexão foi cortada durante a troca
            IO.println(start + " -> error: " + e.getMessage());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    // a resposta de acordo com o método e o caminho da URL
    private void respond(HttpExchange exchange) throws IOException, InterruptedException {
        String route = exchange.getRequestMethod() + " " + exchange.getRequestURI().getPath();
        // os parâmetros da URL
        Map<String, String> urlParameters = parameters(exchange.getRequestURI().getRawQuery());
        switch (route) {
            // a página inicial: um documento HTML
            case "GET /", "HEAD /" -> send(exchange, 200, HOME, "text/html; charset=utf-8");
            // um documento de texto construído a partir de um parâmetro da URL
            case "GET /hello", "HEAD /hello" -> send(exchange, 200,
                    "Hello " + urlParameters.getOrDefault("name", "unknown") + "!", TEXT);
            // os cabeçalhos HTTP recebidos pelo servidor (em ordem alfabética), devolvidos como texto
            case "GET /headers", "HEAD /headers" -> send(exchange, 200,
                    new TreeMap<>(exchange.getRequestHeaders()).entrySet().stream()
                            .map(header -> header.getKey() + ": " + String.join(", ", header.getValue()))
                            .collect(Collectors.joining("\n")),
                    TEXT);
            // redirecionamento temporário (302) para um endereço relativo
            case "GET /old", "HEAD /old" -> redirect(exchange, "/hello?name=visitor");
            // um redirecionamento que entra em loop sobre si mesmo
            case "GET /loop", "HEAD /loop" -> redirect(exchange, "/loop");
            // um erro de servidor (500 Internal Server Error)
            case "GET /error", "HEAD /error" -> exchange.sendResponseHeaders(500, -1);
            // uma resposta que demora: a thread virtual é suspensa durante a espera
            case "GET /slow" -> {
                int seconds = Integer.parseInt(urlParameters.get("seconds"));
                Thread.sleep(seconds * 1000L);
                send(exchange, 200, "Response obtained after " + seconds + " s", TEXT);
            }
            // um formulário enviado por POST: descreve-se o que foi recebido
            case "POST /form" -> {
                Map<String, String> fields = parameters(readDocument(exchange));
                String type = exchange.getRequestHeaders().getFirst("Content-Type");
                String description = fields.entrySet().stream()
                        .map(field -> field.getKey() + "=[" + field.getValue() + "]")
                        .collect(Collectors.joining(", "));
                send(exchange, 200, "Content-Type received: " + type + "\nFields received: " + description,
                        TEXT);
            }
            // qualquer texto enviado por POST: ele é devolvido em maiúsculas
            case "POST /text" -> send(exchange, 200,
                    "Content-Type received: " + exchange.getRequestHeaders().getFirst("Content-Type")
                            + "\nText received in upper case: " + readDocument(exchange).toUpperCase(),
                    TEXT);
            // a lista de pessoas
            case "GET /api/persons" -> {
                synchronized (lock) {
                    send(exchange, 200, mapper.writeValueAsString(persons), JSON);
                }
            }
            // adição de uma pessoa: o servidor atribui um número a ela e responde 201 Created
            case "POST /api/persons" -> {
                Person newPerson = mapper.readValue(readDocument(exchange), Person.class);
                synchronized (lock) {
                    int id = persons.stream().mapToInt(Person::id).max().orElse(0) + 1;
                    Person created = new Person(id, newPerson.name(), newPerson.age());
                    persons.add(created);
                    exchange.getResponseHeaders().set("Location", "/api/persons/" + id);
                    send(exchange, 201, mapper.writeValueAsString(created), JSON);
                }
            }
            default -> {
                // uma pessoa designada por seu número, ou 404 se ela não existir
                Matcher matcher = PERSON.matcher(route);
                if (matcher.matches()) {
                    int id = Integer.parseInt(matcher.group(1));
                    synchronized (lock) {
                        var person = persons.stream().filter(p -> p.id() == id).findFirst();
                        if (person.isPresent()) {
                            send(exchange, 200, mapper.writeValueAsString(person.get()), JSON);
                            return;
                        }
                    }
                }
                // qualquer outra URL dá a resposta 404 Not Found
                exchange.sendResponseHeaders(404, -1);
            }
        }
    }

    // envio de um documento de texto com seu código de status e seu tipo; nenhum documento para HEAD
    private void send(HttpExchange exchange, int code, String text, String type) throws IOException {
        byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().set("Content-Type", type);
        if (exchange.getRequestMethod().equals("HEAD")) {
            exchange.sendResponseHeaders(code, -1);
        } else {
            exchange.sendResponseHeaders(code, bytes.length);
            exchange.getResponseBody().write(bytes);
        }
    }

    // redirecionamento temporário (302): cabeçalho Location, sem documento
    private void redirect(HttpExchange exchange, String address) throws IOException {
        exchange.getResponseHeaders().set("Location", address);
        exchange.sendResponseHeaders(302, -1);
    }

    // o documento enviado pelo cliente, decodificado em UTF-8
    private String readDocument(HttpExchange exchange) throws IOException {
        return new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
    }

    // os parâmetros name1=value1&name2=value2 de uma URL ou de um formulário, decodificados
    private Map<String, String> parameters(String string) {
        Map<String, String> result = new LinkedHashMap<>();
        if (string != null && !string.isEmpty()) {
            for (String pair : string.split("&")) {
                String[] fields = pair.split("=", 2);
                result.put(URLDecoder.decode(fields[0], StandardCharsets.UTF_8),
                        fields.length == 2 ? URLDecoder.decode(fields[1], StandardCharsets.UTF_8) : "");
            }
        }
        return result;
    }
}

Comentários:

  • linha 23: em um projeto Maven, escrevemos classes comuns, com seu pacote ([internet]) e imports, em vez de arquivos-fonte compactos;
  • linhas 40–44: os dados do servidor: um pequeno “banco de dados” de pessoas, o lock que o protege e o objeto Jackson [JsonMapper] que converte objetos em JSON e vice-versa;
  • linhas 50–52: todas as URLs são passadas ao método [process] de uma instância de [Internet10]. Por padrão, o servidor do JDK processa todas as requisições em uma única thread: uma requisição lenta bloquearia todas as outras. O método [setExecutor] fornece a ele um [ExecutorService] que executa cada requisição em uma thread virtual;
  • linhas 58–70: cada requisição é exibida no console junto com a porta do cliente e o código de status da resposta. A porta do cliente nos permitirá determinar se duas requisições usaram a mesma conexão TCP;
  • linha 74: a “rota” da requisição, formada por seu método e pelo caminho da URL ([GET /hello], [POST /form]…), sobre a qual o [switch] da linha 77 é executado;
  • linha 79: a URL [/] retorna um pequeno documento HTML;
  • linha 81: a URL [/hello?name=xx] gera o texto [Hello xx!];
  • Linha 84: a URL [/headers] devolve ao cliente, como texto, os cabeçalhos HTTP da requisição do cliente, ordenados alfabeticamente por meio de um [TreeMap]. Isso nos permitirá ver o que o [HttpClient] envia;
  • linhas 90–92: um redirecionamento temporário para [/hello?name=visitor] e um redirecionamento que volta para si mesmo, como no servidor da primeira parte;
  • linha 94: uma resposta 500 (erro interno do servidor);
  • linhas 96–100: a URL [/slow?seconds=n] só responde depois que n segundos se passaram. A thread virtual que processa a requisição fica suspensa durante esse tempo, sem bloquear nenhuma thread do sistema;
  • linhas 102–110: a URL [/form] recebe um formulário enviado pelo método [POST] e descreve o que recebeu;
  • linhas 112–115: a URL [/text] recebe texto arbitrário por [POST] e o devolve em maiúsculas;
  • linhas 117–148: o “banco de dados” de pessoas, trocado em formato JSON. [GET /api/persons] retorna a lista de pessoas, [GET /api/persons/n] retorna a pessoa de número n (ou uma resposta 404), [POST /api/persons] adiciona a pessoa enviada pelo cliente, atribui-lhe um número e responde com o código de status 201 (Created) e um cabeçalho [Location] contendo a URL da nova pessoa. Como várias requisições podem ser processadas simultaneamente por threads diferentes, a lista é protegida por um lock ([synchronized], Capítulo 8). [writeValueAsString] converte um objeto em um documento JSON; [readValue] realiza a operação inversa;
  • linha 147: qualquer outra URL retorna uma resposta 404.

O servidor é iniciado em uma janela de comando a partir da pasta [Internet10] com [mvn compile exec:java] e permanece em execução ali durante todos os testes desta seção. As requisições que ele recebeu serão apresentadas no final da seção.

12.7.2.2. Baixando um documento: send e BodyHandlers

O uso de [HttpClient] envolve três tipos:

  • [HttpClient]: o próprio cliente, criado por [HttpClient.newHttpClient()] ou, para configurá-lo, por [HttpClient.newBuilder()...build()];
  • [HttpRequest]: uma requisição, também construída por um “construtor” ([builder]): [HttpRequest.newBuilder(uri)...build()]. Salvo indicação em contrário, trata-se de uma requisição [GET];
  • [HttpResponse<T>]: a resposta, retornada pelo método [send(request, handler)] do cliente. O segundo parâmetro, um [BodyHandler<T>], especifica o que fazer com o documento recebido; a classe [BodyHandlers] fornece os handlers mais comuns:
Handler
O documento é retornado como
BodyHandlers.ofString()
cadeia de caracteres ([HttpResponse<String>]), decodificada de acordo com o conjunto de caracteres especificado pelo cabeçalho [Content-Type]
BodyHandlers.ofByteArray()
array de bytes (uma imagem, por exemplo)
BodyHandlers.ofInputStream(), ofLines()
fluxo de bytes ou stream ([Stream<String>]) de linhas, para serem lidos à medida que o documento chega (por exemplo, um arquivo grande)
BodyHandlers.ofFile(Path)
arquivo no qual o documento é salvo
BodyHandlers.discarding()
nenhum: o documento é ignorado

O método [send] é síncrono: ele retorna a resposta quando seus cabeçalhos e, exceto no caso de fluxos, seu documento chegaram. Ele lança uma [IOException] em caso de problema de comunicação, mas não para um código de status de erro: uma resposta 404 é tratada como qualquer outra resposta. Veremos sua versão assíncrona, [sendAsync], mais adiante.

O programa [Internet11.java] é o seguinte:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

// primeiros passos com java.net.http.HttpClient: download de um documento
// o servidor de teste [Internet10] deve estar iniciado na porta 27210

// o endereço base das URLs relativas que serão solicitadas
final URI BASE = URI.create("http://localhost:27210/");

void main() throws IOException, InterruptedException {
    // um cliente HTTP, fechado ao sair do try (HttpClient é AutoCloseable desde o Java 21)
    try (HttpClient client = HttpClient.newHttpClient()) {
        // 1 - um documento de texto: requisição GET, documento recebido como string
        HttpRequest request = HttpRequest.newBuilder(BASE.resolve("hello?name=Serge")).build();
        HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
        IO.println("Document received: " + response.body());

        // 2 - os cabeçalhos HTTP enviados pelo HttpClient, como o servidor os recebeu
        IO.println("--- headers sent by default");
        request = HttpRequest.newBuilder(BASE.resolve("headers")).build();
        IO.println(client.send(request, BodyHandlers.ofString()).body());

        // 3 - uma requisição HTTP/1.1, com cabeçalhos adicionados
        request = HttpRequest.newBuilder(BASE.resolve("headers"))
                .version(HttpClient.Version.HTTP_1_1)
                .header("User-Agent", "java-course-client/1.0")
                .header("Accept-Language", "en-US")
                .build();
        IO.println("--- headers of an HTTP/1.1 request with User-Agent and Accept-Language");
        IO.println(client.send(request, BodyHandlers.ofString()).body());

        // 4 - um documento HTML, como array de bytes
        request = HttpRequest.newBuilder(BASE.resolve("/")).build();
        byte[] bytes = client.send(request, BodyHandlers.ofByteArray()).body();
        IO.println("--- the home page is " + bytes.length + " bytes long");

        // 5 - um documento que não existe: nenhuma exceção, cabe ao programa testar o código de status
        request = HttpRequest.newBuilder(BASE.resolve("unknown")).build();
        response = client.send(request, BodyHandlers.ofString());
        IO.println("--- status code: " + response.statusCode() + ", document: [" + response.body() + "]");
    }
}

Resultados (o servidor [Internet10] foi iniciado em outra janela):

> java Internet11.java
Document received: Hello Serge!
--- headers sent by default
Connection: Upgrade, HTTP2-Settings
Host: localhost:27210
Http2-settings: AAEAAEAAAAIAAAAAAAMAAAAAAAQBAAAAAAUAAEAAAAYABgAA
Upgrade: h2c
User-agent: Java-http-client/25.0.4.1
--- headers of an HTTP/1.1 request with User-Agent and Accept-Language
Accept-language: en-US
Host: localhost:27210
User-agent: java-course-client/1.0
--- the home page is 163 bytes long
--- status code: 404, document: []

Comentários:

  • Linha 10: o [HttpClient] não tem um endereço base para as referências de URL relativas: usamos o método [resolve] da classe [URI], como vimos no cliente web da Parte 1, que resolve uma URL relativa ([hello?name=Serge]) a partir da URI base para obter [http://localhost:27210/hello?name=Serge]. A barra final no endereço base é importante: sem ela, o último segmento do caminho seria substituído pela URL relativa;
  • linha 14: criação do cliente. Desde o Java 21, [HttpClient] implementa [AutoCloseable]: seu método [close] espera a conclusão das requisições em andamento e então libera seus recursos (conexões, threads);
  • Linhas 16–18: três instruções bastam para obter o documento: construir a requisição, enviá-la e ler o documento da resposta ([body]). [HttpClient] construiu a requisição HTTP, estabeleceu uma conexão, analisou a resposta e decodificou o documento;
  • Linhas 22–23: as linhas 4–8 dos resultados mostram o que o [HttpClient] envia por padrão: o cabeçalho obrigatório [Host] e um cabeçalho [User-Agent] que especifica a versão do Java. Os cabeçalhos [Connection: Upgrade, HTTP2-Settings], [Upgrade: h2c], e [HTTP2-Settings] são mais surpreendentes: por padrão, o [HttpClient] prefere o HTTP/2 e sugere que o servidor passe para o HTTP/2 na conexão não criptografada ([h2c]). Nosso servidor, que só reconhece o HTTP/1.1, ignorou a proposta e respondeu com HTTP/1.1. Com uma URL [https], a versão do HTTP é negociada durante o estabelecimento da conexão TLS. Observa-se também que o servidor do JDK exibe os nomes dos cabeçalhos recebidos com uma única letra maiúscula ([User-agent]);
  • Linhas 26–30: uma requisição construída com mais precisão: a versão do HTTP (1.1, o que elimina os cabeçalhos da transição para o HTTP/2) e dois cabeçalhos específicos dessa requisição. [HttpClient] não tem cabeçalhos comuns a todas as requisições: quando necessário, escreve-se um método para construir as requisições. As linhas 10–12 dos resultados mostram que os cabeçalhos foram de fato recebidos pelo servidor;
  • linhas 35–36: o documento é obtido como bytes. Observe a URL [/]: uma URL relativa que começa com uma barra se refere à raiz do site a partir do endereço base;
  • linhas 40–42: um documento inexistente. Nenhuma exceção é lançada: a resposta tem o código de status 404 ([statusCode]) e um documento vazio. Cabe ao programa verificar o código de status.

12.7.2.3. Requisição e resposta: HttpRequest e HttpResponse

Vamos examinar mais de perto a configuração do cliente e da requisição, bem como o conteúdo da resposta:

Membro
Função
HttpClient.newBuilder() .followRedirects(Redirect r) .connectTimeout(Duration d) .version(Version v) .executor(Executor e) .proxy(ProxySelector p) .build()
Configuração do cliente: acompanhamento de redirecionamentos ([Redirect.NEVER] por padrão, [Redirect.NORMAL] para acompanhá-los, exceto de [https] para [http], [Redirect.ALWAYS]), tempo máximo para estabelecer a conexão, versão preferida do HTTP, threads usadas nas operações assíncronas, proxy…
HttpRequest.newBuilder(URI uri) .GET() .POST(BodyPublisher p) .method(String method, BodyPublisher p) .header(String name, String value) .timeout(Duration d) .version(Version v) .build()
a requisição: método e documento enviado (para [POST] e [PUT]), cabeçalhos, tempo máximo de resposta ([HttpTimeoutException] além disso), versão do HTTP
HttpResponse.statusCode(), version()
o código de status e a versão (HTTP) da resposta. Não há método para a mensagem que segue o código (ela não existe mais no HTTP/2)
HttpResponse.headers()
os cabeçalhos da resposta, um objeto [HttpHeaders]: [firstValue(name)] retorna o primeiro valor de um cabeçalho (um [Optional<String>]), [map()] todos os cabeçalhos na forma de um dicionário: chave → lista de valores
HttpResponse.body()
o documento, no formato escolhido pelo [BodyHandler]
HttpResponse.uri(), request(), previousResponse()
a URI da resposta e a requisição correspondente: no caso de um redirecionamento, é a última requisição enviada; [previousResponse] retorna a resposta anterior (o redirecionamento)

Usando essas classes, retomamos o cliente web da Parte 1 ([Internet08.java], [Internet09.java]), que era chamado com uma URL e o método [GET] ou [HEAD]. O programa [Internet12.java] é o seguinte:

import java.net.http.HttpClient;
import java.net.http.HttpConnectTimeoutException;
import java.net.http.HttpHeaders;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.net.http.HttpTimeoutException;

// cliente web baseado em HttpClient: exibe o status, os cabeçalhos e o documento recebido
// chamada: java Internet12.java URL GET|HEAD

final String SYNTAX = "Syntax: java Internet12.java URL GET|HEAD";

void main(String[] args) throws InterruptedException {
    if (args.length != 2) {
        IO.println(SYNTAX);
        return;
    }
    // a URL deve ser uma URL http ou https absoluta
    URI uri = parse(args[0]);
    if (uri == null) {
        IO.println("Incorrect URL [" + args[0] + "]: give a URL of the form "
                + "http://machine[:port]/document");
        return;
    }
    // o método HTTP
    String command = args[1].toUpperCase();
    if (!command.equals("GET") && !command.equals("HEAD")) {
        IO.println(SYNTAX);
        return;
    }

    // no máximo 4 requisições por URL solicitada, ou seja, 3 redirecionamentos seguidos (5 requisições por padrão)
    // esta propriedade é lida quando o HttpClient é usado pela primeira vez
    System.setProperty("jdk.httpclient.redirects.retrylimit", "4");
    // o cliente HTTP: ele segue os redirecionamentos, exceto de https para http; no máximo 5 s para conectar
    try (HttpClient client = HttpClient.newBuilder()
            .followRedirects(HttpClient.Redirect.NORMAL)
            .connectTimeout(Duration.ofSeconds(5))
            .build()) {
        // a requisição: método, URL, cabeçalhos, timeout da resposta
        HttpRequest request = HttpRequest.newBuilder(uri)
                .method(command, HttpRequest.BodyPublishers.noBody())
                .header("User-Agent", "java-course-client/1.0")
                .timeout(Duration.ofSeconds(10))
                .build();
        // ela é enviada e esperamos a resposta
        HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
        // a linha de status: URL da última requisição, versão HTTP, código
        IO.println("The server " + response.uri() + " responded: " + response.version() + " "
                + response.statusCode());
        // os cabeçalhos da resposta
        IO.println("--- headers");
        displayHeaders(response.headers());
        // o documento, se o código de status indicar sucesso (200-299)
        if (response.statusCode() / 100 == 2) {
            IO.println("--- document");
            IO.println(response.body());
        }
    } catch (HttpConnectTimeoutException e) {
        IO.println("The connection could not be established within the allotted time");
    } catch (HttpTimeoutException e) {
        IO.println("The server did not respond within the allotted time");
    } catch (ConnectException e) {
        IO.println("Unable to connect to the server " + uri.getAuthority());
    } catch (IOException e) {
        IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
    }
}

// uma URL http ou https absoluta correta, ou null
URI parse(String url) {
    try {
        URI uri = new URI(url);
        return uri.isAbsolute() && uri.getHost() != null
                && (uri.getScheme().equals("http") || uri.getScheme().equals("https")) ? uri : null;
    } catch (URISyntaxException e) {
        return null;
    }
}

// exibe uma coleção de cabeçalhos: um nome pode ter vários valores
void displayHeaders(HttpHeaders headers) {
    headers.map().forEach((name, values) -> IO.println(name + ": " + String.join(", ", values)));
}

Comentários:

  • Linha 20: como em [Internet08.java], o programa verifica se a URL é válida (linhas 72–80). O esquema [https] é aceito desta vez: [HttpClient] é capaz de realizar a negociação TLS;
  • linha 35: o número de redirecionamentos seguidos não é uma propriedade do cliente, mas uma propriedade de sistema do Java, [jdk.httpclient.redirects.retrylimit], que limita o número total de requisições enviadas para uma URL solicitada (5 por padrão). Esse valor é lido de uma vez por todas quando o [HttpClient] é usado pela primeira vez: aqui ele é definido programaticamente antes de criar o cliente, mas também poderia ser especificado na linha de comando ([java -Djdk.httpclient.redirects.retrylimit=4 ...]);
  • linhas 37–40: o cliente segue redirecionamentos (mas não aqueles que passariam de [https] para [http], o que resultaria na perda da criptografia) e espera até 5 segundos para que uma conexão seja estabelecida;
  • linhas 42–46: a requisição, com o método solicitado (nenhum documento a enviar: [noBody()]), um cabeçalho [User-Agent] e um tempo máximo de resposta de 10 segundos;
  • linha 48: a requisição é enviada; a resposta fica disponível quando seus cabeçalhos e seu corpo foram recebidos;
  • Linhas 50–51: a linha de status. [response.uri()] é a URL da última requisição: no caso de um redirecionamento, ela difere da URL solicitada. [version()] retorna uma constante da enumeração [HttpClient.Version];
  • linha 54: os cabeçalhos da resposta, exibidos pelo método [displayHeaders] (linhas 83–85). Um nome de cabeçalho pode ter vários valores: [map()] associa cada nome à sua lista de valores;
  • linhas 56–59: o documento só é exibido se o código de status indicar sucesso (família 2xx);
  • linhas 60–68: erros. [HttpConnectTimeoutException] (conexão não estabelecida dentro do limite de tempo) é um tipo de [HttpTimeoutException] (resposta não recebida dentro do limite de tempo), que por sua vez é um tipo de [IOException]: o [catch] que pertence à classe mais específica deve vir primeiro. Uma recusa de conexão resulta em uma [ConnectException].

Vamos solicitar a raiz do site:

> java Internet12.java http://localhost:27210/ GET
The server http://localhost:27210/ responded: HTTP_1_1 200
--- headers
content-length: 163
content-type: text/html; charset=utf-8
date: Sat, 03 Oct 2026 17:42:17 GMT
--- document
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Test server</title></head>
<body><h1>Welcome to the HttpClient test server</h1></body>
</html>

Encontramos as informações que obtivemos ao analisar nós mesmos a resposta com o cliente TCP: a linha de status, os cabeçalhos de resposta [Content-Length], [Content-Type] e [Date], seguidos do documento. [HttpClient] lista os nomes dos cabeçalhos em minúsculas: esse é o formato exigido pelo HTTP/2, e [HttpHeaders] faz buscas sem diferenciar maiúsculas de minúsculas de qualquer forma.

Uma URL sujeita a um redirecionamento:

1
2
3
4
5
6
7
8
> java Internet12.java http://localhost:27210/old GET
The server http://localhost:27210/hello?name=visitor responded: HTTP_1_1 200
--- headers
content-length: 14
content-type: text/plain; charset=utf-8
date: Sat, 03 Oct 2026 17:42:18 GMT
--- document
Hello visitor!

O redirecionamento foi seguido automaticamente: a resposta recebida é a da URL [/hello?name=visitor] (linha 2). Vamos comparar com a primeira parte: o cliente [Internet09.java] tinha de ler a linha de status, extrair o código, procurar o cabeçalho [Location], calcular a nova URL e repetir o processo em um laço limitado a três redirecionamentos. Aqui, tudo isso é tratado pelo [HttpClient]. Para tratar os redirecionamentos você mesmo, basta não chamar [followRedirects]: a resposta 302 é então retornada como está.

Um documento inexistente:

1
2
3
4
5
> java Internet12.java http://localhost:27210/unknown GET
The server http://localhost:27210/unknown responded: HTTP_1_1 404
--- headers
content-length: 0
date: Sat, 03 Oct 2026 17:42:18 GMT

O código 404 é incluído na resposta, junto com seus cabeçalhos; o documento não é exibido. Nenhuma exceção foi lançada: cabe ao programa decidir o que fazer com uma resposta de erro.

A URL [/loop], que redireciona para si mesma:

1
2
3
4
5
> java Internet12.java http://localhost:27210/loop HEAD
The server http://localhost:27210/loop responded: HTTP_1_1 302
--- headers
date: Sat, 03 Oct 2026 17:42:19 GMT
location: /loop

Depois de quatro requisições, isto é, três redirecionamentos, o [HttpClient] desiste e retorna a última resposta recebida, uma resposta 302.

Um erro do servidor:

1
2
3
4
> java Internet12.java http://localhost:27210/error HEAD
The server http://localhost:27210/error responded: HTTP_1_1 500
--- headers
date: Sat, 03 Oct 2026 17:42:19 GMT

Uma porta em que nenhum servidor está escutando:

> java Internet12.java http://localhost:27299/ GET
Unable to connect to the server localhost:27299

A conexão foi recusada ([ConnectException]). Por fim, uma URL [https] dirigida ao nosso servidor, que só fala HTTP em texto simples:

> java Internet12.java https://localhost:27210/ GET
The connection could not be established within the allotted time

O cliente enviou a primeira mensagem da negociação TLS; nosso servidor, que esperava uma linha de requisição (HTTP), não a entendeu e não respondeu. Após 5 segundos, como a conexão segura não havia sido estabelecida, o tempo limite de conexão expirou. Em uma máquina conectada à Internet, uma requisição como a URL [https://dev.java/] normalmente seria atendida em HTTP/2, se o servidor permitir.

Uma última observação sobre proxies: são as máquinas pelas quais as estações de trabalho de uma rede corporativa muitas vezes precisam passar para acessar a Web. Por padrão, o [HttpClient] usa o proxy especificado pelas propriedades de sistema da máquina virtual [http.proxyHost], [http.proxyPort], [https.proxyHost], e [https.proxyPort] (e nenhum se elas não estiverem definidas). Você pode especificar outro por meio do método [proxy] do construtor do cliente: [HttpClient.newBuilder().proxy(ProxySelector.of(new InetSocketAddress("proxy.example.org", 3128)))].

12.7.2.4. Enviando dados ao servidor: GET e POST

Um cliente pode enviar informações ao servidor de duas maneiras:

  • com o método [GET], as informações fazem parte da URL: [/document?param1=value1&param2=value2];
  • com o método [POST], elas formam o documento anexado à requisição, depois da linha em branco que encerra os cabeçalhos. O cabeçalho [Content-Type] especifica seu formato. Para um formulário HTML, o documento tem o mesmo formato da seção de parâmetros de uma URL: [param1=value1&param2=value2], com o tipo [application/x-www-form-urlencoded].

Nos dois casos, os valores devem ser codificados: certos caracteres (o espaço, [&], [=], [?], letras acentuadas etc.) não podem aparecer como estão em uma URL ou em um formulário. Para isso, usamos o método estático [URLEncoder.encode(value, charset)], que gera o formato de formulário; [URLDecoder.decode], usado por nossos servidores de teste, realiza a operação inversa.

O documento a ser enviado é fornecido à requisição por meio de um [BodyPublisher]; a classe [BodyPublishers] fornece os mais comuns:

Método
Documento enviado
BodyPublishers.ofString(String text[, Charset charset])
texto, codificado em UTF-8 por padrão. O tipo do documento é especificado por um cabeçalho [Content-Type] adicionado à requisição: [text/plain], [application/json], [application/x-www-form-urlencoded]…
BodyPublishers.ofByteArray(byte[] bytes), ofFile(Path path), ofInputStream(...)
bytes quaisquer, um arquivo, um fluxo
BodyPublishers.noBody()
nenhum documento

Não existe no JDK uma classe que construa um formulário: você mesmo constrói a cadeia [name=value&...]. O programa [Internet13.java] é o seguinte:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

import static java.nio.charset.StandardCharsets.UTF_8;

// envio de dados ao servidor: parâmetros de URL (GET), formulário e texto (POST)
// o servidor de teste [Internet10] deve estar iniciado na porta 27210

final URI BASE = URI.create("http://localhost:27210/");

void main() throws IOException, InterruptedException {
    try (HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {
        // 1 - GET: os parâmetros fazem parte da URL; eles devem ser codificados nela
        String name = "Jean & Marie";
        String url = "hello?name=" + URLEncoder.encode(name, UTF_8);
        IO.println("--- GET " + url);
        HttpRequest request = HttpRequest.newBuilder(BASE.resolve(url)).build();
        IO.println(client.send(request, BodyHandlers.ofString()).body());

        // 2 - POST de um formulário: os parâmetros formam o documento enviado ao servidor
        List<Map.Entry<String, String>> fields = List.of(
                Map.entry("name", "Jean & Marie"),
                Map.entry("age", "42"),
                Map.entry("city", "Angers"));
        // o documento: name=value&name=value..., nomes e valores codificados
        String form = fields.stream()
                .map(field -> URLEncoder.encode(field.getKey(), UTF_8) + "="
                        + URLEncoder.encode(field.getValue(), UTF_8))
                .collect(Collectors.joining("&"));
        IO.println("--- POST form, document sent: " + form);
        request = HttpRequest.newBuilder(BASE.resolve("form"))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(BodyPublishers.ofString(form))
                .build();
        HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
        IO.println(response.statusCode() + " : " + response.body());

        // 3 - POST de um texto qualquer, com seu tipo e sua codificação
        IO.println("--- POST text");
        request = HttpRequest.newBuilder(BASE.resolve("text"))
                .header("Content-Type", "text/plain; charset=utf-8")
                .POST(BodyPublishers.ofString("naïve café", UTF_8))
                .build();
        response = client.send(request, BodyHandlers.ofString());
        IO.println(response.statusCode() + " : " + response.body());
    }
}

Resultados:

1
2
3
4
5
6
7
8
9
> java Internet13.java
--- GET hello?name=Jean+%26+Marie
Hello Jean & Marie!
--- POST form, document sent: name=Jean+%26+Marie&age=42&city=Angers
200 : Content-Type received: application/x-www-form-urlencoded
Fields received: name=[Jean & Marie], age=[42], city=[Angers]
--- POST text
200 : Content-Type received: text/plain; charset=utf-8
Text received in upper case: NAÏVE CAFÉ

Comentários:

  • Linhas 17–18: o valor [Jean & Marie] é colocado dentro da URL. Sem codificação, o caractere [&] seria interpretado como o separador entre dois parâmetros, e o servidor receberia o parâmetro [name] com o valor [Jean]. Na linha 2 dos resultados, vemos que o espaço virou [+] e o caractere [&] virou [%26]: é o código hexadecimal do caractere, precedido de [%]. [URLEncoder] gera o formato de formulário, no qual o espaço é codificado como [+]; no caminho de uma URL, [%20] seria necessário, mas na seção de parâmetros os servidores aceitam ambos;
  • linhas 24–27: os campos do formulário, na forma de uma lista de pares (nome, valor) criados por [Map.entry]. Uma lista preserva a ordem dos campos, o que um dicionário [Map.of] não faria;
  • Linhas 29–32: o documento é construído pela API de streams: cada par vira [name=value], com nomes e valores codificados, e os pares são unidos por [&]. A linha 4 dos resultados mostra o formato [name=value&name=value];
  • linhas 34–37: o formulário é enviado pelo método [POST] para a URL [/form], junto com seu tipo. O servidor indica (linhas 5–6 dos resultados) que recebeu um documento do tipo [application/x-www-form-urlencoded] e que extraiu e decodificou dele os três campos;
  • linhas 43–46: texto codificado em UTF-8, do tipo [text/plain]. O servidor o devolve em maiúsculas (linha 9 dos resultados): os caracteres acentuados foram transmitidos e recebidos corretamente.

Vamos recapitular a diferença entre [GET] e [POST]: um navegador exibe em sua barra de endereço os parâmetros de uma requisição [GET], e não os de uma requisição [POST]; além disso, uma requisição [GET] só deve ser usada para obter informações, enquanto uma requisição [POST] é usada para enviar informações ou modificar o estado do servidor.

12.7.2.5. Troca de objetos em formato JSON

Hoje, as aplicações trocam a maior parte de seus dados no formato JSON, descrito no Capítulo 5. O JDK não tem uma biblioteca JSON: [HttpClient] transporta documentos JSON como cadeias de caracteres, e o Jackson é usado na conversão entre objetos e JSON:

  • No lado do envio, [mapper.writeValueAsString(object)] gera o documento JSON, que [BodyPublishers.ofString] envia com o cabeçalho [Content-Type: application/json];
  • No lado da recepção, [mapper.readValue(json, Type.class)] converte o documento JSON recebido em um objeto. Para um tipo genérico como [List<Person>], usa-se um [TypeReference], que preserva o parâmetro de tipo que o Java remove durante a compilação.

O programa [Internet14] é um projeto Maven, no qual o [pom.xml] difere do do servidor [Internet10] apenas no nome do projeto ([internet14]) e na classe principal ([internet.Internet14]). Ele contém o mesmo record, [Person], que o servidor. A classe [Internet14] é a seguinte:

package internet;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.List;
import tools.jackson.core.type.TypeReference;
import tools.jackson.databind.json.JsonMapper;

// troca de objetos em formato JSON com um servidor web
// o servidor de teste [Internet10] deve estar iniciado na porta 27210
public class Internet14 {

    private static final URI BASE = URI.create("http://localhost:27210/");
    // o conversor Jackson objetos <-> JSON
    private static final JsonMapper MAPPER = JsonMapper.builder().build();

    public static void main(String[] args) throws IOException, InterruptedException {
        try (HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {
            // 1 - a lista de pessoas: o documento JSON é transformado em uma lista de objetos
            List<Person> persons = readJson(client, "api/persons", new TypeReference<List<Person>>() {
            });
            IO.println("--- list of persons");
            persons.forEach(IO::println);

            // 2 - uma pessoa
            Person durand = readJson(client, "api/persons/2", new TypeReference<Person>() {
            });
            IO.println("--- person no. 2: " + durand);

            // 3 - adição de uma pessoa: o objeto é enviado em formato JSON
            var martin = new Person(0, "Martin", 25);
            HttpRequest request = HttpRequest.newBuilder(BASE.resolve("api/persons"))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(MAPPER.writeValueAsString(martin)))
                    .build();
            HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
            IO.println("--- addition of " + martin);
            IO.println("Status: " + response.statusCode() + ", Location: "
                    + response.headers().firstValue("Location").orElse("?"));
            // o documento JSON recebido, bruto e depois como objeto
            IO.println("JSON received: " + response.body());
            Person created = MAPPER.readValue(response.body(), Person.class);
            IO.println("Person created: " + created);

            // 4 - uma pessoa que não existe
            try {
                readJson(client, "api/persons/99", new TypeReference<Person>() {
                });
            } catch (IOException e) {
                IO.println("--- person no. 99: " + e.getClass().getSimpleName() + " : " + e.getMessage());
            }
        }
    }

    // GET [path] e transformação do documento JSON recebido em um objeto do tipo T
    // lança uma IOException se o código de status não indicar sucesso
    private static <T> T readJson(HttpClient client, String path, TypeReference<T> type)
            throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(BASE.resolve(path))
                .header("Accept", "application/json")
                .build();
        HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
        if (response.statusCode() / 100 != 2) {
            throw new IOException("GET " + response.uri() + " : status code " + response.statusCode());
        }
        return MAPPER.readValue(response.body(), type);
    }
}

Resultados (a partir da pasta [Internet14]):

> mvn compile exec:java
--- list of persons
Person[id=1, name=Dupont, age=42]
Person[id=2, name=Durand, age=35]
--- person no. 2: Person[id=2, name=Durand, age=35]
--- addition of Person[id=0, name=Martin, age=25]
Status: 201, Location: /api/persons/3
JSON received: {"id":3,"name":"Martin","age":25}
Person created: Person[id=3, name=Martin, age=25]
--- person no. 99: IOException : GET http://localhost:27210/api/persons/99 : status code 404

Comentários:

  • linha 19: o [JsonMapper] do Jackson é criado uma vez por todas; ele pode ser usado por várias threads ao mesmo tempo;
  • Linhas 61–71: o método genérico [readJson] realiza o equivalente a um método que “solicita uma URL e converte o documento JSON recebido em um objeto”: ele envia a requisição [GET] com o cabeçalho [Accept: application/json], verifica o código de status (linha 67) e converte o documento em um objeto do tipo solicitado (linha 70);
  • Linhas 24–25: a lista de pessoas. O documento JSON [[{"id":1,"name":"Dupont","age":42},...]] enviado pelo servidor é convertido diretamente em uma lista de objetos [Person]. A expressão [new TypeReference<List<Person>>() {}] cria uma instância de uma classe anônima derivada de [TypeReference]: esse é o truque que permite ao Jackson determinar, em tempo de execução, o tipo [List<Person>];
  • linha 27: cada pessoa é exibida usando o método [toString] gerado para o record;
  • linhas 30–31: uma única pessoa;
  • linhas 35–40: o objeto [martin] é convertido em JSON e enviado ao servidor por [POST]. O servidor responde com o código de status 201 (Created) e o cabeçalho [Location], que fornece a URL do novo recurso (linha 7 dos resultados);
  • linhas 45–46: o documento JSON recebido, primeiro em forma bruta e depois convertido em um objeto. Os nomes das propriedades são os dos componentes do record ([id], [name], [age]), formatados em “camelCase” segundo as convenções da web;
  • Linhas 50–55: uma pessoa inexistente: [readJson] lança uma [IOException] para uma resposta 404.

Voltaremos a essas técnicas no próximo capítulo, em que o servidor de cálculo de impostos se tornará um serviço web JSON.

12.7.2.6. Timeout, cancelamento e reutilização do cliente

O programa [Internet15.java] ilustra quatro pontos importantes para o uso de [HttpClient] em uma aplicação real: reutilização do cliente, timeouts, cancelamento de requisições e requisições assíncronas. O método [sendAsync] de [HttpClient] é a versão assíncrona de [send]: ele envia a requisição e retorna imediatamente um [CompletableFuture<HttpResponse<T>>] (Capítulo 9), que será completado quando a resposta chegar. O programa é o seguinte:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.net.http.HttpTimeoutException;

// timeout, cancelamento e reutilização de um HttpClient; requisições assíncronas (sendAsync)
// o servidor de teste [Internet10] deve estar iniciado na porta 27210

final URI BASE = URI.create("http://localhost:27210/");

void main() throws IOException, InterruptedException {
    // 1 - uma única instância de HttpClient para toda a aplicação
    try (HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {

        // 2 - requisições sucessivas: a mesma conexão TCP é reutilizada
        IO.println("--- three successive requests");
        for (int i = 1; i <= 3; i++) {
            IO.println(client.send(request("hello?name=trial" + i), BodyHandlers.ofString()).body());
        }

        // 3 - uma resposta obtida dentro do timeout de 2 s e depois uma resposta lenta demais
        for (int seconds : List.of(1, 3)) {
            IO.println("--- response expected in " + seconds + " s");
            try {
                IO.println(client.send(request("slow?seconds=" + seconds), BodyHandlers.ofString()).body());
            } catch (HttpTimeoutException e) {
                IO.println(e.getClass().getSimpleName() + " : " + e.getMessage());
            }
        }

        // 4 - uma requisição assíncrona cancelada pelo programa após meio segundo
        IO.println("--- cancellation after 0.5 s");
        CompletableFuture<HttpResponse<String>> future =
                client.sendAsync(request("slow?seconds=1"), BodyHandlers.ofString());
        CompletableFuture.delayedExecutor(500, TimeUnit.MILLISECONDS).execute(() -> future.cancel(true));
        try {
            IO.println(future.join().body());
        } catch (CancellationException e) {
            IO.println("Request cancelled (" + e.getClass().getSimpleName() + ")");
        }

        // 5 - quatro requisições assíncronas simultâneas com o mesmo cliente
        IO.println("--- four simultaneous requests of one second each");
        long start = System.nanoTime();
        List<CompletableFuture<String>> responses = IntStream.rangeClosed(1, 4)
                .mapToObj(_ -> client.sendAsync(request("slow?seconds=1"), BodyHandlers.ofString())
                        .thenApply(HttpResponse::body))
                .toList();
        // esperamos o fim das quatro requisições
        CompletableFuture.allOf(responses.toArray(CompletableFuture[]::new)).join();
        responses.forEach(response -> IO.println(response.join()));
        IO.println("Total duration: %.1f s".formatted((System.nanoTime() - start) / 1e9));
    }
}

// uma requisição GET a uma URL relativa a BASE: no máximo 2 segundos para obter a resposta
HttpRequest request(String url) {
    return HttpRequest.newBuilder(BASE.resolve(url)).timeout(Duration.ofSeconds(2)).build();
}

Resultados:

> java Internet15.java
--- three successive requests
Hello trial1!
Hello trial2!
Hello trial3!
--- response expected in 1 s
Response obtained after 1 s
--- response expected in 3 s
HttpTimeoutException : request timed out
--- cancellation after 0.5 s
Request cancelled (CancellationException)
--- four simultaneous requests of one second each
Response obtained after 1 s
Response obtained after 1 s
Response obtained after 1 s
Response obtained after 1 s
Total duration: 1.0 s

Comentários:

  • Linha 14: uma única instância de [HttpClient] é usada por todo o programa. Essa é a regra: um objeto [HttpClient] gerencia um pool de conexões e as reutiliza de uma requisição para a seguinte; ele foi projetado para ter vida longa e pode ser usado por várias threads simultaneamente. Criar um [HttpClient] para cada requisição é um erro comum: cada instância abre suas próprias conexões, que o sistema mantém em reserva por algum tempo depois de fechadas (estado TIME_WAIT do TCP); um programa que faz muitas requisições acabará esgotando as portas disponíveis. Criamos um cliente em cada um dos programas anteriores porque eles faziam apenas algumas requisições antes de terminar;
  • linhas 58–60: cada requisição deve receber uma resposta em no máximo 2 segundos;
  • linhas 18–20: três requisições consecutivas. Veremos no log do servidor que elas usaram a mesma conexão TCP;
  • linhas 23–30: uma resposta que chega em 1 segundo, seguida de uma resposta que levaria 3 segundos; após 2 segundos, a requisição é abandonada e uma [HttpTimeoutException] é lançada (linha 9 dos resultados);
  • linhas 34–41: um cancelamento iniciado pelo programa. A requisição é lançada de forma assíncrona por [sendAsync], que retorna imediatamente um [CompletableFuture]. Um executor diferido ([CompletableFuture.delayedExecutor]) é instruído a chamar seu método [cancel] após meio segundo; em uma aplicação interativa, esse seria o efeito de um botão [Cancel]. A partir do Java 16, cancelar um [CompletableFuture] retornado por [sendAsync] realmente encerra a troca com o servidor. [join] espera o resultado; para uma requisição cancelada, ele lança uma [CancellationException];
  • linhas 46–49: quatro requisições lançadas simultaneamente no mesmo cliente: cada [sendAsync] retorna imediatamente seu [CompletableFuture], que é transformado por [thenApply] em [CompletableFuture<String>], que fornecerá o documento. O padrão anônimo [_] (Java 22) substitui o parâmetro da lambda, que não é necessário;
  • linha 51: [CompletableFuture.allOf] (Capítulo 9) retorna um [CompletableFuture] concluído quando os quatro estão completos; é isso que [join] espera. Cada requisição leva um segundo para ser processada no servidor; toda a operação levou um segundo (linha 17 dos resultados): as requisições foram processadas em paralelo, tanto pelo cliente quanto pelo servidor.

Com threads virtuais, o mesmo nível de paralelismo também pode ser obtido sem [sendAsync]: basta executar quatro chamadas ao método síncrono [send] em quatro threads virtuais. As duas abordagens são válidas; [sendAsync] é conveniente quando as respostas precisam ser encadeadas a outros processamentos assíncronos.

O log do servidor [Internet10] mostra todas as requisições recebidas desde o início desta seção:

> mvn compile exec:java
Web server started on http://localhost:27210
GET /hello?name=Serge HTTP/1.1 (client port 47338) -> 200
GET /headers HTTP/1.1 (client port 47338) -> 200
GET /headers HTTP/1.1 (client port 47338) -> 200
GET / HTTP/1.1 (client port 47338) -> 200
GET /unknown HTTP/1.1 (client port 47338) -> 404
GET / HTTP/1.1 (client port 47352) -> 200
GET /old HTTP/1.1 (client port 41552) -> 302
GET /hello?name=visitor HTTP/1.1 (client port 41552) -> 200
GET /unknown HTTP/1.1 (client port 41560) -> 404
HEAD /loop HTTP/1.1 (client port 41576) -> 302
HEAD /loop HTTP/1.1 (client port 41592) -> 302
HEAD /loop HTTP/1.1 (client port 41596) -> 302
HEAD /loop HTTP/1.1 (client port 41610) -> 302
HEAD /error HTTP/1.1 (client port 41622) -> 500
GET /hello?name=Jean+%26+Marie HTTP/1.1 (client port 41634) -> 200
POST /form HTTP/1.1 (client port 41634) -> 200
POST /text HTTP/1.1 (client port 41634) -> 200
GET /api/persons HTTP/1.1 (client port 41638) -> 200
GET /api/persons/2 HTTP/1.1 (client port 41638) -> 200
POST /api/persons HTTP/1.1 (client port 41638) -> 201
GET /api/persons/99 HTTP/1.1 (client port 41638) -> 404
GET /hello?name=trial1 HTTP/1.1 (client port 41654) -> 200
GET /hello?name=trial2 HTTP/1.1 (client port 41654) -> 200
GET /hello?name=trial3 HTTP/1.1 (client port 41654) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 41654) -> 200
GET /slow?seconds=3 HTTP/1.1 (client port 41654) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 40736) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 40744) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 40758) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 40748) -> 200
GET /slow?seconds=1 HTTP/1.1 (client port 40760) -> 200
  • linhas 3–7: as cinco requisições de [Internet11.java] chegaram pela mesma conexão (mesma porta de cliente): o cliente a manteve aberta entre as requisições;
  • linhas 9–10: a requisição redirecionada de [Internet12.java] e a requisição ao novo endereço, feita automaticamente pela mesma conexão;
  • linhas 12–15: a requisição inicial a [/loop] e os três redirecionamentos que se seguiram antes de a conexão ser abandonada;
  • linhas 17–19: as requisições de [Internet13.java], na mesma conexão;
  • linhas 20–23: requisições a [Internet14];
  • linhas 24–28: as requisições sucessivas de [Internet15.java] usaram todas a mesma conexão. A requisição que demorou demais (linha 28) foi abandonada pelo cliente após 2 segundos: [HttpClient] então fechou a conexão. O servidor não detectou isso: após 3 segundos, ele escreveu sua resposta em uma conexão que o cliente já havia fechado, e o sistema não reporta erro para uma operação de escrita desse tipo. É por isso que o log mostra o código de status 200;
  • Linha 29: a requisição cancelada pelo programa deve ter aberto uma nova conexão, já que a anterior havia sido fechada. Mais uma vez, o servidor respondeu sem saber que a resposta não seria lida;
  • as quatro últimas linhas: as quatro requisições simultâneas usaram quatro conexões diferentes, abertas especialmente para isso. No HTTP/1.1, uma conexão transporta apenas uma requisição por vez; o HTTP/2 permitiria enviar todas elas por uma única conexão.

Um programa que permanece em execução por muito tempo (um servidor, um serviço do sistema) deve levar em conta um último ponto: um [HttpClient] mantém suas conexões inativas por um certo período (30 segundos por padrão, ajustável pela propriedade de sistema [jdk.httpclient.keepalive.timeout]) antes de fechá-las. Em aplicações Spring, também é possível usar o cliente HTTP do framework, [RestClient] (construído sobre [HttpClient] ou outra biblioteca), que acrescenta a conversão automática de objetos em JSON; os clientes do próximo capítulo, por sua vez, usarão simplesmente [HttpClient] e Jackson, como em [Internet14].

12.7.3. Aplicação: um cliente proxy para um serviço web de tradução

Vamos agora demonstrar como o [HttpClient] permite usar recursos da web, mesmo quando esses recursos não foram pensados para serem usados por um programa.

12.7.3.1. A aplicação

Nos anos 2000, havia na Web sites gratuitos de tradução. O usuário digitava um texto, escolhia o sentido da tradução (“francês para inglês” etc.) em uma lista suspensa, clicava em um botão e recebia uma página HTML contendo a tradução. É possível escrever uma classe [TranslationService] que faz o mesmo por meio de programação: ela monta a URL da requisição, consulta o site e extrai a tradução da página HTML recebida com uma expressão regular. Uma interface gráfica ou outro programa pode então se apoiar nessa classe; fala-se aqui de um cliente “proxy”: a classe [TranslationService] faz as vezes do site e o oculta de seu usuário.

Como nossa máquina de teste não tem acesso à Internet, substituímos o site por um pequeno site local que imita os da época: ele tem o mesmo formulário (uma caixa de texto, uma lista suspensa antiquada com os sentidos de tradução) e exibe a tradução no mesmo lugar de sua página. Suas “traduções” são feitas palavra por palavra com pequenos dicionários: o que nos interessa é a técnica do cliente, não a qualidade da tradução. O cliente é usado por um programa de teste de console. A arquitetura é a seguinte:

Image

12.7.3.2. O site de tradução

O programa [Internet16.java] é o seguinte:

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;

import static java.nio.charset.StandardCharsets.UTF_8;

// um pequeno site de "tradução" palavra por palavra, que imita um site de tradução dos anos 2000
// chamada: java Internet16.java [port]   (porta 27220 por padrão); parar com Ctrl-C

// um sentido de tradução: seu rótulo e seu dicionário
record Translator(String label, Map<String, String> words) {
}

// os sentidos de tradução: código -> tradutor (LinkedHashMap: a ordem de inserção é mantida)
final Map<String, Translator> translationDirections = new LinkedHashMap<>();
// uma palavra, possivelmente seguida de um apóstrofo
final Pattern WORD = Pattern.compile("\\p{L}+'?");

void main(String[] args) throws IOException {
    int port = args.length == 1 ? Integer.parseInt(args[0]) : 27220;
    translationDirections.put("fe", new Translator("French to English", Map.of(
            "ce", "this", "chien", "dog", "est", "is", "perdu", "lost", "malade", "sick",
            "l'", "the ", "été", "summer", "sera", "will be", "chaud", "hot")));
    translationDirections.put("ef", new Translator("English to French", Map.of(
            "my", "mon", "tailor", "tailleur", "is", "est", "rich", "riche",
            "this", "ce", "dog", "chien", "lost", "perdu")));
    translationDirections.put("fs", new Translator("French to Spanish", Map.of(
            "ce", "este", "chien", "perro", "est", "está", "perdu", "perdido",
            "l'", "el ", "été", "verano", "sera", "será", "chaud", "caliente")));

    HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), port), 0);
    server.createContext("/translation", this::translate);
    server.start();
    IO.println("Translation service started on http://localhost:" + port + "/translation");
}

// a página de tradução: o formulário, seguido da tradução se um texto foi fornecido
void translate(HttpExchange exchange) throws IOException {
    try (exchange) {
        Map<String, String> parameters = parameters(exchange.getRequestURI().getRawQuery());
        String direction = parameters.get("direction");
        String text = parameters.getOrDefault("text", "");
        var page = new StringBuilder("""
                <!DOCTYPE html>
                <html lang="en">
                <head><meta charset="utf-8"><title>Translator of the Java course</title></head>
                <body>
                <h1>Translation of texts</h1>
                <form action="/translation" method="get">
                <textarea name="text" rows="4" cols="60"></textarea>
                <select name="direction">
                """);
        // a lista dos sentidos de tradução, escrita à moda antiga: tags <option> não fechadas
        translationDirections.forEach((code, translator) -> page.append("    <option value='").append(code)
                .append("'>").append(translator.label()).append('\n'));
        page.append("""
                </select>
                <input type="submit" value="Translate">
                </form>
                """);
        // a tradução, se houver um texto a traduzir
        if (!text.isBlank()) {
            Translator translator = direction == null ? null : translationDirections.get(direction);
            if (translator != null) {
                // tradução palavra por palavra; uma palavra desconhecida é deixada como está
                String translation = WORD.matcher(text.strip().toLowerCase())
                        .replaceAll(word -> Matcher.quoteReplacement(
                                translator.words().getOrDefault(word.group(), word.group())));
                page.append("<strong>Translated text: </strong><div class=\"txtTrans\">")
                        .append(encodeHtml(translation)).append("</div>\n");
            } else {
                page.append("<p>Unknown translation direction</p>\n");
            }
        }
        page.append("</body>\n</html>\n");
        byte[] bytes = page.toString().getBytes(UTF_8);
        exchange.getResponseHeaders().set("Content-Type", "text/html; charset=utf-8");
        exchange.sendResponseHeaders(200, bytes.length);
        exchange.getResponseBody().write(bytes);
        // trace das requisições no console
        IO.println("%s %s -> %d".formatted(exchange.getRequestMethod(), exchange.getRequestURI(),
                exchange.getResponseCode()));
    }
}

// codificação HTML: os caracteres especiais e os caracteres não ASCII viram entidades &#nnn;
String encodeHtml(String text) {
    var result = new StringBuilder();
    text.codePoints().forEach(c -> {
        if (c > 127 || c == '<' || c == '>' || c == '&' || c == '"' || c == '\'') {
            result.append("&#").append(c).append(';');
        } else {
            result.appendCodePoint(c);
        }
    });
    return result.toString();
}

// os parâmetros name1=value1&name2=value2 da URL, decodificados
Map<String, String> parameters(String query) {
    Map<String, String> result = new HashMap<>();
    if (query != null) {
        for (String pair : query.split("&")) {
            String[] fields = pair.split("=", 2);
            result.put(fields[0], fields.length == 2 ? URLDecoder.decode(fields[1], UTF_8) : "");
        }
    }
    return result;
}

Comentários:

  • linhas 10–11: um sentido de tradução é um record composto por um rótulo e um dicionário;
  • linhas 20–28: os três sentidos de tradução propostos, com seus códigos ([fe] para francês → inglês, [ef] para inglês → francês, [fs] para francês → espanhol), seus rótulos e seus dicionários. [Map.of] aceita no máximo dez pares (nome, valor); para mais que isso, use [Map.ofEntries];
  • linha 31: a única página do site, [/translation], pode receber dois parâmetros: o sentido da tradução [direction] e o texto [text] (linhas 39–41);
  • linhas 53–54: a lista suspensa. Como era comum nos sites da época, as tags [<option>] não são fechadas: o código HTML dos sites reais nem sempre é muito limpo, e nosso cliente terá de contornar isso;
  • linhas 65–67: a tradução palavra por palavra. A expressão regular [\p{L}+'?] (linha 16) reconhece uma palavra, isto é, uma sequência de letras ([\p{L}]), possivelmente seguida de um apóstrofo ([l'], [d']). Não usamos [\w]: em Java, [\w] por padrão designa apenas letras sem acento, dígitos e o caractere [_], e [été] não seria reconhecido como palavra. O método [replaceAll] de [Matcher] (Java 9) substitui cada palavra pelo resultado de uma função: sua tradução, ou a própria palavra se for desconhecida. [Matcher.quoteReplacement] protege os caracteres [$] e [\], que têm um significado especial em um texto de substituição;
  • linhas 68–69: a tradução é colocada dentro de uma tag [<div class="txtTrans">], como era comum nos sites da época. Ela é codificada pelo método [encodeHtml] (linhas 86–96): os caracteres que têm significado em HTML ([<], [&]…) e os caracteres não ASCII são substituídos por entidades numéricas [&#nnn;]. O JDK não possui um método de codificação HTML: as aplicações web usam o de seu framework;
  • linha 71: um sentido de tradução desconhecido resulta em uma página sem tradução.

Eis a página gerada com [curl] para traduzir [l'été sera chaud] para o espanhol; observe a codificação do texto na URL:

> curl -s "http://localhost:27220/translation?direction=fs&text=l%27%C3%A9t%C3%A9%20sera%20chaud"
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Translator of the Java course</title></head>
<body>
<h1>Translation of texts</h1>
<form action="/translation" method="get">
<textarea name="text" rows="4" cols="60"></textarea>
<select name="direction">
    <option value='fe'>French to English
    <option value='ef'>English to French
    <option value='fs'>French to Spanish
</select>
<input type="submit" value="Translate">
</form>
<strong>Translated text: </strong><div class="txtTrans">el verano ser&#225; caliente</div>
</body>
</html>

Para escrever o cliente, precisamos:

  • saber o que o site espera: uma requisição [GET /translation?direction=code&text=encoded text]. Em um site real, isso pode ser descoberto olhando a URL exibida pelo navegador após uma tradução, ou o atributo [action] do formulário;
  • saber onde, nas páginas recebidas, está a informação de que precisamos: os sentidos de tradução estão nas tags [<option value='code'>label] da lista suspensa (linhas 10–12 da página acima), e a tradução está na tag [<div class="txtTrans">] (linha 16). Isso se descobre exibindo o código-fonte da página no navegador.

Duas expressões regulares (Capítulo 5) permitem extrair essas informações:

  • [<option[^>]*value='(\w+)'>([^<\r\n]+)]: uma tag [<option], seguida de caracteres diferentes de [>], de [value='], do código (primeiro grupo), de [>] e, depois, do rótulo, isto é, os caracteres que vêm a seguir até o próximo [<] ou o fim da linha (segundo grupo);
  • [<div class="txtTrans">(.*?)</div>]: a tradução é o texto (primeiro grupo) entre a tag de abertura e a primeira tag [</div>] que vem depois. O quantificador [*?] é “preguiçoso” (lazy): ele pega o menor número possível de caracteres.

12.7.3.3. O cliente TranslationService

Para ser breve, reunimos a interface [ITranslationService], sua implementação [TranslationService], a exceção [TranslationException] e o programa de teste em um único arquivo-fonte compacto; em uma aplicação real, a interface e sua implementação formariam uma biblioteca separada. O programa [Internet17.java] é o seguinte:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

import static java.nio.charset.StandardCharsets.UTF_8;

// cliente "proxy" de um serviço web de tradução: a classe TranslationService
// esconde do programa o diálogo HTTP e a análise das páginas HTML do site de tradução
// chamada: java Internet17.java [siteUrl]   (por padrão http://localhost:27220/)

// um teste de tradução
record Trial(String text, String direction) {
}

void main(String[] args) {
    URI siteUrl = URI.create(args.length == 1 ? args[0] : "http://localhost:27220/");
    try (HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build()) {
        // criação do serviço de tradução: ele consulta o site para saber quais idiomas são traduzidos
        ITranslationService service = TranslationService.create(client, siteUrl);
        IO.println("Translation directions offered by the site:");
        service.translatedLanguages().forEach((code, label) -> IO.println("  " + code + " : " + label));
        // algumas traduções
        List<Trial> trials = List.of(
                new Trial("ce chien est perdu", "fe"),
                new Trial("l'été sera chaud", "fs"),
                new Trial("my tailor is rich", "ef"),
                new Trial("xx", "ef"),
                new Trial("", "fe"),
                new Trial("hello", "fx"));
        for (Trial trial : trials) {
            try {
                String translation = service.translate(trial.text(), trial.direction());
                IO.println("Translation [%s] of [%s] : [%s]".formatted(
                        service.translatedLanguages().get(trial.direction()), trial.text(), translation));
            } catch (TranslationException e) {
                IO.println("The following error with code " + e.getCode() + " occurred: "
                        + e.getMessage());
            }
        }
    } catch (TranslationException e) {
        IO.println("The following error with code " + e.getCode() + " occurred: " + e.getMessage());
        // a possível causa: toString dá sua classe, seguida de sua mensagem, se houver
        if (e.getCause() != null) {
            IO.println("Cause: " + e.getCause());
        }
    }
}

// --------------------------------------------------------------------
// a interface apresentada ao programa
interface ITranslationService {

    // os sentidos de tradução: código -> rótulo, por exemplo fe -> French to English
    Map<String, String> translatedLanguages();

    // tradução de um texto no sentido dado por seu código
    String translate(String text, String direction);
}

// a exceção específica do serviço de tradução (não verificada), com um código de erro
// static: em um arquivo-fonte compacto, uma classe sem static seria uma classe interna
static class TranslationException extends RuntimeException {

    @Serial
    private static final long serialVersionUID = 1L;

    private final int code;

    TranslationException(String message, int code) {
        this(message, null, code);
    }

    TranslationException(String message, Throwable cause, int code) {
        super(message, cause);
        this.code = code;
    }

    int getCode() {
        return code;
    }
}

// a implementação: um cliente HTTP do site de tradução
static class TranslationService implements ITranslationService {

    // as opções <option value='fe'>French to English do formulário
    private static final Pattern OPTION = Pattern.compile("<option[^>]*value='(\\w+)'>([^<\\r\\n]+)");
    // a tradução: <div class="txtTrans">...</div>
    private static final Pattern TRANSLATION = Pattern.compile("<div class=\"txtTrans\">(.*?)</div>");
    // uma entidade HTML: &#225; ou &ccedil;
    private static final Pattern ENTITY = Pattern.compile("&(#\\d+|\\w+);");
    // as poucas entidades nomeadas que podem ser decodificadas
    private static final Map<String, String> ENTITIES = Map.of(
            "amp", "&", "lt", "<", "gt", ">", "quot", "\"", "apos", "'", "ccedil", "ç", "eacute", "é");

    // o cliente HTTP e o endereço do site, fornecidos pelo programa
    private final HttpClient client;
    private final URI siteUrl;
    private final Map<String, String> translatedLanguages;

    // construtor privado: o método de fábrica create é usado
    private TranslationService(HttpClient client, URI siteUrl, Map<String, String> languages) {
        this.client = client;
        this.siteUrl = siteUrl;
        this.translatedLanguages = languages;
    }

    @Override
    public Map<String, String> translatedLanguages() {
        return translatedLanguages;
    }

    // criação do serviço: os sentidos de tradução são lidos do formulário do site
    static TranslationService create(HttpClient client, URI siteUrl) {
        String page;
        try {
            HttpRequest request = HttpRequest.newBuilder(siteUrl.resolve("translation"))
                    .timeout(Duration.ofSeconds(10)).build();
            page = client.send(request, BodyHandlers.ofString()).body();
        } catch (IOException | InterruptedException e) {
            throw new TranslationException("The translation site is unreachable", e, 11);
        }
        Map<String, String> languages = new LinkedHashMap<>();
        Matcher option = OPTION.matcher(page);
        while (option.find()) {
            // as entidades HTML (&ccedil;...) são decodificadas
            languages.put(option.group(1), decodeHtml(option.group(2).strip()));
        }
        if (languages.isEmpty()) {
            throw new TranslationException("The site gives no translation direction", 13);
        }
        return new TranslationService(client, siteUrl, Collections.unmodifiableMap(languages));
    }

    // tradução
    @Override
    public String translate(String text, String direction) {
        // a tradução solicitada é possível?
        if (!translatedLanguages.containsKey(direction)) {
            throw new TranslationException("The translation direction [" + direction + "] is not recognized", 10);
        }
        // a URL a solicitar: o texto deve ser codificado
        URI url = siteUrl.resolve("translation?direction=" + direction + "&text=" + URLEncoder.encode(text, UTF_8));
        HttpRequest request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(10)).build();
        Optional<String> translation;
        try {
            // o documento é retornado como um stream de linhas, lidas à medida que chegam
            HttpResponse<Stream<String>> response = client.send(request, BodyHandlers.ofLines());
            if (response.statusCode() != 200) {
                throw new TranslationException("The site responded with code " + response.statusCode(), 11);
            }
            // a tradução é procurada linha após linha, e paramos assim que ela é encontrada
            try (Stream<String> lines = response.body()) {
                translation = lines.map(TRANSLATION::matcher)
                        .filter(Matcher::find)
                        .map(result -> decodeHtml(result.group(1).strip()))
                        .findFirst();
            }
        } catch (IOException | UncheckedIOException | InterruptedException e) {
            throw new TranslationException("Error encountered during the translation", e, 11);
        }
        // a página não continha uma tradução
        return translation.orElseThrow(
                () -> new TranslationException("The server did not send back a translation", 12));
    }

    // decodificação das entidades HTML de um texto
    private static String decodeHtml(String text) {
        return ENTITY.matcher(text).replaceAll(entity -> {
            String name = entity.group(1);
            String character = name.startsWith("#")
                    ? Character.toString(Integer.parseInt(name.substring(1)))
                    : ENTITIES.getOrDefault(name, entity.group());
            return Matcher.quoteReplacement(character);
        });
    }
}

Comecemos pela interface e pela exceção:

  • linhas 52–59: a interface exposta ao programa. O método [translatedLanguages] devolve o dicionário dos sentidos de tradução aceitos pelo site, formado por entradas do tipo [fe] → [French to English]; o método [translate] traduz o texto [text] no sentido de código [direction]. Ele é síncrono: um programa que queira executar várias traduções em paralelo as executará em threads virtuais;
  • linhas 63–82: a exceção própria do serviço, não verificada, com um código de erro, nos moldes de [TaxException] (Capítulo 6). Em um arquivo-fonte compacto, todas as declarações são membros da classe implícita: uma classe declarada sem a palavra-chave [static] seria uma classe interna, cujas instâncias só podem ser criadas a partir de uma instância da classe implícita. Já as interfaces e os records são sempre implicitamente estáticos;
  • linhas 65–66: uma exceção é serializável; [-Xlint:all] exige, portanto, um número de versão, anotado com [@Serial] (Java 14).

A classe [TranslationService]:

  • linhas 88–95: as expressões regulares apresentadas acima, compiladas uma única vez, e uma terceira para as entidades HTML, que podem ser numéricas ([&#225;]) ou nomeadas ([&ccedil;]);
  • linha 98: o serviço não cria seu próprio [HttpClient]; ele o recebe do programa, que determina sua configuração e seu tempo de vida;
  • linha 103: o construtor é privado. O serviço só pode ser criado depois de consultar o site; em vez de realizar essa operação de rede em um construtor, usamos um método estático de construção, [create];
  • linhas 115–134: criação do serviço. A lista dos sentidos de tradução é lida diretamente do próprio site, o que garante que esteja atualizada:
    • linhas 118–120: a página do formulário é solicitada sem nenhum parâmetro;
    • linhas 121–123: um erro de comunicação é encapsulado em uma [TranslationException] com código 11;
    • linhas 125–129: cada tag [<option>] encontrada pela expressão regular fornece um código (grupo 1) e um rótulo (grupo 2). O método [decodeHtml] (linhas 169–177) substitui as entidades HTML pelos caracteres que elas representam: os rótulos do site não contêm nenhuma, mas [Fran&ccedil;ais] se tornaria [Français];
    • linha 133: o dicionário se torna não modificável por [Collections.unmodifiableMap], que preserva a ordem do [LinkedHashMap];
  • linhas 138–166: a tradução:
    • linhas 140–142: verifica-se se o sentido de tradução solicitado existe;
    • linha 144: a requisição é feita à URL, já que o texto está codificado;
    • linha 149: o handler [BodyHandlers.ofLines()] devolve a resposta assim que seus cabeçalhos chegam; seu documento é um fluxo ([Stream<String>]) de linhas, lidas à medida que chegam;
    • linhas 154–159: a tradução é procurada linha por linha, e o processo para na primeira ocorrência encontrada: [findFirst] interrompe o fluxo, e o restante da página nunca é lido. O fluxo é fechado na saída do [try] com recursos, o que libera a conexão. O resultado é um [Optional<String>], que fica vazio se nenhuma linha contiver uma tradução;
    • linhas 160–162: um erro de comunicação resulta em uma exceção de código 11. Um erro durante a leitura do fluxo de linhas é sinalizado por uma [UncheckedIOException], já que os métodos de [Stream] não podem lançar uma exceção verificada;
    • linhas 164–165: se a página foi lida por inteiro sem encontrar nenhuma tradução, uma exceção de código 12 é lançada.

O programa de teste:

  • linha 17: o endereço do site pode ser passado como argumento;
  • linha 18: o cliente HTTP da aplicação;
  • linha 20: criação do serviço. O programa passa então a interagir com o serviço apenas por meio de sua interface [ITranslationService];
  • linhas 24–30: alguns testes, incluindo dois casos de erro: um texto vazio e um sentido de tradução desconhecido. Cada teste é um record [Trial] (linhas 13–14).

Resultados, com o site [Internet16.java] iniciado em outra janela:

> java Internet17.java
Translation directions offered by the site:
  fe : French to English
  ef : English to French
  fs : French to Spanish
Translation [French to English] of [ce chien est perdu] : [this dog is lost]
Translation [French to Spanish] of [l'été sera chaud] : [el verano será caliente]
Translation [English to French] of [my tailor is rich] : [mon tailleur est riche]
Translation [English to French] of [xx] : [xx]
The following error with code 12 occurred: The server did not send back a translation
The following error with code 10 occurred: The translation direction [fx] is not recognized
  • linhas 3–5: os sentidos de tradução foram lidos do formulário do site;
  • linha 9: uma palavra desconhecida é devolvida como está;
  • linha 10: para um texto vazio, o site devolveu seu formulário sem tradução;
  • linha 11: a tradução [fx] foi recusada pelo serviço sem consultar o site.

Se o site estiver indisponível:

1
2
3
> java Internet17.java http://localhost:27299/
The following error with code 11 occurred: The translation site is unreachable
Cause: java.net.ConnectException

No lado do site, vemos a requisição de [curl] vista acima, seguida das enviadas pelo cliente: a primeira para o formulário, as seguintes para as traduções (a tradução [fx], recusada pelo serviço, não gerou nenhuma requisição). [URLEncoder] codificou os espaços com [+], enquanto a URL passada ao [curl], os codificou com [%20]:

1
2
3
4
5
6
7
8
9
> java Internet16.java
Translation service started on http://localhost:27220/translation
GET /translation?direction=fs&text=l%27%C3%A9t%C3%A9%20sera%20chaud -> 200
GET /translation -> 200
GET /translation?direction=fe&text=ce+chien+est+perdu -> 200
GET /translation?direction=fs&text=l%27%C3%A9t%C3%A9+sera+chaud -> 200
GET /translation?direction=ef&text=my+tailor+is+rich -> 200
GET /translation?direction=ef&text=xx -> 200
GET /translation?direction=fe&text= -> 200

12.7.3.4. Conclusão

Esta aplicação demonstrou que o [HttpClient] nos permite aproveitar recursos da web. A técnica é sempre a mesma:

  • determinar a URL a consultar. Em geral, ela é pré-configurada;
  • consultá-la;
  • encontrar o que procuramos na resposta do servidor por meio de expressões regulares.

Essa técnica, hoje conhecida como “web scraping”, é frágil: com o tempo, a URL consultada ou a estrutura da página podem mudar, e a expressão regular que encontrava o resultado pode deixar de funcionar. É uma boa ideia guardar essas informações em um arquivo de configuração, mas isso nem sempre basta; além disso, os termos de uso de muitos sites a proíbem. Uma análise robusta de uma página HTML seria, aliás, mais bem feita com uma biblioteca especializada, como o jsoup, do que com expressões regulares. Veremos no próximo capítulo que existem recursos mais estáveis na Web, projetados para uso por programas: os serviços web. Os serviços de tradução atuais, por exemplo, oferecem todos uma interface desse tipo, que aceita e devolve JSON.

12.7.4. Um cliente SMTP com Jakarta Mail

Um cliente SMTP é cliente de um servidor SMTP, um servidor de envio de e-mail, cujo protocolo descrevemos na Parte 1. O JDK não possui uma classe para e-mail. A biblioteca padrão de fato é o Jakarta Mail (antigo JavaMail), cuja implementação de referência hoje se chama Eclipse Angus Mail. Ela encapsula as exigências de um cliente de e-mail: o desenvolvedor não precisa conhecer os detalhes do protocolo SMTP nem os do formato de mensagem MIME. Suas principais classes são [Session] (a configuração), [MimeMessage] (uma mensagem), [InternetAddress] (um endereço de e-mail), [MimeMultipart] e [MimeBodyPart] (uma mensagem com várias partes, como texto e anexos) e [Transport], que envia a mensagem. Ela também sabe ler e-mails em POP3 e IMAP e cuida da autenticação e da criptografia (TLS) exigidas pelos servidores reais.

Não podemos enviar e-mails a um servidor SMTP real: nossa máquina de teste não tem acesso à Internet e, como mencionamos, os provedores de acesso bloqueiam a porta 25. O e-mail será enviado a um pequeno servidor de teste, escrito em Java e executado na máquina local, que exibirá tudo o que receber e não encaminhará nada. Para uso real, existem servidores de teste completos, como Mailpit ou GreenMail (escrito em Java), que também oferecem uma interface para consultar as mensagens recebidas.

12.7.4.1. Um servidor SMTP de teste

Nosso servidor SMTP segue a estrutura do servidor de eco da Parte 1: um laço que espera clientes, uma thread virtual por cliente e encerramento limpo com Ctrl-C. O serviço prestado a cada cliente é o diálogo SMTP mínimo apresentado na Parte 1. O programa [Internet18.java] é o seguinte:

import static java.nio.charset.StandardCharsets.UTF_8;

// servidor SMTP de teste: ele executa o diálogo SMTP mínimo e exibe as mensagens recebidas,
// sem nunca entregá-las a seus destinatários
// chamada: java Internet18.java [port]   (porta 27225 por padrão); parar com Ctrl-C

final Set<Socket> connections = ConcurrentHashMap.newKeySet();
volatile boolean stop = false;

void main(String[] args) {
    int port = args.length == 1 ? Integer.parseInt(args[0]) : 27225;
    // o servidor só aceita os clientes da máquina local (endereço de loopback)
    try (var listener = new ServerSocket(port, 50, InetAddress.getLoopbackAddress());
         var services = Executors.newVirtualThreadPerTaskExecutor()) {
        stopOnCtrlC(listener);
        IO.println("Test SMTP server started on " + listener.getLocalSocketAddress());
        try {
            for (int clientNum = 0; ; clientNum++) {
                Socket client = listener.accept();
                connections.add(client);
                int number = clientNum;
                services.submit(() -> serve(client, number));
            }
        } catch (SocketException e) {
            if (!stop) {
                throw e;
            }
            IO.println("Server stop requested");
            for (Socket connection : connections) {
                connection.close();
            }
        }
    } catch (IOException e) {
        IO.println("The following error occurred on the server: " + e.getMessage());
    }
}

// Ctrl-C: fechamento do serviço de escuta e depois espera pelo fim do programa principal
void stopOnCtrlC(ServerSocket listener) {
    Thread main = Thread.currentThread();
    Runtime.getRuntime().addShutdownHook(new Thread(() -> {
        stop = true;
        try {
            listener.close();
            main.join();
        } catch (IOException | InterruptedException e) {
            // paramos assim mesmo
        }
    }));
}

// o diálogo SMTP com um cliente: C: linhas recebidas do cliente, S: linhas enviadas pelo servidor
void serve(Socket client, int clientNum) {
    IO.println("--- start of the dialog with client " + clientNum + " ("
            + client.getRemoteSocketAddress() + ")");
    try (client;
         var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var writer = new OutputStreamWriter(client.getOutputStream(), UTF_8)) {
        // envio de uma linha de resposta, também exibida no console; o SMTP exige fins de linha \r\n
        Responder reply = response -> {
            IO.println("S: " + response);
            writer.write(response + "\r\n");
            writer.flush();
        };
        // o envelope da mensagem atual: remetente e destinatários
        String sender = null;
        List<String> recipients = new ArrayList<>();
        // mensagem de boas-vindas
        reply.send("220 smtp.test ESMTP test server of the Java course");
        String command;
        while ((command = reader.readLine()) != null) {
            IO.println("C: " + command);
            // o verbo: os quatro primeiros caracteres, sem diferenciar maiúsculas de minúsculas
            String verb = command.length() >= 4 ? command.substring(0, 4) : command;
            verb = verb.toUpperCase(Locale.ROOT);
            // o que vem depois do caractere ":" em MAIL FROM:<address> e RCPT TO:<address>
            String address = command.substring(command.indexOf(':') + 1).strip();
            switch (verb) {
                case "EHLO" -> {
                    // resposta em várias linhas: 250-... depois 250 ...
                    reply.send("250-smtp.test hello");
                    reply.send("250-SIZE 10485760");
                    reply.send("250 8BITMIME");
                }
                case "HELO" -> reply.send("250 smtp.test hello");
                case "MAIL" -> {
                    sender = address;
                    recipients.clear();
                    reply.send("250 2.1.0 Ok");
                }
                case "RCPT" -> {
                    recipients.add(address);
                    reply.send("250 2.1.5 Ok");
                }
                case "DATA" -> {
                    // o remetente e os destinatários são exigidos primeiro
                    if (sender == null || recipients.isEmpty()) {
                        reply.send("503 5.5.1 Give the sender and the recipients first");
                        continue;
                    }
                    reply.send("354 End data with <CR><LF>.<CR><LF>");
                    // a mensagem: todas as linhas até uma linha reduzida a um ponto
                    int nbLines = 0;
                    String line;
                    while ((line = reader.readLine()) != null && !line.equals(".")) {
                        IO.println("C: " + line);
                        nbLines++;
                    }
                    // o cliente fechou a conexão antes do fim da mensagem
                    if (line == null) {
                        IO.println("[incomplete message: connection closed by the client]");
                        return;
                    }
                    IO.println("C: .");
                    IO.println("[message from %s to %s: %d lines]".formatted(sender,
                            String.join(", ", recipients), nbLines));
                    reply.send("250 2.0.0 Ok: message accepted");
                    sender = null;
                    recipients.clear();
                }
                case "RSET" -> {
                    sender = null;
                    recipients.clear();
                    reply.send("250 2.0.0 Ok");
                }
                case "NOOP" -> reply.send("250 2.0.0 Ok");
                case "QUIT" -> {
                    reply.send("221 2.0.0 Bye");
                    return;
                }
                default -> reply.send("502 5.5.2 Command not recognized");
            }
        }
    } catch (IOException e) {
        if (stop) {
            IO.println("Dialog with client " + clientNum + " interrupted by the server stop");
        } else {
            IO.println("The following error occurred with client " + clientNum + ": "
                    + e.getMessage());
        }
    } finally {
        connections.remove(client);
        IO.println("--- end of the dialog with client " + clientNum);
    }
}

// envio de uma linha de resposta: uma interface funcional cujo método pode lançar uma IOException
interface Responder {
    void send(String response) throws IOException;
}

Comentaremos apenas o que é novo em relação ao servidor de eco:

  • linha 13: o servidor escuta apenas no endereço de loopback; somente programas da mesma máquina podem se conectar a ele. O segundo parâmetro (50) é o tamanho da fila de conexões;
  • linhas 60–64: uma lambda que envia uma linha de resposta ao cliente, terminada por \r\n como exige o SMTP, e a exibe no console, precedida de [S:]. As linhas recebidas do cliente são exibidas precedidas por [C:], como nos diálogos de exemplo da Parte 1. As interfaces funcionais do JDK ([Consumer<String>]…) não permitem exceções verificadas: por isso declaramos nossa própria interface funcional, [Responder] (linhas 148–150), cujo método pode lançar uma [IOException];
  • linhas 66–67: o envelope da mensagem atual: o remetente indicado por [MAIL FROM] e os destinatários indicados por [RCPT TO];
  • linha 69: a mensagem de saudação: no SMTP, o servidor fala primeiro;
  • linhas 74–75: o verbo do comando é formado por seus quatro primeiros caracteres ([EHLO], [MAIL], [RCPT]…), em maiúsculas. [Locale.ROOT] torna a conversão independente do idioma da máquina (em turco, a versão maiúscula de [i] não é [I]);
  • linhas 79–84: a resposta a [EHLO] é composta de várias linhas. O servidor lista aqui suas capacidades: o tamanho máximo da mensagem ([SIZE]) e o suporte a caracteres codificados em 8 bits ([8BITMIME]);
  • linhas 97–100: o comando [DATA] é recusado se o remetente ou os destinatários não tiverem sido indicados; [continue] passa ao comando seguinte;
  • linhas 101–119: a mensagem propriamente dita. O servidor convida o cliente a enviá-la (código 354), depois lê e exibe todas as linhas até uma linha reduzida a um único ponto, e confirma o recebimento (código 250). Se o cliente fechar a conexão antes do fim da mensagem, ela é descartada (linhas 110–113);
  • linhas 127–130: o cliente terminou; o servidor responde e fecha a conexão, saindo do método (o [try] com recursos fecha o socket);
  • linha 131: qualquer outro comando é recusado.

Este servidor não faz muitas verificações e não trata as extensões [STARTTLS] e [AUTH] : ele é suficiente para observar o que o Jakarta Mail envia.

12.7.4.2. O cliente SMTP

O programa [Internet19] pede ao usuário os dados do e-mail (remetente, destinatários, assunto, anexos, corpo) e o envia ao servidor SMTP indicado como argumento. Trata-se de um projeto Maven, no qual o [pom.xml] declara a seguinte dependência:

1
2
3
4
5
6
7
8
    <dependencies>
        <!-- Jakarta Mail: a API jakarta.mail e sua implementação Eclipse Angus -->
        <dependency>
            <groupId>org.eclipse.angus</groupId>
            <artifactId>angus-mail</artifactId>
            <version>2.0.3</version>
        </dependency>
    </dependencies>

A dependência [angus-mail] fornece a implementação e, por dependências transitivas, a API, as bibliotecas [jakarta.mail], e [jakarta.activation] que ela utiliza. O código usa apenas a API, encontrada nos pacotes [jakarta.mail] e [jakarta.mail.internet]. A classe [Internet19] é a seguinte:

package internet;

import jakarta.mail.Message.RecipientType;
import jakarta.mail.MessagingException;
import jakarta.mail.Session;
import jakarta.mail.Transport;
import jakarta.mail.internet.AddressException;
import jakarta.mail.internet.InternetAddress;
import jakarta.mail.internet.MimeBodyPart;
import jakarta.mail.internet.MimeMessage;
import jakarta.mail.internet.MimeMultipart;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;

// envio de um e-mail com o Jakarta Mail
// chamada: mvn exec:java -Dexec.args="smtpServer port"
// os anexos são procurados na pasta atual
public class Internet19 {

    private static final String SYNTAX = "Syntax: mvn exec:java -Dexec.args=\"smtpServer port\"";

    public static void main(String[] args) {
        if (args.length != 2 || !args[1].matches("\\d{1,5}")) {
            IO.println(SYNTAX);
            return;
        }
        String server = args[0];
        String port = args[1];

        // entrada dos elementos do e-mail
        String sender = input("Sender");
        String recipients = input("Recipients (separated by commas)");
        String copies = input("Copy to (Cc)");
        String blindCopies = input("Blind copy to (Bcc)");
        String subject = input("Subject");
        String attachments = input("Attachments (separated by commas)");
        // o texto: várias linhas, terminadas por uma linha vazia
        IO.println("Text of the message (ended by an empty line):");
        var text = new StringBuilder();
        String line;
        while ((line = IO.readln()) != null && !line.isEmpty()) {
            text.append(line).append('\n');
        }

        try {
            // a sessão de e-mail: ela contém a configuração do cliente SMTP
            var properties = new Properties();
            properties.put("mail.smtp.host", server);
            properties.put("mail.smtp.port", port);
            Session session = Session.getInstance(properties);

            // a mensagem
            var message = new MimeMessage(session);
            var from = new InternetAddress(sender, true);
            from.validate();
            message.setFrom(from);
            message.setRecipients(RecipientType.TO, addresses(recipients));
            message.setRecipients(RecipientType.CC, addresses(copies));
            message.setRecipients(RecipientType.BCC, addresses(blindCopies));
            message.setSubject(subject, "UTF-8");
            // uma mensagem multipart: primeiro o texto, em UTF-8 transportado como está (8 bits)
            var textPart = new MimeBodyPart();
            textPart.setText(text.toString(), "UTF-8");
            textPart.setHeader("Content-Transfer-Encoding", "8bit");
            var content = new MimeMultipart(textPart);
            // depois os anexos, designados por seu caminho
            List<String> names = new ArrayList<>();
            for (String file : attachments.split(",")) {
                if (!file.isBlank()) {
                    var part = new MimeBodyPart();
                    part.attachFile(new File(file.strip()));
                    content.addBodyPart(part);
                    names.add(part.getFileName());
                }
            }
            message.setContent(content);

            // o envio: Transport conhece o protocolo SMTP; a mensagem conhece o formato MIME
            Transport.send(message);

            // resumo do envio
            IO.println("Sending successful...");
            IO.println("Subject: " + message.getSubject());
            IO.println("Recipients: " + list(message, RecipientType.TO));
            IO.println("Cc: " + list(message, RecipientType.CC));
            IO.println("Bcc: " + list(message, RecipientType.BCC));
            IO.println("Attachments: " + String.join(", ", names));
        } catch (MessagingException | IOException e) {
            IO.println("The following error occurred: " + e.getClass().getSimpleName() + " : "
                    + e.getMessage());
            if (e.getCause() != null) {
                IO.println("Cause: " + e.getCause());
            }
        }
    }

    // uma lista de endereços separados por vírgulas; cada endereço é verificado
    private static InternetAddress[] addresses(String list) throws AddressException {
        InternetAddress[] addresses = InternetAddress.parse(list, true);
        for (InternetAddress address : addresses) {
            address.validate();
        }
        return addresses;
    }

    // os endereços de uma categoria de destinatários, separados por vírgulas
    private static String list(MimeMessage message, RecipientType type) throws MessagingException {
        return InternetAddress.toString(message.getRecipients(type));
    }

    // entrada de uma linha no teclado
    private static String input(String label) {
        String line = IO.readln(label + " : ");
        return line == null ? "" : line.strip();
    }
}

Comentários:

  • linhas 34–46: entrada dos elementos do e-mail pelo método [input] (linhas 115–118). O texto da mensagem é composto de várias linhas, terminadas por uma linha em branco;
  • linhas 50–53: a sessão de e-mail. Sua configuração é um objeto [Properties]: aqui, a máquina e a porta do servidor SMTP. Para um servidor real, acrescentaríamos [mail.smtp.auth=true], [mail.smtp.starttls.enable=true] (criptografia via [STARTTLS]) e forneceríamos o nome de usuário e a senha a [Transport.send];
  • linhas 56–63: a mensagem:
    • linhas 57–59: o remetente, um objeto [InternetAddress]. O segundo parâmetro do construtor ([true]) exige uma validação estrita do endereço, e [validate] verifica além disso que ele tem a forma [name@domain]; um endereço incorreto resulta em uma [AddressException];
    • linhas 60–62: os destinatários, os do campo “Cc” (Carbon Copy) e os do campo “Bcc” (Blind Carbon Copy). Os destinatários do campo “Bcc” recebem a mensagem, mas os outros destinatários não sabem disso. O método [addresses] (linhas 101–107) analisa uma lista de endereços separados por vírgulas com [InternetAddress.parse] e valida cada um deles;
    • linha 63: o assunto, com seu conjunto de caracteres;
  • linhas 65–68: a mensagem é composta de várias partes ([MimeMultipart]). A primeira parte é o texto, em UTF-8. O cabeçalho [Content-Transfer-Encoding: 8bit] especifica que ele deve ser transmitido como está, em 8 bits (o servidor indicou que aceita isso); sem ele, o Jakarta Mail escolheria sua própria codificação (quoted-printable ou base64), o que tornaria o texto difícil de ler quando exibido pelo servidor;
  • linhas 71–78: os anexos, identificados por seus caminhos de arquivo. Um caminho relativo é relativo ao diretório atual; em nossos testes, o arquivo [attachment.txt] está no diretório [Internet19], a partir do qual o programa é iniciado. [attachFile] cria uma parte cujo conteúdo será lido do arquivo no momento do envio;
  • linha 82: envio da mensagem pelo método estático [Transport.send], que se conecta ao servidor indicado pela sessão, executa o diálogo SMTP e transmite a mensagem no formato MIME;
  • linhas 85–90: um resumo da transmissão. [InternetAddress.toString] (linha 111) concatena uma lista de endereços em uma única string;
  • linhas 91–97: um endereço inválido dispara uma [AddressException]; um erro de envio dispara uma [MessagingException], cuja causa é exibida. Um anexo ausente só é detectado no momento do envio: ele dispara uma [MessagingException], cuja causa é uma [FileNotFoundException].

O servidor SMTP de teste é iniciado em uma janela de comando, na porta 27225. Em outra janela, a partir da pasta [Internet19], uma mensagem é enviada a dois destinatários, com um destinatário em cópia, um em cópia oculta e um anexo:

> mvn compile exec:java -Dexec.args="localhost 27225"
Sender : alice@example.org
Recipients (separated by commas) : bob@example.com, carole@example.com
Copy to (Cc) : david@example.com
Blind copy to (Bcc) : eve@example.com
Subject : Meeting minutes
Attachments (separated by commas) : attachment.txt
Text of the message (ended by an empty line):
Hello,
here are the minutes of the summer meeting.
Best regards,
Alice

Sending successful...
Subject: Meeting minutes
Recipients: bob@example.com, carole@example.com
Cc: david@example.com
Bcc: eve@example.com
Attachments: attachment.txt

O arquivo [attachment.txt] contém duas linhas de texto. Eis o que o servidor exibiu:

> java Internet18.java
Test SMTP server started on localhost/127.0.0.1:27225
--- start of the dialog with client 0 (/127.0.0.1:47628)
S: 220 smtp.test ESMTP test server of the Java course
C: EHLO localhost
S: 250-smtp.test hello
S: 250-SIZE 10485760
S: 250 8BITMIME
C: MAIL FROM:<alice@example.org>
S: 250 2.1.0 Ok
C: RCPT TO:<bob@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<carole@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<david@example.com>
S: 250 2.1.5 Ok
C: RCPT TO:<eve@example.com>
S: 250 2.1.5 Ok
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: Date: Sat, 3 Oct 2026 19:41:44 +0200 (CEST)
C: From: alice@example.org
C: To: bob@example.com, carole@example.com
C: Cc: david@example.com
C: Message-ID: <1094834071.1.1791049304833@localhost>
C: Subject: Meeting minutes
C: MIME-Version: 1.0
C: Content-Type: multipart/mixed; 
C:     boundary="----=_Part_0_1213415012.1791049304796"
C: 
C: ------=_Part_0_1213415012.1791049304796
C: Content-Type: text/plain; charset=UTF-8
C: Content-Transfer-Encoding: 8bit
C: 
C: Hello,
C: here are the minutes of the summer meeting.
C: Best regards,
C: Alice
C: 
C: ------=_Part_0_1213415012.1791049304796
C: Content-Type: text/plain; charset=us-ascii; name=attachment.txt
C: Content-Transfer-Encoding: 7bit
C: Content-Disposition: attachment; filename=attachment.txt
C: 
C: This is the attachment of the test mail.
C: It contains two lines.
C: 
C: ------=_Part_0_1213415012.1791049304796--
C: .
[message from <alice@example.org> to <bob@example.com>, <carole@example.com>, <david@example.com>, <eve@example.com>: 28 lines]
S: 250 2.0.0 Ok: message accepted
C: QUIT
S: 221 2.0.0 Bye
--- end of the dialog with client 0
Server stop requested

Comentários:

  • linha 5: o Jakarta Mail se identifica com o nome da máquina local, neste caso [localhost];
  • linhas 9–18: o envelope da mensagem: o remetente, seguido de todos os destinatários, inclusive o destinatário em cópia oculta ([eve@example.com]). O envelope determina a quem a mensagem é entregue;
  • linhas 21–29: os cabeçalhos da mensagem, que compõem o que os destinatários verão: a data, o remetente, os destinatários [To] e [Cc], um identificador único da mensagem ([Message-ID]), o assunto… O destinatário em cópia oculta não aparece aqui: é assim que ele permanece oculto. A linha de assunto contém apenas caracteres ASCII e é enviada como está; como os cabeçalhos só podem conter caracteres ASCII, um assunto com um caractere acentuado teria sido codificado segundo a RFC 2047: [=?UTF-8?Q?...?=] significa “texto UTF-8 codificado em quoted-printable”, com cada byte não ASCII escrito como [=XX] em hexadecimal ([=C3=A9] para os dois bytes de [é]) e cada espaço como [_];
  • linhas 28–29: a mensagem está no formato MIME (Multipurpose Internet Mail Extensions, RFC 2045 e seguintes): ela é composta de várias partes ([multipart/mixed]), separadas por uma linha delimitadora ([boundary]) escolhida aleatoriamente pelo Jakarta Mail. Um cabeçalho longo demais pode ser quebrado na linha seguinte, desde que ela comece com um espaço ou uma tabulação;
  • linhas 31–39: a primeira parte, o corpo da mensagem, em UTF-8 de 8 bits: ela é legível como está;
  • linhas 40–47: a segunda parte, o anexo. O Jakarta Mail reconheceu um arquivo de texto ([text/plain]) contendo apenas caracteres ASCII ([charset=us-ascii]) e o transmitiu como está ([7bit]); um texto com outros caracteres teria sido codificado em quoted-printable: essa codificação mantém legíveis os caracteres ASCII e codifica os demais, como [è] ([=C3=A8]). Um arquivo binário (uma imagem, por exemplo) teria sido codificado em Base64, que representa bytes quaisquer usando 64 caracteres do conjunto ASCII. O cabeçalho [Content-Disposition: attachment] indica que se trata de um anexo e fornece seu nome;
  • linhas 48–49: o delimitador de fechamento, seguido de dois hifens, depois a linha reduzida a um único ponto que encerra a mensagem;
  • linha 50: nosso servidor recebeu uma mensagem para quatro destinatários;
  • linhas 52–53: o Jakarta Mail encerra a sessão;
  • linha 55: o servidor foi interrompido com Ctrl-C após os testes.

Um endereço inválido é recusado antes que qualquer mensagem seja enviada:

> mvn compile exec:java -Dexec.args="localhost 27225"
Sender : alice@example.org
Recipients (separated by commas) : bob.example.com
Copy to (Cc) : 
Blind copy to (Bcc) : 
Subject : test
Attachments (separated by commas) : 
Text of the message (ended by an empty line):
text

The following error occurred: AddressException : Missing final '@domain'

Se o servidor SMTP não estiver disponível, uma [MailConnectException], variante de [MessagingException], é lançada; ela é causada pela [ConnectException] do socket:

> mvn compile exec:java -Dexec.args="localhost 27299"
Sender : alice@example.org
Recipients (separated by commas) : bob@example.com
Copy to (Cc) : 
Blind copy to (Bcc) : 
Subject : test
Attachments (separated by commas) : 
Text of the message (ended by an empty line):
text

The following error occurred: MailConnectException : Couldn't connect to host, port: localhost, 27299; timeout -1
Cause: java.net.ConnectException: Connection refused

12.8. Programação de rede assíncrona: dos canais NIO às threads virtuais

Com exceção das requisições [sendAsync] do [HttpClient], os programas deste capítulo usam operações de rede bloqueantes, executadas por threads (threads virtuais para os servidores). Esta não é a única maneira de fazer, e o leitor encontrará em códigos existentes os outros dois modelos que o Java oferecia antes do Java 21.

O primeiro, introduzido no Java 1.4, é o modelo de E/S não bloqueante do pacote [java.nio.channels]. Um [SocketChannel] configurado em modo não bloqueante ([channel.configureBlocking(false)]) devolve imediatamente o controle, haja ou não dados para ler; um objeto [Selector] permite a uma única thread monitorar um grande número de canais e ser despertada quando um deles estiver pronto (uma nova conexão a aceitar, dados a ler, espaço para escrever). O programa executa então em um único laço que, a cada despertar, trata os canais prontos. Os dados são lidos em blocos, em buffers de bytes ([ByteBuffer]): cabe ao programa reconstituir as linhas, já que uma linha pode ficar dividida entre dois blocos, e guardar, para cada cliente, o estado atual de sua sessão.

O segundo, introduzido no Java 7 (NIO.2), é o dos canais assíncronos: [AsynchronousSocketChannel] e [AsynchronousServerSocketChannel]. Cada operação é iniciada com um objeto de retorno de chamada ([CompletionHandler]), cujo método [completed] é executado por uma thread de um pool ao fim da operação. Uma conexão de cliente se escreve, assim, [channel.connect(address, null, handler)], e o método [completed] do handler deve iniciar a leitura seguinte, cujo método [completed] iniciará a próxima, e assim por diante. O código é longo, e a lógica do diálogo fica espalhada por vários métodos de retorno de chamada.

Esses dois modelos são eficientes: permitem que poucas threads atendam milhares de conexões. Mas são difíceis de programar e de depurar; são usados sobretudo por meio de bibliotecas como o Netty, no qual se baseiam muitos servidores. As threads virtuais do Java 21 tornaram essas técnicas desnecessárias para a maioria das aplicações: uma thread virtual bloqueada em uma operação de rede não bloqueia nenhuma thread do sistema, e o código se lê na ordem em que é executado, como um código síncrono. O cliente TCP genérico da Parte 1 ([Internet06.java]) é um exemplo disso: uma thread virtual lê do teclado enquanto a thread principal lê da rede, com simples chamadas a [readLine].

Convém lembrar que a assincronia traz pouco benefício a um cliente com uma única conexão: sua thread não tem nada a fazer além de esperar a resposta. Ela é, porém, essencial para um servidor: um servidor que atende seus clientes com threads de plataforma bloqueantes prende uma thread do sistema por cliente; com threads virtuais ou canais não bloqueantes, algumas poucas threads do sistema bastam para atender um grande número de clientes. É o que faz o servidor da aplicação de exemplo a seguir.

12.9. Aplicação de exemplo, versão 8: servidor de cálculo do imposto

12.9.1. A arquitetura da nova versão

Retomemos a aplicação de cálculo do imposto. Na versão 5 (Capítulo 6), ela era composta de três camadas, cada uma em seu próprio módulo Maven: [dao] (as faixas do imposto), [business] (o cálculo) e [ui] (o diálogo de console), montadas pelo contêiner de injeção de dependência do Spring; as versões 6 e 7 substituíram a camada [dao] por um acesso a banco de dados. Partiremos da versão 5, mais simples de executar: a nova versão funcionaria da mesma forma com a camada [dao] das versões 6 e 7.

Implantaremos essa arquitetura em duas máquinas:

Image

  • uma máquina [server] hospeda as camadas [business] e [dao] da versão 5. Uma camada chamada [server] é construída para permitir que clientes da rede consultem o serviço de cálculo do imposto por meio de um protocolo textual chamado TCP;
  • uma máquina [client] hospeda a camada [ui] da versão 5. Uma nova camada [business], que atua como cliente da camada TCP do servidor, permite consultar o serviço de cálculo do imposto no servidor.

A arquitetura passa por uma grande mudança: a versão 5 era uma aplicação monousuário; a versão 8 se torna uma aplicação cliente/servidor, e o servidor poderá atender vários clientes simultaneamente. Escreveremos, porém, apenas duas novas classes, [TaxServer] e [TaxBusinessTcp], um record de opções e dois programas principais: todo o resto é reutilizado sem modificação.

O projeto [TaxV8] é um projeto Maven multimódulo composto de dois módulos que usam os módulos da versão 5. Estes devem ter sido instalados no repositório Maven local com o comando [mvn install], executado na pasta [TaxV5] (Capítulo 6):

12-internet/TaxV8/
  pom.xml                         parent project: modules, versions, common configuration
  tax-server/
    pom.xml                       dependencies: tax-dao and tax-business (V5), Spring
    server.properties             configuration of the [dao] layer and of the server
    TaxData.txt                   the tax brackets
    src/main/java/tax/server/
      Main.java                   integration of the layers, launch of the server
      ServerOptions.java          the options of the server
      TaxServer.java              the [server] layer
  tax-client/
    pom.xml                       dependencies: tax-business and tax-ui (V5), Spring
    src/main/java/tax/client/
      TaxBusinessTcp.java         the [business] layer of the client: a TCP client
      Main.java                   integration of the layers, dialog

O projeto pai é o seguinte:

<?xml version="1.0" encoding="UTF-8"?>
<!-- projeto pai da aplicação [Tax], versão 8: um servidor TCP e seu cliente -->
<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>

    <groupId>examples.tax</groupId>
    <artifactId>tax-v8</artifactId>
    <version>8.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>tax-server</module>
        <module>tax-client</module>
    </modules>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <!-- as camadas da versão 5 (instaladas por mvn install em TaxV5) e o Spring -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>examples.tax</groupId>
                <artifactId>tax-dao</artifactId>
                <version>5.0</version>
            </dependency>
            <dependency>
                <groupId>examples.tax</groupId>
                <artifactId>tax-business</artifactId>
                <version>5.0</version>
            </dependency>
            <dependency>
                <groupId>examples.tax</groupId>
                <artifactId>tax-ui</artifactId>
                <version>5.0</version>
            </dependency>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-context</artifactId>
                <version>7.0.9</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.15.0</version>
                    <configuration>
                        <parameters>true</parameters>
                        <compilerArgs>
                            <arg>-Xlint:all</arg>
                        </compilerArgs>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.codehaus.mojo</groupId>
                    <artifactId>exec-maven-plugin</artifactId>
                    <version>3.5.1</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>
  • linhas 8–11: o projeto pai, com o empacotamento [pom], tem a versão de aplicação 8.0;
  • linhas 13–16: seus dois módulos;
  • linhas 24–47: as versões das dependências usadas pelos módulos: os três módulos da versão 5 e o contêiner Spring;
  • linhas 49–70: a configuração comum do compilador e do plugin de execução.

12.9.2. O protocolo de comunicação

Quando o cliente se conecta, o servidor lhe envia uma mensagem de boas-vindas e depois aceita os comandos a seguir, um por linha, sem distinção entre maiúsculas e minúsculas:

Comando
Resposta do servidor
help
uma lista dos comandos aceitos, em quatro linhas
tax married nbChildren annualSalary
o imposto de uma pessoa casada (married vale [y]) ou solteira ([n]) com [nbChildren] filhos e um salário anual de [annualSalary] euros, por exemplo, [4282] em resposta a [tax y 2 60000]; ou uma mensagem de erro, em uma linha
goodbye
a mensagem [Goodbye...]; o servidor então fecha a conexão

Qualquer outro comando recebe a resposta [Command not recognized. Use the help command.]

12.9.3. O servidor de cálculo do imposto

12.9.3.1. O módulo

O arquivo [pom.xml] do módulo [tax-server] é o seguinte:

<?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>examples.tax</groupId>
        <artifactId>tax-v8</artifactId>
        <version>8.0</version>
    </parent>

    <artifactId>tax-server</artifactId>

    <dependencies>
        <!-- as camadas [dao] e [business] da versão 5, reutilizadas como estão -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-dao</artifactId>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
        </dependency>
        <!-- o contêiner de injeção de dependência Spring -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- mvn exec:java executa a classe principal, na pasta do módulo -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <configuration>
                    <mainClass>tax.server.Main</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
  • linhas 7–11: o módulo herda do projeto pai;
  • linhas 17–24: as camadas [dao] e [business] da versão 5 são dependências, sem versão especificada: a versão é fornecida pelo projeto pai;
  • linhas 26–29: o contêiner de injeção de dependência do Spring;
  • linhas 35–41: a classe principal executada por [mvn exec:java]. Como na versão 5, o programa lê sua configuração e o arquivo das faixas do imposto no diretório atual, isto é, o diretório do módulo, onde estão os arquivos [server.properties] e [TaxData.txt].

O arquivo de configuração [server.properties]:

1
2
3
4
5
6
7
# configuração do servidor de cálculo do imposto
# a camada [dao]: como na versão 5
dao.implementation=FileTax
dao.file=TaxData.txt
# a porta de escuta e o eco do diálogo com os clientes no log
server.port=27200
server.echo=true
  • linhas 3–4: a configuração da camada [dao], idêntica à da versão 5: as faixas do imposto são lidas do arquivo de texto [TaxData.txt];
  • linhas 6–7: a porta de escuta do servidor e o eco do diálogo com os clientes no log do servidor. Em vez de um console de administração (com comandos como [start], [stop], [echo]…), optamos por um arquivo de configuração e pelo encerramento com Ctrl-C, que são mais simples e mais condizentes com o funcionamento dos servidores modernos.

12.9.3.2. O programa principal

As opções do servidor formam um record:

1
2
3
4
5
package tax.server;

// as opções do servidor: porta de escuta e eco do diálogo no log
public record ServerOptions(int port, boolean echo) {
}

A classe [Main] do servidor é a seguinte:

package tax.server;

import tax.dao.FileTax;
import tax.dao.HardwiredTax;
import tax.dao.ITaxDao;
import tax.dao.JsonTax;
import tax.entities.TaxException;
import tax.business.TaxBusiness;
import java.io.IOException;
import java.io.Reader;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;
import org.springframework.context.support.GenericApplicationContext;

// o servidor TCP de cálculo do imposto: configuração, integração das camadas, execução
// chamada: mvn exec:java (na pasta tax-server); parar com Ctrl-C
public class Main {

    public static void main(String[] args) {
        TaxServer server;
        try {
            // lendo a configuração, na pasta atual
            Properties config = new Properties();
            try (Reader reader = Files.newBufferedReader(Path.of("server.properties"))) {
                config.load(reader);
            }
            String implementation = config.getProperty("dao.implementation", "HardwiredTax");
            String file = config.getProperty("dao.file", "");
            int port = Integer.parseInt(config.getProperty("server.port", "27200"));
            boolean echo = Boolean.parseBoolean(config.getProperty("server.echo", "false"));

            // registro das camadas no contêiner do Spring
            GenericApplicationContext context = new GenericApplicationContext();
            // a camada [dao]: a implementação é escolhida pela configuração (como na versão 5)
            context.registerBean(ITaxDao.class, () -> switch (implementation) {
                case "HardwiredTax" -> new HardwiredTax();
                case "FileTax" -> new FileTax(file);
                case "JsonTax" -> new JsonTax(file);
                default -> throw new TaxException(
                        "Unknown implementation [" + implementation + "] of the [dao] layer");
            });
            // a camada [business] da versão 5
            context.registerBean(TaxBusiness.class);
            // a camada [server]: o contêiner passará ao seu construtor a camada [business]
            // e as opções do servidor
            context.registerBean(ServerOptions.class, () -> new ServerOptions(port, echo));
            context.registerBean(TaxServer.class);

            // inicialização do contêiner: criação das camadas [dao], [business] e [server]
            context.refresh();
            server = context.getBean(TaxServer.class);
        } catch (IOException | RuntimeException e) {
            // exibição da cadeia de exceções e parada
            IO.println("The following error occurred during the initialization of the server:");
            for (Throwable cause = e; cause != null; cause = cause.getCause()) {
                IO.println(cause.getClass().getSimpleName() + " : " + cause.getMessage());
            }
            System.exit(1);
            return;
        }

        // Ctrl-C: a parada do servidor é solicitada e depois esperamos o fim da thread principal
        Thread main = Thread.currentThread();
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            server.stop();
            try {
                main.join();
            } catch (InterruptedException e) {
                // paramos assim mesmo
            }
        }));
        // execução do servidor até que a parada seja solicitada
        server.execute();
    }
}

Reconhecemos o programa principal da versão 5:

  • linhas 24–31: leitura da configuração. Os valores são strings: a porta e o eco são convertidos, com valores padrão fornecidos;
  • linhas 34–44: as camadas [dao] e [business] são registradas no contêiner exatamente como na versão 5;
  • linhas 47–48: a novidade. As opções do servidor (porta, eco) são registradas como uma função que as constrói, seguidas da própria camada [server]. O construtor de [TaxServer] espera um [ITaxBusiness] e um [ServerOptions]: o contêiner os fornecerá;
  • linha 51: iniciar o contêiner cria o servidor, o que provoca a criação da camada [business], que por sua vez provoca a criação da camada [dao]; é nesse momento que o arquivo [TaxData.txt] é lido. Um erro (arquivo ausente ou malformado) é exibido, e o programa termina (linhas 53–61);
  • linhas 64–72: Ctrl-C aciona um hook de parada que pede ao servidor que pare e depois espera o término da thread principal, como no servidor de eco;
  • linha 74: o servidor executa até que lhe peçam para parar.

12.9.3.3. A camada [server]

A classe [TaxServer] é a seguinte:

package tax.server;

import tax.business.ITaxBusiness;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.net.ServerSocket;
import java.net.Socket;
import java.net.SocketException;
import java.time.LocalTime;
import java.time.format.DateTimeFormatter;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.Executors;
import java.util.function.Consumer;

import static java.nio.charset.StandardCharsets.UTF_8;

// a camada [server]: ela torna a camada [business] acessível por meio de um protocolo TCP de linhas de texto
public class TaxServer {

    // as respostas fixas do protocolo
    private static final String WELCOME = "Welcome to the tax calculation server";
    private static final String HELP = """
            Accepted commands
            1-help
            2-tax married(Y/N) nbChildren annualSalary
            3-goodbye""";
    private static final String GOODBYE = "Goodbye...";
    private static final String INCORRECT_COMMAND = "Command not recognized. Use the help command.";
    private static final String INCORRECT_CALCULATION = "Incorrect calculation command. Use the help command.";
    private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("HH:mm:ss");

    // a camada [business] e as opções, recebidas pelo construtor
    private final ITaxBusiness business;
    private final ServerOptions options;
    // o serviço de escuta e as conexões de serviço em andamento
    private volatile ServerSocket listener;
    private final Set<Socket> connections = ConcurrentHashMap.newKeySet();
    private volatile boolean stop = false;

    public TaxServer(ITaxBusiness business, ServerOptions options) {
        this.business = business;
        this.options = options;
    }

    // execução do servidor até que [stop] seja chamado
    public void execute() {
        // uma thread virtual por cliente; close() espera o fim de todos os serviços
        try (var listener = new ServerSocket(options.port());
             var services = Executors.newVirtualThreadPerTaskExecutor()) {
            this.listener = listener;
            log("Tax calculation server started on port " + options.port());
            try {
                for (int clientNum = 0; ; clientNum++) {
                    // espera por um cliente
                    Socket client = listener.accept();
                    connections.add(client);
                    // ele é atendido por uma thread virtual: voltamos imediatamente a esperar o próximo cliente
                    int number = clientNum;
                    services.submit(() -> serve(client, number));
                }
            } catch (SocketException e) {
                // accept falha quando [stop] fecha o serviço de escuta
                if (!stop) {
                    throw e;
                }
                log("Server stop requested");
                // as conexões em andamento são fechadas: os serviços param
                for (Socket connection : connections) {
                    connection.close();
                }
            }
        } catch (IOException e) {
            log("The following error occurred on the server: " + e.getMessage());
        }
        log("Server stopped");
    }

    // pedido de parada do servidor (chamado por outra thread)
    public void stop() {
        stop = true;
        try {
            if (listener != null) {
                listener.close();
            }
        } catch (IOException e) {
            // o serviço de escuta é fechado de qualquer maneira
        }
    }

    // o serviço prestado a um cliente
    private void serve(Socket client, int clientNum) {
        log("Start of service to client " + clientNum + " (" + client.getRemoteSocketAddress() + ")");
        try (client;
             var reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
             var writer = new PrintWriter(client.getOutputStream(), true, UTF_8)) {
            // envio de uma resposta ao cliente, com um possível eco no log
            Consumer<String> write = response -> {
                if (options.echo()) {
                    log("---> client " + clientNum + " : " + response);
                }
                writer.println(response);
            };
            // mensagem de boas-vindas
            write.accept(WELCOME);
            // laço de leitura da requisição / escrita da resposta, até o comando de despedida
            String request;
            while ((request = reader.readLine()) != null) {
                if (options.echo()) {
                    log("<--- client " + clientNum + " : " + request);
                }
                // a requisição dividida em campos
                String[] fields = request.strip().toLowerCase().split("\\s+");
                if (fields.length == 1 && fields[0].equals("goodbye")) {
                    write.accept(GOODBYE);
                    break;
                }
                // a resposta de acordo com o comando
                String response = switch (fields[0]) {
                    case "help" -> fields.length == 1 ? HELP : INCORRECT_COMMAND;
                    case "tax" -> calculateTax(fields);
                    default -> INCORRECT_COMMAND;
                };
                write.accept(response);
            }
        } catch (IOException e) {
            if (stop) {
                log("Service to client " + clientNum + " interrupted by the server stop");
            } else {
                log("The following error occurred while serving client " + clientNum + " : "
                        + e.getMessage());
            }
        } finally {
            connections.remove(client);
            log("End of service to client " + clientNum);
        }
    }

    // o comando tax married nbChildren annualSalary: retorna o imposto ou uma mensagem de erro
    private String calculateTax(String[] fields) {
        // 4 campos são exigidos: tax, y ou n, dois inteiros
        if (fields.length != 4 || !fields[1].matches("[yn]")
                || !fields[2].matches("-?\\d{1,9}") || !fields[3].matches("-?\\d{1,9}")) {
            return INCORRECT_CALCULATION;
        }
        try {
            // o cálculo é entregue à camada [business]
            int tax = business.calculateTax(fields[1].equals("y"), Integer.parseInt(fields[2]),
                    Integer.parseInt(fields[3]));
            return String.valueOf(tax);
        } catch (RuntimeException e) {
            // a mensagem da exceção, em uma única linha: o protocolo é feito de linhas de texto
            return e.getMessage().replaceAll("\\R", " ");
        }
    }

    // o log do servidor: cada linha tem um carimbo de data e hora
    private static void log(String message) {
        IO.println(LocalTime.now().format(TIME) + " " + message);
    }
}
  • linhas 24–32: as respostas fixas do protocolo. A resposta ao comando [help], escrita em um bloco de texto, contém quebras de linha: o cliente a receberá como quatro linhas;
  • linhas 43–46: a classe recebe a camada [business] e suas opções por meio do construtor. Ela conhece apenas a interface [ITaxBusiness] da camada [business] e não sabe nada da camada [dao];
  • linhas 49–79: o laço de espera de clientes. É o mesmo do servidor de eco da primeira parte: cada cliente é atendido por uma thread virtual que não é aguardada (linha 62); fechar o serviço de escuta encerra a espera por um cliente (linha 64); em seguida, as conexões ativas são fechadas (linhas 71–73), e o programa espera todos os serviços terminarem antes de encerrar (fechamento do [ExecutorService] na saída do [try]). Nenhuma thread do sistema fica bloqueada por um cliente que está pensando;
  • linha 53: o serviço de escuta é guardado em um campo para que o método [stop] possa fechá-lo;
  • linhas 82–91: o método [stop], chamado pelo hook de saída em outra thread: por isso os campos [listener] e [stop] são declarados como [volatile] (linhas 39 e 41);
  • linhas 94–139: o serviço prestado a um cliente:
    • linhas 100–105: uma lambda que implementa a interface funcional [Consumer<String>], que envia uma resposta ao cliente e também a escreve no log se o eco estiver ativado;
    • linha 107: quando o cliente se conecta, o servidor lhe envia uma mensagem de boas-vindas;
    • linha 110: o laço de leitura de comandos, que para se o cliente fechar a conexão ou se o servidor for encerrado;
    • linha 115: o comando, convertido em minúsculas, é dividido em campos. A expressão regular [\s+] (um ou mais espaços) evita campos vazios causados por vários espaços consecutivos;
    • linhas 116–119: o comando é formado unicamente pela palavra [goodbye]. O servidor responde e sai do laço: a conexão é fechada na saída do [try] com recursos;
    • linhas 121–125: uma expressão [switch] escolhe a resposta com base no primeiro campo: [help] sozinho, um comando que começa com [tax], ou qualquer outro comando. Uma linha vazia recebe a resposta [Command not recognized];
  • linhas 142–157: cálculo do imposto:
    • linhas 144–147: o comando deve ter quatro campos, sendo o segundo [y] ou [n] e os dois últimos números inteiros (de um a nove dígitos, possivelmente precedidos de um sinal de menos: [parseInt] não gerará erro);
    • linhas 150–152: o cálculo é solicitado à camada [business]. Uma única instância de [TaxBusiness] atende todos os clientes, possivelmente ao mesmo tempo, a partir de threads diferentes: isso é possível porque essa classe não modifica nenhum dado depois de construída (sua lista de faixas é somente leitura);
    • linhas 153–156: se a camada [business] lançar uma exceção (por exemplo, por um número negativo de filhos), sua mensagem é devolvida ao cliente. Essa mensagem pode conter quebras de linha: elas são substituídas por espaços ([\R] designa qualquer quebra de linha), porque o protocolo exige uma resposta de uma única linha;
  • linhas 160–162: o log do servidor no console: cada linha é precedida da hora, o que permite ver a sequência dos serviços concorrentes. [IO.println] pode ser chamado sem cuidados especiais por várias threads: suas escritas não entram em conflito.

12.9.4. O cliente do servidor de cálculo do imposto

O cliente reutiliza a interface de console da versão 5, a classe [tax.ui.Dialog], sem modificá-la.

12.9.4.1. A camada [business] do cliente

A camada [ui] se comunica com uma camada [business], da qual conhece apenas a interface [ITaxBusiness] da versão 5, reduzida a um único método: [int calculateTax(boolean married, int nbChildren, int salary)].

Basta, portanto, fornecer-lhe outra implementação dessa interface que, em vez de calcular o imposto, o solicite ao servidor. É a classe [TaxBusinessTcp]:

package tax.client;

import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.net.Socket;

import static java.nio.charset.StandardCharsets.UTF_8;

// a camada [business] do cliente: ela implementa ITaxBusiness delegando o cálculo ao servidor TCP
public class TaxBusinessTcp implements ITaxBusiness, AutoCloseable {

    // a conexão com o servidor, aberta durante toda a vida do objeto
    private final Socket client;
    private final BufferedReader reader;
    private final PrintWriter writer;

    // conexão ao servidor (machine, port)
    public TaxBusinessTcp(String machine, int port) {
        try {
            client = new Socket(machine, port);
            reader = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
            writer = new PrintWriter(client.getOutputStream(), true, UTF_8);
            // o servidor fala primeiro: sua mensagem de boas-vindas é lida (e ignorada)
            readResponse();
        } catch (IOException e) {
            throw new TaxException("Unable to connect to the server (" + machine + ", " + port + ")",
                    e, 21);
        }
    }

    // cálculo do imposto: uma requisição, uma resposta
    @Override
    public int calculateTax(boolean married, int nbChildren, int salary) {
        String response;
        try {
            writer.println("tax " + (married ? "y" : "n") + " " + nbChildren + " " + salary);
            response = readResponse();
        } catch (IOException e) {
            throw new TaxException("Error communicating with the server", e, 22);
        }
        // o servidor retorna o imposto ou uma mensagem de erro
        try {
            return Integer.parseInt(response);
        } catch (NumberFormatException e) {
            throw new TaxException("The server answered: " + response, 23);
        }
    }

    // leitura de uma linha de resposta; null significa que o servidor fechou a conexão
    private String readResponse() throws IOException {
        String response = reader.readLine();
        if (response == null) {
            throw new TaxException("The server has closed the connection", 24);
        }
        return response;
    }

    // fim da conexão: nos despedimos do servidor, se ele ainda estiver lá
    @Override
    public void close() {
        try (client) {
            writer.println("goodbye");
            reader.readLine();
        } catch (IOException e) {
            // a conexão já foi cortada: não há mais nada a fazer
        }
    }
}
  • linha 14: a classe implementa [ITaxBusiness]. Ela também implementa [AutoCloseable]: ela mantém uma conexão de rede, que deve ser fechada;
  • linhas 17–19: a conexão com o servidor e seus fluxos de leitura e escrita. Abrimos uma única conexão, usada para todos os cálculos de uma sessão, em vez de uma conexão por cálculo: isso é mais eficiente, e o servidor vê um cliente por sessão de usuário;
  • linhas 22–33: o construtor se conecta ao servidor e lê sua mensagem de boas-vindas (linha 28). Um erro de conexão é encapsulado em uma [TaxException], a exceção da aplicação, com código 21;
  • linhas 37–51: cálculo do imposto. O comando [tax y 2 60000] é enviado ao servidor (linha 40) e sua resposta é lida. Se a resposta for um número inteiro, ela é o valor do imposto; caso contrário, é uma mensagem de erro do servidor, que é transmitida em uma [TaxException] (linha 49): converter diretamente a resposta em inteiro provocaria, no caso de uma mensagem de erro, uma exceção de conversão que mascararia a verdadeira causa do erro;
  • linhas 54–60: [readLine] devolve [null] quando o servidor fechou a conexão: uma [TaxException] é então lançada;
  • linhas 64–71: o fim da conexão. O cliente se despede do servidor com o comando [goodbye], lê a resposta e depois fecha a conexão ([try (client)]). Se o servidor já tiver encerrado a conexão, a [IOException] resultante é ignorada.

Esta classe usa os métodos bloqueantes de [Socket], como todos os clientes deste capítulo: a interface [ITaxBusiness] da versão 5 é síncrona ([calculateTax] devolve um [int], e não um [CompletableFuture<Integer>]), e para um programa de console que atende um único usuário isso é perfeitamente adequado: a thread principal não tem nada a fazer além de esperar a resposta. Se vários cálculos tivessem de ser feitos em paralelo, [calculateTax]seria chamado a partir de várias threads virtuais (com uma conexão por thread, já que [TaxBusinessTcp] não foi projetada para ser usada por várias threads ao mesmo tempo).

12.9.4.2. O programa principal do cliente

O módulo [tax-client] depende da camada [business] e da camada [ui] da versão 5:

    <dependencies>
        <!-- a interface da camada [business] e a camada [ui] da versão 5 -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-ui</artifactId>
        </dependency>
        <!-- o contêiner de injeção de dependência Spring -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
    </dependencies>

O módulo [tax-ui] da versão 5 contém uma aplicação (sua classe [Main]); no entanto, ele pode ser usado como biblioteca por sua classe pública, [tax.ui.Dialog]. A classe [Main] do cliente é a seguinte:

package tax.client;

import tax.business.ITaxBusiness;
import tax.ui.Dialog;
import org.springframework.context.support.GenericApplicationContext;

// o cliente de console do servidor de cálculo do imposto
// chamada: mvn exec:java [-Dexec.args="machine port"]   (por padrão: localhost 27200)
public class Main {

    public static void main(String[] args) {
        String machine = args.length > 0 ? args[0] : "localhost";
        int port = args.length > 1 ? Integer.parseInt(args[1]) : 27200;

        // o contêiner do Spring é fechado ao sair do try: ele então fecha os objetos AutoCloseable
        // que criou
        try (var context = new GenericApplicationContext()) {
            // a camada [business] agora é um cliente TCP do servidor de cálculo do imposto
            context.registerBean(ITaxBusiness.class, () -> new TaxBusinessTcp(machine, port));
            // inicialização do contêiner: criação da camada [business] e, portanto, conexão ao servidor
            context.refresh();
            ITaxBusiness business = context.getBean(ITaxBusiness.class);
            IO.println("Connected to the tax calculation server (" + machine + ", " + port + ")");
            // a camada [ui] da versão 5, inalterada
            Dialog.run(business);
        } catch (RuntimeException e) {
            // erro de conexão ou de comunicação: exibição da cadeia de exceções
            Dialog.displayError(e);
        }
    }
}
  • linhas 12–13: a máquina e a porta do servidor, passadas como argumentos, com valores padrão;
  • linha 17: o contêiner Spring é declarado em um [try] com recursos. Quando ele é fechado no fim do programa, chama o método [close] dos objetos [AutoCloseable] que criou: a conexão [TaxBusinessTcp] será fechada corretamente;
  • linha 19: a camada [business] registrada no contêiner agora é [TaxBusinessTcp]. Como seu construtor espera dois parâmetros que o contêiner não conhece, uma função de criação lhe é fornecida;
  • linha 21: quando o contêiner inicia, ele cria a camada [business], conectando-se assim ao servidor;
  • linha 25: o diálogo da versão 5, sem alterações. A camada [ui] não sabe que o imposto é calculado por um servidor remoto;
  • linhas 26–29: um erro de conexão ou de comunicação é exibido pelo método [displayError] da versão 5.

12.9.5. Execuções

O servidor é iniciado em uma janela de comando, a partir da pasta [tax-server], com [mvn compile exec:java], estando os módulos da versão 5 instalados como descrito acima. Em outra janela, o cliente é iniciado a partir da pasta [tax-client]:

> mvn compile exec:java
Connected to the tax calculation server (localhost, 27200)
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: x 2 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect Married argument: type y or n
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y two 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect NbChildren argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

O diálogo é exatamente o mesmo da versão 5: ele exibe os valores de validação (4.282 e 2.959 para uma pessoa casada com 2 ou 3 filhos e salário de 60.000 euros; 11.519 para uma pessoa solteira sem filhos) e as mesmas mensagens de erro para entradas incorretas. Essas mensagens são geradas pela camada [ui] do cliente, que valida a entrada antes de solicitar o cálculo: entradas incorretas nunca chegam ao servidor.

Vamos agora iniciar dois clientes, A e B, em duas janelas, com B começando enquanto A ainda está conectado. Cada um faz dois cálculos. Na janela do cliente A:

1
2
3
4
5
6
7
> mvn compile exec:java
Connected to the tax calculation server (localhost, 27200)
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 2 40000
Tax=2854 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Na janela do cliente B:

1
2
3
4
5
6
7
> mvn compile exec:java
Connected to the tax calculation server (localhost, 27200)
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

Para ver as respostas do servidor a comandos incorretos, é necessário um cliente que envie os comandos exatamente como são digitados: o cliente TCP genérico da primeira parte serve perfeitamente. O servidor fala primeiro, o que esse cliente sabe tratar:

> java Internet06.java localhost 27200
Type your commands (bye to stop):
<-- Welcome to the tax calculation server
help
<-- Accepted commands
<-- 1-help
<-- 2-tax married(Y/N) nbChildren annualSalary
<-- 3-goodbye
tax y 2 60000
<-- 4282
TAX N 0 60000
<-- 11519
tax x 2 60000
<-- Incorrect calculation command. Use the help command.
tax y 2
<-- Incorrect calculation command. Use the help command.
tax y -2 60000
<-- nbChildren (-2) must be positive or zero
calculation
<-- Command not recognized. Use the help command.
goodbye
<-- Goodbye...
[the server closed the connection]
  • linha 3: a mensagem de boas-vindas, recebida imediatamente após a conexão;
  • linhas 5–8: a resposta ao comando [help], distribuída em quatro linhas;
  • linhas 11–12: a diferença entre maiúsculas e minúsculas no comando é ignorada;
  • linhas 13–16: dois comandos de cálculo malformados;
  • linhas 17–18: o comando está bem formado, mas a camada [business] rejeita um número negativo de filhos; a mensagem da exceção foi devolvida;
  • linhas 19–20: um comando desconhecido;
  • linhas 21–23: depois do comando [goodbye], o servidor fechou a conexão, e o cliente encerrou sozinho.

O servidor é então encerrado com Ctrl-C enquanto um último cliente ainda está conectado. Esse cliente fez um primeiro cálculo antes do encerramento e enviou sua segunda requisição depois:

1
2
3
4
5
6
7
8
9
> mvn compile exec:java
Connected to the tax calculation server (localhost, 27200)
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Exception chain:
----------------------------------------
tax.entities.TaxException: The server has closed the connection
----------------------------------------

A leitura da resposta devolveu [null]: a camada [business] lançou uma [TaxException], que o programa principal exibiu. Com o servidor parado, um novo cliente não consegue mais se conectar:

> mvn compile exec:java
Oct 03, 2026 7:43:33 PM org.springframework.context.support.GenericApplicationContext refresh
WARNING: Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'tax.business.ITaxBusiness': Instantiation of supplied bean failed
Exception chain:
----------------------------------------
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'tax.business.ITaxBusiness': Instantiation of supplied bean failed
----------------------------------------
tax.entities.TaxException: Unable to connect to the server (localhost, 27200)
----------------------------------------
java.net.ConnectException: Connection refused
----------------------------------------

O construtor de [TaxBusinessTcp] lançou uma [TaxException], causada pela [ConnectException] do socket. Como foi chamado pelo contêiner Spring durante a inicialização, o contêiner o encapsulou em uma [BeanCreationException], no topo da cadeia de exceções. As duas primeiras linhas são um aviso escrito pelo Spring em seu log (na saída de erro, no formato de log padrão do Java): a inicialização do contêiner falhou.

Por fim, eis o log do servidor para todos esses testes:

> mvn compile exec:java
19:42:50 Tax calculation server started on port 27200
19:42:52 Start of service to client 0 (/127.0.0.1:44044)
19:42:52 ---> client 0 : Welcome to the tax calculation server
19:42:54 <--- client 0 : tax y 2 60000
19:42:54 ---> client 0 : 4282
19:42:55 <--- client 0 : tax y 3 60000
19:42:55 ---> client 0 : 2959
19:42:56 <--- client 0 : tax n 0 60000
19:42:56 ---> client 0 : 11519
19:42:58 <--- client 0 : goodbye
19:42:58 ---> client 0 : Goodbye...
19:42:58 End of service to client 0
19:43:00 Start of service to client 1 (/127.0.0.1:54654)
19:43:00 ---> client 1 : Welcome to the tax calculation server
19:43:02 <--- client 1 : tax y 2 60000
19:43:02 ---> client 1 : 4282
19:43:03 Start of service to client 2 (/127.0.0.1:54662)
19:43:03 ---> client 2 : Welcome to the tax calculation server
19:43:05 <--- client 2 : tax y 3 60000
19:43:05 ---> client 2 : 2959
19:43:05 <--- client 1 : tax n 2 40000
19:43:05 ---> client 1 : 2854
19:43:08 <--- client 2 : tax n 0 60000
19:43:08 ---> client 2 : 11519
19:43:08 <--- client 1 : goodbye
19:43:08 ---> client 1 : Goodbye...
19:43:08 End of service to client 1
19:43:11 <--- client 2 : goodbye
19:43:11 ---> client 2 : Goodbye...
19:43:11 End of service to client 2
19:43:13 Start of service to client 3 (/127.0.0.1:45664)
19:43:13 ---> client 3 : Welcome to the tax calculation server
19:43:14 <--- client 3 : help
19:43:14 ---> client 3 : Accepted commands
1-help
2-tax married(Y/N) nbChildren annualSalary
3-goodbye
19:43:15 <--- client 3 : tax y 2 60000
19:43:15 ---> client 3 : 4282
19:43:16 <--- client 3 : TAX N 0 60000
19:43:16 ---> client 3 : 11519
19:43:17 <--- client 3 : tax x 2 60000
19:43:17 ---> client 3 : Incorrect calculation command. Use the help command.
19:43:18 <--- client 3 : tax y 2
19:43:18 ---> client 3 : Incorrect calculation command. Use the help command.
19:43:19 <--- client 3 : tax y -2 60000
19:43:19 ---> client 3 : nbChildren (-2) must be positive or zero
19:43:20 <--- client 3 : calculation
19:43:20 ---> client 3 : Command not recognized. Use the help command.
19:43:21 <--- client 3 : goodbye
19:43:21 ---> client 3 : Goodbye...
19:43:21 End of service to client 3
19:43:25 Start of service to client 4 (/127.0.0.1:43690)
19:43:25 ---> client 4 : Welcome to the tax calculation server
19:43:27 <--- client 4 : tax y 2 60000
19:43:27 ---> client 4 : 4282
19:43:30 Server stop requested
19:43:30 Service to client 4 interrupted by the server stop
19:43:30 End of service to client 4
19:43:30 Server stopped
  • linhas 3–13: o cliente da primeira execução. Com o comando echo, vemos todos os comandos recebidos e todas as respostas enviadas. Observe o comando [goodbye] (linha 11), enviado pelo método [close] de [TaxBusinessTcp] quando o contêiner Spring foi encerrado: a sessão foi fechada corretamente;
  • linhas 14–31: os clientes A (cliente 1) e B (cliente 2). O cliente 2 chegou (linha 18) enquanto o cliente 1 ainda estava sendo atendido, e suas requisições foram tratadas alternadamente, à medida que chegavam: o servidor de fato atende vários clientes simultaneamente;
  • linhas 32–53: a sessão do cliente TCP genérico;
  • linhas 54–61: o último cliente, atendido no momento do encerramento. Ctrl-C fechou o serviço de escuta, o que encerrou a espera por um novo cliente; o servidor fechou a conexão do cliente 4, cuja thread de serviço, que esperava um comando, terminou, e então o servidor se encerrou.

12.9.6. Conclusão

Mais uma vez, pudemos reutilizar código existente sem modificá-lo: as camadas [dao] e [business] da versão 5 no lado do servidor e a camada [ui] no lado do cliente, usadas como bibliotecas Maven. Isso foi possível graças ao uso consistente de interfaces e de injeção de dependência: para implantar a aplicação em duas máquinas, bastou acrescentar uma camada [server] sobre a camada [business] e fornecer à camada [ui] uma implementação diferente de [ITaxBusiness]. Se a versão 1 tivesse reunido o cálculo do imposto e a interação com o usuário no mesmo programa, nada disso seria reutilizável. Observe que a camada [ui] não sabe que um servidor remoto calcula o valor do imposto.

Nosso protocolo caseiro tem, no entanto, seus limites: precisamos escrever o servidor, gerenciar as conexões, analisar os comandos, converter as respostas, e um cliente escrito em outra linguagem precisaria conhecer esse protocolo específico. A versão 9, no próximo capítulo, substituirá o servidor TCP por um serviço web: o protocolo será o HTTP, os dados serão trocados em JSON e o cliente usará [HttpClient].

12.10. Conclusão

Este capítulo introduziu a programação para a Internet em Java, partindo dos fundamentos e avançando até as classes de alto nível:

  • a primeira parte revisou o funcionamento dos protocolos da Internet (IP, TCP, UDP, DNS) e dos protocolos de aplicação textuais (HTTP, SMTP, POP, FTP), depois apresentou as classes [InetAddress] e [NetworkInterface], e as classes [Socket] e [ServerSocket]. Com essas classes, e uma thread virtual por cliente, escrevemos servidores que atendem vários clientes simultaneamente, clientes TCP genéricos e um cliente web que se comunicava em HTTP “manualmente”;
  • a segunda parte apresentou classes especializadas em um protocolo. Para o HTTP, a classe [HttpClient] do Java 11 substitui [URL] e [HttpURLConnection]: ela realiza em poucas instruções o que nosso cliente TCP fazia em cinquenta linhas, trata redirecionamentos, formulários, timeouts, cancelamentos e requisições assíncronas, e foi projetada para ser reutilizada entre requisições; usada com o Jackson, troca objetos no formato JSON. Para o SMTP, a biblioteca Jakarta Mail constrói as mensagens MIME e cuida da comunicação com o servidor;
  • A aplicação de exemplo se tornou uma aplicação cliente/servidor sem nenhuma alteração em suas camadas existentes.

As threads virtuais, vistas no Capítulo 8, encontraram aqui sua principal aplicação: um servidor atende um grande número de clientes com apenas algumas threads do sistema, mantendo a estrutura simples de código de uma thread por cliente. No entanto, escrever um servidor TCP e inventar o próprio protocolo continua sendo exceção: a maioria das aplicações distribuídas hoje se comunica por HTTP, com serviços web que trocam dados JSON. Esse é o assunto do próximo capítulo.