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


<table>
  <tr>
    <td><strong>Detection Criterion</strong></td>
    <td><tt>java_opts</tt> set in the <tt>config/java_opts.yml</tt> file or the <tt>JAVA_OPTS</tt> environment variable set</td>
  </tr>
  <tr>
    <td><strong>Tags</strong></td>
    <td><tt>java-opts</tt></td>
  </tr>
</table>
Tags are printed to standard output by the buildpack detect script

## Configuration
For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].

The framework can be configured by creating or modifying the [`config/java_opts.yml`][] file in the buildpack fork.

| Name | Description
| ---- | -----------
| `from_environment` | Whether to append the value of the `JAVA_OPTS` environment variable to the collection of Java options
| `java_opts` | The Java options to use when running the application. All values are used without modification when invoking the JVM. The options are specified as a single YAML scalar in plain style or enclosed in single or double quotes.

Any `JAVA_OPTS` from either the config file or environment variables will be specified in the start command after any Java Opts added by other frameworks.

## Escaping strings

Java options will have special characters escaped when used in the shell command that starts the Java application but the `$` and `\` characters will not be escaped. This is to allow Java options to include environment variables when the application starts.

```bash
cf set-env my-application JAVA_OPTS '-Dexample.port=$PORT'
```

If an escaped `$` or `\` character is needed in the Java options they will have to be escaped manually. For example, to obtain this output in the start command.

```bash
-Dexample.other=something.\$dollar.\\slash
```

From the command line use;
```bash
cf set-env my-application JAVA_OPTS '-Dexample.other=something.\\\\\$dollar.\\\\\\\slash'
```

From the [`config/java_opts.yml`][] file use;
```yaml
from_environment: true
java_opts: '-Dexample.other=something.\\$dollar.\\\\slash'
```

Finally, from the applications manifest use;
```yaml
  env:
    JAVA_OPTS: '-Dexample.other=something.\\\\\$dollar.\\\\\\\slash'
```

## Examples

### Configuration File Example
```yaml
# config/java_opts.yml
---
from_environment: false
java_opts: -Xloggc:$PWD/beacon_gc.log -verbose:gc
```

### Environment Variable Override Examples

To override the configuration via the `JBP_CONFIG_JAVA_OPTS` environment variable, use YAML flow style (inline YAML) with curly braces:

**Example 1: Using an array of options (recommended)**
```bash
cf set-env my-application JBP_CONFIG_JAVA_OPTS '{ java_opts: ["-Xms256m", "-Xmx1024m", "-XX:+UseG1GC"] }'
```

Or in the application manifest:
```yaml
env:
  JBP_CONFIG_JAVA_OPTS: '{ java_opts: ["-Xms256m", "-Xmx1024m", "-XX:+UseG1GC"] }'
```

**Example 2: Disabling from_environment**
```bash
cf set-env my-application JBP_CONFIG_JAVA_OPTS '{ from_environment: false, java_opts: ["-Xmx512m"] }'
```

**Example 3: Multiple JVM options**
```yaml
env:
  JBP_CONFIG_JAVA_OPTS: '{ from_environment: false, java_opts: ["-Xmx512M", "-Xms256M", "-Xss1M", "-XX:MetaspaceSize=157286K", "-XX:MaxMetaspaceSize=314572K"] }'
```

**Note**: For backward compatibility, a space-separated string is also supported:
```yaml
env:
  JBP_CONFIG_JAVA_OPTS: '{ java_opts: "-Xmx512M -Xms256M" }'
```
However, using an array format is recommended for clarity and to avoid parsing ambiguities.

## Allowed Memory Settings

| Argument| Description
| ------- | -----------
| `-Xms` | Minimum or initial size of heap.
| `-Xss` | Size of each thread's stack. **This could effect the total heap size. [JRE Memory]**
| `-XX:MaxMetaspaceSize` | The maximum size Metaspace can grow to. **This could effect the total heap size. [JRE Memory]**
| `-XX:MaxPermSize` | The maximum size Permgen can grow to.  Only applies to Java 7. **This could effect the total heap size. [JRE Memory]**
| `-Xmn <SIZE>` | Maximum size of young generation, known as the eden region.
| `-XX:+UseGCOverheadLimit` | Use a policy that limits the proportion of the VM's time that is spent in GC before an `java.lang.OutOfMemoryError` error is thrown.
| `-XX:+UseLargePages` | Use large page memory. For details, see [Java Support for Large Memory Pages].
| `-XX:-HeapDumpOnOutOfMemoryError` | Dump heap to file when `java.lang.OutOfMemoryError` is thrown.
| `-XX:HeapDumpPath=<PATH>` | Path to directory or filename for heap dump.
| `-XX:LargePageSizeInBytes=<SIZE>` | Sets the large page size used for the Java heap.
| `-XX:MaxDirectMemorySize=<SIZE>` | Upper limit on the maximum amount of allocatable direct buffer memory. **This could effect the total heap size. [JRE Memory]**
| `-XX:MaxHeapFreeRatio=<RATIO>` | Maximum percentage of heap free after GC to avoid shrinking.
| `-XX:MaxNewSize=<SIZE>` | Maximum size of new generation. Since `1.4`, `MaxNewSize` is computed as a function of `NewRatio`.
| `-XX:MinHeapFreeRatio=<RATIO>` | Minimum percentage of heap free after GC to avoid expansion.
| `-XX:NewRatio=<RATIO>` | Ratio of old/new generation sizes. 2 is equal to approximately 66%.
| `-XX:NewSize=<SIZE>` | Default size of new generation.
| `-XX:OnError="<CMD ARGS>;<CMD ARGS>"` | Run user-defined commands on fatal error.
| `-XX:ReservedCodeCacheSize=<SIZE>` | _Java 8 Only_ Maximum code cache size. Also know as `-Xmaxjitcodesize`. **This could effect the total heap size. [JRE Memory]**
| `-XX:SurvivorRatio=<RATIO>` | Ratio of eden/survivor space. Solaris only.
| `-XX:TargetSurvivorRatio=<RATIO>` | Desired ratio of survivor space used after scavenge.

[`config/java_opts.yml`]: ../config/java_opts.yml
[Configuration and Extension]: ../README.md#configuration-and-extension
[Java Support for Large Memory Pages]: http://www.oracle.com/technetwork/java/javase/tech/largememory-jsp-137182.html
[JRE Memory]: jre-open_jdk_jre.md#memory