The AspectJ^TM Development Environment Guide

AspectJ introduces two new paths for the binary input to the weaver which you’ll find referenced in ajc, the AspectJ compiler/weaver, AspectJ Ant Tasks, and Load-Time Weaving.

As in Java, the classpath is where the AspectJ tools resolve types specified in the program. When running an AspectJ program, the classpath should contain the classes and aspects along with the AspectJ runtime library, aspectjrt.jar.

In AspectJ tools, the aspectpath is where to find binary aspects. Like the classpath, it can include archives (.jar and .zip files) and directories containing .class files in a package layout (since binary aspects are in .class files). These aspects affect other classes in exactly the same way as source-level aspects, but are themselves not affected. When deploying programs, the original aspects must be included on the runtime classpath.

In AspectJ tools, the inpath is where to find binary input - aspects and classes that weave and may be woven. Like the classpath, it can include archives and class directories. Like the aspectpath, it can include aspects that affect other classes and aspects. However, unlike the aspectpath, an aspect on the inpath may itself be affected by aspects, as if the source were all compiled together. When deploying aspects that were put on the inpath, only the woven output should be on the runtime classpath.

Although types in the inpath and the aspectpath need to be resolved by the AspectJ tools, you usually do not need to place them on the classpath because this is done automatically by the compiler/weaver. But when using the WeavingURLClassLoader, your code must explicitly add the aspects to the classpath so they can be resolved (as you’ll see in the sample code and the aj.bat script).

The most common mistake is failing to add aspectjrt.jar to the classpath. Also, when weaving with binary aspects, users forget to deploy the aspect itself along with any classes it requires. A more subtle mistake is putting a binary aspect (BA) on the inpath instead of the aspectpath. In this case the aspect BA might be affected by an aspect, even itself; this can cause the program to fail, e.g., when an aspect uses exclusion to avoid infinite recursion but fails to exclude advice in aspect BA.

The latter is one of many ways that mistakes in the build process can affect aspects that are written poorly. Aspects should never rely on the boundaries of the build specification to narrow the scope of their crosscutting, since the build can be changed without notice to the aspect developer. Careful users might even avoid relying on the implementation scope, to ensure their AspectJ code will run on other implementations.

ajc accepts source files with either the .java extension or the .aj extension. We normally use .java for all of our files in an AspectJ system — files that contain aspects as well as files that contain classes. However, if you have a need to mechanically distinguish files that use AspectJ’s additional functionality from those that are pure Java we recommend using the .aj extension for those files.

We’d like to discourage other means of mechanical distinction such as naming conventions or sub-packages in favor of the .aj extension.

AspectJ is a compatible extension to the Java programming language. The AspectJ compiler adheres to the The Java Language Specification, Second Edition and to the The Java Virtual Machine Specification, Second Edition and runs on any Java 2 compatible platform. The code it generates runs on any Java 1.1 or later compatible platform. For more information on compatibility with Java and with previous releases of AspectJ, see Version Compatibility.

Compile two files:

To avoid specifying file names on the command line, list source files in a line-delimited text argfile. Source file paths may be absolute or relative to the argfile, and may include other argfiles by @-reference. The following file sources.lst contains absolute and relative files and @-references:

Compile the files using either the -argfile or @ form:

Argfiles are also supported by jikes and javac, so you can use the files in hybrid builds. However, the support varies:

Bytecode weaving using -inpath: AspectJ 1.2 supports weaving .class files in input zip/jar files and directories. Using input jars is like compiling the corresponding source files, and all binaries are emitted to output. Although Java-compliant compilers may differ in their output, ajc should take as input any class files produced by javac, jikes, eclipse, and, of course, ajc. Aspects included in -inpath will be woven into like other .class files, and they will affect other types as usual.

Aspect libraries using -aspectpath: AspectJ 1.1 supports weaving from read-only libraries containing aspects. Like input jars, they affect all input; unlike input jars, they themselves are not affected or emitted as output. Sources compiled with aspect libraries must be run with the same aspect libraries on their classpath.

The following example builds the tracing example in a command-line environment; it creates a read-only aspect library, compiles some classes for use as input bytecode, and compiles the classes and other sources with the aspect library.

The tracing example is in the AspectJ distribution ({aspectj}/doc/examples/tracing). This uses the following files:

Below, the path separator is taken as ";", but file separators are "/". All commands are on one line. Adjust paths and commands to your environment as needed.

Setup the path, classpath, and current directory:

Build a read-only tracing library:

