From 596eafd3611e24b3f015b56ba9da3dfac5348050 Mon Sep 17 00:00:00 2001 From: zanarellidev Date: Sat, 22 Aug 2026 12:27:20 -0300 Subject: [PATCH] docs: pt: add localization for polling-publisher, money, delegation patterns Add Brazilian Portuguese (pt) translations for three previously untranslated pattern READMEs, following the existing localization/pt/ convention documented in the wiki (15. Support for multiple languages). Frontmatter and section headers follow the same structure used by the most recently updated existing translation (singleton), keeping code blocks, links, and image references unchanged from the English source. --- localization/pt/delegation/README.md | 157 ++++++++++++++++++++ localization/pt/money/README.md | 131 ++++++++++++++++ localization/pt/polling-publisher/README.md | 119 +++++++++++++++ 3 files changed, 407 insertions(+) create mode 100644 localization/pt/delegation/README.md create mode 100644 localization/pt/money/README.md create mode 100644 localization/pt/polling-publisher/README.md diff --git a/localization/pt/delegation/README.md b/localization/pt/delegation/README.md new file mode 100644 index 000000000000..9f424895891d --- /dev/null +++ b/localization/pt/delegation/README.md @@ -0,0 +1,157 @@ +--- +title: "Delegation Pattern in Java: Mastering Efficient Task Assignment" +shortTitle: Delegation +description: "Explore the Delegation Design Pattern in Java with real-world examples, class diagrams, and its benefits. Learn how to enhance your code flexibility and reuse." +category: Behavioral +language: pt +tag: + - Decoupling + - Delegation + - Object composition +--- + +## Também conhecido como + +* Helper +* Surrogate + +## Propósito + +Permitir que um objeto delegue a responsabilidade por uma tarefa a outro objeto auxiliar. + +## Explicação + +Exemplo do mundo real + +> Em um restaurante, o chef principal delega tarefas aos sous-chefs: um cuida das grelhas, outro das saladas e um terceiro é responsável pelas sobremesas. Cada sous-chef é especializado em sua área, permitindo que o chef principal se concentre na gestão geral da cozinha. Isso reflete o padrão Delegation, no qual um objeto principal delega tarefas específicas a objetos auxiliares, cada um especialista em seu domínio. + +Em outras palavras + +> Delegation é um padrão de design em que um objeto repassa uma tarefa a um objeto auxiliar. + +De acordo com a Wikipédia + +> Em programação orientada a objetos, delegação se refere a avaliar um membro (propriedade ou método) de um objeto (o receptor) no contexto de outro objeto original (o remetente). A delegação pode ser feita explicitamente, passando o objeto remetente para o objeto receptor, o que pode ser feito em qualquer linguagem orientada a objetos; ou implicitamente, pelas regras de busca de membros da linguagem, o que exige suporte da linguagem para esse recurso. + +Diagrama de sequência + +![Delegation sequence diagram](../../../delegation/etc/delegation-sequence-diagram.png) + +## Exemplo Programático + +Vamos considerar um exemplo de impressão. + +Temos uma interface `Printer` e três implementações: `CanonPrinter`, `EpsonPrinter` e `HpPrinter`. + +```java +public interface Printer { + void print(final String message); +} + +@Slf4j +public class CanonPrinter implements Printer { + @Override + public void print(String message) { + LOGGER.info("Canon Printer : {}", message); + } +} + +@Slf4j +public class EpsonPrinter implements Printer { + @Override + public void print(String message) { + LOGGER.info("Epson Printer : {}", message); + } +} + +@Slf4j +public class HpPrinter implements Printer { + @Override + public void print(String message) { + LOGGER.info("HP Printer : {}", message); + } +} +``` + +O `PrinterController` pode ser usado como um `Printer`, delegando qualquer trabalho tratado por essa interface a um objeto que a implemente. + +```java +public class PrinterController implements Printer { + + private final Printer printer; + + public PrinterController(Printer printer) { + this.printer = printer; + } + + @Override + public void print(String message) { + printer.print(message); + } +} +``` + +No código cliente, os controladores de impressora podem imprimir mensagens de formas diferentes, dependendo do objeto para o qual delegam esse trabalho. + +```java +public class App { + + private static final String MESSAGE_TO_PRINT = "hello world"; + + public static void main(String[] args) { + var hpPrinterController = new PrinterController(new HpPrinter()); + var canonPrinterController = new PrinterController(new CanonPrinter()); + var epsonPrinterController = new PrinterController(new EpsonPrinter()); + + hpPrinterController.print(MESSAGE_TO_PRINT); + canonPrinterController.print(MESSAGE_TO_PRINT); + epsonPrinterController.print(MESSAGE_TO_PRINT); + } +} +``` + +Saída do programa: + +``` +HP Printer:hello world +Canon Printer:hello world +Epson Printer:hello world +``` + +## Quando usar o padrão Delegation + +* Quando você deseja passar a responsabilidade de uma classe para outra sem usar herança. +* Para obter reutilização baseada em composição em vez de herança. +* Quando você precisa usar diversas classes auxiliares intercambiáveis em tempo de execução. + +## Aplicações do mundo real do padrão Delegation + +* O pacote java.awt.event do Java, no qual listeners são frequentemente usados para tratar eventos. +* Classes wrapper do Java Collections Framework (java.util.Collections), que delegam a outros objetos de coleção. +* No Spring Framework, a delegação é usada extensivamente no container IoC, no qual beans delegam tarefas a outros beans. + +## Benefícios e desafios do padrão Delegation + +Benefícios: + +* Reduz a criação de subclasses: os objetos podem delegar operações a objetos diferentes e alterá-los em tempo de execução, reduzindo a necessidade de criar subclasses. +* Incentiva a reutilização: a delegação promove a reutilização do código do objeto auxiliar. +* Aumenta a flexibilidade: ao delegar tarefas a objetos auxiliares, é possível alterar o comportamento das suas classes em tempo de execução. + +Desafios: + +* Sobrecarga em tempo de execução: a delegação pode introduzir camadas adicionais de indireção, o que pode resultar em pequenos custos de desempenho. +* Complexidade: o design pode se tornar mais complicado, pois envolve classes e interfaces adicionais para gerenciar a delegação. + +## Padrões relacionados + +* [Composite](https://java-design-patterns.com/patterns/composite/): a delegação pode ser usada dentro de um padrão composite para delegar comportamentos específicos de componentes a componentes filhos. +* [Strategy](https://java-design-patterns.com/patterns/strategy/): a delegação é frequentemente usada no padrão strategy, no qual um objeto de contexto delega tarefas a um objeto de estratégia. +* https://java-design-patterns.com/patterns/proxy/: o padrão proxy é uma forma de delegação em que um objeto proxy controla o acesso a outro objeto, ao qual delega o trabalho. + +## Referências e Créditos + +* [Effective Java](https://amzn.to/4aGE7gX) +* [Head First Design Patterns](https://amzn.to/3J9tuaB) +* [Refactoring: Improving the Design of Existing Code](https://amzn.to/3VOcRsw) +* [Delegate Pattern: Wikipedia ](https://en.wikipedia.org/wiki/Delegation_pattern) diff --git a/localization/pt/money/README.md b/localization/pt/money/README.md new file mode 100644 index 000000000000..278924fb1315 --- /dev/null +++ b/localization/pt/money/README.md @@ -0,0 +1,131 @@ +--- +title: "Money Pattern in Java: Encapsulating Monetary Values with Currency Consistency" +shortTitle: Money +description: "Learn how the Money design pattern in Java ensures currency safety, precision handling, and maintainable financial operations. Explore examples, applicability, and benefits of the pattern." +category: Structural +language: pt +tag: + - Business + - Domain + - Encapsulation + - Immutable +--- + +## Também conhecido como + +* Monetary Value Object + +## Propósito + +Encapsular valores monetários e sua moeda associada em um objeto específico do domínio. + +## Explicação + +Exemplo do mundo real + +> Imagine um sistema de vale-presente on-line, no qual cada vale-presente mantém um saldo específico em uma determinada moeda. Em vez de usar apenas um valor de ponto flutuante para o saldo, o sistema usa um objeto Money para rastrear o valor e a moeda com precisão. Sempre que alguém usa o vale-presente, o saldo é atualizado com cálculos precisos que evitam erros de arredondamento de ponto flutuante, garantindo que a lógica de domínio permaneça consistente e correta. + +Em outras palavras + +> O padrão Money encapsula tanto um valor quanto sua moeda, garantindo que as operações financeiras sejam precisas, consistentes e fáceis de manter. + +De acordo com a Wikipédia + +> O padrão de design Money encapsula um valor monetário e sua moeda, permitindo operações aritméticas e conversões seguras, ao mesmo tempo em que preserva a precisão e a consistência nos cálculos financeiros. + +Mapa mental + +![Money Pattern Mind Map](../../../money/etc/money-mind-map.png) + +Fluxograma + +![Money Pattern Flowchart](../../../money/etc/money-flowchart.png) + +## Exemplo Programático + +Neste exemplo, criamos uma classe `Money` para demonstrar como valores monetários podem ser encapsulados junto com sua moeda. Essa abordagem ajuda a evitar imprecisões de ponto flutuante, garante que as operações aritméticas sejam tratadas de forma consistente e fornece uma maneira clara e centrada no domínio de trabalhar com dinheiro. + +```java +@AllArgsConstructor +@Getter +public class Money { + private double amount; + private String currency; + + public Money(double amnt, String curr) { + this.amount = amnt; + this.currency = curr; + } + + private double roundToTwoDecimals(double value) { + return Math.round(value * 100.0) / 100.0; + } + + public void addMoney(Money moneyToBeAdded) throws CannotAddTwoCurrienciesException { + if (!moneyToBeAdded.getCurrency().equals(this.currency)) { + throw new CannotAddTwoCurrienciesException("You are trying to add two different currencies"); + } + this.amount = roundToTwoDecimals(this.amount + moneyToBeAdded.getAmount()); + } + + public void subtractMoney(Money moneyToBeSubtracted) throws CannotSubtractException { + if (!moneyToBeSubtracted.getCurrency().equals(this.currency)) { + throw new CannotSubtractException("You are trying to subtract two different currencies"); + } else if (moneyToBeSubtracted.getAmount() > this.amount) { + throw new CannotSubtractException("The amount you are trying to subtract is larger than the amount you have"); + } + this.amount = roundToTwoDecimals(this.amount - moneyToBeSubtracted.getAmount()); + } + + public void multiply(int factor) { + if (factor < 0) { + throw new IllegalArgumentException("Factor must be non-negative"); + } + this.amount = roundToTwoDecimals(this.amount * factor); + } + + public void exchangeCurrency(String currencyToChangeTo, double exchangeRate) { + if (exchangeRate < 0) { + throw new IllegalArgumentException("Exchange rate must be non-negative"); + } + this.amount = roundToTwoDecimals(this.amount * exchangeRate); + this.currency = currencyToChangeTo; + } +} +``` + +Ao encapsular toda a lógica relacionada a dinheiro em uma única classe, reduzimos o risco de misturar moedas diferentes, melhoramos a clareza do código-base e facilitamos futuras modificações, como adicionar novas moedas ou refinar as regras de arredondamento. Esse padrão fortalece o modelo de domínio ao tratar o dinheiro como um conceito distinto, e não apenas como mais um valor numérico. + +## Quando usar o padrão Money + +* Quando cálculos financeiros ou manipulações de dinheiro fazem parte da lógica de negócio +* Quando é necessário um tratamento preciso de valores monetários para evitar imprecisões de ponto flutuante +* Quando princípios de domain-driven design e tipagem forte são desejados + +## Aplicações do mundo real do padrão Money + +* A biblioteca JSR 354 (Java Money and Currency) em Java +* Modelos de domínio personalizados em sistemas de e-commerce e contabilidade + +## Benefícios e desafios do padrão Money + +Benefícios + +* Fornece uma representação única e type-safe para valores monetários e moeda +* Incentiva o encapsulamento de operações relacionadas, como adição, subtração e formatação +* Evita erros de ponto flutuante ao usar inteiros ou bibliotecas decimais especializadas + +Desafios + +* Requer classes e infraestrutura adicionais para lidar com conversões e formatação de moeda +* Pode introduzir sobrecarga de desempenho ao realizar um grande número de operações monetárias + +## Padrões relacionados + +* [Value Object](https://java-design-patterns.com/patterns/value-object/): Money é tipicamente um exemplo clássico de value object em domain-driven design. + +## Referências e Créditos + +* [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://amzn.to/3wlDrze) +* [Implementing Domain-Driven Design](https://amzn.to/4dmBjrB) +* [Patterns of Enterprise Application Architecture](https://amzn.to/3WfKBPR) diff --git a/localization/pt/polling-publisher/README.md b/localization/pt/polling-publisher/README.md new file mode 100644 index 000000000000..d9cf98a550b3 --- /dev/null +++ b/localization/pt/polling-publisher/README.md @@ -0,0 +1,119 @@ +--- +title: "Polling Publisher-Subscriber Pattern in Java: Mastering Asynchronous Messaging Elegantly" +shortTitle: Polling Pub/Sub +description: "Learn how to implement a Polling Publisher-Subscriber system in Java using Spring Boot and Kafka. Explore the architecture, real-world analogies, and benefits of asynchronous communication with clean code examples." +category: Architectural +language: pt +tag: + - Spring Boot + - Kafka + - Microservices + - Asynchronous Messaging + - Decoupling +--- + +## Também conhecido como + +* Event-Driven Architecture +* Asynchronous Pub/Sub Pattern +* Message Queue-Based Polling System + +## Propósito + +O padrão Polling Publisher-Subscriber desacopla os produtores de dados dos consumidores ao permitir uma comunicação assíncrona e orientada a mensagens. Um serviço consulta periodicamente (poll) uma fonte de dados e publica mensagens em um message broker (por exemplo, Kafka), que são então consumidas por um ou mais serviços assinantes. + +## Explicação + +### Exemplo do mundo real + +> Uma agência de notícias consulta constantemente as últimas atualizações. Assim que recebe novas informações, ela as publica em diferentes veículos (TV, jornais, aplicativos). Cada veículo consome e exibe as atualizações de forma independente. + +### Em outras palavras + +> Um serviço verifica regularmente se há atualizações (polling) e envia mensagens para o Kafka. Outro serviço escuta o Kafka e processa as mensagens de forma assíncrona. + +### De acordo com a Wikipédia + +> Este padrão se assemelha muito ao [modelo Publish–subscribe](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern), no qual as mensagens são enviadas pelos publicadores e recebidas pelos assinantes sem que eles se conheçam. + +### Fluxo da arquitetura + +``` ++------------+ +--------+ +-------------+ +| Publisher | ---> | Kafka | ---> | Subscriber | ++------------+ +--------+ +-------------+ +``` + +## Exemplo Programático (Spring Boot + Kafka) + +### Serviço Publisher + +- Usa o `@Scheduled` do Spring para consultar dados periodicamente. +- Publica dados em um tópico do Kafka. +- Opcionalmente expõe uma API REST para publicação manual de dados. + +```java +@Scheduled(fixedRate = 5000) +public void pollAndPublish() { + String data = pollingService.getLatestData(); + kafkaTemplate.send("updates-topic", data); +} +``` + +### Serviço Subscriber + +- Escuta um tópico do Kafka usando `@KafkaListener`. +- Processa as mensagens de forma assíncrona. + +```java +@KafkaListener(topics = "updates-topic") +public void processUpdate(String message) { + log.info("Received update: {}", message); + updateProcessor.handle(message); +} +``` + +## Quando usar o padrão Polling Publisher-Subscriber + +Use esse padrão quando: + +* Não é possível o produtor enviar dados em tempo real (push). +* Deseja-se um baixo acoplamento entre produtores e consumidores. +* É necessário processamento de eventos assíncrono e escalável. +* Você está construindo uma arquitetura de microsserviços orientada a eventos. + +## Aplicações do mundo real + +* Painéis de relatórios em tempo real +* Agregadores de health check para sistemas distribuídos +* Processamento de telemetria de IoT +* Sistemas de notificação e alerta + +## Benefícios e desafios do padrão Polling Pub/Sub + +### Benefícios + +* Baixo acoplamento entre serviços +* Arquitetura assíncrona e escalável +* Tolerante a falhas, com persistência de mensagens no Kafka +* Fácil de estender com novos consumidores ou publicadores + +### Desafios + +* O polling introduz latência entre a geração e o consumo dos dados +* Requer o gerenciamento e a configuração do Kafka (ou de outro broker) +* Implantação e infraestrutura ligeiramente mais complexas + +## Padrões relacionados + +* [Observer Pattern](https://java-design-patterns.com/patterns/observer/) +* [Mediator Pattern](https://java-design-patterns.com/patterns/mediator/) +* [Message Queue Pattern](https://java-design-patterns.com/patterns/event-queue/) + +## Referências e Créditos + +* [Apache Kafka Documentation](https://kafka.apache.org/documentation/) +* [Spring Kafka Documentation](https://docs.spring.io/spring-kafka) +* [Spring Scheduled Tasks](https://www.baeldung.com/spring-scheduled-tasks) +* [Spring Kafka Tutorial – Baeldung](https://www.baeldung.com/spring-kafka) +* Inspired by: [iluwatar/java-design-patterns](https://github.com/iluwatar/java-design-patterns)