For a long time bytecode weaving in OSGi has been a cumbersome process. Using it's internal hooks Equinox has supported basic transformation since version 3.2, but there has still been no simple, standard way to enhance classes and add new dependencies to the bundle that contains them. The new OSGi WeavingHook whiteboard pattern, which allows any OSGi bundle, not just an Equinox framework extension, to weave classes from, and add dependencies to, other OSGi bundles. Also new in OSGi is the opportunity to scan the classpath of an OSGi bundle. Whilst the isolated, modular classpath of an OSGi bundle provides an excellent system for building Java applications, many extenders and libraries need to be able to search for classes or resources within the bundle. This function further aids weaving implementations by allowing them to search for resources, class and package name patterns, and other configuration without requiring specific metadata to be present. As the lead author for the Bytecode weaving design within the OSGi Alliance, and a committer in the Apache Aries project, Tim will use his expertise to demonstrate the power and flexibility of WeavingHooks, particularly in conjunction with the latest OSGi updates for classpath scanning. Drawing on real-world examples from the Apache Aries project Tim will use real-world examples to prove that first-class weaving support is now available in OSGi.

1. OSGi-friendly bytecode weaving –
Enhance your classes, not your dependency graph!
Tim Ward
IBM
21 Sep 2011
OSGi Alliance Marketing © 2008-2010 . 1
Page
COPYRIGHT © 2008-2011 OSGi Alliance. All Rights Reserved, © IBM Corp. 2011
All Rights Reserved

2. Legal
• Java and all Java-based trademarks and logos are trademarks
or registered trademarks of Oracle and/or its affiliates.
• OSGi and the OSGi logo are trademarks or registered
trademarks of the OSGi Alliance
• Other product and service names might be trademarks of IBM
or other companies. A current list of IBM trademarks is
available on the Web at “Copyright and trademark information”
at www.ibm.com/legal/copytrade.shtml
Page 2 OSGi Alliance Marketing © 2008-2011 . All Rights Reserved,
© IBM Corp. 2011

3. What we're going to cover
What weaving is
How weaving is done in Java SE (10,000 foot view)
Why OSGi needs a different approach
How to use OSGi weaving hooks
How to do classpath scanning in OSGi
A real world demo using classpath scanning and weaving
Page 3 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

4. What is bytecode weaving?
Simply put, bytecode weaving involves generating or editing
code by directly modifying existing .class files
This can occur at different points in the application lifecycle
• At compile time
Outside a VM
• At packaging time
• At class load time
Inside a VM
• After a class has been loaded
Weaving later is more flexible (to a point)
Page 4 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

5. How do we normally weave bytecode?
In Java 1.4 you had to create your own ClassLoader and
mess about with the class bytes before defineClass()
Java 5 introduced Java Agents and a defined
transformation API (java.lang.instrument)
• ClassFileTransformers registered on a VM wide basis
Java 6 supports re-transformation (post class load) and
addition of Java Agents to a running VM
In all cases we get an opportunity to read/change the bytes
of the class file before they are loaded into the VM
Page 5 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

6. Why do we need a Weaving Hook?
Clearly the base VM support exists already but...
OSGi is modular
• Java Agent Class transformation is VM wide
OSGi has a ClassLoader graph, not a flat classpath
• Weaving often adds new dependencies to a class
• New dependencies cannot be loaded without being
imported by the bundle hosting the woven class
Page 6 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

7. How to use a Weaving Hook
This is very simple!
Bundle
Register your implementation as a
WeavingHook
service using the
org.osgi.framework.hooks.weaving.
WeavingHook interface
The framework will call your hook for every class loaded
by any bundle
• If security is on then you need AdminPermission
WEAVE to make any changes for a given bundle
Page 7 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

8. How to use a Weaving Hook (2)
You only implement a single method
• public void weave(WovenClass classInfo)
The WovenClass provides access to:
• The Bundle defining the class
• Read/Replace the class bytes that will be used
• The BundleWiring and Bundle ClassLoader
• A List of dynamic package imports to add, this allows
us to add new dependencies based on what we weave!
Page 8 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

9. Working out what to weave
Most weavers use XML and annotations to configure which
classes should be woven and what to do to them
• Annotations mean we need access to the class
• We don't know the name of the class
In Java SE we tend to rely on searching the file system to
find class files to load on the classpath
• OSGi does not (in general) let you do this
Page 9 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

10. Scanning the bundle Classpath
The BundleWiring API adds a new method
• public Collection<String> listResources( String path,
String filePattern, int options )
This method lets us scan for resources on the classpath
• path can be used to specify a package folder
• filePattern lets you specify a type (e.g. *.class)
• options lets you specify whether to recurse into sub-
packages, and whether to include resources that are
imported from other bundles
Page 10 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

11. Combining the two specifications
There are two options for scanning
• Up front
• When the WeavingHook is called
The BundleWiring is accessible from the Bundle object
using the adapt method
• bundle.adapt(BundleWiring.class);
The BundleWiring is also available from the WovenClass
• wovenClass.getBundleWiring();
Page 11 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

12. Live demo!
The Apache Aries JPA container uses both scanning and a
Weaving Hook to provide load-time entity enhancement
• The function is pretty new, but a release is due in the
next few weeks
Using a debugger we can see the various pieces in action!
Page 12 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011

13. Any Questions?
Apache Aries: http://aries.apache.org/
Tim Ward: @TimothyWard timothyjward@apache.org
OSGi and JPA on YouTube:
http://www.youtube.com/user/EnterpriseOSGi
For more information on Enterprise OSGi take a look at
Enterprise OSGi in Action :
http://www.manning.com/cummins
Page 13 OSGi Alliance Community Event 2011© 2008-2011. All Rights Reserved,
© IBM Corp. 2011