12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453 |
- <?xml version="1.0" encoding="ISO-8859-1"?>
-
- <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "../../lib/docbook/docbook-dtd/docbookx.dtd">
-
- <!-- set style sheet in build.xml using xml-html-stylesheet variable -->
- <!-- `copy-to-register' (C-x r s) then `insert-register' (C-x r i).
- <qandaentry>
- <question id="q:XX" xreflabel="Q:XX">
- <para></para>
- </question>
-
- <answer>
- <para></para>
- </answer>
- </qandaentry>
- -->
- <article class="faq">
- <title>Frequently Asked Questions about AspectJ</title>
- <para>Copyright (c) 1997-2001 Xerox Corporation,
- 2002 Palo Alto Research Center, Incorporated,
- 2003-2006 Contributors. All rights reserved.
- </para>
- <!-- todo Update me! -->
- <para>Last updated November 3, 2006
- </para>
- <para>
- For a list of recently-updated FAQ entries, see <xref linkend="q:faqchanges"/>
- </para>
- <qandaset defaultlabel="number">
- <qandadiv id="overview" xreflabel="Overview">
- <title>Overview</title>
- <qandaentry>
- <question id="q:whatisaj" xreflabel="Q:What is AspectJ?">
- <para>What is AspectJ?</para>
- </question>
- <answer>
- <para>
- AspectJ(tm) is a simple and practical extension to the
- Java(tm) programming
- language that adds to Java aspect-oriented programming (AOP)
- capabilities. AOP allows developers to reap the benefits of
- modularity for concerns that cut across the natural units of
- modularity. In object-oriented programs like Java, the natural unit
- of modularity is the class. In AspectJ, aspects modularize concerns that
- affect more than one class.
- </para>
- <para>You compile your program using the AspectJ compiler
- (perhaps using the supported development environments)
- and then run it,
- supplying a small (< 100K) runtime library.
- </para>
- <para>The AspectJ technologies include
- a compiler (<literal>ajc</literal>),
- a debugger (<literal>ajdb</literal>),
- a documentation generator (<literal>ajdoc</literal>),
- and integration with
- Eclipse, Sun-ONE/Netbeans, GNU Emacs/XEmacs,
- JBuilder, and Ant.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:benefits"
- xreflabel="Q:What are the benefits of using AspectJ?">
- <para>What are the benefits of using AspectJ?</para>
- </question>
- <answer>
- <para>AspectJ can be used to improve the modularity of software
- systems.
- </para>
- <para> Using ordinary Java, it can be difficult to modularize design
- concerns such as
- </para>
- <itemizedlist>
- <listitem><para>system-wide error-handling</para></listitem>
- <listitem><para>contract enforcement</para></listitem>
- <listitem><para>distribution concerns</para></listitem>
- <listitem><para>feature variations</para></listitem>
- <listitem><para>context-sensitive behavior</para></listitem>
- <listitem><para>persistence</para></listitem>
- <listitem><para>testing</para></listitem>
- </itemizedlist>
- <para>The code for these concerns tends to be spread out across the
- system. Because these concerns won't stay inside of any one module
- boundary, we say that they <emphasis>crosscut</emphasis> the
- system's modularity.
- </para>
- <para>AspectJ adds constructs to Java that enable the modular
- implementation of crosscutting concerns. This ability is
- particularly valuable because crosscutting concerns tend to be both
- complex and poorly localized, making them hard to deal with.
- </para>
- <!--
- <para>Initial studies have shown code size reductions of up to 40%
- and programmer productivity gains of 20%-40%. These studies were in
- an earlier version of the language and only for small sample sizes.
- So while the results are encouraging, they aren't conclusive. We
- intend to run a new set of studies once the current phase of
- language development stabilizes.</para>
- -->
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:compability"
- xreflabel="Q:Can AspectJ work with any Java program?">
- <para>Can AspectJ work with any Java program?</para>
- </question>
- <answer>
- <para>AspectJ has been designed as a <emphasis>compatible</emphasis>
- extension to Java. By compatible, we mean
- </para>
- <informaltable frame="none">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="right">
- <emphasis>upward compatible</emphasis>
- </entry>
- <entry>All legal Java programs are legal AspectJ
- programs.
- </entry>
- </row>
- <row>
- <entry align="right">
- <emphasis>platform
- compatible
- </emphasis>
- </entry>
- <entry>All legal AspectJ programs run on standard Java
- virtual machines.
- </entry>
- </row>
- <row>
- <entry align="right">
- <emphasis>tool
- compatible
- </emphasis>
- </entry>
- <entry>Existing tools can be extended to work with
- AspectJ.
- </entry>
- </row>
- <row>
- <entry align="right">
- <emphasis>programmer compatible</emphasis>
- </entry>
- <entry>Programming in AspectJ feels natural to Java
- programmers.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>The AspectJ tools run on any Java 2 Platform compatible
- platform. The AspectJ compiler produces classes that run
- on any Java 1.1 (or later) compatible platform.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:license" xreflabel="Q:How is AspectJ licensed?">
- <para>How is AspectJ licensed?</para>
- </question>
- <answer>
- <para>Since AspectJ 1.9.7, source code and documentation is available under the
- <ulink url="https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt">Eclipse Public License v 2.0</ulink>.
- </para>
- <para>AspectJ 1.5.2 through 1.9.6 source code and documentation is available under the
- <ulink url="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License v 1.0</ulink>.
- </para>
- <para>AspectJ 1.1 through 1.5.1 source code and documentation is available under the
- <ulink url="http://eclipse.org/legal/cpl-v10.html">Common Public License 1.0</ulink>.
- </para>
- <para>The AspectJ 1.0 tools are open-source software available under the
- <ulink url="http://www.opensource.org/licenses/mozilla1.1">Mozilla Public License 1.1</ulink>.
- That documentation is available under a separate license
- that precludes for-profit or commercial
- redistribution.
- </para>
- <para>The runtime jar aspectjrt.jar and its distribution are also covered by the
- <ulink url="https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt">Eclipse Public License</ulink>.
- </para>
- <para>For answers to common licensing questions, see the
- <ulink url="http://www.eclipse.org/legal/eplfaq.php">Eclipse Public License FAQ</ulink>.
- </para>
- <para>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:project" xreflabel="Q:What is the AspectJ Project?">
- <para>What is the AspectJ Project?</para>
- </question>
- <answer>
- <para>AspectJ is based on over ten years of research at
- <ulink url="http://www.parc.xerox.com">
- Xerox Palo Alto Research Center
- </ulink>
- as funded by Xerox, a U.S. Government grant (NISTATP), and a
- DARPA contract.
- </para>
- <para>It has evolved through open-source releases
- to a strong user community and now operates as an
- open source project at
- <ulink url="http://eclipse.org/aspectj">
- http://eclipse.org/aspectj</ulink>
- The AspectJ team works closely with the community
- to ensure AspectJ continues to evolve as an effective
- aspect-oriented programming language and tool set.
- </para>
- <para>
- The latest release is 1.2 <!-- XXX todo Update me! -->
- which can be downloaded from the
- <ulink url="http://eclipse.org/aspectj">AspectJ project page</ulink>,
- including sources as described
- <xref linkend="q:buildingsource"/>.
- Development is focused on supporting applications,
- improving quality and performance,
- enhancing integration with IDE's,
- and building the next generations of the language.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="quickstart" xreflabel="Quick Start">
- <title>Quick Start</title>
- <qandaentry>
- <question id="q:requirements"
- xreflabel="Q:What Java versions does AspectJ require and support?">
- <para>
- What Java versions does AspectJ require and support?
- </para>
- </question>
- <answer>
- <para>
- The AspectJ compiler produces programs for any released version of the
- Java platform (jdk1.1 and later). When running, your program classes must
- be able to reach classes in the
- small (< 100K) runtime library (aspectjrt.jar) from the distribution.
- The tools themselves require J2SE 1.3 or later to run,
- but the compiler can produce classes for any 1.1-compliant
- version of the Java platform.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:install"
- xreflabel="Q:How do I download and install AspectJ?">
- <para>How do I download and install AspectJ?</para>
- </question>
- <answer>
- <para>From AspectJ's
- <ulink url="http://eclipse.org/aspectj">web page
- </ulink>, download the AspectJ distribution.
- The <literal>jar</literal> file is installed by executing
- </para>
- <programlisting>
- java -jar <emphasis>jar file name</emphasis>
- </programlisting>
- <para>Do <emphasis role="bold">not</emphasis> try to extract the
- <literal>jar</literal> file contents and then attempt to execute
- <literal>java org.aspectj.tools.Main</literal>. (A
- <classname>NoClassDefFoundError</classname> exception will be
- thrown.) The AspectJ distribution is not designed to be installed
- this way. Use the <literal>java -jar</literal> form shown above.
- </para>
- <para>To uninstall, remove the files the installer wrote in your
- file system. In most cases, you can delete the top-level install
- directory (and all contained files), after you remove any
- new or updated files you want to keep. On Windows, no
- registry settings were added or changed, so nothing needs to be
- undone. Do not install over prior versions, which might have
- different files. Delete the prior version first.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:startUsingAJ"
- xreflabel="Q: How should I start using AspectJ?">
- <para>How should I start using AspectJ?</para>
- </question>
- <answer>
- <para>Many users adopt AspectJ in stages, first using it
- to understand and validate their systems (relying on it only in
- development) and then using it to implement crosscutting concerns
- in production systems. AspectJ has been designed to make each
- step discrete and beneficial.
- </para>
- <para>
- In order of increasing reliance, you may use AspectJ:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold"> In the development
- process
- </emphasis> Use AspectJ to trace or log
- interesting information. You can do this by adding
- simple AspectJ code that performs logging or tracing.
- This kind of addition may be removed ("unplugged") for
- the final build since it does not implement a design
- requirement; the functionality of the system is unaffected by
- the aspect.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">As an ancillary part of your
- system
- </emphasis> Use AspectJ to more completely and
- accurately test the system.
- Add sophisticated code that can check contracts,
- provide debugging support, or implement test strategies.
- Like pure development aspects, this code may also be
- unplugged from production builds. However, the same code
- can often be helpful in diagnosing failures in deployed
- production systems, so you may design the functionality
- to be deployed but disabled, and enable it when debugging.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">As an essential part of your
- system
- </emphasis> Use AspectJ to modularize
- crosscutting concerns in your system by design.
- This uses AspectJ to implement logic integral to a system
- and is delivered in production builds.
- </para>
- </listitem>
- </itemizedlist>
- <para>This adoption sequence works well in practice and has been
- followed by many projects.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:integrateWithDevTools"
- xreflabel="Q: How well does AspectJ integrate with existing Java development tools?">
- <para>How does AspectJ integrate with existing Java development
- tools?
- </para>
- </question>
- <answer>
- <para>AspectJ products are designed to make it easy to integrate
- AspectJ into an existing development process.
- Each release includes
- Ant tasks for building programs,
- the AspectJ Development Environment (AJDE) for writing
- aspects inside popular IDE's, and
- command-line tools for compiling and documenting Java and AspectJ code.
- </para>
- <!-- ok to order for style, not priority? -->
- <para>AspectJ provides replacements for standard Java tools:
- <itemizedlist>
- <listitem>
- <para><literal>ajc</literal>, the AspectJ compiler,
- runs on any Java 2 compatible platform, and produces classes
- that run on any Java 1.1 (or later) compatible platform.
- </para>
- </listitem>
- <listitem>
- <para><literal>ajdoc</literal> produces API documentation like
- javadoc, with additional crosscutting links. For example,
- it shows advice affecting
- a particular method or all code affected by a given aspect.
- At present, <literal>ajdoc</literal> is only supported in AspectJ 1.0.
- </para>
- </listitem>
- <!-- restore ajdb, ajdoc -->
- </itemizedlist>
- </para>
- <para>For debugging, AspectJ supports JSR-45, which provides a mechanism for
- debugging .class files that have multiple source files.
- Debugger clients and VM's are beginning to support this;
- see Sun's J2SE 1.4.1 VM and jdb debugger
- and recent versions of JBuilder.
- </para>
- <para>The AspectJ Development Environment (AJDE)
- enables programmers to view and navigate the crosscutting structures
- in their programs, integrated with existing support in
- popular Java IDE's for viewing and navigating object-oriented
- structures. For many programmers this provides a deeper understanding
- of how aspects work to modularize their concerns and permits them
- to extend some of their development practices without
- having to abandon their existing tools.
- </para>
- <para>
- AJDE is a set of API's providing the basis for the following
- development tool integrations:
- </para>
- <itemizedlist>
- <listitem>
- <para>Eclipse (version 2.0)
- in the Eclipse AspectJ Development Tools project
- <ulink url="http://eclipse.org/ajdt">
- http://eclipse.org/ajdt
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>Emacs (GNU version 20.3)
- and XEmacs (version 21.1 on Unix and 21.4 on Windows),
- in the SourceForge AspectJ for Emacs project
- <ulink url="http://aspectj4emacs.sourceforge.net">
- http://aspectj4emacs.sourceforge.net
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>JBuilder (versions 4 through 7) from Borland
- in the SourceForge AspectJ for JBuilder project
- <ulink url="http://aspectj4jbuildr.sourceforge.net">
- http://aspectj4jbuildr.sourceforge.net
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>Netbeans up to 3.4
- (and Sun Microsystems' Forte for Java (versions 2 and 3), Sun/One)
- in the SourceForge AspectJ for NetBeans project
- <ulink url="http://aspectj4netbean.sourceforge.net">
- http://aspectj4netbean.sourceforge.net
- </ulink>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The common functionality of AJDE is also available in
- the stand-alone source code browser <literal>ajbrowser</literal>,
- included in the tools distribution.
- </para>
- <para>Finally, as mentioned above,
- AspectJ also supports building with Ant by providing
- task interfaces to the ajc and ajdoc tools.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="typicalprograms" xreflabel="Typical AspectJ programs">
- <title>Typical AspectJ programs</title>
- <qandaentry>
- <question id="q:aspectsoptional"
- xreflabel="Q:Are aspects always optional or non-functional parts of a program?">
- <para>Are aspects always optional or non-functional parts of
- a program?
- </para>
- </question>
- <answer>
- <para>No. Although AspectJ can be used in a way that allows AspectJ
- code to be removed for the final build, aspect-oriented code is not
- <emphasis>always</emphasis> optional or non-functional. Consider
- what AOP really does: it makes the modules in a program correspond
- to modules in the design. In any given design, some modules are
- optional, and some are not.
- </para>
- <para>The examples directory included in the AspectJ distribution
- contains some examples of the use aspects that are not optional.
- Without aspects,
- </para>
- <informaltable frame="none">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="right">
- <emphasis role="strong">bean</emphasis>
- </entry>
- <entry>Point objects would not be JavaBeans.</entry>
- </row>
- <row>
- <entry align="right">
- <emphasis role="strong">introduction</emphasis>
- </entry>
- <entry>Point objects would not be cloneable, comparable or
- serializable.
- </entry>
- </row>
- <row>
- <entry align="right">
- <emphasis role="strong">spacewar</emphasis>
- </entry>
- <entry>Nothing would be displayed.</entry>
- </row>
- <row>
- <entry align="right">
- <emphasis role="strong">telecom</emphasis>
- </entry>
- <entry>No calls would be billed.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:developmentAndProductionAspects"
- xreflabel="Q:What is the difference between development and production aspects?">
- <para>
- What is the difference between development and production aspects?
- </para>
- </question>
- <answer>
- <para>
- Production aspects are delivered with the finished product,
- while development aspects are used during the development process.
- Often production aspects are also used during development.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:devAspects"
- xreflabel="Q:What are some common development aspects?">
- <para>
- What are some common development aspects?
- </para>
- </question>
- <answer>
- <para>Aspects for logging, tracing, debugging, profiling
- or performance monitoring, or testing.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:prodAspects"
- xreflabel="Q:What are some common production aspects?">
- <para>
- What are some common production aspects?
- </para>
- </question>
- <answer>
- <para>
- Aspects for performance monitoring and diagnostic systems,
- display updating or notifications generally, security,
- context passing, and error handling.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="concepts" xreflabel="Basic AOP and AspectJ Concepts">
- <title>Basic AOP and AspectJ Concepts</title>
- <qandaentry>
- <question id="q:crosscutting"
- xreflabel="Q:What are scattering, tangling, and crosscutting?">
- <para>What are scattering, tangling, and crosscutting?</para>
- </question>
- <answer>
- <para>
- "Scattering" is when similar code is distributed throughout many
- program modules. This differs from a component being used by
- many other components since
- it involves the risk of misuse at each point and of inconsistencies
- across all points. Changes to the implementation may require
- finding and editing all affected code.
- </para>
- <para>"Tangling" is when two or more concerns are implemented in
- the same body of code or component, making it more difficult to understand.
- Changes to one implementation may cause unintended changes
- to other tangled concerns.
- </para>
- <para>"Crosscutting" is how to characterize a concern than spans
- multiple units of OO modularity - classes and objects. Crosscutting
- concerns resist modularization using normal OO constructs, but
- aspect-oriented programs can modularize crosscutting concerns.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:joinpoints"
- xreflabel="Q: What are join points?">
- <para>What are join points?</para>
- </question>
- <answer>
- <para>Join points are well-defined points in the execution of a
- program. Not every execution point is a join point: only those
- points that can be used in a disciplined and principled manner are.
- So, in AspectJ, the execution of a method call is a join point, but
- "the execution of the expression at line 37 in file Foo.java" is
- not.
- </para>
- <para>The rationale for restricting join points is similar to the
- rationale for restricting access to memory (pointers) or
- restricting control flow expressions (<literal>goto</literal>) in
- Java: programs are easier to understand, maintain and extend
- without the full power of the feature.
- </para>
- <para>AspectJ join points include reading or writing a field; calling
- or executing an exception handler, method or constructor.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:pointcut"
- xreflabel="Q; What is a pointcut?">
- <para>
- What is a pointcut?
- </para>
- </question>
- <answer>
- <para>A pointcut picks out
- <link linkend="q:joinpoints">
- join points
- </link>. These join points are described by the pointcut
- declaration. Pointcuts can be defined in classes or in aspects,
- and can be named or be anonymous.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:advice"
- xreflabel="Q:What is advice?">
- <para>What is advice?</para>
- </question>
- <answer>
- <para>Advice is code that executes at each
- <link linkend="q:joinpoints">join point</link> picked out by a
- <link linkend="q:pointcut">pointcut</link>. There are three
- kinds of advice: before advice, around advice and after advice. As
- their names suggest, before advice runs before the join point
- executes; around advice executes before and after the join point;
- and after advice executes after the join point. The power of
- advice comes from the advice being able to access values in the
- execution context of a pointcut.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:declarations"
- xreflabel="Q:What are inter-type declarations?">
- <para>What are inter-type declarations?</para>
- </question>
- <answer>
- <para>AspectJ enables you to declare members and supertypes of another class
- in an aspect, subject to Java's type-safety and access rules. These are
- visible to other classes only if you declare them as accessible.
- You can also declare compile-time errors and warnings based on pointcuts.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:whatisanaspect"
- xreflabel="Q:What is an aspect?">
- <para>What is an aspect?</para>
- </question>
- <answer>
- <para>Aspects are a new class-like language element that has been
- added to Java by AspectJ. Aspects are how developers encapsulate
- concerns that cut across classes, the natural unit of modularity in
- Java.
- </para>
- <para>Aspects are similar to classes because...
- <itemizedlist>
- <listitem><para>aspects have type</para></listitem>
- <listitem>
- <para>
- aspects can extend classes and other aspects
- </para>
- </listitem>
- <listitem>
- <para>
- aspects can be abstract or concrete
- </para>
- </listitem>
- <listitem>
- <para>
- non-abstract aspects can be instantiated
- </para>
- </listitem>
- <listitem>
- <para>aspects can have static and non-static state and
- behavior
- </para>
- </listitem>
- <listitem>
- <para>aspects can have fields, methods, and types
- as members
- </para>
- </listitem>
- <listitem>
- <para>the members of non-privileged aspects follow the
- same accessibility rules as those of classes
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>Aspects are different than classes because...
- <itemizedlist>
- <listitem>
- <para>aspects can additionally include as members pointcuts,
- advice, and inter-type declarations;
- </para>
- </listitem>
- <listitem>
- <para>aspects can be qualified by specifying the
- context in which the non-static state is available
- </para>
- </listitem>
- <listitem>
- <para>aspects can't be used interchangeably with
- classes
- </para>
- </listitem>
- <listitem>
- <para>aspects don't have constructors or finalizers,
- and they cannot be created with the new operator;
- they are automatically available as needed.
- </para>
- </listitem>
- <listitem>
- <para>privileged aspects can access private members of
- other types
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="whyaop" xreflabel="Why AOP?">
- <title>Why AOP?</title>
- <qandaentry>
- <question id="q:ccfromflaws"
- xreflabel="Q:Are crosscutting concerns induced by flaws?">
- <para>Are crosscutting concerns induced by flaws in parts of the
- system design, programming language, operating system, etc. Or is
- there something more fundamental going on?
- </para>
- </question>
- <answer>
- <para>AOP's fundamental assumption is that in any sufficiently
- complex system, there will inherently be some crosscutting
- concerns.
- </para>
- <para>So, while there are some cases where you could re-factor a
- system to make a concern no longer be crosscutting, the AOP idea
- is that there are many cases where that is not possible, or where
- doing so would damage the code in other ways.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:definingaspectspercc"
- xreflabel="Q:Does it really make sense to define aspects in terms of crosscutting?">
- <para>Does it really make sense to define aspects in terms of
- crosscutting?
- </para>
- </question>
- <answer>
- <para>Yes.</para>
- <para>The short summary is that it is right to define AOP in terms of
- crosscutting, because well-written AOP programs have clear
- crosscutting structure. It would be a mistake to define AOP in
- terms of "cleaning up tangling and scattering", because that isn't
- particular to AOP, and past programming language innovations also
- do that, as will future developments.
- </para>
- <para>(Slides for a long talk on this topic were once available at
- http://www.cs.ubc.ca/~gregor/vinst-2-17-01.zip.)
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:domainspecific"
- xreflabel="Q:Is AOP restricted to domain-specific applications?">
- <para>Is AOP restricted to domain-specific
- applications?
- </para>
- </question>
- <answer>
- <para>No. Some implementations of AOP are domain-specific, but
- AspectJ was specifically designed to be general-purpose.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:whyaopifinterceptors"
- xreflabel="Q:Why do I need AOP if I can use interceptors?">
- <para>Why do I need AOP if I can use interceptors
- (or JVMPI or ref
- lection)?
- </para>
- </question>
- <answer>
- <para>There are many mechanisms people use now to implement
- some crosscutting concerns. But they don't have a way to express
- the actual structure of the program so you (and your tools)
- can reason about it. Using a language enables you to express the
- crosscutting in first-class constructs. You can not only avoid the
- maintenance problems and structural requirements of some other
- mechanisms, but also combine forms of crosscutting so that all
- the mechanisms for a particular concern are one piece of code.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="related" xreflabel="Related Technology">
- <title>Related Technology</title>
- <qandaentry>
- <question id="q:comparetonewforms"
- xreflabel="Q:How does AspectJ compare to other new forms of programming?">
- <para>
- How does AspectJ compare to other new forms of programming?
- </para>
- </question>
- <answer>
- <para>There are many recent proposals for programming languages that
- provide control over crosscutting concerns. Aspect-oriented
- programming is an overall framework into which many of these
- approaches fit. AspectJ is one particular instance of AOP,
- distinguished by the fact that it was designed from the ground up
- to be compatible with Java.
- </para>
- <para>For more alternatives for aspect-oriented programming, see
- <ulink url="http://aosd.net">http://aosd.net</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:compartoreflection"
- xreflabel="Q:How do you compare the features of AspectJ with reflective systems?">
- <para>How do you compare the features of AspectJ with
- reflective systems?
- </para>
- </question>
- <answer>
- <para>Reflective and aspect-oriented languages have an important
- similarity: both provide programming support for dealing with
- crosscutting concerns. In this sense reflective systems proved
- that independent programming of crosscutting concerns is
- possible.
- </para>
- <para>But the control that reflection provides tends to be low-level
- and extremely powerful. In contrast, AspectJ provides more
- carefully controlled power, drawing on the rules learned from
- object-oriented development to encourage a clean and understandable
- program structure.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:comparetomixin"
- xreflabel="Q:How do AspectJ features compare with those of mixin-based inheritance?">
- <para>How do AspectJ features compare with those of mixin-based
- inheritance?
- </para>
- </question>
- <answer>
- <para>Some features of AspectJ, such as introduction, are related to
- <emphasis>mixin-based inheritance</emphasis>. But, in order to
- support crosscutting, a core goal for AspectJ, AspectJ goes beyond
- mixin-based inheritance.
- </para>
- <para>Firstly, an aspect imposes behavior on a class, rather than a
- class requesting behavior from an aspect. An aspect can modify a
- class without needing to edit that class. This property is
- sometimes called <emphasis>reverse inheritance</emphasis>.
- </para>
- <para>Secondly, a single aspect can affect multiple classes in
- different ways. A single paint aspect can add different paint
- methods to all the classes that know how to paint, unlike mixin
- classes.
- </para>
- <para>
- So mixin-based inheritance doesn't have the reverse inheritance
- property, and mixins affect every class that mixes them in the same.
- If I want to do something like SubjectObserverProtocol, I need two
- mixins, SubjectPartofSubjectObserverProtocol and ObserverPartof...
- In AspectJ, both halves of the protocol can be captured in a single
- aspect.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:dynamicaop"
- xreflabel="Q:How does AspectJ compare with more dynamic AOP?">
- <para>How does AspectJ compare with more dynamic AOP?
- </para>
- </question>
- <answer>
- <para>
- Some AOP techniques are presented as "dynamic" because the weaving
- occurs when classes are loaded, because aspects can be configured
- in a separate XML file before launch, or because some advice
- depends on runtime reflection. They are said to be more flexible
- than AspectJ.
- </para>
- <para>
- This is a misconception. First, the AspectJ 1.1 weaver has always
- supported weaving at compile-time or class-load-time. Weaving at
- compile-time reduces application launch and running time, and it helps
- IDE's offer support for tracking down weaving errors and understanding
- the impact of aspects on a system.
- On the other hand, weaving at load-time simplifies build and deployment.
- Before AspectJ 1.2, the user had to write a class loader that used the
- weaver API to weave at load time; since 1.2, AspectJ comes with a
- command-line launcher to support weaving at class-load-time without
- any other changes to a build configuration. In AspectJ 5, we expect
- to get a similar level of support as AspectWerkz, and to exploit
- the class bytecode weaving hook available in Java 5 VM's.
- </para>
- <para>
- Second, AspectJ programs, like Java programs generally, can be
- written to support any level of XML configuration or to depend on
- runtime reflection. There are some benefits to using AspectJ;
- e.g., the proceed() form within around advice simplifies a lot of
- the work that otherwise would go into writing a generalized
- interceptor, without introducing many of the runtime errors that can
- result from interceptors.
- For AspectJ examples of configurable or reflection-dependent programs,
- see the sample code linked off the AspectJ documentation page
- or the examples discussed on the mailing list, e.g.,
- <ulink url="http://dev.eclipse.org/mhonarc/lists/aspectj-users/msg02151.html">
- Incremental and runtime weaving support?</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aopandxp"
- xreflabel="Q:What is the relationship between AOP and
- XP (extreme programming AKA agile methods)?">
- <para>What is the relationship between AOP and
- XP (extreme programming AKA agile methods)?
- </para>
- </question>
- <answer>
- <para>From a question on the user list:
- <programlisting>
- > Anyone know the connections between AOP and Extreme Programming?
- > I am really confused. It seems AOP is a programming paradigm, which
- > is the next level of abstraction of OOP. Extreme Programming, however,
- > this is a lightweight software development process. One of the common
- > motivations of AOP and XP is designed to adopt to the requirement
- > changes, so that it can save the cost of software development.
- </programlisting>
- </para>
- <para>
- This is Raymond Lee's answer:
- </para>
- <para>
- You're not really that confused. AOP and XP are orthogonal concepts,
- although AOP can be used to help accomplish XP goals.
- One of the goals of XP is to respond to changing requirements.
- Another is to reduce the overall cost of development. These are
- not necessarily the same thing.
- </para>
- <para>
- One of the principles of XP that contribute to meeting those goals
- is to maintain clean, simple designs. One of the criteria for clean,
- simple designs is to factor out duplication from the code. Benefits
- of removing duplication include the code being easier to understand,
- better modularity of the design, lower costs of code changes, less
- chance of conflicting changes when practicing collective code
- ownership, etc.
- </para>
- <para>
- Different types of duplication lend themselves to being addressed by
- different design paradigms and language features. Duplicate snippets
- of code can be factored out into methods. Duplicate methods can be
- factored out to common classes, or pushed up to base classes.
- Duplicate patterns of methods and their use can be factored out to
- mechanisms of classes and methods (i.e. instantiations of design
- patterns).
- </para>
- <para>
- AOP addresses a type of duplication that is very difficult to handle
- in the other common paradigms, namely cross-cutting concerns. By
- factoring out duplicate cross-cutting code into aspects, the target
- code becomes simpler and cleaner, and the cross-cutting code becomes
- more centralized and modular.
- </para>
- <para>
- So, AOP as a paradigm, and the associated tools, gives an XPer, or
- anyone wanting to remove duplication from the code base, a powerful
- way to remove a form of duplication not easily addressed until now.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectjandcsharp"
- xreflabel="Q:Will you support C#?">
- <para>Will you support C#?</para>
- </question>
- <answer>
- <para>Not at this time. Although the resemblances between C# and Java
- means it would probably be a fairly straightforward matter to take
- the AspectJ language design and produce AspectC#, our current focus
- is only on supporting effective uses of AspectJ.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="adoption" xreflabel="Deciding to adopt AspectJ">
- <title>Deciding to adopt AspectJ</title>
- <qandaentry>
- <question id="q:productplans"
- xreflabel="Q:Is it safe to use AspectJ in my product plans??">
- <para>
- Is it safe to use AspectJ in my product plans?
- </para>
- </question>
- <answer>
- <para>You may use AspectJ in your product or project with little
- risk. Several factors play a role in reducing the risk of adopting
- this new technology:
- <itemizedlist>
- <listitem>
- <para>AspectJ is an <emphasis>addition</emphasis> to
- Java, and can be introduced into a project
- in a way that limits risk.
- See <xref linkend="q:startUsingAJ"/> for
- some suggestions on how to do this.
- </para>
- </listitem>
- <listitem>
- <para>The AspectJ compiler accepts standard Java as
- input and produces standard Java bytecode as output.
- In 1.0, an optional mode produces standard Java source code
- which may then be compiled with any compliant Java compiler
- (e.g. Sun's <literal>javac</literal> compiler
- or IBM's <literal>jikes</literal> compiler).
- In 1.1, an optional mode accepts standard Java bytecode
- from any compliant Java compiler
- and weaves in the aspects to produce new bytecode.
- </para>
- </listitem>
- <listitem>
- <para>AspectJ is available under a non-proprietary, open source license, the
- <ulink url="https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt">
- Eclipse Public License v 2.0</ulink>.
- AspectJ will continue to evolve and be available, regardless
- of the fate of any particular organization involved with
- AspectJ.
- </para>
- </listitem>
- <listitem>
- <para>Removing AspectJ from your program is not
- difficult, although you will lose the flexibility and
- economy that AspectJ provided.
- </para>
- </listitem>
- <listitem>
- <para>A number of significant open-source projects and industry
- products use AspectJ successfully. One list is kept on
- <ulink url="http://www.aosd.net/wiki/index.php?title=FAQ">
- the AOSD FAQ</ulink>, and more appear on the mailing
- lists (search for, e.g., "AspectJ in real world", as
- described in <xref linkend="q:searchingsite"/>).
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:effectonsize"
- xreflabel="Q:What is the effect of using AspectJ on the source code size of programs?">
- <para>What is the effect of using AspectJ on the source code
- size of programs?
- </para>
- </question>
- <answer>
- <para>Using aspects reduces, as a side effect, the number of source
- lines in a program. However, the major benefit of using aspects
- comes from <emphasis>improving</emphasis> the modularity of a
- program, not because the program is smaller. Aspects gather into a
- module concerns that would otherwise be scattered across or
- duplicated in multiple classes.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:effectonperformance"
- xreflabel="Q:Does AspectJ add any performance overhead?">
- <para>
- Does AspectJ add any performance overhead?
- </para>
- </question>
- <answer>
- <para>The issue of performance overhead is an important one. It is
- also quite subtle, since knowing what to measure is at least as
- important as knowing how to measure it, and neither is always
- apparent.
- </para>
- <para>We aim for the performance of our implementation of AspectJ to
- be on par with the same functionality hand-coded in Java. Anything
- significantly less should be considered a bug.
- </para>
- <para>There is currently no benchmark suite for AOP languages in
- general or for AspectJ in particular. It is probably too early to
- develop such a suite because AspectJ needs more maturation of the
- language and the coding styles first. Coding styles really drive
- the development of the benchmark suites since they suggest what is
- important to measure.
- </para>
- <para>Though we cannot show it without a benchmark suite, we believe
- that code generated by AspectJ has negligible performance overhead.
- Inter-type member and parent introductions should have very little
- overhead, and advice should only have some indirection which
- could be optimized away by modern VM's.
- </para>
- <para>The <literal>ajc</literal> compiler will use static typing information
- to only insert the advice and dynamic pointcut tests that are absolutely necessary.
- Unless you use 'thisJoinPoint' or 'if', the main dynamic checks will be
- 'instanceof' checks which are generally quite fast.
- These checks will only be inserted when they can not be inferred from
- the static type information.
- </para>
- <para>When measuring performance, write AspectJ code
- fragments and compare them to the performance of the
- corresponding code written without AspectJ. For example, don't
- compare a method with before/after advice that grabs a lock to just
- the method. That would be comparing apples and oranges. Also be
- sure to watch out for JIT effects that come from empty method
- bodies and the like. Our experience is that they can be quite
- misleading in understanding what you've measured.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:modularityviolations"
- xreflabel="Q:I've heard that AspectJ leads to modularity violations. Does it?">
- <para>
- I've heard that AspectJ leads to modularity violations. Does it?
- </para>
- </question>
- <answer>
- <para>
- Well I haven't yet seen a language in which you can't write bad code!
- </para>
- <para>
- But seriously, most AspectJ users find that just like when they learned
- OO, it takes a while to really get the hang of it. They tend to start
- in the usual way, by copying canonical examples and experimenting with
- variations on them.
- </para>
- <para>
- But users also find that rather than being dangerous, AspectJ helps them
- write code that is more clear and has better encapsulation -- once they
- understand the kind of modularity AspectJ supports. There are several
- good papers that talk about this (see below), but here's a basic point
- to keep in mind: when properly used, AspectJ makes it possible program
- in a modular way, something that would otherwise be spread throughout
- the code. Consider the following code, adapted from the AspectJ tutorial:
- </para>
- <programlisting>
- aspect PublicErrorLogging {
- Log log = new Log();
-
- pointcut publicInterface(Object o):
- call(public * com.xerox.*.*(..)) && target(o);
-
- after(Object o) throwing (Error e): publicInterface(o) {
- log.write(o, e);
- }
- }
- </programlisting>
- <para>
- The effect of this code is to ensure that whenever any public method of
- an interface or class in the <literal>com.xerox</literal> package
- throws an error, that error is logged before being thrown to its caller.
- </para>
- <para>
- Of course in the alternative implementation a large number of methods
- have a try/catch around their body.
- </para>
- <para>
- The AspectJ implementation of this crosscutting concern is clearly
- modular, whereas the other implementation is not. As a result, if you
- want to change it, its easier in the AspectJ implementation. For
- example, if you also want to pass the name of the method, or its
- arguments to <literal>log.write</literal>, you only have to edit
- one place in the AspectJ code.
- </para>
- <para>
- This is just a short example, but I hope it shows how what happens
- with AOP and AspectJ is that the usual benefits of modularity are
- achieved for crosscutting concerns, and that leads to better code,
- not more dangerous code.
- </para>
- <para>
- One paper someone else just reminded me of that talks some more
- about this is:
- <ulink url="http://www.cs.ubc.ca/~kdvolder/Workshops/OOPSLA2001/submissions/12-nordberg.pdf">
- http://www.cs.ubc.ca/~kdvolder/Workshops/OOPSLA2001/submissions/12-nordberg.pdf
- </ulink>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:encapsulation"
- xreflabel="Q:Why does AspectJ permit aspects to access and add members of another type?">
- <para>
- Why does AspectJ permit aspects to access and add members of another type?
- Isn't that violating OO encapsulation?
- </para>
- </question>
- <answer>
- <para>In the spirit of Smalltalk, we have decided to give more power
- to the language in order to let the user community experiment and
- discover what is right. To date this has proven to be a successful
- strategy because it has permitted the construction of many useful
- aspects that crosscut the internal state of an object, and as such
- need access the its private members. However, we are not
- discounting that some sort of restrictions are useful, rather, we
- are seeking input from the community in order to decide on what
- these restrictions should be.
- </para>
- <para>
- In that light, our position on encapsulation is :
- </para>
- <itemizedlist>
- <listitem><para>we respect Java's visibility rules</para></listitem>
- <listitem><para>we also provide open-classes, a mature OO technology</para></listitem>
- <listitem><para>we provide "privileged" access if you really need it.</para></listitem>
- </itemizedlist>
- <para>
- Introducing parents or members to classes is a well-studied OO technique
- known as open classes.
- </para>
- <para>
- Open classes have been used in many languages prior to AspectJ,
- including CLOS, Python, Smalltalk, Objective-C, and others.
- Building from Java, introduction in AspectJ provides better
- name hygiene and access control than prior languages.
- Introduced code obeys all of Java's normal accessibility rules
- for its lexical location in the aspect that it is introduced from.
- Such code can not even see, much less access, private members of
- the class it is introduced into. Further, introductions can be
- declared private to the aspect, so they are not visible to
- other clients of the class.
- </para>
- <para>
- Privileged aspects do permit access to private members of another
- class. They are a response to the very few cases where developers
- genuinely need such access (typically for testing purposes where it
- access is necessary), but it would be more risky to open access by
- putting the aspect in the same package, adding test code, or changing
- access in the target class. We recommend using privileged aspects
- only as necessary, and believe that marking them "privileged" makes
- any potential misuse apparent.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectjandj2ee"
- xreflabel="Q:Can I use AspectJ with J2EE?">
- <para>Can I use AspectJ with J2EE?</para>
- </question>
- <answer>
- <para>
- Consider the component types in J2EE:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Servlet: AspectJ works well within servlets
- </para>
- </listitem>
- <listitem>
- <para>
- JSP: It is possible to use AspectJ to affect code in JSPs by precompiling
- them into Java sources and compiling these with ajc. This can be used, e.g., to
- customize displays by turning on and off custom JSP taglibs. The mapping from a
- given jsp source to java package and class name is not standardized, which means
- doing this imposes dependencies on specific container versions.
- </para>
- </listitem>
- <listitem>
- <para>
- EJB: AspectJ supports a wide variety of aspects for EJBs. It can be used for
- logging, tracing, debugging, error handling by layers, correlated method-level
- interception (e.g., chargebacks), metering, fine-grained transactions, etc.
- Indeed, it can be used to enforce adherence to coding restrictions within an
- EJB (e.g., not using java.io, creating a class loader, or listening on
- sockets) using <literal>declare error</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The basic limitations are that there is no built-in support for writing J2EE
- analogs for AspectJ extensions to Java, like distributed aspects, distributed
- cflow, or managing state between invocations. These don't prevent one from using
- AspectJ to do useful intra-container implementation, nor need they prevent one
- from building distributed support, state management, and inter-component
- implementations that leverage AspectJ. It just takes some work. In more detail:
- </para>
- <para>
- All AspectJ implementations may define "code the implementation controls".
- The AspectJ 1.0 implementation defines this as the files passed to the compiler
- (AspectJ 1.1 will also support bytecode weaving).
- </para>
- <para>
- Some advice on EJB operations will generate methods that confuse ejb compilers.
- To avoid this problem, you can use the -XaddSafePrefix flag when compiling with ajc.
- </para>
- <para>
- EJB components may be invoked remotely, and containers may passivate and
- pool EJB's. Servlets have similar limitations, and in both cases the
- lifespan of the defining class loader is implementation-dependent
- (though it must span the operation of a particular request).
- </para>
- <para>
- Being limited by lifecycle and namespace, the AspectJ 1.0 implementation
- supports aspects that operate through non-remote invocations during the lifetime
- of the namespace for a particular
- deployment unit compiled in its entirety by the ajc compiler.
- This means AspectJ supports common aspects only within a single local runtime
- namespace (usually implemented as a class loader hierarchy).
- </para>
- <para>
- Further, AspectJ recognizes language-level join points (object initialization,
- method calls, etc.), not their EJB analogs (ejb find or create methods...).
- These lead to the following consequences:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Issingleton aspects (the default) are limited to the lifetime of
- the defining class loader, which in some implementations may not span
- multiple invocations of the same application or EJB component.
- </para>
- </listitem>
- <listitem>
- <para>
- EJB lifecycles are different from object lifecycles, so perthis
- and pertarget aspects will make little sense. They do not work
- in the current implementation, which uses synchronized methods
- to ensure a correct association in threaded environments
- (EJB's may not have synchronized methods).
- </para>
- </listitem>
- <listitem>
- <para>
- Percflow or percflowbelow aspects are restricted to a chain of
- non-remote invocations. While EJB 2.0 permits declaring an interface
- local, this information is not available to the AspectJ compiler today.
- For same reasons as stated above fore perthis, these will not work even
- in the EJB container.
- </para>
- </listitem>
- <listitem>
- <para>
- Evaluation of cflow or cflowbelow pointcuts will be valid only
- with respect to a chain of non-remote invocations.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- In addition, any AspectJ code should respect EJB operations:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The EJB container accesses EJB component fields directly, i.e.,
- in code outside the control of the compiler. There is no join point for
- these accesses, and hence no way to write a pointcut to advise that access.
- </para>
- </listitem>
- <listitem>
- <para>
- The EJB container may pool EJB components, so any initialization
- join points may run once per component constructed, not once per
- component initialized for purposes of a client call.
- </para>
- </listitem>
- <listitem>
- <para>
- The EJB container is permitted to change class loaders, even
- between invocations of a particular EJB component (by passivating and
- activating with a new class loader). In this case, instances of singleton
- aspects will not operate over multiple invocations of the component, or that
- static initialization join point recur for a given class as it is re-loaded.
- This behavior depends on the container implementation.
- </para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectjandgj"
- xreflabel="Q:Can I use AspectJ with Generic Java?">
- <para>Can I use AspectJ with Generic Java?</para>
- </question>
- <answer>
- <para>We plan to support Generics when Java 1.5 is available.
- </para>
- <para>But at this time, unfortunately not. The two compilers are just not
- at all compatible. In an ideal world, there would be a wonderful
- Open Source extensible compiler framework for Java that both GJ and
- AspectJ would be built on top of, and they would seamlessly
- interoperate along with all other extensions to Java that you might
- be interested in, but that's not the case (yet?).
- </para>
- <para>However, on 09 October 2000, the Java Community Process
- approved a proposal to add generic types to Java that is largely
- based on GJ (JSR 14). A draft specification was submitted for
- public review, which closed on 01 August 2001, and a
- prototype implementation has been released by Sun.
- </para>
- <para>We are committed to moving very rapidly to add support for
- generic types in AspectJ when generic types become part of the Java
- language specification. Everyone on the AspectJ team is looking
- forward to this, because we too would really like to be able to
- write code that includes both aspects and generic types.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectjandj2me"
- xreflabel="Q:Can I use AspectJ with J2ME?">
- <para>Can I use AspectJ with J2ME?</para>
- </question>
- <answer>
- <para>The J2ME platform has several different components.
- The diagram below shows how the different profiles
- build on top of the two configurations CDC (Connected Device
- Configuration) and CLDC (Connected Limited Device Configuration):
- <programlisting>
- --------------
- | Personal |
- -------------- --------
- | Foundation | | MIDP |
- ------------------ ------------------
- | CDC | | CLDC |
- ------------------------------------------
- | Java |
- ------------------------------------------
- </programlisting>
- Which configuration you have dictates the restrictions when
- running AspectJ compiled programs.
- </para>
- <para>
- If you're running with a profile which sits on top of CDC then
- there are not, as far as we are aware, any restrictions when
- running AspectJ compiled code on this flavour of J2ME.
- </para>
- <para>
- If you're running with a profile sitting on top of CLDC 1.1
- you are currently unable to use the <literal>thisJoinPoint,
- thisJoinPointStaticPart</literal> and <literal>
- thisEnclosingJoinPointStaticPart</literal> variables, the
- <literal>cflow</literal> and <literal>cflowbelow</literal>
- pointcuts and the <literal>percflow</literal> and <literal>
- percflowbelow</literal> perClauses.
- </para>
- <para>
- Finally, if you're running with a profile which sits on top
- of CLDC 1.0 you have all the restrictions of CLDC 1.1. There may
- be further restrictions due to the lack of types corresponding
- to the primitive types (e.g. Integer.TYPE), however, at the
- time of writing we have been unable to do any extensive testing
- on this.
- </para>
- <para>
- Note that the aspectj runtime jar is now (as of AspectJ5) quite
- large but only a small subset is required for executing code
- in J2ME environments. We plan to ship a second aspectjrt.jar
- built for the J2ME environment at some point.
- </para>
- <para>
- For more discussion and to raise any issues you have with
- AspectJ and J2ME, refer to
- <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=92933">
- bugzilla entry 92933</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aopinjava"
- xreflabel="Q: Are you working to put AOP into Java?">
- <para> Are you working to put AOP into Java?
- It seems that every AOP toolset currently uses proprietary mechanisms
- to describe point-cuts, etc.
- </para>
- </question>
- <answer>
- <para>
- We are working on standardization, but it's
- a question of timing/ripeness (imagine going from thousands of users
- to millions). (See <xref linkend="q:standardization"/>.) We believe
- AspectJ addresses this question in the best way possible now:
- <itemizedlist>
- <listitem>
- <para>
- It's open-source. Rather than being proprietary or controlled by a
- vendor, it's available for anybody to use and build upon, forever.
- </para>
- </listitem>
- <listitem>
- <para>
- AspectJ is not a set of mechanisms, it's a language. It is currently
- implemented using certain techniques, but there's nothing that prevents
- it from being implemented with other techniques. That means users can
- adopt the language with confidence that implementations will get better.
- </para>
- </listitem>
- <listitem>
- <para>
- There is no engineering need to change Java. The AspectJ language uses
- the join point model already in Java, so there is no need to extend the
- programming model. Our implementation produces valid Java bytecode, which
- runs in any compliant J2SE VM and supports standard debuggers for those VM's
- that support JSR-45 (debugging support for multi-language/multi-file sources).
- This is a huge benefit to Sun since Sun must be extremely cautious
- about extensions to the language or VM; before adopting AOP, Sun should
- demand the kind of actual-proof that AspectJ implementations offer.
- </para>
- </listitem>
- <listitem>
- <para>
- On the issue of "proprietary mechanisms to describe pointcuts, etc.": Any AOP
- has to have some language to describe pointcuts and the like ("pointcuts"
- of course being the AspectJ term). Users would like to have one language
- (to avoid having to learn or transform between many languages) and the
- choice of multiple implementations (tailored for a configuration, subject
- to competitive pressure, etc.). That's what AspectJ offers.
- </para>
- </listitem>
- <listitem>
- <para>
- That said, we believe the AspectJ extensions to Java could form the basis
- for bringing AOP to Java; when that happens, there will be engineering
- opportunities to make the implementation and tool support better.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:support"
- xreflabel="Q: What kind of support is available?">
- <para>What kind of support is available?</para>
- </question>
- <answer>
- <para>
- The mailing lists provide the primary support for everyone
- in the community
- (See <xref linkend="q:mailingLists"/>).
- To request commercial support, tutorials, or presentations,
- use the developer mailing list,
- <literal>aspectj-dev@eclipse.org</literal>.
- </para>
- <para>
- To find out about known issues, see the
- <ulink url="progguide/implementation.html">
- AspectJ Programming Guide Appendix, "Implementation Notes"</ulink>
- and the AspectJ bugs in the database at
- <ulink url="http://bugs.eclipse.org/bugs">http://bugs.eclipse.org/bugs</ulink>
- (using the product <literal>AspectJ</literal>). Here are direct links to
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">
- view open compiler bugs</ulink>,
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ">
- view all Aspectj bugs (open or closed)</ulink>, or
- <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
- add new bugs</ulink>.
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="q:mailingLists"
- xreflabel="Q: What mailing lists are there?">
- <para>What mailing lists are there?</para>
- </question>
- <answer>
- <para>
- The AspectJ users mailing list
- (<literal>aspectj-users@eclipse.org</literal>)
- provides an informal network of AspectJ language users who
- can answer usage questions about AspectJ programs
- and the AspectJ tools.
- This is the place to ask how to code something in AspectJ
- or how to write Ant or shell scripts to invoke the tools.
- </para>
- <para>
- The AspectJ developers mailing list
- (<literal>aspectj-dev@eclipse.org</literal>)
- provides an informal network of AspectJ technology experts who
- aim to understand the technology behind AspectJ.
- The committers to the AspectJ project use this list
- for open technical and planning discussions.
- Developers can answer questions about what's possible and about
- integrating AspectJ technology with other technologies.
- </para>
- <para>
- For both mailing lists, only subscribed members may post messages.
- To subscribe, visit the
- <ulink url="http://eclipse.org/aspectj">AspectJ web site</ulink>.
- </para>
- <para>
- There you can also subscribe to
- <literal>aspectj-announce@eclipse.org</literal>,
- a low-traffic list containing only announcements
- about significant AspectJ events and product releases.
- To get on a similar list for aspect-oriented software
- development generally, see
- <ulink url="http://aosd.net">http://aosd.net</ulink>.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="compiler" xreflabel="Using the AspectJ compiler">
- <title>Using the AspectJ compiler</title>
- <qandaentry>
- <question id="q:compilerRequired"
- xreflabel="Q:Do I have to use the AspectJ compiler?">
- <para>
- Do I have to use the AspectJ compiler?
- </para>
- </question>
- <answer>
- <para> The AspectJ compiler or weaver is required at some point, but
- many people can use AspectJ without changing their build or
- deployment process significantly. For aspects that are not
- required to compile, you can use the AspectJ binary weaver, run
- at build-time or class-load-time. You can write aspects using
- the original code style (which must be compiled with the AspectJ
- compiler) or using the annotation style new in AspectJ 5 (which
- may be compiled with Javac or the AspectJ compiler). </para>
- <para>
- For more information, see
- <xref linkend="q:codeversusannotationstyles"/>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:requiredsources"
- xreflabel="Q:What files do I need to include when compiling AspectJ programs?">
- <para>
- What files do I need to include when compiling AspectJ programs?
- </para>
- </question>
- <answer>
- <para>You need to specify to the compiler the files that
- contain your aspects and the files that contain the
- types affected by your aspects.
- See <xref linkend="q:knowWhenAspectsAffectClasses"/>.
- The AspectJ compiler will not search the source path for types
- that may be affected (unlike Javac and Jikes).
- In AspectJ 1.0, ajc requires all code to be in source form;
- in AspectJ 1.1, Java and AspectJ code may be in either source
- or binary form.
- </para>
- <para>In some cases you should compile your entire system all at once.
- If this is too slow, then you can try to make reasonable divisions
- between sets of source files whose aspects do not interact to
- achieve a shorter compile cycle (particularly for development
- aspects). If you have aspects that apply to different modules,
- you can try compiling them into a binary form and using them
- to weave each module. However, if you get any problems
- or if you wish to run tests or do a release, you should recompile
- the entire system.
- </para>
- <para>
- For more information, see the
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:listingsources"
- xreflabel="Q:Is there any other way to provide the file names to ajc?">
- <para>I have to list many files in the command line to
- compile with <literal>ajc</literal>. Is there any other way to
- provide the file names to <literal>ajc</literal>?
- </para>
- </question>
- <answer>
- <para>
- Yes, use the argfile option to ajc. List source
- files in a line-delimited text file and direct ajc to that
- file using <literal>-argfile</literal> or <literal>@</literal>:
- </para>
- <programlisting>ajc @sources.lst
- ajc -argfile sources.lst
- </programlisting>
- <para>Another way in AspectJ 1.1 is to use the
- <literal>-sourceroots</literal> options, which reads all
- source files in a given set of directories:
- </para>
- <programlisting>ajc -sourceroots "src;testsrc"
- </programlisting>
- <para>
- For more information, see the
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:compilerVM"
- xreflabel="Q: What Java virtual machine (JVM) do I use to run the
- AspectJ compiler? ">
- <para>What Java virtual machine (JVM) do I use to run the
- AspectJ compiler?
- </para>
- </question>
- <answer>
- <para>Use the latest, greatest, fastest JVM you can get your hands on
- for your platform. The compiler's performance is dependent on the
- performance of the JVM it is running on, so the faster a JVM you
- can find to run it on, the shorter your compile times will be. At a
- minimum you need to use a Java 2 or later JVM to run the compiler
- (J2SE 1.3 for AspectJ 1.1).
- We realize that this constraint can be a problem for users who
- don't currently have a Java 2 JVM available. We're sorry for the
- inconvenience, but we had to make the hard decision that the
- advantages of being able to rely on Java 2 were worth the cost of
- losing a number of developers who are working on platforms without
- Java 2 support. Here is a list of starting places where you might
- find support for your system.
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="http://java.sun.com/j2se/">Java 2
- Platform, Standard Edition
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink
- url="http://www-106.ibm.com/developerworks/java/jdk/">
- developerWorks : Java technology : Tools and products - Developer kits
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink
- url="http://www-124.ibm.com/developerworks/oss/jikes/">
- developerWorks : Open Source - Jikes Project
- </ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://java.sun.com/cgi-bin/java-ports.cgi">Java
- Platform Ports
- </ulink>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>The requirement of Java 2 support is only for
- <emphasis>running</emphasis> the AspectJ compiler. The AspectJ
- compiler can be used to build programs that will run on Java 1.1
- (or probably even on Java 1.0) systems. This means that it can
- build programs that will run on Macintosh, FreeBSD, and applets
- that will run in Internet Explorer and Netscape Navigator that are
- still not yet Java 2 compliant.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:compilingForDifferentVMs"
- xreflabel="Q: How to use ajc to compile for a different VM?">
- <para>How can I use <literal>ajc</literal> to compile
- programs for a JVM that is different from the one used to run it?
- </para>
- </question>
- <answer>
- <para>
- <literal>ajc</literal> can be used to develop programs that are
- targeted at the Java 1.1 platform, even though the
- <literal>ajc</literal> compiler won't run on that platform. Here's
- an example of using <literal>ajc</literal> in this sort of
- cross-compilation mode (assuming a Windows platform with all the
- default installation directories):
- </para>
- <programlisting>
- ajc -target 1.1 -bootclasspath c:\jdk1.1.7\lib\classes.zip \
- -classpath c:\aspectj1.0\lib\aspectjrt.jar -extdirs "" \
- -argfile jdk11system.lst
- </programlisting>
- <para>This same technique can be used if you want to run
- <literal>ajc</literal> on a JDK 1.3 JVM (highly recommended) but
- need to generate code for JDK 1.2. That would look something
- like:
- </para>
- <programlisting>
- ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \
- -classpath c:\aspectj1.0\lib\aspectjrt.jar \
- -extdirs c:\jdk1.2\jre\lib\ext
- -argfile jdk12system.lst
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:assert"
- xreflabel="Q:Does the ajc compiler support the assert keyword in Java 1.4?">
- <para>Does the <literal>ajc</literal> compiler support
- the <literal>assert</literal> keyword in Java 1.4?
- </para>
- </question>
- <answer>
- <para>Yes. As with <literal>Javac</literal>,
- use the <literal>-source 1.4</literal> option as described
- in the
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:generics"
- xreflabel="Q:Does the ajc compiler support generics and the other new language features of Java 5?">
- <para>Does the <literal>ajc</literal> compiler support
- generics and the other new language features of Java 5?
- </para>
- </question>
- <answer>
- <para>Yes. As with <literal>Javac</literal>,
- use the <literal>-1.5</literal> option as described
- in the
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:versionCompatibility"
- xreflabel="Q:Will AspectJ aspects work with different versions of the compiler/weaver and runtime?">
- <para>Will aspects work with different versions of the compiler/weaver and runtime?
- </para>
- </question>
- <answer>
- <para>Yes. Both <literal>ajc</literal> and
- <literal>aspectjrt.jar</literal> should work with versions
- of aspect code and libraries back to AspectJ 1.2.1.
- Any aspects should be deployed
- with the same version of <literal>aspectjrt.jar</literal>
- they were compiled with. For more information, see the
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>
- and
- <ulink url="devguide/deployment.html">
- Deployment notes</ulink> section on
- <ulink url="devguide/versionCompatibility.html">
- Version compatibility</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:msjvm"
- xreflabel="Q:Are there any issues using AspectJ with the Microsoft JVM?">
- <para>Are there any issues using AspectJ with the Microsoft
- JVM?
- </para>
- </question>
- <answer>
- <para>Since AspectJ requires Java 2 or later, it will not run on the
- Microsoft JVM, which does not support Java 2.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:javacbytecode"
- xreflabel="Q:Does ajc rely on javac for generating bytecode?">
- <para>Does <literal>ajc</literal> rely
- on <literal>javac</literal> for generating Java bytecode
- (<literal>.class</literal>) files?
- </para>
- </question>
- <answer>
- <para> No. Some previous versions of AspectJ had this requirement.
- In AspectJ 1.0, <literal>javac</literal> can still be used as
- <literal>ajc</literal> back end by using the
- <literal>-usejavac</literal> flag. You can also run <literal>ajc</literal>
- in preprocessor mode to generate Java source
- (<literal>.java</literal>) files to be compiled using
- <literal>javac</literal> or another java compiler.
- Neither option is supported in AspectJ 1.1.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:parsergenerators"
- xreflabel="Q:I noticed the AspectJ compiler doesn't use a parser generator. Why is that?">
- <para>
- I noticed the AspectJ compiler doesn't use a parser generator. Why is that?
- </para>
- </question>
- <answer>
- <para>In AspectJ 1.0,
- the PARSER for ajc is written by hand. This choice was made with full
- awareness of the generator tools out there. (Jim had for example used
- the excellent javacc tool for building the parser for JPython (now Jython)).
- One of the reasons that AspectJ uses a hand-written parser is that using
- javacc taught Jim about the LL-k design for parsers (pioneered by antlr).
- As opposed to the state-machine parsers produced by yacc, these parsers are
- very readable and writable by humans.
- </para>
- <para>
- Antlr and javacc did not really suit the project:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Antlr's support for unicode in the lexer is still immature and this makes
- using it with Java challenging. This was an even bigger issue 3 years ago
- when we started on the Java implementation of ajc.
- </para>
- </listitem>
- <listitem>
- <para>
- While javacc is freely available, it is not Open Source. Depending on a
- closed-source tool to build an Open Source compiler would reduce some
- of the transparency and control of open-source.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- There were also several things that were easier to implement with
- a hand-written parser than with any of the exiting tools.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Semi-keywords -- it's important to us that
- "every legal Java program is also a legal AspectJ program."
- This wouldn't be true if we made 'before' and 'call' full keywords in
- AspectJ. It is easier to support these sorts of semi-keywords with a
- hand-written parser. (Note: ajc-1.0.x handles 'aspect' and 'pointcut'
- slightly specially which can break a few unusual pure Java programs.
- This is a compiler limitation that will be fixed in a future release.)
- </para>
- </listitem>
- <listitem>
- <para>
- Deprecated syntax warnings -- the syntax of AspectJ
- changed many times from version 0.2 to the 1.0 release. It was easier
- to provide helpful warning messages for these changes with our
- hand-written parser.
- </para>
- </listitem>
- <listitem>
- <para>
- Grammar modularity -- We like being able to have
- AspectJParser extend JavaParser.
- </para>
- </listitem>
- <listitem>
- <para>
- Part of the grammar for AspectJ is extremely hard for existing tools to
- capture. This is the type pattern syntax, i.e. "com.xerox..*.*(..)".
- The sort of case that gives standard parser generators fits is something
- like "*1.f(..)" which no one would ever write, but which must be
- supported for a consistent language.
- </para>
- <para>
- In AspectJ 1.1, the parser was written as it is for the underlying
- Eclipse compiler,
- with some hand-coding of the sort that avoids adding keywords to
- the language.
- </para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:howIncrementalWorks"
- xreflabel="Q: How does incremental mode work?">
- <para>How does incremental mode work?
- </para>
- </question>
- <answer>
- <para>In incremental mode, ajc minimizes the files that need
- to be recompiled after another file has changed. In Java,
- only the changed files need to be recompiled, but in AspectJ,
- other files might also need to be recompiled or re-woven.
- </para>
- <para> Depending on what is modified, we may need to re-weave
- code. If you change a pointcut and save it, we currently have
- to check everywhere in case a new match is occurring or an old
- match is no longer correct. However, if you simply change
- the body of an advice in an aspect, there is (usually) no need
- to reweave as the affected classes call the advice and the
- advice (by design) maintains its name in the recompiled
- aspect. </para>
- <para> If you make a change to a class (as opposed to an aspect) and
- save it, we usually can get away with merely having to
- compile that class then weave the existing aspects with it -
- rather than doing a full recompile of the entire system.
- </para>
- <para> There are a lot of possible optimizations to the
- algorithms we use, by performing more complete analysis of
- the change made to a file that will enable us to know more
- accurately whether we need to reweave and if we do then what
- we need to reweave - we just haven't gotten around to
- implementing them yet. </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="devtools" xreflabel="Integrating AspectJ into your development environment">
- <title>Integrating AspectJ into your development environment</title>
- <qandaentry>
- <question id="q:knowWhenAspectsAffectClasses"
- xreflabel="Q: How do I know which aspects affect a class when looking at that class's source code?">
- <para>How do I know which aspects affect a class when looking
- at that class's source code?
- </para>
- </question>
- <answer>
- <para>When you are working with the IDE support, you can get an
- understanding of which aspects affect any class.
- This enables AspectJ programmers to get the benefits of
- modularizing crosscutting concerns while still having immediate
- access to what aspects affect a class.
- </para>
- <para>
- See <xref linkend="q:integrateWithDevTools"/> for more
- information on which Java development environments are
- supported.)
- </para>
- <para>
- When you are looking at documentation for AspectJ 1.0 programs,
- <literal>ajdoc</literal> will provide links from aspects and
- advice to the affected code, but it provides less information
- than the IDE support because it only parses declarations.
- </para>
- <para>
- When you are compiling your program, pointcuts that are
- statically-determinable can be used in declare statements
- to identify the code picked out by the pointcut.
- (A pointcut is statically determinable if it only uses
- the pointcut designators
- <literal>within</literal>,
- <literal>withincode</literal>,
- <literal>execution</literal>,
- <literal>call</literal>,
- <literal>get</literal>,
- <literal>set</literal>,
- <literal>initialiation</literal>, and
- <literal>staticinitialiation</literal>.)
- The compiler will list the static code points which will be
- affected by any advice specifying the same pointcut.
- For example, the following will print a warning
- whereever some code in class Bar gets a field value from Foo:
- <programlisting>
- declare warning: get(* Foo.*) && within(Bar)
- : "reading Foo state from Bar";
- </programlisting>
- </para>
- <para>
- When you are running your program,
- you can trace advice as it executes. This
- enables you to identify advice on join points picked out
- dynamically, which cannot be reflected precisely by IDE support.
- For a related tracing question,
- see <xref linkend="q:seeingjoinpoints"/>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:idesupport"
- xreflabel="Q:What kind of IDE support is available for developing AspectJ programs?">
- <para>What kind of IDE support is available for developing
- AspectJ programs?
- </para>
- </question>
- <answer>
- <para>See <xref linkend="q:integrateWithDevTools"/></para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:idesupportplans"
- xreflabel="Q:What plans are there to support my IDE?">
- <para>What plans are there to support my IDE?</para>
- </question>
- <answer>
- <para>
- The AspectJ team directly provided components for JBuilder, Forte,
- and Emacs and supported the open-source AspectJ plugin project
- at <ulink url="http://eclipse.org/ajdt">http://eclipse.org/ajdt</ulink>
- which uses the AJDE API support for IDE's.
- Supporting new IDE's is a matter of building on the AJDE API's,
- mostly likely adopting one of the existing open-source IDE
- extensions as a design template.
- Here are the IDE's where we know people have expressed interest,
- so interested developer may want to join with others in their
- developer communities to build the integration.
- <itemizedlist>
- <title></title>
- <listitem>
- <para>IDEA/IntelliJ has an enthusiastic community and
- the developers are working on an extensibility API
- - <ulink url="http://intellij.com">http://intellij.com</ulink>
- </para>
- </listitem>
- <listitem>
- <para>jEdit comes from a very active open-source community.</para>
- </listitem>
- <listitem>
- <para>
- Oracle JDeveloper is supported at
- <ulink url="https://jdeveloperaop.dev.java.net/">
- https://jdeveloperaop.dev.java.net/</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>Some have suggested Codeguide from Omnicore
- <ulink url="http://www.omnicore.com">http://www.omnicore.com/</ulink>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- For questions on AJDE, join the developer's list
- <literal>aspectj-dev@eclipse.org</literal>.
- For questions on the current IDE integrations, contact those projects.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:portingajde"
- xreflabel="Q:Can I port AJDE support to my development environment?">
- <para>Can I port AJDE support to my development environment?</para>
- </question>
- <answer>
- <para>Yes. The core AJDE API is extensible and the source code is
- available for download. Start by studying the sources
- for the existing IDE support linked off the AspectJ site
- <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:hybridbuilds"
- xreflabel="Q:Setting up hybrid builds">
- <para>I want the aspects for development builds but
- remove them for production builds. How can I set up the build
- system so they are unpluggable? And so I use <literal>javac</literal>
- in my production build?
- </para>
- </question>
- <answer>
- <para>
- If you are using development-time-only aspects - aspects that only
- exist when you are developing the code, not when you ship it -
- you can use implement a hybrid build process by listing
- the production source files into a javac-compliant argfile,
- and the development source files in another ajc argfiles:
- </para>
- <programlisting>
- -- file "production.lst":
- One.java
- two/Three.java
- ...
-
- -- file "tracing.lst":
- trace/Library.java
- Trace.java
-
- -- file "development.lst":
- @production.lst
- @tracing.lst
- </programlisting>
- <para>
- Then your development build can use <literal>ajc</literal>:
- </para>
- <programlisting>
- ajc @development.lst
- </programlisting>
- <para>
- And your development build can use
- <literal>ajc</literal> or <literal>javac</literal>
- or <literal>jikes</literal>:
- </para>
- <programlisting>
- jikes @production.lst
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:stepwiseBuilds"
- xreflabel="Q:We compile module jars and then assemble them. Can we continue this with AspectJ?">
- <para>
- We compile module jars and then assemble them. Can we continue this with AspectJ?
- </para>
- </question>
- <answer>
- <para>
- Aspects apply to everything in a namespace, as if everything is
- compiled together.
- Sometimes you can break the build down into separate steps without breaking
- this model, but we haven't stated exactly where it could break
- because it depends on the interactions between all types.
- You can try the approaches below, but remember to rebuild
- everything in one go if there are problems.
- </para>
- <para>
- The simplest scenario is when the aspects apply to all modules
- and the modules compile without the aspects. In that case,
- weaving in the aspects is just the final assembly step for
- the build.
- </para>
- <para>
- Next is the case where the aspects make changes to a common
- library that are visible to other clients, which themselves
- are otherwise unaffected by the aspects. In this case, the
- common library can be built using ajc, and used on the
- classpath for the module builds:
- <programlisting><![CDATA[
- ajc -outjar common.jar -sourceroots "aspectj-src:src" ...
- cd ../otherProject
- javac -classpath "../common/common.jar:${aspectjrt.jar}" {src}
- ]]></programlisting>
- </para>
- <para>
- Combining these last two,
- there's the case where a common set of aspects should
- affect two or more modules that are in a dependency relationship
- to one another. It should work to reuse the aspects
- in binary form for each compile, in dependency order:
-
- <programlisting><![CDATA[
- ajc -outjar common-aspects.jar
- -sourceroots "aspectj-src" ...
-
- ajc -outjar common.jar
- -sourceroots "src"
- -aspectpath common-aspects.jar ...
-
- cd ../module1
- ajc -outjar module1.jar
- -sourceroots "src"
- -classpath common.jar
- -aspectpath ../common-aspects.jar ...
-
- cd ../module2
- ajc -outjar module2.jar
- -sourceroots "src"
- -classpath "common.jar;../module1.jar"
- -aspectpath ../common-aspects.jar ...
- ]]></programlisting>
- </para>
- <para>
- If two modules are visibly affected by aspects and
- mutually-dependent, the only thing to do is compile
- them together.
- </para>
- <para>
- It's safest to assume that all aspects can affect all
- types in a namespace; using build boundaries to effect
- crosscutting limits causes a dangerous dependency on
- the build process and might cause problems.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:incrementalModuleCompiles"
- xreflabel="Q: We use modules and would like to use incremental compilation.
- Is that possible?">
- <para>We use modules and would like to use incremental compilation.
- Is that possible?
- </para>
- </question>
- <answer>
- <para>
- Just incrementally-compile the whole system.
- Specify to ajc the modules as multiple source roots
- (or input jars if you are weaving libraries).
- </para>
- <para>
- In Eclipse's AJDT, you can create a top-level project with symbolic
- links out to the sources:
-
- <programlisting><![CDATA[
- app-assembly/
- {link common/aspects}
- {link common/src}
- {link module1/src}
- ...
- ]]></programlisting>
-
- Then everything is part of one huge incremental compile. Also, you
- can close this master project and work the others using the Java
- compiler or AJDT.
- </para>
- <para>
- The links make incremental development possible without affecting
- the modularized Ant builds. (Our practice runs along those lines.)
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="notes" xreflabel="Programming notes and tips">
- <title>Programming notes and tips</title>
- <qandaentry>
- <question id="q:methodsignatures"
- xreflabel="Q:Is it possible to change methods by introducing keywords, adding parameters, or changing the throws clause?">
- <para>Is it possible to change methods by introducing keywords (like
- <literal>synchronized</literal>), adding parameters,
- or changing the "throws" clause?
- </para>
- </question>
- <answer>
- <para>AspectJ does not enable you to change the signature of a method,
- but you can (by express declaration) work around some
- limits imposed by the signature. You can convert a checked exception to
- unchecked using <literal>declare soft</literal>, privileged aspects
- have access to private methods, and you can use a percflow aspect to
- ferry additional state to a callee without changing intervening
- signatures. For more details, see
- <ulink url="progguide/index.html">The AspectJ Programming Guide</ulink>.
- In the case of <literal>synchronized</literal>,
- we have what we consider a better solution that uses
- around advice instead of introduction. This solution is described
- in
- <ulink url="http://aspectj.org/pipermail/users/2000/000534.html">
- this thread (no longer available)
- </ulink> on the AspectJ users list, with some
- <ulink url="http://aspectj.org/pipermail/users/2000/000536.html">
- additional comments (no longer available)
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:seeingjoinpoints"
- xreflabel="Q:I don't understand what join points exist. How can I see them?">
- <para>
- I don't understand what join points exist. How can I see them?
- </para>
- </question>
- <answer>
- <para>
- You can trace them using using an aspect.
- For example, you can start logging at a particular method call and
- see what join points occur after the call and before it returns.
- </para>
- <para>
- Here's some code Jim Hugunin wrote to trace join points
- and posted to the users list. To reuse the aspect,
- define a subaspect and implement the pointcuts, for example:
- <programlisting>
- aspect JoinPointSampleAspect extends aj.TraceJoinPoints {
- protected pointcut entry() :
- execution(static void JoinPointSample.main(String[]));
- protected pointcut exit() :
- call(static void JoinPointSampleAspect.exit());
-
- public static void main (String[] args) {
- JoinPointSample.main(args);
- JoinPointSampleAspect.exit();
- }
- public static void exit() {}
- }
-
- class JoinPointSample {
- public static void main(String[] args) {}
- }
- </programlisting>
- </para>
- <para>Here's the aspect:
- <programlisting><![CDATA[
- /* TraceJoinPoints.java */
-
- package aj;
-
- import org.aspectj.lang.*;
- import org.aspectj.lang.reflect.*;
- import java.io.*;
-
- public abstract aspect TraceJoinPoints {
- protected abstract pointcut entry();
- protected pointcut exit(): call(* java..*.*(..));
- // this line is for AspectJ 1.1; for 1.0, use "dominates"
- declare precedence : TraceJoinPoints, *;
- final pointcut start(): entry() && !cflowbelow(entry());
-
- final pointcut trace():
- cflow(entry()) && !cflowbelow(exit()) && !within(TraceJoinPoints+);
-
- before(): start() { makeLogStream(); }
-
- before(): trace() { logEnter(thisJoinPointStaticPart); }
- after(): trace() { logExit(thisJoinPointStaticPart); }
-
- after(): start() { closeLogStream(); }
-
- //------------ added
- /**
- * Emit a message in the log, e.g.,
- * <pre>TraceJoinPoints tjp = TraceJoinPoints.aspectOf();
- * if (null != tjp) tjp.message("Hello, World!");</pre>
- */
- public void message(String s) {
- out.println("<message>" + prepareMessage(s) + "</message>");
- }
- public void message(String sink, String s) {
- if (null == sink) {
- message(s);
- } else {
- out.println("<message sink=" + quoteXml(sink)
- + " >" + prepareMessage(s) + "</message>");
- }
- }
- protected String prepareMessage(String s) { return s; } // XXX implement
-
- //--------- end of added
-
- PrintStream out;
- int logs = 0;
- protected void makeLogStream() {
- try {
- out = new PrintStream(new FileOutputStream("log" + logs++ + ".xml"));
- } catch (IOException ioe) {
- out = System.err;
- }
- }
-
- protected void closeLogStream() {
- out.close();
- }
-
-
- int depth = 0;
- boolean terminal = false;
- protected void logEnter(JoinPoint.StaticPart jp) {
- if (terminal) out.println(">");
- indent(depth);
- out.print("<" + jp.getKind());
- writeSig(jp);
- writePos(jp);
-
- depth += 1;
- terminal = true;
- }
-
- void writeSig(JoinPoint.StaticPart jp) {
- out.print(" sig=");
- out.print(quoteXml(jp.getSignature().toShortString()));
- }
-
- void writePos(JoinPoint.StaticPart jp) {
- SourceLocation loc = jp.getSourceLocation();
- if (loc == null) return;
-
- out.print(" pos=");
- out.print(quoteXml(loc.getFileName() +
- ":" + loc.getLine() +
- ":" + loc.getColumn()));
- }
-
- String quoteXml(String s) {
- return "\"" + s.replace('<', '_').replace('>', '_') + "\"";
- }
-
- protected void logExit(JoinPoint.StaticPart jp) {
- depth -= 1;
- if (terminal) {
- out.println("/>");
- } else {
- indent(depth);
- out.println("</" + jp.getKind() + ">");
- }
- terminal = false;
- }
-
- void indent(int i) {
- while (i-- > 0) out.print(" ");
- }
- }
- ]]></programlisting>
- </para>
- <para>Note that if you are using AspectJ 1.0,
- the line starting with <literal>declare precedence</literal>
- would be removed, and the aspect declaration would look like
- <literal>aspect TraceMyJoinPoints dominates *</literal>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:comparecallandexecution"
- xreflabel="Q:What is the difference between call and execution join points?">
- <para>
- What is the difference between call and execution join points?
- </para>
- </question>
- <answer>
- <para>
- Briefly, there are two interesting times when a constructor or method is
- run. Those times are when it is called, and when it actually
- executes.
- </para>
- <para>
- The main difference is that a call join point happens outside of
- the target object (for non-static methods) or class (for static methods
- and constructors), and that an execution join point happens inside
- the object or class. This means that the <literal>within</literal>
- and <literal>withincode</literal> pointcuts pick them out
- differently: A call join point is picked out within the caller,
- while an execution join point is picked
- out where it is actually defined.
- </para>
- <para>
- A call join point is the ``outermost'' join point for a particular
- call. Once a call join point proceeds, then a number of different
- things happen. For non-static methods, for example, method
- dispatch happens, which will cause one method execution join point
- -- perhaps more, if there are super calls. For constructors, the
- super constructor is called, and fields are initialized, and then
- various constructor execution join points will occur.
- </para>
- <para>
- A call join point matches only the ``external'' calls of a method
- or constructor, based on a signature, and it does not pick out
- calls made with <literal>super</literal>, or
- <literal>this</literal> constructor calls.
- </para>
- <para>Here's more detail:
- </para>
- <para>Consider method execution in Java as (1) the initial call from
- this object to some method on the target object with a
- particular signature; and (2) the execution of the actual code
- in the particular method dispatched in the target object.
- The call join point starts with the initial call and ends
- when control returns to the call (by return or perhaps
- thrown exception). The execution join point starts with
- the method body and ends when the body completes (again
- by return or throwing an exception), so the execution join
- point always happens within the bounds of the corresponding
- call join point. You can see this if you use the
- join-point tracing aspect in see <xref linkend="q:seeingjoinpoints"/>.
- </para>
- <para>As you would expect, the context differs
- in advice on pointcuts picking out execution and call join
- points; for call, <literal>this</literal> refers to the caller, whereas
- for execution <literal>this</literal> refers to the called
- (executing) object.
- </para>
- <para>
- There are some subtle interactions with other AspectJ semantics.
- First, the meaning of the signature in the
- <literal>execution()</literal> and <literal>call()</literal>
- pointcut designators (PCD's) differ: the call type depends upon
- the type of the reference making the call, while the execution
- type depends on the enclosing class.
- Second, you may choose one over another if you cannot bring all
- your sources within the code the compiler controls
- (described in the <ulink url="progguide/semantics.html">appendix</ulink>
- to the <literal>Programming Guide</literal>).
- For example, to trace calls into a
- method from classes which are outside the code the compiler controls
- at compile time, then using <literal>execution()</literal> will work
- while using <literal>call()</literal>may not. Finally, since
- <literal>super</literal> invocations are not considered method calls,
- to trace <literal>super.foo()</literal> would require using
- <literal>execution</literal>.
- </para>
- <para>
- Because of differences in the way AspectJ 1.0 and 1.1
- are implemented, in 1.0
- you should use the <literal>call()</literal>
- pointcut designator unless you have a good reason to use
- <literal>execution()</literal>; in AspectJ 1.1, the
- reverse is true.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:comparecflowandcflowbelow"
- xreflabel="Q:What is the difference between cflow and cflowbelow?">
- <para>
- What is the difference between cflow and cflowbelow?
- </para>
- </question>
- <answer>
- <para>
- Both pick out all the join points in the control flow of
- the specified join points.
- They differ only in that the <literal>cflowbelow()</literal>
- pointcut designator does not pick out the join points
- specified, while <literal>cflow()</literal> does.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:recursiveentrypoints"
- xreflabel="Q:How do I say that I want the topmost entrypoint in a recursive call?">
- <para>How do I say that I want the topmost entrypoint in a
- recursive call? How about the most-recent prior entrypoint?
- </para>
- </question>
- <answer>
- <para>This is best seen by way of example.
- Given a recursive call to <literal>int factorial(int)</literal>
- you can print the arguments for
- (a) the current and most-recent recursive call
- or (b) the current and original recursive call:
- </para>
- <programlisting>
- aspect LogFactorial {
- pointcut f(int i) : call(int factorial(int)) && args(i);
-
- // most-recent
- before(int i, final int j) : f(i) && cflowbelow(f(j)) {
- System.err.println(i + "-" + j);
- }
-
- // original
- before(int i, final int j) : f(i)
- && cflowbelow(cflow(f(j)) && !cflowbelow(f(int))) {
- System.err.println(i + "@" + j);
- }
- }
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:initializationjoinpoints"
- xreflabel="Q:What is the difference between constructor call, constructor execution, initialization, and static initialization join points?">
- <para>What is the difference between constructor call,
- constructor execution, initialization, and static
- initialization join points?
- </para>
- </question>
- <answer>
- <para>Static initialization pertains to initialization of
- a class or interface type. Constructor call and execution
- are akin to method call, and initialization generalizes this and
- picks out the first constructor called.
- </para>
- <para>Their relations are best
- demonstrated by tracing the join points. Below is the class
- Test which implements an interface and extends a class
- along with a trace of the join points below and including
- the constructor call obtained using
- <literal>TraceJointPoints.java</literal>
- from <xref linkend="q:seeingjoinpoints"/>.
- </para>
- <programlisting><![CDATA[
- public class Init {
- public static void main (String[] args) {
- new Test();
- end();
- }
- static void end() {}
- }
- class Super {}
- interface I {}
- class Test extends Super implements I {
- Test() {}
- }
- ]]></programlisting>
- <para>For a program compiled with AspectJ 1.0,
- the result is this:</para>
- <programlisting><![CDATA[
- <constructor-call sig="Test()" >
- <staticinitialization sig="Super._init_" />
- <staticinitialization sig="Test._init_" />
- <initialization sig="Super()" >
- <instanceinitializer-execution sig="Super._init_" />
- <constructor-execution sig="Super()" />
- </initialization>
- <initialization sig="I()" >
- <instanceinitializer-execution sig="I._init_" />
- <constructor-execution sig="I()" />
- </initialization>
- <initialization sig="Test()" >
- <instanceinitializer-execution sig="Test._init_" />
- <constructor-execution sig="Test()" />
- </initialization>
- </constructor-call>
- ]]></programlisting>
- <para>
- Ordinarily, using a <literal>call</literal> pointcut designator
- is best because the call join point surrounds the others, but in
- the case of constructors there is no target object for
- the call (because it has not been constructed yet), so you
- might prefer to use the <literal>initialization</literal>
- pointcut designator.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:adviseconstructors"
- xreflabel="Q:How do I work with an object right when it is created?">
- <para>How do I work with an object right when it is created?
- </para>
- </question>
- <answer>
- <para>
- You can advise some form of constructor join point.
- Constructors are tricky in Java, and that's exposed in AspectJ.
- Here are some rules of thumb:
- <itemizedlist>
- <listitem>
- <para>If you want the join point on the "outside" of object creation,
- use after returning from call to the constructor:
- </para>
- <programlisting>
- after() returning (Foo newlyCreatedObject): call(Foo.new(..)) { ... }
- </programlisting>
- <para>
- You might be tempted to use "this" or "target" to expose the new object, but remember
- that if you're on the "outside" of object creation, the object itself might not be
- created yet... it only exists "on the way out", when you return the object.
- </para>
- </listitem>
- <listitem>
- <para>If you want the join point inside a particular constructor, use:
- </para>
- <programlisting>
- after(Foo newlyCreatedObject) returning: this(newlyCreatedObject) && execution(Foo.new(..)) { ... }
- </programlisting>
- <para>
- Remember, though, that if you use "before" advice here, the body of the constructor
- will not have run, and so the object may be somewhat uninitialized.
- </para>
- </listitem>
- <listitem>
- <para>
- In the rare case that there are all sorts of constructors for the object that call
- each other with <literal>this(...)</literal> and you want exactly one join point
- for each initialization of <literal>Foo</literal>, regardless of the path of
- constructors it takes, then use:
- </para>
- <programlisting>
- after(Foo f) returning: this(f) && initialization(Foo.new(..)) { ... }
- </programlisting>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:andingpointcuts"
- xreflabel="Q:I want advice to run at two join points, but it doesn't run at all.">
- <para>
- I want advice to run at two join points, but it doesn't run at all. What gives?
- </para>
- </question>
- <answer>
- <para>
- This usually reflects both a conceptual error and a programming mistake.
- Most likely you want to do something like "run the advice for all
- public and private calls," and the code looks something like this:
- </para>
- <programlisting>
- within(com.xerox.printing..*) && call(public * *(..)) && call(private * *(..))
- </programlisting>
- <para>
- But a pointcut is evaluated at *each* join point.
- The expression above would never pick out any call join point,
- because no method signature has both public and private access.
- In a pointcut, <literal>pc1() && pc2()</literal> means both
- must be true at a given join point for advice to run at that join point.
- The correct pointcut would use <literal>||</literal> as follows:
- </para>
- <programlisting>
- within(com.xerox.printing..*) && (call(public * *(..)) || call(private * *(..)))
- </programlisting>
- <para>
- Then the advice will run at the join point.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:staticfieldreferences"
- xreflabel="Q:How do I refer to a static field when my advice crosscuts multiple classes?">
- <para>
- How do I refer to a static field when my advice crosscuts multiple classes?
- </para>
- </question>
- <answer>
- <para>There is no way in advice to refer to the type of the
- code executing in a static context except by specification.
- This makes it impossible to refer to static members using
- runtime information.
- </para>
- <para>However, AspectJ can determine the class for something
- in the join point context, which you can use as a per-class key.
- Then you can actually declare an instance field to contain
- the per-class value (see the next question). This comes at
- the cost of an extra reference, but the field can be final.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:interfacesastypepatterns"
- xreflabel="Q:How can I reuse a type pattern?">
- <para>I would like to reuse a type pattern, e.g., to
- write advice that is limited to a certain set of classes.
- Do I have to retype it each time?
- </para>
- </question>
- <answer>
- <para>No. You can declare that all the types implement
- an interface you define, and then use the interface type in
- your program. For example:
- </para>
- <programlisting>
- /**
- * Example of using an interface to represent a type pattern.
- * sub-aspects use declare parents to add to traced types, e.g.,
- * declare parents: com.mycompany.whatever..* implements Marked;
- */
- abstract aspect MarkerExample {
- /** marker interface for types that we want to trace */
- interface Marked {}
-
- /** calls to an instance of Marked not from an instance of Marked */
- pointcut dynamicCallsIn(): call(* *(..)) && target(Marked) && !this(Marked);
-
- /** calls to methods defined by a subtype of Marked
- * that don't come from the body of a subtype of Marked
- */
- pointcut staticCallsIn(): call(* Marked+.*(..)) && !within(Marked+);
-
- /** print dynamic calls */
- before(): dynamicCallsIn() { System.out.println("before " + thisJoinPoint); }
- }
-
- aspect MyMarker extends MarkerExample {
- declare parents: com.mycompany.whatever..* implements Marked;
- }
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:exampleprograms"
- xreflabel="Q:Where do I find example programs and how-to's?">
- <para>Where do I find example programs and how-to's?</para>
- </question>
- <answer>
- <para>There are a number of places to find sample code
- and instructions for using AspectJ with other programming tools.
- <orderedlist>
- <listitem><para>
- The AspectJ release includes examples in its
- <literal>doc</literal> directory.
- </para></listitem>
-
- <listitem><para>
- There is a community repository of sample code and tutorials
- in the AspectJ CVS tree
- <literal>docs</literal> module <literal>sandbox</literal> directory.
- These are extracted and published (online only)
- <ulink url="http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/aspectj-home/sample-code.html">
- here
- </ulink>.
- </para></listitem>
-
- <listitem><para>
- The <literal>teaching</literal> directory of the
- <literal>docs</literal> module contains public materials
- the AspectJ committers use for presentations, some of
- which include example code. To access CVS, see
- <xref linkend="q:buildingsource"/>.
- </para></listitem>
-
- <listitem><para>
- The archives for the user and developer mailing lists
- contain many good examples. To search the archives, see
- <xref linkend="q:searchingsite"/>.
- </para></listitem>
- </orderedlist>
- This code can vary in quality.
- Code that we publish or include with AspectJ is generally
- correct. However, code found in our CVS tree might not have
- been tested thoroughly, and code from the mailing lists might
- be untested or use older versions of the language.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectlibraries"
- xreflabel="Q:Are aspect libraries available?">
- <para>Are aspect libraries available?</para>
- </question>
- <answer>
- <para>Some libraries are distributed in the release under the
- examples folder in the distribution.
- These are "libraries" in the sense that they are reusable,
- but they are delivered in source form.
- Similarly, some of the sample code is reusable; for that,
- see <xref linkend="q:exampleprograms"/>.
- If you develop such a library and want to make it available to
- other users, feel to send it to the users mailing list
- <literal>aspectj-users@eclipse.org</literal>.
- </para>
- <para>In AspectJ 1.1, ajc supports binary aspects, so
- you can distribute aspect libraries without distributing the
- source. For more information, see the
- <literal>-aspectpath</literal>
- option in the
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:serialversionuid"
- xreflabel="Q:How does ajc interact with the serialVersionUID?">
- <para>How does <literal>ajc</literal> interact with the
- <literal>serialVersionUID</literal>?
- </para>
- </question>
- <answer>
- <para>The current version of <literal>ajc</literal> can change the
- <varname>serialVersionUID</varname> of generated
- <filename>.class</filename> files as a result of weaving in advice.
- This is an important fact that developers using both aspects and
- serialization should be aware of. It is likely that a future
- version of the compiler will be better behaved regarding the
- <varname>serialVersionUID</varname>.
- </para>
- <para>However, changes to the <literal>serialVersionUID</literal>
- attribute are typically only important when using serialization for
- the long-term persistence of objects. Using standard Java
- serialization for long-term persistence has a number of drawbacks
- and many developers already use alternative solutions. For one
- possibly standard solution, see
- <ulink url="http://jcp.org/jsr/detail/057.jsp">
- Long-Term Persistence for JavaBeans Specification
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:applets"
- xreflabel="Q:How can I use AspectJ with applets?">
- <para>How can I use AspectJ with applets?</para>
- </question>
- <answer>
- <para>
- Just include the aspectjrt.jar as a required archive.
- For example, here is the HTML code for an HTML editor
- applet that contains some debugging aspects:
- </para>
- <programlisting><![CDATA[
- <APPLET
- CODE='com.company.swing.applets.EditorApplet'
- WIDTH='700'
- HEIGHT='525'>
- <PARAM NAME="CODE" VALUE="com.company.swing.applets.EditorApplet" >
- <PARAM NAME="ARCHIVE"
- VALUE ="../company-applets.jar,../aspectjrt.jar,../xmlrpc-applet.jar" >
- <PARAM NAME="type" VALUE="application/x-java-applet;version=1.4">
- <PARAM NAME="scriptable" VALUE="false">
- </APPLET>
- ]]></programlisting>
- <para>
- The above markup has worked reliably with the Java Plugin
- (included in the JRE 1.4.x) in IE 6, Mozilla 1.1 (Win32),
- and Mozilla 1.0.1 (Red Hat Linux 8.0).
- The following link describes how to configure Mozilla/Netscape
- 6.x/7.x to use the Java Plugin from a JRE/SDK installation:
- <ulink url="http://java.sun.com/j2se/1.4.1/manual_install_linux.html">
- http://java.sun.com/j2se/1.4.1/manual_install_linux.html</ulink>.
- (Thanks to Chris Bartling for this answer.)
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:typeoblivious"
- xreflabel="Q:How can I specify types for advice that captures primitives, void, etc.?">
- <para>How can I specify types for advice that captures primitives, void, etc.?</para>
- </question>
- <answer>
- <para>
- In some cases, AspectJ allows conversion from values of primitive types to Object,
- so that highly polymorphic advice may be written. This works if an advice parameter
- or the return type for around is typed to Object. So:
- </para>
- <programlisting>
- class Test {
- static int i;
- public static void main(String[] args) {
- i = 37;
- }
- }
-
- aspect TraceSet {
- before(Object val): set(* Test.*) && args(val) {
- System.err.println(val);
- System.err.println(val.class);
- }
- }
- </programlisting>
- <para>
- will print out
- </para>
- <programlisting>
- 37
- java.lang.Integer
- </programlisting>
- <para>
- For more information, see the Programming Guide
- <ulink url="progguide/semantics-pointcuts.html">
- semantics section "Context Exposure"
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:versioninfo"
- xreflabel="Q:How do I detect which version I am running?">
- <para>How do I detect which version I am running?</para>
- </question>
- <answer>
- <para>The <literal>ajc</literal>
- compiler emits the version when passed the
- <literal>-version</literal> flag as an argument.
- </para>
- <para>To programmatically
- detect the version of the AspectJ runtime while running
- under Java 1.4 or later, get the version from the package:
- <programlisting>
- Package lang = org.aspectj.lang.JoinPoint.class.getPackage();
- String version = lang.getImplementationVersion();
- </programlisting>
- </para>
- <para>When running under Java 1.3 or earlier, read the manifest
- directly. For example code, see the source for
- <literal>AjBuildManager.checkRtJar(AjBuildConfig)</literal>
- in the <literal>org.aspectj.ajdt.internal.core.builder</literal>
- package of the <literal>org.aspectj.ajdt.core</literal> module,
- available as described in
- <xref linkend="q:buildingsource"/>.
- </para>
- <para>Note that the version of AspectJ for the tools in
- <literal>aspectjtools.jar</literal> is in
- <literal>org.aspectj.bridge.Version</literal>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:synchronizedAdvice"
- xreflabel="Q:How do I write synchronized advice?">
- <para>How do I write synchronized advice?</para>
- </question>
- <answer>
- <para>The only modifier advice can take is <literal>strictfp</literal>.
- However, you can enclose the body of the advice in a synchronized
- clause:
- <programlisting>
- before() : pc() {
- synchronized (this) {
- // advice code here
- }
- }
- </programlisting>
- </para>
- <para>It should not be necessary to synchronize a percflow aspect,
- but you might do this for perthis, pertarget, or issingleton (default)
- aspects. To serialize advice in multiple aspects, synchronize on a
- lock object available (only) to the aspects.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="problems" xreflabel="Common Problems">
- <title>Common Problems</title>
- <qandaentry>
- <question id="q:infiniterecursion"
- xreflabel="Q:When I run, I get a StackOverflowError or no output.">
- <para>When I run, I get a <literal>StackOverflowError</literal>
- (or a long stack trace or no output whatsoever)
- </para>
- </question>
- <answer>
- <para>Most likely this is a case of infinite recursion,
- where advice is advising itself. It presents as a
- <literal>StackOverflowError</literal>
- or silence as the VM exhausts itself in the recursion.
- </para>
- <para>Of course, infinite recursion is possible in Java:</para>
- <programlisting>
- public class Main {
- public static void main(String[] args) {
- try {
- main(args);
- } finally {
- main(args);
- }
- }
- }
- </programlisting>
- <para>If you compile and run this program, and it will fail silently, trying
- to process the finally clause even after throwing the StackOverflowError.
- </para>
- <para>Here's a similar AspectJ program where the recursion is
- not so obvious:
- </para>
- <programlisting>
- aspect A {
- after(): call(* *(..)) { System.out.println("after " + thisJoinPoint); }
- }
- </programlisting>
- <para>This re-invokes itself because it advises any call.
- It invokes itself even after an exception is thrown, since
- <literal>after</literal> advice, like a finally clause, runs even
- after exceptions are thrown. You can fix this by following two practices:
- </para>
- <para>In AspectJ 1.1, the String concatenation operator (+) is
- advised in its StringBuffer form, so if your advise uses
- String + in a way that is picked out by your pointcut,
- you will get infinite recursion.</para>
- <para>
- (1) Use <literal>after returning</literal> to advise normal completions
- or <literal>after throwing</literal> to advise abrupt completions.
- If you use <literal>after</literal> or <literal>after throwing</literal>,
- write the advice with the same care you would a finally clause,
- understanding that it may run after some failure.
- </para>
- <para>(2) Avoid writing advice that advises itself. One simple way to
- do so is to exclude the code within the current aspect:
- </para>
- <programlisting>
- aspect A {
- after() returning: !within(A) && call(* *(..)) {
- System.out.println("after " + thisJoinPoint);
- }
- }
- </programlisting>
- <para>A better way is often to re-write the pointcut.
- If the advice is advising itself accidentally, that's a sign that
- the pointcut is not saying what you mean.
- </para>
- <programlisting>
- aspect A {
- pointcut withinTargetClasses() : within(A+) || within(B+);
- after() returning: withinTargetClasses() && call(* *(..)) {
- System.out.println("after " + thisJoinPoint);
- }
- }
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:typelessdeclarations"
- xreflabel="Q:I've declared a field on every class in my package; how do I use it in advice?">
- <para>I've declared a field on every class in
- my package; how do I use it in advice?
- </para>
- <programlisting>
- aspect A {
- boolean com.xerox..*.dirtyFlag;
- after (Object target) returning
- : target(target) && call(* com.xerox..*.set*(..)) {
- target.dirtyFlag = true; // compile fails here
- }
- }
- </programlisting>
- </question>
- <answer>
- <para>You need a type to refer to any member, field or method.
- It's generally better to introduce onto an interface and
- declare classes to implement the interface, which permits you
- to use the interface type in advice formals.
- </para>
- <programlisting>
- aspect A {
- interface TrackingSets {}
- boolean TrackingSets.dirtyFlag;
- declare parents : com.xerox..* implements TrackingSets;
-
- after (TrackingSets target) returning
- : target(target) && call(* com.xerox..*.set*(..)) {
- target.dirtyFlag = true;
- }
- }
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ajcoom"
- xreflabel="Q:The AspectJ compiler aborts with an OutOfMemoryError when compiling many classes. How can I fix this?">
- <para>The AspectJ compiler aborts with an OutOfMemoryError when
- compiling many classes. How can I fix this?
- </para>
- </question>
- <answer>
- <para><literal>ajc</literal> can use more memory than a javac
- compile of the corresponding pure-java sources when aspects
- are added to the mix. You'll need to increase the memory
- available.
- </para>
- <para>The command <literal>ajc</literal> is actually a script that
- launches a Java virtual machine with the correct classpath. You
- should make a copy of this script, rename it, and then edit it.
- Change the -Xmx option, size of memory allocation pool (heap). You
- might try <literal>-Xmx128M</literal> or even
- <literal>-Xmx256M</literal>.
- </para>
- <para>When running under Ant, give Ant more memory or
- use the <literal>fork</literal> option together with
- the <literal>Xmaxmem</literal> option.
- </para>
- <para>When running under an IDE, look to the documentation
- for the IDE to determine how to increase available memory.
- </para>
- <para>In either case, doing incremental compilations can hold on to
- more memory than a one-shot compile process, as the compiler
- trades space for time in recompiles.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:duplicateclass"
- xreflabel="Q:Why do I get a message that my class is already defined?">
- <para>
- Why do I get a message that my class is already defined?
- </para>
- </question>
- <answer>
- <para>
- Most commonly, a source file was specified twice on the command line
- (e.g., directly and by a *.java entry in a .lst file).
- However, sometimes you have defined a class in two files in the
- same package, and you need to rename the class or change its
- scope. You should get this message from any Java compiler.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ajcrecompile"
- xreflabel="Q:ajc recompiles all files every time. How can I make it recompile only the files that have changed?">
- <para>
- <literal>ajc</literal> recompiles all files every time.
- How can I make it recompile only the files that have changed?
- </para>
- </question>
- <answer>
- <para>
- <literal>ajc</literal> 1.0 does not support incremental
- compilation, but since 1.1 <literal>ajc</literal> does when passed the
- <literal>-incremental</literal> option. It may still recompile
- files that have not changed, if they could be affected by aspects
- in particular ways, but the files compiled should be fewer
- and result in faster compiles.
- Further, the 1.1 release supports binary weaving, so you
- need not recompile if you already have .class files.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ajcjvm"
- xreflabel="Q:ajc is using the wrong JVM. How do I fix it?">
- <para>
- <literal>ajc</literal> is using the wrong JVM. How do I
- fix it?
- </para>
- </question>
- <answer>
- <para>The easiest way to fix this is to re-install
- <literal>ajc</literal> (using the same <literal>.class</literal> or
- <literal>.exe</literal> file that you originally downloaded) and
- this time make sure to tell it to use the desired JDK (typically
- the JDK versions 1.2 or 1.3 from Sun).
- </para>
- <para>If you are familiar with DOS batch files or shell programming,
- you could also fix this by simply editing the
- <literal>bin\ajc.bat</literal> or <literal>bin/ajc</literal>
- script.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:idebalkingataspects"
- xreflabel="Q:My IDE is trying to parse AspectJ files which makes my project unusable. What can I do?">
- <para>My IDE is trying to parse AspectJ files which makes my project unusable.
- What can I do?
- </para>
- </question>
- <answer>
- <para>
- When working with an unsupported IDE that objects to the syntax of
- AspectJ source files (and, e.g., automatically gathers them
- in a source tree as Java files based on the .java extension),
- you can use the .aj extension for your AspectJ files.
- The ajc compiler accepts both .java and .aj files, and you can
- set up your build scripts to include the correct list of
- source files. (You will have to find another editor for
- editing AspectJ files; you can use the ajbrowser to view
- edit your AspectJ files and navigate the crosscutting structure.)
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:idememory"
- xreflabel="Q:I used to be able to compile my program, but now I run out of memory.">
- <para>I used to be able to compile my program in my IDE, but when I
- use AJDE, I run out of memory (or it goes really slow).
- </para>
- </question>
- <answer>
- <para>
- The ajc compiler does more analysis than (e.g.,) javac,
- and AJDE may in some IDE's hold a copy of the structure tree until the
- next tree is available from the compile process. Both mean that you may
- need extra memory to compile the same program. However, increasing
- available memory to the point that you are swapping to disk can
- slow the process considerably.
- </para>
- <para>
- If you are having problems and would like to find the optimal memory
- allocation, iteratively decrease the amount of memory available until
- AJDE or ajc signals out-of-memory errors, and then increase that
- amount by 5-10%.
- </para>
- <para>
- To increase memory for the ajc compiler, see <xref linkend="q:ajcoom"/>.
- For your IDE, do something similar or follow the provider's instructions.
- For example, to increase memory in JBuilder, edit the
- <literal>jbuilderX/bin/jbuilder.config</literal>
- file to have an entry like:
- <programlisting>
- vmparam -Xmx384m
- </programlisting>
- </para>
- <para>
- If it turns out that your project is too big to use with AJDE, your IDE
- may nonetheless support external commands or Ant build processes, which
- run outside the IDE memory space. For a JBuilder Ant plugin, some
- people have directed us to <ulink url="http://antrunner.sourceforge.net"/>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:noaspectbound"
- xreflabel="Q:When I run, I get a NoAspectBoundException or a
- ClassNotFound message for NoAspectBoundException.">
- <para>
- When I run, I get a <literal>NoAspectBoundException</literal> or a
- ClassNotFound message for <literal>NoAspectBoundException</literal>.
- </para>
- </question>
- <answer>
- <para>This happens when an aspect is not associated with an object
- that is being advised. We have seen this happen two ways:
- <itemizedlist>
- <listitem>
- <para>You get a ClassNotFound message for
- <literal>NoAspectBoundException</literal> when loading a
- class affected by aspects if <literal>aspectjrt.jar</literal>
- classes are not on the runtime classpath.
- To fix this, put the classes on the classpath.
- </para>
- </listitem>
- <listitem>
- <para>
- You can get a <literal>NoAspectBoundException</literal> when
- there is a cycle in aspect initialization or static
- initialization, most commonly when an aspect advises
- its own initializer. To fix this, first find the class that
- fails to load by running java in debug mode or looking
- at the <literal>NoAspectBoundException</literal> trace,
- and then fix the offending (probably unintended) dependency.
- Most often, it comes from a pointcut like
- <literal>staticinitialization(com.company..*)</literal>
- or <literal>within(com.company..*)</literal>, which
- can include any aspects in the same subpackages.
- You can avoid advising most join points associated with
- the aspect <literal>TheAspect</literal>
- by adding <literal>&& !within(TheAspect)</literal>
- to your pointcut.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question id="q:stacktraces"
- xreflabel="Q:My stack traces don't make sense. What gives?">
- <para>
- My stack traces don't make sense. What gives?
- </para>
- </question>
- <answer>
- <para>In 1.0, unless you are using the <literal>ajdb</literal> debugger,
- stack traces may
- have synthetic methods in the stack, and the line numbers may
- not track your source code. The
- <ulink url="devguide/index.html">
- Development Environment Guide</ulink>
- discusses how to interpret stack at the end of the
- <ulink url="devguide/ajc-ref.html">
- Reference for ajc</ulink>.
- </para>
- <para>In 1.1, line numbers should work correctly.
- The only difference from a normal stack might be the addition
- of extra stack frames for call-backs.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:advicenotrunning"
- xreflabel="Q:My advice is not running (or running twice), and I don't know why.">
- <para>
- My advice is not running (or running twice), and I don't know why.
- </para>
- </question>
- <answer>
- <para>
- When advice is not running,
- there is probably a problem in the pointcut.
- Sometimes users specify pointcuts that
- do not mean what they intend -
- most often when they misspell a type name. Run the compiler in
- <literal>-Xlint</literal> mode, which will flag some likely mistakes,
- like the type name.
- If that does not work, and your pointcut is staticly-determinable,
- use a declare statement to identify affected code. (For more
- information, see <xref linkend="q:knowWhenAspectsAffectClasses"/>.)
- If that does not work and your pointcut is dynamically determined,
- see if your join points are executing at all by using
- TraceJoinPoints.java from <xref linkend="q:seeingjoinpoints"/>.
- </para>
- <para>When advice is running more than it should, either
- (1) your advice is in an abstract aspect and the pointcut picks
- out the same join point for more than one concrete instantiation
- of the aspect, or
- (2) your pointcut picks out more join points than you intend.
- </para>
- <para>
- In the case of advice in abstract aspects, the advice will run once
- for each concrete instance of the aspect.
- If the pointcut for that advice picks out the same join point for two
- concrete aspects, then the correct behavior is for the advice to run
- the advice twice at that join point.
- </para>
- <para>
- To see if your pointcut picks out the join points you intend, you
- can use IDE support, logging, or declare-warnings.
- If you are using IDE support, you should be able to trace back from
- the pointcut or advice to the join points which can be statically
- determined to be affected.
- Without IDE support, you can write
- declare-warning statements to identify code affected by staticly-
- determinable pointcuts.
- To identify advised dynamic join points,
- you can try using <literal>TraceJoinPoints.java</literal> as above,
- or update the advice to print the source location of the join point.
- Doing any of these should show if the advice applies to code that
- you did not expect.
- </para>
- <para>If you've done this and convinced yourself it's not working,
- it may be a bug. See <xref linkend="q:bugreports"/>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:adviceOnOveriddenMethods"
- xreflabel="Q:My advice runs for each overridden method!">
- <para>
- My advice runs for each overridden method!
- </para>
- </question>
- <answer>
- <para>Most likely you are advising the method execution join
- point and specifying the defining signature.
- Since all overriding methods share this signature,
- the advice runs for each method executed.
- (This happens, e.g., when one method invokes the same method
- in the superclass using <literal>super.{method}(..)</literal>).
- This is the correct behavior.
- </para>
- <para>To avoid this, use the <literal>call(..)</literal> pointcut
- designator, or use <literal>!cflow(..)</literal> to pick
- out only the initial method-execution.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:tejpsp"
- xreflabel="Q:I don't understand when thisEnclosingJoinPointStaticPart is available.">
- <para>
- I don't understand when thisEnclosingJoinPointStaticPart is available.
- </para>
- </question>
- <answer>
- <para>
- <literal>thisEnclosingJoinPointStaticPart</literal> is a special
- variable available in the context of advice to refer to the
- join point, if any, lexically enclosing the current join point:
- <table>
- <title>thisEnclosingJoinPointStaticPart</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>One of these...</entry>
- <entry>will be tEJSP for each of these:</entry>
- </row>
- <row>
- <entry>
- constructor-execution, method-execution,
- advice execution, initialization,
- pre-initialization, static initialization
- </entry>
- <entry>
- constructor-call, method-call, handler,
- field-set, field-get
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- Expressions in the body of handlers have the same
- <literal>thisEnclosingJoinPointStaticPart</literal>
- as the handler itself.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:packagedeclares"
- xreflabel="Q:I declared a member on a class with package access, but other classes in the package cannot see it.">
- <para>
- I declared a member on a class with package access, but other classes in the package cannot see it.
- </para>
- </question>
- <answer>
- <para>When declaring parents on other types from an aspect, package access only
- applies to code the implementation controls. For AspectJ 1.0, that is the set of files
- passed to the compiler. That means other classes not compiled with the aspect will not
- be able to access the aspect-declared members even if they are in the same package.
- The only way for classes outside the control of the implementation to access aspect-declared
- members is to declare them public.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:interfaceDeclarations"
- xreflabel="Q:I declared a member on a interface, but javac does not see it.">
- <para>I declared a member on a interface, but javac does not see it.
- </para>
- </question>
-
- <answer>
- <para>
- You have to compile all the top-level implementating
- classes of the interface using <literal>ajc</literal>.
- From an email by Jim Hugunin on the requirements for AspectJ 1.1 to
- implement members declared by an aspect on an interface:
- </para>
- <para>
- If you introduce non-static fields or non-abstract methods on an interface
- from an aspect, then all of the top-most implementors of that interface must
- be woven by that same aspect.
- (A class C is a top-most implementor of an interface I if C implements I
- and the superclass of C does not implement I.)
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:cantfindjavac"
- xreflabel="Q:ajc 1.0 complains that it can't find javac. What's wrong?">
- <para>
- <literal>ajc</literal> 1.0 complains that it can't find
- <literal>javac</literal>. What's wrong?
- </para>
- </question>
- <answer>
- <para>
- <literal>ajc</literal> 1.0 does not try to locate
- <literal>javac</literal> in your path: it uses the
- <literal>javac</literal> classes directly. In JDK 1.2 and 1.3 these
- classes are found in <literal>tools.jar</literal> (in the
- <literal>lib</literal> directory of the JDK distribution), which
- must be on your classpath to make
- <literal>ajc</literal> work with <literal>javac</literal>.
- Inspect the java command that launches ajc to make sure that
- <literal>tools.jar</literal> is on the classpath for ajc;
- the -classpath option only applies to the sources compiled.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ajdocneeds13"
- xreflabel="Q:I'm running under 1.4, but ajdoc asks for 1.3 (or throws IllegalAccessError for HtmlWriter.configuration)">
- <para>
- I'm running under 1.4, but <literal>ajdoc</literal> asks for 1.3
- (or throws IllegalAccessError for HtmlWriter.configuration)
- </para>
- </question>
- <answer>
- <para>
- The 1.0 implementation of <literal>ajdoc</literal> uses
- specific javadoc classes in the J2SE 1.3 tools.jar.
- We are working on addressing this limitation, but in the interim
- it is best to run ajdoc under 1.3.
- </para>
- <para>
- When running from the command-line scripts, edit the scripts directly
- to put the 1.3 tools.jar first on the classpath. (The installer does
- not know about this limitation of ajdoc.)
- </para>
- <para>
- When running from Ant, users often have tools.jar in ${ant.classpath}
- (to make javac, et al work). That makes it impossible to run the ajdoc
- taskdef (which does not currently support forking), so you'll need to
- run a separate ant process, either from the command-line or via Ant's
- exec task (the Ant task will propagate the classpath).
- If the wrong tools.jar is not on the ant classpath, then it should work
- to put the 1.3 tools.jar in the taskdef classpath.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:compileunits"
- xreflabel="Q:I set up different files to my compiles to change what the aspects see, but now I don't understand how the aspects are working?">
- <para>I set up different files to my compiles to change what
- the aspects see, but now I don't
- understand how the aspects are working.
- </para>
- </question>
- <answer>
- <para>It is a bad practice to use the compilation unit
- to control crosscutting. Aspects and pointcuts especially
- should be written to specify crosscutting precisely.
- Aspects will behave the same when you add files if
- you initially included all files affected by your aspects.
- If you use the compilation unit, then your code will behave
- differently in AspectJ implementations that do not limit
- themselves to specified files.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:readingpreprocessedcode"
- xreflabel="Q:I'm reading the code generated by ajc 1.0 in -preprocess mode, and it seems like it would not work.">
- <para>I'm reading the code generated by <literal>ajc</literal> 1.0
- in <literal>-preprocess</literal> mode, and it seems like it would not
- work (or "like it works this way").
- </para>
- </question>
- <answer>
- <para>The generated code can be difficult for a human to read and
- understand. The compiler uses implementation techniques which might
- not be apparent. To determine if the code is behaving correctly, you
- should write and run a program that attempts to provoke the error you
- suspect. Similarly, you should not rely on invariants you infer from
- the generated code (especially naming conventions for generated members).
- Please rely only on the semantics stated in the appendix of the
- AspectJ <ulink url="progguide/index.html">Programming Guide</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:injection"
- xreflabel="Q:I've heard AspectJ can generate or inject code into my code. Is this true?">
- <para>I've heard AspectJ can generate or inject code into my code.
- Is this true?
- </para>
- </question>
- <answer>
- <para>
- This is a misconception spawned from the early implementation.
- </para>
- <para>
- AspectJ does not "inject" or "generate" code. In AspectJ the
- pointcut constructs allow the programmer to identify join points,
- and the advice constructs define additional code to run at those
- join points.
- </para>
- <para>
- So the semantic model of advice is like the semantic model of a
- method -- it says "when any of these things happen, do this".
- </para>
- <para>
- People who worked with earlier versions of AspectJ, in which ajc
- was very explicitly a pre-processor, sometimes thought of AspectJ
- as injecting code. But that was an artifact of the implementation,
- not the underlying language semantics.
- </para>
- <para>
- This distinction is important for two reasons. One is that thinking
- about it this way will make more sense at the implementation continues
- to evolve towards load-time or runtime weaving. The other is that
- it makes it much easier to understand the semantics of advice on
- cflow pointcuts.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:newjoinpoints"
- xreflabel="Q:Why can't AspectJ pick out local variables (or array elements or ...)?">
- <para>Why can't AspectJ pick out local variables (or array elements or ...)?
- </para>
- </question>
- <answer>
- <para>Users have sometimes wanted AspectJ to pick out
- many more join points, including
- <itemizedlist>
- <listitem><para>method-local field access</para></listitem>
- <listitem><para>array-element access</para></listitem>
- <listitem><para>loop iteration</para></listitem>
- <listitem><para>method parameter evaluation</para></listitem>
- </itemizedlist>
- Most of these have turned out not to make sense,
- for a variety of reasons:
- <itemizedlist>
- <listitem><para>it is not a commonly-understood unit for Java programmers</para></listitem>
- <listitem><para>there are very few use-cases for advice on the join point</para></listitem>
- <listitem><para>a seemingly-insignificant change to the underlying program
- causes a change in the join point</para></listitem>
- <listitem><para>pointcuts can't really distinguish the join point in question</para></listitem>
- <listitem><para>the join point would differ too much for different
- implementations of AspectJ, or would only be implementable
- in one way
- </para></listitem>
- </itemizedlist>
- We prefer to be very conservative in the join point model for the language,
- so a new join point would have to be useful, sensible, and implementable.
- The most promising of the new join points proposed are for exception
- throws clauses and for synchronized blocks.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:reflectiveCalls"
- xreflabel="Q:Why doesn't AspectJ pick out reflective calls?">
- <para>Why doesn't AspectJ pick out reflective calls?
- The pointcut <literal>call(void run())</literal>
- won't pick out a call using reflection, like
- <literal>((Method)run).invoke(null, args)</literal>.
- </para>
- </question>
- <answer>
- <para>The pointcut
- <literal>execution(void run())</literal> will
- work. The call pointcut doesn't work because
- <literal>Method.invoke(..)</literal> is the Java method-call,
- and AspectJ cannot delve into the Java reflection library to
- implement call semantics. To advise a reflective call
- (e.g., because the compiler does not control the code for the
- method execution), test the context for <literal>invoke(..)</literal>.
- Here's a pointcut that tests only if the method name is
- correct:
- </para>
- <programlisting>
- aspect A {
- pointcut runReflectiveCall(Method run) : target(run) &&
- call(Object Method.invoke(..)) && if("run".equals(run.getName()));
- before() : runReflectiveCall(Method) {
- System.out.println("before reflective call " + thisJoinPoint);
- }
- }
- </programlisting>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:currentbugs"
- xreflabel="Q:What are the bugs now most affecting users?">
- <para>What are the bugs now most affecting users?</para>
- </question>
- <answer>
- <para>The bugs affecting the semantics of the language
- are marked with the "info" keyword. Find them with
- the query
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info">
- http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info
- </ulink>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:runtimeMemory"
- xreflabel="Q:What extra memory is required at runtime?">
- <para>What extra memory is required at runtime?
- </para>
- </question>
- <answer>
- <para>When running classes produced by the AspectJ weaver or compiler,
- there are no significant hidden uses of memory. As would be expected,
- each aspect is instantiated. The per-object aspects (like
- <literal>pertarget</literal> or <literal>perthis</literal>)
- in some implementations
- use a map to link aspects and the associated object. When using
- <literal>cflow</literal>-related pointcuts, a <literal>ThreadLocal</literal>
- is used to track control flow for each affected thread.
- </para>
- <para>Of course, the size and code in an aspect can require memory.
- Aside from normal Java practices, take care with join point references.
- When referencing the static part of a join point (e.g.,
- <literal>thisJoinPointStaticPart</literal>), only one object is
- created. However, if you reference the join point itself
- (e.g., <literal>thisJoinPoint</literal>), then one
- <literal>JoinPoint</literal> object will be created for each
- join point running advice.
- </para>
- <para>Aspect instances will be garbage collected just like regular objects
- after there are no more strong references to them. For the default
- aspect instantiation model, <literal>issingleton</literal>, the aspect
- class retains a reference to the singleton instance, in order to
- implement <literal>static {AspectClass} aspectOf()</literal>, so
- singleton instances will not be garbage collected until the class is.
- For long-running or memory-critical programs, consider using weak
- references in singleton aspects for state that should be garbage collected.
- </para>
- <para>Finally, when using load-time weaving, the weaver can require
- memory in its own right. Because the class loader never can
- know when it is done loading classes, the weaver can hold on
- to the aspects required to weave for some time. There are
- strategies for minimizing this (with different trade-off's),
- so the time and memory required for load-time weaving will
- vary as load-time weaving evolves.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:weavingcglib"
- xreflabel="Q:I get a VerifyError when running CGLIB generated code that has been woven by AspectJ. Why is this?">
- <para>I get a VerifyError when running CGLIB generated code that has been woven by
- AspectJ. Why is this?
- </para>
- </question>
- <answer>
- <para>When weaving after advice into any piece of code, the AspectJ strategy is to make all
- exit points from that code jump to a single exit point that executes the advice
- before returning. There is a verifier rule in the JVM specification that specifies
- that all routes to a jump destination must have the same height stack when they get there,
- regardless of the route taken to get there through the bytecode. The CGLIB generated code has different
- stack heights at the various exit points. This is not a problem with the CGLIB generated code,
- it is perfectly valid - it is just unusual and the AspectJ weaving strategy causes the
- verify error to trigger when it makes all exits jump to a single destination.
- </para>
- <para>AspectJ could cope with this and instead implement after advice by calling the
- advice and returning at each exit point. However, it is unlikely that the user
- actually meant to weave the CGLIB generated code in the first place - and so usually
- the right thing to do is to exclude CGLIB generate code from the weaving process by
- appropriate use of the exclude element in the aop.xml. A typical clause in the aop.xml might
- look as follows:
- </para>
- <programlisting>
- <weaver>
- <exclude within="*CGLIB*" />
- </weaver>
- </programlisting>
- </answer>
- </qandaentry>
- </qandadiv>
-
- <qandadiv id="aj11" xreflabel="AspectJ 1.1 and eclipse.org">
- <title>AspectJ 1.1 and eclipse.org</title>
- <qandaentry>
- <question id="q:whyeclipse"
- xreflabel="Q:Why did the AspectJ project move to eclipse.org?">
- <para>Why did the AspectJ project move to eclipse.org?
- </para>
- </question>
- <answer>
- <para>From the message sent to users:
- </para>
- <para>
- AspectJ has come a long way -- the language has
- stabilized; there are a rapidly growing number of
- commercial users; the 1.1 release is imminent and will
- include byte-code weaving and incremental compilation;
- and the tool support is now well integrated with several
- major IDEs.
- </para>
- <para>
- This growth of the community and the technology means
- that the original research and prototype development of
- AspectJ is complete. As such it is time for ongoing
- development and support of AspectJ to move outside of
- PARC. This has already started to happen; the Eclipse
- AJDT plug-in and the several books in preparation are
- examples.
- </para>
- <para>
- To encourage the growth of the AspectJ technology and
- community, PARC is transferring AspectJ to an
- openly-developed eclipse.org project. This project will
- include documentation, web site, mailing lists, bug
- database, and sources for the compiler. The
- command-line AspectJ compiler is still the primary tool
- produced by this project, in addition to APIs that support
- integration with a variety of IDEs. The Eclipse plug-in will
- remain at eclipse.org, while the NetBeans, JBuilder and
- Emacs support will move to SourceForge.net projects.
- We look forward to your involvement with and
- contribution to those projects.
- </para>
- <para>
- We see Eclipse as an excellent new home for core
- AspectJ technology development -- it is an active
- community of Open Source development and innovation
- in the Java space. Once development moves to
- Eclipse.org, others will be able to contribute more easily.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:eclipserequired"
- xreflabel="Q:Do I have to download Eclipse to use AspectJ?">
- <para>Do I have to download Eclipse to use AspectJ?
- </para>
- </question>
- <answer>
- <para>No. The AspectJ tools download is completely self-contained
- and does not require that you work in Eclipse.
- For information on IDE support, see
- <xref linkend="q:integrateWithDevTools"/>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:eclipseetc"
- xreflabel="Q:What are the relationships between AspectJ, JDT,
- Eclipse, AJDT, and IDE support generally?">
- <para>What are the relationships between AspectJ, JDT,
- Eclipse, AJDT, and IDE support generally?
- </para>
- </question>
- <answer>
- <para>Eclipse is a software platform.
- </para>
- <para>JDT is an eclipse project to support Java development.
- JDT has a Java compiler.
- </para>
- <para>AspectJ 1.1 is built on Eclipse/JDT's Java compiler
- but is distributed standalone and can run standalone.
- With the AspectJ distribution, you can compile and run
- AspectJ programs and use the AspectJ structure browser.
- </para>
- <para>AJDT is an eclipse project to integrate AspectJ
- into Eclipse/JDT so you can use Eclipse to develop
- AspectJ programs. AJDT aims to support the full Eclipse
- experience - searching, compiler-error tasks, etc.
- AJDT will use the AspectJ Development Environment (AJDE)
- API's for creating IDE integrations, as well as hooking
- in to the model underlying the Java compiler.
- </para>
- <para>Similarly, Sourceforge has projects integrating
- AspectJ into other development environments
- using the AJDE API's:
- <ulink url="http://aspectj4emacs.sourceforge.net">
- AspectJ for Emacs</ulink>,
- <ulink url="http://aspectj4jbuildr.sourceforge.net">
- AspectJ for JBuilder</ulink>, and
- <ulink url="http://aspectj4netbean.sourceforge.net">
- AspectJ for NetBeans</ulink>.
- </para>
- <para>This is the right level of separation/integration.
- AspectJ is available standalone, leverages an existing open-source
- compliant Java compiler, and supports external projects
- doing IDE integrations in Eclipse, Emacs, JBuilder, and NetBeans
- through a common API, AJDE.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="AspectJ5" xreflabel="AspectJ 5 and Java 5">
- <title>AspectJ 5 and Java 5</title>
- <qandaentry>
- <question id="q:aspectj5features"
- xreflabel="Q:What are the new features of AspectJ 5?">
- <para>
- What are the new features of AspectJ 5?
- </para>
- </question>
- <answer>
- <para>
- All the new features are documented in the
- <ulink url="adk15notebook/index.html">
- AspectJ 5 Developer's Notebook</ulink>
- and the
- <ulink url="devguide/index.html">
- AspectJ Development Environment Guide</ulink>.
- To summarize:
- </para>
- <itemizedlist>
- <listitem><para>
- Java 5 support: as an extension to Java, AspectJ supports
- all the new language features of Java 5, including generics
- (parameterized types), autoboxing, covariant return types,
- enhanced for-loops, enums, varargs, and of course
- annotations.
- </para></listitem>
- <listitem><para>
- Java 5 extensions: the AspectJ language has been extended
- to make use of Java 5 language features.
- <itemizedlist>
- <listitem><para>
- Generic aspects: an abstract aspect can be declared
- with a generic type parameter which can be used
- in pointcuts and when declaring members on the aspect
- (but not when declaring members on other types).
- </para></listitem>
- <listitem><para>
- Annotations: pointcuts can now pick out join points
- based on the associated annotations, annotation
- values can be bound in the same way that other
- context variables are bound at the join point,
- and annotations may be declared on other types in
- an aspect.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- Annotation-style aspects: AspectJ 5 integrates AspectWerkz-style
- aspects declared in annotations. This permits aspects to
- be written and compiled in pure-java code and woven using
- build-time or load-time weaving with the AspectJ weaver.
- (The original AspectJ language aspects are distinguished
- as "code-style" aspects.)
- </para></listitem>
- <listitem><para>
- AspectWerkz load-time weaving: Load-time weaving is
- greatly improved for all versions of Java, and now supports
- an XML configuration file which can declare concrete aspects.
- This means developers can deploy binary abstract aspects
- that deployers configure using only XML.
- </para></listitem>
- <listitem><para>
- pertypewithin instantiation model: aspects may now be instantiated
- on a per-class basis.
- </para></listitem>
- <listitem><para>
- Reflection and runtime support: AspectJ 5 supports reflection
- on aspects using the Aspect class, and also support runtime
- evaluation of pointcuts using a pointcut parser.
- </para></listitem>
- </itemizedlist>
- <para>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:codeversusannotationstyles"
- xreflabel="Q:Should I use code- or annotation-style aspects?">
- <para>
- Should I use code- or annotation-style aspects?
- </para>
- </question>
- <answer>
- <para>
- To use AspectJ, you can use the original code-style aspects
- or the annotation-style aspects new in AspectJ 5.
- </para>
- <para>
- The original code-style is a small extension of the Java language
- designed to express crosscutting as clearly as possible
- in ways familiar to most Java programmers.
- To use the original code-style aspects,
- compile them with the AspectJ compiler or weave
- pre-compiled binary aspects using the AspectJ binary (.class)
- weaver, either at build-time or at class-load-time.
- Code-style aspects have excellent IDE support, allowing
- you to navigate to and from affected source code.
- </para>
- <para>
- Annotation-style
- aspects are written (not surprisingly) using annotations.
- They use the subset of the AspectJ language that works
- when aspects are woven after the code is compiled.
- The source files are compiled with Javac, which simply saves the
- annotations in the .class files. The resulting .class files
- must be woven using
- the AspectJ weaver, which reads the annotations from the
- .class file and uses them to define aspects.
- Annotation-style aspects have the benefit of being compilable
- by Javac, but you can't use the full AspectJ language,
- and you don't enjoy the same level of IDE support
- for viewing crosscutting structure.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:aspectj5ltw"
- xreflabel="Q:What's new about the load-time weaving support in AspectJ 5?">
- <para>
- What's new about the load-time weaving support in AspectJ 5?
- </para>
- </question>
- <answer>
- <para>
- While the AspectJ weaver could be used at load-time in previous
- releases, the AspectJ 5 release supports much better integration
- with the Java 5 VM and the BEA JRocket JVM. It also supports
- an XML file for configuration that allows deployers to declare
- concrete aspects using only XML. This means aspect developers
- can write abstract aspects, and deployers need only configure
- <literal>aop.xml</literal> and run using the AspectJ weaver in Java 5.
- For example, to run Java 5 VM with load-time weaving,
- </para>
- <programlisting><![CDATA[
- java -javaagent:aspectjweaver.jar -classpath "aspects.jar:${CLASSPATH}" ..
- ]]></programlisting>
- <para>
- To declare a concrete aspect, add a a
- concrete-aspect XML entity to <literal>META-INF/aop.xml</literal>.
- This example extends a tracing aspect to apply to
- every type in the application:
- </para>
- <programlisting><![CDATA[
- <concrete-aspect
- name="com.company.tracing.ConcreteTracing"
- extends="tracing.AbstractTracing">
- <pointcut
- name="tracingScope"
- expression="within(com.company.app..*)"/>
- </concrete-aspect>
- ]]></programlisting>
- <para>
- For more information, see the
- <ulink url="devguide/index.html">
- AspectJ Development Environment Guide</ulink>.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="Technology" xreflabel="Understanding AspectJ Technology">
- <title>Understanding AspectJ Technology</title>
- <qandaentry>
- <question id="q:implementation"
- xreflabel="Q:Do I need to know how the compiler works?">
- <para>Do I need to know how the compiler or weaver works?
- </para>
- </question>
- <answer>
- <para>Writing AspectJ programs only requires understanding the
- <ulink url="progguide/index.html">Programming Guide</ulink>.
- However, current implementations do not control everything in
- a system, so AspectJ program semantics may be limited to code
- the implementation controls. For our implementation, these
- limitations are stated in
- <ulink url="progguide/implementation.html">
- Programming Guide Appendix: Implementation Notes</ulink>.
- Aside from understanding the use and limitations of the
- implementation, there is no need to understand the underlying
- technology when writing AspectJ programs.
- </para>
- <para>
- The technology that implements AspectJ interests
- some academic researchers and some developers
- who want new features or new ways to weave.
- These extensions are not discussed in the documentation.
- Some are being developed already,
- others are on the drawing board (or perhaps were left off
- long ago), and still others haven't been considered.
- If you are interested in a certain extension,
- check the bug database for feature requests
- and the mailing list archives for any past discussions.
- Then email the list to see if it's been considered.
- For more information, see
- <xref linkend="Developers"/>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:whitepapers"
- xreflabel="Q:How does the compiler/weaver work? Are there any white papers?">
- <para>How does the compiler/weaver work? Are there any white papers?
- </para>
- </question>
- <answer>
- <para>
- There are currently no documents describing this process in detail.
- You can compile programs and inspect the generated source or bytecode,
- or view the source code (see <xref linkend="Developers"/>).
- We hope to write papers on the bytecode weaving model used in
- AspectJ-1.1 if we can find the time.
- Erik Hilsdale and Jim Hugunin did draft a paper for AOSD 2004,
- now available on Jim's web site:
- <ulink url="http://hugunin.net/papers.html">
- http://hugunin.net/papers.html</ulink>
- Jim summarized advice weaving in the AspectJ 1.1 implementation in the
- <ulink url="http://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00519.html">
- following mailing-list reply</ulink>:
- </para>
- <para>
- Each piece of advice in an aspect is associated with a pointcut.
- This pointcut is stored in an attribute on the methods
- corresponding to each piece of advice.
- Before weaving, all of these pieces of advice are gathered
- into one large list.
- </para>
- <para>
- Each .class file is woven independently.
- A .class file is woven by the following steps:
- <itemizedlist>
- <listitem><para>
- Collect all of the joinpoint shadows in the .class file.
- For every dynamic joinpoint in the AspectJ language model,
- there is a corresponding static shadow of that joinpoint
- in the bytecode.
- For example, every method call joinpoint has an INVOKE
- bytecode as its static shadow. Some joinpoints
- (such as initialization) have much more
- complicated static shadows.
- </para></listitem>
- <listitem><para>
- Each piece of advice is matched to each static shadow.
- There are three results possible from this match.
- <itemizedlist>
- <listitem><para>
- Never matches,
- in which case nothing is done to the shadow
- </para></listitem>
- <listitem><para>
- Always matches,
- in which case the advice is woven into this joinpoint shadow
- </para></listitem>
- <listitem><para>
- Sometimes matches,
- in which case the advice is woven into the shadow
- along with the minimal dynamic tests to determine
- if any particular joinpoint in the actual running
- program matches the advice.
- The simplest example of sometimes matches is
- when the pointcut uses if(test()).
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- If any advice matched any static shadows in the .class file,
- then the transformed .class file is written out,
- otherwise it is left unchanged.
- </para></listitem>
- </itemizedlist>
- See <literal>BcelClassWeaver</literal> and
- <literal>BcelShadow</literal> in the
- <literal>org.aspectj.weaver.bcel</literal> package
- for the two primary classes involved in this process.
-
- </para>
- <para>
- Note: This explanation ignores the implementations of inter-type
- declarations completely.
- It also ignores performance optimizations such as fast-match
- or pipelining that speed up the process.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ltwAppServers"
- xreflabel="Q:How do I get load-time weaving to work in my chosen application server?">
- <para>How do I get load-time weaving to work in my chosen application server?
- </para>
- </question>
- <answer>
- <para>You have two choices based on how wide you want the weaving to take effect: application-server wide and application-specific weaving.
- You choose between the two by loading aspect artifacts--aspects, associated types, and aop.xml--through the right classloader.
- The aop.xml must be in the META-INF directory on the classpath for the chosen classloader. In either case, you modify the
- startup script to specify the -javaagent:path-to/aspectjweaver.jar option to the Java virtual machine. Note that it is not
- essential that all the artifacts be placed in a single jar.
- </para>
- <para>For application-server wide weaving, you make aspect artifacts accessible to the server's classloader. Typically, you
- achieve such access by putting these artifacts in the server's lib directory. For example, for Tomcat, you will place
- the aspect artifacts in the TOMCAT_HOME/lib directory.</para>
- <para>For application-specific weaving, you make aspect artifacts accessible to application classloader by bundling
- them along with application's classes. For example, for a web application, you will place the aspect artifacts in
- the MY_APP/WEB-INF/lib and/or MY_APP/WEB-INF/classes directory.</para>
- <para>
- We recommend that you start with application-specific weaving.
- Note that you have an additional option if your application is based on the Spring framework. If you deploy in one of
- the supported web servers or application servers, you can avoid modifications to the startup script. Please
- see <ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/aop.html#aop-aj-ltw-spring">http://static.springframework.org/spring/docs/2.5.x/reference/aop.html#aop-aj-ltw-spring</ulink> for more details.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:reflection"
- xreflabel="Q:Does AspectJ use reflection at runtime?">
- <para>Does AspectJ use reflection at runtime?
- </para>
- </question>
- <answer>
- <para>
- The only time that reflection is used during run-time is when the special
- thisJoinPoint object is used to discover reflective information about the
- join point. If you don't use thisJoinPoint then no reflection will be used.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:loadtimeWeaving"
- xreflabel="Q:What about load-time weaving? Can I weave aspects at runtime?">
- <para>What about load-time weaving? Can I weave aspects at runtime?
- </para>
- </question>
- <answer>
- <para>
- Since the 1.1 release, AspectJ can weave binary aspects
- into classes in bytecode form. Hooked up to a class loader,
- this can weave class bytecodes after they are read in,
- before the
- class is defined by the VM. (This means load-time weaving
- only works were aspects are not required to compile the pure-java
- classes. If the aspects are required, then the Java classes
- have to be compiled with the aspects using the AspectJ compiler.)
- The AspectJ 1.2 release had the
- WeavingURLClassLoader, and the 1.2.1 release introduced
- the aj.bat script for Java 1.4.
- The AspectJ 5 release introduces much better support for
- load-time weaving, including declaring concrete aspects
- in XML files and integrating with Java 5 and BEA JRocket
- JVM's. See <xref linkend="q:aspectj5ltw"/>.
- </para>
- <para>Some have asked about only weaving particular classes
- specified at run-time.
- Aspects should work across an entire namespace, and problems
- will likely result from weaving
- some classes but not others. Also, it's confusing to
- specify crosscutting both in the aspect and in the
- list of runtime classes; the crosscutting specification
- should be in the aspect itself,
- where it can be processed by tools.
- </para>
- <para>And just to state the obvious:
- do not use bytecode weaving, at load-time or otherwise,
- to modify .class files protected by license,
- without permission from the licensor.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="Developers" xreflabel="AspectJ Project Development">
- <title>AspectJ Project Development</title>
- <qandaentry>
- <question id="q:howitworks"
- xreflabel="Q:I'm interested in the code implementing AspectJ.">
- <para>I'm interested in the code implementing AspectJ.
- </para>
- </question>
- <answer>
- <para>Most people do not need to see the code for AspectJ;
- they can download the binary distribution for documentation
- and tools for writing AspectJ programs.
- </para>
- <para>For people who want to know how the AspectJ technology works,
- the source code is the best resource, until we write some
- proper white papers
- (see <xref linkend="q:implementation"/>).
- To get and compile the Java source code for the AspectJ
- distribution, see
- <xref linkend="q:buildingsource"/>.
- </para>
- <para>Bear in mind when looking at the code that there are many
- ways to implement the AspectJ language, and the code inspected
- might be an initial version of a new architecture (e.g., bytecode
- weaving).
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:contributions"
- xreflabel="Q:How can I get involved with developing the AspectJ project?">
- <para>How can I get involved with developing the AspectJ project?
- </para>
- </question>
- <answer>
- <para>For those who want to contribute to the project,
- here's a general list of ways to do so, in no particular order:
- <itemizedlist>
- <listitem>
- <para>Participate effectively in the mailing lists.
- The quality of the mailing lists makes a huge difference
- in the ability of new and experienced AspectJ users
- to write good code. For guidance on effective
- participation, see
- <xref linkend="q:talktousers"/> and
- <xref linkend="q:writingbugsandemails"/>.
- Also, the time that experienced users take in answering emails
- can directly translate to time developers can use (instead)
- for fixing bugs or adding features.
- </para>
- </listitem>
- <listitem>
- <para>Write bugs. Good bugs, especially with test cases,
- are always appreciated. We especially like proposals for
- new <literal>XLint</literal> messages, since they are
- sometimes easy to implement and help users learn
- AspectJ, and for other implementable features
- grounded in a compelling use-case.
- </para>
- </listitem>
- <listitem>
- <para>Write test cases for compiler bugs without test cases.
- Compiler bugs without test cases are much less likely to be fixed;
- until they are rendered in code, they might be user mistakes,
- and they might duplicate another bug or actually cover many bugs.
- </para>
- <para>Find them by searching open compiler bugs and picking out
- any which do not have test case attachments or a comment that
- a test case has been written.
- Here is a query for open compiler bugs:
- <!-- ulink gacks on ampersands in url value, so quote them -->
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED">
- http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED
- </ulink>
- </para>
- <para>For how to write test cases, see
- <xref linkend="q:harnesstestcases"/>.
- </para>
- </listitem>
- <listitem>
- <para>Write patches to fix bugs.
- If you particularly need a bug to be fixed, or if you're interested in
- learning about the system, then get the source code and try to fix the
- bug. Most likely you'll want to email aspectj-dev@eclipse.org to
- declare your intentions and the approach you propose (based on having
- looked at the code).
- Mailing the list gives those experienced with the code a chance to
- guide you away from pitfalls. To submit the patch, attach it to
- the bug. (When creating patches, do so on a per-module basis; that
- means if fixing the bug involves changes to three modules, submit
- three patches.)
- </para>
- </listitem>
- <listitem>
- <para>Write patches for other reasons.
- Often documentation needs to be fixed, or there may be a small new
- feature you'd like to see. You can just do it and then submit it
- as a patch to a bug you create. As with bugs, in some cases you
- might want to declare your intentions on the mailing list to avoid
- wasting time on something that's been fixed but not committed or
- on an approach that will be fruitless.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:buildingsource"
- xreflabel="Q:How do I get and compile the source code for AspectJ?">
- <para>How do I get and compile the source code for AspectJ?
- </para>
- </question>
- <answer>
- <para>AspectJ 1.0 source code is available in an archive available
- with the 1.0 downloads. It contains instructions for building
- from sources.
- </para>
- <para>AspectJ 1.1+ source code is available through CVS using the
- CVS Root <literal>dev.eclipse.org:/cvsroot/technology</literal>.
- For more information on accessing the CVS tree at eclipse.org,
- see the documentation from <ulink
- url="http://eclipse.org">http://eclipse.org</ulink>. Find
- specific instructions in the AspectJ tree at <ulink
- url="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.aspectj/modules/build/readme-build-and-test-aspectj.html?rev=HEAD&content-type=text/html&cvsroot=Technology_Project">
- org.aspectj/modules/build/readme-build-and-test-aspectj.html</ulink>.
- If you would like to use Ant to checkout the sources, build the
- distribution, and test everything, see <ulink
- url="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.aspectj/modules/build/release/build.xml?rev=HEAD&content-type=text/xml&cvsroot=Technology_Project">
- org.aspectj/modules/build/release/build.xml</ulink>. </para>
- <para>
- To check out the source code in Eclipse go to (<literal>File > new > Other > CVS > Checkout Projects from CVS</literal>). You'll need about 125 MB of space for the source and build.
- Host: <literal>dev.eclipse.org</literal>,
- Repository Path: <literal>/cvsroot/technology</literal>,
- user name: <literal>anonymous</literal>,
- password: (your email address),
- connection type: <literal>pserver</literal>,
- default port.
- Then select the individual modules you want to check out (you probably want all of them bar aspectj-attic and java5) and click Next and choose to check out the modules you selected as Java projects.
- Once thats done each module you checked out should show up as a project in the package explorer.
- If you have problems after this point you can view the build instructions that come with AspectJ by going in the package explorer to: <literal>build > readme-build-and-test-aspectj.html</literal>.
- </para>
- <para>
- To get the modules to build you have to set some classpath variables (<literal>Window > Preferences > Java > Build Path > Classpath Variables</literal>):
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Name: <literal>JAVA_HOME</literal>, Value: (wherever your Java JDK is installed)
- </para>
- </listitem>
- <listitem>
- <para>
- Name: <literal>JRE14_LIB</literal>, Value: (wherever your Java 4 Runtime is installed)<literal>\jre\lib\rt.jar</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Name: <literal>JRE15_LIB</literal>, Value: (wherever your Java 5 Runtime is installed)<literal>\jre\lib\rt.jar</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Name: <literal>ASPECTJRT_LIB</literal>, Value: (wherever your workspace is)<literal>\lib\aspectj\lib\aspectjrt.jar</literal>. To find out where your workspace is go to <literal>File > Switch Workspace</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The <literal>org.aspectj.lib</literal> project is an AspectJ project so
- you also have to have AJDT installed. For the latest AJDT release and
- download instructions visit the
- <ulink url="http://www.eclipse.org/ajdt/downloads/">AJDT Downloads</ulink> page.
- </para>
- <para>
- When you've added the variables click OK to do a full rebuild, then run the tests by going in the Package Explorer to:
- <literal>run-all-junit-tests > testsrc > (default package) > RunTheseBeforeYouCommitTests.java</literal>
- and running this as a JUnit test (right click and select <literal>Run As > JUnit Test</literal>).
- Don't worry about any errors that appear in the console output,
- just check that there are no failures in the JUnit view (<literal>Window > Show View > Other > Java > JUnit</literal>).
- If that finishes with no Failures and a full green bar you have the AspectJ compiler source and it's building and testing properly.
- </para>
- <para>
- Further details:
- </para>
- <para>
- You can check out the entire modules directory and build using the
- Ant build script <literal>modules/build/build.xml</literal>.
- All required libraries are included in <literal>modules/lib/</literal>,
- (including Ant 1.5.1 in <literal>modules/lib/ant</literal>).
- If you are using Eclipse, you can check out any <literal>modules/</literal>
- subdirectory as an eclipse Java project.
- Depending on what you are trying to build, you need not check out
- all modules; as of this writing, here are the modules to get
- for building the specific parts of AspectJ:
- </para>
- <para>
- <itemizedlist>
- <listitem><para>For any builds: build, lib
- </para></listitem>
- <listitem><para>For the documentation: docs
- </para></listitem>
- <listitem><para>For the compiler: bridge, util, testing-util,
- weaver, asm, org.eclipse.jdt.core, org.aspectj.ajdt.core,
- and runtime.
- </para></listitem>
- <listitem><para>For the AspectJ distribution, the ajbrowser modules,
- plus aspectj5rt and org.aspectj.lib.
- </para></listitem>
- <listitem><para>For the test harness (or to run the release build
- scripts and tests): testing, testing-client, and testing-drivers.
- </para></listitem>
- <listitem><para>To run the test suite: the test harness modules, plus
- tests.
- </para></listitem>
- </itemizedlist>
- </para>
- <para>
- Note that module interdependencies are recorded only in the eclipse
- <literal>modules/{module}/.classpath
- </literal>
- files and may
- change, so the list above may not be correct when you read it.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
-
- <question id="q:buildingAspectJAndAJDT"
- xreflabel="Q:How do I build AspectJ and integrate it into AJDT?">
- <para>How do I build AspectJ and integrate it into AJDT?
- </para>
- </question>
- <answer>
- <para>To build AspectJ, first get the source tree as
- described in <xref linkend="q:buildingsource"/>. Once you have
- a development environment set up, copy the
- <literal>build/sample-local.properties</literal> file
- to <literal>build/local.properties</literal> and within this file point the
- <literal>java14.home</literal> and <literal>java15.home</literal>
- to the corresponding places on your machine.
- </para>
- <para>
- To build AspectJ on the command line:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Open a command prompt
- </para>
- </listitem>
- <listitem>
- <para>
- Navigate to the <literal>build</literal> directory within your AspectJ workspace
- (to find out where your workspace is go to <literal>File >
- Switch Workspace</literal> within Eclipse).
- </para>
- </listitem>
- <listitem>
- <para>
- Run <literal>ant clean</literal> to remove the files from
- previously built AspectJ versions.
- </para>
- </listitem>
- <listitem>
- <para>
- Run <literal>ant</literal> to build AspectJ. The built files are created in
- <literal>your_eclipse_installation_directory/aspectj_development_workspace/aj-build</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- To import a locally built AspectJ into AJDT first follow the
- instructions on <ulink url="http://www.eclipse.org/ajdt/faq.php#q:develop">
- How do I setup an AJDT development environment in Eclipse?</ulink>
- for setting up an AJDT development environment and running the
- correctness tests. Then:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Create a file <literal>aspectjlib.properties</literal> within
- the <literal>org.aspectj.ajde</literal> project and add the following two lines
- <programlisting>
- aspectj.lib.dir=C:/eclipse/aspectj-workspace/aj-build/dist/tools/lib
- aspectj.doc.dir=C:/eclipse/aspectj-workspace/aj-build/dist/ide/eclipse/org.aspectj.ajde.doc/doc
- </programlisting>
- making sure to change the path to correspond to your set up.
- </para>
- </listitem>
- <listitem>
- <para>
- Run the <literal>build.xml</literal> file in <literal>org.aspectj.ajde</literal>
- with the <literal>plugin jars</literal> target:
- <itemizedlist>
- <listitem>
- <para>
- Right click on the <literal>build.xml</literal> file in the
- <literal>org.aspectj.ajde</literal> plugin
- </para>
- </listitem>
- <listitem>
- <para>
- Select <literal>Run As > Ant build...</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- In the resultant dialog navigate to the <literal>Targets</literal> tab
- </para>
- </listitem>
- <listitem>
- <para>
- Ensure <literal>plugin jars</literal> is the only selected target
- </para>
- </listitem>
- <listitem>
- <para>
- Click <literal>Run</literal>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- Refresh the <literal>org.aspectj.ajde, org.aspectj.runtime</literal>
- and <literal>org.aspectj.weaver</literal> plugins.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:devDocs"
- xreflabel="Q:Where do I find developer documentation on building and testing AspectJ source code?">
- <para>Where do I find developer documentation on building and testing AspectJ source code?
- </para>
- </question>
- <answer>
- <para>Find the developer documentation in HTML files in the CVS tree,
- inside the <literal>build</literal> and <literal>testing</literal> modules
- (i.e., in <literal>org.aspectj/modules/build/...</literal>).
- Most pertinant:
- <itemizedlist>
- <listitem><para>
- <literal>../build/readme-build-and-test-aspectj.html</literal>
- describes how to build the AspectJ distribution in Eclipse
- and in Ant.
- </para></listitem>
- <listitem>
- <para><literal>../build/readme-docs-module.html</literal>
- describes the AspectJ documentation sources and
- how to build the documentation using Ant.
- </para></listitem>
- <listitem><para><literal>../build/readme-tests-module.html</literal>
- describes the all the tests
- in the <literal>tests</literal> module.
- </para></listitem>
- <listitem><para><literal>../build/readme-writing-compiler-tests.html</literal>
- describes how to write compiler tests that can be run by
- the AspectJ test harness.
- </para></listitem>
- <listitem><para><literal>../build/readme-testing-drivers-module.html</literal>
- describes the test harness used to run the compiler tests
- in the <literal>tests</literal> module.
- </para></listitem>
- <listitem><para><literal>../build/readme-testing-drivers-module.html</literal>
- describes the test harness used to run the compiler tests
- in the <literal>testing</literal> module.
- </para></listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:harnesstestcases"
- xreflabel="Q:How should I submit test cases for bugs?">
- <para>How should I submit test cases for bugs?
- </para>
- </question>
- <answer>
- <para>You can attach files to a bug after it has been created.
- The code of course should replicate the actual behavior
- described in the bug when run on the target version.
- If you have a single source file, you can attach it directly,
- describing in the comments the expected result
- (e.g., error on line 14, or successful compile/run).
- The most helpful form for describing the test scenario
- and the expected results are the test definitions
- described next.
- </para>
- <para>For more complex bugs requiring many files,
- create a zip file of a directory containing all the files
- and an XML test definition file.
- The XML test definition file contains specifications
- for how to compile, recompile, or run the test sources.
- Complete documentation is available in the CVS tree
- at <literal>tests/readme-writing-compiler-tests.html</literal>
- but here is a sample file with some example definitions,
- preceded by comments showing the directory layout
- of the files referred to in the test definitions.
- </para>
- <para>
- <programlisting><![CDATA[
- <!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
- <suite>
-
- <!-- Compile and run
- using the following files:
-
- {testDefinitions}.xml
- one/
- pack1/
- Main.java
- p2/
- BeforeConstructor.java
-
- Note the bug number goes in the pr attribute.
- ("pr" stands for "problem report")
- -->
- <ajc-test dir="one" pr="234" title="before constructor call">
- <compile files="pack1/Main.java,p2/BeforeConstructor.java"/>
- <run class="pack1.Main"/>
- </ajc-test>
-
- <!-- Check that compiler warning was emitted
- using the following files:
-
- {testDefinitions}.xml
- two/
- UsesDeprecated.java
- -->
- <ajc-test dir="two" pr="244" title="deprecated, noImportError">
- <compile options="-warn:deprecated,-noImportError"
- files="UsesDeprecated.java">
- <message kind="warning" line="20"/>
- </compile>
- </ajc-test>
-
- <!-- Cooked example that uses all compiler attributes
- and the following files:
- {testDefinitions}.xml
- testCaseDir/
- jars/
- injar.jar
- required.jar
- requiredAspects.jar
- pack/
- Main.java
- providedClassesDir/
- ClassInDefaultPackage.class
- org/
- foo/
- AnotherRequired.class
- -->
- <ajc-test dir="testCaseDir" title="attributes test">
- <compile files="pack/Main.java,jars/injar.jar"
- staging="true"
- options="-Xlint,-g:none"
- argfiles="debug.lst,aspects/test.lst"
- aspectpath="jars/requiredAspects.jar"
- classpath="providedClassesDir,jars/required.jar"/>
- <run class="Main"/>
- </ajc-test>
-
- <!-- Compiler errors, recompile after changing files, and run
- using the following files:
-
- {testDefinitions}.xml
- three/
- pack/
- IncCompileFix.java
- IncCompileFix.20.java
-
- Before compiling, IncCompileFix.java is copied to a staging
- directory. Before recompiling, IncCompileFix.20.java
- replaces it, so the compiler treats file as updated.
- -->
- <ajc-test dir="three" pr="622" title="incremental fix">
- <compile staging="true" files="pack/IncCompileFix.java">
- <message kind="error" line="20"/>
- <message kind="error" line="42"/>
- </compile>
- <inc-compile tag="20"/>
- <run class="pack.IncCompileFix"/>
- </ajc-test>
-
- </suite>
- ]]></programlisting>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:testharness"
- xreflabel="Q:I'd like to run my test case. How do I get the test harness?">
- <para>I'd like to run my test case. How do I get the test harness?
- </para>
- </question>
- <answer>
- <para>The test harness is not distributed.
- To build it, get the source tree as
- described in <xref linkend="q:buildingsource"/> and then
- build the <literal>build-testing-drivers</literal> target:
- <programlisting>
- cd build
- ../lib/ant/bin/ant -f build.xml build-testing-drivers
- </programlisting>
- This produces
- <literal>../aj-build/jars/testing-drivers-all.jar</literal>
- which you can run as described in
- <literal>tests/readme-tests-module.html</literal>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:bcel"
- xreflabel="Q:BCEL is used by AspectJ but it's not actively developed. Will you change?">
- <para>BCEL is used by AspectJ but it's not actively developed. Will you change?
- </para>
- </question>
- <answer>
- <para>The AspectJ bytecode weaver has used BCEL for bytecode manipulation
- since its first release. We have upgraded it extensively, to improve
- performance, support Java 5, etc. The BCEL developers have not
- incorporated our patches, so we continue to maintain our own version.
- Ours has been optimized for the AspectJ weaver and battle-hardened
- over years of development and use. At some point in the future,
- the AspectJ weaver might be restructured to make it easy to see
- whether another bytecode package offers the same stability,
- functionality, and performance, but for now we prefer using something
- that we know works well.
- </para>
- <para>
- In the AspectJ 5 release, the weaver has been restructured to
- use reflection where possible. Otherwise, it
- continues to use BCEL, but does not hold BCEL structures in
- memory after our evaluation completes.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
-
- <qandadiv id="help" xreflabel="Getting Help">
- <title>Getting Help</title>
- <qandaentry>
- <question id="q:moreaboutaj"
- xreflabel="Q:How do I find out more about AspectJ?">
- <para>
- How do I find out more about AspectJ?
- </para>
- </question>
- <answer>
- <para>Visit the AspectJ project web site:
- <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:bugreports"
- xreflabel="Q:How do I submit a bug report?">
- <para>How do I submit a bug report?</para>
- </question>
- <answer>
- <para>You can submit a bug from
- <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
- http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
- </ulink>.
- If it seems to be a bug in the compiler,
- please attach a small test case (source code)
- to reproduce the problem.
- For more information on writing compiler test cases, see
- <xref linkend="q:ajcbugs"/>.
- If you are unable to submit a test case, consider submitting traces,
- ajcore files, and/or .class dump files, as described in the
- <ulink url="pdguide/index.html">AspectJ Problem Diagnosis Guide</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:talktousers"
- xreflabel="Q:How do I communicate with other AspectJ users?">
- <para>
- How do I communicate with other AspectJ users?
- </para>
- </question>
- <answer>
- <para>You can reach other AspectJ users by using the
- aspectj-users mailing list. You can subscribe to the list or view the
- list archives from the AspectJ home page
- <ulink url="http://eclipse.org/aspectj">
- http://eclipse.org/aspectj
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:searchingsite"
- xreflabel="Q:How can I search the email archives or the web site?">
- <para>
- How can I search the email archives or the web site?
- </para>
- </question>
- <answer>
- <para>
- It is very effective to do a google search of the form,
- <ulink url="http://www.google.com/search?q=site:eclipse.org+cflowbelow">
- http://www.google.com/search?q=site:eclipse.org+cflowbelow
- </ulink>,
- and you can use the eclipse.org search at
- <ulink url="http://www.eclipse.org/search/search.cgi">
- http://www.eclipse.org/search/search.cgi
- </ulink>.
- You can also check the old archives available for download from
- the AspectJ home page
- <ulink url="http://eclipse.org/aspectj">
- http://eclipse.org/aspectj
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:writingbugsandemails"
- xreflabel="Q:How should I write email queries?">
- <para>
- How should I write email queries?
- </para>
- </question>
- <answer>
- <para>Here's the general form of a good email:
- </para>
- <orderedlist>
- <listitem>
- <para>
- Describe the big picture of what you are trying to do...
- </para>
- </listitem>
- <listitem>
- <para>
- Describe what you think it takes, in AspectJ terms
- (concepts, syntax, and semantics) from the
- <ulink url="progguide/index.html">Programming Guide</ulink>...
- </para>
- </listitem>
- <listitem>
- <para>
- Show the AspectJ code you are using, what output it
- produces when run, and what output you expect...
- </para>
- </listitem>
- </orderedlist>
- <para>
- The big picture helps others redirect you to other approaches.
- Using AspectJ terms helps others correct mistakes in thinking
- about the problem (the most common being to confuse join points
- and pointcuts).
- The code is key to clarifying your question and getting a good
- response. On the mail list, someone can reply by fixing your
- code. In bugs, the developers can reproduce the problem immediately
- and start analyzing the fix.
- The code should not be incomplete; it should run (or fail) as-is,
- without additional libraries or source files.
- </para>
- <para>
- For the mail lists, we try to follow the conventions for open-source
- discussions that help avoid "the tragedy of the commons."
- For example conventions, see
- <ulink url="http://jakarta.apache.org/site/mail.html">
- http://jakarta.apache.org/site/mail.html
- </ulink> and
- <ulink url="http://www.tuxedo.org/%7Eesr/faqs/smart-questions.html">
- http://www.tuxedo.org/%7Eesr/faqs/smart-questions.html
- </ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:idebugs"
- xreflabel="Q:How do I write bugs for the IDE support?">
- <para>
- How do I write bugs for IDE support?
- </para>
- </question>
- <answer>
- <para>
- Bugs appearing in the IDE's may apply to the affected IDE
- or to the compiler. Compiler stack traces in IDE message windows
- are prefixed "Internal Compiler Error" and should be written up
- as compiler bugs. If you are unsure, try redoing the compile
- from the command line.
- </para>
- <para>
- Bug report for the IDE extensions go to their respective projects,
- listed in
- <xref linkend="q:integrateWithDevTools"/>
- (including bug reports for the AJDE Eclipse support,
- which you can submit at
- <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT">
- http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT
- </ulink>).
- </para>
- <para>
- One of the benefits of open-source is that you can
- find and fix the bug for yourself; when you submit
- the fix back to us, we can validate the fix for you
- and incorporate it into the next release.
- You can submit a patch by attaching it to the bug.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:ajcbugs"
- xreflabel="Q:How do I write bugs for the AspectJ compiler?">
- <para>
- How do I write bugs for the AspectJ compiler?
- </para>
- </question>
- <answer>
- <para>
- The best compiler bug report is a reproducible test case,
- standalone code that demonstrates the problem.
- Sometimes with aspects, a test case requires several
- files, if not some way to capture the behavior.
- Here's how we recommend submitting test cases:
- <orderedlist>
- <listitem>
- <para>
- Write the test case so that when the compiler bug
- is fixed, the test completes normally without output
- (e.g., expected compiler errors are issued,
- or classes produced run correctly). This usually
- means writing one or more source files.
- </para>
- </listitem>
- <listitem>
- <para>
- In the bug report, briefly summarize the bug.
- If it is not obvious, be sure to specify
- the expected output/behavior (e.g., compiler error on line 32)
- and, if the compile should complete, the main class to run.
- </para>
- </listitem>
- <listitem>
- <para>
- Submit the bugs via the web form
- <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
- http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
- </ulink>.
- </para>
- </listitem>
- <listitem>
- <para>Attach the test case to the bug.
- The test case may be a single file
- or it may be multiple files in a single zip archive,
- of the form discussed in
- <xref linkend="q:harnesstestcases"/>.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:teachingmaterials"
- xreflabel="Q:Can you recommend reading or teaching material for AspectJ?">
- <para>
- Can you recommend reading or teaching material for AspectJ?
- </para>
- </question>
- <answer>
- <para>The documentation available in the distribution is the
- best source for language and usage questions. You can also find
- selected AspectJ papers and presentations on the
- <ulink url="http://www.parc.com/groups/csl/projects/aspectj/index.html">
- PARC AspectJ page</ulink>.
- For links to Aspect-oriented programming materials in general, see
- <ulink url="http://aosd.net">http://aosd.net</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:consulting"
- xreflabel="Q:Where can our group get consulting and support?">
- <para>
- Where can our group get consulting and support?
- </para>
- </question>
- <answer>
- <para>The best thing to to is join and email the
- <literal>aspectj-dev@eclipse.org</literal> mailing list.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:faqchanges"
- xreflabel="Q:What has changed since the last FAQ version?">
- <para>
- What has changed since the last FAQ version?
- </para>
- </question>
- <answer>
- <para>
- Entries changed recently:
- <itemizedlist>
- <listitem><para><xref linkend="q:license"/></para></listitem>
- <listitem><para><xref linkend="q:productplans"/></para></listitem>
- <listitem><para><xref linkend="q:whitepapers"/></para></listitem>
- <listitem><para><xref linkend="q:bugreports"/></para></listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- <qandadiv id="project" xreflabel="About the AspectJ Project">
- <title>About the AspectJ Project</title>
- <qandaentry>
- <question id="q:opensource"
- xreflabel="Q:What does the fact that AspectJ is an Open Source Project mean to me?">
- <para>What does the fact that AspectJ is an Open Source
- Project mean to me?
- </para>
- </question>
- <answer>
- <para>Open source protects your interest in a correct, long-lived,
- up-to-date, and widely-accepted implementation of AspectJ.
- <itemizedlist>
- <listitem>
- <para>With the source code, you control your own destiny
- in perpetuity. You can continue to use the implementation
- and update it as necessary to fix bugs and add things you need.
- </para>
- </listitem>
- <listitem>
- <para>Because the code is available to all, anyone can find
- and fix bugs. There is no need to hope for it to be fixed
- in the next product release. Those who encounter the bugs
- are motivated to fix them, and there are more eyeballs on
- the code than in closed-source, so the quality tends to be high.
- This can be particularly true for the AspectJ community,
- which tends to be highly skilled.
- </para>
- </listitem>
- <listitem>
- <para>The same is true of new features or behavior, so the
- implementation should be up-to-date. This is important as
- the field of AOP develops, to capture the latest solutions.
- </para>
- </listitem>
- <listitem>
- <para>For a programming language which forms the basis of
- an entire solution stack, open source facilitates the kind
- of adoption -- tool integrations and significant projects --
- that develop and prove the technology for wider adoption. This
- limits delays caused by waiting for the completion of standards
- process or promulgation by industry leaders, and also provides
- the proofs necessary for such adoption.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:standardization"
- xreflabel="Q:What are your plans to make AspectJ a general feature of Java supported by Sun and the other key-players in the Java Industry?">
- <para>What are your plans to make AspectJ a general feature
- of Java supported by Sun and the other key players in the Java
- Industry?
- </para>
- </question>
- <answer>
- <para>Although we are committed to making AspectJ available to a wide
- range of users, it is too early to decide on a strategy. Some
- options include continuing AspectJ as a stand-alone product,
- integrating it into IDEs, or possibly incorporating it into
- standard Java with Sun's blessing.
- </para>
- <para>We currently focus on developing for the 1.1 implementation
- which improves AspectJ in key areas: rapid
- incremental compilation, bytecode weaving, and IDE integration.
- </para>
- <para>Through all of this our goal is to make AspectJ integrate as
- seamlessly as possible with the Java programming language. The
- AspectJ language design is becoming more integrated, the compiler
- is becoming faster and more integrated, the IDE extensions are
- becoming more integrated. All of this is designed to help users
- really use AspectJ and give us feedback on it.
- </para>
- <para>As the system is improved and we work more closely
- with users, we will be in good position to explore the best path
- for AspectJ in the long term.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:bytecodeweaving"
- xreflabel="Q:When will AspectJ work from class files? When will it work at class-loading time?">
- <para>When will AspectJ work from class files?
- When will it work at class-loading time?
- </para>
- </question>
- <answer>
- <para>Bytecode weaving is in AspectJ 1.1. We believe it
- works as described in an email to the users list by Jim Hugugin:
- </para>
- <para>
- The AspectJ language was designed to support weaving at many different times:
- compile, load, or even run-time in the JVM. Weaving into bytecodes at both
- compile and load-time will definitely be provided in a future release. This
- will allow weaving at compile-time into libraries for which source code is
- not available. It will also support aspect-aware class loaders that can
- perform weaving at load time on arbitrary classes. One advantage of a
- language like AspectJ, rather than an explicit meta-tool like jiapi, is
- that it separates the specification of a crosscutting concern from any
- particular implementation strategy for weaving.
- </para>
- <para>
- ...AspectJ provides a language that can cleanly
- capture crosscutting concerns while preserving the static type checking,
- modularity, and composability of Java.
- </para>
- <para>If you have an application for using aspects and bytecode,
- please let the AspectJ team know of your requirements.
- We expect to have a demonstration classloader available in
- the 1.1 release or soon thereafter.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:differences"
- xreflabel="Q:What are the differences between the current and previously released versions of AspectJ?">
- <para>What are the differences between the current and
- previously released versions of AspectJ?
- </para>
- </question>
- <answer>
- <para>The AspectJ team aims to keep the implementation bug-free and
- up-to-date with the Java language,
- to limit AspectJ language changes to those that
- are carefully considered, compelling, and backwards-compatible,
- and to deliver those language changes only in significant releases (1.0, 1.1).
- </para>
- <table>
- <title></title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="left">Version</entry>
- <entry align="left">Description</entry>
- </row>
- <row>
- <entry>AspectJ 1.5</entry>
- <entry>Upgrade to support Java 5 language and much better
- load-time weaving.
- See <ulink url="README-150.html">README-150.html</ulink>
- for more details.
- </entry>
- </row>
- <row>
- <entry>AspectJ 1.1</entry>
- <entry>A few language changes and clarifications;
- bytecode weaving and incremental compilation.
- See <ulink url="README-11.html">README-11.html</ulink>
- for more detail.
- </entry>
- </row>
- <row>
- <entry>AspectJ 1.0</entry>
- <entry>Many language changes, fixes, cleanup and
- clarifications, some significant.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.8</entry>
- <entry>More cleanup of the syntax and semantics.</entry>
- </row>
- <row>
- <entry>AspectJ 0.7</entry>
- <entry>Clean up of the semantics, 0.7 beta 4 is the first
- open source release.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.6</entry>
- <entry>Advice and crosscuts get explicit type signatures
- which describe the values that are available to advice at a
- crosscut.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.5</entry>
- <entry>Improved tool support: better Emacs environment
- support and <literal>ajdoc</literal> to parallel
- <literal>javadoc</literal>. around advice is added, and the
- <literal>aspect</literal> keyword is removed and replaced
- by the Java keyword class.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.4</entry>
- <entry>Clear separation of crosscuts and crosscut actions
- makes it possible to define extensible library
- aspects.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.3</entry>
- <entry>First all Java implementation, also includes many
- small language improvements.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.2</entry>
- <entry>General-purpose support for crosscutting. Users could
- program any kind of aspects, not just coordination. This
- release dropped COOL.
- </entry>
- </row>
- <row>
- <entry>AspectJ 0.1</entry>
- <entry>A single domain-specific aspect language, called COOL,
- for programming coordination in multi-threaded
- programs.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para> More details for 1.0 and earlier releases are available in
- <ulink url="changes.html">changes.html</ulink>.
- </para>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:schedule"
- xreflabel="Q:What is the AspectJ development schedule?">
- <para>
- What is the AspectJ development schedule?
- </para>
- </question>
- <answer>
- <para>
- Below is a table describing the goals for the major releases.
- For information about specific features, search the bug database
- for <literal>RFE</literal>'s ("requests for enhancement") by
- <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&bug_severity=enhancement">
- selecting severity of "enhancement"</ulink>.
-
- Like many open-source projects, we don't make or promise
- schedules, but we do follow a pattern of issuing preview releases
- which can give observers an idea of when
- a particular release might be available.
- </para>
- <table>
- <title>The AspectJ Development Schedule</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="left">Version</entry>
- <entry align="left">Description</entry>
- </row>
- <row>
- <entry valign="top" align="center">1.0</entry>
- <entry>Final syntax and semantic changes. Standalone structure
- browser. Complete documentation.
- </entry>
- </row>
- <row>
- <entry valign="top" align="center">1.1</entry>
- <entry>Faster incremental compilation, bytecode weaving,
- and a small number of language changes.</entry>
- </row>
- <row>
- <entry valign="top" align="center">1.2</entry>
- <entry>Faster weaving, -inpath option, better error messages,
- better handling of binary input and resources
- during incremental compilation, faster runtime
- </entry>
- </row>
- <row>
- <entry valign="top" align="center">1.5 (AspectJ 5)</entry>
- <entry>Support for Java 1.5, generic aspects,
- annotations, etc. Integrates AspectWerkz-style
- load-time weaving.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </answer>
- </qandaentry>
- <qandaentry>
- <question id="q:java5"
- xreflabel="Q:Will AspectJ support Java 5?">
- <para>
- Will AspectJ support Java 5?
- </para>
- </question>
- <answer>
- <para>
- Yes. Java 5 is supported in AspectJ 5.
- </para>
- </answer>
- </qandaentry>
- </qandadiv>
- </qandaset>
- <para>AspectJ is a registered trademark of Palo Alto Research Center, Incorporated (PARC),
- used with permission.
- Java and all Java-based marks are trademarks or registered trademarks of
- Sun Microsystems, Inc. in the United States and other countries. All other
- trademarks are the property of their respective owners.
- </para>
- </article>
- <!--
- Local variables:
- compile-command: "java com.icl.saxon.StyleSheet -o faq.html faq.xml /usr/local/docbook/docbook-xsl-1.44/html/docbook.xsl"
- fill-column: 79
- sgml-local-ecat-files: faq.ced
- End:
- -->
|