Extension point for supplying an external Tomcat configuration

config/tomcat.yml

@@ -19,6 +19,10 @@ tomcat:
   version: 8.0.+
   repository_root: ! '{default.repository.root}/tomcat'
   context_path:
+  external_configuration_enabled: false
+external_configuration:
+  version: 1.+
+  repository_root: ""
 lifecycle_support:
   version: 2.+
   repository_root: ! '{default.repository.root}/tomcat-lifecycle-support'

docs/container-tomcat.md

@@ -8,7 +8,7 @@ The Tomcat Container allows servlet 2 and 3 web applications to be run.  These a
   </tr>
   <tr>
     <td><strong>Tags</strong></td>
-    <td><tt>tomcat-instance=&lang;version&rang;</tt>, <tt>tomcat-lifecycle-support=&lang;version&rang;</tt>, <tt>tomcat-logging-support=&lang;version&rang;</tt> <tt>tomcat-redis-store=&lang;version&rang;</tt> <i>(optional)</i></td>
+    <td><tt>tomcat-instance=&lang;version&rang;</tt>, <tt>tomcat-lifecycle-support=&lang;version&rang;</tt>, <tt>tomcat-logging-support=&lang;version&rang;</tt>, <tt>tomcat-redis-store=&lang;version&rang;</tt> <i>(optional)</i>, <tt>tomcat-external_configuration=&lang;version&rang;</tt> <i>(optional)</i></td>
   </tr>
 </table>
 Tags are printed to standard output by the buildpack detect script
