OTHowtos/BuildTime Weaver

The normal mode of executing OT/J programs employs load-time weaving to integrate teams and roles into their affected base classes. While load-time weaving has the advantage of easier deployment - no tweaking of the classpath is required to ensure that the right version of a class is loaded - it may be difficult to integrate in some application containers. As a fallback mechanism, the OT weaver can be used to process all affected classes already at build-time. The resulting woven classes can then be executed on any JVM (≥1.5) without using the load-time weaver.

objectteams-weaver-maven-plugin

Currently, the built-time weaver only exists as a Maven plugin. If you'd like to use it without Maven, please file a bug

Maven site

http://download.eclipse.org/objectteams/maven/3/sites/objectteams-weaver-maven-plugin

The Usage page already explains the basics, so let's directly go to some examples:

Stopwatch

The stopwatch example has always been the OT/J hello world, so how would this be configured to work without the load-time weaver?

Download

http://download.eclipse.org/objectteams/examples/maven/OTStopwatch_Built-Time_Weaver_Example.zip

Unpack this zip in a fresh directory and inspect the pom.xml:

• parent: configure the project for compiling OT/J code
• properties: select tool versions:
  • tycho is used for integrating the OT/J compiler for Maven
  • OT/J version 2.2.0 corresponds to the Kepler release
• repository: tell maven where to find any Object Teams artifacts and plug-ins
• dependencies: tell maven that we need the OT/J runtime library. In fact only a small portion is needed since we don't use the load-time weaver
• plugin objectteams-weaver-maven-plugin: this is the main configuration item
  • activate goal weave
  • specify which team classes should be processed by the weaver. Additional classes will be automatically pulled in as needed.

For a hello world examples this is all. See the Usage for all configuration options of this plugin.

When you're ready just say:

mvn install

You should see within the maven output:

[INFO] --- objectteams-weaver-maven-plugin:0.8.0-SNAPSHOT:weave (default) @ OTStopwatch_Built-Time_Weaver_Example ---
[INFO] ==== Scanning OT classes ====
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUI.class
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUIAnalog.class
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUI$__OT__WatchDisplay.class
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUIAnalog$__OT__WatchDisplay.class
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUIAnalog$WatchDisplay.class
[INFO] Scanning OT class: org/eclipse/objectteams/example/stopwatch/WatchUI$WatchDisplay.class
[INFO] ==== Weaving teams ====
[INFO] ==== Weaving other classes ====
[INFO] ==== Number of woven classes: 7 ====

If you don't see this please ask in the forum, but gee wiz, I'm probably the wrong person to ask when Maven has a bad day...

After BUILD SUCCESS you may want to have a look into target/woven-classes, where you'll find the result of weaving. If you package the content of this directory, you should be ready to run this OT/J program in every Java environment.

Now, as mentioned, we need to be careful to provide the correct classpath in the correct order. So here is what you could say on Linux:

java -classpath target/woven-classes:\
target/classes:\
${HOME}/.m2/repository/org/eclipse/objectteams/objectteams-runtime/2.2.0/objectteams-runtime-2.2.0.jar \
org.eclipse.objectteams.example.stopwatch.Main

• first entry is target/woven-classes to override non-woven versions
• target/classes is still needed for classes not affected by weaving
• objectteams-runtime-2.2.0 is needed just for a handful of classes like org.objectteams.Team, the ancestor of all team classes

Flight Bonus

Now, let's use a more advanced example to show case a few options of the weaver. For this purpose I've split the omnipresent OTSample-FlightBonus into two maven projects.

Download

http://download.eclipse.org/objectteams/examples/maven/Example-FlightBooking.zip

http://download.eclipse.org/objectteams/examples/maven/Example-FlightBonus.zip

The first project has about the simplest configuration a Java project could have. Run a

mvn install

and we're done with this one.

The configuration of Example-FlightBonus is mostly the same as for the stopwatch example, with these exceptions:

• a dependency on Example-FlightBooking - sure that's the application where we want to add the bonus feature to.
• the configuration of objectteams-weaver-maven-plugin shows two more options:
  • activeTeamClasses: this section lists one of the team classes as active, which means: we want this class to be instantiated and activated at program start, so that it is globally active.
  • mainClass: when we specify one or more activeTeamClasses, we need to tell the weaver, where the program start is, because that's where team instantiation/activation needs to be woven into.

Unfortunately, when you build this project for the first time you may see this:

The type org.eclipse.objectteams.example.fbapplication.BonusGUI$__OT__FlightBonusDialog$RoFi__OT__ cannot be resolved. It is indirectly referenced from required .class files

Please just call mvn install a second time and it should succeed. This is bug 414498 which I hope to fix soon.

For launching this example the command line is a bit longer:

java -classpath target/woven-classes:\
target/classes:\
${HOME}/.m2/repository/org/eclipse/objectteams/objectteams-runtime/2.2.0/objectteams-runtime-2.2.0.jar:\
${HOME}/.m2/repository/org/eclipse/objectteams/Example-FlightBooking/0.8.0-SNAPSHOT/Example-FlightBooking-0.8.0-SNAPSHOT.jar \
org.eclipse.objectteams.example.flightbooking.Main

To test whether the bonus feature is correctly integrated please add a new passenger. At this point you should be asked "Register for Flight Bonus?". If you say "Yes", booking a flight for this particular passenger should be answered by an additional dialog showing the credit points earned so far.

In addition to global team activation, this example also shows, that weaving may affect classes from other artifacts. If you look into target/woven-classes, you'll see a few classes in package .../flightbooking/.... So, searching woven-classes lets you review the extent of weaving.

Weaving into system classes

For a final twist we'll add one more team, which actually modifies the behavior of the JRE class java.awt.Window. For this example I've prepared a second pom, so just say

mvn -f pom2.xml install

Differences

• One more team (WindowPlacer) is listed in teamClasses and activeTeamClasses
• Writing into a different output directory by using the wovenClassDirectory option.

After building, indeed target/woven-classes2 will contain a few more files, most prominently: our own - woven - version of java/awt/Window.class.

Conceptually, there's nothing special to it, but now we have to make sure, that this Window class is used instead of the one from rt.jar. This can be achieved like this:

java -Xbootclasspath/p:target/woven-classes2:\
target/classes:\
${HOME}/.m2/repository/org/eclipse/objectteams/objectteams-runtime/2.2.0/objectteams-runtime-2.2.0.jar:\
${HOME}/.m2/repository/org/eclipse/objectteams/Example-FlightBooking/0.8.0-SNAPSHOT/Example-FlightBooking-0.8.0-SNAPSHOT.jar \
org.eclipse.objectteams.example.flightbooking.Main
 

I'm tempted to say: "don't try this at home", fiddling with the bootclasspath may look scary. If it works, you'll see that automagically all windows are placed neatly in the center of the screen :)

Currently, in this mode you'll have to place your entire application into the bootclasspath, because classes from there cannot see classes from the regular classpath. When using the load-time weaver we have a mechanisms even for this in place and bug 414503 requests to make this available for the build-time weaver as well.

If these examples left some questions unanswered please:

• check the plugin usage, or
• ask in the Object Teams forum