Build Time Enhancement

This topic applies to Java version only 

For build-time enhancement you will need to put the following jars into the lib folder of EnhancementExample project:

pilot.jar supplies Pilot and Id classes presented before

tacustom.jar  provides an annotation-based class filter. Using this jar we can mark the classes that should be enhanced with @Db4oPersistent annotation to filter them from the other classes.

You can use the following script to enhance your classes:

build.xml
001<?xml version="1.0"?> 002 003<!-- 004 TA and NQ build time instrumentation sample. 005--> 006 007<project name="enhance_db4o" default="run-enhanced"> 008 009<!-- The classpath needed for the enhancement process, including the application classpath --> 010<path id="db4o.enhance.path"> 011 <fileset dir="lib"> 012 <include name="**/*.jar"/> 013 </fileset> 014</path> 015 016<!-- Define enhancement tasks (from resource in db4otools.jar). --> 017<typedef 018 resource="instrumentation-def.properties" 019 classpathref="db4o.enhance.path" 020 loaderref="db4o.enhance.loader" /> 021 022<!-- A custom filter that selects classes with the @Db4oPersistent annotation --> 023<typedef 024 name="annotation-filter" 025 classname="tacustom.AnnotationClassFilter" 026 classpathref="db4o.enhance.path" 027 loaderref="db4o.enhance.loader" /> 028 029<!-- Example for a regexp pattern for selecting classes to be instrumented. --> 030<regexp pattern="^enhancement\.model\." id="re.model.only" /> 031 032 033 034<target name="compile"> 035 036 <mkdir dir="${basedir}/bin" /> 037 <delete dir="${basedir}/bin" quiet = "true"> 038 <include name="**/*"/> 039 </delete> 040 041 <javac srcdir="${basedir}/src" destdir="${basedir}/bin" source="1.5" target="1.5"> 042 <classpath refid="db4o.enhance.path" /> 043 </javac> 044 045</target> 046 047 048<target name="enhance" depends="compile"> 049 050 <!-- Prepare the target folders --> 051 <mkdir dir="${basedir}/enhanced-bin" /> 052 <delete dir="${basedir}/enhanced-bin" quiet = "true"> 053 <include name="**/*"/> 054 </delete> 055 <mkdir dir="${basedir}/enhanced-lib" /> 056 <delete dir="${basedir}/enhanced-lib" quiet = "true"> 057 <include name="**/*"/> 058 </delete> 059 060 <db4o-instrument classTargetDir="${basedir}/enhanced-bin" jarTargetDir="${basedir}/enhanced-lib"> 061 062 <classpath refid="db4o.enhance.path" /> 063 <!-- Fileset for original class files to be instrumented --> 064 <sources dir="${basedir}/bin"> 065 <include name="enhancement/**/*.class" /> 066 </sources> 067 <!-- Fileset for original jars to be instrumented --> 068 <jars dir="${basedir}/lib"> 069 <include name="pilot.jar" /> 070 </jars> 071 072 <!-- Instrument Native Query predicates --> 073 <native-query-step /> 074 075 <!-- Instrument TA field access. --> 076 <transparent-activation-step> 077 <!-- Instrument classes that are annotated as @Db4oPersistent. --> 078 <annotation-filter /> 079 <!-- Instrument classes from the specified paths only. --> 080 <regexp refid="re.model.only" /> 081 <regexp pattern="^enhancement\.model\." /> 082 </transparent-activation-step> 083 084 </db4o-instrument> 085 086</target> 087 088 089<target name="run-unenhanced" depends="compile"> 090 091 <java classname="enhancement.EnhancerMain" failonerror="true"> 092 <classpath> 093 <pathelement location="${basedir}/bin" /> 094 <pathelement location="${basedir}/lib/pilot.jar" /> 095 <path refid="db4o.enhance.path" /> 096 </classpath> 097 </java> 098 099</target> 100 101<target name="run-enhanced" depends="enhance"> 102 103 <java classname="enhancement.EnhancerMain" failonerror="true"> 104 <classpath> 105 <pathelement location="${basedir}/enhanced-bin" /> 106 <pathelement location="${basedir}/enhanced-lib/pilot.jar" /> 107 <path refid="db4o.enhance.path" /> 108 </classpath> 109 </java> 110 111</target> 112 113 114</project>

The core part of this script is inside the db4o-instrument task, which is imported by the first typedef instruction. (The second typedef imports the custom annotation class filter.) The classTargetDir and jarTargetDir attributes specify the target folders where instrumented class files and instrumented jar files should be created, respectively.

