AspectJ(tm) is a simple and practical extension to the Java(tm) programming language that adds to Java aspect-oriented programming (AOP) capabilities. AOP allows developers to reap the benefits of modularity for concerns that cut across the natural units of modularity. In object-oriented programs like Java, the natural unit of modularity is the class. In AspectJ, aspects modularize concerns that affect more than one class.

You compile your program using the AspectJ compiler (perhaps using the supported development environments) and then run it, supplying a small (< 100K) runtime library.

The AspectJ technologies include a compiler (ajc), a debugger (ajdb), a documentation generator (ajdoc), a program structure browser (ajbrowser), and integration with Eclipse, Sun-ONE/Netbeans, GNU Emacs/XEmacs, JBuilder, and Ant.

AspectJ can be used to improve the modularity of software systems.

Using ordinary Java, it can be difficult to modularize design concerns such as

The code for these concerns tends to be spread out across the system. Because these concerns won't stay inside of any one module boundary, we say that they crosscut the system's modularity.

AspectJ adds constructs to Java that enable the modular implementation of crosscutting concerns. This ability is particularly valuable because crosscutting concerns tend to be both complex and poorly localized, making them hard to deal with.

AspectJ has been designed as a compatible extension to Java. By compatible, we mean

The AspectJ tools run on any Java 2 Platform compatible platform. The AspectJ compiler produces classes that run on any Java 1.1 (or later) compatible platform.

AspectJ 1.1 source code and documentation is available under the Common Public License 1.0.

The AspectJ 1.0 tools are open-source software available under the Mozilla Public License 1.1. That documentation is available under a separate license that precludes for-profit or commercial redistribution.

Most users only want to use AspectJ to build programs they distribute. There are no restrictions here. When you distribute your program, be sure to include all the runtime classes from the aspectjrt.jar for that version of AspectJ. When distributing only the runtime classes, you need not provide any notice that the program was compiled with AspectJ or includes binaries from the AspectJ project, except as necessary to preserve the warranty disclaimers in our license.

AspectJ is based on over ten years of research at Xerox Palo Alto Research Center as funded by Xerox, a U.S. Government grant (NISTATP), and a DARPA contract.

It has evolved through open-source releases to a strong user community and now operates as an open source project at http://eclipse.org/aspectj The AspectJ team works closely with the community to ensure AspectJ continues to evolve as an effective aspect-oriented programming language and tool set.

The latest release is 1.2 which can be downloaded from the AspectJ project page, including sources as described Q:How do I get and compile the source code for AspectJ?. Development is focused on supporting applications, improving quality and performance, enhancing integration with IDE's, and building the next generations of the language.

The AspectJ compiler produces programs for any released version of the Java platform (jdk1.1 and later). When running, your program classes must be able to reach classes in the small (< 100K) runtime library (aspectjrt.jar) from the distribution. The tools themselves require J2SE 1.3 or later to run, but the compiler can produce classes for any 1.1-compliant version of the Java platform.

From AspectJ's web page , download the AspectJ distribution. The jar file is installed by executing

            java -jar jar file name
          

Do not try to extract the jar file contents and then attempt to execute java org.aspectj.tools.Main. (A NoClassDefFoundError exception will be thrown.) The AspectJ distribution is not designed to be installed this way. Use the java -jar form shown above.

To uninstall, remove the files the installer wrote in your file system. In most cases, you can delete the top-level install directory (and all contained files), after you remove any new or updated files you want to keep. On Windows, no registry settings were added or changed, so nothing needs to be undone. Do not install over prior versions, which might have different files. Delete the prior version first.

Many users adopt AspectJ incrementally, first using it to understand and validate their systems (relying on it only in development) and then using it to implement crosscutting concerns in production systems. AspectJ has been designed to make each step discrete and beneficial.

In order of increasing reliance, you may use AspectJ:

This adoption sequence works well in practice and has been followed by many projects.

AspectJ products are designed to make it easy to integrate AspectJ into an existing development process. Each release includes Ant tasks for building programs, the AspectJ Development Environment (AJDE) for writing aspects inside popular IDE's, and command-line tools for compiling and documenting Java and AspectJ code.

AspectJ provides replacements for standard Java tools:

For debugging, AspectJ supports JSR-45, which provides a mechanism for debugging .class files that have multiple source files. Debugger clients and VM's are beginning to support this; see Sun's J2SE 1.4.1 VM and jdb debugger and recent versions of JBuilder.

The AspectJ Development Environment (AJDE) enables programmers to view and navigate the crosscutting structures in their programs, integrated with existing support in popular Java IDE's for viewing and navigating object-oriented structures. For many programmers this provides a deeper understanding of how aspects work to modularize their concerns and permits them to incrementally extend their development practices without having to abandon their existing tools.

AJDE is a set of API's providing the basis for the following development tool integrations:

The common functionality of AJDE is also available in the stand-alone source code browser ajbrowser, included in the tools distribution.

Finally, as mentioned above, AspectJ also supports building with Ant by providing task interfaces to the ajc and ajdoc tools.

No. Although AspectJ can be used in a way that allows AspectJ code to be removed for the final build, aspect-oriented code is not always optional or non-functional. Consider what AOP really does: it makes the modules in a program correspond to modules in the design. In any given design, some modules are optional, and some are not.

The examples directory included in the AspectJ distribution contains some examples of the use aspects that are not optional. Without aspects,

Production aspects are delivered with the finished product, while development aspects are used during the development process. Often production aspects are also used during development.

Aspects for logging, tracing, debugging, profiling or performance monitoring, or testing.

Aspects for performance monitoring and diagnostic systems, display updating or notifications generally, security, context passing, and error handling.

"Scattering" is when similar code is distributed throughout many program modules. This differs from a component being used by many other components since it involves the risk of misuse at each point and of inconsistencies across all points. Changes to the implementation may require finding and editing all affected code.

"Tangling" is when two or more concerns are implemented in the same body of code or component, making it more difficult to understand. Changes to one implementation may cause unintended changes to other tangled concerns.

"Crosscutting" is how to characterize a concern than spans multiple units of OO modularity - classes and objects. Crosscutting concerns resist modularization using normal OO constructs, but aspect-oriented programs can modularize crosscutting concerns.

Join points are well-defined points in the execution of a program. Not every execution point is a join point: only those points that can be used in a disciplined and principled manner are. So, in AspectJ, the execution of a method call is a join point, but "the execution of the expression at line 37 in file Foo.java" is not.

The rationale for restricting join points is similar to the rationale for restricting access to memory (pointers) or restricting control flow expressions (goto) in Java: programs are easier to understand, maintain and extend without the full power of the feature.

AspectJ join points include reading or writing a field; calling or executing an exception handler, method or constructor.

A pointcut picks out join points . These join points are described by the pointcut declaration. Pointcuts can be defined in classes or in aspects, and can be named or be anonymous.

Advice is code that executes at each join point picked out by a pointcut. There are three kinds of advice: before advice, around advice and after advice. As their names suggest, before advice runs before the join point executes; around advice executes before and after the join point; and after advice executes after the join point. The power of advice comes from the advice being able to access values in the execution context of a pointcut.

AspectJ enables you to declare members and supertypes of another class in an aspect, subject to Java's type-safety and access rules. These are visible to other classes only if you declare them as accessible. You can also declare compile-time errors and warnings based on pointcuts.

Aspects are a new class-like language element that has been added to Java by AspectJ. Aspects are how developers encapsulate concerns that cut across classes, the natural unit of modularity in Java.

Aspects are similar to classes because...

Aspects are different than classes because...

AOP's fundamental assumption is that in any sufficiently complex system, there will inherently be some crosscutting concerns.

So, while there are some cases where you could re-factor a system to make a concern no longer be crosscutting, the AOP idea is that there are many cases where that is not possible, or where doing so would damage the code in other ways.

Yes.

The short summary is that it is right to define AOP in terms of crosscutting, because well-written AOP programs have clear crosscutting structure. It would be a mistake to define AOP in terms of "cleaning up tangling and scattering", because that isn't particular to AOP, and past programming language innovations also do that, as will future developments.

