AspectJ Design Overview

Let’s trace the following example program through the compiler.

When parsed, this program will produce the following tree.

Let’s look more closely at the pointcut declaration:

The pointcut declaration is implemented as a subtype of a method declaration. The actual pointcut is parsed by the weaver module. This parsing happens as part of the shallow parse phase. This is because this information might be needed to implement a declare soft.

Next we look at the processing for an advice declaration:

After parsing, the AdviceDeclaration.postParse method will be called to make this a valid MethodDeclaration so that the standard eclipse code for analyzing a method body can be applied to the advice. After postParse, the selector is filled in and several additional arguments are added for the special thisJoinPoint forms that could be used in the body.

At this point the statements field which will hold the body of the advice is still null. This field is not filled in until the second stage of the compiler when full parsing is done on each source file as a prelude to generating the classfile.

The main classes in this module are shown in the following diagram:

Do a Team→Synchronize With Repository and make sure that your tree is completely in sync with the existing repository. Make sure to address any differences before moving on.

Run the existing test suite. I currently do this in four steps:

There should be no failures when you run these tests. If there are failures, resolve them with the AspectJ developers before moving on.

a. Create a new file in tests/design/pcds/Throw.java

b. Create a temporary test harness file to run just this test in myTests.xml

c. Run this test using the harness. You should see:

Modify runtime/org.aspectj.lang/JoinPoint.java to add a name for the Throw shadow kind.

Modify weaver/org.aspectj.weaver/Shadow.java to add the Throw shadow kind. This adds a static typesafe enum for the Throw Kind. The constructor uses the name from the runtime API to ensure that these names will always match. The '12' is used for serialization of this kind to classfiles and is part of the binary API for aspectj. The final 'true' indicates that this joinpoint has its arguments on the stack. This is because the throw bytecode in Java operates on a single argument that is a Throwable which must be the top element on the stack. This argument is removed from the stack by the bytecode.

We also modify the neverHasTarget method to include the Throw kind because in Java there is no target for the throwing of an exception.

In the read method on Shadow.Kind, add another case to read in our new Shadow.Kind.

Modify weaver/org.aspectj.weaver.bcel/BcelClassWeaver.java to recognize this new joinpoint kind. In the method

Add a test for this instruction, i.e.

Then, modify BcelShadow.java to create this new kind of join point shadow:

Finally modify weaver/org.aspectj.weaver/Member.java to generate the needed signature

Run the proto test again and you should see:

That last line shows the 'throw(catch(Throwable))' join point. This is a slightly confusing string form, but it is the first sign of our brand new join point. The reason for the weird 'catch(Throwable)' part is that we used Member.HANDLER for the kind of the signature of this join point. That’s clearly not correct. We’ll fix that at the end of the lesson as part of the clean-up. For now, let’s go on with the interesting parts.

Add a second piece of before advice to the test aspect A:

When we run the test again we’ll get a long error message from the harness. The interesting part of the message is the following:

This error is not quite what you might have expected. You might have hoped for a syntax error saying that there is not 'throw' pointcut designator defined. Unfortunately, this is a weakness in the syntax of AspectJ where primitive PCDs and named PCDs have the same syntax, so the compiler can’t tell the difference between a misspelled or non-existent primitive PCD and a named PCD reference that is missing. This also has some impact on extending the primitive PCDs because it will break existing programs. In this case, when we add the throw PCD we will break any existing programs that use throw as the name for a user-defined PCD. Fortunately because throw is a Java keyword this particular change is very safe.

Modify the parseSinglePointcut method in weaver/org.aspectj.weaver.patterns/PatternParser.java to add one more else if clause for the throw pcd:

Modify the matches method in weaver/org.aspectj.weaver.patterns/SignaturePattern.java to add:

Run the proto test again and you should see:

Make sure that you see the 'about to throw' printed before moving on. This shows that the throw PCD is now successfully matching the throw join point shadow we added earlier.

Now that we have a valid pcd for this advice, we can simplify our test case. Modify our test aspect A to be the following. In addition to removing the overly generic withincode pcd, this change also prints the actual object that is about to be thrown:

When we run the test again we should see the output below:

Congratulations! You’ve just implemented the throw join point and PCD. This code isn’t yet ready to be checked into any repository. It still has some rough edges that need to be smoothed. However, you’ve now added a new join point to the AspectJ language and a corresponding PCD to match it. This is a good time to take a break before moving on to part two.