Build the application with tracing in one step:

Run the application with tracing:

Build the application with tracing from binaries in two steps:

Run the application with tracing (same as above):

Run the application without tracing:

The AspectJ compiler is implemented completely in Java and can be called as a Java class. The only interface that should be considered public are the public methods in org.aspectj.tools.ajc.Main. E.g., main(String[] args) takes the the standard ajc command line arguments. This means that an alternative way to run the compiler is

To access compiler messages programmatically, use the methods setHolder(IMessageHolder holder) and/or run(String[] args, IMessageHolder holder). ajc reports each message to the holder using IMessageHolder.handleMessage(..). If you just want to collect the messages, use MessageHandler as your IMessageHolder. For example, compile and run the following with aspectjtools.jar on the classpath:

Unlike traditional java compilers, the AspectJ compiler may in certain cases generate classfiles from multiple source files. Unfortunately, the original Java class file format does not support multiple SourceFile attributes. In order to make sure all source file information is available, the AspectJ compiler may in some cases encode multiple filenames in the SourceFile attribute. When the Java VM generates stack traces, it uses this attribute to specify the source file.

(The AspectJ 1.0 compiler also supports the .class file extensions of JSR-45. These permit compliant debuggers (such as jdb in Java 1.4.1) to identify the right file and line even given many source files for a single class. JSR-45 support is planned for ajc in AspectJ 1.1, but is not in the initial release. To get fully debuggable .class files, use the -XnoInline option.)

Probably the only time you may see this format is when you view stack traces, where you may encounter traces of the format

where instead of the usual

format, you see

In this case, LineNumber is the usual offset in lines plus the "start line" of the actual source file. That means you use LineNumber both to identify the source file and to find the line at issue. The number in [brackets] after each file tells you the virtual "start line" for that file (the first file has a start of 0).

In our example from the null pointer exception trace, the virtual start line is 1030. Since the file SynchAspect.java "starts" at line 1000 [1k], the LineNumber points to line 30 of SynchAspect.java.

So, when faced with such stack traces, the way to find the actual source location is to look through the list of "start line" numbers to find the one just under the shown line number. That is the file where the source location can actually be found. Then, subtract that "start line" from the shown line number to find the actual line number within that file.

In a class file that comes from only a single source file, the AspectJ compiler generates SourceFile attributes consistent with traditional Java compilers.

The following tables list the supported parameters. For any parameter specified as a Path, a single path can be specified directly as an attribute, multiple paths can be specified using a nested element of the same name, and a common path can be reused by defining it as a global and passing the id to the corresponding {name}ref attribute. See Path below for more details.

Most attributes and nested elements are optional. The compiler requires that the same version of aspectjrt.jar be specified on the classpath, and that some sources be be specified (using one or more of sourceroots, injars, inpath, argfiles, and/or srcdir (with patterns)). When in incremental mode, only sourceroots may be specified.

Boolean parameters default to false unless otherwise stated.

AjcTask (iajc) options for specifying sources

AjcTask (iajc) options for specifying output

AjcTask (iajc) options for specifying compiler behavior

AjcTask (iajc) options for specifying compiler side-effects and messages

AjcTask (iajc) options for specifying Eclipse compiler options

This task forms an implicit FileSet and supports all attributes of fileset (dir becomes srcdir) as well as the nested include, exclude, and patternset elements. These can be used to specify source files. However, it is better to use sourceroots to specify source directories unless using filters to exclude some files from compilation.

Some parameters are path-like structures containing one or more elements; these are sourceroots, argfiles, injars, inpath, classpath, bootclasspath, forkclasspath, and aspectpath. In all cases, these may be specified as nested elements, something like this:

As with other Path-like structures, they may be defined elsewhere and specified using the refid attribute:

The task also supports an attribute {name}ref for each such parameter. E.g., for aspectpath:

A minimal build script defines the task and runs it, specifying the sources:

Below is script with most everything in it. The compile process…​

When this target is built, the compiler will build once and then wait for input from the user. Messages are printed as usual. When the user has quit, then this runs the application.

For an example of a build script, see ../examples/build.xml.

Unlike javac, the ajc compiler always processes all input because new aspects can apply to updated classes and vice-versa. However, in the case where no files have been updated, there is no reason to recompile sources. One way to implement that is with an explicit dependency check using the uptodate task:

When using this technique, be careful to verify that binary input jars are themselves up-to-date after they would have been modified by any build commands.

