From cef04c01de43726b7ef6d8c8adabca257a3bdf39 Mon Sep 17 00:00:00 2001 From: Svilen Date: Sun, 23 Jul 2017 14:55:43 +0300 Subject: [PATCH] [Developers] Add article about EventAdmin (#450) Signed-off-by: Svilen Valkanov --- _includes/dev-menu.html | 1 + developers/prerequisites/eventadmin.md | 96 ++++++++++++++++++ .../prerequisites/images/event-admin.png | Bin 0 -> 38131 bytes 3 files changed, 97 insertions(+) create mode 100644 developers/prerequisites/eventadmin.md create mode 100644 developers/prerequisites/images/event-admin.png diff --git a/_includes/dev-menu.html b/_includes/dev-menu.html index 6f1ceabe5..18cf2abeb 100644 --- a/_includes/dev-menu.html +++ b/_includes/dev-menu.html @@ -10,6 +10,7 @@
  • Overview
  • Declarative Services
  • Coding tasks
  • +
  • Evend Admin
  • Tycho
  • diff --git a/developers/prerequisites/eventadmin.md b/developers/prerequisites/eventadmin.md new file mode 100644 index 000000000..93b011dd3 --- /dev/null +++ b/developers/prerequisites/eventadmin.md @@ -0,0 +1,96 @@ +--- +layout: developersguide +title: Event Admin +--- + +{% include base.html %} + +# Event Admin Service + +## Introduction + +In a dynamic environment like OSGi, communication with events has a wide variety of use cases. A lot of core services share information using events, so understanding how to use events in OSGi is fundamental. + +## Basics + +### Publish-Subscribe Pattern + +OSGi events are based on the publish-subscribe messaging pattern. Let's use the definition for the pattern that can be found in the [OSGi Compendium Specification](https://osgi.org/download/r4v42/r4.cmpn.pdf) : *This pattern decouples sources from their handlers by interposing an event channel between them. The publisher posts events to the channel, which identifies which handlers need to be notified and then takes care of the notification process.* + +What is interesting about the OSGi model is that both publishers and subscribers can disappear at any time. A central module to track the handlers availability is needed - the *Event Admin Service*. + +### Event Admin Service + +The *Event Admin Service* (`org.osgi.service.event.EventAdmin`) takes a central place in the communication between *Event Publishers* and subscribers (*Event Listeners*). It is responsible for keeping track of the listeners, and sending events to them. It supports both synchronous and asynchronous sending that will be reviewed in more details in the [section about sending events](#send-events). But let's illustrate that with the following picture: + +![Bundle lifecycle][fig1] + +Fig.1 Event Admin Service (Source: ) + +Before going into more details, let's take a look at the events. + +### Event + +The *Event* interface(`org.osgi.service.event.Event`) encapsulates a single message. It contains: + +- topic - used from the *Event Admin Service* as a filter to dispatch the events only to the listeners that are interested; +- payload - the information that we would like to send. It is represented by a key-value pair. + +## Receive Events + +In order to receive an event through the *Event Admin Service* we have to register a service that implements the `org.osgi.service.event.EventHandler` interface with a property *event.topics* that contains all topics that we are interested in. An example with Declarative Service: + +```xml + + + + + + + + +``` + +```java +package com.example.handler; + +import org.osgi.service.event.Event; +import org.osgi.service.event.EventHandler; +import org.osgi.service.log.LogService; + +public class LogEventHandler implements EventHandler { + + private LogService logService; + + protected void bind(LogService logService) { + this.logService = logService; + } + + @Override + public void handleEvent(Event event) { + logService.log(LogService.LOG_DEBUG, " Recevied event with topic: " + event.getTopic()); + + } + + protected void undbind(LogService logService) { + this.logService = null; + } +} +``` + +You can register a handler for multiple topics by adding the topics to the *event.topics* property (``) or by using wildcard symbol (``). + +## Send Events + +As we have already mentioned, you will need an *Event Admin Service* implementation to send events. In Equinox the service is implemented in the `org.eclipse.equinox.event` bundle. The service contains two methods for sending events: + +- `void postEvent(Event event)` - sends an Event asynchronously; +- `void sendEvent(Event event)` - sends an Event synchronously; + +## Further Reading + + - [*OSGi Service Platform Service Compendium, Release 4, Version 4.2,August 2009*](https://osgi.org/download/r4v42/r4.cmpn.pdf) + - + - + +[fig1]:images/event-admin.png \ No newline at end of file diff --git a/developers/prerequisites/images/event-admin.png b/developers/prerequisites/images/event-admin.png new file mode 100644 index 0000000000000000000000000000000000000000..20b05f4b19d21c76c0e51ae0f5ab876be7660e2e GIT binary patch literal 38131 zcmeFXWl&sQ()BlUS7G)Yn8lh~(3P(ztLc5i)_w zFkzuI9ujXp;b78hn5lI`ONCRKO5z}g1e+`%USTK?^r%Qk?yg4LBA!=rgVxf)gWBs$ z`^^hWmgoKpZBWY3!En89TF`-9d0IGU$31#j*dsshU5l%?Qy~muI%V`<+XI`&4OsSJiS!v4a)*Qc=Jv* znRKY#JGz;f`%HN#Hk>rW(S4dcy9f?R9Ky4RD;Ow*#Gm{fE@)8?{8rgeUPYEWk#G?* zCPkPFsn)v(zbqav>s232*clW16gIzl$xmE2pnPM)53F`fmV~C(wokK)JFO%>J=LDy zvw8q7t&;|*f`xziJgHyOoJ?eYh|bntw>zm|?Zkt+rP9eDsqacshib5YE4I5?p>$3T zb@c|SVJ#Cx8fIq@|8on47CGwV#Lg8u$CichfcGgU*l`#b#($SKa`vPlScESc^j-#+ z(_C`5sJKW@VssP*EoH(Ce1`$q?&h~18|q`q%<0Cz{BoeKa*&7^8e!G`MJPz?JBt}o zC}3_AK)^!_PZ*G8i(}<(2<88UU%5pF{+FXLl=ypCDhE*?82@8k40fbnT^&}Han-J| z96m4mk7UStkq(>kA1GD#Zc$>*T&VMz2n*Ij?RsFazQeoaB5?(=u)#1Hp%MpjI>D}y zLxl!PW56cEvPi>Ni^0`>5LtW;LH0#xj}RLtsM#Q&NjSw|9;df@aGKqyPRJ;MQesG9 zJ#uW&YeCis!50{~`5(%@O@T`_g2V_?y(1eEUbva?_}$B!vMqQb zXwAL&o9`~5n7$bHCLoCYLV%t6q=oSAQsU!xEh=bC3fnl!A26ko>EF?Qylah-j&t6D zeH)%zsF;N!5Q=rTxc>^Tckx>A?kt1gP9S- z{8Pgy)=0M|r51M4_(YHxZLphgi`Xfkg+PzPfx8N>8GRwTJ@B{>b(7}OtAk+;=R6p_ z$MwR*kD?0+Knx&Vk0l!b(tbzOfwK)pr${EJvZGSNAVSzj0Ec4sa;XHBD7jIFVR--4 zGoi2jw)mk#hL}b%0Y@f`3jZ?|eOg11nv4ylK8-LEV1OrB}IPORxxieZ}Gy`T#e3yeySSdVH@L5)VG??}Uro|Y zB1}TIxcgP8JK}@lo3WHi#SUwxsS7EHKF$<+Pq#EEGzk1Q|IJ1s#rxxFCgHIEn(UzS z8qu8ETz8jlmw1)Kd(O{m=It79Qe5Os#k(VOdx->Nr zSu*i5F+&Qfi?eHLMr{)f6DYQORy17Y-0g$;H7nZM6`$sF`TK-^`4xC)JTM{)M`=Z6 z;jQ8sGMzH1G9NRMY13=J(Xwwis(I}D{WING-_(CF%x2rPe!OUPud%X}dEEne>MxkC zU$ctWuGl_ti*`%-MDxTBFC6X_-ida%=;lG!9_l}bd3>7jq2~GoE1epU7>y0~HUk`LodoUU6v>}z=EFR3qXK{}& zLWtZb`nZp-1T0Kk6*MQ_E$UtYUY>BwCXy23Kij2ae@*|Aii*LL!}I(!B-JlDC#4|i zE14oGm!id_UBB}wS|^&kNEnao9j-5xhfC?*^r~F=_Q@8~_8AMOUUL1(ZPAQ9NTrMvP~*M_a0yKoB$?cq=H`vZ*oF_-%H=Ff3(DWP?tQxYjZ z^&?DWs$_6wwqcY$G;X-p8D0hLlqP;pETHEsohlu(4sEz^nE6O;99hGt&nZmX$=b(N zz$V@{Y(00Tj-4+y6(>*Us%_Dp`t3#jMmm}*gE~YTx!$I3%~HxdXINzvbMJa5eaB&h zWC%3$6u@o4?dfjWp0e)++KR=V&v0EjQP8D zhsd>Am0XpYE+eb@^SyzOtshl3JDJCI(d_!|aP3Z4E$S<6mQyGVrfy6|wj#Hbs8`~T z*R}mMA67?iLr*&kZwsG1H#`tLS5^<(Kw4=g+6GILRU7)1yQ5e6SIzC3CtVuGy3R)E z*0E->4ICwPowC(7Qgg*eKaPTkV$=6Jk9?a?vwjaQF96r=0W;7su>J5Nq&UPKfM0jY zwv`|3`;AvNEBYpm^N-qqmH*#+Jb-b9|>nD~L(ZRbHp z@Wzd}FLwE%GG{^SJscke|K--;J=u9SiqMjGq<`5VEjZ`4X;LRrCvSdbKBDOdkF~G7 z@A_fjOcu#F3A1Ph#P2%#HZ8q=*ivpHZX7o=gFnYJ;OgVRm&>RK{BQwHH<7l6o$0Kq znyR&tpp)I|1AH`(=c$%JZXD&vf)X9^|y%|NTe(C)TywHvipkkgRvGQEwm5Sh{>61}nmc{%hbV_)>HO(NP~huoc+!WILZ0 zNr@r5Otca_cfVj!+IfAFyI?d?|J5=!tVNs^lJrom)c0nhbb|3y!>1#uN~wwHhv-$G z+Ux#{k?53}?Jq$3m!`Xar_4yB&m6H4~ikq!4rIvy+xwxZ?IXO2A7YiGu2ogCtxsZ#Qg}`TtPyZo* zeG{g%a&vPMU}g36^knhmWN~z{WM${)=VxW(VCCRoe#KyR^>%PG_F{H$eg6-W|IJ6j z+||^@+R4q@(SiIAUt<$TcQ;{5%0Ghs`};>vH*1Ukk>ud|AG2N!Wc~Anm7Rr+^}oDd zNrnDE1;icgom|XaU0?Z&a0~s#{C~jyN6tU^%2tkUj;~&Du{M=)a5Hy#C3Z9Zqn!xH zf2jY@82@ixN-oysuU7x1X8#ZMzhVEu7h?Tm_`e+SkC*>KU)?N%B*gmPE)zkj+2&Y< zf)az0k@%qI1$~kQZ-guPGH7Wi^CeX5qs&34v}&R_hGZ>8iI(zV@aY*~ztl7P>#j-v z+2Nr#10^}nwVl>PSmdeLcZN=JD@3Xvz+1?R#d=pqsFd_R^||21$l3V#$+(}#KDbLz zu)Q1y7V$gO|84(2@POD43^vNb{0dsc?_yxe3$sTBh5YCP8J-+wftDSS>R6y|kJ!;> z$MUhZ$2K@N;Ec7cnp7i5k_H;fDiDqswMMZ5>y;9gTsc)=NW>5qTmY^1MV(H(+o7K1 zlNyISTndt2b=PLm}TnEpt+i&7*degzh5t#w?o9OPy_4%@# zlxK!6T0ENI7J|LYcVF1W*k0p=m<$G|e=uC|P8Nnr3?@!77Zd6$c~cLPG38fDV$MH- z)a^_mrsAhp<68WRFi5!paz44JC74^d5h;wVyv7;Phr;Z0Ab7)0{+FHTA9k_Ack+MP z$%{$U!j(5`k>=uTV<6@AzN)Ic54Y2V`@ds!mK*wz8jYt*{YO`y>TU(~PoE~zh^gqM!>33G!u_{Vet#u`BX!eA`yZHeE*Es< z*0fNI#2-!m(=dYI=px@=TKT-?KH{3pWf< zFQ^8}oa)!r@bFC7$G<8f_7n3}trqcdq*t|O-v$}z3zTk(2WZ;Nylb}C^u4nz>w$fQ z-zxO<91Bx88dZfqYRTU+xtW>9WndK4&6=!?I-2gP{I=fdnZv-~QM&Vk<|w=nSjJPS zQ}7$9p1hyaSSlXN9j`*SK^nc-X{C&t)Q}3;Z;Pudw)C{WQz4`(Nip@ z>ukd2Pzt2JJgXr9eh&%IK3%ETjM^e;zbj#cxRuAd*{kZ7sUP!}i5dzkuDWld9wmH< znmuV=*Hlp~j*N6EGcO0I?q`Wej0KzoxYO;|JWdoF9-Io__S%^j(24BT8o~S#&W8sr zV&%#7QBUblWa5%LjeujznnK3sZvmd7xvrTWR}p2lgSSU9=ps`i4{yF4WleNViZfGf z6+Mw^oaz>raT|6N<8?jM`GC@-=2TgMWyw`K1v61z0f%wEbF}q2su1rpnVTui^|Fv9 zejnn?b;z@CmPL=;M9H1yi|Paj{cmuH%^}tlw;Y|MCj5z07&wP?4udS;N2AUasyt`% zfTPr@qor2I65VQ`4)eW9p3PK6nt<(v*y{4rn3CM={nY!p5ywt^X)=85g5)ZLa+IG` z)KpeeOpNf?hlO@L8IOp4G~=SC(&WOH{|r@|Feu+h+pzb|A7Q94HsQ>?B-Tk+8ye;0 zP$vmEuY{7^557N=q7QUFzDOOVGqO&Z272be<}Q(u%-~WzQw9)iV=uDugKZ#wxJ%)6_d`(EI)p6Jx*qx zHLT9?lend3)F8veC#FDOkoh$>p&7Ha6|Cu;{dc_PBEc=H>b5EB#5zv=Z~>8t)P)BlfsDkgz>A*p7s zt^GP-)=+IAjC`Kk{x~L=lcKzF%TxcL#<_dRbHgC--&8bw!QEfo^>gq61@{ZXr-ww= z;qF=GPYn}n`KY_Dbkz)>vOo4I_e;Zqa2az{qC4vR2&_4iHplAdeT(Y6>k|i)cVoCY zu(9(w23I(Wa!CtJr(`w|U<|4?D|OlffD6asGap8*b9+v2OP+&a-sd?Nyk$l6JYT{N z>7yI0>se?F%C4%=K!6d+neaNyZjL{3(B#Y+oSA*!wSH_HiQSpDuxA^Y!L~Hx zXK?wXV)cgYKA;aj#_L^^N~nfPs5SdMzG>$zc=ByNESfPt@^awY8gu$;+L3pK9Hzpz z6{M#=!~{-YD9x`X>}BzAJK+&|Sa5qQBE@M^gjuU$%~@lXw&ynwzoAWhGsfl-(K?tF z_ZI6i>X%R))zlgUX&7W*X9sbJ>mteyJF$l#jfZ(S(x*@?%#BN*$z(r~*yU}Im%jm1 zL5#N_ONtyW9_~Abl;utJwfEmhc-$~h?cQ;a^ae#M$OB@ zQ!0vD4Z-ca#60cBu6*D7-!dC5o?JlgVHfP_?!7Cae?rUmtZWh5h|QceJ9I4M)P8~^OYP*zeRt(#Y_g^Pz*y7DZPl#x;Fas?6! zcXbu^et7VRU9d$$TD7uUp4x80@pmXE@6pVssIpt3_1R8kH+51O5rZ+75)1Q`*^WaV zgM+B~5KZ@w&^phA`w83_H_%T)^ak_d7(>~P46{Q*MH0F-Co?vweN1wMWSNvo)> zHz@w+)tv^9?b12K|3H={Y=SimGT2a3qJ@itSJwB?%D~HNNHRX+y1zquyN8b_;MdYu z)NDn-l3{Fz1&KYa#(|I(`Z3aq2syV`Skh4#l~%;3B4qh)-ty}^13VDISWpJsR|pR> z>|;R$`*E8glkU{K_DAxv@?7aORAoOy;pPZvfisAJm~z1{32I7T^e-M9Y7=j;f@i`a z6S%lD4TuclACK#lWt6l=yS~0K#~<~{3&K+kKn(05ylsyk%{PSLC{HE$VT}?Ni9=I1)`qjyzi;? zQ7$3OZ8<iQ9PFGpJ}4f=G(D;!a!W{V|bLE8Q2| z*6|w-Nh`f+D_k<%lCaV?nYkz9NGP2w)X`HMJ8;Pu#Et`@FYhwXtU!6L>9tZL*u-Rs zhCXTab?7~Hb1xP0>u3H?dI#F`%>hoj@XbaY$o^sWaWiN7d=D=}8Nqcf$#6%Jfn1c< ze#vZjADH$_ZraTiFxAh+@n<(o77K2=XmHB|f5BgWu%cixS%jc`+0rkMyfiIiz`DOb zj4kjyA0i44iV)u@4)2vh4-Sk@GX6#{GqjdGG)6q6knsVEwu~l*h%wrg?>0Lad@{8+ zvOGL>1vj{0^wJUR=Z^6r3fiD(fExHrnf^5f6} z1(lu*17y4;bSeZW$64e1ga9H$!`Wc?*)`awxij#SUO1Y$=?TY=+Oa0gX8pB3wgYrQ ziROm@tw*-QF=O(eHgfXLUXx_LyR&{*I@+p6}zIm4LRl@>Z)b$wce66BsQzjt& z>v5Kj^ZV@PXu@cF@3-jW*U?X?pL$Q)wBIocN2X+4%19g8`sjQ++q+s#Ab!qX7 zE-YvyzU(07q>umNRU^`SNVNY`q^pbTuCW*Vp`4lX6*t>+jb)&v0 z&+*d@(EX?7BDs*+#wQ;gd?t{q7MiO(X_Wc83$m|g$HseWA-G=Oo!1$`sNyF_P(&- zMt>(~(UWkhk(8d(9{Wwh=K4GHg|COD7o#U?s&qywK>Bk!weRo3LV@2+vNOUxjrw7a z9pH~E3Tv&j;`Yl~o2%KiBgY=?7wJ&TBG+ZW*gG@7MLvPE8TLcd9WV$7icmqZLf>lPwqV6?agMiYAcMiTiGYkVkuj=HXwC zNjJXc3VoH)bM#6|W~9jN^#boorMx9EbU*Bcq*Qt-%H)2A+d0Kxsb)t5XQ*E2DK}dc z&#cmLkF6D%mrWI^Gvc29JYanGk;sS4fBvMSje8V}Z)BX>9{_}`9}e?p9{&t^`^=%yb{#q<}!C(o_4g|9X@t6e(X~V7ShHn-_?-q z09*@{KPNkyNo4xLo+3>?c<)R`bAitEO+;yAFP?veyFWAV=$d{Xpq>q>~`W}Y4(W93& za+Ku!t7aFFM&)zXXEl|bLX0^bdZA_F@-X$6J)JxpmJRv`Qmc`97{6*7!n;dIXBr;c z)V{M>GwFT)nC}+=k4ExwdoiEKVR@^U8Q+?G#9910PO;X0&-J<1oyJ)fW*6&gL-v-7 zu@f~Saa8xnjDce;@7-Ext=huJj{YWT#mjDppg@Clc_x}ST+e!%I|@V+;uw!MFKHp) ze}B3L#D4*lJI;JNC9Pf#!NeQD_lh}vuS%MJ{iQMMk&Bz#(4T>QSitsoImzm@8TLhyuLkI znVYIKrJa)w`y`tSsfvf7Srsu{fi?(#FbjH?Bpolban_>?Y(O-(t%O#p{U>;jX2Qjf zlIXJCpH_kla@ugKkqJq*qo-r?EQ_lcXmr+Q&E5dXZ;=g-?}ukmiZGgzC9!ou^FIDA z7gqTRp25M?8xbXS9e1W#v6Z5XW{n71k^JKcJz>k`Tjvfr8mi<;7FvM4*RH=2B z0grw(RP1}{l#QQddb@utzON<5@HR``nD^-_tJobFc+oM+<|6eyyC}=O6&mjk!P=NWzI6~058)oI*rDikM^Lqep$c2 z7!M9$JF_>1ABk^I(jq~=i>+e3p2XgbugD3%X9L}OhoI)%$;3|hxGI7nK5^GEYDn1MyuWD346bywQ zQ5<;&h}Y-ni%yX@SNL}PUe^Z!%GY$ERBmg=;|HU?22Fvd#5+ucuBjn~^fsl#nf18H zbHqu&f+#pX79NyRrG2OiH0Kn_wY3}AFNV0B_9d*L4|1|IN!Gq>$qxjHiZ`$AHY}Sy z-X828thToI65x(awlN^#^%c<#*q9-aGFI$^^OppmM$avA+}Kq#pMN+%*ZI7uA|4wE zLO)pHa39z~uQ2VSN0gxZlQk5+sPM3cadpUx0EP50lt6q>w|o zJO<3p&(G78T8|Ob*=!wMC<8iO& zy4O5hN#EFT80E#5y(`Pd^#wVPjQ6#Uo^E08hi7E-n(^r`%YIe#4FjcQkCynPzaZAT z9QYD-BqT1e#f3#H+*<>fSFLy3q@hMyq17`$4?Cun0C*%<{58tWcLGM=-_t`oCe&P4 zs>|9E3im$pAZ=AL;xk6b!#ZpD*cLX9J{$Kq9#@grOx5MExAn%bZhIHkEG!DB@W-(I zNpX5~Yp-I#TuoKl6&V0|a4|_-RxIz|ToYw$PKmD+1Mb$E zy7YaGOW-2+fCrd<`QOHLpZ6NfvH<*FbNf4~P(k6GKuSMFm#Jz9$YHq?`@LB-KjPY= zC>oQhQW!d5BU`? z)}{Si@FX_=K`6>{CH(xIke5&nx4>EceZO^mb?{HnuOS#*0f(>}ae07?jjTs^Fhir=DFbU6 zL^K1_cQcXD^cG$*Ss=6a+Kl9^&P>KM&V>Ds<-~VQ2d_!oA6(VS*afQHsBI+HVMcyMDXB zhx=ONozgS&eMf23!!~8)ShL(o&X-LrO>NXItt3>u>Ua$#hg;+f)jif6G5@Xo+m<o=o92=q^aN6>^nHGNaj}HJrJ17z(HAAG?+c{3hNOeHQGE-=Atx5gZ z)S_JJg;C91E1*7M%tSRiV1!X(a1kAO6&`&b=Xa8$n?8U=;9iwY!`s$ffYsliwyPE7yL^m*6-o(z3= zySeeb+cx_rj=NZ5ZZo%nH|xN=R<)oYI3haejzIOBApa$?<3XFaz<5t|U!kLL0!z1j zP*~=!Rnqj9v|%+al~K}-dL9=v7!b0JzZ?BIYuT-aWLVftG||`VS+Y20?Y1ZXE_p#6 zRH~}N)GV(j$)Ced@=f&<3ZVnf*X}gK$3@vF1P55W@9(!OlKY+umu6i9?v3RYtV_2{ zOyt~d}{4qnc(T{Ll;v`cE2u9yfv`HM~O5SpC6A)hqtw7`MOl1REo2<<*jB3 z5D$RNvZ%uVO;w=GpjP;-N7F~mxLSzOo+N%Yj}PiIgeXegUU972cy^EUc{y3LsukI@ znvmrro7BwDBA=L!@jhY@<9TvmO@Eqk`l!~MguAPU{hJ1}w1;;*z_U}q@&u)W z*vOpCxNX45mxFZj!I}PQ2_H z72M1G4CbtRW}c0p8{o@d&RrZp7kuFIEw>;LhjV7E-k@u>VQUY%F(ip8r>(%hWVBYW zqWo4{g3S*2ae2I68QY7Gw(FJ(zH0EMO#$e*GXIn2=fj{Iz8b4rJ^@b%y0_FjXY!j- zPCutu;UD2=#;8v^^7zedM`MSJ3G#R{RA1H#m1t+|yH`eS;THjaD-m}2KDiy5+b&b0 z=D+PsBSI;o1_hB{2I0PFaVkccW}&~{h%kA`n%G*0$#0h%QQ-@;Is!h_9&`=w_Pq?j}ajxUam6j z(Y+N?W7tQjfGlZt44VD6Xqh&GWSE2mdyEsIRM>%ks(`t(5rLBk^UxlIqkd2boJolF zXI`B#3f?)#znc=8{YQ8#G#<~t-mE{ul?+_Qev8x)f66(!e(b;>&E(lnAI^+QlF=>C zUsSCDLrcew7vF_{uQk>r0NF(Hm4BrSWUv14uzlSjn#KJ|Ly4LhBqabGaE_Vn##VIM zka+Bqo3Y3-&63%b&oElOt5Gt(>oEu&O1WAK7e>xNUWUfb8~v+foZtACcoxM;dI{8>_g=W*~Jj(Nz z^Rrae&Q33#67{Hu4GEP(avN*2v4yb6qi<$27wV;PG8Leo?YHRWCUKAU-h>+1FAnX58Q+6j3Y5|^2Rdp|Zc zdS=(MeE2VCOSKJFRim}#z>h<4P%?g{eAt?~b)$}36r%pJKe%KxD&uv1YA)`&`9I$f zVh*5CISC;i7y&#xtn6gGaVKe#a9(YJ^(zFj> z?6tsy=}uVA7j7T%9A?y}wG(SnoK z#X2+0Q4q|XOYKu}9Trs%ZpO0g>|t%g#-pOgs9yYiqk9n5~O>XlTqQj$rz zXk^Jm9flG{dev$GDO82mCER>Rl7TNgzjG>(>)jRS1a+q9SVDUFC+AC+*ol@OZ-2w^ ze)wBxS4M@YR`lf_ItHPh{x0Gq4J(2a1<)6q+9(6vWKZcF4;pcOgbT`?he_ia2P7}$ zJiDe*VNaGD6nhYm==3q$bvBOlO;IYMk@51P06r2-d(>YPxAD8{%p%S9Xn|J~IXq*_ ze3uUAMD{pR4OpN4DRUDihy{(gviP;eCCAG`l)$RxkF3Llh3UN3XleG*e0vev5pdir zk)5RL4+K&t)^io+xdfCaql`3|t#upt13m^-RL@(y7vv;x^#B8&-sc_922im(i0jLx zZKYv{Yn2c^3B#`tcbBn7Dl2orQHY?G_FBKT?YS_@Z*tb(RipKL^N@c(cZQf`;oi6*pMAcNKM;I z@49?h%^uMAh}Ayt#|ZM4MZ*&M1jr4{yF8qW)aXj)Y^n*~o|a6$jJf<;Pv6(<9bNG& zc?|yz82N!W>`?EG((I@;Z2STK)4zHZ6#`WFu>~A{rZp*h5n&Xg+C#E6M zox6|_zp7GXdH+c|Y4q957lbu{heOljPO(zrAoE19+{L-n#M5ky(u<7#eRCZ3<%gT< zlGik?fBnh3Mq5#X_auoxvo4?KBOTxyQ2D__!aNf$Yu-hF<>Jfo5RpCVGrhM!!&@Gj zjGCutwEM1Bg(@_6OV$_ZH|A^6oR*`T*uOA{S>Ih)He5-6vVGBdK)wV675E(U z8wr>4v(KlCqC~4aZh`!!^=)3izZ`AQE-|q1h$vf>KRd+gQgbVQJ|FMqeXop(pSGC65L=pzhOAtbuA0Mox*v%0-P$@}xXj zXu)N|sWe8_Ue6UP9DDPyA^xD!@aF(2*p0p*IpkAO!N#+SV(wB=E+>d0&*^WoqaY<$wF+S# zD@YN9!2`FPQd314?{usYQvT{oVqPJitTz8%5}U1ugzF}TV^Q1km*l;Y({0xMbhy|- zUDFrffF%1{uZFKN12TaCm`}m{9$FHah8yYZS|K<0)k^TfwngmQ3^|6kb9w6U+!c^C zj;JxXQ!I83FJaxIOO7caES2{*Ex8sGn!L zaJAO6eRz22bJny#xg!Al*86I1GC=&YMiV*7@Ov>{wRXkb1L{2Lp=)~YmmbWUSdUNJ zF^FK;M$y7SdYh*;5}WyOPVVqZ-=?zB6WF644zO-Sn|Gk}9JO}5Q*|Rgq_PIHQ>>fg zFhlj&+ts;^wc<2)_VP#$f?;dVvX@1r#P_l(A6lxHI%L5ukF?aHZ!NC{`$h}oqV>h4 zSq(sgYDD(wnmnUa;heW!Jr|l;y>3Nj>5V}w-!`4Tu*DK*bASf>>)2? z3Zl}L%i`#nh`=9N@%LQMGrJ!~2lU^~zJxr@1tetJCZ+yq2}Bd2=|cxx2exN)1eVtp;c} zO;*FpljQYNUctlM>NY*&-mHsOKd9j1;2w-ODhTqHezW$vK!JFiF00G-aee#Z6q>x) z>R3EH$`1veQTGQOf3!*!vP$L5HNIfi1b~sFkmfu`fO9&Q%IB);%Xs!TJgW})ZWGNm z((5y`>CEMM?x=IkoL$FQ`Og-5tM>p}gS|j}0WUuTrI-f@5pMqrV?ULjy~MX5(T(rh zfFX|jn>woRGd=Pp)eM&nWz=Ti;>fh3{0DQ}#Z3AE^JOfyn|;6w7*HNPx_Sgu3Luo` zynMN|`FYMVnSXy;y{54s!XbHMwV+DoCiAowf_y#na>jdJ!k;rfbx9vVe*^%6qe++G zZnlAt;;X2uT8E~!CJdUILCzQXi~QrAN$z4G$ibg=i)FWcGrW})JRLs6(2$Yg-~Ku%a0 zH)y`}TWQwp!6AMr$&+WvEwf+=E8sy--{rB;X3xI9yL)BuCRVSU=XC9dNx}B)Bgye> z#$87t3$aVBh1=@;g^~rJ7b-qc-z?F!)!heiuhVl!a(kxGi@~GaScA{g$X)IecsC<* zBS{W{ZRC4RArJ6Kgldp$5Fez(pl{-NN2~xz@ZIPe&bgjG zc=zzc6LCMVt|6KB-kl|r*q}O@xlQU)0BQmXDhL=DW*uSK-DF{>im&jl6wNq;@(gkw zv0naE<*y7jz9v)S2@99?uO?-ew9P7hc~<&yNc)AS97ipn+##rR&z>bMB2JDBBWozS z?9)qXi50p4eV-~0uy8Fhfl-pyhi>d>cpVE$01f3$f!@@;bF!>yV{6&2<`F7FOF!RY zVTh9d#l@h_Ge7q1m*!ZB^SuC}#?*YCla)Zy1#=8<$Ffds-#OG+{c=*sw&-jka?#P% z`hBcuSq9|6@@7}n@EEK5cgJV{t3`l&?19LSbI#Tjod%OQ(z?rujBFKP`wPwui$sHv z8AjQ2>zmf2G1m3T<@it6*j3kS;9HWfzX9+>;o1&)?=yEC5k=EtUHInkxV8okdR{i3 z?&fwq^~-3o0F8KCb!$78dkGIo85$)JmKS;R4j@@)OUzBux#Wx#Jt3_97wkzRk$@A< zEYE4!?YRuY&ODZ2x_}$d!mQx>vs9(8eSxf;btT&VZb{Grs&c(Zdf|)L5SjaJ;W0qv zP9GHbIAhLRmRh1^n?NyAeXNE&xE{gy_+lubiKqP!I^^oPG(e^Xd*AzlbZV#L=%3@%b-GrWZf8Z3ZQUfQlj zEq{SU?oS;o2z|F4K4ij4;|})a#(HWYE^OAoz*H}iM)Z2r9gvPlPxWaA-d9;{&>m%00YM!Xv_H1FN z4W^`bFQzWyE`>;7?-EM6>B-cV;SAsIs9C?)D0;0Jx)^5i6l0irn~XAY8gatoSrdr} zI~K7t8sJs9zdU?Cej`N55D$F6rtdjUzfakDQhe<(A!OZR6SRp&mWwIhxk1EDwsqbh zBCamAV&aWzqT?gf-gsyeX=9dDUcN7S&pU90cL?^hpHa9=9Zoi1lxS{RowK;EIeLF8 z%0KE2P&0y9Jh)!D&Wb`n4Q2}z{OsDow}Z5E64BlqO79^^@-R0GDi#50S-~zN-_f*1 zT_)*-9lS2nb0{Juc_~r}VL|q~4XO%6+$srVskzlxVYkBiye9PNU)>N*Cy0=rd4yT} zSk?laQpP$!W6Ld#Ze{WCR~{oq0mKCX`cDPT56Cxw0*c5u=>g_-p*_468<(SJf%nsC z{oS9goh$Dz%Vl4J^FN*^^$jw=xC{Xtd61n)fl4Htk}|duFMD5Rj^qA01eWl?45M>L$juhf$4{YZsXE?p9{O%dZ9 zvCi=MtxVsxaeUe9yRO9(+r#ksmw<$a?>(lV(*%)i7@_6-@TsIr0Pf|w`UAN6>fmF< zcI`8|h2&0_>#%o`A&wzV!hG|Pr61@%9s%z->eNjNI$LwQ6x-{C5I)c7NVO{^a z7kbkITaI<mv?)kWaAyz8S^S#ZpV=0g~h$zv`OF>%%M`tN#3`2pfJ)Pl3 zqfT9l?`frF_?;XHP(J|edkq6P3$#k2@&DYkfM}IQGch}Tv)F{n&O}k`mg1_&t>Uk`x);v<$Wuz zUJJH=FO@dKZRMZ(UR|m(ZR?F;?3BZH3DH%Bfgy1(;@90`D|4Zw2)H#6XGM^7tMqY3G_pfGW#(cB&~G8sTt+q#HfV-_b4nLYGMh zDP#+8g>>b?Q=&t94n`2i|r7dDTc`!+Nc0&k0XdjS1m9P=9BHwZ{{;c z6^=Elw4YLL7Y8ZFh>G%foHg9YyC4#vh_j=C4%UcOfH>WaUS@rw|DtqxCnQ;k#$G(Sr)WN77T# zkt1kl1Nh6_P89saW@&S?WM|&rJsG6q>&0fL1}hHT0NEc-Q_$E^D%ue1D%N$th`s|P zxdGykHT}sp^^WXWy6d{Enc4K4dm6SGUkhRIowYrAW!eM5utLkRpv7VmG?*HF=f(~Y zoFwl^&Ih>g(|(z6Q@-I{r*yx5BvSy&Kv$f~=3PZ0JGu7SE_O5#9piAGr)5;w?64wr zz=TZd?>X}-VLjN6%X~58o&P-4;hrrW9lGI`Gz8?ejm3)`;bj?g`;u*lxS1M60fpt$ za9ju<2O-`5vJ+JAg(CT#?fHi*8x7AV@OCBbb@>U{p=2w&a5Q}8|5^~+}&g1FmA%&LF zDu!Fhqjwn7bpXP0;VsAg{5WQ2nS&h8V_hu$q{ozeT4WeUBMp*6+Beyb=(Y3(^<487tGj( zv}%Lz7GHGNtlTlu#cu((P{1(nCq!Z5j{_*W=4dR=hgTWx3Hw1m&RG5L^Si|L)buJ| zz%Q;g*ChBR%WGmWA+fgJH|UC<4UY>F0p9OZ;lgLy2UZMjAoE^IwF*ljW8)*OH0X|I zUk8^_Wc9ga#Gxr#^Cv3@fE6?3BHwuq5Z-S6s2cpmDr2#g8<~X4Yv7UKbN@Ja{Zfee zylco?zW-uUl;F=bc%RPSJfW&emR*tUy>IPKAdVHbA$!uVyUUEaS5;}B%pgih4QS?B zRR@lP)$g3M*d?}TJF0%xW3;T`-b^z3X2$CG`F(ub6PuJC(d1j=az#(uaVo;CgMrj~f`Mjw5T{F7u1qP}}4 zS`)kB|K=el@*s$Df~fe+=Mc>u`~^4|a$>QcJP$jQ2T#gS0RO@>V)%m9mJC7W^QvGd zgwGBl?S987yI^Qg*+ziAouyVsF&Y5`fJnX9=23PZ9GA`uE%mC3fNZFa(R@G7(i0tQ zQl)6hEyb+~fIyahvi4fPml@_{wMw?st=vUZ7Ijj^3=*0QSm?wS$YZe>bkcbi*u zRXKy6=O~=y%}epV0a2d12iuzzy8v4>uCa5FcW#er0MoiJ-iIJ8BqSkiSl>*Olso7Y zB#RucQaXSrxOSULl4K_ZKcIT4=@YUKVW)z{1Ajzy_iIQp&X(t7I+FQPXb=hU; zom-`Lv7dqu7!ky4Z#XNZOT^}7(In=rAOWdS}AY;Rho$a@$&(=rc*zhR~`1t?Ht|WF>2paIuo!Ny2(2OTgzII?P2_EM+e7X!uDBLES%FLWMUk08`m1hv5u;+i z6vtJq*&V`e_SyFd>g|B8)RgPqg{-@koO{!DcY~g{J)D=f>lXpbcW&F(4#4C3q5y|` zh%?v!9QY&j!DP1Wq^4Hta=G_pU#D9vBS`pO*5)|HdaV_3H5=;Y9{_r@BK~t_A)k59 zDO99^Gp59RHZjKHa8uWaksLzSgRfJG1L-U0PpDBnE0giv3>tlMtlA=;WCE^L`6l%K z2s8kU7t)K`#iox@`L82tS6qKAm6dpHKD+VPp+~b6@z6iYed$+Flj*7!bBMy($ztwc z3a5M1Vg$_v*7|`n(DY2B)r4~;l-5IHPv)}59KSwg39HisP|Ujf)xR%I)R^_w>ert7 z$=me~p=P5=(&$y`@?uf!=CQB=581z+Y&^~oudTlORp#bJ;l-Ah z?r!tzyS8yAgQn=@Yj8cbUe>#IqjS<^Q52Mg#kiT~YDuX@WtbtYPQpNH; zz=27?-6!piZa@FejBfj$n;rlMc*=TM%}%IajOlo3*>7XF#Y6kb^i5T9yc`sh{+|B6dbg>ys45O7>PzS1y4X0n#kU*?Baqs11acBs z%46*&O!foPZ4o+=j5cdLDP+#O=%x(S=?uaFjvH7*Y?rXqM12chc3KDAJ<#kuUX<6b z7U!sdw=Lo(g4*U61G|5lnJCeypsU>V*SG|r91qJX={sJpRe%1I7xT7MQ|WRSc>1*b z=TgT_R~6=`x1YwnZI5(B6AT#pCfbRUUgeYMK}VVC~Twp0Xio`Qwbqt~dVA2gdc zzjvUmlZM{^vRBrB3O*c=m>shs&T8ovaDDpE zVw0}H;U0%97G>-rAl&Liax+Mhka_WeT>D-wPl&-$6-bRPgId9%r(lQmDCrw4v&tYX zoc{b7sr_Ace|6)1lfTpF=bVEG>4xf-SYE4}T3pqXcQTA|UpFwuUzA6?WTaj_<4pho z*0ImQfg#iSPuN?I6M78b-e8h>`Eb@+?$f|=;s4gaKz8dSv}y$*+xPq+O8$lrZltuW zLk=AD^~LuXnSs}9jyd;U`%B1{SKEoUQ&{Qe56f_@_qET`r)oi>77I_0;JN>5S<+Ux z2KajWlI_Glr8-R=*cHF!jBU!25_lLWjE#%d{@d>vB6s_io{mmUj|p5|o*#)u+|0ME0if@=lRI`AQ!i|k!6lnnTg zU4~vj@9l`{bCHc1wXYIgP0 zm@|*?A!+9ntJg_X_-KWr-~XBF7pbkl?Mt8bu|@%iUbnc_U1i4fg5 zEW)a|>p5nrqb|Wvwz(AgPP?|Xeyb?lLrwMK*i996vo^w*T?|u&Y}e!)j}7@S`6$8N zpn5`kR{M8Ms_zi_#s|`rwiSL$vtK#EBX!WA6D~npc+rDJ{WsqeiY`G|*K*rMugK;k zHy_6(??Xio{h6vQzW?=4zGI}izh<0HyWUz`)^l*StSUuC)x&yu+f|}Dfa)w*JI8Z{tkGxh=-f5Mhrd|)UbKW8madF8cP*^vuVqUtXO z1F>ZL7>m@n?UfQ~<7xra*TvI;v4K0OUGLYxT0omsqgIm%9&sCoP|UBQstmW&J}nY) zXr=#qrq18D`j4wKD%(35))%!slaw2n#8GZ(`pXi`~WlJ7W zPL^BgYPQ=&YM<8N)|2A<&9=w=vwjWyRp8=)T+6K+M_7(Zc>RBGedBlih4Whv!xFsSH*LK2i#d-sl<0)JGZVEgLT)c_Fk`Mwsx@VdDJlT;*N#-MUgn|gaiBB z!U&FSI>^&xi8wYk+!5)7uP^QQlz_Q)McCGFw4>jPyD_q;=`^;PjlnlFiOn(3@{s$i zbhhi$Pd01yqKxYeeSrftz+&s&>NM7OPkP3Gy8Ay4TP2RSI zRU6OG>M>oX$qPW9TpQv2Z`HL}%8$rKl9DQ^qkKho?WzP7zq1U>Q_`M+37ZC9xxa>s zvIRU*&uh0Gr6&71*xv`XF=jCSE$bkygBxr2-q3d|Q%BC8{;L=I{=iiE_Y`3Ca(Q*P znO7}iQ7dy&4Hb%70=9YTNlM5Ld{^4ME1gcrf(vZ}s&V!f-9LY1R8t}j)^=|39wnCZ z&%9Ue9bGJ!Re@57J6NwM}m-_w&f3U zZfv^TTnU$AaAcQ#Yw-s9XxRs<;ZxYxW}>&1vqX3SGQNWIDjHrST0mn9LeL7bU6X?3 zZd{HkQ<1WV3Pt)4hu-f~JIfi2N!?|Px9N5#soAjEO`6%)=~|86!K-2=@Ko%TAdyH+Jl(*zG78>*?L;_=md5PMnbc57#f#yj(CB?_4dI%af}1lXU}0+xLe*kd3s+~`O006z3S_X-GX2oIw?tT z(kabOWs}tKdgQs3KSBH)K&Yz>CyG`fauE5FuvL~=%GoqMV zrB=OF5`j?|;1mAdrCdT z?>6TjH?`PRfnbucapkUa!1;Q7EB0XDP{@)872klHso_hXH@5J~AakKR6;T&R-F@;P zmEuy*4$2^7{eWeq*vYOz@uJ{2rt%#Z6s%fu!wn;Ql3N2Q<8KhP-`7MF?Aupn202{+ z$S{4$o;SPrJQuTzpXsR9ccz4EUx{u*{qB#Sa1ZN^W(SGm#{a>D{Bwvn!?$yIPq1V! zJ`rsEbpF-AKCoUZVP^K4s6a=?C2ITUz0KjhEm0D(XXM6lJ7Im5EP(rR{b*ur{jz4+ zTH6b7nIF!$V;b9PA}8t`>#BQD-JG`+a5r+Nu7&;V<*OuQgy8X2WjCLom5)mb%3mZV zHvEyg{%37c`5D_zFwPU-4Z z3M6V82o(PpaemJUfg2hW764q5Y`0F z{Gg1-{u*82302#YPh7F`0BVQf#|6)S^YdtNT2$`j?=!E)qei7pT~~HIIIE(KJ`EfUvW)z{ZLU$%`P71I7XC5`idC$IT8dRQT&% zzMG{Y+9slbyI|-nk}0ST=F4XX&q~jYbXQkxS@L*r=K}6N+v5d?O6J4Mg+vg9K$)go zOIgUT@Tic*B@padxqA@$9qIdu$0I|JYcI;x0Rn{5j1lT@zPEE$t8h-e-OQ&6hPsrl zhq{#MYVzv_S3wpVEIAMOJV zlaYBJ)!R_J?b3Yc$Hqa6W9tQisr*mIe`0W)2oHMPCD9W?q?8CwY%lI!{WjQWH*aSf ztj(`YSx{zr1!j#gfARGV%_8JS5*M|-f@owmV}1iGxT;-1vwQ)b*3m-oNGzC;~b$meDEDAN-q17ei5?ze_$E-HV2wO*#UgZ|2T?Ez zcy#zGw(NzNh<<)XG_}_qSfVa`n6+-S8|#(DwHT-`;)jmc?MEsErE-o zq1W$bX&n`_ge5AsJWgrOa9K9ki_!>H9ySE=7ZsE-vq1{^sW%4Qk|{O;=G}OLK9cd3yb%z{bHY#_#7) ztNn3Zqfr@XQc-t@0n5Rv@J;1mLlk6e@8@56N`|r)Vdw=Uj?~d5|DgC}!T5gj~8W*q`dtWy=p1j<8 zq>XLFRF8MN2OdvtnPBTqV(z#O?fx&JyNFg}n?2GLF}$Wwi2Xuer~8i0}vl1%PIHi+%Ae zK0B4wd-HazOx+I$!AnJbAlh$U@{*0c10$~;4I{}BPCb{#-Y}z;1~@=VzPAYEPWW_) zg!3+lNPpHjQV5V*8UAip6YD_1cE z!n-j3Zj#X!c>I~Bog8IF)Wet+8(E(l)G1fXK&$-rkPbGNcRF zrKhv=nhTo)<@MbE`Qj}PsG&!h$;j6Y_RL|t>OtD1iYf#I?(rW+QU{l zWh7IHz$*WdDoj2ooRp=Zd1x3cT|{}QC*rW?&+x0dk{pN=qo6QQqUe!-c5!7OCfp$^!7#qHZ-!`m~eT3G}!je9|wHz-&(+E}9?X&2ysX-^B+={+DY{bqVDy`x3VQnS^ zor{N$ugA!36;DWyKT1q4ctsu^+3#1FXWM9#2?QC{Ec<%zJb;!68CNmQ1N!AO4K zPXRgiFUQsnd)#i~U`#%Q6#E|`QWEaSwsX}4KF3e%5tktwTo*C!=HL2{M3^3EJ!{8S zld5q$X8PUkceXW5MhW?i&T_vKo?-?ykk_|}sbwch(+IvE_V@&uye9=kI=26~#)d_fG>kp@PF5cyM%9O1H5Kgro;!+( z_|xa_sP>(d*UI`lXKT_)Tw=vqphz?{SzEo)=6TiGes-(& z*6>v2E8w*q&AtB6bIAFV#lo?tSA~loi^_)kiRjqDOk(BSAvGwuribM@C$7P_d|a9! zJVaVM=^VP5%*mmIn8iZRtjCz7TwfKL{7<1Sb&oN>ns$E$A9@pUG9*9z1NImlg{gB~ z-O%NX>%k5yIOK&WL9PxN-l5Ga)t9cz3Mq+n3#?r3RHxBZOXfHV<%6fWJT8!xN7=Uc zrQBQiP3QtK9siS-{&GkmQJ3EPd7L)2Tz06`+xFx3D{JF(4isUhA<%}t4ll;qEQ)%x znqTZ9GJc*K?aZ#ci}P15-v`3RlF-`2nX9+`kKY{@b+=^lHd(Jy#s+51;M-~6vNxO+ z6lOdxCKp~4?gA>+&I4iU-a3>g>;lBX7d0eI|8}ScfiwIit<*QAjnA)NzR)p<>@nBS z8z=%lN-YDzw3kD5YA!;9F;K>!ro znAC=S@}=P#RQ;5m0wO{9gao;joPsV`H7>$R>$=OPnr)Wr#+%hC;wGX6yoXO`3aLTC zEEcmnus8a;2Fg{uEbxy#l;&M0(O-B)0_Ss26Q_tSMXcnY*cg6)f27)xd8804Pke zCG-b=4Sa^rF0gU|4Jph9Q2KQW0cTRZ_cf49n+D|8UBST!3IUpA#OymY z-#8-K&ruSbdPE=iA-Ql}pyVFD#(;h<1+&;cC?71>Q0w>Pw%@=OBep#k6L)Mu!|n9L z|ERU8I&mzk*DHU(>N9Xnl))*n(4la)uTIE^Z9WZQO&GYNz7W>?mIpyBPSCBXtN7a>`*?IIqdFNO;yc$ zO@6QuC`P(7mt~uJjV27@qb)MX@6C=SPDGsYih}N|@S7npfQ}|lgK%`XhBB3>+qai8 z%t!~d4cdj>n%o*kZbr)>+;<@O7_46h8i7XN?&@9W+3*in!7yXo*3qClL)YLMLtg!a zh?1tUbP=neYx);$)J4PB*Q-R@d6dL5y%GPh8V`rkzYh{AKCG+avAZPbC{=5ngd0!~ z{nBVz9^!ftZRQgt&3++tsb;+nUtY$N%w^bkY76?R8+^=NGyJ|!o7xFS9~A93{EiPS zkO#w4otF_Ye5N8pY|@-e1Ln73&VG!`RSe zM9`(a8eY}F8~zdj3;H5klz50a5#!H2S8H^(YJn9PTt&!uneH#8*k&CB0ubm)vVmh| zHFq`bh?r9BU#Q6K@#Ms`Q+dAH=Olx0ZrKfT19*y-l;~qHr~{noAO!yeOFzEQWU=S;6yx)R)N;GbbSTA9R)Zf<6o6Nc1H&@M|*<}X>o zeFbrYHcQ#&$Pm<~Z#i0eXVfZP7{wtfu8>R%%+xOWkU~L-RH7?R=yDgm8a7(r_BRbe z4NL+H82wcDN9g~#=dqmV(aXNr8r~X#B~%vpUb3HYf2Hw);^8cYwWpQhH*3$a*Kud# zMJUm8LcOpYnB5E8q`p41b%4GPh4(Bj@ye#IB_-CUVO3Zdr}^vtK!kUyBbhcTlx+Tzuf}mG!=P6fqAX#h22C6ktaaHw z&8|n6>NLn|?kOZ-`}9N+xp0oblwVxpa(!@SX`&I$B+HBC1i~MCGw1b#1{F$?6Q$ImpljT?x z)8HNIj35=xoS9*#_w6}l^;$Fxv8}Lx?+%BAB1QyQZdYtNz90B`L%{~KkZ~vu(n34w zT3nC9+b;bbGr95#($pt}v5uT2sfh<+0ip?^37KlAmZ*YU)Fag-Y#v4fMsCGOwYPbQ za!0MH{)29Ie&flG=TdP+g|P^oQk4}%dV2PtW+ z#?N524poSc+D5@3yLg3Q!n>P?rkda~P1r=DrYTB?BD9>n=%A%h;S`s}V1I;8kmcjH zM@t<0csQzvTk?ndH~$tAvVZsBY0C40$(gR#s$jNm@C#wkK2WR?SoX7-m5oS9MzZyl zVmG*-j-Wu^45*Vdu0hq2F{G?_YN&Gov!5jG*dTFiki2ofmQNYCNqo%OG@_BYS(|?r zFx~jg@4YLzTg|0@W(c=8(C;nhn!NBLCU~Dm?EFVx#ofWruVG;u>Pb;1H{TjazkDI~ zB2q32ueE10Fein^$lHx7p=m=h3Jb>WjWC!YruT%1V2}#>U^hzBxEhw>?@j!W56WO8 zC@mpPwk9u#r3y3YxI#4jxH#)FvG_WA4!D|sVgEuJ1^QnhCWr_ESgy4LY65iHlb@l; zHzHsiM)kVEi(do{t^c7(z56wT0|EK*)9&l9-6VOtquHL+ANW%`2)%~!5Y$XI4jM=o zs9%Fu!@4r)edJLlfFRa?$0bz%U;_+d3%e@(laxT07lCFCy_UG6?H)-GdHNuZpky2M z{Qg%(q(qN1qv?bFtVmJ%UP1pME2e(1EKus9dUyUk4UL{d8j}+^UiMq0HI5@+RkqKTfY0jWYhf+}t_LkICKdiPWav zCv@k>Duns&yvG;MP0rNMQKD%=F99e{-Rhetm6AV@5SrvVRQ~vsTZ~KGJ^L=8w+YfBaf+upcwH` zk%&YNn8;K7w%HA@ArM^455hZ;vL6EnFNtbzI{8EOkjNKc5gGgmTjMkwG2jRwJ8{#; z?Kl;s&n%zjJi~uPE(*FG@}^`s%}CDx0zW$}C8mD<&}m9|KW>F{@V7R(e;l-R$ad>V z9oc|t3W{23skC4o;R9H}#E2^!QNqs&LR2eWY~WVWGxMuPcOacN zN+_GP0o|iul)zcOUgXT~ykA(1zhkXk z%z69;b2mfyIiiVvrWmy=Xo71;0a=Y_48B3Zs%Sum?Rzwd;~yETq&Zf;k@u6t@|EhY z!-x86KJeSbjl1PD2j}Ho(6hbq_4gdM51uN$c%+4N4h&paeaFu4o`IH8*z%^zbeHJp zx-R#7Y#a3reo)0IO^nqimX9t~RSG|Jh0YI&ptwm!IVG03fJ(>yk7fEogRWeI&BYa& zE?LYZzLdQV=hT=4=Y9F371)t$#*&8k6(oXV@+oLdTG9UOr*9VrSiX z+1+YL?D3lB<2TJ++*rH01umWsiN1sYvQmqxbd>2m^N-uU(tMS(!)mJe;8}gB(|VWz zHYO~xB~i3;O~=A`?iS#C&cX*?VG&>JS1L4}Bq?JfZQnJi_^;U}tMv*;>k8030hLP# zkI*SX#BKzuwR!0W#1TQ&VmTz!au0^0Oe1)M-IF9)U{Y3#xD0;nvD$pS;!~0?4qiw%7;D4FcTC|C$vJb#;1je{xdB4{VW?SeLc7XF+^HUrbxSu6dq@c&ynEy+%y(0;F64nkAn|eN4?(8B`sEJvc|MK=GP6D zNw95ofg4O;j0xE46to6$D%Qz7DNwWz>*e*p%t{z46K-YsyRou5Vs%JI8$EQ6bkyox z=g|%A0|bHOd#~fKU%4O0K$^jKU50q((|Pf0cIP6kuTAts>r58&WiB>{p826o{9*3H zm)ShE>Vg>+S-XaKbAclw`|LScJ0oDEhR-7+wMZJQQD}owF;t@=@?=D)-}-!ICa;sk z|F$=rq--&B{faXAROXQvVN&}P==|ojKM8(Oe&@4qk?SxCQhh4UG`R7doJbA}p42wH z?&R)Fob24BgKBF|>AvDQUT>}RdVJ9C&0Mn)$tT zlam12YVY?zCyPa~o!DYg=RCc#Tyr<}T84{*#|?egB$5v)$Y`z6C-d>b17iuA ziV7GPyB+dix7G%89X*!`ALZZIM*2^{%Mp3t%lEzbZ@K0VK-6I8OJVYJQ2G~u9{X4J zsdjgY){8&>H*Gz~G056tZ;zn^w-0R-=_e443wWK4UVB;BDWhwuX6^OaVq?l8P3CJNrj<+3m)1E!6WL6sX7BQOUph(Q zubz~1@Qv24vUn9o9~86Vh8K~TqV6+!?;n+$o2mu4-76}*%_5LaJ;QnTGwvMSLfaZ` zEp(e5(+^6Fv<=conqagS)44&hb*>j2%iNE67KoPx>ogIrzAuT;kVY`~apSLflxTUb zgB8@qGxJbEkKfuH&q&`swakp9gOBh?rn}0mU#@F@Lpw!$;3P{zZQE>Ee6dRpTM{!Y?M-s>@RWY&Oe0x=M*LFn z%=b4nsB~cMqnbCFkM|}^bA|kQ1|qccsc__w3wK&@Cqi{r(0A_05QW?C^$nyWcH)lm zd+lI7th+RuVOg7j6}xvEE*(Q8uP&oe62gf6R;yp+E9!~@gi;zXBdk`YgfdM)S%C*} zgU8gP++t{`H6xpF)#n1~-@#|Ej5D`8Y7V1e?`nj0<)+A$EQp@_)=czD$2D!3n`)H9e@UkvWKVCYf0d`IOPIbCW@@YB|Pj^n%~Vc_3;q` zO?z9wn)86@%6GGvu=Sot%aBs)-`!P~0d9>DifIaSZ-eTKE#`YW!vY zq7}}cOg?*wtI|^4kk$}&W~li5w2IujbO1kVhMjzSdtck$k9BQ>UjEY6ebsC9r!)(R z4}VGbXYNC;=#?KzRa90D zAe9ui;QP9*IGJ=$h>Rvj?+sW%5hhUU9v?YKmq%JI+WW9r>yM(1rF$s$w3pry5?t1T z=J1n*v$Fg(R)^~CAc^(ycfD78jK**#k2twpz{uiX;p%zYJFcj$Ov5W*^U=)OrwN%@ zJKEKyG;8gv3rvh#Gra>GaoJ6u$6;*~Q>y_CeF+IwA&VZNb}nI?6xQT#N&)Qxu1S5w zvdMu%Z4)9t48XtO>yzq>#End-3#g!s~_aw-n{hA)(e+=)QfZlZFc&6#;29| zDlNTyE7?d=xe6p%K5RSwHS4MT0ws)=gJp?5L`+a0N6+fzxmYjCI3Z`l`CTpqqn>Wt z`_Njp@5X5JCNFjQHSr>)M@8vih#<#qh3AG}${`GSNb*ApK`40<4<0yuU3Bbke{3<1m zO1peZUbS~~BWT8~e6MZ%b?-5?KDA!^&G9|<3vOo*Z;11s?RuJW7XoDTA~wr!B&}Xb z>W4)(u=t-Z!hL=zU8==C91ERf2HL}4dcPb`7_VWy(hGj<4J}9f*px((YVu1}kzqV? z@tPrK%Oo8eumSqr*DH=jMLXzE^eQBOAMREa03{6#s+3ekBh~4^8!^-nZRCR&AOnTrFU%H-L@drv6Ij332^xxsfM2mAZ7HeHV1Fj4429s)!vW%JBl zx#P1`_JCdJG3>G9rIC7lNrhibYHg$OFrS&H+&w^L%1l>wiPm8V;~vH$ZlC3vfL|iUn#>COwBp-&?Tq$-{HbHv{ z)tn~<%0*sBVimpJ5z_*m)I@9vIC(W-7N(MyDWeX@P>d$;?#+OmI_BGhR1i~W)yj#o{!62B&r;WIs7j<-}&n{D&HS>8}vc` zj=E&n4tSMw;xH>YI%cS&mbGO)p9Cu;B8IPq`b>$K%kU#fI0mr*i+Z!0X&fyCfFVR1 zB0~Jv3qQblQ6Z&?aJ$F2Kj|8*-UVwG4S!qzMt+Ar?QOeSJe22BPoJqSe-n*Kl2$t( zOWdDd{dUa~+U$NWpHh%H6q({0E66)t`{$4KeQg#)FhzfM&JPCAtLsk7!l0h*)SJBe zzwoP4WKN+w2{&1&mwxN9>f{ zYD(qP65G z*H@FN;rH0vlUSo&`)JOrG2&HwUj^{Y(K`*#7*IVIGt$=^`r*M(4ViHpZDr*cf>kwU z-fY-K@(@rsbQ?-ieZJuH!kGv56S9dExOgZ)*a){nDb-$7%n%ZKe&*%%A!zE0>i^0Q zxfg18UcF=j>aJ9N?2#(?vfN0GuwChnH>gr41b7!e8iWtWi&8D%$t{kd4Tkzr`miM!h^HdZ zpiJN&>G-bC^k=#Po#>C{hQ9ug-$SdOS7WFxzglVPj^{6uq0}A!jh4Zi1^b&l+K-Yk zvh?QA!z_Wc1k}ryJR5$Lu25>4_>y#Ca=C0y(0nEjlP&w5mr0H!YffH^r1zRfJ!ibX zlN@tM^9mzt6dnp&OkeT1b{*T(ZAl4b=lq2KJkD14$e=6q?cFc+bkT<*Goe~FTTinQ zXpYr3m;23kMnt_9*{aud+ji|*983O;RC1d?DHrx#ZH_~F)e4pS`5Paa{%nr6Nxom%(m4eIiECBHvb zv+6fVB$o^xjqpc1!yQtnjJ}c+zz6Ui-Xcy5)@?W3%xh`E5=z?I8i7a(EJX*(l@}Ho zWo?f!@J(9AR073_^GPyk(}X*ZujO%^Cko18MRd4tT8J5sykY9L@iv-nbF5b(Ca+2} z+JpMWzHU~-KYKlHJmt6GztRKA|j=NPMPv#?5q zzK9+eGkm5tG*mh8?J(R_4@D`wDx~u8Kh|W6)k*sx%dzO$v;)n{wRaOO`GJNe`i~Dc zvlA@RlLE9|AbDyFe-jt(%gEn}m}zVdBF(+-VXaXP6z$iWaLinwy37GQ}Q4!8hq6mu^oj;i2aYK1ysd+I@6 zc2y=GzT@{xFs_Hzh%w0rTSY`_*X#qOheN7+@s!8@Q}LsJ8`wiDOp4nYADh3Bk-4hh zpO)o*4L(a0N(e4&APX`%jR|z;C3@EyYj&B8O`A9#xpi0rqv4Cxl{ThZmTujfm!LpCO*d*D#IB8>BBRz?M^rDMp z;qn}VyhF;k>e}{W^G8*wY(NYv9W7n~rXH;=!>dA~+MkYfjrbX;MN+G*r|?!2TZ3jy zjcTD*s68X9J3Oe@bJ|tEeb-zC&3P8{NU>~FA8J+A2N%XES>ECVd``c+?@#WUJcp2` zwHjw~hO!28Nt~nUaHG>Na8{_Vt{gxTWea<3mt8sneI=@|SN1AFGw(#Wl&ZI@{Vkr%k~_ zTFnN&>Ed+Wv%3C7>vbZrm&@Tt++@)@Q%ZvsnS5;&OG;tZ!?eS8gh!O1i|a)DvFlLW z>n2^r?s|XMkSW}Dhhwqk&=6@mDzYhy3Zb4zr2bg^UT64NV3x$e=A^M+_!% z(zrK4k+t1M{Tp$oZShWQ5##$q=+tv=?o+>u)>a+KACjuE+fe$~(q{;(mx_)qwN;YZ z7G_S9oDr4}6FcICwSs1nT7ScB&qZ>z z!|uOps#+$dbB!e+2W$TAyn-r+jXiFPGq*B836W!w3oxy+=wBJj}Bv#ICE=1fcNTEd8HDSo6P8zMc+KTpuHVfqOUUAz->iCy|H^cT_}rrinVCzkq)R1UHdjLe`2TQb7Nx5=w_ zb3P1}d?S?urY92O%4BSg z#)rG!{PE?zVfH2l$2sQo-DucCEZ3@e!bbbM*iEZfja&kZ^H+imS0B95dap*12afVP zv|&%PHEMIR&BXAipgWHcXmp?c(bt`njTZaSqOY^-;<9k& zpK$t^#GmWK+C@P`Y)7X9DQS54^lma~e-!s$aTj6%3H52i(i}wgKgrJa+;gDz@@xi% zVgz6J4s0#g*JZ9`Y)DPNjS(4*ZTB`%{?O4tOZ$Dompn%670E>*LhCnPH#xchJ6r`- zTj#sMj`kqGk0!?Z{_vj039**B>k*7n`3GLFlRd;u-O6)hTs>9yk4Lu%U*DCf6&3ZzUo}kGxFK=`yHaIIYIGHAOm3Li#-tKUEG?rzXIM0ZV)lZn>8?~&GAVrXZ-?~fYjIB zF_$4A)ZIx0^?4D;ie*(IMlRq`v(gx5tbNO0^atGatH;0J^6)kwXFhadtUm`0G#?Ms67NvXwg zS}9uo6{QrL;jXffUW3=Bp<5W9t08pNDXRJ{)WR9JunujID$-&DbNq&FA$ty{@4ug5 ziyxj{`@ZfecHhNV6~p6G;LYrIZA<_e=j`TbI1TgdqzptPD!c zKziR?m_AJFA5amJ3MSQ$%AhO$>gZjz$?8o4mb{}+`fEDwHhX%TDWa(+JI`$cBk*Gu zW4xa0c*S((yMz5;1p+gD{Ufm-`|`YsGdFYnTvKvzpKnXuob;+=Y`1mBGTKsWX9m_X zjbhTUWc{`6=ilWC{^$avp-`oULrSJ9q>3ur5wO)tO|ta7T{u$QeYR_9cNM$bk9&yH zm-PZ3Bo6Z(P5b(&CP9|Z@6}`>?zUB+q@Be(^#n7L5B&T-a+#{HL>v9c64@r~MOg`= zdB=#Kfrwy#2)ulfzl^D$p&Rf3O%_RffEYDaNXX3J%y7vqEIMVlU|tzXePK|f#|o#T z>fBCHZM8ZXZKLL9&IAWo#8^d!?jkzIb}_+v_-8J>HKT(uOnx0l%yRs_4zIpTgY`WI zGweFsC>_+#6cUY-S_<)6p^KzG5W8qL6{0?Jt%=m#`cH{L2{1wB+4U@p`g3Cxn-Tz~ z{T8RAy>jX{$sd1AL>Z&6W*<-T1Li_W6eaWG)bm?#bQ{lwh$k9nDNLWe8z0?T85>ym zBy?Tank>KO87liD`b#Al63ak#eb*Us4`TI>Tx68O^BC8wth8aO_rjfu5JYZzR|P2P z(6QBQK{N4sTJpzWq+U~P3I61nS@HEAYk;08fm^l&-ssikAO2mhQ^huZ{Z%O@q}Zl) zGm}!+p^iUnN|Yb_xyS-ZR2nGkQ4w;0Sg{!o&ly?+OP^ie^)h1Ta!0Q?>lt0@IE8vq zKe7a$IE2vfc0_#C^<=fD~^H#Q@m}X|C%h z?ml&}&M0g)!fPy<=wArRNcB0}Bn*kFhfTBySh zKmSB1;}puKREtDOsr(V64Egi8g%E{rqXEGn%g2bjI|dIY9gnIt zgk9k z5JM&F_wA-@$*Nn|`?T|AHvZ1bQxQsSV?h%JAikC#M@k|&rn}FYjoTNU6;~|YEn4r< zPS6}gor{J5)Q#4P+zO=rzjm$sAIklUKQm*7rpc0#8DqWfwbP6eiE9**WG_@Q_MIt9 zWP2znl)4c`j1on*7BkoS+%Wb%S+AyOP-7>}CB8F#@9X zg~4sF#;GSqg~Ox)q3z{rkr!Q|jd+TSprf>%J&F(itS~(*W9(*<8B@;i;hkkBhkIny zb<|O{WY*6semdPLk!Q!Lc%9hlXWKQH84L_39+2II>m^q7kSwtL7ppdn)(M3RT|PfJH>Z3B3qm(CGKJTOSLQSCqE1HVzbY{yoMVUmUZ7}HBXl-hmO3(S0 z@_G&KuBydnph1P$g`@S#)La{TREihb^kUW8tTF#*RQWdqL3_m%ZfkCgeSwhU??row@7ul-_j>}8fhj1$IH>Xqndj-p2%!nuWMj+4O0m|uQ*6I4e)`>4 zw<|CXNK}`I!+gc*kAr=Oc=N~yyiwE418V*GTV9aXjR1{ZSEf41IutN=Xv?<@)jg!7 zhUft4ykecBsq{vc*C(;zg`yXYP3n`S$0$P1;fV>0u-f|MTUiN_n^x0@Um=S5ORBM8g6b zrL`cvNs2)0SEuC64AZlx%H}gONk*`liwz$UEx9{(q*lFnQsZt@{ETF<(>vqw?XkA0 z)Tc$5jC9_feV(%JJ%h?fK)VBHvv(8BEh4VJelgR|a5CQ0?_b|R_K&#lIWyfK?PMQ> z4vvu)g@wUpHFXpO*J^H~-oy6;GGH;72YrPsXsTp|vm!K6PkjmEg)t)qIiOFxQ&}?z zG=&_2Tf@^|A{+rs5Uu~-kv*)smONa`_eM~G91niFKe^+Ra1dmA&|!~2LC}|W@Q_$i z2=WWOX}8rx>RMBx!98PWm5k{VW~s$acN^TqUEi9AWaUK}1XfJT^e1KVDZE}P&lI2j z0s`L~Pvf2q*UeYIC}fEDx9?g%jdjelei}31c5K$f(!zbAzghg;ZvPIm4!l$Ldx4y5 zIfWbFq{h4BQnrlcv5`n$n2pMy%CGT&%Jp4if>0O~>64>iB*=itr@sOPVLeD`R3960 z9J^|O4n?~cd6DA0&rfn~DI`%OV@!!7uL5;G)=`YRLC)_2W8> ziL8-Q@ukpM_*LNwGZ!osrDKZwa4ot>IsE0Gk8PoiRikaVWo9h4Pdz(9M_^V=25qSY zt(&)dC_}gwnppG1Wek-V3d2X;1Qq}#Nt)PzI?VChRha{UN9Huo@a~Ja(KH$-d!CzI zR{5!g7-pKyuFuSfa(6d>>ozx;Xq_-rvLC^HNn(?Oy^mY59_BZx3iuU+57(X~e-z$K zu!L}O^Mi{1Y2zZWu(Ru^2n4qN;H4HDG_HE8l8~&wToxo ze~-xv{tmCRbaJnIk&5m~zkTX~&PL~>fQzZvW^80kT6e}claRte21H-<$wCY!cta{I zYx1w62;316)8Z=)MLN~~xVA_3iEl7+3x*TiLf<*rK)kGZM~H*?2cGuobD(6}vJTU1 zzb+yRcroSAGJ}G5n5Ze55quy>aO9g~f*3hJF-*lSuKM70|1EKbFau2?WLKjiV6Vqv zlbbje9rA+A!SL)wxZ&)U+Y*5y582#A0a0DRFA3=h<-qtwT__+B<-38XqpJh5jVSqE zjIu5Nv{^?}N%}LW@MLWo#vvNzZ}_9_G~(==5_*l>BmH&e#;jwhpG>TEQB6$AxQJ;R zI~&1mZyzn)+3wZB+O7H8)%8zBNz+E$os3UuqaDzPQzi?wCnHbhn%PRDGBO)$^ymj5 z>U|ApNbeOANo>NZ4XUu(ow0Xj21LK$(9v-fzrYlq-Q`gYi&ik@)4=l6r*46>? zaOGk>U1WCXm04+$m7H1eWZC$UP5QjbdQ3q6&ih#jLyElX<9p&|xKGV#2YtE<-dX#^ zRL;H1&6P%H-2;+{a<}Yp_GzC1J}~l3Q{z=m>X~u%4BjHLjjWkbI#_I7dVe^5Zk@7P z6fQ^ATlxBZI3)K&k(;=Wp{vnzm(Gp1(T$VGE|naus;e_-HwfRmYTCgSEN2)iy>Dh>&IW$ zudJlDzV;vW^{m%#$kLB3yvq~rE_MD#4qM^Dq!ybs(9QiLLQQ!;NkKJsYP+&|z4Oe1 zho!pQWrDF~1+l(q4Vw?B{NW;(?2+}5XAckZ@?kRM9;2BnraU)RAs{eMmSDJZZBAwl z)MIzMaA>r*ta94i2i>M-?#cP(+%Eg2y=$mJb<6#vmda((Qh5~qCx6hvvB;14ET@AU zPJx6}t`O#;Jf+oKiI0iLIoFVAw^|~z=_|#{B6`$v(uF z6VK1)Cs!Zmtt`ADAy>4U5tR4P1Izqpqs&vQ-X(F;Ezv#u_;RN~3vqQzq3PX%Ewkvq z7G(B