The AspectJ^TM Programming Guide

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.

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).

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 dynamic context of the original call join point.

In AspectJ, pointcuts pick out certain join points in the program flow. For example, the pointcut

picks out each join point that is a call to a method that has the signature void Point.setX(int) - that is, Point's void setX method with a single int parameter.

A pointcut can be built out of other pointcuts with and, or, and not (spelled &&, ||, and !). For example:

picks out each join point that is either a call to setX or a call to setY.

Pointcuts can identify join points from many different types - in other words, they can crosscut types. For example,

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).

In our example system, this pointcut captures all the join points when a FigureElement 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 pointcut form. So the following declares a new, named pointcut:

and whenever this definition is visible, the programmer can simply use move() to capture this complicated pointcut.

The previous pointcuts are all based on explicit enumeration of a set of method signatures. We sometimes call this name-based crosscutting. AspectJ also provides mechanisms that enable specifying a pointcut in terms of properties of methods other than their exact name. We call this property-based crosscutting. The simplest of these involve using wildcards in certain fields of the method signature. For example, the pointcut

picks out each join point that’s a call to a void method defined on Figure whose the name begins with “make” regardless of the method’s parameters. In our system, this picks out calls to the factory methods makePoint and makeLine. The pointcut

picks out each call to Figure's public methods.

But wildcards aren’t the only properties AspectJ supports. Another pointcut, cflow, identifies join points based on whether they occur in the dynamic context of other join points. So

picks out each join point that occurs in the dynamic context of the join points picked out by move(), 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).

So pointcuts pick out join points. But they don’t do 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).

AspectJ has several different kinds of advice. Before advice 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.

After advice 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: after returning, after throwing, and plain after (which runs after returning or throwing, like Java’s finally).

Around advice 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.

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.

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 each affected class a method that implements this interface.

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.

Suppose we want to have Screen objects observe changes to Point objects, where Point is an existing class. We can implement this by writing an aspect declaring that the class Point Point has an instance field, observers, that keeps track of the Screen objects that are observing Points.

The observers field is private, so only PointObserving can see it. So observers are added or removed with the static methods addObserver and removeObserver on the aspect.

Along with this, we can define a pointcut changes that defines what we want to observe, and the after advice defines what we want to do when we observe a change.

Note that neither Screen's nor Point's code has to be modified, and that all the changes needed to support this new capability are local to this aspect.

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.

Like classes, aspects may be instantiated, but AspectJ controls how that instantiation happens — so you can’t use Java’s new 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:

Aspects may also have more complicated rules for instantiation, but these will be described in a later chapter.

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.

This code makes use of the thisJoinPoint 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 draw method call:

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 tracedCalls pointcut and recompiling. The individual methods that are traced do not need to be edited.

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.

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.

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.

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.

For example, the following aspect counts the number of calls to the rotate method on a Line and the number of calls to the set* methods of a Point that happen within the control flow of those calls to rotate:

In effect, this aspect allows the programmer to ask very specific questions like

and

Such questions may be difficult to express using standard profiling or logging tools.

Many programmers use the "Design by Contract" style popularized by Bertand Meyer in Object-Oriented Software Construction, 2/e. 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.

AspectJ makes it possible to implement pre- and post-condition testing in modular form. For example, this code

implements the bounds checking aspect of pre-condition testing for operations that move points. Notice that the setX pointcut refers to all the operations that can set a Point’s x coordinate; this includes the setX method, as well as half of the setXY method. In this sense the setX pointcut can be seen as involving very fine-grained crosscutting - it names the the setX method and half of the setXY method.

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.

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.

This aspect uses the withincode primitive pointcut to denote all join points that occur within the body of the factory methods on FigureElement (the methods with names that begin with “make”). 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.

This advice throws a runtime exception at certain join points, but AspectJ can do better. Using the declare error form, we can have the compiler signal the error.

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 withincode pointcut picks out join points totally based on their code, and the call 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.

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.

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.

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.

Implementing this functionality as an aspect is straightforward. The testAndClear 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 move captures all the method calls that can move a figure element. The after advice on move sets the dirty flag whenever an object moves.

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 dirty flag, the testAndClear method, as well as a setFlag method. Each of the methods that could move a figure element would include a call to the setFlag method. Those calls, or rather the concept that those calls should happen at each move operation, are the crosscutting concern in this case.

The AspectJ implementation has several advantages over the standard implementation:

