The java-buildpack is a Cloud Foundry buildpack for running Java applications. It is designed to run most Java applications with no additional configuration, but supports configuration of the standard components, and extension to add custom components.

• Usage (Configuration)
• Design
• Standard Components
  • OpenJDK JRE (Configuration)
  • Java Main Class Container (Configuration)
  • JAVA_OPTS Framework (Configuration)
• Extending
  • JREs
  • Containers
  • Frameworks

To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry.

cf push --buildpack https://github.com/cloudfoundry/java-buildpack

The buildpack supports configuration and extension through the use of Git repository forking. The easiest way to accomplish this is to use GitHub's forking functionality to create a copy of this repository. In that copy of the repository, make the required configuration and extension changes. Then when pushing a Cloud Foundry application, use the URL of the new repository. If the modifications are applicable to the Cloud Foundry community, please submit a pull request with the changes.

Components are configured by setting key-value pairs in a system.properties file. The system.properties file can exist anywhere within the pushed artifact's file system.

The buildpack is designed as a collection of components. These components are divided into three types; JREs, Containers, and Frameworks.

JRE components represent the JRE that will be used when running an application. This type of component is responsible for determining which JRE should be used, downloading and unpacking that JRE, and resolving any JRE-specific options that should be used at runtime.

Only a single JRE component can be used to run an application. If more than one JRE can be used, an error will be raised and application deployment will fail. In this case, the java.runtime.vendor property in system.properties must be set to a value that will cause a single JRE component to be used.

Container components represent the way that an application will be run. Container types range from traditional application servers and servlet containers to simple Java main() method execution. This type of component is responsible for determining which container should be used, downloading and unpacking that container, and producing the command that will be executed by Cloud Foundry at runtime.

Only a single container component can run an application. If more than one container can be used, an error will be raised and application deployment will fail.

Framework components represent additional behavior or transformations used when an application is run. Framework types include the downloading of JDBC JARs for bound services and automatic reconfiguration of DataSources in Spring configuration to match bound services. This type of component is responsible for determining which frameworks are required, transforming the application, and contributing any additional options that should be used at runtime.

Any number of framework components can be used when running an application.

The buildpack contributes a number of standard components that enable most Java applications to run.

The OpenJDK JRE provides Java runtimes from the OpenJDK project. Versions of Java from the 1.6, 1.7, and 1.8 lines are available. If the version to use is not configured in system.properties, the latest version from the 1.7.0 line is chosen.

JREs versions are composed of major, minor, micro, and optional qualifier parts (<major>.<minor>.<micro>[_<qualifier>]). The major, minor, and micro parts must be numeric. The qualifier part is composed of letters, digits, and hyphens. The lexical ordering of the qualifier is:

1. hyphen
2. lowercase letters
3. uppercase letters
4. digits

In addition to declaring a specific version of JRE to use, you can also specify a bounded range of JRES to use. Appending the + symbol to a version prefix chooses the latest JRE that begins with the prefix.

The OpenJDK JRE allows the configuration of the version of Java to use as well as the allocation of memory at runtime.

If some memory sizes are not specified using the above properties, default values are provided. For maximum heap, Metaspace, or PermGen size, the default value is based on a proportion of the total memory specified when the application was pushed. For stack size, the default value is one megabyte.

If any memory sizes are specified which are not equal to the default value, the proportionate defaults are adjusted accordingly. The default stack size is never adjusted from the default value.

The calculation of default memory sizes for OpenJDK is configured via YAML files in the buildpack's config directory.

The configuration contains a weighting between 0 and 1 corresponding to a proportion of the total memory specified when the application was pushed. The weightings should add up to 1.

The Java Main Class Container allows applications that provide a class with a main() method in it to be run. These applications are run with a command that looks like ./java/bin/java -cp . com.gopivotal.SampleClass.

The JAVA_OPTS Framework contributes arbitrary Java options to the application at runtime.

The buildpack is designed to be extended by specifying components in config/components.yml. The values listed in this file correspond to Ruby class names that will be instantiated and called. In order for these classes to be instantiated, the files containing them must be located in specific directories in the repository.

To add a JRE, the class file must be located in lib/java_buildpack/jre. The class must have the following methods:

# An initializer for the instance.
#
# @param [Hash<Symbol, String>] context A shared context provided to all components
# @option context [String] :app_dir the directory that the application exists in
# @option context [Array<String>] :java_opts an array that Java options can be added to
# @option context [Hash] :system_properties the properties provided by the user
def initialize(context = {})

# Determines if the JRE can be used to run the application.
#
# @return [String, nil] If the JRE can be used to run the application, a +String+ that uniquely identifies the JRE
#                       (e.g. +jre-openjdk-1.7.0_21+).  Otherwise, +nil+.
def detect

# Downloads and unpacks the JRE.  The JRE is expected to be unpacked such that +JAVA_HOME+ is +.java+.  Status output
# written to +STDOUT+ is expected as part of this invocation.
#
# @return [void]
def compile

# Adds any JRE-specific options to +context[:java_opts]+.  Typically this includes memory configuration (heap, perm gen,
# etc.) but could be anything that a JRE needs to have configured.
#
# @return [void]
def release

To add a container, the class file must be located in lib/java_buildpack/container. The class must have the following methods

# An initializer for the instance.
#
# @param [Hash<Symbol, String>] context A shared context provided to all components
# @option context [String] :app_dir the directory that the application exists in
# @option context [Array<String>] :java_opts an array that Java options can be added to
# @option context [Hash] :system_properties the properties provided by the user
def initialize(context = {})

# Determines if the container can be used to run the application.
#
# @return [String, nil] If the container can be used to run the application, a +String+ that uniquely identifies the
#                       container (e.g. +tomcat-7.0.29+).  Otherwise, +nil+.
def detect

# Downloads and unpacks the container.  The container is expected to transform the application in whatever way
# necessary (e.g. moving files or creating symbolic links) to run it.  Status output written to +STDOUT+ is expected as
# part of this invocation.
#
# @return [void]
def compile

# Creates the command to run the application with.  The container is expected to read +context[:java_opts]+ and take
# those values into account when creating the command.
#
# @return [String] the command to run the application with
def release

To add a framework, the class file must be located in lib/java_buildpack/framework. The class must have the following methods:

# An initializer for the instance.
#
# @param [Hash<Symbol, String>] context A shared context provided to all components
# @option context [String] :app_dir the directory that the application exists in
# @option context [Array<String>] :java_opts an array that Java options can be added to
# @option context [Hash] :system_properties the properties provided by the user
def initialize(context = {})

# Determines if the framework can be applied to the application
#
# @return [String, nil] If the framework can be used to run the application, a +String+ that uniquely identifies the
#                        framework (e.g. +java-opts+).  Otherwise, +nil+.
def detect

# Transforms the application based on the framework.  Status output written to +STDOUT+ is expected as part of this invocation.
#
# @return [void]
def compile

# Adds any framework-specific options to +context[:java_opts]+.  Typically this includes any JRE configuration required
# by the framework, but could be anything that a framework needs to have configured.
#
# @return [void]
def release