Users may specify a message holder to which the compiler will pass all messages as they are generated. This will override all of the normal message printing, but does not prevent the task from failing if exceptions were thrown or if failonerror is true and the compiler detected errors in the sources.

Handling messages programmatically could be useful when using the compiler to verify code. If aspects consist of declare [error|warning], then the compiler can act to detect invariants in the code being processed. For code to compare expected and actual messages, see the AspectJ testing module (which is not included in the binary distribution).

To build using the adapter, put the aspectjtools.jar on the system/ant classpath (e.g., in ${ANT_HOME}/lib) and define the build.compiler property as the fully-qualified name of the class, org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter.

The AspectJ compiler should run for any compile using the Javac task (for options, see the Ant documentation for the Javac task). For example, the call below passes all out-of-date source files in the src/org/aspectj subdirectories to the ajc command along with the destination directory:

To pass ajc-specific arguments, use a compilerarg entry.

The Javac task does special handling of source files that can interfere with ajc. It removes any files that are not out-of-date with respect to the corresponding .class files. But ajc requires all source files, since an aspect may affect a source file that is not out of date. (For a solution to this, see the build.compiler.clean property described below.) Conversely, developers sometimes specify a source directory to javac, and let it search for files for types it cannot find. AspectJ will not do this kind of searching under the source directory (since the programmer needs to control which sources are affected). (Don’t confuse the source directory used by Javac with the source root used by ajc; if you specify a source root to ajc, it will compile any source file under that source root (without exception or filtering).) To replace source dir searching in Javac, use an Ant filter to specify the source files.

The adapter supports any ajc command-line option passed using compilerarg, as well as the following options available only in AjcTask. Find more details on the following options in AjcTask (iajc).

Special considerations when using Javac and compilerarg:

Most attributes and nested elements are optional. The compiler requires that the same version of aspectjrt.jar be specified on the classpath, and that some sources be be specified (using one or more of argfiles and srcdir (with patterns)).

Boolean parameters default to false unless otherwise stated.

The following table shows that many of the unique parameters in AspectJ 1.0 are no longer supported.

This task forms an implicit FileSet and supports all attributes of fileset (dir becomes srcdir) as well as the nested include, exclude, and patternset elements. These can be used to specify source files.

ajc's srcdir, classpath, bootclasspath, extdirs, and jvmarg attributes are path-like structures and can also be set via nested src, classpath, bootclasspath, extdirs, and jvmargs elements, respectively.

Following is a declaration for the ajc task and a sample invocation that uses the ajc compiler to compile the files listed in default.lst into the dest dir:

This build script snippet

compiles all .java files specified in the demo.lst and stores the .class files in the ${build} directory. Unlike the Javac task, the includes attribute is empty by default, so only those files specified in demo.lst are included.

This next example

compiles .java files under the ${src} directory in the spacewar and coordination packages, and stores the .class files in the ${build} directory. All source files under spacewar/ and coordination/ are used, except Debug.java.

See ../examples/build.xml for an example build script.

For the most up-to-date information on known problems, see the bug database for unresolved compiler bugs or taskdef bugs .

When running Ant build scripts under Eclipse 2.x variants, you will get a VerifyError because the Eclipse Ant support fails to isolate the Ant runtime properly. To run in this context, set up iajc to fork (and use forkclasspath). Eclipse 3.0 will fork Ant processes to avoid problems like this.

Memory and forking: Users email most often about the ajc task running out of memory. This is not a problem with the task; some compiles take a lot of memory, often more than similar compiles using javac.

Forking is now supported in both the Ajc11CompilerAdapter (javac) and AjcTask (iajc), and you can set the maximum memory available. You can also not fork and increase the memory available to Ant (see the Ant documentation, searching for ANT_OPTS, the variable they use in their scripts to pass VM options, e.g., ANT_OPTS=-Xmx128m).

For questions, you can send email to aspectj-users@dev.eclipse.org. (Do join the list to participate!) We also welcome any bug reports, patches, and features; you can submit them to the bug database at https://bugs.eclipse.org/bugs using the AspectJ product and Ant component.

As of AspectJ 5 aspects (code style or annotation style) and woven classes are reweavable by default. If you are developing AspectJ applications that are to be used in a load-time weaving environment with an older version of the compiler you need to specify the -Xreweavable compiler option when building them. This causes AspectJ to save additional state in the class files that is used to support subsequent reweaving.

AspectJ 5 supports several ways of enabling load-time weaving for an application: agents, a command-line launch script, and a set of interfaces for integration of AspectJ load-time weaving in custom environments.