The structure of the crosscutting concern is captured explicitly. The moves pointcut clearly states all the methods involved, so the programmer reading the code sees not just individual calls to setFlag, 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.

Evolution is easier. 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 An Overview of AspectJ (available linked off of the AspectJ web site — https://eclipse.org/aspectj), presented at ECOOP 2001, presents a detailed discussion of various ways this aspect could be expected to evolve.

The functionality is easy to plug in and out. 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.

The implementation is more stable. If, for example, the programmer adds a subclass of Line 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 setFlag in the new overriding method. This benefit is often even more compelling for property-based aspects (see the section Providing Consistent Behavior).

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.

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 Figure are called in the control flow of a method on a ColorControllingClient.

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.

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 com.bigboxco 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 publicMethodCall 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.

In some cases this aspect can log an exception twice. This happens if code inside the com.bigboxco 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 com.bigboxco package and the re-entrant call. The cflow primitive pointcut can be used in a nice way to exclude these re-entrant calls:

The following aspect is taken from work on the AspectJ compiler. The aspect advises about 35 methods in the JavaParser class. The individual methods handle each of the different kinds of elements that must be parsed. They have names like parseMethodDec, parseThrows, and parseExpr.

This example exhibits a property found in many aspects with large property-based pointcuts. In addition to a general property based pattern call(* JavaParser.parse*(..)) it includes an exception to the pattern !call(Stmt parseVarDec(boolean)). The exclusion of parseVarDec happens because the parsing of variable declarations in Java is too complex to fit with the clean pattern of the other parse* methods. Even with the explicit exclusion this aspect is a clear expression of a clean crosscutting modularity. Namely that all parse* methods that return ASTObjects, except for parseVarDec share a common behavior for establishing the parse context of their result.

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.

Here’s an example of an aspect definition in AspectJ:

The FaultHandler consists of one inter-type field on Server (line 03), two methods (lines 05-07 and 09-11), one pointcut definition (line 13), and two pieces of advice (lines 15-17 and 19-22).

This covers the basics of what aspects can contain. In general, aspects consist of an association of other program entities, ordinary variables and methods, pointcut definitions, inter-type declarations, and advice, where advice may be before, after or around advice. The remainder of this lesson focuses on those crosscut-related constructs.

AspectJ’s pointcut definitions give names to pointcuts. Pointcuts themselves pick out join points, i.e. interesting points in the execution of a program. These join points can be method or constructor invocations and executions, the handling of exceptions, field assignments and accesses, etc. Take, for example, the pointcut definition in line 13:

This pointcut, named services, picks out those points in the execution of the program when Server objects have their public methods called. It also allows anyone using the services pointcut to access the Server object whose method is being called.

The idea behind this pointcut in the FaultHandler aspect is that fault-handling-related behavior must be triggered on the calls to public methods. For example, the server may be unable to proceed with the request because of some fault. The calls of those methods are, therefore, interesting events for this aspect, in the sense that certain fault-related things will happen when these events occur.

Part of the context in which the events occur is exposed by the formal parameters of the pointcut. In this case, that consists of objects of type Server. That formal parameter is then being used on the right hand side of the declaration in order to identify which events the pointcut refers to. In this case, a pointcut picking out join points where a Server is the target of some operation (target(s)) is being composed (&&, meaning and) with a pointcut picking out call join points (call(..)). The calls are identified by signatures that can include wild cards. In this case, there are wild cards in the return type position (first *), in the name position (second *) and in the argument list position (..); the only concrete information is given by the qualifier public.

Pointcuts pick out arbitrarily large numbers of join points of a program. But they pick out only a small number of kinds of join points. Those kinds of join points correspond to some of the most important concepts in Java. Here is an incomplete list: method call, method execution, exception handling, instantiation, constructor execution, and field access. Each kind of join point can be picked out by its own specialized pointcut that you will learn about in other parts of this guide.

A piece of advice brings together a pointcut and a body of code to define aspect implementation that runs at join points picked out by the pointcut. For example, the advice in lines 15-17 specifies that the following piece of code

is executed when instances of the Server class have their public methods called, as specified by the pointcut services. More specifically, it runs when those calls are made, just before the corresponding methods are executed.

The advice in lines 19-22 defines another piece of implementation that is executed on the same pointcut:

But this second method executes after those operations throw exception of type FaultException.

There are two other variations of after advice: upon successful return and upon return, either successful or with an exception. There is also a third kind of advice called around. You will see those in other parts of this guide.

Here are examples of pointcuts picking out

Pointcuts compose through the operations OR (||), ANT (&&) and NOT (!).

When methods and constructors run, there are two interesting times associated with them. That is when they are called, and when they actually execute.

AspectJ exposes these times as call and execution join points, respectively, and allows them to be picked out specifically by call and execution pointcuts.

So what’s the difference between these join points? Well, there are a number of differences:

Firstly, the lexical pointcut declarations within and withincode match differently. At a call join point, the enclosing code is that of the call site. This means that call(void m()) && withincode(void m()) will only capture directly recursive calls, for example. At an execution join point, however, the program is already executing the method, so the enclosing code is the method itself: execution(void m()) && withincode(void m()) is the same as execution(void m()).

Secondly, the call join point does not capture super calls to non-static methods. This is because such super calls are different in Java, since they don’t behave via dynamic dispatch like other calls to non-static methods.

The rule of thumb is that if you want to pick a join point that runs when an actual piece of code runs (as is often the case for tracing), use execution, but if you want to pick one that runs when a particular signature is called (as is often the case for production aspects), use call.

Pointcuts are put together with the operators and (spelled &&), or (spelled ||), and not (spelled !). This allows the creation of very powerful pointcuts from the simple building blocks of primitive pointcuts. This composition can be somewhat confusing when used with primitive pointcuts like cflow and cflowbelow. Here’s an example:

cflow(P) picks out each join point in the control flow of the join points picked out by P. So, pictorially:

What does cflow(P) && cflow(Q) pick out? Well, it picks out each join point that is in both the control flow of P and in the control flow of Q. So…​

Note that P and Q might not have any join points in common…​ but their control flows might have join points in common.

But what does cflow(P && Q) mean? Well, it means the control flow of those join points that are both picked out by P and picked out by Q.

and if there are no join points that are both picked by P and picked out by Q, then there’s no chance that there are any join points in the control flow of (P && Q).

Here’s some code that expresses this.

The !within(A) pointcut above is required to avoid the printPC pointcut applying to the System.out.println call in the advice body. If this was not present a recursive call would result as the pointcut would apply to its own advice. (See Infinite loops for more details.)

Consider again the first pointcut definition in this chapter:

As we’ve seen, this pointcut picks out each call to setX(int) or setY(int) methods where the target is an instance of Point. The pointcut is given the name setter and no parameters on the left-hand side. An empty parameter list means that none of the context from the join points is published from this pointcut. But consider another version of version of this pointcut definition:

This version picks out exactly the same join points. But in this version, the pointcut has one parameter of type Point. This means that any advice that uses this pointcut has access to a Point from each join point picked out by the pointcut. Inside the pointcut definition this Point is named p is available, and according to the right-hand side of the definition, that Point p comes from the target of each matched join point.

Here’s another example that illustrates the flexible mechanism for defining pointcut parameters:

This pointcut also has a parameter of type Point. Similar to the setter pointcut, this means that anyone using this pointcut has access to a Point from each join point. But in this case, looking at the right-hand side we find that the object named in the parameters is not the target Point object that receives the call; it’s the argument (also of type Point) passed to the equals method when some other Point is the target. If we wanted access to both Points, then the pointcut definition that would expose target Point p1 and argument Point p2 would be

Let’s look at another variation of the setter pointcut:

In this case, a Point object and an int value are exposed by the named pointcut. Looking at the the right-hand side of the definition, we find that the Point object is the target object, and the int value is the called method’s argument.

The use of pointcut parameters is relatively flexible. The most important rule is that all the pointcut parameters must be bound at every join point picked out by the pointcut. So, for example, the following pointcut definition will result in a compilation error:

because p1 is only bound when calling setX, and p2 is only bound when calling setY, but the pointcut picks out all of these join points and tries to bind both p1 and p2.

The example below consists of two object classes (plus an exception class) and one aspect. Handle objects delegate their public, non-static operations to their Partner objects. The aspect HandleLiveness ensures that, before the delegations, the partner exists and is alive, or else it throws an exception.

During compilation, AspectJ processes pointcuts in order to try and optimize matching performance. Examining code and determining if each join point matches (statically or dynamically) a given pointcut is a costly process. (A dynamic match means the match cannot be fully determined from static analysis and a test will be placed in the code to determine if there is an actual match when the code is running). On first encountering a pointcut declaration, AspectJ will rewrite it into an optimal form for the matching process. What does this mean? Basically pointcuts are rewritten in DNF (Disjunctive Normal Form) and the components of the pointcut are sorted such that those components that are cheaper to evaluate are checked first. This means users do not have to worry about understanding the performance of various pointcut designators and may supply them in any order in their pointcut declarations.

However, AspectJ can only work with what it is told, and for optimal performance of matching the user should think about what they are trying to achieve and narrow the search space for matches as much as they can in the definition. Basically there are three kinds of pointcut designator: kinded, scoping and context:

A well written pointcut should try and include at least the first two types (kinded and scoping), whilst the contextual designators may be included if wishing to match based on join point context, or bind that context for use in the advice. Supplying either just a kinded designator or just a contextual designator will work but could affect weaving performance (time and memory used) due to all the extra processing and analysis. Scoping designators are very fast to match, they can very quickly dismiss groups of join points that should not be further processed - that is why a good pointcut should always include one if possible.

AspectJ allows private and package-protected (default) inter-type declarations in addition to public inter-type declarations. Private means private in relation to the aspect, not necessarily the target type. So, if an aspect makes a private inter-type declaration of a field

Then code in the aspect can refer to Foo's x field, but nobody else can. Similarly, if an aspect makes a package-protected introduction,

then everything in the aspect’s package (which may or may not be Foo's package) can access x.

The example below consists of one class and one aspect. The aspect privately declares the assertion methods of Point, assertX and assertY. It also guards calls to setX and setY with calls to these assertion methods. The assertion methods are declared privately because other parts of the program (including the code in Point) have no business accessing the assert methods. Only the code inside of the aspect can call those methods.

(The code for this example is in InstallDir/examples/tjp.)

A join point is some point in the execution of a program together with a view into the execution context when that point occurs. Join points are picked out by pointcuts. When a program reaches a join point, advice on that join point may run in addition to (or instead of) the join point itself.

When using a pointcut that picks out join points of a single kind by name, typicaly the the advice will know exactly what kind of join point it is associated with. The pointcut may even publish context about the join point. Here, for example, since the only join points picked out by the pointcut are calls of a certain method, we can get the target value and one of the argument values of the method calls directly.

But sometimes the shape of the join point is not so clear. For instance, suppose a complex application is being debugged, and we want to trace when any method of some class is executed. The pointcut

will pick out each execution join point of every method defined within ProblemClass. Since advice executes at each join point picked out by the pointcut, we can reasonably ask which join point was reached.

Information about the join point that was matched is available to advice through the special variable thisJoinPoint, of type org.aspectj.lang.JoinPoint. Through this object we can access information such as

(The code for this example is in InstallDir/examples/introduction.)

Like advice, inter-type declarations are members of an aspect. They declare members that act as if they were defined on another class. Unlike advice, inter-type declarations affect not only the behavior of the application, but also the structural relationship between an application’s classes.

This is crucial: Publically affecting the class structure of an application makes these modifications available to other components of the application.

Aspects can declare inter-type

and can also declare that target types

This example provides three illustrations of the use of inter-type declarations to encapsulate roles or views of a class. The class our aspect will be dealing with, Point, is a simple class with rectangular and polar coordinates. Our inter-type declarations will make the class Point, in turn, cloneable, hashable, and comparable. These facilities are provided by AspectJ without having to modify the code for the class Point.

(The code for this example is in InstallDir/examples/tracing.)

Writing a class that provides tracing functionality is easy: a couple of functions, a boolean flag for turning tracing on and off, a choice for an output stream, maybe some code for formatting the output — these are all elements that Trace classes have been known to have. Trace classes may be highly sophisticated, too, if the task of tracing the execution of a program demands it.

But developing the support for tracing is just one part of the effort of inserting tracing into a program, and, most likely, not the biggest part. The other part of the effort is calling the tracing functions at appropriate times. In large systems, this interaction with the tracing support can be overwhelming. Plus, tracing is one of those things that slows the system down, so these calls should often be pulled out of the system before the product is shipped. For these reasons, it is not unusual for developers to write ad-hoc scripting programs that rewrite the source code by inserting/deleting trace calls before and after the method bodies.

AspectJ can be used for some of these tracing concerns in a less ad-hoc way. Tracing can be seen as a concern that crosscuts the entire system and as such is amenable to encapsulation in an aspect. In addition, it is fairly independent of what the system is doing. Therefore tracing is one of those kind of system aspects that can potentially be plugged in and unplugged without any side-effects in the basic functionality of the system.

(The code for this example is in InstallDir/examples/bean.)

This example examines an aspect that makes Point objects into Java beans with bound properties.

Java beans are reusable software components that can be visually manipulated in a builder tool. The requirements for an object to be a bean are few. Beans must define a no-argument constructor and must be either Serializable or Externalizable. Any properties of the object that are to be treated as bean properties should be indicated by the presence of appropriate get and set methods whose names are getproperty and setproperty where property is the name of a field in the bean class. Some bean properties, known as bound properties, fire events whenever their values change so that any registered listeners (such as, other beans) will be informed of those changes. Making a bound property involves keeping a list of registered listeners, and creating and dispatching event objects in methods that change the property values, such as setproperty methods.

Point is a simple class representing points with rectangular coordinates. Point does not know anything about being a bean: there are set methods for x and y but they do not fire events, and the class is not serializable. Bound is an aspect that makes Point a serializable class and makes its get and set methods support the bound property protocol.

(The code for this example is in InstallDir/examples/observer.)

This demo illustrates how the Subject/Observer design pattern can be coded with aspects.

The demo consists of the following: A colored label is a renderable object that has a color that cycles through a set of colors, and a number that records the number of cycles it has been through. A button is an action item that records when it is clicked.

With these two kinds of objects, we can build up a Subject/Observer relationship in which colored labels observe the clicks of buttons; that is, where colored labels are the observers and buttons are the subjects.

The demo is designed and implemented using the Subject/Observer design pattern. The remainder of this example explains the classes and aspects of this demo, and tells you how to run it.

(The code for this example is in InstallDir/examples/telecom.)

This example illustrates some ways that dependent concerns can be encoded with aspects. It uses an example system comprising a simple model of telephone connections to which timing and billing features are added using aspects, where the billing feature depends upon the timing feature.

(The code for this example is in InstallDir/examples/tracing.)

Pointcuts are defined and named by the programmer with the pointcut declaration.

A named pointcut may be defined in either a class or aspect, and is treated as a member of the class or aspect where it is found. As a member, it may have an access modifier such as public or private.

Pointcuts that are not final may be declared abstract, and defined without a body. Abstract pointcuts may only be declared within abstract aspects.

In such a case, an extending aspect may override the abstract pointcut.

For completeness, a pointcut with a declaration may be declared final.

Though named pointcut declarations appear somewhat like method declarations, and can be overridden in subaspects, they cannot be overloaded. It is an error for two pointcuts to be named with the same name in the same class or aspect declaration.

The scope of a named pointcut is the enclosing class declaration. This is different than the scope of other members; the scope of other members is the enclosing class body. This means that the following code is legal:

Pointcuts have an interface; they expose some parts of the execution context of the join points they pick out. For example, the PublicIntCall above exposes the first argument from the receptions of all public unary integer methods. This context is exposed by providing typed formal parameters to named pointcuts and advice, like the formal parameters of a Java method. These formal parameters are bound by name matching.

On the right-hand side of advice or pointcut declarations, in certain pointcut designators, a Java identifier is allowed in place of a type or collection of types. The pointcut designators that allow this are this, target, and args. In all such cases, using an identifier rather than a type does two things. First, it selects join points as based on the type of the formal parameter. So the pointcut

picks out join points where an int (or a byte, short, or char; anything assignable to an int) is being passed as an argument. Second, though, it makes the value of that argument available to the enclosing advice or pointcut.

Values can be exposed from named pointcuts as well, so

is a legal way to pick out all calls to public methods accepting an int argument, and exposing that argument.

There is one special case for this kind of exposure. Exposing an argument of type Object will also match primitive typed arguments, and expose a "boxed" version of the primitive. So,

will pick out all unary methods that take, as their only argument, subtypes of Object (i.e., not primitive types like int), but

will pick out all unary methods that take any argument: And if the argument was an int, then the value passed to advice will be of type java.lang.Integer.

The "boxing" of the primitive value is based on the original primitive type. So in the following program

The pointcut will match and expose the integer argument, but it will expose it as an Integer, not a Long.

One very important property of a join point is its signature, which is used by many of AspectJ’s pointcut designators to select particular join points.

The withincode, call, execution, get, and set primitive pointcut designators all use signature patterns to determine the join points they describe. A signature pattern is an abstract description of one or more join-point signatures. Signature patterns are intended to match very closely the same kind of things one would write when declaring individual members and constructors.

Method declarations in Java include method names, method parameters, return types, modifiers like static or private, and throws clauses, while constructor declarations omit the return type and replace the method name with the class name. The start of a particular method declaration, in class Test, for example, might be

In AspectJ, method signature patterns have all these, but most elements can be replaced by wildcards. So

picks out call join points to that method, and the pointcut

picks out all call join points to methods, regardless of their name name or which class they are defined on, so long as they take no arguments, return no value, are both public and final, and are declared to throw ArrayOutOfBoundsExceptions.

The defining type name, if not present, defaults to *, so another way of writing that pointcut would be

The wildcard .. indicates zero or more parameters, so

picks out execution join points for void methods named m, of any number of arguments, while

picks out execution join points for void methods named m whose last parameter is of type int.

The modifiers also form part of the signature pattern. If an AspectJ signature pattern should match methods without a particular modifier, such as all non-public methods, the appropriate modifier should be negated with the ! operator. So,

picks out all join points associated with code in null non-public void methods named foo, while

picks out all join points associated with code in null void methods named foo, regardless of access modifier.

Method names may contain the * wildcard, indicating any number of characters in the method name. So

picks out all call join points to int methods regardless of name, but

picks out all call join points to int methods where the method name starts with the characters "get".

AspectJ uses the new keyword for constructor signature patterns rather than using a particular class name. So the execution join points of private null constructor of a class C defined to throw an ArithmeticException can be picked out with

Type patterns are a way to pick out collections of types and use them in places where you would otherwise use only one type. The rules for using type patterns are simple.

Here is a summary of the pattern syntax used in AspectJ:

The strictfp modifier is the only modifier allowed on advice, and it has the effect of making all floating-point expressions within the advice be FP-strict.

An advice declaration must include a throws clause listing the checked exceptions the body may throw. This list of checked exceptions must be compatible with each target join point of the advice, or an error is signalled by the compiler.

For example, in the following declarations:

both pieces of advice are illegal. The first because the body throws an undeclared checked exception, and the second because field get join points cannot throw FileNotFoundExceptions.

The exceptions that each kind of join point in AspectJ may throw are:

Multiple pieces of advice may apply to the same join point. In such cases, the resolution order of the advice is based on advice precedence.

Three special variables are visible within bodies of advice and within if() pointcut expressions: thisJoinPoint, thisJoinPointStaticPart, and thisEnclosingJoinPointStaticPart. Each is bound to an object that encapsulates some of the context of the advice’s current or enclosing join point. These variables exist because some pointcuts may pick out very large collections of join points. For example, the pointcut

picks out calls to many methods. Yet the body of advice over this pointcut may wish to have access to the method name or parameters of a particular join point.

Standard Java reflection uses objects from the java.lang.reflect hierarchy to build up its reflective objects. Similarly, AspectJ join point objects have types in a type hierarchy. The type of objects bound to thisJoinPoint is org.aspectj.lang.JoinPoint, while thisStaticJoinPoint is bound to objects of interface type org.aspectj.lang.JoinPoint.StaticPart.

AspectJ allows the declaration of members by aspects that are associated with other types.

An inter-type method declaration looks like

The effect of such a declaration is to make OnType support the new method. Even if OnType is an interface. Even if the method is neither public nor abstract. So the following is legal AspectJ code:

An inter-type constructor declaration looks like

The effect of such a declaration is to make OnType support the new constructor. It is an error for OnType to be an interface.

Inter-type declared constructors cannot be used to assign a value to a final variable declared in OnType. This limitation significantly increases the ability to both understand and compile the OnType class and the declaring aspect separately.

Note that in the Java language, classes that define no constructors have an implicit no-argument constructor that just calls super(). This means that attempting to declare a no-argument inter-type constructor on such a class may result in a conflict, even though it looks like no constructor is defined.

An inter-type field declaration looks like one of

The effect of such a declaration is to make OnType support the new field. Even if OnType is an interface. Even if the field is neither public, nor static, nor final.

The initializer, if any, of an inter-type field declaration runs before the class-local initializers defined in its target class.

Any occurrence of the identifier this in the body of an inter-type constructor or method declaration, or in the initializer of an inter-type field declaration, refers to the OnType object rather than to the aspect type; it is an error to access this in such a position from a static inter-type member declaration.

Inter-type member declarations may be public or private, or have default (package-protected) visibility. AspectJ does not provide protected inter-type members.

The access modifier applies in relation to the aspect, not in relation to the target type. So a private inter-type member is visible only from code that is defined within the declaring aspect. A default-visibility inter-type member is visible only from code that is defined within the declaring aspect’s package.

Note that a declaring a private inter-type method (which AspectJ supports) is very different from inserting a private method declaration into another class. The former allows access only from the declaring aspect, while the latter would allow access only from the target type. Java serialization, for example, uses the presense of a private method void writeObject(ObjectOutputStream) for the implementation of java.io.Serializable. A private inter-type declaration of that method would not fulfill this requirement, since it would be private to the aspect, not private to the target type.

The access modifier of abstract inter-type methods has one constraint: It is illegal to declare an abstract non-public inter-type method on a public interface. This is illegal because it would say that a public interface has a constraint that only non-public implementors must fulfill. This would not be compatible with Java’s type system.

Inter-type declarations raise the possibility of conflicts among locally declared members and inter-type members. For example, assuming otherPackage is not the package containing the aspect A, the code

declares that onType in otherPackage has a field r. This field, however, is only accessible from the code inside of aspect A. The aspect also declares that onType has a method “register”, but makes this method accessible from everywhere.

If onType already defines a private or package-protected field r, there is no conflict: The aspect cannot see such a field, and no code in otherPackage can see the inter-type r.

If onType defines a public field r, there is a conflict: The expression

is an error, since it is ambiguous whether the private inter-type r or the public locally-defined r should be used.

If onType defines a method register(Registry) there is a conflict, since it would be ambiguous to any code that could see such a defined method which register(Registry) method was applicable.

Conflicts are resolved as much as possible as per Java’s conflict resolution rules:

Given a potential conflict between inter-type member declarations in different aspects, if one aspect has precedence over the other its declaration will take effect without any conflict notice from compiler. This is true both when the precedence is declared explicitly with declare precedence as well as when when sub-aspects implicitly have precedence over their super-aspect.

An aspect may change the inheritance hierarchy of a system by changing the superclass of a type or adding a superinterface onto a type, with the declare parents form.

For example, if an aspect wished to make a particular class runnable, it might define appropriate inter-type void run() method, but it should also declare that the class fulfills the Runnable interface. In order to implement the methods in the Runnable interface, the inter-type run() method must be public:

Through the use of inter-type members, interfaces may now carry (non-public-static-final) fields and (non-public-abstract) methods that classes can inherit. Conflicts may occur from ambiguously inheriting members from a superclass and multiple superinterfaces.

Because interfaces may carry non-static initializers, each interface behaves as if it has a zero-argument constructor containing its initializers. The order of super-interface instantiation is observable. We fix this order with the following properties: A supertype is initialized before a subtype, initialized code runs only once, and the initializers for a type’s superclass are run before the initializers for its superinterfaces. Consider the following hierarchy where {Object, C, D, E} are classes, {M, N, O, P, Q} are interfaces.

when a new E is instantiated, the initializers run in this order:

An aspect may specify that a particular join point should never be reached.

If the compiler determines that a join point in Pointcut could possibly be reached, then it will signal either an error or warning, as declared, using the String for its message.

An aspect may specify that a particular kind of exception, if thrown at a join point, should bypass Java’s usual static exception checking system and instead be thrown as a org.aspectj.lang.SoftException, which is subtype of RuntimeException and thus does not need to be declared.

For example, the aspect

Would, at the execution join point, catch any Exception and rethrow a org.aspectj.lang.SoftException containing original exception.

This is similar to what the following advice would do

except, in addition to wrapping the exception, it also affects Java’s static exception checking mechanism.

Like advice, the declare soft form has no effect in an abstract aspect that is not extended by a concreate aspect. So the following code will not compile unless it is compiled with an extending concrete aspect:

An aspect may declare a precedence relationship between concrete aspects with the declare precedence form:

This signifies that if any join point has advice from two concrete aspects matched by some pattern in TypePatternList, then the precedence of the advice will be the order of in the list.

In TypePatternList, the wildcard * can appear at most once, and it means "any type not matched by any other pattern in the list".

For example, the constraints that (1) aspects that have Security as part of their name should have precedence over all other aspects, and (2) the Logging aspect (and any aspect that extends it) should have precedence over all non-security aspects, can be expressed by:

For another example, the CountEntry aspect might want to count the entry to methods in the current package accepting a Type object as its first argument. However, it should count all entries, even those that the aspect DisallowNulls causes to throw exceptions. This can be accomplished by stating that CountEntry has precedence over DisallowNulls. This declaration could be in either aspect, or in another, ordering aspect:

Pointcuts that appear inside of declare forms have certain restrictions. Like other pointcuts, these pick out join points, but they do so in a way that is statically determinable.

Consequently, such pointcuts may not include, directly or indirectly (through user-defined pointcut declarations) pointcuts that discriminate based on dynamic (runtime) context. Therefore, such pointcuts may not be defined in terms of

all of which can discriminate on runtime information.

The aspect declaration is similar to the class declaration in that it defines a type and an implementation for that type. It differs in a number of ways:

To support abstraction and composition of crosscutting concerns, aspects can be extended in much the same way that classes can. Aspect extension adds some new rules, though.

Unlike class expressions, aspects are not instantiated with new expressions. Rather, aspect instances are automatically created to cut across programs. A program can get a reference to an aspect instance using the static method aspectOf(..).

Because advice only runs in the context of an aspect instance, aspect instantiation indirectly controls when advice runs.

The criteria used to determine how an aspect is instantiated is inherited from its parent aspect. If the aspect has no parent aspect, then by default the aspect is a singleton aspect. How an aspect is instantiated controls the form of the aspectOf(..) method defined on the concrete aspect class.

Code written in aspects is subject to the same access control rules as Java code when referring to members of classes or aspects. So, for example, code written in an aspect may not refer to members with default (package-protected) visibility unless the aspect is defined in the same package.

While these restrictions are suitable for many aspects, there may be some aspects in which advice or inter-type members needs to access private or protected resources of other types. To allow this, aspects may be declared privileged. Code in priviliged aspects has access to all members, even private ones.

In this case, if A had not been declared privileged, the field reference c.i would have resulted in an error signaled by the compiler.

If a privileged aspect can access multiple versions of a particular member, then those that it could see if it were not privileged take precedence. For example, in the code

A's private inter-type field C.i, initially bound to 999, will be referenced in the body of the advice in preference to C's privately declared field, since A would have access to its own inter-type fields even if it were not privileged.

Note that a privileged aspect can access private inter-type declarations made by other aspects, since they are simply considered private members of that other aspect.

The java language form Foo.class is implemented in bytecode with a call to Class.forName guarded by an exception handler catching a ClassNotFoundException.

The java language + operator, when applied to String arguments, is implemented in bytecode by calls to StringBuffer.append.

In both of these cases, the current AspectJ compiler operates on the bytecode implementation of these language features; in short, it operates on what is really happening rather than what was written in source code. This means that there may be call join points to Class.forName or StringBuffer.append from programs that do not, at first glance, appear to contain such calls:

In short, the join point model of the current AspectJ compiler considers these as valid join points.

The end of exception handlers cannot reliably be found in Java bytecode. Instead of removing the handler join point entirely, the current AspectJ compiler restricts what can be done with the handler join point:

The first of these is relatively straightforward. If any piece of after advice (returning, throwing, or "finally") would normally apply to a handler join point, it will not in code output by the current AspectJ compiler. A compiler warning is generated, whenever this is detected to be the case. before advice is allowed.

The second is that the control flow of a handler join point is not picked out. For example, the following pointcut

will capture all join points in the control flow of a call to void foo(), but it will not capture those in the control flow of an IOException handler. It is equivalent to cflow(call(void foo())). In general, cflow(handler(Type)) will not pick out any join points, the one exception to this is join points that occur during the execution of any before advice on the handler.

This does not restrict programs from placing before advice on handlers inside other control flows. This advice, for example, is perfectly fine:

A source-code implementation of AspectJ (such as AspectJ 1.0.6) is able to detect the endpoint of a handler join point, and as such will likely have fewer such restrictions.

The code for Java initializers, such as the assignment to the field d in

are considered part of constructors by the time AspectJ gets ahold of bytecode. That is, the assignment of d to the square root of two happens inside the default constructor of C.

Thus inter-type constructors will not necessarily run a target type’s initialization code. In particular, if the inter-type constructor calls a super-constructor (as opposed to a this constructor), the target type’s initialization code will not be run when that inter-type constructor is called.

It is the job of an inter-type constructor to do all the required initialization, or to delegate to a this constructor if necessary.