Using JProfiler With Ant

Integrating JProfiler with your ant script (read about ant at ant.apache.org) is easy. Just use the profile task that is provided in {JProfiler installation directory}/bin/ant.jar instead of the java task. The profile task drop in replacement for the the java as it supports all its attributes and nested tasks. In addition, it has a number of additional attributes that govern how the application is profiled.

Note: At least ant 1.6.3 is required for the profile task to work.

To make the profile task available to ant, you must first insert a taskdef element that tells ant where to find the task definition. Here is an example of using the task in an ant build file:

      <taskdef name="profile"
               classname="com.jprofiler.ant.ProfileTask"
               classpath="C:\Program Files\jprofiler10\bin\ant.jar"/>

      <target name="profile">
        <profile classname="MyMainClass" offline="true" sessionid="80">
          <classpath>
            <fileset dir="lib" includes="*.jar" />
          </classpath>
        </profile>
      </target>

The taskdef definition must occur only once per ant-build file and can appear anywhere on the top level below the project element.

Note: it is not possible to copy the ant.jar archive to the lib folder of your ant distribution. You have to reference a full installation of JProfiler in the task definition.

Besides the attributes of the java task, the profile task supports the following additional attributes:

Attribute	Description	Required
offline	Whether the profiling run should be in offline mode. Corresponds to the offline library parameter. Either `true` or `false`.	No, offline and nowait cannot both be `true`
nowait	Whether profiling should start immediately or whether the profiled JVM should wait for a connection from the JProfiler GUI. Corresponds to the nowait library parameter. Either `true` or `false`.	No, offline and nowait cannot both be `true`
sessionid	Defines the session id from which profiling settings should be taken. Has no effect if neither nowait nor offline are set because in that case the profiling session is selected in the GUI. Corresponds to the id library parameter.	Required if offline is set nowait is set and the profiled JVM has a version of 1.5 or earlier
configfile	Defines the config file from which the profiling settings should be read. If not set or empty, the default config file location will be taken ($HOME/.jprofiler10/config.xml). Has no effect if neither nowait nor offline are set because in that case the profiling session is selected in the GUI. Corresponds to the config library parameter.	No
port	Defines the port number on which the profiling agent should listen for a connection from the JProfiler GUI. This must be the same as the port configured in the remote session configuration. If not set or zero, the default port (8849) will be used. Has no effect if offline is set because in that case there's no connection from the GUI. Corresponds to the port library parameter.	No

If the generated snapshots have heap dumps in them, you can then use the analyze ant task to prepare the heap dump analysis in advance. This is an alternative to calling the jpanalyze executable directly as described for offline profiling.

Here is an example of using the task in an ant build file:

      <taskdef name="analyze"
               classname="com.jprofiler.ant.AnalyzeTask"
               classpath="C:\Program Files\jprofiler10\bin\ant.jar"/>

      <target name="analyze">
        <analyze>
          <fileset dir="output" includes="*.jps" />
        </analyze>
      </target>

This will prepare heap dump analyses for all snapshot files in the "output" directory.

Besides the file set for the snapshot files to by analyzed, the analyze task supports the following additional attributes:

Attribute	Description	Required
obfuscator	Deobfuscate class and method names for the selected obfuscator. Defaults to "none", for other values the \"mappingfile\" option has to be specified. One of `none`, `proguard` or `yguard`.	No
mappingfile	The mapping file for the selected obfuscator. May only be set if the "obfuscator" attribute is specified.	Only if "obfuscator" is specified
removeunreferenced	Corresponds to the "Perform full GC in heap dump" option in the heap walker options dialog. Either `true` or `false`.	No
retainsoft	Corresponds to the "Retain objects held by soft references" option in the heap walker options dialog. Either `true` or `false`.	No
retainweak	Corresponds to the "Retain objects held by weak references" option in the heap walker options dialog. Either `true` or `false`.	No
retainphantom	Corresponds to the "Retain objects held by phantom references" option in the heap walker options dialog. Either `true` or `false`.	No
retainfinalizer	Corresponds to the "Retain objects held by finalizer references" option in the heap walker options dialog. Either `true` or `false`.	No
retained	Corresponds to the "Calculate retained sizes" option in the heap walker options dialog. Either `true` or `false`. If set to `true`, `removeunreferenced` will be set to to `true` as well.	No