1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
|
<chapter id="starting" xreflabel="Getting Started with AspectJ">
<title>Getting Started with AspectJ</title>
<sect1 id="starting-intro">
<title>Introduction</title>
<para>
Many software developers are attracted to the idea of aspect-oriented
programming (AOP) but unsure about how to begin using the
technology. They recognize the concept of crosscutting concerns, and
know that they have had problems with the implementation of such
concerns in the past. But there are many questions about how to adopt
AOP into the development process. Common questions include:
<itemizedlist spacing="compact">
<listitem>
<para>Can I use aspects in my existing code?</para>
</listitem>
<listitem>
<para>
What kinds of benefits can I expect to get from using aspects?
</para>
</listitem>
<listitem>
<para>How do I find aspects in my programs?</para>
</listitem>
<listitem>
<para>How steep is the learning curve for AOP?</para>
</listitem>
<listitem>
<para>What are the risks of using this new technology?</para>
</listitem>
</itemizedlist>
</para>
<para>
This chapter addresses these questions in the context of AspectJ: a
general-purpose aspect-oriented extension to Java. A series of
abridged examples illustrate the kinds of aspects programmers may
want to implement using AspectJ and the benefits associated with
doing so. Readers who would like to understand the examples in more
detail, or who want to learn how to program examples like these, can
find more complete examples and supporting material linked from the
AspectJ web site ( <ulink url="http://eclipse.org/aspectj" /> ).
</para>
<para>
A significant risk in adopting any new technology is going too far
too fast. Concern about this risk causes many organizations to be
conservative about adopting new technology. To address this issue,
the examples in this chapter are grouped into three broad categories,
with aspects that are easier to adopt into existing development
projects coming earlier in this chapter. The next section, <xref
linkend="starting-aspectj"/>, we present the core of AspectJ's
features, and in <xref linkend="starting-development"/>, we present
aspects that facilitate tasks such as debugging, testing and
performance tuning of applications. And, in the section following,
<xref linkend="starting-production"/>, we present aspects that
implement crosscutting functionality common in Java applications. We
will defer discussing a third category of aspects, reusable aspects,
until <xref linkend="language"/>.
</para>
<para>
These categories are informal, and this ordering is not the only way
to adopt AspectJ. Some developers may want to use a production aspect
right away. But our experience with current AspectJ users suggests
that this is one ordering that allows developers to get experience
with (and benefit from) AOP technology quickly, while also minimizing
risk.
</para>
</sect1>
<sect1 id="starting-aspectj" xreflabel="Introduction to AspectJ">
<title>Introduction to AspectJ</title>
<para>
This section presents a brief introduction to the features of AspectJ
used later in this chapter. These features are at the core of the
language, but this is by no means a complete overview of AspectJ.
</para>
<para>
The features are presented using a simple figure editor system. A
<classname>Figure</classname> consists of a number of
<classname>FigureElements</classname>, which can be either
<classname>Point</classname>s or <classname>Line</classname>s. The
<classname>Figure</classname> class provides factory services. There
is also a <classname>Display</classname>. Most example programs later
in this chapter are based on this system as well.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="figureUML.gif"/>
</imageobject>
<caption>
<para>
UML for the <literal>FigureEditor</literal> example
</para>
</caption>
</mediaobject>
</para>
<para>
The motivation for AspectJ (and likewise for aspect-oriented
programming) is the realization that there are issues or concerns
that are not well captured by traditional programming
methodologies. Consider the problem of enforcing a security policy in
some application. By its nature, security cuts across many of the
natural units of modularity of the application. Moreover, the
security policy must be uniformly applied to any additions as the
application evolves. And the security policy that is being applied
might itself evolve. Capturing concerns like a security policy in a
disciplined way is difficult and error-prone in a traditional
programming language.
</para>
<para>
Concerns like security cut across the natural units of
modularity. For object-oriented programming languages, the natural
unit of modularity is the class. But in object-oriented programming
languages, crosscutting concerns are not easily turned into classes
precisely because they cut across classes, and so these aren't
reusable, they can't be refined or inherited, they are spread through
out the program in an undisciplined way, in short, they are difficult
to work with.
</para>
<para>
Aspect-oriented programming is a way of modularizing crosscutting
concerns much like object-oriented programming is a way of
modularizing common concerns. AspectJ is an implementation of
aspect-oriented programming for Java.
</para>
<para>
AspectJ adds to Java just one new concept, a join point -- and that's
really just a name for an existing Java concept. It adds to Java
only a few new constructs: pointcuts, advice, inter-type declarations
and aspects. Pointcuts and advice dynamically affect program flow,
inter-type declarations statically affects a program's class
hierarchy, and aspects encapsulate these new constructs.
</para>
<para>
A <emphasis>join point</emphasis> is a well-defined point in the
program flow. A <emphasis>pointcut</emphasis> picks out certain join
points and values at those points. A piece of
<emphasis>advice</emphasis> is code that is executed when a join
point is reached. These are the dynamic parts of AspectJ.
</para>
<para>
AspectJ also has different kinds of <emphasis>inter-type
declarations</emphasis> that allow the programmer to modify a
program's static structure, namely, the members of its classes and
the relationship between classes.
</para>
<para>
AspectJ's <emphasis>aspect</emphasis> are the unit of modularity for
crosscutting concerns. They behave somewhat like Java classes, but
may also include pointcuts, advice and inter-type declarations.
</para>
<para>
In the sections immediately following, we are first going to look at
join points and how they compose into pointcuts. Then we will look at
advice, the code which is run when a pointcut is reached. We will see
how to combine pointcuts and advice into aspects, AspectJ's reusable,
inheritable unit of modularity. Lastly, we will look at how to use
inter-type declarations to deal with crosscutting concerns of a
program's class structure.
</para>
<!-- ============================== -->
<sect2>
<title>The Dynamic Join Point Model</title>
<para>
A critical element in the design of any aspect-oriented language is
the join point model. The join point model provides the common
frame of reference that makes it possible to define the dynamic
structure of crosscutting concerns. This chapter describes
AspectJ's dynamic join points, in which join points are certain
well-defined points in the execution of the program.
</para>
<para>
AspectJ provides for many kinds of join points, but this chapter
discusses only one of them: method call join points. A method call
join point encompasses the actions of an object receiving a method
call. It includes all the actions that comprise a method call,
starting after all arguments are evaluated up to and including
return (either normally or by throwing an exception).
</para>
<para>
Each method call at runtime is a different join point, even if it
comes from the same call expression in the program. Many other
join points may run while a method call join point is executing --
all the join points that happen while executing the method body,
and in those methods called from the body. We say that these join
points execute in the <emphasis>dynamic context</emphasis> of the
original call join point.
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Pointcuts</title>
<para>
In AspectJ, <emphasis>pointcuts</emphasis> pick out certain join
points in the program flow. For example, the pointcut
</para>
<programlisting format="linespecific">
call(void Point.setX(int))
</programlisting>
<para>
picks out each join point that is a call to a method that has the
signature <literal>void Point.setX(int)</literal> — that is,
<classname>Point</classname>'s void <function>setX</function>
method with a single <literal>int</literal> parameter.
</para>
<para>
A pointcut can be built out of other pointcuts with and, or, and
not (spelled <literal>&&</literal>, <literal>||</literal>,
and <literal>!</literal>). For example:
</para>
<programlisting format="linespecific">
call(void Point.setX(int)) ||
call(void Point.setY(int))
</programlisting>
<para>
picks out each join point that is either a call to
<function>setX</function> or a call to <function>setY</function>.
</para>
<para>
Pointcuts can identify join points from many different types
— in other words, they can crosscut types. For example,
</para>
<programlisting format="linespecific">
call(void FigureElement.setXY(int,int)) ||
call(void Point.setX(int)) ||
call(void Point.setY(int)) ||
call(void Line.setP1(Point)) ||
call(void Line.setP2(Point));
</programlisting>
<para>
picks out each join point that is a call to one of five methods
(the first of which is an interface method, by the way).
</para>
<para>
In our example system, this pointcut captures all the join points
when a <classname>FigureElement</classname> moves. While this is a
useful way to specify this crosscutting concern, it is a bit of a
mouthful. So AspectJ allows programmers to define their own named
pointcuts with the <literal>pointcut</literal> form. So the
following declares a new, named pointcut:
</para>
<programlisting format="linespecific">
pointcut move():
call(void FigureElement.setXY(int,int)) ||
call(void Point.setX(int)) ||
call(void Point.setY(int)) ||
call(void Line.setP1(Point)) ||
call(void Line.setP2(Point));
</programlisting>
<para>
and whenever this definition is visible, the programmer can simply
use <literal>move()</literal> to capture this complicated
pointcut.
</para>
<para>
The previous pointcuts are all based on explicit enumeration of a
set of method signatures. We sometimes call this
<emphasis>name-based</emphasis> crosscutting. AspectJ also
provides mechanisms that enable specifying a pointcut in terms of
properties of methods other than their exact name. We call this
<emphasis>property-based</emphasis> crosscutting. The simplest of
these involve using wildcards in certain fields of the method
signature. For example, the pointcut
</para>
<programlisting format="linespecific">
call(void Figure.make*(..))
</programlisting>
<para>
picks out each join point that's a call to a void method defined
on <classname>Figure</classname> whose the name begins with
"<literal>make</literal>" regardless of the method's parameters.
In our system, this picks out calls to the factory methods
<function>makePoint</function> and <function>makeLine</function>.
The pointcut
</para>
<programlisting format="linespecific">
call(public * Figure.* (..))
</programlisting>
<para>
picks out each call to <classname>Figure</classname>'s public
methods.
</para>
<para>
But wildcards aren't the only properties AspectJ supports.
Another pointcut, <function>cflow</function>, identifies join
points based on whether they occur in the dynamic context of
other join points. So
</para>
<programlisting format="linespecific">
cflow(move())
</programlisting>
<para>
picks out each join point that occurs in the dynamic context of
the join points picked out by <literal>move()</literal>, our named
pointcut defined above. So this picks out each join points that
occurrs between when a move method is called and when it returns
(either normally or by throwing an exception).
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Advice</title>
<para>
So pointcuts pick out join points. But they don't
<emphasis>do</emphasis> anything apart from picking out join
points. To actually implement crosscutting behavior, we use
advice. Advice brings together a pointcut (to pick out join
points) and a body of code (to run at each of those join points).
</para>
<para>
AspectJ has several different kinds of advice. <emphasis>Before
advice</emphasis> runs as a join point is reached, before the
program proceeds with the join point. For example, before advice
on a method call join point runs before the actual method starts
running, just after the arguments to the method call are evaluated.
</para>
<programlisting><![CDATA[
before(): move() {
System.out.println("about to move");
}
]]></programlisting>
<para>
<emphasis>After advice</emphasis> on a particular join point runs
after the program proceeds with that join point. For example,
after advice on a method call join point runs after the method body
has run, just before before control is returned to the caller.
Because Java programs can leave a join point 'normally' or by
throwing an exception, there are three kinds of after advice:
<literal>after returning</literal>, <literal>after
throwing</literal>, and plain <literal>after</literal> (which runs
after returning <emphasis>or</emphasis> throwing, like Java's
<literal>finally</literal>).
</para>
<programlisting><![CDATA[
after() returning: move() {
System.out.println("just successfully moved");
}
]]></programlisting>
<para>
<emphasis>Around advice</emphasis> on a join point runs as the join
point is reached, and has explicit control over whether the program
proceeds with the join point. Around advice is not discussed in
this section.
</para>
<sect3>
<title>Exposing Context in Pointcuts</title>
<para>
Pointcuts not only pick out join points, they can also expose
part of the execution context at their join points. Values
exposed by a pointcut can be used in the body of advice
declarations.
</para>
<para>
An advice declaration has a parameter list (like a method) that
gives names to all the pieces of context that it uses. For
example, the after advice
</para>
<programlisting><![CDATA[
after(FigureElement fe, int x, int y) returning:
...SomePointcut... {
...SomeBody...
}
]]></programlisting>
<para>
uses three pieces of exposed context, a
<literal>FigureElement</literal> named fe, and two
<literal>int</literal>s named x and y.
</para>
<para>
The body of the advice uses the names just like method
parameters, so
</para>
<programlisting><![CDATA[
after(FigureElement fe, int x, int y) returning:
...SomePointcut... {
System.out.println(fe + " moved to (" + x + ", " + y + ")");
}
]]></programlisting>
<para>
The advice's pointcut publishes the values for the advice's
arguments. The three primitive pointcuts
<literal>this</literal>, <literal>target</literal> and
<literal>args</literal> are used to publish these values. So now
we can write the complete piece of advice:
</para>
<programlisting><![CDATA[
after(FigureElement fe, int x, int y) returning:
call(void FigureElement.setXY(int, int))
&& target(fe)
&& args(x, y) {
System.out.println(fe + " moved to (" + x + ", " + y + ")");
}
]]></programlisting>
<para>
The pointcut exposes three values from calls to
<function>setXY</function>: the target
<classname>FigureElement</classname> -- which it publishes as
<literal>fe</literal>, so it becomes the first argument to the
after advice -- and the two int arguments -- which it publishes
as <literal>x</literal> and <literal>y</literal>, so they become
the second and third argument to the after advice.
</para>
<para>
So the advice prints the figure element
that was moved and its new <literal>x</literal> and
<literal>y</literal> coordinates after each
<classname>setXY</classname> method call.
</para>
<para>
A named pointcut may have parameters like a piece of advice.
When the named pointcut is used (by advice, or in another named
pointcut), it publishes its context by name just like the
<literal>this</literal>, <literal>target</literal> and
<literal>args</literal> pointcut. So another way to write the
above advice is
</para>
<programlisting><![CDATA[
pointcut setXY(FigureElement fe, int x, int y):
call(void FigureElement.setXY(int, int))
&& target(fe)
&& args(x, y);
after(FigureElement fe, int x, int y) returning: setXY(fe, x, y) {
System.out.println(fe + " moved to (" + x + ", " + y + ").");
}
]]></programlisting>
</sect3>
</sect2>
<!-- ============================== -->
<sect2>
<title>Inter-type declarations</title>
<para>
Inter-type declarations in AspectJ are declarations that cut across
classes and their hierarchies. They may declare members that cut
across multiple classes, or change the inheritance relationship
between classes. Unlike advice, which operates primarily
dynamically, introduction operates statically, at compile-time.
</para>
<para>
Consider the problem of expressing a capability shared by some
existing classes that are already part of a class hierarchy,
i.e. they already extend a class. In Java, one creates an
interface that captures this new capability, and then adds to
<emphasis>each affected class</emphasis> a method that implements
this interface.
</para>
<para>
AspectJ can express the concern in one place, by using inter-type
declarations. The aspect declares the methods and fields that are
necessary to implement the new capability, and associates the
methods and fields to the existing classes.
</para>
<para>
Suppose we want to have <classname>Screen</classname> objects
observe changes to <classname>Point</classname> objects, where
<classname>Point</classname> is an existing class. We can implement
this by writing an aspect declaring that the class Point
<classname>Point</classname> has an instance field,
<varname>observers</varname>, that keeps track of the
<classname>Screen</classname> objects that are observing
<classname>Point</classname>s.
</para>
<programlisting><![CDATA[
aspect PointObserving {
private Vector Point.observers = new Vector();
...
}
]]></programlisting>
<para>
The <literal>observers</literal> field is private, so only
<classname>PointObserving</classname> can see it. So observers are
added or removed with the static methods
<function>addObserver</function> and
<function>removeObserver</function> on the aspect.
</para>
<programlisting><![CDATA[
aspect PointObserving {
private Vector Point.observers = new Vector();
public static void addObserver(Point p, Screen s) {
p.observers.add(s);
}
public static void removeObserver(Point p, Screen s) {
p.observers.remove(s);
}
...
}
]]></programlisting>
<para>
Along with this, we can define a pointcut
<function>changes</function> that defines what we want to observe,
and the after advice defines what we want to do when we observe a
change.
</para>
<programlisting><![CDATA[
aspect PointObserving {
private Vector Point.observers = new Vector();
public static void addObserver(Point p, Screen s) {
p.observers.add(s);
}
public static void removeObserver(Point p, Screen s) {
p.observers.remove(s);
}
pointcut changes(Point p): target(p) && call(void Point.set*(int));
after(Point p): changes(p) {
Iterator iter = p.observers.iterator();
while ( iter.hasNext() ) {
updateObserver(p, (Screen)iter.next());
}
}
static void updateObserver(Point p, Screen s) {
s.display(p);
}
}
]]></programlisting>
<para>
Note that neither <classname>Screen</classname>'s nor
<classname>Point</classname>'s code has to be modified, and that
all the changes needed to support this new capability are local to
this aspect.
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Aspects</title>
<para>
Aspects wrap up pointcuts, advice, and inter-type declarations in a
a modular unit of crosscutting implementation. It is defined very
much like a class, and can have methods, fields, and initializers
in addition to the crosscutting members. Because only aspects may
include these crosscutting members, the declaration of these
effects is localized.
</para>
<para>
Like classes, aspects may be instantiated, but AspectJ controls how
that instantiation happens -- so you can't use Java's
<literal>new</literal> form to build new aspect instances. By
default, each aspect is a singleton, so one aspect instance is
created. This means that advice may use non-static fields of the
aspect, if it needs to keep state around:
</para>
<programlisting><![CDATA[
aspect Logging {
OutputStream logStream = System.err;
before(): move() {
logStream.println("about to move");
}
}
]]></programlisting>
<para>
Aspects may also have more complicated rules for instantiation, but
these will be described in a later chapter.
</para>
</sect2>
</sect1>
<!-- ============================== -->
<sect1 id="starting-development" xreflabel="Development Aspects">
<title>Development Aspects</title>
<para>
The next two sections present the use of aspects in increasingly
sophisticated ways. Development aspects are easily removed from
production builds. Production aspects are intended to be used in
both development and in production, but tend to affect only a few
classes.
</para>
<para>
This section presents examples of aspects that can be used during
development of Java applications. These aspects facilitate debugging,
testing and performance tuning work. The aspects define behavior that
ranges from simple tracing, to profiling, to testing of internal
consistency within the application. Using AspectJ makes it possible
to cleanly modularize this kind of functionality, thereby making it
possible to easily enable and disable the functionality when desired.
</para>
<sect2>
<title>Tracing</title>
<para>
This first example shows how to increase the visibility of the
internal workings of a program. It is a simple tracing aspect that
prints a message at specified method calls. In our figure editor
example, one such aspect might simply trace whenever points are
drawn.
</para>
<programlisting><![CDATA[
aspect SimpleTracing {
pointcut tracedCall():
call(void FigureElement.draw(GraphicsContext));
before(): tracedCall() {
System.out.println("Entering: " + thisJoinPoint);
}
}
]]></programlisting>
<para>
This code makes use of the <literal>thisJoinPoint</literal> special
variable. Within all advice bodies this variable is bound to an
object that describes the current join point. The effect of this
code is to print a line like the following every time a figure
element receives a <function>draw</function> method call:
</para>
<programlisting><![CDATA[
Entering: call(void FigureElement.draw(GraphicsContext))
]]></programlisting>
<para>
To understand the benefit of coding this with AspectJ consider
changing the set of method calls that are traced. With AspectJ,
this just requires editing the definition of the
<function>tracedCalls</function> pointcut and recompiling. The
individual methods that are traced do not need to be edited.
</para>
<para>
When debugging, programmers often invest considerable effort in
figuring out a good set of trace points to use when looking for a
particular kind of problem. When debugging is complete or appears
to be complete it is frustrating to have to lose that investment by
deleting trace statements from the code. The alternative of just
commenting them out makes the code look bad, and can cause trace
statements for one kind of debugging to get confused with trace
statements for another kind of debugging.
</para>
<para>
With AspectJ it is easy to both preserve the work of designing a
good set of trace points and disable the tracing when it isn t
being used. This is done by writing an aspect specifically for that
tracing mode, and removing that aspect from the compilation when it
is not needed.
</para>
<para>
This ability to concisely implement and reuse debugging
configurations that have proven useful in the past is a direct
result of AspectJ modularizing a crosscutting design element the
set of methods that are appropriate to trace when looking for a
given kind of information.
</para>
</sect2>
<sect2>
<title>Profiling and Logging</title>
<para>
Our second example shows you how to do some very specific
profiling. Although many sophisticated profiling tools are
available, and these can gather a variety of information and
display the results in useful ways, you may sometimes want to
profile or log some very specific behavior. In these cases, it is
often possible to write a simple aspect similar to the ones above
to do the job.
</para>
<para>
For example, the following aspect counts the number of calls to the
<function>rotate</function> method on a <classname>Line</classname>
and the number of calls to the <function>set*</function> methods of
a <classname>Point</classname> that happen within the control flow
of those calls to <function>rotate</function>:
</para>
<programlisting><![CDATA[
aspect SetsInRotateCounting {
int rotateCount = 0;
int setCount = 0;
before(): call(void Line.rotate(double)) {
rotateCount++;
}
before(): call(void Point.set*(int))
&& cflow(call(void Line.rotate(double))) {
setCount++;
}
}
]]></programlisting>
<para>
In effect, this aspect allows the programmer to ask very specific
questions like
<blockquote>
How many times is the <function>rotate</function>
method defined on <classname>Line</classname> objects called?
</blockquote>
and
<blockquote>
How many times are methods defined on
<classname>Point</classname> objects whose name begins with
"<function>set</function>" called in fulfilling those rotate
calls?
</blockquote>
questions it may be difficult to express using standard
profiling or logging tools.
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Pre- and Post-Conditions</title>
<para>
Many programmers use the "Design by Contract" style popularized by
Bertand Meyer in <citetitle>Object-Oriented Software Construction,
2/e</citetitle>. In this style of programming, explicit
pre-conditions test that callers of a method call it properly and
explicit post-conditions test that methods properly do the work
they are supposed to.
</para>
<para>
AspectJ makes it possible to implement pre- and post-condition
testing in modular form. For example, this code
</para>
<programlisting><![CDATA[
aspect PointBoundsChecking {
pointcut setX(int x):
(call(void FigureElement.setXY(int, int)) && args(x, *))
|| (call(void Point.setX(int)) && args(x));
pointcut setY(int y):
(call(void FigureElement.setXY(int, int)) && args(*, y))
|| (call(void Point.setY(int)) && args(y));
before(int x): setX(x) {
if ( x < MIN_X || x > MAX_X )
throw new IllegalArgumentException("x is out of bounds.");
}
before(int y): setY(y) {
if ( y < MIN_Y || y > MAX_Y )
throw new IllegalArgumentException("y is out of bounds.");
}
}
]]></programlisting>
<para>
implements the bounds checking aspect of pre-condition testing for
operations that move points. Notice that the
<function>setX</function> pointcut refers to all the operations
that can set a Point's <literal>x</literal> coordinate; this
includes the <function>setX</function> method, as well as half of
the <function>setXY</function> method. In this sense the
<function>setX</function> pointcut can be seen as involving very
fine-grained crosscutting — it names the the
<function>setX</function> method and half of the
<function>setXY</function> method.
</para>
<para>
Even though pre- and post-condition testing aspects can often be
used only during testing, in some cases developers may wish to
include them in the production build as well. Again, because
AspectJ makes it possible to modularize these crosscutting concerns
cleanly, it gives developers good control over this decision.
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Contract Enforcement</title>
<para>
The property-based crosscutting mechanisms can be very useful in
defining more sophisticated contract enforcement. One very powerful
use of these mechanisms is to identify method calls that, in a
correct program, should not exist. For example, the following
aspect enforces the constraint that only the well-known factory
methods can add an element to the registry of figure
elements. Enforcing this constraint ensures that no figure element
is added to the registry more than once.
</para>
<programlisting><![CDATA[
aspect RegistrationProtection {
pointcut register(): call(void Registry.register(FigureElement));
pointcut canRegister(): withincode(static * FigureElement.make*(..));
before(): register() && !canRegister() {
throw new IllegalAccessException("Illegal call " + thisJoinPoint);
}
}
]]></programlisting>
<para>
This aspect uses the withincode primitive pointcut to denote all
join points that occur within the body of the factory methods on
<classname>FigureElement</classname> (the methods with names that
begin with "<literal>make</literal>"). This is a property-based
pointcut because it identifies join points based not on their
signature, but rather on the property that they occur specifically
within the code of another method. The before advice declaration
effectively says signal an error for any calls to register that are
not within the factory methods.
</para>
<para>
This advice throws a runtime exception at certain join points, but
AspectJ can do better. Using the <literal>declare error</literal>
form, we can have the <emphasis>compiler</emphasis> signal the
error.
</para>
<programlisting><![CDATA[
aspect RegistrationProtection {
pointcut register(): call(void Registry.register(FigureElement));
pointcut canRegister(): withincode(static * FigureElement.make*(..));
declare error: register() && !canRegister(): "Illegal call"
}
]]></programlisting>
<para>
When using this aspect, it is impossible for the compiler to
compile programs with these illegal calls. This early detection is
not always possible. In this case, since we depend only on static
information (the <literal>withincode</literal> pointcut picks out
join points totally based on their code, and the
<literal>call</literal> pointcut here picks out join points
statically). Other enforcement, such as the precondition
enforcement, above, does require dynamic information such as the
runtime value of parameters.
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Configuration Management</title>
<para>
Configuration management for aspects can be handled using a variety
of make-file like techniques. To work with optional aspects, the
programmer can simply define their make files to either include the
aspect in the call to the AspectJ compiler or not, as desired.
</para>
<para>
Developers who want to be certain that no aspects are included in
the production build can do so by configuring their make files so
that they use a traditional Java compiler for production builds. To
make it easy to write such make files, the AspectJ compiler has a
command-line interface that is consistent with ordinary Java
compilers.
</para>
</sect2>
</sect1>
<!-- ============================== -->
<sect1 id="starting-production" xreflabel="Production Aspects">
<title>Production Aspects</title>
<para>
This section presents examples of aspects that are inherently
intended to be included in the production builds of an application.
Production aspects tend to add functionality to an application
rather than merely adding more visibility of the internals of a
program. Again, we begin with name-based aspects and follow with
property-based aspects. Name-based production aspects tend to
affect only a small number of methods. For this reason, they are a
good next step for projects adopting AspectJ. But even though they
tend to be small and simple, they can often have a significant
effect in terms of making the program easier to understand and
maintain.
</para>
<sect2>
<title>Change Monitoring</title>
<para>
The first example production aspect shows how one might implement
some simple functionality where it is problematic to try and do it
explicitly. It supports the code that refreshes the display. The
role of the aspect is to maintain a dirty bit indicating whether or
not an object has moved since the last time the display was
refreshed.
</para>
<para>
Implementing this functionality as an aspect is straightforward.
The <function>testAndClear</function> method is called by the
display code to find out whether a figure element has moved
recently. This method returns the current state of the dirty flag
and resets it to false. The pointcut <function>move</function>
captures all the method calls that can move a figure element. The
after advice on <function>move</function> sets the dirty flag
whenever an object moves.
</para>
<programlisting><![CDATA[
aspect MoveTracking {
private static boolean dirty = false;
public static boolean testAndClear() {
boolean result = dirty;
dirty = false;
return result;
}
pointcut move():
call(void FigureElement.setXY(int, int)) ||
call(void Line.setP1(Point)) ||
call(void Line.setP2(Point)) ||
call(void Point.setX(int)) ||
call(void Point.setY(int));
after() returning: move() {
dirty = true;
}
}
]]></programlisting>
<para>
Even this simple example serves to illustrate some of the important
benefits of using AspectJ in production code. Consider implementing
this functionality with ordinary Java: there would likely be a
helper class that contained the <literal>dirty</literal> flag, the
<function>testAndClear</function> method, as well as a
<function>setFlag</function> method. Each of the methods that could
move a figure element would include a call to the
<function>setFlag</function> method. Those calls, or rather the
concept that those calls should happen at each move operation, are
the crosscutting concern in this case.
</para>
<para>
The AspectJ implementation has several advantages over the standard
implementation:
</para>
<para>
<emphasis>The structure of the crosscutting concern is captured
explicitly.</emphasis> The moves pointcut clearly states all the
methods involved, so the programmer reading the code sees not just
individual calls to <literal>setFlag</literal>, but instead sees
the real structure of the code. The IDE support included with
AspectJ automatically reminds the programmer that this aspect
advises each of the methods involved. The IDE support also
provides commands to jump to the advice from the method and
vice-versa.
</para>
<para>
<emphasis>Evolution is easier.</emphasis> If, for example, the
aspect needs to be revised to record not just that some figure
element moved, but rather to record exactly which figure elements
moved, the change would be entirely local to the aspect. The
pointcut would be updated to expose the object being moved, and the
advice would be updated to record that object. The paper
<citetitle>An Overview of AspectJ</citetitle> (available linked off
of the AspectJ web site -- <ulink
url="http://eclipse.org/aspectj" />), presented at ECOOP
2001, presents a detailed discussion of various ways this aspect
could be expected to evolve.
</para>
<para>
<emphasis>The functionality is easy to plug in and out.</emphasis>
Just as with development aspects, production aspects may need to be
removed from the system, either because the functionality is no
longer needed at all, or because it is not needed in certain
configurations of a system. Because the functionality is
modularized in a single aspect this is easy to do.
</para>
<para>
<emphasis>The implementation is more stable.</emphasis> If, for
example, the programmer adds a subclass of
<classname>Line</classname> that overrides the existing methods,
this advice in this aspect will still apply. In the ordinary Java
implementation the programmer would have to remember to add the
call to <function>setFlag</function> in the new overriding
method. This benefit is often even more compelling for
property-based aspects (see the section <xref
linkend="starting-production-consistentBehavior"/>).
</para>
</sect2>
<!-- ============================== -->
<sect2>
<title>Context Passing</title>
<para>
The crosscutting structure of context passing can be a significant
source of complexity in Java programs. Consider implementing
functionality that would allow a client of the figure editor (a
program client rather than a human) to set the color of any figure
elements that are created. Typically this requires passing a color,
or a color factory, from the client, down through the calls that
lead to the figure element factory. All programmers are familiar
with the inconvenience of adding a first argument to a number of
methods just to pass this kind of context information.
</para>
<para>
Using AspectJ, this kind of context passing can be implemented in a
modular way. The following code adds after advice that runs only
when the factory methods of <classname>Figure</classname> are
called in the control flow of a method on a
<classname>ColorControllingClient</classname>.
</para>
<programlisting><![CDATA[
aspect ColorControl {
pointcut CCClientCflow(ColorControllingClient client):
cflow(call(* * (..)) && target(client));
pointcut make(): call(FigureElement Figure.make*(..));
after (ColorControllingClient c) returning (FigureElement fe):
make() && CCClientCflow(c) {
fe.setColor(c.colorFor(fe));
}
}
]]></programlisting>
<para>
This aspect affects only a small number of methods, but note that
the non-AOP implementation of this functionality might require
editing many more methods, specifically, all the methods in the
control flow from the client to the factory. This is a benefit
common to many property-based aspects while the aspect is short and
affects only a modest number of benefits, the complexity the aspect
saves is potentially much larger.
</para>
</sect2>
<!-- ============================== -->
<sect2 id="starting-production-consistentBehavior" xreflabel="Providing Consistent Behavior">
<title>Providing Consistent Behavior</title>
<para>
This example shows how a property-based aspect can be used to
provide consistent handling of functionality across a large set of
operations. This aspect ensures that all public methods of the
<literal>com.bigboxco</literal> package log any Errors they throw
to their caller (in Java, an Error is like an Exception, but it
indicates that something really bad and usually unrecoverable has
happened). The <function>publicMethodCall</function> pointcut
captures the public method calls of the package, and the after
advice runs whenever one of those calls throws an Error. The advice
logs that Error and then the throw resumes.
</para>
<programlisting><![CDATA[
aspect PublicErrorLogging {
Log log = new Log();
pointcut publicMethodCall():
call(public * com.bigboxco.*.*(..));
after() throwing (Error e): publicMethodCall() {
log.write(e);
}
}
]]></programlisting>
<para>
In some cases this aspect can log an exception twice. This happens
if code inside the <literal>com.bigboxco</literal> package itself
calls a public method of the package. In that case this code will
log the error at both the outermost call into the
<literal>com.bigboxco</literal> package and the re-entrant
call. The <function>cflow</function> primitive pointcut can be used
in a nice way to exclude these re-entrant calls:</para>
<programlisting><![CDATA[
after() throwing (Error e):
publicMethodCall() && !cflow(publicMethodCall()) {
log.write(e);
}
]]></programlisting>
<para>
The following aspect is taken from work on the AspectJ compiler.
The aspect advises about 35 methods in the
<classname>JavaParser</classname> class. The individual methods
handle each of the different kinds of elements that must be
parsed. They have names like <function>parseMethodDec</function>,
<function>parseThrows</function>, and
<function>parseExpr</function>.
</para>
<programlisting><![CDATA[
aspect ContextFilling {
pointcut parse(JavaParser jp):
call(* JavaParser.parse*(..))
&& target(jp)
&& !call(Stmt parseVarDec(boolean)); // var decs
// are tricky
around(JavaParser jp) returns ASTObject: parse(jp) {
Token beginToken = jp.peekToken();
ASTObject ret = proceed(jp);
if (ret != null) jp.addContext(ret, beginToken);
return ret;
}
}
]]></programlisting>
<para>
This example exhibits a property found in many aspects with large
property-based pointcuts. In addition to a general property based
pattern <literal>call(* JavaParser.parse*(..))</literal> it
includes an exception to the pattern <literal>!call(Stmt
parseVarDec(boolean))</literal>. The exclusion of
<function>parseVarDec</function> happens because the parsing of
variable declarations in Java is too complex to fit with the clean
pattern of the other <function>parse*</function> methods. Even with
the explicit exclusion this aspect is a clear expression of a clean
crosscutting modularity. Namely that all
<function>parse*</function> methods that return
<classname>ASTObjects</classname>, except for
<function>parseVarDec</function> share a common behavior for
establishing the parse context of their result.
</para>
<para>
The process of writing an aspect with a large property-based
pointcut, and of developing the appropriate exceptions can clarify
the structure of the system. This is especially true, as in this
case, when refactoring existing code to use aspects. When we first
looked at the code for this aspect, we were able to use the IDE
support provided in AJDE for JBuilder to see what methods the
aspect was advising compared to our manual coding. We quickly
discovered that there were a dozen places where the aspect advice
was in effect but we had not manually inserted the required
functionality. Two of these were bugs in our prior non-AOP
implementation of the parser. The other ten were needless
performance optimizations. So, here, refactoring the code to
express the crosscutting structure of the aspect explicitly made
the code more concise and eliminated latent bugs.
</para>
</sect2>
</sect1>
<!-- ============================== -->
<sect1 id="starting-conclusion">
<title>Conclusion</title>
<para>
AspectJ is a simple and practical aspect-oriented extension to
Java. With just a few new constructs, AspectJ provides support for
modular implementation of a range of crosscutting concerns.
</para>
<para>
Adoption of AspectJ into an existing Java development project can be
a straightforward and incremental task. One path is to begin by using
only development aspects, going on to using production aspects and
then reusable aspects after building up experience with
AspectJ. Adoption can follow other paths as well. For example, some
developers will benefit from using production aspects right
away. Others may be able to write clean reusable aspects almost right
away.
</para>
<para>
AspectJ enables both name-based and property based crosscutting.
Aspects that use name-based crosscutting tend to affect a small
number of other classes. But despite their small scale, they can
often eliminate significant complexity compared to an ordinary Java
implementation. Aspects that use property-based crosscutting can
have small or large scale.
</para>
<para>
Using AspectJ results in clean well-modularized implementations of
crosscutting concerns. When written as an AspectJ aspect the
structure of a crosscutting concern is explicit and easy to
understand. Aspects are also highly modular, making it possible to
develop plug-and-play implementations of crosscutting
functionality.
</para>
<para>
AspectJ provides more functionality than was covered by this short
introduction. The next chapter, <xref linkend="language"/>,
covers in detail more of the features of the AspectJ language. The
following chapter, <xref linkend="examples"/>, then presents some
carefully chosen examples that show you how AspectJ might be used. We
recommend that you read the next two chapters carefully before
deciding to adopt AspectJ into a project.
</para>
</sect1>
</chapter>
|