From 25f7bc6fea72017e1b38c022f0fee2b54246532a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Sun, 6 Apr 2025 08:27:22 +0300 Subject: [PATCH] docs: balking, bloc, bridge diagrams --- balking/README.md | 4 ++++ balking/etc/balking-flowchart.png | Bin 0 -> 49015 bytes bloc/README.md | 4 ++++ bloc/etc/bloc-sequence-diagram.png | Bin 0 -> 29876 bytes bridge/README.md | 8 ++++---- bridge/etc/bridge-sequence-diagram.png | Bin 0 -> 26796 bytes 6 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 balking/etc/balking-flowchart.png create mode 100644 bloc/etc/bloc-sequence-diagram.png create mode 100644 bridge/etc/bridge-sequence-diagram.png diff --git a/balking/README.md b/balking/README.md index f659d278b..cdd09cf5b 100644 --- a/balking/README.md +++ b/balking/README.md @@ -29,6 +29,10 @@ Wikipedia says > The balking pattern is a software design pattern that only executes an action on an object when the object is in a particular state. For example, if an object reads ZIP files and a calling method invokes a get method on the object when the ZIP file is not open, the object would "balk" at the request. +Flowchart + +![Balking flowchart](./etc/balking-flowchart.png) + ## Programmatic Example of Balking Pattern in Java This example demonstrates the Balking Pattern in a multithreaded Java application, highlighting state management and concurrency control. The Balking Pattern is exemplified by a washing machine's start button that initiates washing only if the machine is idle. This ensures state management and prevents concurrent issues. diff --git a/balking/etc/balking-flowchart.png b/balking/etc/balking-flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..400a1ce8d3e3a56292b142f49816e6493a0d5fcd GIT binary patch literal 49015 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�ovyVw4eSIMl!2>e1>F>^41^vWB*}n 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