The nested classpath is just a normal Ant path type and should cover the full application classpath. In the example, we are using one single classpath for task definition and application for convenience - in a real project, these are better kept separate, of course. The nested sources FileSet specifies the location of the class files to be instrumented. Similarly, the jars FileSet specifies the location of jar files to be instrumented. Both are optional (providing neither sources nor jars doesn't make much sense, of course). If one is left out, the corresponding target folder attribute is not required, either.

The remaining nested arguments specify the instrumentation steps to be processed. For Native Query optimization, there is no further configuration - it will simply try to instrument all Predicate implementations. Transparent Activation instrumentation allows to specify more fine-grained filters to select the classes to be instrumented. This can be Ant regular expression types or arbitrary custom ClassFilters. These are OR-ed together and used to further constrain the implicit filter provided by the sources/jars FileSets. In the example, we are constraining TA instrumentation to classes that are either annotated with the @Db4oPersistent annotation, or whose fully qualified name matches the given regexes.

After running the enhance target, the instrumented model classes should appear in the enhanced-bin folder, and an instrumented version of the pilot.jar should have been created in the enhanced-lib folder.

For rather straightforward projects you can alternatively use the db4o-enhance task variant that provides a default setting for joint NQ/TA instrumentation (but doesn't allow fine-grained configuration for the single instrumentation steps in return). This is demonstrated by the following build script for the same sample project.

build-simple.xml
01<?xml version="1.0"?> 02 03<!-- 04 Simple TA and NQ build time instrumentation sample. 05 06 This version uses db4o-enhance instead of db4o-instrument. db4o-enhance provides a default 07 configuration for NQ/TA instrumentation, while db4o-instrument requires to configure 08 (and optionally fine-tune) the single instrumentation steps. Other than that, the 09 configuration options for the two are identical. 10--> 11 12<project name="enhance_db4o" default="run-enhanced"> 13 14<!-- The classpath needed for the enhancement process, including the application classpath --> 15<path id="db4o.enhance.path"> 16 <pathelement path="${basedir}" /> 17 <fileset dir="lib"> 18 <include name="**/*.jar"/> 19 </fileset> 20</path> 21 22<!-- Define enhancement tasks (from resource in db4otools.jar). --> 23<typedef 24 resource="instrumentation-def.properties" 25 classpathref="db4o.enhance.path" /> 26 27 28<target name="compile"> 29 30 <mkdir dir="${basedir}/bin" /> 31 <delete dir="${basedir}/bin" quiet = "true"> 32 <include name="**/*"/> 33 </delete> 34 35 <javac srcdir="${basedir}/src" destdir="${basedir}/bin"> 36 <classpath refid="db4o.enhance.path" /> 37 </javac> 38 39</target> 40 41 42<target name="enhance" depends="compile"> 43 44 <!-- Prepare the target folders --> 45 <mkdir dir="${basedir}/enhanced-bin" /> 46 <delete dir="${basedir}/enhanced-bin" quiet = "true"> 47 <include name="**/*"/> 48 </delete> 49 <mkdir dir="${basedir}/enhanced-lib" /> 50 <delete dir="${basedir}/enhanced-lib" quiet = "true"> 51 <include name="**/*"/> 52 </delete> 53 54 <db4o-enhance classTargetDir="${basedir}/enhanced-bin" jarTargetDir="${basedir}/enhanced-lib"> 55 56 <classpath refid="db4o.enhance.path" /> 57 <!-- Fileset for original class files to be instrumented --> 58 <sources dir="${basedir}/bin" /> 59 <!-- Fileset for original jars to be instrumented --> 60 <jars dir="${basedir}/lib"> 61 <include name="pilot.jar" /> 62 </jars> 63 64 </db4o-enhance> 65 66</target> 67 68 69<target name="run-unenhanced" depends="compile"> 70 71 <java classname="enhancement.EnhancerMain" failonerror="true"> 72 <classpath> 73 <pathelement location="${basedir}/bin" /> 74 <pathelement location="${basedir}/lib/pilot.jar" /> 75 <path refid="db4o.enhance.path" /> 76 </classpath> 77 </java> 78 79</target> 80 81 82<target name="run-enhanced" depends="enhance"> 83 84 <java classname="enhancement.EnhancerMain" failonerror="true"> 85 <classpath> 86 <pathelement location="${basedir}/enhanced-bin" /> 87 <pathelement location="${basedir}/enhanced-lib/pilot.jar" /> 88 <path refid="db4o.enhance.path" /> 89 </classpath> 90 </java> 91 92</target> 93 94 95</project>