ActiveJDBC – as ORM : Instrumentation

• Instrumentation in ActiveJDBC

Instrumentation Intro

• ActiveJDBC requires instrumentation of class files after they are compiled.
• This is accomplished with an Instrumentation package provided by the project.
• There are three ways to use it:
  • with a Maven plugin,
  • Ant, and
  • as a standalone Java class (in case you have a non-Maven project)

What is instrumentation?

• Instrumentation is byte code manipulation that happens after compile phase.
• It adds static methods from super class to a subclass.
• Instrumentation makes writing code like this possible:

 
 List<Person> retirees = Person.where("age >= ?", 65); 

• Without instrumentation, AJ would not be able to know what table to query.
• This is one reason why other Java ORM APIs are clunky and require a third party class, such as PersistentManager (JPA), Session (Hibernate), etc.
• While instrumentation introduces an additional step in the process, the benefit is a very intuitive and concise API.

Maven instrumentation plugin

For Maven

<plugin>
<groupId>activejdbc</groupId>
<artifactId>activejdbc-instrumentation</artifactId>
<version>1.4.1</version>
<executions>
<execution>
<phase>process-classes</phase>
<goals>
<goal>instrument</goal>
</goals>
</execution>
</executions>
</plugin>

Ant instrumentation

The class responsible for instrumentation is called activejdbc.instrumentation.Main, and here is an example of using it:

For Ant

<target name="instrument" depends="compile">
<java classname="activejdbc.instrumentation.Main">
<sysproperty key="outputDirectory" value="${classes}"/>
<classpath refid="build_classpath"/>
</java>
</target> 

where ${classes} represents a directory where class files were compiled.

Standalone instrumentation

If you are not using Maven or Ant, you can run instrumentation with a command similar to this:

java  -cp=$CLASSPATH  -DoutputDirectory=build  activejdbc.instrumentation.Main 

where:  
-$CLASSPATH is your classpath in the Ant example above for things you will need to have on the classspath.  
-build - is a directory where you compiled all classes in a "compile" step before instrumentation