Equinox Aspects - Quick-start guide

The following steps are intended to help you getting started with Equinox Aspects. Please also take a look at the "Hello world!" demo (from the link for from CVS) which is used as an example at some points.

Setting up your development environment

The following applies to the latest (milestone or development) build of Equinox Aspects which is compatible to Equinox 3.4 and AJDT/AspectJ 1.6.

  1. Install Eclipse 3.4 SDK.
  2. Install the latest version of AJDT form the AJDT update site.
  3. Download the latest build of Equinox Aspects.
  4. Equinox Aspects comes without any tooling, thus there is no need to install it into your development environment (SDK). We strongly recommend to use a custom target platform local to your workspace as described in the next section. But if you prefer to mix your SDK with Equinox Aspects you could extract the downloaded archive into your SDK installation.

Setting up a workspace local target platform

These steps are highly recommended. If you installed Equinox Aspects into your SDK you could skip them.

  1. Create a "general" project (a folder), e.g. org.eclipse.equinox.weaving.demo.target.
  2. Copy all bundles which are required for your application into this target project, e.g. into a bundles directory. For Equinox Aspects the following bundles make up the minimal target:
    • org.eclipse.osgi (The system bundle)
    • org.eclipse.equinox.weaving.hook (Must be co-located with the system bundle!)
    • org.eclipse.equinox.weaving.aspectj
    • org.aspectj.runtime
    • org.aspectj.weaver
    • Optionally: org.eclipse.equinox.weaving.caching
    • Optionally: org.eclipse.equinox.weaving.caching.j9
  3. Create a target definition (File>New>...) in the target project root, e.g. default.target.
  4. On the first tab (Overview) of the target definition editor select the above directory containing your application's bundles as Target Location.
  5. On the second tab (Content) check Include all plug-ins form the specified target.
  6. Set your workspace local target platform by clicking the link Set as Target Platform in the upper right corner of the editor.

If you are planning to support different target platforms, e.g. with different versions of your bundles, you could also apply a version-based naming scheme to the above directory and target definintion.

For the "Hello world!" demo the target project looks like this:

Configuring your aspect bundle

There is nothing special about non-aspect bundles in Equinox Aspects. Your bundles containing aspects however need some special treatment:

  1. Export all packages containing aspects you want to be woven into other bundles, e.g. org.eclipse.equinox.weaving.demo.hello.aspects.
  2. Put your aop.xml file into the META-INF directory or specify a different location using the special Eclipse-AspectContext manifest header.
  3. Use Require-Bundle to declare a dependency on org.aspecj.runtime (AJDT will prompt for that when applying the AspectJ nature: Click OK!) and re-export this dependency.
  4. Use the special manifest header Eclipse-SupplementBundle to declare the target bundles for weaving, e.g. Eclipse-SupplementBundle: org.eclipse.equinox.weaving.demo.hello.

For the "Hello world!" demo the bundle manifest looks like this:

Configuring your runtime

  1. Tell Equinox to use org.eclipse.equinox.weaving.hook as framework extension using the system property osgi.framework.extensions=org.eclipse.equinox.weaving.hook.
  2. The AspectJ weaving service (bundle org.eclipse.equinox.weaving.aspectj) has to be started before any classes are loaded from any bundles targeted for weaving.

For the "Hello world!" demo applying all these steps will result in printing "Hi from HelloAspect ;-)" when the bundle org.eclipse.equinox.weaving.demo.hello is started (after the AspectJ weaving service).

 

Equinox links
Aspects links
Incubation
Incubation