Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
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 | + | == 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> | + | |
| − | + | === 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 | + | === 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> | + | <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
This page replaces the out-of-date "Equinox Aspects Quick-Start Guide"
Contents
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
- Martin Lippert (2009). What's New in Equinox Aspects. JAX 2009
- James Sugrue (2010). Aspect Oriented Programming for Eclipse Plug-ins. dZone.
- JDT Weaving Features