The Oracle JRE provides Java runtimes from Oracle project. No versions of the JRE are available be default due to licensing restrictions. Instead you will need to create a repository with the Oracle JREs in it and configure the buildpack to use that repository. Unless otherwise configured, the version of Java that will be used is specified in config/oracle_jre.yml.
| Detection Criterion | Unconditional. Existence of a single bound Volume Service will result in Terminal heap dumps being written.
|
| Tags | oracle=⟨version⟩, open-jdk-like-memory-calculator=⟨version⟩, jvmkill=⟨version⟩ |
NOTE: Unlike the OpenJDK JRE, this JRE does not connect to a pre-populated repository. Instead you will need to create your own repository by:
- Downloading the Oracle JRE binary (in TAR format) to an HTTP-accesible location
- Uploading an
index.ymlfile with a mapping from the version of the JRE to its location to the same HTTP-accessible location - Configuring the
config/oracle_jre.ymlfile to point to the root of the repository holding both the index and JRE binary - Configuring the
config/components.ymlfile to disable the OpenJDK JRE and enable the Oracle JRE
For details on the repository structure, see the repository documentation.
For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to Configuration and Extension.
The JRE can be configured by modifying the config/oracle_jre.yml file in the buildpack fork. The JRE uses the Repository utility support and so it supports the version syntax defined there.
To use Oracle JRE instead of OpenJDK without forking java-buildpack, set environment variable:
cf set-env <app_name> JBP_CONFIG_COMPONENTS '{ jres: [ "JavaBuildpack::Jre::OracleJRE" ] }'
cf set-env <app_name> JBP_CONFIG_ORACLE_JRE '{ jre: { repository_root: "<INTERNAL_REPOSITORY_URI>" } }'
cf restage <app_name>
| Name | Description |
|---|---|
jre.repository_root |
The URL of the Oracle repository index (details). |
jre.version |
The version of Java runtime to use. Candidate versions can be found in the the repository that you have created to house the JREs. Note: version 1.8.0 and higher require the memory_sizes and memory_heuristics mappings to specify metaspace rather than permgen. |
jvmkill.repository_root |
The URL of the jvmkill repository index (details). |
jvmkill.version |
The version of jvmkill to use. Candidate versions can be found in the listings for mountainlion and trusty. |
memory_calculator |
Memory calculator defaults, described below under "Memory". |
The JRE can also be configured by overlaying a set of resources on the default distribution. To do this, add files to the resources/oracle_jre directory in the buildpack fork.
To add the JCE Unlimited Strength local_policy.jar, add your file to resources/oracle_jre/lib/security/local_policy.jar. In case you you'r using the 'server jre', then the file should go to resources/oracle_jre/jre/lib/security/local_policy.jar. This file will be overlayed onto the Oracle distribution.
To add custom SSL certificates, add your cacerts file to resources/oracle_jre/lib/security/cacerts. This file will be overlayed onto the Oracle distribution.
The jvmkill agent runs when an application has experience a resource exhaustion event. When this event occurs, the agent will print out a histogram of the first 100 largest types by total number of bytes.
Resource exhaustion event: the JVM was unable to allocate memory from the heap.
ResourceExhausted! (1/0)
| Instance Count | Total Bytes | Class Name |
| 18273 | 313157136 | [B |
| 47806 | 7648568 | [C |
| 14635 | 1287880 | Ljava/lang/reflect/Method; |
| 46590 | 1118160 | Ljava/lang/String; |
| 8413 | 938504 | Ljava/lang/Class; |
| 28573 | 914336 | Ljava/util/concurrent/ConcurrentHashMap$Node; |
It will also print out a summary of all of the memory spaces in the JVM.
Memory usage:
Heap memory: init 65011712, used 332392888, committed 351797248, max 351797248
Non-heap memory: init 2555904, used 63098592, committed 64815104, max 377790464
Memory pool usage:
Code Cache: init 2555904, used 14702208, committed 15007744, max 251658240
PS Eden Space: init 16252928, used 84934656, committed 84934656, max 84934656
PS Survivor Space: init 2621440, used 0, committed 19398656, max 19398656
Compressed Class Space: init 0, used 5249512, committed 5505024, max 19214336
Metaspace: init 0, used 43150616, committed 44302336, max 106917888
PS Old Gen: init 43515904, used 247459792, committed 247463936, max 247463936
If a Volume Service with the string heap-dump in its name or tag is bound to the application, terminal heap dumps will be written with the pattern <CONTAINER_DIR>/<SPACE_NAME>-<SPACE_ID[0,8]>/<APPLICATION_NAME>-<APPLICATION_ID[0,8]>/<INSTANCE_INDEX>-<TIMESTAMP>-<INSTANCE_ID[0,8]>.hprof
Heapdump written to /var/vcap/data/9ae0b817-1446-4915-9990-74c1bb26f147/pcfdev-space-e91c5c39/java-main-application-892f20ab/0-2017-06-13T18:31:29+0000-7b23124e.hprof
The total available memory for the application's container is specified when an application is pushed.
The Java buildpack uses this value to control the JRE's use of various
regions of memory and logs the JRE memory settings when the application starts or restarts.
These settings can be influenced by configuring
the stack_threads and/or class_count mappings (both part of the memory_calculator mapping),
and/or Java options relating to memory.
Note: If the total available memory is scaled up or down, the Java buildpack will re-calculate the JRE memory settings the next time the application is started.
The user can change the container's total memory available to influence the JRE memory settings.
Unless the user specifies the heap size Java option (-Xmx), increasing or decreasing the total memory
available results in the heap size setting increasing or decreasing by a corresponding amount.
The amount of memory that is allocated to metaspace and compressed class space (or, on Java 7, the permanent generation) is calculated from an estimate of the number of classes that will be loaded. The default behaviour is to estimate the number of loaded classes as a fraction of the number of class files in the application. If a specific number of loaded classes should be used for calculations, then it should be specified as in the following example:
class_count: 500A percentage of the total memory allocated to the container to be left as headroom and excluded from the memory calculation.
headroom: 10The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option -Xss. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example:
stack_threads: 500Note that the default value of 250 threads is optimized for a default Tomcat configuration. If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value. Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself.
If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to specific values. The heap size can be set explicitly, but changing the value of options other than the heap size can also affect the heap size. For example, if the user increases the maximum direct memory size from its default value of 10 Mb to 20 Mb, then this will reduce the calculated heap size by 10 Mb.
Memory calculation happens before every start of an application and is performed by an external program, the Java Buildpack Memory Calculator. There is no need to restage an application after scaling the memory as restarting will cause the memory settings to be recalculated.
The container's total available memory is allocated into heap, metaspace and compressed class space (or permanent generation for Java 7), direct memory, and stack memory settings.
The memory calculation is described in more detail in the Memory Calculator's README.
The inputs to the memory calculation, except the container's total memory (which is unknown at staging time), are logged during staging, for example:
Loaded Classes: 13974, Threads: 300, JAVA_OPTS: ''
The container's total memory is logged during cf push and cf scale, for example:
state since cpu memory disk details
#0 running 2017-04-10 02:20:03 PM 0.0% 896K of 1G 1.3M of 1G
The JRE memory settings are logged when the application is started or re-started, for example:
JVM Memory Configuration: -XX:MaxDirectMemorySize=10M -XX:MaxMetaspaceSize=99199K \
-XX:ReservedCodeCacheSize=240M -XX:CompressedClassSpaceSize=18134K -Xss1M -Xmx368042K