Since we aren’t going to recover the static type of the exception thrown, we need to fix the parser for the throw pcd to remove this information. We’ll fix the PatternParser code that we added in step 1.6 to read as follows:

Notice that this code also starts to fix the member kind to be Member.THROW instead of the bogus Member.HANDLER that we were using before. To make this work we have a set of things to do. First, let’s create this new kind in org.aspectj.weaver.Member. Find where the HANDLER kind is defined there, and add a corresponding throw kind:

We also need to fix the serialization kind in Member.Kind.read(DataInputStream) just above this constant list to add a case for this new kind:

Still in this file, we also need to fix Member.makeThrowSignature to use this new kind:

If you run the test now you’ll get an error from the parser reminding us that the throw pcd now doesn’t accept a type pattern:

This is an easy fix to the test case as we modify our pcd for the new syntax in the aspect A in our Throws.java test code:

Now when we run the test case it looks like everything’s fixed and we’re passing:

The pass result from running our test should worry you. Unlike previous runs, this test run doesn’t show the output from our System.out.println in the before advice. So, it’s clear this advice is not running. The problem is that even though the advice is not running, the test case is passing. We need to make this a real test case to fix this. We’ll do that by adding code that notes when the advice runs and then checks for this event. This code uses the Tester.event and Tester.checkEvent methods:

Now when we run our test case it will fail. This failure is good because we’re not matching the throw join point anymore.

In org.aspectj.weaver.patterns.SignaturePattern.matches, we need to handle throw signature matching the same way we handle advice signature matching. Both of these pcds match solely on the kind of join point and use combinations with other pcds to narrow their matches. So, find the line for kind == Member.ADVICE and add the same line below it for Member.THROW.

This change will make our test case pass again. Run it to be sure.

There’s an interesting tension between a good automated test and a good test for development. Our new test case now correctly includes an automated test to let us know when we are and are not matching the new throw join point. However, without the println the test doesn’t feel as satisfactory to me to run during development. I often like to turn this kind of printing back on the see what’s happening. If you uncomment to System.out.println in the test aspect A and rerun the test, you won’t be very happy with the results:

It looks like there’s more work to do to add the new member kind for Member.THROW. This problem only shows up when we try to print thisJoinPoint. It’s showing that we haven’t updated the reflection API to understand this new signature kind.

We need to add a couple of classes to the reflection API to implement the throw signature. Because we decided at the beginning of this section to not include the static type of the exception thrown in the throw signature, these classes are extremely simple. Nevertheless, we have to build them. Notice that when we add new source files to the system we need to include the standard eclipse EPL license header.

To finish up our work in the runtime module, we need to extend org.aspectj.runtime.reflect.Factory to add a factory method for this new signature kind:

We’re not done yet. We still need to fix up the org.aspectj.weaver.Member class to use these new methods and types and fix the unimplemented exception that started us down this road in the first place. First let’s add a method to create a string for the throw signature. This is a very simple method copied from the other create*SignatureString methods.

Now we need to modify three methods to add cases for the new Member.THROW kind. First, Member.getSignatureMakerName add:

Next, to Member.getSignatureType add:

Finally, to Member.getSignatureString add:

With all of these changes in place we should have working code for thisJoinPoint reflection using our new join point and signature kinds. Rerun the test to confirm:

Modify the before advice to include at least minimal checks of the new reflective information:

As usual, you should rerun the tests and make sure they pass.

With these changes to the reflection code, it looks like we have a working version of the throw join point and there are no obvious pieces that we’ve skipped. Take a break before proceeding to the final phase of tests.

Rerun the tests you ran at the beginning of part 1. Any failures that occur should be resolved at this point. At the time of writing this tutorial, I found 31 failures in the BcWeaverModuleTests. These failures are for all of the test cases that check the exact set of shadows produces by a given program. These test cases need to be updated based on the new join point we’re adding. These particular test cases will probably be removed from the AspectJ test suite very soon because they’ve shown themselves to be very fragile over time and they often break for changes that are not introducing new bugs. However, you should be aware of this kind of failure because you may find it in other unit tests.

You should expect to see at least one other test case fail when you run ajcTests.xml. Here’s the failure message:

Most of this message can be ignored. To find out what went wrong you should look for messages that have "fail" in them. The last line tells you what happened. There was an unexpected event, "before AllTargetJoinPoints throw(catch(Throwable))". This is the signature for one of the new throw join points that we added in part 1. How could an existing test case match this new join point? The failing test case uses 'within(TargetClass)' to collect information about ALL join points that are lexically within a given class. Whenever we add a new kind of join point to the language we will extend the set of points matched by pcds like within. This means that these changes need to be very prominently noted in the release notes for any AspectJ release. Since we’re not writing documentation in this tutorial, we will move on an fix the test case.

