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:
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.
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>