AspectJ introduces two new paths for the binary input to the weaver which you'll find referenced in The ajc Command-line Reference, AspectJ Browser, AspectJ Ant Tasks, and Load-Time Weaving.

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

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

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

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

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

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

A build configuration is a set of files to compile for a program (and optionally some additional compile arguments). Because ajc requires all sources to be specified (at least using the -sourceroots option), most users create .lst files that list the files to compile (one argument per line, globbing permitted - for more details, see The ajc Command-line Reference).

To work with a particular program, select the corresponding ".lst" build configuration file from the GUI using the File menu, "open" item, or by using the "Open Build Configuration" button (). You can populate the build list from the command line by passing any number of ".lst" paths. (However, if you pass in any non-".lst" arguments, it will run the command-line compiler directly.)

To switch between build configurations, select, add, or remove them using the corresponding toolbar buttons.

Global build options are stored in an .ajbrowser file in your HOME directory. Edit these from the GUI by clicking the "Options" button or selecting the Tools menu item "Options...". This is how to set classpath, aspectpath, etc.

The following sections walk through a build.

To compile click the "Build" button (), or or use the tools menu.

You may select from different build configurations in the GUI (see label 1 in the graphic below). (If you get classpath or other errors, set up the global build options as described above.)

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

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

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

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

Boolean parameters default to false unless otherwise stated.

AjcTask (iajc) options for specifying sources

AjcTask (iajc) options for specifying output

AjcTask (iajc) options for specifying compiler behavior

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

AjcTask (iajc) options for specifying Eclipse compiler options

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

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

    
    <iajc {attributes..} />
        <{name}>    
            <pathelement path="{first-location}"/>
            <pathelement path="{second-location}"/>
            ...
        <{name}>    
        ...
    </iajc>

	

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

    
    <path id="aspect.path">
        <pathelement path="${home}/lib/persist.jar"/>
        <pathelement path="${home}/lib/trace.jar"/>
    </path>
    ...
    <iajc {attributes..} />
        <aspectpath refid="aspect.path"/>    
        ...
    </iajc>

	

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

    
    <iajc {attributes..} aspectpathref="aspect.path"/>    

	

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

		
<project name="simple-example" default="compile" >
  <taskdef 
      resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties">
    <classpath>
      <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/>
    </classpath>
  </taskdef>

  <target name="compile" >
    <iajc sourceroots="${home.dir}/ec/project/src" 
        classpath="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/> 
  </target>
</project>

		

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

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

		
  <target name="build-test" >
    <iajc outjar="${home.dir}/output/application.jar" 
            sourceRootCopyFilter="**/CVS/*,**/*.java"
            inpathDirCopyFilter="**/CVS/*,**/*.java,**/*.class"
            incremental="true" >
      <sourceroots>
        <pathelement location="${home.dir}/ec/project/src"/>
        <pathelement location="${home.dir}/ec/project/testsrc"/>
      </sourceroots>
      <inpath>
        <pathelement location="${home.dir}/build/module.jar"/>
        <pathelement location="${home.dir}/build/binary-input"/>
      </inpath>
      <aspectpath>
        <pathelement location="${home.dir}/ec/int/persist.jar"/>
      </aspectpath>
      <classpath>
        <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
      </classpath>
    </iajc>
    
    <java classname="org.smart.app.Main">
      <classpath>
        <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
        <pathelement location="${home.dir}/ec/int/persist.jar"/>
        <pathelement location="${home.dir}/output/application.jar"/>
      </classpath>
    </java>
  </target>

		

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

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

		
  <target name="check.aspects.jar">
    <uptodate property="build.unnecessary" 
        targetfile="${aspects.module-jar}" >
       <srcfiles dir="${src1}" includes="**/*.aj"/>
       <srcfiles dir="${src2}/" includes="**/*.aj"/>
    </uptodate>
  </target>

  <target name="compile.aspects" depends="prepare,check.aspects.jar" 
          unless="build.unnecessary">
     <iajc ... 

		

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

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

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

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

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

		
-- command:

    cp aspectj1.1/lib/aspectjtools.jar ant/lib
    ant/bin/ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter ...

-- task invocation in the build script:

  <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" />

		

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

		
-- command

  Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter

-- build script

  <property name="ajc" 
              value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/>

  <javac srcdir="src" includes="org/aspectj/**/*.java" destdir="dest" >
    <compilerarg compiler="${ajc}" line="-argfile src/args.lst"/>
  <javac/>

		

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