@@ -49,6 +49,9 @@ The container can be configured by modifying the [`config/tomcat.yml`][] file in
 | `tomcat.context_path` | The context path to expose the application at.
 | `tomcat.repository_root` | The URL of the Tomcat repository index ([details][repositories]).
 | `tomcat.version` | The version of Tomcat to use. Candidate versions can be found in [this listing](http://download.pivotal.io.s3.amazonaws.com/tomcat/index.yml).
+| `tomcat.external_configuration_enabled` | Set to `true` to be able to supply an external Tomcat configuration. Default is `false`.
+| `external_configuration.version` | The version of the External Tomcat Configuration to use. Candidate versions can be found in the the repository that you have created to house the External Tomcat Configuration. Note: It is required the external configuration to allow symlinks.
+| `external_configuration.repository_root` | The URL of the External Tomcat Configuration repository index ([details][repositories]).
 
 ### Common configurations
 The version of Tomcat can be configured by setting an environment variable.
@@ -65,7 +68,34 @@ $ cf set-env my-application JBP_CONFIG_TOMCAT '{tomcat: { context_path: /first-s
 
 
 ### Additional Resources
-The container can also be configured by overlaying a set of resources on the default distribution.  To do this, add files to the `resources/tomcat` directory in the buildpack fork.  For example, to override the default `logging.properties` add your custom file to `resources/tomcat/conf/logging.properties`.
+The container can also be configured by overlaying a set of resources on the default distribution.  To do this follow one of the options below.
+
+#### Buildpack Fork
+Add files to the `resources/tomcat` directory in the buildpack fork.  For example, to override the default `logging.properties` add your custom file to `resources/tomcat/conf/logging.properties`.
+
+#### External Tomcat Configuration
+Supply a repository with an external Tomcat configuration.
+
+Example in a manifest.yml
+```
+env:
+  JBP_CONFIG_TOMCAT: "{ tomcat: { external_configuration_enabled: true }, external_configuration: { repository_root: \"http://repository...\" } }"
+```
+
+The artifacts that the repository provides must be in TAR format and must follow the Tomcat archive structure:
+
+```
+tomcat
+|__conf
+   |__context.xml
+   |__server.xml
+   |__web.xml
+   |...
+```
+
+Notes:
+* It is required the external configuration to allow symlinks. For more information check [Tomcat 7 configuration] or [Tomcat 8 configuration].
+* `JasperListener` is removed in Tomcat 8 so you should not add it to the server.xml.
 
 ## Session Replication
 By default, the Tomcat instance is configured to store all Sessions and their data in memory.  Under certain circumstances it my be appropriate to persist the Sessions and their data to a repository.  When this is the case (small amounts of data that should survive the failure of any individual instance), the buildpack can automatically configure Tomcat to do so by binding an appropriate service.
@@ -98,3 +128,5 @@ Additional supporting functionality can be found in the [`java-buildpack-support
 [`SPRING_PROFILES_ACTIVE`]: http://docs.spring.io/spring/docs/4.0.0.RELEASE/javadoc-api/org/springframework/core/env/AbstractEnvironment.html#ACTIVE_PROFILES_PROPERTY_NAME
 [Tomcat wiki]: http://wiki.apache.org/tomcat/HowTo/FasterStartUp
 [version syntax]: extending-repositories.md#version-syntax-and-ordering
+[Tomcat 7 configuration]: http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Standard_Implementation
+[Tomcat 8 configuration]: http://tomcat.apache.org/tomcat-8.0-doc/config/resources.html#Common_Attributes

lib/java_buildpack/container/tomcat.rb

@@ -18,6 +18,7 @@
 require 'java_buildpack/container'
 require 'java_buildpack/container/tomcat/tomcat_insight_support'
 require 'java_buildpack/container/tomcat/tomcat_instance'
+require 'java_buildpack/container/tomcat/tomcat_external_configuration'
 require 'java_buildpack/container/tomcat/tomcat_lifecycle_support'
 require 'java_buildpack/container/tomcat/tomcat_logging_support'
 require 'java_buildpack/container/tomcat/tomcat_access_logging_support'
@@ -49,7 +50,7 @@ def command
 
       # (see JavaBuildpack::Component::ModularComponent#sub_components)
       def sub_components(context)
-        [
+        components = [
           TomcatInstance.new(sub_configuration_context(context, 'tomcat')),
           TomcatLifecycleSupport.new(sub_configuration_context(context, 'lifecycle_support')),
           TomcatLoggingSupport.new(sub_configuration_context(context, 'logging_support')),
@@ -58,6 +59,12 @@ def sub_components(context)
           TomcatGemfireStore.new(sub_configuration_context(context, 'gemfire_store')),
           TomcatInsightSupport.new(context)
         ]
+
+        tomcat_configuration = @configuration['tomcat']
+        components << TomcatExternalConfiguration.new(sub_configuration_context(context, 'external_configuration')) if
+          tomcat_configuration['external_configuration_enabled']
+
+        components
       end
 
       # (see JavaBuildpack::Component::ModularComponent#supports?)

lib/java_buildpack/container/tomcat/tomcat_external_configuration.rb

@@ -0,0 +1,46 @@
+# Encoding: utf-8
+# Cloud Foundry Java Buildpack
+# Copyright 2016 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/container'
+
+module JavaBuildpack
+  module Container
+
+    # Encapsulates the detect, compile, and release functionality for Tomcat external configuration.
+    class TomcatExternalConfiguration < JavaBuildpack::Component::VersionedDependencyComponent
+      include JavaBuildpack::Container
+
+      # (see JavaBuildpack::Component::BaseComponent#compile)
+      def compile
+        download_tar
+      end
+
+      # (see JavaBuildpack::Component::BaseComponent#release)
+      def release
+      end
+
+      protected
+
+      # (see JavaBuildpack::Component::VersionedDependencyComponent#supports?)
+      def supports?
+        true
+      end
+
+    end
+
+  end
+end

spec/java_buildpack/container/tomcat/tomcat_external_configuration_spec.rb

@@ -0,0 +1,40 @@
+# Encoding: utf-8
+# Cloud Foundry Java Buildpack
+# Copyright 2016 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/container/tomcat/tomcat_external_configuration'
+
+describe JavaBuildpack::Container::TomcatExternalConfiguration do
+  include_context 'component_helper'
+
+  let(:component_id) { 'tomcat' }
+
+  it 'always detects' do
+    expect(component.detect).to eq("tomcat-external-configuration=#{version}")
+  end
+
+  it 'extracts Tomcat external configuration files from a GZipped TAR',
+     app_fixture:   'container_tomcat',
+     cache_fixture: 'stub-tomcat-external-configuration.tar.gz' do
+
+    component.compile
+
+    expect(sandbox + 'conf/context.xml').to exist
+    expect(sandbox + 'conf/server.xml').to exist
+  end
+
+end

spec/java_buildpack/container/tomcat_spec.rb

@@ -35,10 +35,11 @@
       'lifecycle_support'      => lifecycle_support_configuration,
       'logging_support'        => logging_support_configuration,
       'access_logging_support' => access_logging_support_configuration,
-      'redis_store'            => redis_store_configuration }
+      'redis_store'            => redis_store_configuration,
+      'external_configuration' => tomcat_external_configuration }
   end
 
-  let(:tomcat_configuration) { double('tomcat-configuration') }
+  let(:tomcat_configuration) { { 'external_configuration_enabled' => false } }
 
   let(:lifecycle_support_configuration) { double('lifecycle-support-configuration') }
 
@@ -48,6 +49,8 @@
 
   let(:redis_store_configuration) { double('redis-store-configuration') }
 
+  let(:tomcat_external_configuration) { double('tomcat_external_configuration') }
+
   it 'detects WEB-INF',
      app_fixture: 'container_tomcat' do
 
@@ -88,6 +91,18 @@
                                       ' run')
   end
 
+  context do
+
+    let(:tomcat_configuration) { { 'external_configuration_enabled' => true } }
+
+    it 'creates submodule TomcatExternalConfiguration' do
+      expect(JavaBuildpack::Container::TomcatExternalConfiguration)
+        .to receive(:new).with(sub_configuration_context(tomcat_external_configuration))
+
+      component.sub_components context
+    end
+  end
+
 end
 
 class StubTomcat < JavaBuildpack::Container::Tomcat