Adding Support for JaCoCo Agent Configuration Options

This change introduces support for additional configuration options for the
JaCoCo agent, enhancing its flexibility and usability. These changes were
made to be backwards compatible, ensuring that existing configurations
continue to work without modification.

Added optional configuration options:

- destfile
- append
- exclclassloader
- inclbootstrapclasses
- inclnolocationclasses
- sessionid (defaulted to instance uuid)
- dumponexit
- classdumpdir
- jmx

Issue: #1116

Author: billy-briggs-dev

docs/framework-jacoco_agent.md

@@ -21,13 +21,22 @@ Users may optionally provide their own JaCoCo service. A user-provided JaCoCo se
 
 The credential payload of the service may contain the following entries:
 
-| Name | Description
-| ---- | -----------
-| `address` | The host for the agent to connect to or listen on
-| `excludes` | (Optional) A list of class names that should be excluded from execution analysis. The list entries are separated by a colon (:) and may use wildcard characters (* and ?).
-| `includes` | (Optional) A list of class names that should be included in execution analysis. The list entries are separated by a colon (:) and may use wildcard characters (* and ?).
-| `port` | (Optional) The port for the agent to connect to or listen on
-| `output` | (Optional) The mode for the agent. Possible values are either tcpclient (default) or tcpserver. 
+| Name                   | Description
+|------------------------|------------
+| `address`              | The host for the agent to connect to or listen on.
+| `destfile`             | (Optional) The path to the file where execution data is written. Default is `jacoco.exec`.
+| `sessionid`            | (Optional) The identifier for the coverage session. Useful for distinguishing between different test runs.
+| `append`               | (Optional) If set to `true`, coverage data is appended to the existing file. Default is `false`.
+| `includes`             | (Optional) A list of class names to include in execution analysis. Entries are separated by a colon (`:`) and may use wildcards (`*`, `?`).
+| `excludes`             | (Optional) A list of class names to exclude from execution analysis. Entries are separated by a colon (`:`) and may use wildcards (`*`, `?`).
+| `exclclassloader`      | (Optional) A list of class loader names to exclude from instrumentation. Entries are separated by a colon (`:`).
+| `inclbootstrapclasses` | (Optional) If set to `true`, includes bootstrap classes for instrumentation. Default is `false`.
+| `inclnolocationclasses`| (Optional) If set to `true`, includes classes without a location for instrumentation. Default is `false`.
+| `dumponexit`           | (Optional) If set to `true`, coverage data is written on JVM shutdown. Default is `true`.
+| `output`               | (Optional) The mode for the agent. Possible values are `tcpclient` (default) or `tcpserver`.
+| `port`                 | (Optional) The port for the agent to connect to or listen on.
+| `classdumpdir`         | (Optional) The directory where class files are dumped if class dumping is enabled.
+| `jmx`                  | (Optional) If set to `true`, enables JMX control for the agent. Default is `false`.
 
 ## Configuration
 For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].

lib/java_buildpack/framework/jacoco_agent.rb

@@ -32,16 +32,27 @@ def compile
       # (see JavaBuildpack::Component::BaseComponent#release)
       def release
         credentials = @application.services.find_service(FILTER, ADDRESS)['credentials']
+
         properties = {
           'address' => credentials[ADDRESS],
           'output' => 'tcpclient',
           'sessionid' => '$CF_INSTANCE_GUID'
         }
 
-        properties['excludes'] = credentials['excludes'] if credentials.key? 'excludes'
-        properties['includes'] = credentials['includes'] if credentials.key? 'includes'
-        properties['port'] = credentials['port'] if credentials.key? 'port'
-        properties['output'] = credentials['output'] if credentials.key? 'output'
+        # Add SuppPattern match for all other JaCoCo agent options
+        properties['destfile'] = credentials['destfile'] if credentials.key?('destfile')
+        properties['sessionid'] = credentials['sessionid'] if credentials.key?('sessionid')
+        properties['append'] = credentials['append'] if credentials.key?('append')
+        properties['includes'] = credentials['includes'] if credentials.key?('includes')
+        properties['excludes'] = credentials['excludes'] if credentials.key?('excludes')
+        properties['exclclassloader'] = credentials['exclclassloader'] if credentials.key?('exclclassloader')
+        properties['inclbootstrapclasses'] = credentials['inclbootstrapclasses'] if credentials.key?('inclbootstrapclasses')
+        properties['inclnolocationclasses'] = credentials['inclnolocationclasses'] if credentials.key?('inclnolocationclasses')
+        properties['dumponexit'] = credentials['dumponexit'] if credentials.key?('dumponexit')
+        properties['output'] = credentials['output'] if credentials.key?('output')
+        properties['port'] = credentials['port'] if credentials.key?('port')
+        properties['classdumpdir'] = credentials['classdumpdir'] if credentials.key?('classdumpdir')
+        properties['jmx'] = credentials['jmx'] if credentials.key?('jmx')
 
         @droplet.java_opts.add_javaagent_with_props(@droplet.sandbox + 'jacocoagent.jar', properties)
       end

spec/java_buildpack/framework/jacoco_agent_spec.rb

@@ -68,6 +68,32 @@
                                    'excludes=test-excludes,includes=test-includes,port=6300')
     end
 
+    it 'updates JAVA_OPTS with extended options' do
+      allow(services).to receive(:find_service).and_return('credentials' => {
+        'address'               => 'ext-address',
+        'output'                => 'tcpserver',
+        'sessionid'             => 'ext-session',
+        'excludes'              => 'ex.*',
+        'includes'              => 'in.*',
+        'port'                  => 7654,
+        'destfile'              => 'custom.exec',
+        'append'                => 'false',
+        'exclclassloader'       => 'loader.*',
+        'inclbootstrapclasses'  => 'true',
+        'inclnolocationclasses' => 'true',
+        'dumponexit'            => 'false',
+        'classdumpdir'          => 'dumpdir',
+        'jmx'                   => 'true'
+      })
+
+      component.release
+
+      expect(java_opts).to include('-javaagent:$PWD/.java-buildpack/jacoco_agent/jacocoagent.jar=' \
+        'address=ext-address,output=tcpserver,sessionid=ext-session,excludes=ex.*,includes=in.*,port=7654,' \
+        'destfile=custom.exec,append=false,exclclassloader=loader.*,inclbootstrapclasses=true,' \
+        'inclnolocationclasses=true,dumponexit=false,classdumpdir=dumpdir,jmx=true')
+    end
+
   end
 
 end