Jump to: navigation, search

Difference between revisions of "Equinox Weaving QuickStart"

(Cobbled together a brief how-to)
(More changes)
Line 1: Line 1:
 
{{note | This page replaces the out-of-date [http://www.eclipse.org/equinox/incubator/aspects/equinox-aspects-quick-start.php "Equinox Aspects Quick-Start Guide"]}}
 
{{note | This page replaces the out-of-date [http://www.eclipse.org/equinox/incubator/aspects/equinox-aspects-quick-start.php "Equinox Aspects Quick-Start Guide"]}}
  
As of Eclipse Juno (for 2012), these are the steps to enable Equinox Weaving with AspectJ, as cribbed together from various sources.  Note that the <tt>aop.xml</tt> file is no longer necessary.
+
== Enabling Weaving for Plug-Ins with AspectJ  ==
 +
 
 +
As of Eclipse Juno, these are the steps required to enable Equinox Weaving with AspectJ.  Note that the <tt>aop.xml</tt> file is no longer necessary.
  
 
*Install the AspectJ Development Tooling (AJDT) and Equinox Weaving from the [http://eclipse.org/ajdt/downloads/ AJDT Downloads].  
 
*Install the AspectJ Development Tooling (AJDT) and Equinox Weaving from the [http://eclipse.org/ajdt/downloads/ AJDT Downloads].  
Line 7: Line 9:
 
*Configure your bundle's MANIFEST.MF to (i) export its aspects, and (ii) specify the bundles that its aspects advise. The former is done by adding a parameter on the <tt>Export-Package</tt> header. The latter is done through the <tt>Eclipse-SupplementBundle</tt> header. For example, a bundle with an aspect swing.edt.EdtRuleChecker, advising bundles com.example.core and com.example.ui would specify:
 
*Configure your bundle's MANIFEST.MF to (i) export its aspects, and (ii) specify the bundles that its aspects advise. The former is done by adding a parameter on the <tt>Export-Package</tt> header. The latter is done through the <tt>Eclipse-SupplementBundle</tt> header. For example, a bundle with an aspect swing.edt.EdtRuleChecker, advising bundles com.example.core and com.example.ui would specify:
 
<pre>Export-Package: swing.edt;aspects="EdtRuleChecker"
 
<pre>Export-Package: swing.edt;aspects="EdtRuleChecker"
Eclipse-SupplementBundle: com.example.core,com.example.ui
+
Eclipse-SupplementBundle: com.example.core, com.example.ui</pre>  
</pre>  
+
 
*Add the following bundles to your launch configuration  
 
*Add the following bundles to your launch configuration  
 
**org.aspectj.weaver  
 
**org.aspectj.weaver  
Line 15: Line 16:
 
**org.eclipse.equinox.weaving.hook  
 
**org.eclipse.equinox.weaving.hook  
 
*Ensure org.eclipse.equinox.weaving.aspectj is auto-started at, say, level 2  
 
*Ensure org.eclipse.equinox.weaving.aspectj is auto-started at, say, level 2  
*Add the following VM argument to instruct OSGi to load the weaving hooks:
+
*Add the following VM argument (or to your <tt>config.ini</tt>) to instruct OSGi to load the weaving hooks:
<pre>-Dosgi.framework.extensions=org.eclipse.equinox.weaving.hook
+
<pre>-Dosgi.framework.extensions=org.eclipse.equinox.weaving.hook</pre>  
</pre>  
+
  
Basically, <em>Eclipse-BundleSupplement</em> effectively causes the specified bundles to import the packages that are exported by the aspects bundle.
+
=== Control How Aspects are Applied with 'aspect-policy' ===
  
 
Aspects can be defined as opt-in (bundles have to explicitly ask for the aspects to be installed) or opt-out (bundles must explicitly opt-out from weaving).  Opt-out is the default policy.  For example, to change the policy to opt-in:
 
Aspects can be defined as opt-in (bundles have to explicitly ask for the aspects to be installed) or opt-out (bundles must explicitly opt-out from weaving).  Opt-out is the default policy.  For example, to change the policy to opt-in:
Line 26: Line 26:
 
</pre>
 
</pre>
  
A bundle can explicitly accept or forbid aspects through the <tt>apply-aspects</tt> parameter on <tt>Import-Package</tt>:
+
=== Control How Aspects are Received with 'apply-aspects' ===
 +
 
 +
A bundle can explicitly request or forbid aspects being applied to it through the <tt>apply-aspects</tt> parameter on <tt>Import-Package</tt>:
 
<pre>
 
<pre>
 
Import-Package: swing.debug; apply-aspects:=false
 
Import-Package: swing.debug; apply-aspects:=false
 
</pre>
 
</pre>
<tt>true</tt> indicates that aspects should be woven into the bundle (the default), whereas <tt>false</tt> indicates that aspects should not be applied.  These parameters override any supplying bundle's <tt>aspect-policy</tt>.
+
<tt>apply-aspects</tt> defaults to <tt>true</tt>, indicating that aspects should be woven into the bundle, whereas <tt>false</tt> indicates that aspects should not be applied.  These parameters override the supplying bundle's <tt>aspect-policy</tt>.
 +
 
 +
The <em>Eclipse-BundleSupplement</em> in effect causes the specified bundles to include <tt>Import-Package: ...; apply-aspects:=true</tt> for the packages that are exported by the aspects bundle.
 +
 
 +
 
 +
=== Debugging ===
  
 
For debugging output, add the following VM arguments:  
 
For debugging output, add the following VM arguments:  
Line 40: Line 47:
 
== Sources ==
 
== Sources ==
  
* Martin Lippert (2009). [http://www.martinlippert.org/events/JAX2009-WhatsNewInEquinoxAspects.pdf What's New in Equinox Aspects]
+
* Martin Lippert (2009). [http://www.martinlippert.org/events/JAX2009-WhatsNewInEquinoxAspects.pdf What's New in Equinox Aspects]. JAX 2009
* James Sugrue (2010). [http://java.dzone.com/articles/aspect-oriented-programming Aspect Oriented Programming for Eclipse Plug-ins]
+
* James Sugrue (2010). [http://java.dzone.com/articles/aspect-oriented-programming Aspect Oriented Programming for Eclipse Plug-ins]. dZone.
 
* [[JDT_weaving_features | JDT Weaving Features]]
 
* [[JDT_weaving_features | JDT Weaving Features]]
  

Revision as of 16:23, 21 December 2011

Note.png
This page replaces the out-of-date "Equinox Aspects Quick-Start Guide"


Enabling Weaving for Plug-Ins with AspectJ

As of Eclipse Juno, these are the steps required to enable Equinox Weaving with AspectJ. Note that the aop.xml file is no longer necessary.

  • Install the AspectJ Development Tooling (AJDT) and Equinox Weaving from the AJDT Downloads.
  • Define your aspect(s) in a bundle.
  • Configure your bundle's MANIFEST.MF to (i) export its aspects, and (ii) specify the bundles that its aspects advise. The former is done by adding a parameter on the Export-Package header. The latter is done through the Eclipse-SupplementBundle header. For example, a bundle with an aspect swing.edt.EdtRuleChecker, advising bundles com.example.core and com.example.ui would specify:
Export-Package: swing.edt;aspects="EdtRuleChecker"
Eclipse-SupplementBundle: com.example.core, com.example.ui
  • Add the following bundles to your launch configuration
    • org.aspectj.weaver
    • org.eclipse.equinox.weaving.aspectj
    • org.eclipse.equinox.weaving.caching
    • org.eclipse.equinox.weaving.hook
  • Ensure org.eclipse.equinox.weaving.aspectj is auto-started at, say, level 2
  • Add the following VM argument (or to your config.ini) to instruct OSGi to load the weaving hooks:
-Dosgi.framework.extensions=org.eclipse.equinox.weaving.hook

Control How Aspects are Applied with 'aspect-policy'

Aspects can be defined as opt-in (bundles have to explicitly ask for the aspects to be installed) or opt-out (bundles must explicitly opt-out from weaving). Opt-out is the default policy. For example, to change the policy to opt-in:

Export-Package: swing.debug; aspects="EdtRuleChecker"; aspect-policy:=opt-in

Control How Aspects are Received with 'apply-aspects'

A bundle can explicitly request or forbid aspects being applied to it through the apply-aspects parameter on Import-Package:

Import-Package: swing.debug; apply-aspects:=false

apply-aspects defaults to true, indicating that aspects should be woven into the bundle, whereas false indicates that aspects should not be applied. These parameters override the supplying bundle's aspect-policy.

The Eclipse-BundleSupplement in effect causes the specified bundles to include Import-Package: ...; apply-aspects:=true for the packages that are exported by the aspects bundle.


Debugging

For debugging output, add the following VM arguments:

-Daj.weaving.verbose=true
-Dorg.aspectj.weaver.showWeaveInfo=true
-Dorg.aspectj.osgi.verbose=true

Sources