Now we need to fix this failing test case. The first step is to copy the test specification into our local myTests.xml file. The easiest way to do this is to copy the title of the failing test from the output buffer, then open ajcTests.xml and use find to search for this title. Then copy the xml spec for this one test into myTests.xml. Finally, run myTests.xml to make sure you got the failing test. You should see the same failure as before in step 1, but you should see it a lot faster because we’re only running 2 tests.

To fix the test we need to find the source code. If you look at the test specification, you can see that the source file is the new directory with the name NegativeSourceLocation.java. Looking at the bottom of this file, we see a large list of expected events. These are the join points that we expect to see. If we look back up in TargetClass, we can see that the only occurence of throw is just before the handler for catch(Error) and right after the call to new Error. We should add our new expected event between these two:

Run the test suite again to see that this test now passes.

There is a lot we should do now to extend test coverage for this new kind of join point. For the purpose of this tutorial, we’re just going to make sure that the new join point kind is compatible with all 5 kinds of advice. Let’s extend our current simple Throws test to check for before and the three kinds of after advice:

Run this test to confirm that it still passes. This is a very nice property of the orthogonality of the implementation of join points and advice. We never had to do any implementation work to make our new join point kind work for before and all three kinds of after advice.

Let’s create a new test case to see how this new join point interacts with around advice.

When we run this test case we get a very unpleasant result:

A VerifyError at runtime is the second worst kind of bug the AspectJ compiler can produce. The worst is silently behaving incorrectly.

Unfortunately, this VerifyError is either impossible or very hard to fix. Think about what would happen if the around advice body didn’t call proceed. In this case the local variable x would in fact be uninitialized. There is another serious language design question here, and for a real implementation this would once again be the time to start a discussion on the aspectj-dev mailing list to reach consensus on the best design. For the purpose of this tutorial we’re once again going to make the language design choice that is easiest to implement and press on.

The easiest solution to implement is to prohibit around advice on throw join points. There are already a number of these kinds of rules implemented in the org.aspectj.weaver.Shadow.match(Shadow, World) method. We can add our new rule at the beginning of the if(kind == AdviceKind.Around) block:

Now if we rerun our test we’ll see errors telling us that around is prohibited on throw join points:

To finish this test case up we need to modify the specification to be looking for these errors as the correct behavior. This will produce the following specification:

Run myTests.xml one last time to see both tests passing.

You probably want to stop here for the purposes of this tutorial. We’ve pointed out several language design decisions that would need to be resolved before actually adding a throw join point to AspectJ. Some of those might involve a large amount of additional implementation work. If this was actually going into the tree, it would also be important to add several more test cases exploring the space of what can be done with throw.

Assuming those issues were resolved and you are ready to commit this new feature to the tree there are three steps left to follow:

The different kinds of join points, the different primitive pointcuts, and the different kinds of advice can be used in any combination.

This was one of the hardest parts of the design to get right, because of the "constructor must call super" rule in Java. But we finally got this in 1.0.

Abelson and Sussman say that composition and abstraction are the key elements of a real language. Clearly the pointcut mechanism is the new thing in AspectJ, and so it was critical that it support composition and abstraction. The fact that someone can write:

is what makes it possible for people to really work with crosscutting structure and make their code more clear.

The efficiency, code quality and programmer productivity arguments for this have been made elsewhere, so I won’t repeat them.

AspectJ code is as fast as the equivalent functionality, written by hand, in a scattered and tangled way.

I’ve heard some people say that AspectJ is too big and too complex. In the most important sense of simple AspectJ is simple. I can reason about any AspectJ program with a simple model. The kernel of AspectJ is simple, and the orthogonality described above means that its easy to start with just the kernel and slowly add to that.

Its pretty clear to pull out this kernel of AspectJ. I would argue that the right idea for a standard AOP API is this kernel, packaged in a way that allows building more sophisticated tools on top of it.

AspectJ is neutral on whether weaving happens at pre-process, compile, post-process, load, JIT or runtime. This neutrality is critical. Its why there are serious JVM experts who are already thinking about JVM support for AspectJ.

There’s more, but I think these are the most important ones. I think any functionality this group comes up with should also meet these criteria.