Frequently Asked Questions about AJDT

Last updated on 12th April 2005.

1 Overview
1. What is AJDT?
2. Who develops AJDT?
3. Where can I get the latest version?
4. How does AJDT relate to the AspectJ project?
2 Community
1. Are there any newsgroups for AJDT users?
2. What do I do if I think I've found a bug in AJDT?
3. How can I request a new feature in AJDT?
4. Is there an AJDT mailing list?
3 Using AJDT
1. Why aren't AspectJ keywords highlighted in the editor?
2. Why are keywords like "aspect" underlined as problems?
3. Why doesn't the outline view update as I type in the editor?
4. How can I debug AspectJ programs in Eclipse?
5. How does the Visualiser work?
6. What happened to the JoinPoint probe?
4 Contributing
1. How can I contribute to the AJDT project?
2. How can I package my sample code for contribution to the examples plugin?
3. Where will I find the source for AJDT?
4. How do I setup an AJDT development environment in Eclipse?
5 Plans
1. What new AJDT features are being worked on at the moment?

1 Overview

1. What is AJDT?

The AspectJ Development Tools project (AJDT) is a set of plugins for Eclipse that provide support for aspect-oriented software development using AspectJ within the Eclipse IDE.

2. Who develops AJDT?

AJDT is an open-source project hosted on eclipse.org, current contributors are listed on the website. Anyone can get involved, see "How can I contribute?"

3. Where can I get the latest version?

Details about how to get hold of AJDT are available from the download page.

4. How does AJDT relate to the AspectJ project?

AJDT provides Eclipse IDE integration for AspectJ, and includes the AJDE (AspectJ Development Environment) libraries from the AspectJ project as part of its packaging. Development of the AspectJ compiler and AJDE takes place under the AspectJ project.

2 Community

1. Are there any newsgroups for AJDT users?

AJDT is supported through the eclipse.technology.ajdt newsgroup. A web interface is also available.

2. What do I do if I think I've found a bug in AJDT?

First check the bug database to see if you've hit a known problem. There's also a view built into AJDT (Window->Show View->Other...->AspectJ->AJDT Event Trace) that displays a lot of diagnostic information about the execution of the plugin (for example, it will show you the exact classpaths being used for compilation). If it appears to be a genuinely new bug, please submit a bug report on AJDT using bugzilla following the bug reporting guidelines.

3. How can I request a new feature in AJDT?

Informal requests can be posted to the newsgroup or mailing list. Formal requests can be made by raising an AJDT enhancement request on Bugzilla.

4. Is there an AJDT mailing list?

AJDT has a developers mailing list, ajdt-dev@dev.eclipse.org, with archives and subscription information available online. Questions regarding the use of AspectJ the language are best directed to the AspectJ users mailing list.

3 Using AJDT

1. Why aren't AspectJ keywords highlighted in the editor?

The most common cause of this problem is opening Java files (files with the .java extension) using the JDT's Java Editor. AJDT provides an extension to the Java Editor, the AspectJ Editor, that recognizes AspectJ language structure and provides an outline view that displays crosscutting structure information. To configure Eclipse so that Java files are opened with the AspectJ editor, select "preferences" from the Window menu. Expand the workbench preferences and click on "File Associations." Select file type "*.java," then select the AspectJ Editor and click the "Default" button.

2. Why are keywords like "aspect" underlined as problems (red squiggle underline)?

AJDT doesn't yet provide an eager parser for AspectJ. The early problem indication support is therefore expecting to see a regular Java program, and so treats AspectJ keywords as errors. The squiggles can be turned off by opening preferences from the Window menu: Expand the Java preferences and click on "Editor." In the "Problem Indication" tab, uncheck the option "Show problems before compiling."

3. Why doesn't the outline view update as I type in the editor?

AJDT doesn't yet provide an eager parser for AspectJ, so the understanding of the editor buffer contents needed to update the outline view is only after a compilation. The process of compiling creates a structure model (including the crosscutting information) that the outline view then renders.

4. How can I debug AspectJ programs in Eclipse?

Working with with AspectJ programs in the debugger has the following limitations:

  • You can step into and through most aspect code but around advice is still problematic - use "step into" instead of "step over" on an advised line of source in order to step into the aspect code.
  • If you use "step over" to step past a line of code, this will also step over any advice applied to that line in one step.

NB. Since 1.1.11 breakpoints can be set in aspects as well as in classes.

5. How does the Visualiser work?

The Visualiser consists of two views, the Visualiser and the Visualiser Menu, both of which need to be open: Select "Window" , "Show View" , "Other... Visualiser" from the taskbar, then select "Visualiser" and "Visualiser Menu " and click OK. Alternatively, open the Aspect Visualization perspective by clicking "Window", "Open Perspective", "Other... Aspect Visualization".

