From aef4b37c9aff9616bd58828ae6012d9166bf07e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Sun, 6 Apr 2025 18:36:32 +0300 Subject: [PATCH] docs: add diagrams for event aggregator, event-based asynchronous, event queue, execute around, extension objects --- event-aggregator/README.md | 8 ++++---- .../etc/event-aggregator-sequence-diagram.png | Bin 0 -> 31485 bytes event-based-asynchronous/README.md | 4 ++++ ...vent-based-asynchronous-sequence-diagram.png | Bin 0 -> 32555 bytes event-queue/README.md | 4 ++++ .../etc/event-queue-sequence-diagram.png | Bin 0 -> 46210 bytes execute-around/README.md | 4 ++++ execute-around/etc/execute-around-flowchart.png | Bin 0 -> 27692 bytes extension-objects/README.md | 8 ++++---- .../etc/extension-objects-sequence-diagram.png | Bin 0 -> 32698 bytes 10 files changed, 20 insertions(+), 8 deletions(-) create mode 100644 event-aggregator/etc/event-aggregator-sequence-diagram.png create mode 100644 event-based-asynchronous/etc/event-based-asynchronous-sequence-diagram.png create mode 100644 event-queue/etc/event-queue-sequence-diagram.png create mode 100644 execute-around/etc/execute-around-flowchart.png create mode 100644 extension-objects/etc/extension-objects-sequence-diagram.png diff --git a/event-aggregator/README.md b/event-aggregator/README.md index a052e87c4..063aac502 100644 --- a/event-aggregator/README.md +++ b/event-aggregator/README.md @@ -36,6 +36,10 @@ In Plain Words > Event Aggregator is a design pattern that allows multiple event sources to communicate with event handlers through a central point, rather than having each event source communicate directly with each handler. +Sequence diagram + +![Event Aggregator sequence diagram](./etc/event-aggregator-sequence-diagram.png) + ## Programmatic Example of Event Aggregator Pattern in Java Consider the following example where we use the Event Aggregator to handle multiple events. @@ -161,10 +165,6 @@ The console output after running the example. 21:37:38.739 [main] INFO com.iluwatar.event.aggregator.KingJoffrey -- Received event from the King's Hand: Traitor detected ``` -## Detailed Explanation of Event Aggregator Pattern with Real-World Examples - -![Event Aggregator](./etc/classes.png "Event Aggregator") - ## When to Use the Event Aggregator Pattern in Java Use the Event Aggregator pattern when diff --git a/event-aggregator/etc/event-aggregator-sequence-diagram.png b/event-aggregator/etc/event-aggregator-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..f96fbc427a867a126e4d666ffcc31636ed1f7efa GIT binary patch literal 31485 zcmeFZcUY6l6F*87EQsBsNKq*wO+<)v6chm?3Q7+_kQyM;5+Ni3QBgs9k&Z|aDUljT zsG{^9AhaY%hlEaul#rWqzWw~}Kli_TpXVk|l6_}qXJ&V2_nqDMvw8RMfxf_@^M^P% zI0Ovt>6vhFaML(AI34*9uqj^K_9g5e9_L%YTO1rEk%#x5^0KeR9PXI_IXD6&IXHq| zad7OgNkQ`*9Ddh0I2P?VIMhCJaGZUfihHEN&Uol(Vc-M=a$IGn`8l{aPjGOvQ=IHK zN2n_Y&tGW{4z?uri#wC^Ke?G)|H|d2Wpe*3&FT0jBT~oImMz56^|6Jo1@OL_1JpzQ z=`*Okqx=hx=YKMAXuMEkCp{c}pNhTkaQF04d!c#hFAg?mvsOuQV^Y`1(FqQ&51z;qq`Ld8oIuf}*Ob zs=~GF3fHg8u{q>?{5^f2zL4|ux%>|y|B|EU=;Pq+`rOwQ>M8c8+^6Qd{tN1{oz)J%-$^>EQ!2goj zT!kE*>SwvQ_{D-a{_E?}6`cl=*HW)#Fa8giUreW=TlsIKAe~c(j(yYrWpL5xZ&LV= zee)6cU%~uh$6j;s&>p=oX+7~@`u-}&L$l%jy9B*Y9Gr+#>8DCx{kM64a&f8?|4!oi zf4|u}-qyz-KY3Cy`03_RE)U75sHk42miIH|m~e#b86ua{pv>{-JUo|VCWKe%B<;l;Oc{wt5S zNsO(>y-&1uitl+pwr(KMNlz>oEx42bfH(C;;`USWpr2ep3gZE3J(HKNeXsHUslyLh zDZbt|AYweJ2ELfU2fxb{G`V*2C)WT=GVOvn(a#aEl7^dUOnbx%In}9Gq7yg3dV7FI ze!nm)BO~Luly!T1D`&8DHAJoy<(U(A_U_udixB=Bm!eXo`~B}_9T`?Kx+{_<1=?{o zw71Xluw)!qByZn^ojVK0tF5HDF~PV`dgOht*iIWO$?cRAIaM#cSYBS=kydXvv#%~B zno2t$q&kAf;Bn-%{x7UqtJNU{07FN6HA?z>v;`)WpyFk(NXJ~t-&}~-Et$F{rhCHC z&gu<~oS$-G2>xxetNqhH;32Dns1VyPN{)W@6MV0|IVa}vqYHwGoQ|vcI{qfOI6s

