From b901e51c5086768e63a5fbda3f353292c9558af6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Sat, 25 May 2024 22:52:59 +0300 Subject: [PATCH] docs: update execute around --- execute-around/README.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/execute-around/README.md b/execute-around/README.md index 1587a1da5..b24b1ae68 100644 --- a/execute-around/README.md +++ b/execute-around/README.md @@ -23,7 +23,7 @@ Execute Around idiom frees the user from certain actions that should always be e Real-world example -> A class needs to be provided for writing text strings to files. To make it easy for the user, the service class opens and closes the file automatically. The user only has to specify what is written into which file. +> A real-world analogy for the Execute Around pattern can be found in the use of rental cars. When you rent a car, the rental company handles all the setup (cleaning the car, filling it with gas, ensuring it's in good condition) and cleanup (checking the car back in, inspecting it for damage, refueling it if necessary) processes for you. As a customer, you simply use the car for your intended purpose without worrying about the setup and cleanup. This pattern of abstracting away the repetitive tasks around the main operation is similar to the Execute Around pattern in software, where the setup and cleanup of resources are handled by a reusable method, allowing the main logic to be executed seamlessly. In plain words @@ -35,6 +35,8 @@ In plain words **Programmatic Example** +A class needs to be provided for writing text strings to files. To make it easy for the user, the service class opens and closes the file automatically. The user only has to specify what is written into which file. + `SimpleFileWriter` class implements the Execute Around idiom. It takes `FileWriterAction` as a constructor argument allowing the user to specify what gets written into the file. ```java @@ -60,15 +62,18 @@ public class SimpleFileWriter { The following code demonstrates how `SimpleFileWriter` is used. `Scanner` is used to print the file contents after the writing finishes. ```java -// create the file writer and execute the custom action -FileWriterAction writeHello = writer -> writer.write("Gandalf was here"); -new SimpleFileWriter("testfile.txt", writeHello); + public static void main(String[] args) throws IOException { -// print the file contents -try (var scanner = new Scanner(new File("testfile.txt"))) { - while (scanner.hasNextLine()) { - LOGGER.info(scanner.nextLine()); - } + // create the file writer and execute the custom action + FileWriterAction writeHello = writer -> writer.write("Gandalf was here"); + new SimpleFileWriter("testfile.txt", writeHello); + + // print the file contents + try (var scanner = new Scanner(new File("testfile.txt"))) { + while (scanner.hasNextLine()) { + LOGGER.info(scanner.nextLine()); + } + } } ``` @@ -81,10 +86,6 @@ Here's the console output. 21:18:07.199 [main] INFO com.iluwatar.execute.around.App - Gandalf was here ``` -## Class diagram - -![alt text](./etc/execute-around.png "Execute Around") - ## Applicability * Useful in scenarios requiring repetitive setup and cleanup activities, particularly in resource management (e.g., files, network connections, database sessions). @@ -118,4 +119,4 @@ Trade-offs: * [Effective Java](https://amzn.to/4aDdWbs) * [Java Design Patterns: A Hands-On Experience with Real-World Examples](https://amzn.to/3vUGApm) -* [Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions](https://www.amazon.com/gp/product/1937785467/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1937785467&linkCode=as2&tag=javadesignpat-20&linkId=7e4e2fb7a141631491534255252fd08b) +* [Functional Programming in Java](https://amzn.to/3JUIc5Q)