JaCoCo Agent Support

nebhale · nebhale · commit 763d051b604f · 2018-02-16T08:19:22.000-08:00
This change updates the buildpack to include JaCoCo agent support. [resolves cloudfoundry#529]
diff --git a/.idea/dictionaries/bhale.xml b/.idea/dictionaries/bhale.xml
diff --git a/README.md b/README.md
@@ -84,6 +84,7 @@ The buildpack supports extension through the use of Git repository forking. The
   * [Dynatrace SaaS/Managed OneAgent](docs/framework-dynatrace_one_agent.md) ([Configuration](docs/framework-dynatrace_one_agent.md#configuration))
   * [Google Stackdriver Debugger](docs/framework-google_stackdriver_debugger.md) ([Configuration](docs/framework-google_stackdriver_debugger.md#configuration))
   * [Introscope Agent](docs/framework-introscope_agent.md) ([Configuration](docs/framework-introscope_agent.md#configuration))
+  * [JaCoCo Agent](docs/framework-jacoco_agent.md) ([Configuration](docs/framework-jacoco_agent.md#configuration))
   * [Java Memory Assistant](docs/framework-java_memory_assistant.md) ([Configuration](docs/framework-java_memory_assistant.md#configuration))
   * [Java Options](docs/framework-java_opts.md) ([Configuration](docs/framework-java_opts.md#configuration))
   * [JRebel Agent](docs/framework-jrebel_agent.md) ([Configuration](docs/framework-jrebel_agent.md#configuration))
diff --git a/config/components.yml b/config/components.yml
@@ -51,6 +51,7 @@ frameworks:
   - "JavaBuildpack::Framework::DynatraceOneAgent"
   - "JavaBuildpack::Framework::GoogleStackdriverDebugger"
   - "JavaBuildpack::Framework::IntroscopeAgent"
+  - "JavaBuildpack::Framework::JacocoAgent"
   - "JavaBuildpack::Framework::JavaMemoryAssistant"
   - "JavaBuildpack::Framework::Jmx"
   - "JavaBuildpack::Framework::JrebelAgent"
diff --git a/config/jacoco_agent.yml b/config/jacoco_agent.yml
@@ -0,0 +1,19 @@
+# Cloud Foundry Java Buildpack
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Configuration for the JaCoco Agent framework
+---
+version: 0.+
+repository_root: "{default.repository.root}/jacoco"
diff --git a/docs/framework-jacoco_agent.md b/docs/framework-jacoco_agent.md
@@ -0,0 +1,49 @@
+# JaCoco Agent Framework
+The JaCoCo Agent Framework causes an application to be automatically configured to work with a bound [JaCoCo Service][].
+
+<table>
+  <tr>
+    <td><strong>Detection Criterion</strong></td><td>Existence of a single bound JaCoCo service.
+      <ul>
+        <li>Existence of a JaCoCo service is defined as the <a href="http://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES"><code>VCAP_SERVICES</code></a> payload containing a service who's name, label or tag has <code>jacoco</code> as a substring.</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td><strong>Tags</strong></td>
+    <td><tt>jacoco-agent=&lt;version&gt;</tt></td>
+  </tr>
+</table>
+Tags are printed to standard output by the buildpack detect script
+
+## User-Provided Service (Optional)
+Users may optionally provide their own JaCoCo service. A user-provided JaCoCo service must have a name or tag with `jacoco` in it so that the JaCoCo Agent Framework will automatically configure the application to work with the service.
+
+The credential payload of the service may contain the following entries:
+
+| Name | Description
+| ---- | -----------
+| `address` | The host for the agent to connect to
+| `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
+
+## Configuration
+For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
+
+The framework can be configured by modifying the [`config/jacoc_agent.yml`][] file in the buildpack fork.  The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
+
+| Name | Description
+| ---- | -----------
+| `repository_root` | The URL of the JaCoCo repository index ([details][repositories]).
+| `version` | The version of JaCoCo to use. Candidate versions can be found in [this listing][].
+
+### Additional Resources
+The framework can also be configured by overlaying a set of resources on the default distribution.  To do this, add files to the `resources/jacoco_agent` directory in the buildpack fork.  For example, to override the default `jacoco.yml` add your custom file to `resources/jacoco_agent/jacoco.yml`.
+
+[Configuration and Extension]: ../README.md#configuration-and-extension
+[`config/jacoco_agent.yml`]: ../config/jacoco_agent.yml
+[JaCoCo Service]: http://www.jacoco.org/jacoco/
+[repositories]: extending-repositories.md
+[this listing]: https://java-buildpack.cloudfoundry.org/jacoco/index.yml
+[version syntax]: extending-repositories.md#version-syntax-and-ordering
diff --git a/lib/java_buildpack/component/java_opts.rb b/lib/java_buildpack/component/java_opts.rb
@@ -43,11 +43,21 @@ def add_javaagent(path)
         add_preformatted_options "-javaagent:#{qualify_path path}"
       end
 
+      # Adds a +javaagent+ entry to the +JAVA_OPTS+. Prepends +$PWD+ to the path (relative to the droplet root) to
+      # ensure that the path is always accurate.
+      #
+      # @param [Pathname] path the path to the +javaagent+ JAR
+      # @param [Properties] props to append to the +javaagent+ entry
+      # @return [JavaOpts]     +self+ for chaining
+      def add_javaagent_with_props(path, props)
+        add_preformatted_options "-javaagent:#{qualify_path path}=" + props.map { |k, v| "#{k}=#{v}" }.join(',')
+      end
+
       # Adds a +agentpath+ entry to the +JAVA_OPTS+.  Prepends +$PWD+ to the path (relative to the droplet root) to
       # ensure that the path is always accurate.
       #
       # @param [Pathname] path the path to the +agentpath+ shared library
-      # @param [Properties] props to append to the agentpath entry
+      # @param [Properties] props to append to the +agentpath+ entry
       # @return [JavaOpts]     +self+ for chaining
       def add_agentpath_with_props(path, props)
         add_preformatted_options "-agentpath:#{qualify_path path}=" + props.map { |k, v| "#{k}=#{v}" }.join(',')
diff --git a/lib/java_buildpack/framework/jacoco_agent.rb b/lib/java_buildpack/framework/jacoco_agent.rb
@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Cloud Foundry Java Buildpack
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'java_buildpack/component/versioned_dependency_component'
+require 'java_buildpack/framework'
+
+module JavaBuildpack
+  module Framework
+
+    # Encapsulates the functionality for enabling zero-touch JacCoCo support.
+    class JacocoAgent < JavaBuildpack::Component::VersionedDependencyComponent
+
+      # (see JavaBuildpack::Component::BaseComponent#compile)
+      def compile
+        download_zip false
+      end
+
+      # (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'
+
+        @droplet.java_opts.add_javaagent_with_props(@droplet.sandbox + 'jacocoagent.jar', properties)
+      end
+
+      protected
+
+      # (see JavaBuildpack::Component::VersionedDependencyComponent#supports?)
+      def supports?
+        @application.services.one_service? FILTER, ADDRESS
+      end
+
+      ADDRESS = 'address'
+
+      FILTER = /jacoco/
+
+      private_constant :ADDRESS, :FILTER
+
+    end
+
+  end
+end
diff --git a/rakelib/versions_task.rb b/rakelib/versions_task.rb
@@ -66,6 +66,7 @@ def initialize
       'google_stackdriver_debugger'         => 'Google Stackdriver Debugger',
       'groovy'                              => 'Groovy',
       'introscope_agent'                    => 'CA Introscope APM Framework',
+      'jacoco_agent'                        => 'JaCoCo Agent',
       'jre'                                 => 'OpenJDK JRE',
       'jrebel_agent'                        => 'JRebel Agent',
       'jvmkill_agent'                       => 'jvmkill Agent',
diff --git a/spec/fixtures/stub-jacoco-agent.jar b/spec/fixtures/stub-jacoco-agent.jar
diff --git a/spec/java_buildpack/component/java_opts_spec.rb b/spec/java_buildpack/component/java_opts_spec.rb
@@ -30,6 +30,12 @@
     expect(opts).to include('-javaagent:$PWD/.java-buildpack/java_opts/test-java-agent')
   end
 
+  it 'adds a qualified javaagent with properties to the collection' do
+    opts.add_javaagent_with_props(droplet.sandbox + 'test-java-agent', 'key1' => 'value1', 'key2' => 'value2')
+
+    expect(opts).to include('-javaagent:$PWD/.java-buildpack/java_opts/test-java-agent=key1=value1,key2=value2')
+  end
+
   it 'adds a qualified agentpath to the collection' do
     opts.add_agentpath droplet.sandbox + 'test-agentpath'
 
diff --git a/spec/java_buildpack/framework/jacoco_agent_spec.rb b/spec/java_buildpack/framework/jacoco_agent_spec.rb
@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Cloud Foundry Java Buildpack
+# Copyright 2013-2017 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'spec_helper'
+require 'component_helper'
+require 'java_buildpack/framework/jacoco_agent'
+require 'java_buildpack/util/tokenized_version'
+
+describe JavaBuildpack::Framework::JacocoAgent do
+  include_context 'with component help'
+
+  it 'does not detect without jacoco service' do
+    expect(component.detect).to be_nil
+  end
+
+  context do
+
+    before do
+      allow(services).to receive(:one_service?).with(/jacoco/, 'address').and_return(true)
+    end
+
+    it 'detects with jacoco service' do
+      expect(component.detect).to eq("jacoco-agent=#{version}")
+    end
+
+    it 'downloads JaCoco agent JAR',
+       cache_fixture: 'stub-jacoco-agent.jar' do
+
+      component.compile
+
+      expect(sandbox + 'jacocoagent.jar').to exist
+    end
+
+    it 'updates JAVA_OPTS' do
+      allow(services).to receive(:find_service).and_return('credentials' => { 'address' => 'test-address' })
+
+      component.release
+
+      expect(java_opts).to include('-javaagent:$PWD/.java-buildpack/jacoco_agent/jacocoagent.jar=' \
+                                   'address=test-address,output=tcpclient,sessionid=$CF_INSTANCE_GUID')
+    end
+
+    it 'updates JAVA_OPTS with additional options' do
+      allow(services).to receive(:find_service).and_return('credentials' => { 'address'  => 'test-address',
+                                                                              'excludes' => 'test-excludes',
+                                                                              'includes' => 'test-includes',
+                                                                              'port'     => 6300 })
+
+      component.release
+
+      expect(java_opts).to include('-javaagent:$PWD/.java-buildpack/jacoco_agent/jacocoagent.jar=' \
+                                   'address=test-address,output=tcpclient,sessionid=$CF_INSTANCE_GUID,' \
+                                   'excludes=test-excludes,includes=test-includes,port=6300')
+    end
+
+  end
+
+end