r`kRdJ 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 While not a formalized "Gang of Four" design pattern, Bloc is widely used in state-driven applications. It centralizes state management and propagates state changes to registered observers, following principles of separation of concerns. +### Sequence diagram + +![Bloc sequence diagram](./etc/bloc-sequence-diagram.png) + --- ## Programmatic Example of the Bloc Pattern in Java diff --git a/bloc/etc/bloc-sequence-diagram.png b/bloc/etc/bloc-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..5888639850191b0452606dc6301f87d67255705d GIT binary patch literal 29876 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 iNC4L3|LLgx0m-8Pm#?ws!y)3IdP<4Oi The bridge pattern is a design pattern used in software engineering that is meant to "decouple an abstraction from its implementation so that the two can vary independently" +Sequence diagram + +![Bridge sequence diagram](./etc/bridge-sequence-diagram.png) + ## Programmatic Example of Bridge Pattern in Java Imagine you have a weapon that can have various enchantments, and you need to combine different weapons with different enchantments. How would you handle this? Would you create multiple copies of each weapon, each with a different enchantment, or would you create separate enchantments and apply them to the weapon as needed? The Bridge pattern enables you to do the latter. @@ -203,10 +207,6 @@ The hammer is unwielded. The item's glow fades. ``` -## Bridge Pattern Class Diagram - -![Bridge](./etc/bridge.urm.png "Bridge class diagram") - ## When to Use the Bridge Pattern in Java Consider using the Bridge pattern when: diff --git a/bridge/etc/bridge-sequence-diagram.png b/bridge/etc/bridge-sequence-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..b797827628bc117325e9e6b6b90ba30c0dce1122 GIT binary patch literal 26796 zcmeFZXIoS26E{i+MFd4bMT(%H(v&J41O%ih7HTLey##5Yg@6qa=}kIPMWpwHDk8lL zA%Re&6GG@A2}w?H@BQEVIoJ6B&x;c-R@S_bQ zG;|mm8rm`zCThynv^#gGUkr{Kh8i?9l`*VGc8t_#f#CCFGz@?4 zX=tb|Q9txKwEyPj(EXE3hsmM;=bpCgxM1WPZ0s0cEcj4vHpP_x`R#Pdi%n-p{?9J$;;k9sMB<|CIbc(*Ev8S@O8^{|x4@ znf^(oPF3}!vgH4kP4(nO>v?7x8g&{yEse+iv>Pa9+smEfZQDiGRxkSMrbQ=1X&)I@ zMy)k#-eu3E!G|)?U12=Sa^e~Ti|iW?fj7xCdZ9Fh++#{ir!L@Ts5R2Yj|S4mGI04y zXd`F~g)snk;Na*O0uyb{Owa5q{#rIAV89{}N<;VeCAN;P(b-b!LMi%7Q5zRy8|5c-9U_mM{|EG$s zH|?tf88!8D?Ekh+`^sjw=QbJJ zkE)bph!>1aNJvN|y&xDhkflj1CS*@KE6V(1WcdOC2>hPb&#il~pS_iX3i^D{V(_Tr z9@~*H$J*Vfni-&KSxa1505&isS%EH9kYi0TrbhMA`gyEZVEL|Y-}a0M{z|MnAP*~uKhq>q+AlmV5H*44n7Jo@2z(LCdsUDp9QL11}b$TC@39}b30x4wn z8k%#wztnI@61EB=(n4hT+f9D~+ z27YG(4Gk^g`3Q4D@w>_6Od4fod_&Cq;LwS2@t_qC@bD|Nnr{2uORSzG9beDs+Oh~# z6=-vUS$cuMZc-8Zlg`vxia2c11XPf1U~LtPZb}1oc@zJJon0Q zn0iRDE_T4%{>P$+)aK;LHR-0uUf$mBtT1^qoCGM={%I42x-?eh6zwPIrMKnq-tfpv z_GF}0F>qNS^xK^|)l#jOGfWpJs2k^#t??6tP(jj_IXp#*Sp!w zwdB&08uwu0TcE5%M`iA5mN(}wKpn#_`}QrHAYlTFzuDk){Bp0w%+|_+g$X+L`s=*n2RM~STOosD9yvu)?j*T*L}=ObyN2jgibq z8b+&mXuw?Ut04{YpGE{{N`|UBG<-SU8>tVGxV+i?%Oh6n`llbyKwVHp;!Dvg-Z8@0 zupdIRh#{?HHEVs*Ak)DsbpuwkDmcyn5=g-bN3NW(=PaJIwMPlQ^XZ))i;f3rs}F&( zwR6q)pz%OO4|HjI{b1iZ^r++-Z;5^?$LfQBvK6QAbe#1^FPHAd-{VsqsL<4Vxo|aS zr3GiPWi7Nlscl86f_`_dr}=3Y(=~r3#^Btr_pEPJB{xv`X)dSzfi>l0$IJcUOT?PZ4%8B&JHsvcydan%{$zyW@58l*p z&Jm1Zns>uEbko#x%Z|yw{rq0c9ZtFsuB~0!xfLi8pHZ~Q!*~?TcG$SdGenboBo^E4 zDzK>$B*=<${-&p1V^X3ZM%&0A{l+Cf|ZT?CZtH&4yj_pAU% zu4_i$LbJ$t8`iKRQ;}KlZ2s-*|Wc1&|Q+;?);oqY)R6UKAqoxQ?o9q9dLevz5!UNSN z-JADP^398{pZ@3M4OPEMJux2@V-dKPlv7DO$;OE`A*$9P2lGZ=q|p;Q9TX2C1qB{X z0C~h{r|YZUXsNPV!)PgwOqr!8K$*K&=bSzw=exgyo;Ayh8g*@4aH=2v0&%S5YB>NP zfhfriwws}h9N0l#{XC0x9A()TrkFMKyeufBUDLCerP9>k$u6+7-kLAUi zwtgX_xVJjlS-+~RVI+^L?v3515la!@*6nHY+1zJ{Z$akD)mO`J(S2@>>$qzB6?|?R?@vVHj1pvM(FbKcxI@LG%y3f9UruoHB z*C%#;0Ud+<;eet03>>;2+rljOSsa2VC$qfJJfg45tHJYIt%E%WH%-)zRUUUnDO{a| zyWVqAGiPk@+Dy5+T+MrBuLJq^DDIG_;y{XTL@?g1pg+XX&=dTPwXw8xm)D)!9U8qe z4`!$`xAim++ruP_L=Et0@uV~F^>bssR~6ro|KI>~8r4GT== z&F7!E3t_Io;A5j%zZaCea9MQ>CEVXq(w-PzDZpcg9Nspa#{KT^`q}G{(7X6-$DP`@Qz7F#%r z^vA#N%Vn21VjYOTQucaNW+kTqGfl2>O`ez|&rVxjx)zQ*-t}IVLor;x^l-UW2tV7( z3=e4E^d9nq-#)+EH?0{`&$1kfP{_7JZnD6)if}QG?aNG24q|DgLi~$Yy%HK zhfsb?rM9>=EBo&}C|*5tc%C#7BcCFf{Hw=2Mk4WZ^U1{s>3iL#!kCH~#?jgQ5uW$q zsutpqVBfb^0k#kYH*}VX3CE#yIlkoxqu98ycC8)k3QAXMkvFU3w|X`qLJkX>52 zKlxHOV%mREJ>4(Gu3(4UnYXmj#r25<@8j({oxJUkS=S(0e)_28(pb4}nSxK~s@3c5 z^Wy_v#9v7}+0HyXJl2Yk#81zZ}+ORq$@dq!(Nx8h#CeL)*0!*OAx zG`y){C~jvd?fyj*B!DT&CxLCbb?r&X(wlmlSRG+Lf#-d_+VrD{ao45Xn3+UlQ{a&$ zab9Cq9=^h4Zeb%bh1(QGx_jsWqK=NLK}$&mtn%g^SoSFc34{ytMVEt;F-PIqKGgur z7Hb%?Wzz*wBics~!-^{5iepEcf{R_;V#Ak%Md9GuZO&jYsuI*Eu4EW5-WRAJwnnb* zzjI_q5ZRe*!fp@=F_&a5^DGd>P1()(L(g$9h4rYFSI%ZEELtGfw@<$_1U_cqlPW28 z+xVqQ_$Zc~yBT0Ii9{BWeh)z$EH5?z3XDdKe8Nt<7ED0kOX zzUkiEoOpBzZK2ibZu**}U%1I3rjyhdH>{_|IIP~{@^G$D;8Q3gL$GiKg)2-gi*o2$ zt4wyz=|i?>ZAw{3^BQbfTE&Vc)ee|Ad1Q$ICk#U>ZM1JiFbxo+*CZGVi;1qB`L1)y z9uF#ye6mC22EKp27X(<3EI?nfZ(nc2zRy|?NHOuwL>q=NZ9MTEsMBtq)anmdmM4rX z^lk*dJMqEsn;9^LUCLhBuFJX|JPV%YK!CN1&wZK$BcQ^Z4J*BCg%C2kNTPn}jV@>) zTc!4%!}Ev}H6?InYj#=r6Hp*XGe?5}7GX=OBt>o%vAY^VLzZzPK=w^Z3yA!_EIanJ zRQCN<=>D?A_akVWcz?&Yz}@yY>WZv;V%HNr@c1g%Y_ilO!-lJ&ZHYK?YVT%>bQ!Gh;H*7g-yM1#svLAJK0`_dx{`R76* zuSl=Icix<^>?lvd_R{&E^&``Bz}TJd&v0_yF*M>BzK@T^mTT+Y)qYZo-u@H~4M}wB zJNyVQS8rf0kNVau5wxn%+b^Gb{5oM6fbP|iAq(3{bcGjQcq5^Q*lDztwB-=BDYwsa(M=9p_dh#|S2vqO)jyT^)L_&oQM} zqVT*m{Vo4Uo~!Z>huYBZG;e;gr}yH$v0M~{<7~b-;zc=lYwv}={d#e?)7NY8d7LG^B&z6p z^eySG#CeuST$vJS)24%nW~(wKx6sQzxXZ9XlJ``)=u$bhEZ*a7Oyoh7az7 z9lfn1z{@Dyy2qdTr1_qVKY7+V93gPfS-`sZ5oA*tcErpKv0+N%TIpbpi7nzDU@QJE zJ{v3nIU+oQZD!I(C(Rc!Qi?3yC0nx&G;|elza@pgz=wLv4v$nCA$~dNZ*@+t6~xF= zP_k>w(eSm}U9-MA%UNAHUu8$o^TUx+RWe6JRlso_--Sq#7e3*OuMr5w(Hefowpt zV^9wzrk`a@x9q+^VBU&sDB_0L3K_|Dz#{WLf4?bjykkd3^1(TNZTI=QM{@}q5-ARo zMq!(BeU86+%8J-3)R4c+66zX)MBFtXn7TIp#eH;|eS1+DY@zftix2Hqq5VbLR@MxA zx`&yna)9SPqY^iecgx1iOHmFRkrNPW8Gwn5EqrajT(*!g=rx8b7vxLoLXouP*(>VGOEF>_QXH35E50O)t-i9Vlh1 z%R$Q_eRb#$%!J`-WRanchD)E&WFqc5OV52cibB2#Gg5nU*y~e2;>_-?+3`jl$|@!! zK60r7osY6{Nuz_9mXmgbU`CeVMPgZwDYy-_$w8D_;FHEs09-`|^bYJQ%6U~M?Omda z{N-Ke6z9(qb7l~k!*M-Wtbfs9qI>xV^@}UNz9n(q`&fsMk(L)4H;l?9P4yYNLP5~+ zX`j`6djk9@)i2;#YnUJ38b3TOq_hY&urGYew1oB=j~X5{H7mU<3j2bUXM8P$lkh&D zQ=rnhqM_-Ew$e!7j#aY!_T3{a)OM78%Eka+=-a0xo31uI!$q#ur>9j<9Ln>res(eJ z8~0?;t~&ez=26Jdwx%1n_AQ`@zJB9|eA8KEIrvF>GKlT5KI^U)tlkO4iGhWruL-IC zP@euOKCkF(OAI$n>FeNs%P-z5>_QT;vhl=}?Q|D+xWg0b#Geqlo{FHdjruHz`BU7P zM@7GUN=BTE*X}N4?r8upXBRVlKIvj?u)?6RvknZFDQ^_$oP{2Ya~u*^Pv*Cm`lYAV zdX!pTV|Dq8sXEQGmU+o=4wK1M=f{8JHmO_4Q1K{l*=yl6C-T}2S>nD?<_*iC@9OXj zUMeS(oR#)(FO-!_f#E0_I0McjZPtQZx9@|61vrPyfd-z9+5c3My%1BUsp*0a279j- zCC#{-QDFzZfXDF?6^A8lJ<~x>tAJ82En-RiC$*506=0L6;!WG)9=$e&_|G+DHmSxE{Rz*B56 zt(BB7evu=^c@Ke2_39^jYX zY4I!De*g&7tjQi=5V?_bkwxR(fzrrV2byZDrX8;vebJ8uQkr3TM=nVJmqPsw>Av7C znbDfPbPM7{GI2lI{1Kc1at~w8br~Q$S{FCbg?<#Oi?8Mj^WnY&t0nd^@48}GBoseH z5?=yd?CGa8C4^|irORPm`5dHCk7}-g4bhreI>4zh)eQVPXxwYXGRbS2J}d-%X&UAS zo$y#+o*!IAn(i&%EoyBsbtXomquO(_KFePy8#*%5)PF@BQC*(dan)}$LQMrLI+_NO zU!uH?cv>qr!#`r|V6>&hF_&Zgt8C9useV{)S1A1Bsfpc+cA<@(%hJe?Mv74C|EtLK zn{fCP+FNPNekn6aA2U?*^?vFLzRTmAw*Z-{Ur#Ap=HVeP?zy}q4)c6a=YhBdIeD-> zxY@5+;NgV|802k^vb?6lcF~^yLFrD-Z|2z-pEbjx9CgF>^kT1v5slL%R#cixH$aF7 z2vR?-$s@#7lAJu`!GL%Y)4ul%o7JR#5nOlnVdoBHC@R6R?2}No>P5oKretifO@A^b zdefDjbZo~aLrg_AL8}shoD~C~!CL$hQT7&&(Eioe#VO78c}@NuN3nK7&wIjaSYA|x zqCw#5i^%Pgg3sB(D3V_R*l9OZJcxl`Y8>hUPcU;QZ5_U%=z^knh@ssmvP8`x{qcvg8c1ZfQ!nK(-AH6~8T(6-pAdgPbCR zDo@D>)om!t)L>U5XP-`y_XsqruH0_Iv!5P1_}yCa&ilT~_9ppJUq$VWu@1Eh!YS$V zg4|^%Fm!oKhaIAQ_7w5J?l*A-2Rx7Asm5n&_!I#Y6M^d$l84N+*{svIL#i?w5oSui zKdAmFE=7O_55IqHYJOHsm0X*vr32VdWqk9R2&8ib+XseWgj$gfjta<+)43X(M$1g^`RO)f_ zI~5n@Oo(MR`<={QUm7(KW7AGe9(>m0aUj3zSl8X=QDxh{b1{@q~EC8R;&SyuHRHW7#A?L?3PuB+Xlx4fHlx}Fvw?+KD1~-yU!Cu zpnBY87mFg_eqY{}?IVczsoyh{nVU*CqoOVH#3vOSJw%W?O_=<=Rws@!+QYc1y&9sm z?Yrn-#fSv5+pb>wGwGX;`5!Gu2+vLIDIOeU53s#ALXMKB_k8_q6i+SP+EvmjiXzrY zx+6mNH_j>%qN3HSGxbWA0v8u_flmU;#o#B) zG*q~EJn@F6sYuY{juU54o&8rnLmnvMXsRwhzrXmSAa(P5T64^!iGQkzV%T1aw zAH#UYTc$HV-T!QidAjrC$hvKE-9sj@zt5R@A3C~IruY;hRlPcpZZAnCx? zRu?fT*!494D5a6s+~cP$yzG`vYWk_nz5N)qG?(zeUx8@)8t4G2y46D-8eI~JiiHTC zTzvclUaPh%C=8_hWb&4(`}8_TZD84XU3e_KxUy1jbJF1{@yEBd2RW9F_;;Og*Q6*5 z!)pFBY(aaH6=6P_hO3fifR_M#6;F!Kr6<<~6aryHdW4)|O?e;Fc_a@l?^tH>^Dx$y zX@ip|cdpGIogI{BXIn}u3fdPb8lb<=yOKC_Ll8g-SG$ZqGQ?i$toK1CJqdsLOC1^I zJLAXxx_8IkAA476J+j`oNgj~8W?a4!&9pyafV2VE;H!jqt6n}5`o7u{zJF7OHpsnO zGuMNkuoikS3kqws-%Rnv+dbgz02I~v z4%lA-3MrDcV@thgNed-PDDFq}Q)k#iGvja%_aonPm684xx-(o(A}k`@Zs z9S0iNQ|olo>G!8xT{F(tYYo0Wo!{;wDB^wwp6zeo{@ORC2xs{WrMO(lI;Ctden z?^-ckO^rxWdghhC@WxOZ2C8MwHYJIY+%L$AI8SxYeUoey`a9E@G0R4Is7SU58Nrbg zWFYvshx1<-TiBhG95r2M62AS{G53asim(2^i(S3yG*nmlWntCusp^@((b>hl!Zco% zL;R&JZJ6{A9-pROv-8l2tgTv6p`-W$4 z#D=;GwrIeLn_wN?l7{&V0Yb4Ybeq#4_+3J>4EdV3uf!mFlv}*3)pqf{dOX8)Bev}A zRg9dt-@>|;;7fM#(cF-8bYandWkip55kl^kiHW;8Lr8RP!VE_u!{7%-Tg&5+TK4G% z+zpTI=i|lFbS4j{H;Cv~!PZb|T3VZvr@AE#sE&=49Kh?nxfq65`|U7p!cOQzX9lLt zvv+U1lJHZ(EXOCZ)N%>5=Egq{>k!v1Ood5s`==$r*B zG;!8-S0kY0g|jt5rF4)s?Vr4+5{&^fAhUY{M8>_0+08>Q&Tqhto5`fw88b}~iN8ua zVsYDU>fVLq;43*RN1rW|56J|zz&1~B(k^Qow}?v8sgtV;kp9p!Cz{C%mug^K_0!W< z#TQV9@A!3p@hPW?9o|(R!iS`TIGdTK_va!%q~C`UTu?fD;>i*8JVz$J>k*;nhrL7m zv!Bh{P}27|#EFT+$U*ygNm`W^o&61}6Qi|H14h)uEC)u;C*z3w9Ba2Tm`9I%k%am> z`#kNv4A4p|&Vr?^Pm0e}QXV&frwH%GYg{ulfBO9EYjyuHJ5;*X5Z)7h*AsAPDD78T zl9C=&PRWi!7`+Gt*uVJT{(R&Bx6Qf)mk zI1smNL4aMGo4(R_^~7S5M{JgmT=(1wZK;E;nNdfr;zqOGt7>Y-I|f|`R@L9in^7-h zDh7V`0Emh)J|sztW^3!rC!*OBoaT=$1<>h@aYH}7+a-N(_PWNk7erMx2h0V|4(Qu^ z0!hyY_W9QcHV>Mg7K)`yVol4F@dIool7Q1nM_yka4#}LmE=MnMs!uc#&`%F%#_9G?YwwDsoG353MB{!Z5G;|^q#Zyyc|MvIe>t&QX8h*EV$|w?aeiaIEh`&G? zWlN&Rx^F+*Y}==Syudf&Tp;sc+X!j|+50}BJ_DFj1S-9?gv+s&%U|QTRI{?wMdARu zteE4hw*>cp^=A$#f;1Y5x&}6|P?hPrEVnAJkyL-tm8J%A^UVm0WkO7mTZ8Ll=Fp}U zoZ6o{D%C$GZ1*<-_w}kvDq1b8DsZzda~i)f=$k3BONg=5g4cPqx1kq5ntJthLD=m5bJ^G4~!4>K2rl9C_X~heP>5Q?Ckyyc~3&S3_8j;?pm$5Lu8^XS4N5Un^qaLaEMEcG8}T5)JRtPu}HwiUN1gD z-KFkKVL0Tjpd$8d$qNGVc#mUq0H(LDX@#m{PT1A1)byDT0YQWHnJ}4c91dFDl<&9pkuG3PSm1y>C8_7I+2y z4!etX1?Fr5{G2~^*{G}KzWC4@iaUy~xlCzxFp9S36qlurF`5?+c{bg=0?J?dv7sRC zwV&n`(MW#eJ>5X&T-a1;6%rS57%IeR(WTiZ=DY=ZkxMo3wmIc3p$jsVD8aTx9*Rv^M#ERGV*M7kL1b_mz zg#`WBXcH4m7*F@UjqhUET}-d;+M>&doCln37OL;?{~y{vyYPR{sx9hd#=l`XRJWy` zBC22Pmml925fSk|sjv4JDd^@g;Hp&^h*cVT;deEY+{mdllDeEH*WkzxBzOn7Z!R& z;lFWW52(X_vlAZxJ=wrD=?_aFM5!d*+?AZ>E11ca6ThE^mGXZag3q>m4(NDs!H3!X>zvz_r zy|Oklz%lQ_79_>Lx^~;=jp%jvv+E~2d>fLQ+{c?df)nwD*Pg!YTjN9nEcKS zb#E&x{$9%3D(iYiT_Azc!BnnJG^D{7bGDN1n5zVYsNrbRzi&O%{g)NhsLV;kuRa3( zFDdLJHLz{yeTUYSfBE`IOnrEBCC?ajMz^BPbT(Kd;k1I$#5aHlCE!3C-yV>n>+P-o z3YUgQloyvJAqnsL%UNXqNQL+5R8p9}-op~McYZi00N`t=OPigw^Wh_kM3cJHn|=ko zfd9>2PtpE~y=BxJco3^1vLVP1Ar~BB-DV2&p3`%f?_x+wX$?=8QxYe?bsKdZIIBxj)ZU4H-RJ(ka9gQ zijeUeab{6^I&mJk`(ie=_m(BBuUzVu{SzoE=*#vmv@&ES6Q5 z{wy~uHM*gCE61c@@r2ftno?TwsMGF;M2S(tpo>X*HxzMo-L$VH8{=_tF4JHI_^w^xo*=y(R+2vfQ{KQHO8FjW~LtQMjIV zBIcT8GdUU4r{Yi@S69+)UUZqeYG}ne&@d~IY@bTl443OxnP2T#%*XQIV8n;@jV<}E zh7r4WC0nm#8xilvV7rWy)3H%76YHDz53chl*$ZcY2 z=?MFp;eVjL(=lco-zy*gOZbTf8<>~P1#!5Sx?7yuh@W}qUCU5{eEx_C&JS{4IS(dI;&VIo z?@s6tpAk0HdGidjRo3J_Jq5)v>YLv81%NJ2mxFHQ3}q>ra2}I+nBj@x(Uu#TVqjo^ z{dw9T?r02icCbW>)wU9TwOaB;46192>Y3lQZp4?hGI|4Q18dm=%Ukz7%4bkD;E3ZJ{h%DFnf<}JH@*kgP5B!&~i?*KD4;~1Jq}c+B z${qVp^-vn}PP6%WBc^Nof%W^zenIXL*7g=XwdX@32XuOZ$7;1<&B1oid^dMGaHhjx z7I!>6i_@=`7FOm%3zKkdE7LfF&koiE?5#g3EGZ}yt|Jf4rcH!o*0@G9Z78zw-DzV& zmwofIN2}>vZpsFXs)w|yh#>5FQ&cLXZdHR7Ex1#CwcGA($k}4Y^B&(jeVW9OC#p~_ zete**JFpCoW?k&MQC1*^wiYBTboJCeSf3W}`u*S$56hb%-1@~T^YW@TG!jaP-Jc1+ zwI3By3WnD5=mEe27#M$uAYsh!YiS9qxvX1vPAr^o7uID3?kL^a;Q`hM4c+s%o49B3 z1a)Z8p?WQWr)2=yJL>h^xHe1lJuWizBf!s6NV}G5^jmbaVZ8-AnnK+S-gBPr|)P zdm2P2y6EhTGycPUqKQtD-MX2&Qo9rI;OI#CqQaN&!E|Ryw^#3gO#UbeFXCxX&!yI! z9!?~(I-$LsogRLe{!b>c|>H;7L_XYZ4CiJKlo&)rmSdVo`i&%}+Yg@#hh0in&c!FeFfcm63eyiq-{ zw*<(f_I5bj+~&4W&+6lmWnsYvyEktKbfRLh4nu4KpqH+Q>6W`Qi`q)GY?DDgqH(u7 zn9o$ykJ&L&sbWr&)&fcLZ7O!>W~9a$FBPdN>X+dcc)g$jwmy_*5k$*kxe?g(G!j$= z-Wr3k0w@bMM-vB@@HT79${~FF3Au>n0`>?p0cyFJxGTYh5h??t_OF;2;s|3gY3d5M zv~uN*u{#G-A8R!gT=)|FP>6$KIPLpa8oWE@!M(OW@9@4CJ{vehSp6ca*zBUpILwnY=ob@FQ|@Mg zC218vvZaczv-=qL7Al%>|Dlvg>goGj{yA$l>t*22hc=C0?~}=s34V#(OT(e0o6;VE zQ+i$UkO79WvQE+#Juay_#M9~)qB5NSs(y0mEur!w<4wYpre8DDP%9px-5#nUFMsR) zN8J3Ql=fng%R*!Q9VLn%^T|%?-=24%*zX3qFD^f0CclnNnN38aIx7djsT1{1Y$ zMI;1OORCBUJi6`ohNoV9_d!_G^yQ1c%BO3-t?1Xst8;%HKG$^j*fQA4Q#X3z%lkas zz9+8LVN1u()oUp?v!e{Ra38l-9K=!E|I|Twlvx4;qy;7~O^gTjy^Q zweKP8Es0;yo>B9{Y)&hZW@02!g3ryI@e#n@6*FFL6pukYD#Z_ULyqdG<(97n&o)n# zsky?R^bNPu!}hMJ#wc&sO#9Ai?hvG7dWp-dMSGE1$kPwk4lWJ^k0aB*K{#YDg?l;+ zqi(BBy9A(L+1bIX&(bnf>CZ)C??RZ}l+s+)V9^x;EjOlaYJoX)lS2>m;V+R&X)^Cm z%kM;jl-#xXWpfvrnx_0yYPFl1>OqEwOMIw2nBK^U=k)tK^WGmkFb~7|Y;}4@n7#Jj zEhW#|oRKOF_Gyegd8~y|m*}r|Fa+%A3JQb5quuhx2B(1O6{OhPf9d)N394?6(fLFu z(6Y@9xV|?M1gxHwNQi4d|eapCE_;xUdtc;`e zHO)}whw`QU`>oFWGui^_j1A;!{3_G>J^i2q{^u_5|7RG-&QsOgiy<^ORR0?7u{1xR zD(#Mx+lBA`D1?757mp_~&m8;vZv>oL|3xcR^*(NF^-On9&vw(K+cU7lC&z32E;*U2xD*)suF!#}hO^=Su-crAkFB=aP^M5cPrBij zHIJC%l*fg3c{AOwq4Ia&_E>a2*PFjF{a7aIRGmFJuHW@ylsO!0n^po{^F*Uumy6GP zh6UzR9pYUxe;b%t)T!-!Lp-{4@(t_sSjDFn@p#sW^KGyVOOBh-$7?rdNqwzmmM;)u zI?agwI`>M$0x`Cm;n~%dREBY_&r#254)__h5)ZL_w5mLqu3u^9(@|U)!yPTak zQvLjo9Fd`#L&mRPtDi9uonvDH&}1XeR)R$4ROCE(z5k+*qw7@bs4LGXQ|Khe)qDB# zY=4uD?q?eMM@1ajfPeQyfa4e-k-49*@sCkYrIEMPY2Wza2>*9CS+uAC318G%=RfrO z*M-`eM$pM^gzW$5fQD{_3XtgJX7w!fCKm}|1aPV;MI8@XCnfC_d*x@bN*5}@vTc%A_- zl_>$*^_Nv+a5=M~(N{KYNg$8Orn+$zfsfSl}(=QSp5keWEs_ zi<4VC^xeG?b}yEh>eV&}yC;W+pWZSj-8^Q>RIwb|pt6WbSjxHk9uhIu_B)mRZ>rFS zb|KbfkKwYqki8eTK^1d6E*=q))o{vj+X?a658X{Gs}^c?Jbl+bkc3YG9!p6vV= zG>oQJc=_Y1=pRNZJ28wz$g0(CLTOfPso2Mr+jOV!pDvhsX;aBI{^s8R$Et+RKLAJX zDSz$ZL|Wz>`jKB&tc9b;Ll%`DEyC8n#^y-{cKQUkeAl3&BXJ0-W6<$nJ8zFVtkCnH z0EkH=!D*;pgc%h#xhOd-XA3|1)-q-L{C)scBLIicJ)njH{k`#Fd&jT!QJ!o42g3}e zO47|;&d~LLxiIAF$&o}$ejNZ92qTk zO1#EKJ@AfSHDUO(>W3#5SC%>@tFL>xxVTgmTUf|x#VM*J9IfNzd-64-6AG7?Ke09x zyYKFt<#cdTz=Bt8ybd*p_cb)a#CI#hd9PBy2c1TAa%+XDz!gg~78zuDY(r_ncSw&M-zu__Eevtjg^^KMOuO-457*?jHEzYm2eH zl{%L%TV=Hq5q`HzTi|wm+shl5QvVWQ95!K| zrOAZ1it`ioC~wEsJ-yv%hbdiqCy&jB0@*Yfi)^Q{+R`A$de`)rAYS*7xKTsmx@G$K zr1(9Un0?}!VBVOcO$e`5N+qkp*`xTPe?gUj$@K?Yhg92$k6*{@nDnLY+8X+1idi;V zOvp1qeezvDhqJE=70`cpCNXo(^vLL>At(Y3@oq#NG{>kWSYlg@PtQPr0c*9zJKHNZ zy<4AOFKs-EPEhfi)h;8BW!tX@@gtv3MGmR}j8rzAZitIlPCZQ}kFHSmPNr6%2bVRv z@H@*e{`@gwRtOP_Q6?ug9W5)#p(462OBC@zK2q)E83{_` zE_W{vwh6eaw$TP&>?#zipWV$-rtF}r+&b?oELYGk={S4IsihmAK^|W~A#8Y9gMLY^5dFSTX^E)Q!?==hQzgi!e$9i}M?ax% zli@QMV_zNtO9f{>GvxE%(+gOBYx-j5m9`v4&N3=aKg6eQV*>e=*V%FnXDT`AtFUB|LNS zL$I@7X%j9;#{wySh+wj>^h?9d|z;A8$Wc#LBK0LVG8?tWv6b%H(woXKXwPn>d>^4Lf=F}0B-@_T=6+9Ozc z4M<8>u361os!$_s*|>|=7b-3P+FjZ%%1YQBQZ{FLyyx9>cbPhg&;g1@^-w10g5&I1 z`YRZ}|Buau9I!}uJ_OweL8O1^)KBRP(P6e|l$0+0<(RRjGUdBcWNIxc*+eJ|eoklN zt_RsHfK#FK?9&+_f}WftFJUVq`{?dw3&n0q3WI95@gO(jU)VLt$jJ0o7G(l;pv7gy zNt>wqRDR(T#0GCg3{c=|uaMN*oj}obMhD^Z_OnMkyNl3$8Z<;P^jS9 z@ev=Y{*>kM-rBXd__bMUPAAKc{P>6A8~ms4QK@a*;Tvr}6;^T%t;a5&kQ=tHxK$I> zIg{YW>Zd>A!;FO$p&T}k)Kkt7a|hJ2!M9O$i>~lu7CqxTldh<#NHV~z;%_37*(8E~-^%o+9U5+I0ibploZ@ zfXIo?x=tG)*PaOCQ9{7#AsWFtwITO_3)43P6Wh9cH=UtrFG4*SB1&M0a{1%fJ=Dqh z$uK+PZ0P#nTj@lcaPw_5(?^2FWKx-*Uf}+z<`YgS0w2z!Ecla~iOaKZm2-;Ilh1V) zS#|?(lq6aYd}p8SKAZu(*r=L$yymVM5|Z`t@{ib>U ze`K0nPze5nTBoA%rKHfL$?Get0mJsgy3cgH zGkbeGJ*s9`iE_XmFmlTD%UFP8hT94^`N*a5U>UYi*OeI%X6286vhx+clU-(noCWCI z9|<>-Y+Yw+#PL%Sy(RHU8B}1*Ys!Yg=Y62$2CGFaJDLLcH%?cR`T7kgN6|sXU*Id-wnFozM zCV6!;;S)}-9su8aUN_xDi>7 z;2)saa&n+2x2<8GQ}4W6j}bV}3`W06UADT~?3U=W-rq;U8T-%%O_~Z&^@(u+C;O%0 z*^q_x)@-nbksN#d`d)ux3Z`;oA)z>dY4tTBDLr{Vcx{4U`?7H2tyhs%z2A|rvX9w7Of~H2oVjgHd-J$wgtBh<%c|XHjO6DxNUkqYta2#I;_ceZvPJ|4X zN%Uk%0$T1KDD1r8X(AtWtwe;RK8$O;a@}?JR)J_rG_1@XNaV;@y=?xB?v}hCRG+^b z-`o2n7vL=u>r3n5xI6Lrtnbc*hMM!2(vo_iDgW1NbwrkW_bC~IMVE&Stjxkkx2G%- zmyUHn%*$s7>{+|Qh+$p5ypRTqgWDvmlJxjQc?#j3u%)oLscG*-DhXttUMZ={<+r=W zoWbFzA}aleicLxHHav9sb7o&i-r6(uy{RA?Nr{awiptk~QcF5y0*-<)4ihs~4A9Hof3jSuC+!!}_Ond_{bLQf) zS@4kMjjB6mC)3qG7OSpW*h4Uq{RFoMfRLmN*3V}zU$0Mqe&!vk&rj^f(&fRJTS9x$ z93GiCaI&=V@%*r#+^c>lzyE*QyXvT@yKXH*4I!X_yo8j1N=WzuB2oe(k|IbsfOH8; zH;h;)($b}LOUDpm4c*<+F@Uu6J--3tTlcQJzQ6AJ)?F`uuokn*nMKU#0;#Hk38-*Ma#-`$!LD=nxg>EfdY4GOhEkh%948j14wvli`3UwGD zB8cttMbZf=3u8rV*1_*&uzcwD9^ZMKQ4$LOuU^CkXHc}d%wyCBu}*mejZn1kj5u~@ z_H-12R_DiUCZ1qI6^6emLNviZjxf3E%d*v3xx^X0v(%ka8AOCnvnOOtNkC4yA05~M zY4N)TP9{d8eh(K0*bPB)(YR7_&A8QHMT|&VJx2_TOmX z_i`}*R+ST(5Jl?<_z5}y=-HgN{{;363MRD$w=8V>gWfnMs|DldR&JWoqIPjWXvw75)z)_5O;%QNM!85?06u_AMplpI0VQ^VRm7zlNrQ94Y>$68CnNj| z*WFiE8m;Y_ecl44%29f&)6-|_8?6p;%Dm`8KuqJ!+Rg96pmY^b5$cq|LB(9l?Sisd zaIVDK;p?5YRhEbc3%iRky*2Swe3+7Ke{MdDUH;%v|L-mCOr9L2Bc2HiZe!xBdyTer zX{q!L5LA=Jd+28km?Z)ac7#{!CRFMhZL5v!udGCVn(CSe4EFMD^cAs;PK)=H*K>K0 znJuv2ieA2=tStIXtKa@(?k0i3G^YIBez%I~io0D~b*S$kVlQh{US2-`p8J=STE~&6 z5&GV`ORi(LQS%K8Ho@Pd2^)un_giAvGNG=rZx4c_p(Z6hBF}PL+=M;XM8Boe@;T z$ubCCp*lm|@bXR8WD^N*sq0eypi4$hR%ngbIxl_QsPiC`wPdc;4v`sxEhUBBu1!3Y zU07ICFK#Dy50kktm2#dbY^18e7~%N3*?THegJo(L^J-45r%hi0C0!B5x5s(Ph zvcTO0&ii_Gv)xO)9$}&S)dtSTn^fCrZl!<^D-OdjL9qKfAE#otqC?V6)?E(gl$?pJ zA&(rYC?xLZJt` zxfMkIbRFJCTYu4)mM$|=rmlz$X9jCbwdZm}mC!gS<$=?=JhQIT#ZEEp79fCk5;vN* z2ITPw>bQgLn>$~ecxj+gz|J$$}v~it)J1u zARa_)h{Zi4rDK*5Sti}?9NubFavrhjos&Q_dIg!kLZMEX^(MmKsd*po0_3R)b=QSa#vs|)q6$wGW_ z+rZG?+xpb09Jb8l`l2cNvWjU-6mOu!e(bgFCaQkhR=F%j^n zGuXZS{@ryz;yDjtrL8vSsCDe?3I@Dt$axzE1AbGhw_iC=mXiU5bI78Kd##t|H76@(V0DN+4x~{I4dXxTk zga$!1wP4^S(u)$}GjWd!6kVs3%D>NOHu67byinEP*6_+y3k^{c7lrS!?<&VL_YT`d zJkS_*Oj|TreS(mw>0XBbNR!d~gE@SVaGrXWxhF z5F?mt>SvP4X#&QpjywY+V)GQQgb`~Bv|8;djBa~1cIYbdhUnsj$@zrC&jgt0%?^^5 zd}L8c$*9Y&Sc&a!W~QKB_mo8VVo5(|>gxv{ho5STxPjCx@$51)7aV3!q;jA7F^<}15$tzb ze;?Fa2_0RkNC&yu;$_S29{fGBhi6t|QO{L|ebcAJP+u1p zC8I2F!s`(cDOYRHQ+coZ%6+tX1|)f|GVY~*HOtG$dGqlx>>{6pjit3^$kk42v}5C= zg`}uF9oFtt^{LOtdOe8U%)^U~LsQ5Qg7bUkMo37b}Va>sZ^Dt>b@*!iT;uP`d z`;2mAOcnJW>&-SPDT^Jm4@2;C_GbsH>VYSEGa9goLT)q%{PsyHW@CZHni=Z*No{~` zWik;((fQZWXCYVFkMgf>Gb1MB(uju(L+(w02JDV^!`b$bC*xa>iOTDJZAwO&=7Nb9 z-*jy!$qX_WKm6f7+Nb+Va=iyd@he%Sx#?>!qOW=79!_efS*jEjrQM3(|FbY41q>gi z%J#?0l*}5yx@Clz)g0SwFbTNKMW8d-sp|ij_{}%qo0*gSypU~|{7O7IIr$`PSS*sR zpks!2Ai79!O@zE#j@c9#yU6;!BOe_38b;^elVjUg_L!Y3kppi&mK6S3g;~N&I~ZsP z$VE6f-Il1X8@50njj2pdSGBX>A7?-Td;GDcA$hXyk z7#?!l8sN33NtcV>{epC34T6Ko%A|*!hvwpwhxZYGsTyXUlTFgIk>cDBUU{NLx&WdE zS~qMDD+rHsV~-tk-jk^94>T;1RoK5+AILESWQBaNf9PphY_N@kcOCCu(EQGOR4@o8kOIiSRkCjrHBxCz(&YCKDNL@4o2*@C|z;Ol(_!t)?ztbff0BZR- z+t_lg@x+sxLVs)yn;LMvf-5HfBnU77LpI*KY1*C4;M)JOsEG3=5m z4`*HIyT=~&%^S|Gg%DxK);t6dcC2K+GhWlsItpkL@4yZMxUb57y#aqh{42c4OcLfv z`SNs{fTPt=BuQ1|sO$g;sR;Dnek+&^Nrv~5gyibYZ#AX-E2I2rU$Mu??-aO2{#@ld zG9QYW7h*3lFOpY8ySyGqGdQMH{BI-|M<;k$_#`G>$LJL$nY9;?#4$>%SG|4{cCs(khow@taFv z3>6yRVBjFe265QqHf9F6N)k-_e2#g5MU`1Bcz@(R^^t;u&SECGoOjq0p6w#;mftYt z(c&Zt*SKZh`0Q_P7TH_LAKvtia2q*GNY2kM_@XS#&BGeHH9ES681A8A$9=Ft!PfS) zMJf8v2uJ9T2&e9UjBv18tK&8l=B%W%0xakOIlnV_YI!0Rx6u=x&0cPsO?PE4? z=Sua8b4vt0cc(W18Q7nb_w)m*NKoDIn)ls3x83-8J ze!Gn+iQt@)zI&-khc_5q_b$3_H#=JgoM*HzgLsr3dA6<($)l$;%=ANOKwUwW;^Eo~ zpj31!U%9&(`#!4*CsM>c*W7!fQ+Y3*p=fz>%!%f3-dRmejk{Oxk;TI}=WkQJqv7t1 zE?v15s};J&KiX>Twv=ktIQ#&*j*-2ca_+VR3?K*{HMX`F7xYdK6C`5^nsvm$PGn#4 z&(|W8Lmy)`&{?zV8G4cw;wXQv!>Sas`DkF^t8|JCzVwB z`?ud7Wt+d-#h@8cuOkL3u5J%X9~L0@JWKa$2`1^16CU=+s_E#k5-wiWhG@LqfMd~` zTcM}twkkC@oTb>K(c8DDnX5ys7T;POdC5e~{Ymy(^#!g4mZ_;K`U9=UT!_=Y&*V2p}yt-zRJ*SqmKtRr5(7UFxNdz)+FU6}0@(jDMwL}J? z;Oxds*0%_6AiuuF-MLkIdW+d|*Ud)I@&ys&paey~c#3y#8KH#ZQn+Xqf41OXTQ>TL zJ6r=DULY0dt~qGpsglOxOHilMA}W30u(fa336d9%JFO6%cwl_V2Jf+LvcY{!dMyii z`}{Wg$uY!nWcuG|WHdHbD9AqwZW5Fh7b<6AD$INqbtmc}(t67#r64y|CVp=hvB=qx zW!5@Y!4wZ3A3Us+Htvaa6|isdaNV1mnXETUtplmoFtPJXbc&h}c1lq4sGB)i8U4ly zPS8`@M}|FF&nLC3i^(@EJTW<45~Q-&h814XF7l_yz1we*vlaSSQpBrQponFm6Wmp= zYwBN1HVa&G@*Svfb3L4BwLWxQ-17R!|Ga)XEx~#;=CU_3j@)YT`sIzPz{jH7hC8J~ z%VWfaL4yN4X>T_a!q>%mHPFQv_s&B9;|14Kf(Ni%dn{0C5S>}1?4#GY`GSTIrSGQO zpR!D$7b-6+hXdl%MJP8WGTnxo0@AM_Wwvm|sE46^|5=vtXg%d*h3-;8&OBiXjy2^6Dt1eA z=c5l+l1yUzmBB02m#vmOL>jLJHT>L^dKxfCpe|A9m#YHwmE`n&Aj!kr8s>r=8u}oe zmMc4mk~?d-l4|935tnPHUOMnlbE#}gO1lueX12eU(C35b)N`v95en+**`&9vL2o|L z*C@V`Td{{O7#7mSFGNj8M7$u_j9x;@B?S4QFvd)FJlx#y)PCnyBB9p-ifdoiX`QOV zzx_xef5YCWS(mWveI+s+z*SfyeKQxLd&iNT{TPN1>m?oO+ppD)^!F0L&0DeGi%) zQG>zud%OLPPn06Mt+OaLq?qaPpOG<^)mvI9c>ewAS^$H%L+JKw%*|4*hX5k%Cx@@Unm&9*VbNtC2C7r}ZL ziX=d0s&IuCPc!N`-~mcYKmp3{EVwvo=`hO71zoTq3fX4193qZ;><`G;uCwkCa) z;K?zdV7lUL@Q;Y+;hR5VLeBj%xhG(cKnM`Xbv_E4fjXKRg*TYhzuzoL1<%gT?z-hX zqvA>Jxiy*xN(0f`vCofLg}*ASnG1Xfl7L}lJ^y`9)be`bQm3y&III%+iBPEVaS~4z={L3k6$_;di4fkJc4L1zIQb6^2@a+Dvs^`{kkT?i}a5 zeF5;OesZ}!LpnCJIRRS%)T+QV4%clR=6hpHauhV#R>M_|UPXy5M|$NmWW4o4CMR@p zXtKF{jv^do*bK#7v2N>6UH*;|bkgFd4z~te>x^Trwa0f3vg5oA2wW}#Ei8ZE^t{)p z?*ti_e6|#Z5n@#Yzj)RZv(dnJ>fP(3L%x9F<(;x{!9BJUhE(6T3_AD?gMSVN?g~;J zsvf@{=lR$=m>)_o_{ggL>CKi#V`O}qlbgHtd|`bbJiTJRdsvP=4$z`=gh z#*$d%oQ?`T{_{VrMGl`EO7CleNCG;73=jU9xXIQ_98GY>{{)hSuV#Du8UaH%jp{&z z{x@%*nF+4}#)ZxP7B4u(l>nbD?^uMwEd$=M{bkuzFNvCw1Y13BKdcb2Yn_DuP;qa$ z#Ln_l6mV+Q0cjepGe>d(f(Y>Gh%Z!-|MivY_+guEUtY@o6kX7{#G)CD+UaA_o8=eAkJ|5!2q6jMN$xqobtB(<`|7d0@>FjKS{+W-wtg=k*b%V$M1w)$>ga7~l literal 0 HcmV?d00001