AspectJ-enabled Eclipse Runtime Readme

Release Candidate for Eclipse 3.0 m9 - May 23rd, 2004.

Installation

After you have installed the feature via the update site you need to start Eclipse with a number of additional startup parameters to enable the load-time weaving of aspects. The startup options are:

-Xmx512m: the runtime needs a significant amount of memory. This sets the maximum heap size of the VM running eclipse.
-Dosgi.adaptor=org.eclipse.osgi.service.bytecodetransformer.TransformerAdaptor: This option tells the eclipse runtime to use a specialized adaptor to allow load-time bytecode modification.
-Dosgi.frameworkClassPath="core.jar, console.jar, osgi.jar, resolver.jar, defaultAdaptor.jar, eclipseAdaptor.jar, ../org.eclipse.transformer_1.0.0/transformer.jar": With this option you allow the runtime to find the class for the specialized adaptor that you specified in the option above.
-Dosgi.bundles="org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start, org.eclipse.transformer@4, org.aspectj.weavingruntime@5": With this option you tell the runtime to start the load-time weaving directly at startup.
-Dosgi.bundles.defaultStartLevel=5: This option tells the runtime to start the above mentioned bundles at startup.

The easiest way is to write a simple startup script that does this for you.
Important:The first time you start your Eclipse installation with these startup options you need a fresh configuration directory. To get this just delete the configuration directory.

Contributing Aspects

Lets assume you want to write a plugin that should promote an aspect to the load-time weaving runtime. You need to do the following steps:

write your plugin as a normal plugin project using the PDE.
convert your plugin project into an AJDT project and develop your aspect.
promote your aspect with an extension to the aspects extension point of the weaving runtime.
define a bundle manifest for your plugin and export the package of your aspect.
start a runtime workbench.

1. Write your plugin as a normal plugin project using the PDE

Create a plugin project as usual with the PDE support of eclipse. Do everything as usual with your plugin.

2. Convert your plugin project into an AJDT project and develop your aspect

If you have AJDT installed you can convert your plugin project into an AspectJ project by choosing the action from the context menu of the plugin. After that you can develop your aspects inside your plugin. AJDT takes care of compiling the aspect etc.

3. Promote your aspect with an extension to the aspects extension point of the weaving runtime

If you want to promote your aspect to let the runtime weave your aspect into all possible plugins that are used you can use the typical eclipse mechanism of extension and extension point. The weaving runtime defines an extension point calls "org.aspectj.weavingruntime.aspects". To extent this point you have to define the weavingruntime as a required plugin (in your plugin.xml). Then you can define an extension to this point to promote your aspect to the runtime. If you create the extension with the PDE plugin manifest editor, the editor will tell you what you need to do. The final extension in the plugin.xml source code might look like:

   <extension

            
    point="org.aspectj.weavingruntime.aspects">

          <aspect

               
    class="org.myplugin.mypackage.MyAspect">

          </aspect>

       </extension>

Within the class attribute you should define the full qualified class name of the aspect.

4. Define a bundle manifest for your plugin and export the package of your aspect

The new runtime of Eclipse in version 3,0 is based on the OSGi framework. The weaving runtime makes use of this new runtime framework to allow aspects to be woven into other plugins at load-time. Therefore you need to write an OSGi-specific manifest.mf file. Create a folder META-INF in your plugin directory. Then create a MANIFEST.MF file in this folder (you can also let the plugin creating wizard generate this one for you when you create a new plugin project). The MANIFEST.MF file will contain all the dependency information for your plugin. Therefore you need to add the required plugin information that are included in your plugin.xml to the MANIFEST.MF file in a specific format. After you did this, you need to take care of the MANIFEST.MF file for yourself. The PDE does not support you in updating the MANIFEST.MF file if you change the plugin.xml. The MANIFEST.MF file might look like this:

Bundle-Name: org.myplugin

    Bundle-Version: 1.0.0

    Bundle-SymbolicName: org.myplugin

    Bundle-ClassPath: myplugin.jar

    Require-Bundle: 

     org.junit,

     org.aspectj.weavingruntime

    Export-Package: 

     org.myplugin.mypackage

The bundle header are very similar to the headers in the plugin.xml file. The Require-Bundle tag defines the required bundles (similar to the require tag in the plugin.xml). (Note that you need to write a <space> at the end of a line if the tag continues in the next line.)
The Export-Package tag is new: With this tag you need to export the package that defines the aspect you are going to promote.

The handling of the MANIFEST.MF file is somewhat rough at the moment. I hope that the PDE will support this new runtime feature in the near future. That would make it a lot easier to maintain this file.

5. Start a runtime workbench

Now we want to start a runtime workbench to check if the plugin and the promoted aspect works. You can start a runtime workbench with the same launch configuration as you would do without aspects. The only thing you need to add to the launch configuration are similar startup parameters as we used to start eclipse.

Add to the VM parameters: -Xmx512m -Dosgi.adaptor=org.eclipse.osgi.service.bytecodetransformer.TransformerAdaptor -Dosgi.bundles.defaultStartLevel=5
Change the classpath entries to: bin, ../org.eclipse.transformer_1.0.0/transformer.jar
Add to entries to the configuration list (on the configuration tab): org.eclipse.transformer with start level 4 and org.aspectj.weavingruntime with startlevel 5.

Running with cached woven files

If you are using the load-time weaving of aspects within an production environment you might not want to do the load-time weaving every time your applications starts. Therefore the AspectJ-enabled Eclipse Runtime is able to use a cache for load-time woven classes.

The cache thst is build into the AspectJ-enabled runtime is able to recognize if the configuration of your system has changed. If, for example, an aspect is added, removedor changed to the set of plugins you are running the cache will automatically be disabled. But if you are starting your application with the same setting as before the cache will load classes from the cache to improve startup time dramatically.

You can also use the cache while you are in the development mode. But you have to keep in mind that the cache uses the version number of an aspect to find out whether the aspect itself has changed or not. Therefore if you change the aspect without changing the version number the cache will not recognize your change to the aspect and will load cached classes. Therefore it is recommended to not use the cache while you are developing aspects.

To enable the cache just use the application parameter -enableBTC at startup.

Help

If you need any help with the weaving runtime, any kind of feedback or any ideas for improvement please do not hesitate to contact me: lippert@acm.org