The weaver is configured using one or more META-INF/aop.xml files located on the class loader search path. Each file may declare a list of aspects to be used for weaving, type patterns describing which types should woven, and a set of options to be passed to the weaver. In addition AspectJ 5 supports the definition of concrete aspects in XML. Aspects defined in this way must extend an abstract aspect visible to the weaver. The abstract aspect may define abstract pointcuts (but not abstract methods). The following example shows a simple aop.xml file:

The DTD defining the format of this file is available here: https://www.eclipse.org/aspectj/dtd/aspectj.dtd.

An aop.xml file contains two key sections: aspects defines one or more aspects to the weaver and controls which aspects are to be used in the weaving process; weaver defines weaver options and which types should be woven.

The simplest way to define an aspect to the weaver is to specify the fully-qualified name of the aspect type in an aspect element. You can also declare (and define to the weaver) aspects inline in the aop.xml file. This is done using the concrete-aspect element. A concrete-aspect declaration must provide a pointcut definition for every abstract pointcut in the abstract aspect it extends. This mechanism is a useful way of externalizing configuration for infrastructure and auxiliary aspects where the pointcut definitions themselves can be considered part of the configuration of the service. Refer to the next section for more details.

The aspects element may optionally contain one or more include and exclude elements (by default, all defined aspects are used for weaving). Specifying include or exclude elements restricts the set of defined aspects to be used for weaving to those that are matched by an include pattern, but not by an exclude pattern. The within attribute accepts a type pattern of the same form as a within pcd, except that && and || are replaced by 'AND' and 'OR'.

Note that include and exclude elements affect all aspects declared to the weaver including those in other aop.xml files. To help avoid unexpected behaviour a lint warning is issued if an aspect is not declared as a result of of applying these filters. Also note aspect and concrete-aspect elements must be used to declare aspects to the weaver i.e. include and exclude elements cannot be used find aspects on the class loader search path.

The weaver element is used to pass options to the weaver and to specify the set of types that should be woven. If no include elements are specified then all types visible to the weaver will be woven. In addition the dump element can be used capture on disk byte-code of woven classes for diagnostic purposes both before, in the case of those generated at runtime, and after the weaving process.

When several configuration files are visible from a given weaving class loader their contents are conceptually merged. The files are merged in the order they are found on the search path (with a regular getResourceAsStream lookup) according to the following rules:

It is not an error for the same aspect to be defined to the weaver in more than one visible META-INF/aop.xml file. However, if the same concrete aspect is defined in more than one aop.xml file then an error will be issued. A concrete aspect defined in this way will be used to weave types loaded by the class loader that loaded the aop.xml file in which it was defined.

A META-INF/aop.xml can be generated by using either the -outxml or -outxmlfile options of the AspectJ compiler. It will simply contain a (possibly empty) set of aspect elements; one for each abstract or concrete aspect defined. When used in conjuction with the -outjar option a JAR is produced that can be used with the aj5 command or a load-time weaving environment.

It is possible to make an abstract aspect concrete by means of the META-INF/aop.xml file. This is useful way to implement abstract pointcuts at deployment time, and also gives control over precedence through the precedence attribute of the concrete-aspect XML element. Consider the following:

This aspect is equivalent to the following in code style:

This aspect (in either style) can be made concrete using META-INF/aop.xml. It defines the abstract pointcut scope(). When using this mechanism the following rules apply:

A limitation of the implementation of this feature in AspectJ 1.5.0 is that aspects defined using aop.xml are not exposed to the weaver. This means that they are not affected by advice and ITDs defined in other aspects. Support for this capability will be considered in a future release.

If more complex aspect inheritance is required use regular aspect inheritance instead of XML. The following XML definition shows a valid concrete sub-aspect for the abstract aspects above:

It is important to remember that the name attribute in the concrete-aspect directive defines the fully qualified name that will be given to the concrete aspect. It must a valid class name because the aspect will be generated on the fly by the weaver. You must also ensure that there are no name collisions. Note that the concrete aspect will be defined at the classloader level for which the aop.xml is visible. This implies that if you need to use the aspectof methods to access the aspect instance(s) (depending on the perclause of the aspect it extends) you have to use the helper API org.aspectj.lang.Aspects.aspectOf(..) as in:

As described in the previous section, the concrete-aspect element in META-INF/aop.xml gives the option to declare the precedence, just as @DeclarePrecedence or declare precedence do in aspect source code.