(Slides for a long talk on this topic were once available at http://www.cs.ubc.ca/~gregor/vinst-2-17-01.zip.)

No. Some implementations of AOP are domain-specific, but AspectJ was specifically designed to be general-purpose.

There are many mechanisms people use now to implement some crosscutting concerns. But they don't have a way to express the actual structure of the program so you (and your tools) can reason about it. Using a language enables you to express the crosscutting in first-class constructs. You can not only avoid the maintenance problems and structural requirements of some other mechanisms, but also combine forms of crosscutting so that all the mechanisms for a particular concern are one piece of code.

There are many recent proposals for programming languages that provide control over crosscutting concerns. Aspect-oriented programming is an overall framework into which many of these approaches fit. AspectJ is one particular instance of AOP, distinguished by the fact that it was designed from the ground up to be compatible with Java.

For more alternatives for aspect-oriented programming, see http://aosd.net.

Reflective and aspect-oriented languages have an important similarity: both provide programming support for dealing with crosscutting concerns. In this sense reflective systems proved that independent programming of crosscutting concerns is possible.

But the control that reflection provides tends to be low-level and extremely powerful. In contrast, AspectJ provides more carefully controlled power, drawing on the rules learned from object-oriented development to encourage a clean and understandable program structure.

Some features of AspectJ, such as introduction, are related to mixin-based inheritance. But, in order to support crosscutting, a core goal for AspectJ, AspectJ goes beyond mixin-based inheritance.

Firstly, an aspect imposes behavior on a class, rather than a class requesting behavior from an aspect. An aspect can modify a class without needing to edit that class. This property is sometimes called reverse inheritance.

Secondly, a single aspect can affect multiple classes in different ways. A single paint aspect can add different paint methods to all the classes that know how to paint, unlike mixin classes.

So mixin-based inheritance doesn't have the reverse inheritance property, and mixins affect every class that mixes them in the same. If I want to do something like SubjectObserverProtocol, I need two mixins, SubjectPartofSubjectObserverProtocol and ObserverPartof... In AspectJ, both halves of the protocol can be captured in a single aspect.

Some AOP techniques are presented as "dynamic" because the weaving occurs when classes are loaded, because aspects can be configured in a separate XML file before launch, or because some advice depends on runtime reflection. They are said to be more flexible than AspectJ.

This is a misconception. First, the AspectJ 1.1 weaver has always supported weaving at compile-time or class-load-time. Weaving at compile-time reduces application launch and running time, and it helps IDE's offer support for tracking down weaving errors and understanding the impact of aspects on a system. On the other hand, weaving at load-time simplifies build and deployment. Before AspectJ 1.2, the user had to write a class loader that used the weaver API to weave at load time; since 1.2, AspectJ comes with a command-line launcher to support weaving at class-load-time without any other changes to a build configuration. In AspectJ 5, we expect to get a similar level of support as AspectWerkz, and to exploit the class bytecode weaving hook available in Java 5 VM's.

Second, AspectJ programs, like Java programs generally, can be written to support any level of XML configuration or to depend on runtime reflection. There are some benefits to using AspectJ; e.g., the proceed() form within around advice simplifies a lot of the work that otherwise would go into writing a generalized interceptor, without introducing many of the runtime errors that can result from interceptors. For AspectJ examples of configurable or reflection-dependent programs, see the sample code linked off the AspectJ documentation page or the examples discussed on the mailing list, e.g., Incremental and runtime weaving support?.

From a question on the user list:

> Anyone know the connections between AOP and Extreme Programming?
> I am really confused. It seems AOP is a programming paradigm, which
> is the next level of abstraction of OOP. Extreme Programming, however,
> this is a lightweight software development process. One of the common
> motivations of AOP and XP is designed to adopt to the requirement
> changes, so that it can save the cost of software development.
            

This is Raymond Lee's answer:

You're not really that confused. AOP and XP are orthogonal concepts, although AOP can be used to help accomplish XP goals. One of the goals of XP is to respond to changing requirements. Another is to reduce the overall cost of development. These are not necessarily the same thing.

One of the principles of XP that contribute to meeting those goals is to maintain clean, simple designs. One of the criteria for clean, simple designs is to factor out duplication from the code. Benefits of removing duplication include the code being easier to understand, better modularity of the design, lower costs of code changes, less chance of conflicting changes when practicing collective code ownership, etc.

Different types of duplication lend themselves to being addressed by different design paradigms and language features. Duplicate snippets of code can be factored out into methods. Duplicate methods can be factored out to common classes, or pushed up to base classes. Duplicate patterns of methods and their use can be factored out to mechanisms of classes and methods (i.e. instantiations of design patterns).

AOP addresses a type of duplication that is very difficult to handle in the other common paradigms, namely cross-cutting concerns. By factoring out duplicate cross-cutting code into aspects, the target code becomes simpler and cleaner, and the cross-cutting code becomes more centralized and modular.

So, AOP as a paradigm, and the associated tools, gives an XPer, or anyone wanting to remove duplication from the code base, a powerful way to remove a form of duplication not easily addressed until now.

Not at this time. Although the resemblances between C# and Java means it would probably be a fairly straightforward matter to take the AspectJ language design and produce AspectC#, our current focus is only on supporting effective uses of AspectJ.

You may use AspectJ in your product or project with little risk. Several factors play a role in reducing the risk of adopting this new technology:

Using aspects reduces, as a side effect, the number of source lines in a program. However, the major benefit of using aspects comes from improving the modularity of a program, not because the program is smaller. Aspects gather into a module concerns that would otherwise be scattered across or duplicated in multiple classes.

The issue of performance overhead is an important one. It is also quite subtle, since knowing what to measure is at least as important as knowing how to measure it, and neither is always apparent.

We aim for the performance of our implementation of AspectJ to be on par with the same functionality hand-coded in Java. Anything significantly less should be considered a bug.

There is currently no benchmark suite for AOP languages in general or for AspectJ in particular. It is probably too early to develop such a suite because AspectJ needs more maturation of the language and the coding styles first. Coding styles really drive the development of the benchmark suites since they suggest what is important to measure.

Though we cannot show it without a benchmark suite, we believe that code generated by AspectJ has negligible performance overhead. Inter-type member and parent introductions should have very little overhead, and advice should only have some indirection which could be optimized away by modern VM's.

The ajc compiler will use static typing information to only insert the advice and dynamic pointcut tests that are absolutely necessary. Unless you use 'thisJoinPoint' or 'if', the main dynamic checks will be 'instanceof' checks which are generally quite fast. These checks will only be inserted when they can not be inferred from the static type information.

When measuring performance, write AspectJ code fragments and compare them to the performance of the corresponding code written without AspectJ. For example, don't compare a method with before/after advice that grabs a lock to just the method. That would be comparing apples and oranges. Also be sure to watch out for JIT effects that come from empty method bodies and the like. Our experience is that they can be quite misleading in understanding what you've measured.

Well I haven't yet seen a language in which you can't write bad code!

But seriously, most AspectJ users find that just like when they learned OO, it takes a while to really get the hang of it. They tend to start in the usual way, by copying canonical examples and experimenting with variations on them.

But users also find that rather than being dangerous, AspectJ helps them write code that is more clear and has better encapsulation -- once they understand the kind of modularity AspectJ supports. There are several good papers that talk about this (see below), but here's a basic point to keep in mind: when properly used, AspectJ makes it possible program in a modular way, something that would otherwise be spread throughout the code. Consider the following code, adapted from the AspectJ tutorial:

aspect PublicErrorLogging {
    Log log = new Log();

    pointcut publicInterface(Object o):
        call(public * com.xerox.*.*(..)) && target(o);

    after(Object o) throwing (Error e): publicInterface(o) {
        log.write(o, e);
    }
}
          

The effect of this code is to ensure that whenever any public method of an interface or class in the com.xerox package throws an error, that error is logged before being thrown to its caller.

Of course in the alternative implementation a large number of methods have a try/catch around their body.

The AspectJ implementation of this crosscutting concern is clearly modular, whereas the other implementation is not. As a result, if you want to change it, its easier in the AspectJ implementation. For example, if you also want to pass the name of the method, or its arguments to log.write, you only have to edit one place in the AspectJ code.

This is just a short example, but I hope it shows how what happens with AOP and AspectJ is that the usual benefits of modularity are achieved for crosscutting concerns, and that leads to better code, not more dangerous code.

One paper someone else just reminded me of that talks some more about this is: http://www.cs.ubc.ca/~kdvolder/Workshops/OOPSLA2001/submissions/12-nordberg.pdf

In the spirit of Smalltalk, we have decided to give more power to the language in order to let the user community experiment and discover what is right. To date this has proven to be a successful strategy because it has permitted the construction of many useful aspects that crosscut the internal state of an object, and as such need access the its private members. However, we are not discounting that some sort of restrictions are useful, rather, we are seeking input from the community in order to decide on what these restrictions should be.

In that light, our position on encapsulation is :

Introducing parents or members to classes is a well-studied OO technique known as open classes.

Open classes have been used in many languages prior to AspectJ, including CLOS, Python, Smalltalk, Objective-C, and others. Building from Java, introduction in AspectJ provides better name hygiene and access control than prior languages. Introduced code obeys all of Java's normal accessibility rules for its lexical location in the aspect that it is introduced from. Such code can not even see, much less access, private members of the class it is introduced into. Further, introductions can be declared private to the aspect, so they are not visible to other clients of the class.

Privileged aspects do permit access to private members of another class. They are a response to the very few cases where developers genuinely need such access (typically for testing purposes where it access is necessary), but it would be more risky to open access by putting the aspect in the same package, adding test code, or changing access in the target class. We recommend using privileged aspects only as necessary, and believe that marking them "privileged" makes any potential misuse apparent.

Consider the component types in J2EE:

The basic limitations are that there is no built-in support for writing J2EE analogs for AspectJ extensions to Java, like distributed aspects, distributed cflow, or managing state between invocations. These don't prevent one from using AspectJ to do useful intra-container implementation, nor need they prevent one from building distributed support, state management, and inter-component implementations that leverage AspectJ. It just takes some work. In more detail:

All AspectJ implementations may define "code the implementation controls". The AspectJ 1.0 implementation defines this as the files passed to the compiler (AspectJ 1.1 will also support bytecode weaving).

Some advice on EJB operations will generate methods that confuse ejb compilers. To avoid this problem, you can use the -XaddSafePrefix flag when compiling with ajc.

EJB components may be invoked remotely, and containers may passivate and pool EJB's. Servlets have similar limitations, and in both cases the lifespan of the defining class loader is implementation-dependent (though it must span the operation of a particular request).

Being limited by lifecycle and namespace, the AspectJ 1.0 implementation supports aspects that operate through non-remote invocations during the lifetime of the namespace for a particular deployment unit compiled in its entirety by the ajc compiler. This means AspectJ supports common aspects only within a single local runtime namespace (usually implemented as a class loader hierarchy).

Further, AspectJ recognizes language-level join points (object initialization, method calls, etc.), not their EJB analogs (ejb find or create methods...). These lead to the following consequences:

In addition, any AspectJ code should respect EJB operations:

We plan to support Generics when Java 1.5 is available.

But at this time, unfortunately not. The two compilers are just not at all compatible. In an ideal world, there would be a wonderful Open Source extensible compiler framework for Java that both GJ and AspectJ would be built on top of, and they would seamlessly interoperate along with all other extensions to Java that you might be interested in, but that's not the case (yet?).

However, on 09 October 2000, the Java Community Process approved a proposal to add generic types to Java that is largely based on GJ (JSR 14). A draft specification was submitted for public review, which closed on 01 August 2001, and a prototype implementation has been released by Sun.

We are committed to moving very rapidly to add support for generic types in AspectJ when generic types become part of the Java language specification. Everyone on the AspectJ team is looking forward to this, because we too would really like to be able to write code that includes both aspects and generic types.

We have not tested with J2ME, but we understand that users are deploying AspectJ-compiled programs successfully in J2ME. It should work if your program is otherwise J2ME-compatible and if you avoid using cflow-based pointcuts or thisJoinPoint. To ensure that the program is limited to J2ME API's, you should supply the runtime on the bootclasspath. (Fair warning: there was an email about this not working, but there has been no bug report.)

We are working on standardization, but it's a question of timing/ripeness (imagine going from thousands of users to millions). (See Q:What are your plans to make AspectJ a general feature of Java supported by Sun and the other key-players in the Java Industry?.) We believe AspectJ addresses this question in the best way possible now:

The mailing lists provide the primary support for everyone in the community (See Q: What mailing lists are there?). To request commercial support, tutorials, or presentations, use the developer mailing list, aspectj-dev@eclipse.org.

To find out about known issues, see the AspectJ Programming Guide Appendix, "Implementation Notes" and the AspectJ bugs in the database at http://bugs.eclipse.org/bugs (using the product AspectJ). Here are direct links to view open compiler bugs, view all Aspectj bugs (open or closed), or add new bugs.

The AspectJ users mailing list (aspectj-users@eclipse.org) provides an informal network of AspectJ language users who can answer usage questions about AspectJ programs and the AspectJ tools. This is the place to ask how to code something in AspectJ or how to write Ant or shell scripts to invoke the tools.

The AspectJ developers mailing list (aspectj-dev@eclipse.org) provides an informal network of AspectJ technology experts who aim to understand the technology behind AspectJ. The committers to the AspectJ project use this list for open technical and planning discussions. Developers can answer questions about what's possible and about integrating AspectJ technology with other technologies.

For both mailing lists, only subscribed members may post messages. To subscribe, visit the AspectJ web site.

There you can also subscribe to aspectj-announce@eclipse.org, a low-traffic list containing only announcements about significant AspectJ events and product releases. To get on a similar list for aspect-oriented software development generally, see http://aosd.net.

The AspectJ compiler or weaver is required at some point, but many people can use AspectJ without changing their build or deployment process significantly. For aspects that are not required to compile, you can use the AspectJ binary weaver, run at build-time or class-load-time. You can write aspects using the original code style (which must be compiled with the AspectJ compiler) or using the annotation style new in AspectJ 5 (which may be compiled with Javac or the AspectJ compiler).

For more information, see Q:Should I use code- or annotation-style aspects?.

You need to specify to the compiler the files that contain your aspects and the files that contain the types affected by your aspects. See Q: How do I know which aspects affect a class when looking at that class's source code?. The AspectJ compiler will not search the source path for types that may be affected (unlike Javac and Jikes). In AspectJ 1.0, ajc requires all code to be in source form; in AspectJ 1.1, Java and AspectJ code may be in either source or binary form.

In some cases you should compile your entire system all at once. If this is too slow, then you can try to make reasonable divisions between sets of source files whose aspects do not interact to achieve a shorter compile cycle (particularly for development aspects). If you have aspects that apply to different modules, you can try compiling them into a binary form and using them to weave each module. However, if you get any problems or if you wish to run tests or do a release, you should recompile the entire system.

For more information, see the Development Environment Guide Reference for ajc.

Yes, use the argfile option to ajc. List source files in a line-delimited text file and direct ajc to that file using -argfile or @:

ajc @sources.lst
ajc -argfile sources.lst
          

Another way in AspectJ 1.1 is to use the -sourceroots options, which reads all source files in a given set of directories:

ajc -sourceroots "src;testsrc"
          

For more information, see the Development Environment Guide Reference for ajc.

Use the latest, greatest, fastest JVM you can get your hands on for your platform. The compiler's performance is dependent on the performance of the JVM it is running on, so the faster a JVM you can find to run it on, the shorter your compile times will be. At a minimum you need to use a Java 2 or later JVM to run the compiler (J2SE 1.3 for AspectJ 1.1). We realize that this constraint can be a problem for users who don't currently have a Java 2 JVM available. We're sorry for the inconvenience, but we had to make the hard decision that the advantages of being able to rely on Java 2 were worth the cost of losing a number of developers who are working on platforms without Java 2 support. Here is a list of starting places where you might find support for your system.

The requirement of Java 2 support is only for running the AspectJ compiler. The AspectJ compiler can be used to build programs that will run on Java 1.1 (or probably even on Java 1.0) systems. This means that it can build programs that will run on Macintosh, FreeBSD, and applets that will run in Internet Explorer and Netscape Navigator that are still not yet Java 2 compliant.

ajc can be used to develop programs that are targeted at the Java 1.1 platform, even though the ajc compiler won't run on that platform. Here's an example of using ajc in this sort of cross-compilation mode (assuming a Windows platform with all the default installation directories):

ajc -target 1.1 -bootclasspath c:\jdk1.1.7\lib\classes.zip \
   -classpath c:\aspectj1.0\lib\aspectjrt.jar -extdirs "" \
   -argfile jdk11system.lst
          

This same technique can be used if you want to run ajc on a JDK 1.3 JVM (highly recommended) but need to generate code for JDK 1.2. That would look something like:

ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \
   -classpath c:\aspectj1.0\lib\aspectjrt.jar \
    -extdirs c:\jdk1.2\jre\lib\ext
            -argfile jdk12system.lst
          

Yes. As with Javac, use the -source 1.4 option as described in the Development Environment Guide Reference for ajc.

Yes. As with Javac, use the -1.5 option as described in the Development Environment Guide Reference for ajc.

Yes. Both ajc and aspectjrt.jar should work with versions of aspect code and libraries back to AspectJ 1.2.1. Any aspects should be deployed with the same version of aspectjrt.jar they were compiled with. For more information, see the Development Environment Guide Reference for ajc and Deployment notes section on Version compatibility.

Since AspectJ requires Java 2 or later, it will not run on the Microsoft JVM, which does not support Java 2.

No. Some previous versions of AspectJ had this requirement. In AspectJ 1.0, javac can still be used as ajc back end by using the -usejavac flag. You can also run ajc in preprocessor mode to generate Java source (.java) files to be compiled using javac or another java compiler. Neither option is supported in AspectJ 1.1.

In AspectJ 1.0, the PARSER for ajc is written by hand. This choice was made with full awareness of the generator tools out there. (Jim had for example used the excellent javacc tool for building the parser for JPython (now Jython)). One of the reasons that AspectJ uses a hand-written parser is that using javacc taught Jim about the LL-k design for parsers (pioneered by antlr). As opposed to the state-machine parsers produced by yacc, these parsers are very readable and writable by humans.

Antlr and javacc did not really suit the project:

There were also several things that were easier to implement with a hand-written parser than with any of the exiting tools.

When you are working with the IDE support, you can get an understanding of which aspects affect any class. This enables AspectJ programmers to get the benefits of modularizing crosscutting concerns while still having immediate access to what aspects affect a class.

For example, the Development Environment Guide ajbrowser section. shows that you can list or navigate between method and advice affecting that method and between a type and declarations in an aspect on that type. (The IDE support may have more features than ajbrowser, depending on the IDE. See Q: How well does AspectJ integrate with existing Java development tools? for more information on which Java development environments are supported.)

When you are looking at documentation for AspectJ 1.0 programs, ajdoc will provide links from aspects and advice to the affected code, but it provides less information than the IDE support because it only parses declarations.

When you are compiling your program, pointcuts that are statically-determinable can be used in declare statements to identify the code picked out by the pointcut. (A pointcut is statically determinable if it only uses the pointcut designators within, withincode, execution, call, get, set, initialiation, and staticinitialiation.) The compiler will list the static code points which will be affected by any advice specifying the same pointcut. For example, the following will print a warning whereever some code in class Bar gets a field value from Foo:

  declare warning: get(* Foo.*) && within(Bar) 
     : "reading Foo state from Bar";
             

When you are running your program, you can trace advice as it executes. This enables you to identify advice on join points picked out dynamically, which cannot be reflected precisely by IDE support. For a related tracing question, see Q:I don't understand what join points exist. How can I see them?

See Q: How well does AspectJ integrate with existing Java development tools?

The AspectJ team directly provided components for JBuilder, Forte, and Emacs and supported the open-source AspectJ plugin project at http://eclipse.org/ajdt which uses the AJDE API support for IDE's. Supporting new IDE's is a matter of building on the AJDE API's, mostly likely adopting one of the existing open-source IDE extensions as a design template. Here are the IDE's where we know people have expressed interest, so interested developer may want to join with others in their developer communities to build the integration.

For questions on AJDE, join the developer's list aspectj-dev@eclipse.org. For questions on the current IDE integrations, contact those projects.

Yes. The core AJDE API is extensible and the source code is available for download. Start by studying the sources for the existing IDE support linked off the AspectJ site http://eclipse.org/aspectj.

If you are using development-time-only aspects - aspects that only exist when you are developing the code, not when you ship it - you can use implement a hybrid build process by listing the production source files into a javac-compliant argfile, and the development source files in another ajc argfiles:

     -- file "production.lst":
     One.java
     two/Three.java
     ...

     -- file "tracing.lst":
     trace/Library.java
     Trace.java

     -- file "development.lst":
     @production.lst
     @tracing.lst
          

Then your development build can use ajc:

            ajc @development.lst
          

And your development build can use ajc or javac or jikes:

            jikes @production.lst
          

Aspects apply to everything in a namespace, as if everything is compiled together. Sometimes you can break the build down into separate steps without breaking this model, but we haven't stated exactly where it could break because it depends on the interactions between all types. You can try the approaches below, but remember to rebuild everything in one go if there are problems.

The simplest scenario is when the aspects apply to all modules and the modules compile without the aspects. In that case, weaving in the aspects is just the final assembly step for the build.

Next is the case where the aspects make changes to a common library that are visible to other clients, which themselves are otherwise unaffected by the aspects. In this case, the common library can be built using ajc, and used on the classpath for the module builds:

   ajc -outjar common.jar -sourceroots "aspectj-src:src" ...
   cd ../otherProject
   javac -classpath "../common/common.jar:${aspectjrt.jar}" {src}

		

Combining these last two, there's the case where a common set of aspects should affect two or more modules that are in a dependency relationship to one another. It should work to reuse the aspects in binary form for each compile, in dependency order:

   ajc -outjar common-aspects.jar
       -sourceroots "aspectj-src" ...

   ajc -outjar common.jar
       -sourceroots "src"
       -aspectpath common-aspects.jar ...

   cd ../module1
   ajc -outjar module1.jar
       -sourceroots "src"
       -classpath common.jar
       -aspectpath ../common-aspects.jar ...

   cd ../module2
   ajc -outjar module2.jar
       -sourceroots "src"
       -classpath "common.jar;../module1.jar"
       -aspectpath ../common-aspects.jar ...

		

If two modules are visibly affected by aspects and mutually-dependent, the only thing to do is compile them together.

It's safest to assume that all aspects can affect all types in a namespace; using build boundaries to effect crosscutting limits causes a dangerous dependency on the build process and might cause problems.

Just incrementally-compile the whole system. Specify to ajc the modules as multiple source roots (or input jars if you are weaving libraries).

In Eclipse's AJDT, you can create a top-level project with symbolic links out to the sources:

   app-assembly/
	 {link common/aspects}
	 {link common/src}
	 {link module1/src}
	 ...

			

The links make incremental development possible without affecting the modularized Ant builds. (Our practice runs along those lines.)

AspectJ does not enable you to change the signature of a method, but you can (by express declaration) work around some limits imposed by the signature. You can convert a checked exception to unchecked using declare soft, privileged aspects have access to private methods, and you can use a percflow aspect to ferry additional state to a callee without changing intervening signatures. For more details, see The AspectJ Programming Guide. In the case of synchronized, we have what we consider a better solution that uses around advice instead of introduction. This solution is described in this thread (no longer available) on the AspectJ users list, with some additional comments (no longer available) .

You can trace them using using an aspect. For example, you can start logging at a particular method call and see what join points occur after the call and before it returns.

Here's some code Jim Hugunin wrote to trace join points and posted to the users list. To reuse the aspect, define a subaspect and implement the pointcuts, for example:

aspect JoinPointSampleAspect extends aj.TraceJoinPoints {
    protected pointcut entry() : 
        execution(static void JoinPointSample.main(String[]));
    protected pointcut exit() : 
        call(static void JoinPointSampleAspect.exit());

    public static void main (String[] args) {
        JoinPointSample.main(args);   
        JoinPointSampleAspect.exit();   
    } 
    public static void exit() {}
}

class JoinPointSample {
    public static void main(String[] args) {}
}
          

Here's the aspect:

/* TraceJoinPoints.java */

package aj;

import org.aspectj.lang.*;
import org.aspectj.lang.reflect.*;
import java.io.*;

public abstract aspect TraceJoinPoints {
    protected abstract pointcut entry();
    protected pointcut exit(): call(* java..*.*(..));
    // this line is for AspectJ 1.1; for 1.0, use "dominates"
    declare precedence : TraceJoinPoints, *;
    final pointcut start(): entry() && !cflowbelow(entry());

    final pointcut trace():
        cflow(entry()) && !cflowbelow(exit()) && !within(TraceJoinPoints+);

    before(): start() { makeLogStream(); }

    before(): trace() { logEnter(thisJoinPointStaticPart); }
    after(): trace() { logExit(thisJoinPointStaticPart); }

    after(): start() { closeLogStream(); }

    //------------ added
    /**
     * Emit a message in the log, e.g.,
     * <pre>TraceJoinPoints tjp = TraceJoinPoints.aspectOf();
     * if (null != tjp) tjp.message("Hello, World!");</pre>
     */
    public void message(String s) {
        out.println("<message>" + prepareMessage(s) + "</message>");
    }
    public void message(String sink, String s) {
        if (null == sink) {
            message(s);
        } else {
            out.println("<message sink=" + quoteXml(sink)
                        + " >" + prepareMessage(s) + "</message>");
        }
    }
    protected String prepareMessage(String s) { return s; } // XXX implement

    //--------- end of added

    PrintStream out;
    int logs = 0;
    protected void makeLogStream() {
        try {
            out = new PrintStream(new FileOutputStream("log" + logs++ + ".xml"));
        } catch (IOException ioe) {
            out = System.err;
        }
    }

    protected void closeLogStream() {
        out.close();
    }


    int depth = 0;
    boolean terminal = false;
    protected void logEnter(JoinPoint.StaticPart jp) {
        if (terminal) out.println(">");
        indent(depth);
        out.print("<" + jp.getKind());
        writeSig(jp);
        writePos(jp);

        depth += 1;
        terminal = true;
    }

    void writeSig(JoinPoint.StaticPart jp) {
        out.print(" sig=");
        out.print(quoteXml(jp.getSignature().toShortString()));
    }

    void writePos(JoinPoint.StaticPart jp) {
        SourceLocation loc = jp.getSourceLocation();
        if (loc == null) return;

        out.print(" pos=");
        out.print(quoteXml(loc.getFileName() +
                           ":" + loc.getLine() +
                           ":" + loc.getColumn()));
    }

    String quoteXml(String s) {
        return "\"" + s.replace('<', '_').replace('>', '_') + "\"";
    }

    protected void logExit(JoinPoint.StaticPart jp) {
        depth -= 1;
        if (terminal) {
            out.println("/>");
        } else {
            indent(depth);
            out.println("</" + jp.getKind() + ">");
        }
        terminal = false;
    }

    void indent(int i) {
        while (i-- > 0) out.print("  ");
    }
}

          

Note that if you are using AspectJ 1.0, the line starting with declare precedence would be removed, and the aspect declaration would look like aspect TraceMyJoinPoints dominates *.

Briefly, there are two interesting times when a constructor or method is run. Those times are when it is called, and when it actually executes.

The main difference is that a call join point happens outside of the target object (for non-static methods) or class (for static methods and constructors), and that an execution join point happens inside the object or class. This means that the within and withincode pointcuts pick them out differently: A call join point is picked out within the caller, while an execution join point is picked out where it is actually defined.

A call join point is the ``outermost'' join point for a particular call. Once a call join point proceeds, then a number of different things happen. For non-static methods, for example, method dispatch happens, which will cause one method execution join point -- perhaps more, if there are super calls. For constructors, the super constructor is called, and fields are initialized, and then various constructor execution join points will occur.

A call join point matches only the ``external'' calls of a method or constructor, based on a signature, and it does not pick out calls made with super, or this constructor calls.

Here's more detail:

Consider method execution in Java as (1) the initial call from this object to some method on the target object with a particular signature; and (2) the execution of the actual code in the particular method dispatched in the target object. The call join point starts with the initial call and ends when control returns to the call (by return or perhaps thrown exception). The execution join point starts with the method body and ends when the body completes (again by return or throwing an exception), so the execution join point always happens within the bounds of the corresponding call join point. You can see this if you use the join-point tracing aspect in see Q:I don't understand what join points exist. How can I see them?.

As you would expect, the context differs in advice on pointcuts picking out execution and call join points; for call, this refers to the caller, whereas for execution this refers to the called (executing) object.

There are some subtle interactions with other AspectJ semantics. First, the meaning of the signature in the execution() and call() pointcut designators (PCD's) differ: the call type depends upon the type of the reference making the call, while the execution type depends on the enclosing class. Second, you may choose one over another if you cannot bring all your sources within the code the compiler controls (described in the appendix to the Programming Guide). For example, to trace calls into a method from classes which are outside the code the compiler controls at compile time, then using execution() will work while using call()may not. Finally, since super invocations are not considered method calls, to trace super.foo() would require using execution.

Because of differences in the way AspectJ 1.0 and 1.1 are implemented, in 1.0 you should use the call() pointcut designator unless you have a good reason to use execution(); in AspectJ 1.1, the reverse is true.

Both pick out all the join points in the control flow of the specified join points. They differ only in that the cflowbelow() pointcut designator does not pick out the join points specified, while cflow() does.

This is best seen by way of example. Given a recursive call to int factorial(int) you can print the arguments for (a) the current and most-recent recursive call or (b) the current and original recursive call:

aspect LogFactorial {
    pointcut f(int i) : call(int factorial(int)) && args(i);

    // most-recent
    before(int i, final int j) : f(i) && cflowbelow(f(j)) { 
        System.err.println(i + "-" + j);
    }

    // original
    before(int i, final int j) : f(i) 
        && cflowbelow(cflow(f(j)) && !cflowbelow(f(int))) { 
        System.err.println(i + "@" + j);
    }
}
          

Static initialization pertains to initialization of a class or interface type. Constructor call and execution are akin to method call, and initialization generalizes this and picks out the first constructor called.

Their relations are best demonstrated by tracing the join points. Below is the class Test which implements an interface and extends a class along with a trace of the join points below and including the constructor call obtained using TraceJointPoints.java from Q:I don't understand what join points exist. How can I see them?.

            
public class Init {
    public static void main (String[] args) {
        new Test(); 
        end();
    } 
    static void end() {}
}
class Super {}
interface I {}
class Test extends Super implements I {
    Test() {}
}


          

For a program compiled with AspectJ 1.0, the result is this:

            
  <constructor-call sig="Test()" >
    <staticinitialization sig="Super._init_" />
    <staticinitialization sig="Test._init_" />
    <initialization sig="Super()" >
      <instanceinitializer-execution sig="Super._init_" />
      <constructor-execution sig="Super()" />
    </initialization>
    <initialization sig="I()" >
      <instanceinitializer-execution sig="I._init_" />
      <constructor-execution sig="I()" />
    </initialization>
    <initialization sig="Test()" >
      <instanceinitializer-execution sig="Test._init_" />
      <constructor-execution sig="Test()" />
    </initialization>
  </constructor-call>

          

Ordinarily, using a call pointcut designator is best because the call join point surrounds the others, but in the case of constructors there is no target object for the call (because it has not been constructed yet), so you might prefer to use the initialization pointcut designator.

You can advise some form of constructor join point. Constructors are tricky in Java, and that's exposed in AspectJ. Here are some rules of thumb:

This usually reflects both a conceptual error and a programming mistake. Most likely you want to do something like "run the advice for all public and private calls," and the code looks something like this:

            within(com.xerox.printing..*) && call(public * *(..)) && call(private * *(..))
          

But a pointcut is evaluated at *each* join point. The expression above would never pick out any call join point, because no method signature has both public and private access. In a pointcut, pc1() && pc2() means both must be true at a given join point for advice to run at that join point. The correct pointcut would use || as follows:

            within(com.xerox.printing..*) && (call(public * *(..)) || call(private * *(..)))
          

Then the advice will run at the join point.

There is no way in advice to refer to the type of the code executing in a static context except by specification. This makes it impossible to refer to static members using runtime information.

However, AspectJ can determine the class for something in the join point context, which you can use as a per-class key. Then you can actually declare an instance field to contain the per-class value (see the next question). This comes at the cost of an extra reference, but the field can be final.

No. You can declare that all the types implement an interface you define, and then use the interface type in your program. For example:

/** 
 * Example of using an interface to represent a type pattern.
 * sub-aspects use declare parents to add to traced types, e.g.,
 *    declare parents: com.mycompany.whatever..* implements Marked;
 */
abstract aspect MarkerExample {
  /** marker interface for types that we want to trace */
  interface Marked {}

  /** calls to an instance of Marked not from an instance of Marked */
  pointcut dynamicCallsIn(): call(* *(..)) && target(Marked) && !this(Marked);

  /** calls to methods defined by a subtype of Marked
   *  that don't come from the body of a subtype of Marked
   */
  pointcut staticCallsIn(): call(* Marked+.*(..)) && !within(Marked+);

  /** print dynamic calls */
  before(): dynamicCallsIn() { System.out.println("before " + thisJoinPoint); }
}

aspect MyMarker extends MarkerExample {
  declare parents: com.mycompany.whatever..* implements Marked;
}
          

There are a number of places to find sample code and instructions for using AspectJ with other programming tools.

Some libraries are distributed in the release under the examples folder in the distribution. These are "libraries" in the sense that they are reusable, but they are delivered in source form. Similarly, some of the sample code is reusable; for that, see Q:Where do I find example programs and how-to's?. If you develop such a library and want to make it available to other users, feel to send it to the users mailing list aspectj-users@eclipse.org.

In AspectJ 1.1, ajc supports binary aspects, so you can distribute aspect libraries without distributing the source. For more information, see the -aspectpath option in the Reference for ajc.

The current version of ajc can change the serialVersionUID of generated .class files as a result of weaving in advice. This is an important fact that developers using both aspects and serialization should be aware of. It is likely that a future version of the compiler will be better behaved regarding the serialVersionUID.

However, changes to the serialVersionUID attribute are typically only important when using serialization for the long-term persistence of objects. Using standard Java serialization for long-term persistence has a number of drawbacks and many developers already use alternative solutions. For one possibly standard solution, see Long-Term Persistence for JavaBeans Specification .

Just include the aspectjrt.jar as a required archive. For example, here is the HTML code for an HTML editor applet that contains some debugging aspects:

            
<APPLET
   CODE='com.company.swing.applets.EditorApplet'
  WIDTH='700'
 HEIGHT='525'>
    <PARAM NAME="CODE" VALUE="com.company.swing.applets.EditorApplet" >
    <PARAM NAME="ARCHIVE" 
         VALUE ="../company-applets.jar,../aspectjrt.jar,../xmlrpc-applet.jar" >
    <PARAM NAME="type" VALUE="application/x-java-applet;version=1.4">
    <PARAM NAME="scriptable" VALUE="false">
</APPLET>

          

The above markup has worked reliably with the Java Plugin (included in the JRE 1.4.x) in IE 6, Mozilla 1.1 (Win32), and Mozilla 1.0.1 (Red Hat Linux 8.0). The following link describes how to configure Mozilla/Netscape 6.x/7.x to use the Java Plugin from a JRE/SDK installation: http://java.sun.com/j2se/1.4.1/manual_install_linux.html. (Thanks to Chris Bartling for this answer.)

In some cases, AspectJ allows conversion from values of primitive types to Object, so that highly polymorphic advice may be written. This works if an advice parameter or the return type for around is typed to Object. So:

class Test {
    static int i;
    public static void main(String[] args) {
        i = 37;
    }
}

aspect TraceSet {
    before(Object val): set(* Test.*) && args(val) {
        System.err.println(val);
        System.err.println(val.class);
    }
}
          

will print out

37
java.lang.Integer
          

For more information, see the Programming Guide semantics section "Context Exposure" .

The ajc compiler emits the version when passed the -version flag as an argument.

To programmatically detect the version of the AspectJ runtime while running under Java 1.4 or later, get the version from the package:

    Package lang = org.aspectj.lang.JoinPoint.class.getPackage();
    String version = lang.getImplementationVersion();
          

When running under Java 1.3 or earlier, read the manifest directly. For example code, see the source for AjBuildManager.checkRtJar(AjBuildConfig) in the org.aspectj.ajdt.internal.core.builder package of the org.aspectj.ajdt.core module, available as described in Q:How do I get and compile the source code for AspectJ?.

Note that the version of AspectJ for the tools in aspectjtools.jar is in org.aspectj.bridge.Version.

Most likely this is a case of infinite recursion, where advice is advising itself. It presents as a StackOverflowError or silence as the VM exhausts itself in the recursion.

Of course, infinite recursion is possible in Java:

public class Main {
    public static void main(String[] args) {
        try {
           main(args);
        } finally {
           main(args);
        }
    }
}
          

If you compile and run this program, and it will fail silently, trying to process the finally clause even after throwing the StackOverflowError.

Here's a similar AspectJ program where the recursion is not so obvious:

aspect A {
    after():  call(* *(..)) { System.out.println("after " + thisJoinPoint); }
}
          

This re-invokes itself because it advises any call. It invokes itself even after an exception is thrown, since after advice, like a finally clause, runs even after exceptions are thrown. You can fix this by following two practices:

In AspectJ 1.1, the String concatenation operator (+) is advised in its StringBuffer form, so if your advise uses String + in a way that is picked out by your pointcut, you will get infinite recursion.

(1) Use after returning to advise normal completions or after throwing to advise abrupt completions. If you use after or after throwing, write the advice with the same care you would a finally clause, understanding that it may run after some failure.

(2) Avoid writing advice that advises itself. One simple way to do so is to exclude the code within the current aspect:

aspect A {
    after() returning:  !within(A) && call(* *(..)) { 
        System.out.println("after " + thisJoinPoint); 
    }
}
          

A better way is often to re-write the pointcut. If the advice is advising itself accidentally, that's a sign that the pointcut is not saying what you mean.

aspect A {
    pointcut withinTargetClasses() : within(A+) || within(B+);
    after() returning:  withinTargetClasses() && call(* *(..)) { 
        System.out.println("after " + thisJoinPoint); 
    }
}
          

You need a type to refer to any member, field or method. It's generally better to introduce onto an interface and declare classes to implement the interface, which permits you to use the interface type in advice formals.

aspect A {
    interface TrackingSets {}
    boolean TrackingSets.dirtyFlag;
    declare parents : com.xerox..* implements TrackingSets;

    after (TrackingSets target) returning 
        : target(target) && call(* com.xerox..*.set*(..)) {
        target.dirtyFlag = true; 
    }
}
          

ajc can use more memory than a javac compile of the corresponding pure-java sources when aspects are added to the mix. You'll need to increase the memory available.

The command ajc is actually a script that launches a Java virtual machine with the correct classpath. You should make a copy of this script, rename it, and then edit it. Change the -Xmx option, size of memory allocation pool (heap). You might try -Xmx128M or even -Xmx256M.

When running under Ant, give Ant more memory or use the fork option together with the Xmaxmem option.

When running under an IDE, look to the documentation for the IDE to determine how to increase available memory.

Most commonly, a source file was specified twice on the command line (e.g., directly and by a *.java entry in a .lst file). However, sometimes you have defined a class in two files in the same package, and you need to rename the class or change its scope. You should get this message from any Java compiler.

ajc 1.0 does not support incremental compilation, but the 1.1 release does when passed the -incremental option. It may still recompile files that have not changed, if they could be affected by aspects in particular ways, but the files compiled should be fewer and result in faster compiles. Further, the 1.1 release supports binary weaving, so you need not recompile if you already have .class files.

The easiest way to fix this is to re-install ajc (using the same .class or .exe file that you originally downloaded) and this time make sure to tell it to use the desired JDK (typically the JDK versions 1.2 or 1.3 from Sun).

If you are familiar with DOS batch files or shell programming, you could also fix this by simply editing the bin\ajc.bat or bin/ajc script.

When working with an unsupported IDE that objects to the syntax of AspectJ source files (and, e.g., automatically gathers them in a source tree as Java files based on the .java extension), you can use the .aj extension for your AspectJ files. The ajc compiler accepts both .java and .aj files, and you can set up your build scripts to include the correct list of source files. (You will have to find another editor for editing AspectJ files; you can use the ajbrowser to view edit your AspectJ files and navigate the crosscutting structure.)

The ajc compiler does more analysis than (e.g.,) javac, and AJDE may in some IDE's hold a copy of the structure tree until the next tree is available from the compile process. Both mean that you may need extra memory to compile the same program. However, increasing available memory to the point that you are swapping to disk can slow the process considerably.

If you are having problems and would like to find the optimal memory allocation, iteratively decrease the amount of memory available until AJDE or ajc signals out-of-memory errors, and then increase that amount by 5-10%.

To increase memory for the ajc compiler, see Q:The AspectJ compiler aborts with an OutOfMemoryError when compiling many classes. How can I fix this?. For your IDE, do something similar or follow the provider's instructions. For example, to increase memory in JBuilder, edit the jbuilderX/bin/jbuilder.config file to have an entry like:

        
vmparam -Xmx384m

If it turns out that your project is too big to use with AJDE, your IDE may nonetheless support external commands or Ant build processes, which run outside the IDE memory space. For a JBuilder Ant plugin, some people have directed us to http://antrunner.sourceforge.net.

This happens when an aspect is not associated with an object that is being advised. We have seen this happen two ways:

In 1.0, unless you are using the ajdb debugger, stack traces may have synthetic methods in the stack, and the line numbers may not track your source code. The Development Environment Guide discusses how to interpret stack at the end of the Reference for ajc.

In 1.1, line numbers should work correctly. The only difference from a normal stack might be the addition of extra stack frames for call-backs.

When advice is not running, there is probably a problem in the pointcut. Sometimes users specify pointcuts that do not mean what they intend - most often when they misspell a type name. Run the compiler in -Xlint mode, which will flag some likely mistakes, like the type name. If that does not work, and your pointcut is staticly-determinable, use a declare statement to identify affected code. (For more information, see Q: How do I know which aspects affect a class when looking at that class's source code?.) If that does not work and your pointcut is dynamically determined, see if your join points are executing at all by using TraceJoinPoints.java from Q:I don't understand what join points exist. How can I see them?.

When advice is running more than it should, either (1) your advice is in an abstract aspect and the pointcut picks out the same join point for more than one concrete instantiation of the aspect, or (2) your pointcut picks out more join points than you intend.

In the case of advice in abstract aspects, the advice will run once for each concrete instance of the aspect. If the pointcut for that advice picks out the same join point for two concrete aspects, then the correct behavior is for the advice to run the advice twice at that join point.

To see if your pointcut picks out the join points you intend, you can use IDE support, logging, or declare-warnings. If you are using IDE support, you should be able to trace back from the pointcut or advice to the join points which can be statically determined to be affected. Without IDE support, you can write declare-warning statements to identify code affected by staticly- determinable pointcuts. To identify advised dynamic join points, you can try using TraceJoinPoints.java as above, or update the advice to print the source location of the join point. Doing any of these should show if the advice applies to code that you did not expect.

If you've done this and convinced yourself it's not working, it may be a bug. See Q:How do I submit a bug report?.

Most likely you are advising the method execution join point and specifying the defining signature. Since all overriding methods share this signature, the advice runs for each method executed. (This happens, e.g., when one method invokes the same method in the superclass using super.{method}(..)). This is the correct behavior.

To avoid this, use the call(..) pointcut designator, or use !cflow(..) to pick out only the initial method-execution.

thisEnclosingJoinPointStaticPart is a special variable available in the context of advice to refer to the join point, if any, lexically enclosing the current join point:

When declaring parents on other types from an aspect, package access only applies to code the implementation controls. For AspectJ 1.0, that is the set of files passed to the compiler. That means other classes not compiled with the aspect will not be able to access the aspect-declared members even if they are in the same package. The only way for classes outside the control of the implementation to access aspect-declared members is to declare them public.

You have to compile all the top-level implementating classes of the interface using ajc. From an email by Jim Hugunin on the requirements for AspectJ 1.1 to implement members declared by an aspect on an interface:

If you introduce non-static fields or non-abstract methods on an interface from an aspect, then all of the top-most implementors of that interface must be woven by that same aspect. (A class C is a top-most implementor of an interface I if C implements I and the superclass of C does not implement I.)

ajc 1.0 does not try to locate javac in your path: it uses the javac classes directly. In JDK 1.2 and 1.3 these classes are found in tools.jar (in the lib directory of the JDK distribution), which must be on your classpath to make ajc work with javac. Inspect the java command that launches ajc to make sure that tools.jar is on the classpath for ajc; the -classpath option only applies to the sources compiled.

The 1.0 implementation of ajdoc uses specific javadoc classes in the J2SE 1.3 tools.jar. We are working on addressing this limitation, but in the interim it is best to run ajdoc under 1.3.

When running from the command-line scripts, edit the scripts directly to put the 1.3 tools.jar first on the classpath. (The installer does not know about this limitation of ajdoc.)

When running from Ant, users often have tools.jar in ${ant.classpath} (to make javac, et al work). That makes it impossible to run the ajdoc taskdef (which does not currently support forking), so you'll need to run a separate ant process, either from the command-line or via Ant's exec task (the Ant task will propagate the classpath). If the wrong tools.jar is not on the ant classpath, then it should work to put the 1.3 tools.jar in the taskdef classpath.

It is a bad practice to use the compilation unit to control crosscutting. Aspects and pointcuts especially should be written to specify crosscutting precisely. Aspects will behave the same when you add files if you initially included all files affected by your aspects. If you use the compilation unit, then your code will behave differently in AspectJ implementations that do not limit themselves to specified files.

The generated code can be difficult for a human to read and understand. The compiler uses implementation techniques which might not be apparent. To determine if the code is behaving correctly, you should write and run a program that attempts to provoke the error you suspect. Similarly, you should not rely on invariants you infer from the generated code (especially naming conventions for generated members). Please rely only on the semantics stated in the appendix of the AspectJ Programming Guide.

This is a misconception spawned from the early implementation.

AspectJ does not "inject" or "generate" code. In AspectJ the pointcut constructs allow the programmer to identify join points, and the advice constructs define additional code to run at those join points.

So the semantic model of advice is like the semantic model of a method -- it says "when any of these things happen, do this".

People who worked with earlier versions of AspectJ, in which ajc was very explicitly a pre-processor, sometimes thought of AspectJ as injecting code. But that was an artifact of the implementation, not the underlying language semantics.

This distinction is important for two reasons. One is that thinking about it this way will make more sense at the implementation continues to evolve towards load-time or runtime weaving. The other is that it makes it much easier to understand the semantics of advice on cflow pointcuts.

Users have sometimes wanted AspectJ to pick out many more join points, including

The pointcut execution(void run()) will work. The call pointcut doesn't work because Method.invoke(..) is the Java method-call, and AspectJ cannot delve into the Java reflection library to implement call semantics. To advise a reflective call (e.g., because the compiler does not control the code for the method execution), test the context for invoke(..). Here's a pointcut that tests only if the method name is correct:

aspect A {
    pointcut runReflectiveCall(Method run) : target(run) &&
         call(Object Method.invoke(..)) && if("run".equals(run.getName()));		  
    before() : runReflectiveCall(Method) { 
        System.out.println("before reflective call " + thisJoinPoint); 
    }
}
          

The bugs affecting the semantics of the language are marked with the "info" keyword. Find them with the query http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info

From the message sent to users:

AspectJ has come a long way -- the language has stabilized; there are a rapidly growing number of commercial users; the 1.1 release is imminent and will include byte-code weaving and incremental compilation; and the tool support is now well integrated with several major IDEs.

This growth of the community and the technology means that the original research and prototype development of AspectJ is complete. As such it is time for ongoing development and support of AspectJ to move outside of PARC. This has already started to happen; the Eclipse AJDT plug-in and the several books in preparation are examples.

To encourage the growth of the AspectJ technology and community, PARC is transferring AspectJ to an openly-developed eclipse.org project. This project will include documentation, web site, mailing lists, bug database, and sources for the compiler. The command-line AspectJ compiler is still the primary tool produced by this project, in addition to APIs that support integration with a variety of IDEs. The Eclipse plug-in will remain at eclipse.org, while the NetBeans, JBuilder and Emacs support will move to SourceForge.net projects. We look forward to your involvement with and contribution to those projects.

We see Eclipse as an excellent new home for core AspectJ technology development -- it is an active community of Open Source development and innovation in the Java space. Once development moves to Eclipse.org, others will be able to contribute more easily.

No. The AspectJ tools download is completely self-contained and does not require that you work in Eclipse. For information on IDE support, see Q: How well does AspectJ integrate with existing Java development tools?.

Eclipse is a software platform.

JDT is an eclipse project to support Java development. JDT has a Java compiler.

AspectJ 1.1 is built on Eclipse/JDT's Java compiler but is distributed standalone and can run standalone. With the AspectJ distribution, you can compile and run AspectJ programs and use the AspectJ structure browser.

AJDT is an eclipse project to integrate AspectJ into Eclipse/JDT so you can use Eclipse to develop AspectJ programs. AJDT aims to support the full Eclipse experience - searching, compiler-error tasks, etc. AJDT will use the AspectJ Development Environment (AJDE) API's for creating IDE integrations, as well as hooking in to the model underlying the Java compiler.

Similarly, Sourceforge has projects integrating AspectJ into other development environments using the AJDE API's: AspectJ for Emacs, AspectJ for JBuilder, and AspectJ for NetBeans.

This is the right level of separation/integration. AspectJ is available standalone, leverages an existing open-source compliant Java compiler, and supports external projects doing IDE integrations in Eclipse, Emacs, JBuilder, and NetBeans through a common API, AJDE.

All the new features are documented in the AspectJ 5 Developer's Notebook and the AspectJ Development Environment Guide. To summarize:

To use AspectJ, you can use the original code-style aspects or the annotation-style aspects new in AspectJ 5.

The original code-style is a small extension of the Java language designed to express crosscutting as clearly as possible in ways familiar to most Java programmers. To use the original code-style aspects, compile them with the AspectJ compiler or weave pre-compiled binary aspects using the AspectJ binary (.class) weaver, either at build-time or at class-load-time. Code-style aspects have excellent IDE support, allowing you to navigate to and from affected source code.

Annotation-style aspects are written (not surprisingly) using annotations. They use the subset of the AspectJ language that works when aspects are woven after the code is compiled. The source files are compiled with Javac, which simply saves the annotations in the .class files. The resulting .class files must be woven using the AspectJ weaver, which reads the annotations from the .class file and uses them to define aspects. Annotation-style aspects have the benefit of being compilable by Javac, but you can't use the full AspectJ language, and you don't enjoy the same level of IDE support for viewing crosscutting structure.

While the AspectJ weaver could be used at load-time in previous releases, the AspectJ 5 release supports much better integration with the Java 5 VM and the BEA JRocket JVM. It also supports an XML file for configuration that allows deployers to declare concrete aspects using only XML. This means aspect developers can write abstract aspects, and deployers need only configure aop.xml and run using the AspectJ weaver in Java 5. For example, to run Java 5 VM with load-time weaving,

            
java -javaagent:aspectjweaver.jar -classpath "aspects.jar:${CLASSPATH}" ..

          

To declare a concrete aspect, add a a concrete-aspect XML entity to META-INF/aop.xml. This example extends a tracing aspect to apply to every type in the application:

            
<concrete-aspect 
    name="com.company.tracing.ConcreteTracing"
    extends="tracing.AbstractTracing">
    <pointcut 
        name="tracingScope" 
        expression="within(com.company.app..*)"/>
</concrete-aspect>                

          

For more information, see the AspectJ Development Environment Guide.

Writing AspectJ programs only requires understanding the Programming Guide. However, current implementations do not control everything in a system, so AspectJ program semantics may be limited to code the implementation controls. For our implementation, these limitations are stated in Programming Guide Appendix: Implementation Notes. Aside from understanding the use and limitations of the implementation, there is no need to understand the underlying technology when writing AspectJ programs.

The technology that implements AspectJ interests some academic researchers and some developers who want new features or new ways to weave. These extensions are not discussed in the documentation. Some are being developed already, others are on the drawing board (or perhaps were left off long ago), and still others haven't been considered. If you are interested in a certain extension, check the bug database for feature requests and the mailing list archives for any past discussions. Then email the list to see if it's been considered. For more information, see AspectJ Project Development.

There are currently no documents describing this process in detail. You can compile programs and inspect the generated source or bytecode, or view the source code (see AspectJ Project Development). We hope to write papers on the bytecode weaving model used in AspectJ-1.1 if we can find the time. Erik Hilsdale and Jim Hugunin did draft a paper for AOSD 2004, now available on Jim's web site: http://hugunin.net/papers.html Jim summarized advice weaving in the AspectJ 1.1 implementation in the following mailing-list reply:

Each piece of advice in an aspect is associated with a pointcut. This pointcut is stored in an attribute on the methods corresponding to each piece of advice. Before weaving, all of these pieces of advice are gathered into one large list.

Each .class file is woven independently. A .class file is woven by the following steps:

Note: This explanation ignores the implementations of inter-type declarations completely. It also ignores performance optimizations such as fast-match that speed up the weaving process.

The only time that reflection is used during run-time is when the special thisJoinPoint object is used to discover reflective information about the join point. If you don't use thisJoinPoint then no reflection will be used.

Since the 1.1 release, AspectJ can weave binary aspects into classes in bytecode form. Hooked up to a class loader, this can weave class bytecodes after they are read in, before the class is defined by the VM. (This means load-time weaving only works were aspects are not required to compile the pure-java classes. If the aspects are required, then the Java classes have to be compiled with the aspects using the AspectJ compiler.) The AspectJ 1.2 release had the WeavingURLClassLoader, and the 1.2.1 release introduced the aj.bat script for Java 1.4. The AspectJ 5 release introduces much better support for load-time weaving, including declaring concrete aspects in XML files and integrating with Java 5 and BEA JRocket JVM's. See ???.

Some have asked about only weaving particular classes specified at run-time. Aspects should work across an entire namespace, and problems will likely result from weaving some classes but not others. Also, it's confusing to specify crosscutting both in the aspect and in the list of runtime classes; the crosscutting specification should be in the aspect itself, where it can be processed by tools.

And just to state the obvious: do not use bytecode weaving, at load-time or otherwise, to modify .class files protected by license, without permission from the licensor.

Most people do not need to see the code for AspectJ; they can download the binary distribution for documentation and tools for writing AspectJ programs.

For people who want to know how the AspectJ technology works, the source code is the best resource, until we write some proper white papers (see Q:Do I need to know how the compiler works?). To get and compile the Java source code for the AspectJ distribution, see Q:How do I get and compile the source code for AspectJ?.

Bear in mind when looking at the code that there are many ways to implement the AspectJ language, and the code inspected might be an initial version of a new architecture (e.g., bytecode weaving).

For those who want to contribute to the project, here's a general list of ways to do so, in no particular order:

AspectJ 1.0 source code is available in an archive available with the 1.0 downloads. It contains instructions for building from sources.

AspectJ 1.1+ source code is available through CVS using the CVS Root dev.eclipse.org:/cvsroot/technology. For more information on accessing the CVS tree at eclipse.org, see the documentation from http://eclipse.org. Find specific instructions in the AspectJ tree at org.aspectj/modules/build/readme-build-and-test-aspectj.html. If you would like to use Ant to checkout the sources, build the distribution, and test everything, see org.aspectj/modules/build/release/build.xml.

To check out the source code in Eclipse go to (File > new > Other > CVS > Checkout Projects from CVS). You'll need about 125 MB of space for the source and build. Host: dev.eclipse.org, Repository Path: /cvsroot/technology, user name: anonymous, password: (your email address), connection type: pserver, default port. Then select the individual modules you want to check out (you probably want all of them bar aspectj-attic and java5) and click Next and choose to check out the modules you selected as Java projects. Once thats done each module you checked out should show up as a project in the package explorer. If you have problems after this point you can view the build instructions that come with AspectJ by going in the package explorer to: build > readme-build-and-test-aspectj.html.

To get the modules to build you have to set some classpath variables (Window > Preferences > Java > Build Path > Classpath Variables):

When you've added the variables click OK to do a full rebuild, then run the tests by going in the Package Explorer to: run-all-junit-tests > testsrc > (default package) > RunTheseBeforeYouCommitTests.java and running this as a JUnit test (right click and select Run As > JUnit Test). Don't worry about any errors that appear in the console output, just check that there are no failures in the JUnit view (Window > Show View > Other > Java > JUnit). If that finishes with no Failures and a full green bar you have the AspectJ compiler source and it's building and testing properly.

Further details:

You can check out the entire modules directory and build using the Ant build script modules/build/build.xml. All required libraries are included in modules/lib/, (including Ant 1.5.1 in modules/lib/ant). If you are using Eclipse, you can check out any modules/ subdirectory as an eclipse Java project. Depending on what you are trying to build, you need not check out all modules; as of this writing, here are the modules to get for building the specific parts of AspectJ:

Note that module interdependencies are recorded only in the eclipse modules/{module}/.classpath files and may change, so the list above may not be correct when you read it.

Find the developer documentation in HTML files in the CVS tree, inside the build and testing modules (i.e., in org.aspectj/modules/build/...). Most pertinant:

You can attach files to a bug after it has been created. The code of course should replicate the actual behavior described in the bug when run on the target version. If you have a single source file, you can attach it directly, describing in the comments the expected result (e.g., error on line 14, or successful compile/run). The most helpful form for describing the test scenario and the expected results are the test definitions described next.

For more complex bugs requiring many files, create a zip file of a directory containing all the files and an XML test definition file. The XML test definition file contains specifications for how to compile, recompile, or run the test sources. Complete documentation is available in the CVS tree at tests/readme-writing-compiler-tests.html but here is a sample file with some example definitions, preceded by comments showing the directory layout of the files referred to in the test definitions.

<!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
<suite>

<!-- Compile and run
     using the following files:

       {testDefinitions}.xml
       one/
         pack1/
           Main.java
         p2/
           BeforeConstructor.java

    Note the bug number goes in the pr attribute.
    ("pr" stands for "problem report")
 -->
<ajc-test dir="one" pr="234" title="before constructor call">
    <compile files="pack1/Main.java,p2/BeforeConstructor.java"/>
    <run class="pack1.Main"/>
</ajc-test>

<!-- Check that compiler warning was emitted 
     using the following files:

       {testDefinitions}.xml
       two/
         UsesDeprecated.java
 -->
<ajc-test dir="two" pr="244" title="deprecated, noImportError">
    <compile options="-warn:deprecated,-noImportError" 
          files="UsesDeprecated.java">
        <message kind="warning" line="20"/>
    </compile>
</ajc-test>

<!-- Cooked example that uses all compiler attributes 
     and the following files:
       {testDefinitions}.xml
       testCaseDir/
         jars/
           injar.jar
           required.jar
           requiredAspects.jar
         pack/
           Main.java
         providedClassesDir/
           ClassInDefaultPackage.class
           org/
             foo/
               AnotherRequired.class
  -->
<ajc-test dir="testCaseDir" title="attributes test">
    <compile files="pack/Main.java,jars/injar.jar" 
           staging="true"
           options="-Xlint,-g:none"
          argfiles="debug.lst,aspects/test.lst"
        aspectpath="jars/requiredAspects.jar"
         classpath="providedClassesDir,jars/required.jar"/>
    <run class="Main"/>
</ajc-test>

<!-- Compiler errors, recompile after changing files, and run
     using the following files:

       {testDefinitions}.xml
       three/
         pack/
           IncCompileFix.java
           IncCompileFix.20.java

     Before compiling, IncCompileFix.java is copied to a staging
     directory.  Before recompiling, IncCompileFix.20.java 
     replaces it, so the compiler treats file as updated.
  -->
<ajc-test dir="three" pr="622" title="incremental fix">
    <compile staging="true" files="pack/IncCompileFix.java">
        <message kind="error" line="20"/>
        <message kind="error" line="42"/>
    </compile>
    <inc-compile tag="20"/>
    <run class="pack.IncCompileFix"/>
</ajc-test>

</suite>

          

The test harness is not distributed. To build it, get the source tree as described in Q:How do I get and compile the source code for AspectJ? and then build the build-testing-drivers target:

  cd build
  ../lib/ant/bin/ant -f build.xml build-testing-drivers
          

The AspectJ bytecode weaver has used BCEL for bytecode manipulation since its first release. We have upgraded it extensively, to improve performance, support Java 5, etc. The BCEL developers have not incorporated our patches, so we continue to maintain our own version. Ours has been optimized for the AspectJ weaver and battle-hardened over years of development and use. At some point in the future, the AspectJ weaver might be restructured to make it easy to see whether another bytecode package offers the same stability, functionality, and performance, but for now we prefer using something that we know works well.

In the AspectJ 5 release, the weaver has been restructured to use reflection where possible. Otherwise, it continues to use BCEL, but does not hold BCEL structures in memory after our evaluation completes.

Visit the AspectJ project web site: http://eclipse.org/aspectj.

You can submit a bug from http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ . If it seems to be a bug in the compiler, please attach a small test case (source code) to reproduce the problem. For more information on writing compiler test cases, see Q:How do I write bugs for the AspectJ compiler?.

You can reach other AspectJ users by using the aspectj-users mailing list. You can subscribe to the list or view the list archives from the AspectJ home page http://eclipse.org/aspectj .

It is very effective to do a google search of the form, http://www.google.com/search?q=site:eclipse.org+cflowbelow , and you can use the eclipse.org search at http://www.eclipse.org/search/search.cgi . You can also check the old archives available for download from the AspectJ home page http://eclipse.org/aspectj .

Here's the general form of a good email:

The big picture helps others redirect you to other approaches. Using AspectJ terms helps others correct mistakes in thinking about the problem (the most common being to confuse join points and pointcuts). The code is key to clarifying your question and getting a good response. On the mail list, someone can reply by fixing your code. In bugs, the developers can reproduce the problem immediately and start analyzing the fix. The code should not be incomplete; it should run (or fail) as-is, without additional libraries or source files.

For the mail lists, we try to follow the conventions for open-source discussions that help avoid "the tragedy of the commons." For example conventions, see http://jakarta.apache.org/site/mail.html and http://www.tuxedo.org/%7Eesr/faqs/smart-questions.html .

Bugs appearing in the IDE's may apply to the affected IDE or to the compiler. Compiler stack traces in IDE message windows are prefixed "Internal Compiler Error" and should be written up as compiler bugs. If you are unsure, try redoing the compile from the command line.

Bug report for the IDE extensions go to their respective projects, listed in Q: How well does AspectJ integrate with existing Java development tools? (including bug reports for the AJDE Eclipse support, which you can submit at http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT ).

Bug reports on ajbrowser should have version information for both Java and AspectJ, and (most importantly) clear steps for reproducing the bug. You may submit ajbrowser bugs against the IDE component of AspectJ via the web form http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ .

One of the benefits of open-source is that you can find and fix the bug for yourself; when you submit the fix back to us, we can validate the fix for you and incorporate it into the next release. You can submit a patch by attaching it to the bug.

The best compiler bug report is a reproducible test case, standalone code that demonstrates the problem. Sometimes with aspects, a test case requires several files, if not some way to capture the behavior. Here's how we recommend submitting test cases:

The documentation available in the distribution is the best source for language and usage questions. You can also find selected AspectJ papers and presentations on the PARC AspectJ page. For links to Aspect-oriented programming materials in general, see http://aosd.net.

The best thing to to is join and email the aspectj-dev@eclipse.org mailing list.

Entries changed recently:

Open source protects your interest in a correct, long-lived, up-to-date, and widely-accepted implementation of AspectJ.

Although we are committed to making AspectJ available to a wide range of users, it is too early to decide on a strategy. Some options include continuing AspectJ as a stand-alone product, integrating it into IDEs, or possibly incorporating it into standard Java with Sun's blessing.

We currently focus on developing for the 1.1 implementation which improves AspectJ in key areas: rapid incremental compilation, bytecode weaving, and IDE integration.

Through all of this our goal is to make AspectJ integrate as seamlessly as possible with the Java programming language. The AspectJ language design is becoming more integrated, the compiler is becoming faster and more integrated, the IDE extensions are becoming more integrated. All of this is designed to help users really use AspectJ and give us feedback on it.

As the system is improved and we work more closely with users, we will be in good position to explore the best path for AspectJ in the long term.

Bytecode weaving is in AspectJ 1.1. We believe it works as described in an email to the users list by Jim Hugugin:

The AspectJ language was designed to support weaving at many different times: compile, load, or even run-time in the JVM. Weaving into bytecodes at both compile and load-time will definitely be provided in a future release. This will allow weaving at compile-time into libraries for which source code is not available. It will also support aspect-aware class loaders that can perform weaving at load time on arbitrary classes. One advantage of a language like AspectJ, rather than an explicit meta-tool like jiapi, is that it separates the specification of a crosscutting concern from any particular implementation strategy for weaving.

...AspectJ provides a language that can cleanly capture crosscutting concerns while preserving the static type checking, modularity, and composability of Java.

If you have an application for using aspects and bytecode, please let the AspectJ team know of your requirements. We expect to have a demonstration classloader available in the 1.1 release or soon thereafter.

The AspectJ team aims to keep the implementation bug-free and up-to-date with the Java language, to limit AspectJ language changes to those that are carefully considered, compelling, and backwards-compatible, and to deliver those language changes only in significant releases (1.0, 1.1).

More details for 1.0 and earlier releases are available in changes.html.

Below is a table describing the goals for the major releases. For information about specific features, search the bug database for RFE's ("requests for enhancement") by selecting severity of "enhancement". Like many open-source projects, we don't make or promise schedules, but we do follow a pattern of issuing preview releases which can give observers an idea of when a particular release might be available.

Yes. Java 5 is supported in AspectJ 5.