Special considerations when using Javac and compilerarg:

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

Boolean parameters default to false unless otherwise stated.

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

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

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

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

		
<project name="example" default="compile" >
  <taskdef name="ajc"
    classname="org.aspectj.tools.ant.taskdefs.Ajc10" >
    <!-- declare classes needed to run the tasks and tools -->
    <classpath>
      <pathelement location="${home.dir}/tools/aspectj/lib/aspectjtools.jar"/>
    </classpath>
  </taskdef>

  <target name="compile" >
    <mkdir dir="dest" />
    <ajc destdir="dest" argfiles="default.lst" >
      <!-- declare classes needed to compile the target files -->
      <classpath>
        <pathelement location="${home.dir}/tools/aspectj/lib/aspectjrt.jar"/>
      </classpath>
    </ajc>
  </target>
</project>

		

This build script snippet

				
		  <ajc srcdir="${src}"
		       destdir="${build}"
		       argfiles="demo.lst"
		  />

		

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

This next example

				
		  <ajc srcdir="${src}"
		       destdir="${build}"
		       includes="spacewar/*,coordination/*"
		       excludes="spacewar/Debug.java"
		  />

		

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

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

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

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

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

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

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

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

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

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

          <aspectj>

            <aspects>
              <!-- declare two existing aspects to the weaver -->
              <aspect name="com.MyAspect"/>
              <aspect name="com.MyAspect.Inner"/>

              <!-- define a concrete aspect inline -->
              <concrete-aspect name="com.xyz.tracing.MyTracing"
                               extends="tracing.AbstractTracing"
                               precedence="com.xyz.first, *">
                <pointcut name="tracingScope" expression="within(org.maw.*)"/>
              </concrete-aspect>

              <!-- Of the set of aspects declared to the weaver
                   use aspects matching the type pattern "com..*" for weaving. -->
              <include within="com..*"/>

              <!-- Of the set of aspects declared to the weaver
                   do not use any aspects with the @CoolAspect annotation for weaving -->
              <exclude within="@CoolAspect *"/>

            </aspects>

            <weaver options="-verbose">
              <!-- Weave types that are within the javax.* or org.aspectj.*
                   packages. Also weave all types in the foo package that do
                   not have the @NoWeave annotation. -->
              <include within="javax.*"/>
              <include within="org.aspectj.*"/>
              <include within="(!@NoWeave foo.*) AND foo.*"/>

              <!-- Do not weave types within the "bar" pakage -->
              <exclude within="bar.*"/>

              <!-- Dump all types within the "somepack" package,
                   both before are after they are woven,
                   to the "./_ajdump" folder on disk (for diagnostic purposes) -->
              <dump within="somepack.*" />
            </weaver>

          </aspectj>

		  

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

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

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

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

The weaver element is used to pass options to the weaver and to specify the set of types that should be woven. If no include elements are specified then all types visible to the weaver will be woven.

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

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

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

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

            package mypack;

            @Aspect
            public abstract class AbstractAspect {

                // abstract pointcut: no expression is defined
                @Pointcut
                abstract void scope();

                @Before("scope() && execution(* *..doSome(..))")
                public void before(JoinPoint jp) {
                   ....
                }
            }
            

This aspect is equivalent to the following in code style:

            package mypack;

            public abstract aspect AbstractAspect {

                // abstract pointcut: no expression is defined
                abstract pointcut scope();

                before() : scope() && execution(* *..doSome(..)) {
                   ....
                }
            }
            

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

            <aspectj>
                <conrete-aspect name="mypack.__My__AbstractAspect" extends="mypack.AbstractAspect">
                    <pointcut name="scope" expression="within(yourpackage..*)"/>
                </concrete-aspect>
            </aspectj>
            

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

                // exception handling omitted
                Class myConcreteAspectClass = Class.forName("mypack.__My__AbstractAspect");

                // here we are using a singleton aspect
                AbstractAspect concreteInstance = Aspects.aspectOf(myConcreteAspectClass);
            

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

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

                <aspectj>
                    <concrete-aspect name="mypack.__MyDeclarePrecedence"
                                     precedence="*..*Security*, Logging+, *"/>
                </aspectj>
            

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

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

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

			-javaagent:pathto/aspectjweaver.jar
		  

The JRockit agent is configured with the following JVM option:

			-Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent
		  

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

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

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

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

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

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

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

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

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

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

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

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