AspectJ in OpenPixi - PetcuAlexandru/openpixi GitHub Wiki

In OpenPixi we use AspectJ framework on few places to debug or profile the application. Since working with AspectJ is not straight forward and often quite technical we offer some help here on how to use AspectJ within OpenPixi.

What is AspectJ?

Put in simple words AspectJ enables us to define special points in our source code (called pointcuts) where we would like to inject some further code. Why would we like to inject something into our source code? Why don't we write the injected code directly into our source in the first place? That is because we often write auxiliary code which we would like to run only sometimes; such as, debugging code or profiling code. What is more, this auxiliary code is often spread across many classes violating the object oriented principle of encapsulating logically similar code into as few classes as possible.

For instance, in OpenPixi we use AspectJ for profiling (measuring the time). Lets take a look on what it requires to take some time measurements

  • We need to start the timer before the action we want to measure begins.
  • We need to stop the timer after the action finishes.
  • We would most probably like to do some simple calculations which will give us time in seconds or other human readable unit.
  • In the end we would like to remember the time in some member variable of the class which action we were measuring.

The ordinary java code which would fulfill the above requirements has couple of disadvantages

  • It's responsibility is to measure the time what is totally different from the responsibility of our original code which runs the physical simulation; thus, it renders our original code less readable.
  • We do not always need this code and in production version we would like to leave out this code to make the production version as fast as possible.

Using AspectJ we overcome the above drawbacks. First of all, we define all the time measuring code at one place; thus, it improves the readability. Secondly, we can decide at compile time whether we want this measuring code to be interleaved with our original code or not.

To learn more about AspectJ visit AspectJ homepage (especially the AspectJ Programming Guide is very useful). Alternatively, you can also take a look at ParticleID class from org.openpixi.pixi.aspectj.debug package which is richly commented to offer some basic introduction to AspectJ.

How do I compile and run Maven aspectj profiles in Eclipse?

To compile OpenPixi with maven profiles which use AspectJ such as "aspectj-debug" or "aspectj-profile" you have to do the following

  • Turn off the automatic build by unchecking the option Project -> Build Automatically
  • Clean the project: Project -> Clean
  • Create a custom maven build configuration
    • Go to Run -> Run Configurations
    • Click first on Maven Build and then on New launch configuration (the first button on the left above the search bar)
    • Choose some arbitrary name for the run configuration (textbox on the very top)
    • To choose the Base directory click on Browse Workspace... and choose "pixi"
    • Into the Goals textbox type "compile"
    • Finally, into the Profiles textbox type the desired profile (eg. "aspectj-debug")
  • Run your custom maven build

Now you can normally run any class you want but remember that the automatic build is turned off, so for any changes to take effect you need to recompile the application with your custom maven build (not with Project -> Build Project !!!).

If you have AspectJ Development Tools Installed (AJDT) you can see a lot of errors in the AspectJ classes. To get rid of the errors you need to convert your project to AspectJ project. See the next section for solution.

If you would like to learn why the automatic build has to stay off read the section about compile problems.

How do I develop my own aspects in Eclipse?

Aspect is AspectJ's equivalent of Java's class. It simply defines some pointcuts and actions which should happen at those pointcuts. These actions are also called advices.

To use AspectJ and develop your own aspects for OpenPixi in Eclipse we recommend to install AspectJ Development Tools (AJDT) which will give you syntax highlighting, auto-complete and some error checking. After you install AJDT you might see a lot of errors in the AspectJ files (files with .aj ending). You need to convert your project to AspectJ project by

  • Right click on project root in package explorer (left panel) to invoke the context menu
  • Run Configuration -> Convert to AspectJ project

The disadvantage of the AJDT plugin is that it will also always compile all your aspects in the background. Consequently, you will always have particle movement tracing information displayed. To work around this we suggest to exclude the aspects from project build and use a custom maven build as explained in the section before.

AspectJ compile problems in IDE

IDEs like Eclipse or IntelliJ Idea use their own build process and they often do not follow the instructions written in the maven pom file too closely (especially with less standard plugins such as AspectJ compiler plugin). This problem arises also in OpenPixi when trying to compile one of the aspectj profiles. The IDEs fail to follow the instructions specified in the aspectj profiles. If they have some kind of plugin for aspectj installed, they usually compile all the aspects even though the aspectj profiles are turned off. If they do not have any plugin for aspectj they do not compile any aspect even though one of the aspectj profiles is turned on.

To solve this problem one has to turn off IDE's build process and make the IDE use maven to build the application. It is not enough to just force the IDE to use maven build as the automatic build can overwrite the results of the maven build.