The Visualiser has a provider architecture - other plugins define content providers that plug in to the Visualiser through extension points. Only one provider can be active at a time. The active provider determines the bars and stripes that are shown. You can tell which provider is active from the Visualiser title bar. If the AspectJ provider is not active by default, click "Window", "Preferences", then select "Visualiser", select the AspectJ Provider, then click OK.

To visualize an AspectJ project, click on the AspectJ Project in the Package Explorer or the Projects view. If the project has been built the aspects defined in that project should appear in the Menu. The Visualiser shows all the classes in your project with bar length proportional to number of lines of code. Dark bars represent classes not affected by an aspect. Coloured lines on the white bars represent lines of code affected by the Aspect in the Menu with the corresponding colour. It is also possible to click on individual classes or packages in the package explorer to see their individual representations.

The Visualiser starts in class view by default. Click on the package button to choose package view. Here each bar represents a package in your project and length is proportional to total number of lines. Package view was designed as an overview, particularly for large projects. Click on the class button to return to class view.

In either package or class view, clicking on the limit button restricts the view to affected bars only. Clicking again leaves limit mode.

To open the source file of a represented class, double click on the corresponding bar. To open a source file at a line affected by an aspect, double click on the corresponding coloured stripe.

If you would like to find out more the Visualiser has its own Eclipse help pages.

6. What happened to the JoinPoint probe?

The JoinPoint probe was an experimental function that made a brief appearance in AJDT 0.5.2 and 0.6.0beta. We have temporarily removed it from AJDT whilst we work out the correct user-interaction model and port the Swing UI to SWT.

4 Contributing

1. How can I contribute to the AJDT project?

Your contributions to the AJDT project are strongly welcomed! You can create a patch that fixes a bug or provides an enhancement and submit it to the AJDT developers either as an attachment to a bug in Bugzilla, or as an attachment to a post to the newsgroup or developer mailing list. You can also contribute sample code showing interesting uses of AspectJ, by adding entries to the example plugin. All contributions must be made available under the terms of the Eclipse website see the Eclipse contribution and participation FAQ. Sorry, but for legal reasons we are unable to accept patches emailed directly to developers, and will normally ask you to resubmit these either via Bugzilla or the mailing list.

AJDT development is run as a meritocracy, developers who have a track record of submitting good patches can become committers on the project.

2. How can I package my sample code for contribution to the examples plugin?

The org.eclipse.ajdt.examples plugin contains various sample projects which are made available under the Examples category of the New wizard, from where they can be imported into your workspace as AspectJ projects. It is easy to add new samples to this plugin, as follows:

  • Create a jar file containing your source code, and at least one build configuration file. Place this in the archive folder of the examples plugin.
  • Add an entry to the plugin.xml file for your sample project, by copying one of the existing entries.
  • Change the src attribute of the import element to refer to your jar file, and change the title, description, pagetitle, and pagedescription property names as appropriate, and add corresponding entries to the plugin.properties file.
  • Change the build attribute to refer to your default build configuration file. Your project may contain more configurations but the one specified here will be the one used to initially build the project.
  • Optionally, you can specify an open attribute to the projectsetup element, which refers to a file, such as a README file, which is opened after the project has been imported to the workspace.

3. Where will I find the source for AJDT?

AJDT source is held in the Eclipse CVS repository under /home/technology, see the root of the AJDT source tree online. AJDT is organized in subdirectories under org.eclipse.ajdt. The main source tree is in the “AJDT1.2src” subdirectory, and contains the following plugins:

Plugins under “AJDT1.2src”
 
Description
 
org.aspectj.ajde
 
The AJDE plugin provided by the AspectJ project
 
org.aspectj.runtime
 
The AspectJ runtime classes
 
org.eclipse.ajdt.build
 
Automatic build plugin – only used by the build process
 
org.eclipse.ajdt.core
 
Non-UI parts of AJDT
 
org.eclipse.ajdt.examples      
AspectJ examples plugin
 
org.eclipse.ajdt.test
 
AJDT Tests
 
org.eclipse.ajdt.tests.performance
 
AJDT performance tests
 
org.eclipse.ajdt.ui
 
The AJDT UI plugin
 
org.eclipse.aspectj
 
The AspectJ feature
 
org.eclipse.aspectj.feature
 
The "feature" plugin
 
org.eclipse.contribution.visualiser
 
The Visualiser plugin
 
org.eclipse.contribution.visualiser.tests
 
Visualiser tests
 
org.eclipse.contribution.xref.core
 
The Cross References plugin (non-UI)
 
org.eclipse.contribution.xref.core.test
 
tests for the above
 
org.eclipse.contribution.xref.ui
 
The Cross References plugin UI
 
org.eclipse.contribution.xref.ui.test
 
tests for the above
 
UpdateSite     
Plugin used to build an update site

4. How do I setup an AJDT development environment in Eclipse?

There are several stages to this: building AJDT, running the correctness tests, running the performance tests, and creating an Eclipse update site. The first two stages are probably sufficient for most purposes. Note that the steps required for the first stage depend on whether you are using Eclipse 3.0 or 3.1.