O1fGy!wrrvb;b{c_bkc+!pDJXIXR{*O?rKnOIcive@Hgw<7w<% z`pb(C2YjRqw0|EmXy>o>BA!RH^u_Jq=xluceoFworfYrg++oL!$+zQz6JK@2zVdqS zNVKmRABh{Uv#i^VtSn%7ex+-pJwDlN4;`?4)S7bn^Uik(pX0~plPslKYUO2{i_b(@bOUd_;?w+ClO0&e)C{ZobuMyg2&01l;vLiv~C_OVEPtW@##@c~JG#$-?Zab

0z?&$JRwFX?FxvjqNBqkkRM>s&T(*@ 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 The Event-Based Asynchronous design pattern allows tasks to be executed in the background, notifying the main program via events when completed, thereby enhancing system efficiency and responsiveness without blocking ongoing operations. +Sequence diagram + +![Event-Based Asynchronous sequence diagram](./etc/event-based-asynchronous-sequence-diagram.png) + ## Programmatic Example of Event-Based Asynchronous Pattern in Java Event-Based Asynchronous design pattern allows tasks to be executed in the background, notifying the main program via events when completed, thereby enhancing system efficiency and responsiveness without blocking ongoing operations. diff --git a/event-based-asynchronous/etc/event-based-asynchronous-sequence-diagram.png b/event-based-asynchronous/etc/event-based-asynchronous-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..882975df5c0af68c235aed88d07bd4a924c38725 GIT binary patch literal 32555 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 literal 0 HcmV?d00001 diff --git a/event-queue/README.md b/event-queue/README.md index 8b2991b1d..08d807937 100644 --- a/event-queue/README.md +++ b/event-queue/README.md @@ -35,6 +35,10 @@ Wikipedia says > Message queues (also known as event queues) implement an asynchronous communication pattern between two or more processes/threads whereby the sending and receiving party do not need to interact with the queue at the same time. +Sequence diagram + +![Event Queue sequence diagram](./etc/event-queue-sequence-diagram.png) + ## Programmatic Example of Event Queue Pattern in Java This example demonstrates an application using an event queue system to handle audio playback asynchronously. diff --git a/event-queue/etc/event-queue-sequence-diagram.png b/event-queue/etc/event-queue-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..26e01a79e18e5824a0fb82e6baa419967c717e91 GIT binary patch literal 46210 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 z z&&8ci+iu8tOL`FF_6*Hdm0*_LU>}m7qV-gRpHon$r4~9;VGN|9wnH$lZJf7A5Y$qB z({?#~<_=UXxMK?;7*@C6MrnZ?dw9zvCuc*CJ~U)k#D=~boIS`mD5|<#wBwnxlg4&0 zO_xIct%9a|M`JBbRI^zGL!`f!+vl4%EhyQ<1R5n2^2PI6vKv=zllw6Pp8yvWQMy0S zrPoR(>r+L7O~#X*I+}DYKJ?qK(jO`H4jEpL_t^<6Xjd{aYH|K!kLh&n?7-7XVk6=e zZDA(muabE`iRen~+12ry6f0_Z#{|vHA%`}t7pbfF_YKzZhn-y(fb;Yg@CYvN9g>SY z-6`;1&nWiZQbw#k!hPzyZ$P~Lz8ZYBP8`~V8>B^6=7fHK6xt+#rtX%AbRgAC$+;uc z{{%yih36A*bv|%E?H3OwQRwz0=ka_6xn}BDme+#L;MpdqH>X)}7!m$~W-(&)!FEaU zQ*n|BE1nHIJ!CH_R`_F`U7LR(54rH(HXQmOuLBm^ibP4eisEC$EP(7{WA}UU!#Uzt z1`h=`s26M}ViZ}G#xC++vI_!fcZ=BgX>fw|G&W2kCSYUk@}{RL=5U3cwTCU5ejc@+ z5L4HsTG<=;#l({KA--J+c=!4d`Op&AA>7jiQXay=(Hn znRAI-y3#%oxIFY?2Qy!jHw9fRHE0io(N}klH|TKUjeFv4U>NTE!ZIc%2J8d-tG;<# z(57KeDjQiH2X}SP0{EZdY-!=5q27?(NAdT^#``#z6BEr`AoMVyWbMJXh#9dnfiSvwJ+I zkVW-!c`IuV>q?xT<%TK?Y=D&wcn}vfCca*!ex;_%@(yED_F7BI(UYcOMLs)s*)o1)Ir^Q;&tfV4E~1wYwGrzi@kG z_;O@uZ5wPLp4+@Qvv%G%cn%8!AXC5h=`MMB`H_(i5_{p1#Z;(@(kI$&)xANdh7z*j zvcRb^Wk&^qU&vi}k zu>$eYkupab^N+rKP#ayn;meTRJ6)Vaem_8PV?B|;eysjEaueYipbbAbyWAptil5`z zM-;1zA&w&sWFI;zjQ2j35&`*dFG1JwcTylhED&tp^4n=gh$iC-c3WXgT-s}iv|&QaeaA@smMAQVRdQAT6IJ^) zP+!IuyxB(rrf>s@mcjuaq}<7e9M@9QQVCOb(=iYjR)2Xa;S`nos`5vXYmPhM0dCM1 z@#FZuBGs36*VC^+W$&y;Jyfc#!Ta~z!$}{7`>voT(S)^pY8vZtm!#7wQtZ~W^sRnI zcfH*k+dx{1A`QXDe^FJl@o$4p!iO*bA0$JgPQnLM;C6{o zg4!qHgAXV$)+z08YIrn;AO!d@oStlU!qj$w>T5NO9sVyYV7;gZ8nRya!j+To;lJfa z9uWw?dIEeXx5>OpsLD}&Ktc=wK1?Zc{d`dH1! ztd~RNInqta<=8H9RsFfQ7M Basically it's the pattern where you write a method to do things which are always required, e.g. resource allocation and clean-up, and make the caller pass in "what we want to do with the resource". +Flowchart + +![Execute Around flowchart](./etc/execute-around-flowchart.png) + ## Programmatic Example of Execute Around Pattern in Java The Execute Around Pattern is a design pattern that is widely used in Java programming to manage resource allocation and deallocation. It ensures that important setup and cleanup operations are performed reliably around a core business operation. This pattern is particularly useful for resource management, such as handling files, databases, or network connections in Java applications. diff --git a/execute-around/etc/execute-around-flowchart.png b/execute-around/etc/execute-around-flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..3a9048585f621cfb4e74953aa627fcd1fdff7522 GIT binary patch literal 27692 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]}hH16~ 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 s3{S?-5m@yHgKh7GeHq)$ literal 0 HcmV?d00001 diff --git a/extension-objects/README.md b/extension-objects/README.md index 058fce654..82704008d 100644 --- a/extension-objects/README.md +++ b/extension-objects/README.md @@ -33,6 +33,10 @@ Wikipedia says > In object-oriented computer programming, an extension objects pattern is a design pattern added to an object after the original object was compiled. The modified object is often a class, a prototype or a type. Extension object patterns are features of some object-oriented programming languages. There is no syntactic difference between calling an extension method and calling a method declared in the type definition. +Sequence diagram + +![Extension Objects sequence diagram](./etc/extension-objects-sequence-diagram.png) + ## Programmatic Example of Extension Objects Pattern in Java The Extension Objects pattern allows for the flexible extension of an object's behavior without modifying its structure, by attaching additional objects that can dynamically add new functionality. @@ -143,10 +147,6 @@ This produces the following console output. This example demonstrates how the Extension Objects pattern allows for the flexible extension of an object's behavior without modifying its structure. -## Detailed Explanation of Extension Objects Pattern with Real-World Examples - -![Extension_objects](./etc/extension_obj.png "Extension objects") - ## When to Use the Extension Objects Pattern in Java This pattern is applicable in scenarios where an object's functionality needs to be extended at runtime, avoiding the complications of subclassing. It's particularly useful in systems where object capabilities need to be augmented post-deployment, or where the capabilities might vary significantly across instances. diff --git a/extension-objects/etc/extension-objects-sequence-diagram.png b/extension-objects/etc/extension-objects-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..46850163ab9b33bdee9cdb63484be45ec9973f20 GIT binary patch literal 32698 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 WPhzp2I2-=g_EIn9#fn7?KKvh>rg#4U literal 0 HcmV?d00001