Java Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Java Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Java Buildpack How To documentation.

The Paketo Java Buildpack allows users to create an image containing a JVM application from a precompiled artifact or directly from source.

The Java Buildpack is a composite buildpack and each step in a build is handled by one of its components. For a full set of configuration options and capabilities see the homepages for the component buildpacks.

About the JVM

The Java Buildpack uses the BellSoft Liberica implementations of the JRE and JDK. JVM installation is handled by the BellSoft Liberica Buildpack. The JDK will be installed in the build container but only the JRE will be contributed to the application image.

See the homepage for the BellSoft Liberica Buildpack for a full set of configuration options.

Memory Calculator

The Java Memory Calculator is a tool used by the Paketo Java Buildpack to provide an optimized memory configuration for Java applications running in containers with enforced memory limits.

This section describes the algorithm that is responsible for providing this memory configuration, including the inputs used and their default values.

Heap

The Heap memory value, ultimately supplied as the -xmX JVM flag, is calculated using the following formula:

Heap = Total Container Memory - Non-Heap - Headroom

1. The Total Container Memory value is the total memory available to the application, typically the value of the memory limit set for the container.

2. The Non-Heap value is calculated by the algorithm using the following formula.

   Non-Heap = Direct Memory + Metaspace + Reserved Code Cache + (Thread Stack * Thread Count)

3. Headroom is a percentage of the container’s total memory that can be excluded from the memory calculator’s algorithm and left for non-JVM operations. This defaults to 0.

Non-Heap

The below table lists the component parts of the Non-Heap value, the equivalent JVM flags, and their defaults. Where one exists, the JVM default value is used.

The outputs of the tool are the above JVM flags and their calculated values.

The remaining memory left after totalling these values is assigned to the -Xmx flag as Heap. All flags and values are then appended to JAVA_TOOL_OPTIONS when the application image is run.

Notes

It is not recommended to set the Heap memory value directly using the -Xmx flag

The non-heap value calculated by the tool remains fixed for a constant application. Therefore, setting -Xmx directly could either:

• Cause the total memory (Heap + Non-Heap) to exceed the container limit if set too high, or
• Force a lower limit on Heap size than would be necessary after calculation, wasting memory.

Adjusting container memory limits

Decreasing the container memory limit will result in a reduced heap (-Xmx) size.

Similarly, increasing container memory limit beyond a known application’s non-heap (fixed) size will assign all of the increased value to Heap (-Xmx).

Overriding Defaults

It is possible to override the calculated or default values specified above in the non-heap table, however the runtime consequences of adjusting these values should be considered. For more information on how to configure these explicitly, see the How-To section Configure The JVM at Runtime.

Java Application Servers

The Paketo Java buildpack supports multiple application servers. Each application server has different capabilities and configuration options. The following are a list of supported application servers and links to reference documentation for each one.

Spring Boot Applications

If the application uses Spring Boot the Spring Boot Buildpack will enhance the resulting image by adding additional metadata to the image config, applying Boot-specific performance optimizations, and enabling runtime auto-configuration.

Additional Metadata

The Spring Boot Buildpack adds the following additional image labels:

• org.opencontainers.image.title - set to the value of Implementation-Title from MANIFEST.MF.
• org.opencontainers.image.version - set to the values of Implementation-Version from MANIFEST.MF.
• org.springframework.boot.version - set to the value of Spring-Boot-Version from MANIFEST.MF.
• org.springframework.cloud.dataflow.spring-configuration-metadata.json - containing [configuration metadata][spring boot configuration metadata].
• org.springframework.cloud.dataflow.spring-configuration-metadata.json - containing dataflow-configuration-metadata.properties, if present.

In addition, the buildpack will add an entry with name dependencies to the Bill-of-Materials listing the application dependencies.

Optimizations

The Spring Boot Buildpack can apply domain-specific knowledge to optimize the performance of Spring Boot applications. For example, if the buildpack detects that the application is a reactive web application the thread count will be reduced to 50 from a default of 250.

Components

The following component buildpacks compose the Java Buildpack. Buildpacks are listed in the order they are executed.