Building AJDT

Note first of all that in order to build AJDT you may need to increase the memory available to Eclipse. This is typically done by passing something like "-vmargs -Xmx256m" to the Eclipse launcher.

Start with a clean workspace under Eclipse 3.0.1 or the latest milestone build of Eclipse 3.1. Some of the AJDT projects contain aspects, so you will need to install an earlier version of AJDT before you can build the CVS version. See the AJDT download page for more details - a recent version of AJDT is recommended. Make sure you pick a version that matches your Eclipse version.

Now open the CVS Repository Exploring perspective. Right-click on the CVS Repositories view, then click "New" > "Repository Location". Host = dev.eclipse.org, Repository path = /home/technology, Username = anonymous, password should be left blank. Connection type = pserver. Click "Finish". Use the CVS Repositories view to navigate to org.eclipse.ajdt/AJDT1.2src. Select the following projects, right-click and select "Check out" from the context menu:

  • org.aspectj.ajde,
  • org.aspectj.runtime,
  • org.eclipse.ajdt.core,
  • org.eclipse.ajdt.examples,
  • org.eclipse.ajdt.ui,
  • org.eclipse.contribution.visualiser,
  • org.eclipse.contribution.xref.core,
  • org.eclipse.contribution.xref.ui.

Eclipse will build the projects as you import them. Some projects contain source code for both Eclipse 3.0 and 3.1, so the next step is to ensure the correct build configurations are being used:

  • Expand each of the following projects in the package explorer in turn: org.eclipse.ajdt.core, and org.eclipse.ajdt.ui.
  • Eclipse 3.0: Locate the build30.ajproperties file in each project, then right-click and select "Activate this configuration", if it is not the active configuration already. This will ensure that the 3.0.x versions of all files are being built. If you installed a recent version of AJDT, the build30.ajproperties files should be activated by default.
  • Eclipse 3.1: Locate the build31.ajproperties file in each project, then right-click and select "Activate this configuration", if it is not the active configuration already. This will ensure that the 3.1 versions of all files are being built. If you installed a recent version of AJDT, you will need to activate all of the build31.ajproperties files, because the Eclipse 3.0 versions will be chosen as the default ones.

Now you're ready to run the plugins inside Eclipse:

  • Switch to the Java Perspective if you're not already in it...
  • From the run menu select "Run..."
  • Select "Run-time workbench" (this is called "Eclipse Application" on Eclipse 3.1) and click new
  • Give your launch configuration a name, and click "Run"
  • Subsequent runs can simpy use the launch configuration you just created

Running the correctness tests

The next step is to add the test projects. These can be used to verify that everything is okay with your environment and configuration, plus of course to verify the integrity of any changes you might make. Switch back to the CVS perspective and check-out the following projects:

  • org.eclipse.ajdt.test
  • org.eclipse.contribution.visualiser.tests
  • org.eclipse.contribution.xref.core.test
  • org.eclipse.contribution.xref.ui.test

You can then run all of the tests by expanding the org.eclipse.ajdt.test project, then the testsrc folder, then the org.eclipse.ajdt.test package. Now select the AllTests.java file, right-click and select "Run As" > "JUnit Plug-in Test". A new runtime workbench should then be launched and the tests run inside that. Progress and test results can be observed from the JUnit Eclipse view.

Now you're ready to start enhancing the plugins by adding to or extending the code in your projects - just use run (or debug) to try out your changes. When you have a patch to submit to the project, go to the "Team" item in the project context menu and select "Create Patch...". Naturally the correctness tests should also be run, and new tests written to accompany fixes or new features.

Running the performance tests

Work is underway on a new plugin, org.eclipse.ajdt.tests.performance, to monitor the performance of every build of AJDT. This plugin has dependencies on a number of Eclipse test projects, which are not shipped in the base Eclipse SDK. These instructions will be updated later when the plugin is fully up and running.

Creating an update site

Each of the AJDT plugin projects also contains an Ant build file, "build.xml." The default target builds a packaged version of the project in question. Check-out the "UpdateSite" project from CVS, and use the build.xml file in that project to invoke a master build that builds an entire update site structure in its "dist" directory. To run the build.xml file inside Eclipse, you need to do "Run As > Ant Build..." to bring up the run configuration dialog, then go to the "JRE" tab and select "Run in the same JRE as the workspace". This is required for the "eclipse.incrementalBuild" Ant task to work.

You can now test the built update site as follows:

  • Copy the contents of the dist directory to a clean directory, outside of your workspace. For example, "ajupdate."
  • From the help menu of the Eclipse in which you wish to install the AspectJ feature, choose "Help" > "Software Updates" > "Find and Install..." and follow the steps outlined earlier in this section.

5 Plans

1. What new AJDT features are being worked on at the moment?

See the task list on our project home page.