Tips for Java Developers
Page last updated:
Cloud Foundry can deploy a number of different JVM-based artifact types. For a more detailed explanation of what it supports, see the Java Buildpack documentation.
Java Buildpack
For detailed information about using, configuring, and extending the Cloud Foundry Java buildpack, see Java Buildpack documentation.
Design
The Java Buildpack is designed to convert artifacts that run on the JVM into executable applications. It does this by identifying one of the supported artifact types (Grails, Groovy, Java, Play Framework, Spring Boot, and Servlet) and downloading all additional dependencies needed to run. The collection of services bound to the application is also analyzed and any dependencies related to those services are also downloaded.
As an example, pushing a WAR file that is bound to a PostgreSQL database and New Relic for performance monitoring would result in the following:
Initialized empty Git repository in /tmp/buildpacks/java-buildpack/.git/ --> Java Buildpack source: https://github.com/cloudfoundry/java-buildpack#0928916a2dd78e9faf9469c558046eef09f60e5d --> Downloading Open Jdk JRE 1.7.0_51 from http://.../openjdk/lucid/x86_64/openjdk-1.7.0_51.tar.gz (0.0s) Expanding Open Jdk JRE to .java-buildpack/open_jdk_jre (1.9s) --> Downloading New Relic Agent 3.4.1 from http://.../new-relic/new-relic-3.4.1.jar (0.4s) --> Downloading Postgresql JDBC 9.3.1100 from http://.../postgresql-jdbc/postgresql-jdbc-9.3.1100.jar (0.0s) --> Downloading Spring Auto Reconfiguration 0.8.7 from http://.../auto-reconfiguration/auto-reconfiguration-0.8.7.jar (0.0s) Modifying /WEB-INF/web.xml for Auto Reconfiguration --> Downloading Tomcat 7.0.50 from http://.../tomcat/tomcat-7.0.50.tar.gz (0.0s) Expanding Tomcat to .java-buildpack/tomcat (0.1s) --> Downloading Buildpack Tomcat Support 1.1.1 from http://.../tomcat-buildpack-support/tomcat-buildpack-support-1.1.1.jar (0.1s) --> Uploading droplet (57M)
Configuration
In most cases, the buildpack should work without any configuration. If you are new to Cloud Foundry, we recommend that you make your first attempts without modifying the buildpack configuration. If the buildpack requires some configuration, use a fork of the buildpack.
Java Client Library
The Cloud Foundry Client Library provides a Java API for interacting with a
Cloud Foundry instance.
This library, cloudfoundry-client-lib
, is used by the Cloud Foundry Maven
plugin, the Cloud Foundry Gradle plugin, and other Java-based tools.
For information about using this library, see the Java Cloud Foundry Library page.
Grails
Grails packages applications into WAR files for deployment into a Servlet container. To build the WAR file and deploy it, run the following:
$ grails prod war $ cf push my-application -p target/my-application-version.war
Groovy
Groovy applications based on both Ratpack and a simple collection of files are supported.
Ratpack
Ratpack packages applications into two different styles; Cloud Foundry supports
the distZip
style. To build the ZIP and deploy it, run the following:
$ gradle distZip $ cf push my-application -p build/distributions/my-application.zip
Raw Groovy
Groovy applications that are made up of a single entry point plus any supporting files can be run without any other work. To deploy them, run the following:
$ cf push my-application
Java Main
Java applications with a main()
method can be run provided that they are
packaged as self-executable JARs.
Note: If your application is not web-enabled, you must suppress route creation to avoid a “failed to start accepting connections” error. To suppress route creation, add no-route: true
to the application manifest or use the --no-route
flag with the cf push
command.
For more information about the no-route
attribute, see the Deploying with Application Manifests topic.
Maven
A Maven build can create a self-executable JAR. To build and deploy the JAR, run the following:
$ mvn package $ cf push my-application -p target/my-application-version.jar
Gradle
A Gradle build can create a self-executable JAR. To build and deploy the JAR, run the following:
$ gradle build $ cf push my-application -p build/libs/my-application-version.jar
Play Framework
The Play Framework packages applications into two different styles.
Cloud Foundry supports both the staged
and dist
styles. To build the dist
style and deploy it, run the following:
$ play dist $ cf push my-application -p target/universal/my-application-version.zip
Spring Boot CLI
Spring Boot can run applications comprised entirely of POGOs. To deploy then, run the following:
$ spring grab *.groovy $ cf push my-application
Servlet
Java applications can be packaged as Servlet applications.
Maven
A Maven build can create a Servlet WAR. To build and deploy the WAR, run the following:
$ mvn package $ cf push my-application -p target/my-application-version.war
Gradle
A Gradle build can create a Servlet WAR. To build and deploy the JAR, run the following:
$ gradle build $ cf push my-application -p build/libs/my-application-version.war
Binding to Services
Information about binding apps to services can be found on the following pages:
- Service Bindings for Grails Applications
- Service Bindings for Play Framework Applications
- Service Bindings for Spring Applications
Java and Grails Best Practices
Provide JDBC driver
The Java buildpack does not bundle a JDBC driver with your application. If your application will access a SQL RDBMS, include the appropriate driver in your application.
Allocate Sufficient Memory
If you do not allocate sufficient memory to a Java application when you deploy it, it may fail to start, or PAS may terminate it. You must allocate enough memory to allow for the following:
- Java heap
- Metaspace, if using Java 8
- PermGen, if using Java 7 or earlier
- Stack size per Thread
- JVM overhead
The config/open_jdk_jre.yml
file of the Cloud Foundry Java buildpack contains default
memory size and weighting settings for the JRE.
See the Open JDK JRE README on GitHub for an explanation of JRE memory sizes and weightings and
how the Java buildpack calculates and allocates memory to the JRE for your app.
To configure memory-related JRE options for your app, you either create a custom buildpack and specify this buildpack in your deployment manifest or you override the default memory settings of your buildpack as described in the https://github.com/cloudfoundry/java-buildpack#configuration-and-extension with the properties listed in the Open JDK JRE README. For more information about configuring custom buildpacks and manifests, refer to the Custom Buildpacks and Deploying with Application Manifests topics.
When your app is running, you can use the cf app APP-NAME
command to see
memory utilization.
Troubleshoot Out Of Memory
A Java app may crash because of insufficient memory on the Garden container or the JVM on which it runs. See the following sections for help diagnosing and resolving such issues.
JVM
- Error:
java.lang.OutOfMemoryError
. See the following example:$ cf logs APP-NAME --recent 2016-06-20T09:18:51.00+0100 [APP/0] OUT java.lang.OutOfMemoryError: Metaspace
- Cause: If the JVM cannot garbage-collect enough space to ensure the allocation of a data-structure, it fails with java.lang.OutOfMemoryError. In the example above, JVM has an under-sized
metaspace
. You may see failures in other memory pools, such asheap
. - Solution: Configure the JVM correctly for your app. See Allocate Sufficient Memory.
Garden Container
Note: The solutions in this section require configuring the memory calculator, which is a sub-project of the CF Java buildpack that calculates suitable memory settings for Java apps when you push them. See the java-buildpack-memory-calculator repository for more information. If you have questions about the memory calculator, you can ask them in the #java-buildpack channel of the Cloud Foundry Slack organization.
Error: The Garden container terminates the Java process with the
out of memory
event. See the following example:$ cf events APP-NAME time event actor description 2016-06-20T09:18:51.00+0100 app.crash app-name index: 0, reason: CRASHED, exit_description: out of memory, exit_status: 255
This error appears when the JVM allocates more OS-level memory than the quota requested by the app, such as through the manifest.
Cause 1 - Insufficient native memory: This error commonly means that the JVM requires more
native
memory. In the scope of the Java buildpack and the memory calculator, the termnative
means the memory required for the JVM to work, along with forms of memory not covered in the other classifications of the memory calculator. This includes the memory footprint of OS-level threads, direct NIO buffers, code cache, program counters, and others.Solution 1: Determine how much
native
memory a Java app needs by measuring it with realistic workloads and fine-tuning it accordingly. You can then configure the Java buildpack using thenative
setting of the memory calculator, as in the example below:--- applications: - name: app-name memory: 1G env: JBP_CONFIG_OPEN_JDK_JRE: '[memory_calculator: {memory_sizes: {native: 150m}}]'
This example shows that
150m
of the overall available1G
is reserved for anything that is notheap
,metaspace
, orpermgen
. In less common cases, this may come from companion processes started by the JVM, such as the Process API.Cause 2 - High thread count: Java threads in the JVM can cause memory errors at the Garden level. When an app is under heavy load, it uses a high number of threads and consumes a significant amount of memory.
Solution 2: Set the reserved memory for stack traces to the correct value for your app.
You can use thestack
setting of the memory calculator to configure the amount of space the JVM reserves for each Java thread. You must multiply this value by the number of threads your app requires. Specify the number of threads in thestack_threads
setting of the memory calculator. For example, if you estimate the max thread count for an app at800
and the amount of memory needed to represent the deepest stacktrace of a Java thread is512KB
, configure the memory calculator as follows:--- applications: - name: app-name memory: 1G env: JBP_CONFIG_OPEN_JDK_JRE: '[memory_calculator: {stack_threads: 800, memory_sizes: {stack: 512k}}]'
In this example, the overall memory amount reserved by the JVM for representing the stacks of Java threads is
800 * 512k = 400m
.
The correct settings forstack
andstack_threads
depend on your app code, including the libraries it uses. Your app may technically have no upper limit, such as in the case of cavalier usage ofCachedThreadPool
executors. However, you still must calculate the depth of the thread stacks and the amount of space the JVM should reserve for each of them.
Troubleshoot Failed Upload
If your application fails to upload when you push it to Cloud Foundry, it may be for one of the following reasons:
WAR is too large: An upload may fail due to the size of the WAR file. Cloud Foundry testing indicates WAR files as large as 250 MB upload successfully. If a WAR file larger than that fails to upload, it may be a result of the file size.
Connection issues: Application uploads can fail if you have a slow Internet connection, or if you upload from a location that is very remote from the target Cloud Foundry instance. If an application upload takes a long time, your authorization token can expire before the upload completes. A workaround is to copy the WAR to a server that is closer to the Cloud Foundry instance, and push it from there.
Out-of-date cf CLI client: Upload of a large WAR is faster and hence less likely to fail if you are using a recent version of the cf CLI. If you are using an older version of the cf CLI client to upload a large WAR, and having problems, try updating to the latest version of the cf CLI.
Incorrect WAR targeting: By default,
cf push
uploads everything in the current directory. For a Java application,cf push
with no option flags uploads source code and other unnecessary files, in addition to the WAR. When you push a Java application, specify the path to the WAR:$ cf push MY-APP -p PATH/TO/WAR-FILE
You can determine whether or not the path was specified for a previously pushed application by examining the application deployment manifest,
manifest.yml
. If thepath
attribute specifies the current directory, the manifest includes a line like the following:path: .
To re-push just the WAR, do one of the following:
- Delete
manifest.yml
and runcf push
again, specifying the location of the WAR using the-p
flag. - Edit the
path
argument inmanifest.yml
to point to the WAR, and re-push the application.
- Delete
Debug Java Apps on Cloud Foundry
Because of the way that Cloud Foundry deploys your applications and isolates them, it is not possible to connect to your application with the remote Java debugger. Instead, instruct the application to connect to the Java debugger on your local machine.
Here are the instructions for setting up remote debugging when using BOSH Lite or a Cloud Foundry installation.
- Open your project in Eclipse.
- Right-click on your project, go to Debug as and pick Debug Configurations.
- Create a new Remote Java Application.
- Make sure your project is selected, pick Standard (Socket Listen) from the Connection Type drop down and set a port. Make sure this port is open if you are running a firewall.
- Click Debug.
The debugger should now be running. If you switch to the Debug perspective, you should see your application listed in the Debug panel and it should say Waiting for vm to connect at port
.
Next, push your application to Cloud Foundry and instruct Cloud Foundry to connect to the debugger running on your local machine using the following instructions:
- Edit your
manifest.yml
file. Set the instances count to 1. If you set this greater than one, multiple applications try to connect to your debugger. - Also in
manifest.yml
, add theenv
section and create a variable calledJAVA_OPTS
. - Add the remote debugger configuration to the
JAVA_OPTS
variable:-agentlib:jdwp=transport=dt_socket,address=YOUR-IP-ADDRESS:YOUR-PORT
. - Save the
manifest.yml
file. - Run
cf push
.
Upon completion, you should see that your application has started and is now connected to the debugger running in your IDE. You can now add breakpoints and interrogate the application just as you would if it were running locally.
Slow Starting Java or Grails Apps
Some Java and Grails applications do not start quickly, and the health check for an application can fail if an application starts too slowly.
The current Java buildpack implementation sets the Tomcat bindOnInit
property
to false
. This prevents Tomcat from listening for HTTP requests until an
application has fully deployed.
If your application does not start quickly, the health check may fail because it checks the health of the application before the application can accept requests. By default, the health check fails after a timeout threshold of 60 seconds.
To resolve this issue, use cf push APP-NAME
with the -t TIMEOUT-THRESHOLD
option to increase the timeout threshold. Specify TIMEOUT-THRESHOLD
in seconds.
$ cf push my-app -t 180
Note: The timeout threshold cannot exceed 180 seconds. Specifying a timeout threshold greater than 180 seconds results in the following error: Server error, status code: 400, error code: 100001, message: The app is invalid: health_check_timeout maximum_exceeded
Extension
The Java Buildpack is also designed to be easily extended. It creates abstractions for three types of components (containers, frameworks, and JREs) in order to allow users to easily add functionality. In addition to these abstractions, there are a number of utility classes for simplifying typical buildpack behaviors.
As an example, the New Relic framework looks like the following:
class NewRelicAgent < JavaBuildpack::Component::VersionedDependencyComponent
# @macro base_component_compile
def compile
FileUtils.mkdir_p logs_dir
download_jar
@droplet.copy_resources
end
# @macro base_component_release
def release
@droplet.java_opts
.add_javaagent(@droplet.sandbox + jar_name)
.add_system_property('newrelic.home', @droplet.sandbox)
.add_system_property('newrelic.config.license_key', license_key)
.add_system_property('newrelic.config.app_name', "'#{application_name}'")
.add_system_property('newrelic.config.log_file_path', logs_dir)
end
protected
# @macro versioned_dependency_component_supports
def supports?
@application.services.one_service? FILTER, 'licenseKey'
end
private
FILTER = /newrelic/.freeze
def application_name
@application.details['application_name']
end
def license_key
@application.services.find_service(FILTER)['credentials']['licenseKey']
end
def logs_dir
@droplet.sandbox + 'logs'
end
end
Environment Variables
You can access environments variable programmatically.
For example, you can obtain VCAP_SERVICES
as follows:
System.getenv("VCAP_SERVICES");
See the Cloud Foundry Environment Variables topic for more information.