Instrumentation

ActiveJDBC requires instrumentation of class files after they are compiled. This is accomplished with an Instrumentation tool provided by the project. There are four ways to use it: with a Maven plugin, Gradle plugin, Ant, and as a standalone Java class (no Ant or Maven)

What is instrumentation?

Instrumentation is byte code manipulation that happens after a compile phase. It adds static methods from super class to a subclass. Instrumentation allows to inherit static methods from a super class, making elegant code like this possible:

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

Without instrumentation, ActiveJDBC would not be able to know which class is being called, and as a result, what table to query.

For instance, in a case of no instrumentation, this call in source code:

Person.where(...);

translates to this logic in bytecode:

Model.where(...);

It is evident, that there is no way to tell what model is executed, and as a result, we cannot map this call to a database table.

While instrumentation introduces an additional step in the process, the benefit is a very intuitive and concise API.

Maven instrumentation plugin

The simple usage of a Maven plugin is provided by a Maven ActiveJDBC Simple Example project: Simple Maven Example. Specifically, the plugin is added to a pom like this:

<plugin>
    <groupId>org.javalite</groupId>
    <artifactId>activejdbc-instrumentation</artifactId>
    <version>${activejdbc.version}</version>
    <executions>
        <execution>
            <phase>process-classes</phase>
            <goals>
                <goal>instrument</goal>
            </goals>
        </execution>
    </executions>
</plugin>

and binds to a process-classes Maven phase. It will automatically instrument model classes during the build.

Video: IntelliJ Idea + Instrumentation

This video clip shows how to do rapid application development with IntelliJ Idea and integrated instrumentation step.

For more, see IntelliJ Integration

Gradle instrumentation plugin

The instrumentation step is also available as a Gradle plugin, an example project can be found here: Gradle Plugin Example.

Add the ActiveJDBC Gradle plugin to your build.gradle file like this:

plugins {
    id "java"
    id "de.schablinski.activejdbc-gradle-plugin" version "1.2"
}

// activejdbc.toolVersion = '2.3'

The plugin will create an instrumentation task and adds it as doLast-action to the compileJava task that is provided by default with the java plugin. The ActiveJDBC plugin property activejdbc.toolVersion tells it which version of ActiveJDBC to use. As of version 1.2 of the plugin, ActiveJDBC 2.3 is the default. It also has been tested with ActiveJDBC 2.0 and 2.2.

Ant instrumentation

Here is an example project with Ant - based instrumentation: Ant exampe

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

<target name="instrument" depends="compile">
    <java classname="org.javalite.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 org.javalite.instrumentation.Main

where:

• $CLASSPATH is your classpath (see the build.xml 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

There is an example of a standalone project which does not use any build tool, except Java itself. Please follow this link for more information: Standalone instrumentation example project

Speed of instrumentation

? is very fast - for large projects (50 - 60 models) it takes about 5 - 7 seconds, and for small projects (under 10 models) usually within a second or two.

Speed of startup

Another aspect of the Instrumentation plugin is that it can be configured to speed up the start of the applicaiton. For more information, see: Runtime Discovery.

Build time classpath

The Instrumentation package is required on the classpath only during instrumentation and not required during runtime. For Maven projects, this is automatic. Even it finds its way to the runtime classpath, it will do no harm except for increasing the size.

Bare bones Ant script

This Ant script can be used on any project in order to speed up development. The reason we use this script sometimes even on Maven projects is speed. Maven takes a few seconds to startup, but this barebones script is almost instant. You can hook it into IDE to trigger before executing tests:

<?xml version="1.0" encoding="UTF-8"?>
<!-- This script is used for fast instrumentation of the project's models-->
<project default="instrument" basedir=".">
    <property name="out.dir" value="target/test-classes"/>
    <path id="instrument_classpath">
        <pathelement location="${out.dir}"/>
        <path location="${user.home}/.m2/repository/org/javalite/activejdbc-instrumentation/2.2/activejdbc-instrumentation-2.2.jar"/>
        <path location="${user.home}/.m2/repository/javassist/javassist/3.8.0.GA/javassist-3.18.2-GA.jar"/>
        <path location="${user.home}/.m2/repository/org/javalite/activejdbc/2.2/activejdbc-2.2.jar"/>
    </path>
    <target name="instrument">
        <java classname="org.javalite.instrumentation.Main">
            <sysproperty key="outputDirectory" value="${out.dir}"/>
            <classpath refid="instrument_classpath"/>
        </java>
    </target>
</project>

Replace versions with the most up-to-date: Maven search for ActiveJDBC

IDE Integrations

• Intellij Idea Integration
• Eclipse Integration
• Netbeans Integration