Sometimes it is necessary to declare precedence without extending any abstract aspect. It is therefore possible to use the concrete-aspect element without the extends attribute and without any pointcut nested elements, just a precedence attribute. Consider the following:

This deployment time definitions is only declaring a precedence rule. You have to remember that the name attribute must be a valid fully qualified class name that will be then reserved for this concrete-aspect and must not conflict with other classes you deploy.

The table below lists the AspectJ options supported by LTW. All other options will be ignored and a warning issued.

When using Java 5 the JVMTI agent can be used by starting the JVM with the following option (adapt according to the path to aspectjweaver.jar):

Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer part of AspectJ. JRockit JDK never supported Java versions higher than 1.6. Several JRockit JVM features are now part of HotSpot and tools like Mission Control available for OpenJDK and Oracle JDK.

AspectJ programs can run on any Java VM of the required version. The AspectJ tools produce Java bytecode .class files that run on Java compatible VM’s. If a Java class is changed by an aspect, the resulting class is binary compatible (as defined in the Java Language Specification). Further, the AspectJ compiler and weaving do all the exception checking required of Java compilers by the Java specifications.

Like other Java compilers, the AspectJ compiler can target particular Java versions. Obviously, code targeted at one version cannot be run in a VM of a lesser version. The aspectjrt.jar is designed to take advantage of features available in Java 2 or Java 5, but will run in a JDK 1.1.x environment, so you can use AspectJ to target older or restricted versions of Java. However, there may be restricted variants of JDK 1.1.x that do not have API’s used by the AspectJ runtime. If you deploy to one of those, you can email aspectj-dev@eclipse.org or download the runtime code to modify it for your environment.

Aside from the runtime, running the AspectJ tools themselves will require a more recent version of Java. You might use Java 5 to run the AspectJ compiler to produce code for Java 1.1.8.

When deploying AspectJ programs, include on the classpath the classes, aspects, and the AspectJ runtime library (aspectjrt.jar). Use the version of the runtime that came with the tools used to build the program. If the runtime is earlier than the build tools used, it’s very likely to fail. If the runtime is later than the build tools used, it’s possible (but not guaranteed) that it will work.

Given that, three scenarios cause problems. First, you deploy new aspects into an an existing system that already has aspects that were built with a different version. Second, the runtime is already deployed in your system and cannot be changed (e.g., some application servers put aspectjrt.jar on the bootclasspath). Third, you (unintentionally) deploy two versions of the runtime, and the one loaded by a parent loader is used).

In earlier versions of AspectJ, these problems present in obscure ways (e.g., unable to resolve a class). In later versions, a stack trace might even specify that the runtime version is out of sync with an aspect. To find out if the runtime you deployed is the one actually being used, log the defining class loader for the aspects and runtime.

Generally, binary aspects can be read by later versions of the weaver if the aspects were built by version 1.2.1 or later. (Some future weavers might have documented limitations in how far back they go.) If a post-1.2.1 weaver reads an aspect built by a later version, it will emit a message. If the weaver reads in a binary aspect and writes it out again, the result will be in the form produced by that weaver, not the original form of the aspect (just like other weaver output).

With unreleased or development versions of the tools, there are no guarantees for binary compatibility, unless they are stated in the release notes. If you use aspects built with development versions of the weaver, be careful to rebuild and redeploy with the next released version.

Generally, AspectJ source files can be read by later versions of the compiler. Language features do not change in dot releases (e.g., from 1.2.1 to 1.2.2). In some very rare cases, a language feature will no longer be supported or may change its meaning; these cases are documented in the release notes for that version. Some changes like this were necessary when moving to binary weaving in the 1.1 release, but at this time we don’t anticipate more in the future. You might also find that the program behaves differently if you relied on behavior specific to that compiler/weaver, but which is not specified in the Semantics appendix to the Programming Guide.

Let’s say your program behaves differently after being built with a new version of the AspectJ tools. It could be a bug that was introduced by the tools, but often it results from relying on behavior that was not guaranteed by the compiler. For example, the order of advice across two aspects is not guaranteed unless there is a precedence relationship between the aspects. If the program implicitly relies on a certain order that obtains in one compiler, it can fail when built with a different compiler.

Another trap is deploying into the same system, when the aspectjrt.jar has not been changed accordingly.

Finally, when updating to a version that has new language features, there is a temptation to change both the code and the tools at the same time. It’s best to validate the old code with the new tools before updating the code to use new features. That distinguishes problems of new engineering from those of new semantics.