Document memory settings

This commit adds more details documentation about the memory settings that can
and can not be supplied to the Java buildpack and if the setting is likely to
effect the memory weighting in relation to the total memory provided to an
application.

[#78798560]

Author: Christopher Frost

docs/framework-java_opts.md

@@ -35,5 +35,43 @@ from_environment: false
 java_opts: -Xloggc:$PWD/beacon_gc.log -verbose:gc
 ```
 
+## Memory Settings
+
+The following `JAVA_OPTS` are restricted and will cause the application to fail deployment.
+
+* `-Xms`
+* `-Xmx`
+* `-Xss`
+* `-XX:MaxMetaspaceSize`
+* `-XX:MaxPermSize`
+* `-XX:MetaspaceSize`
+* `-XX:PermSize`
+
+### Allowed Memory Settings
+
+Setting any of the allowed memory settings may require a change to the [Memory Weightings]. Where a value is shown it is the default value for that setting.
+
+| Argument| Description
+| ------- | -----------
+| `-Xmn size` | The size of the heap for the young generation objects, known as the eden region. This could effect the total heap size [Memory Weightings].
+| `-XX:MaxDirectMemorySize=64m` | Upper limit on the maximum amount of allocatable direct buffer memory. This could effect the [Memory Weightings].
+| `-XX:+UseGCOverheadLimit` | Use a policy that limits the proportion of the VM's time that is spent in GC before an OutOfMemory error is thrown. Performance Options.
+| `-XX:HeapDumpPath=./java_pid<pid>.hprof` | Path to directory or filename for heap dump. Manageable.
+| `-XX:-HeapDumpOnOutOfMemoryError` | Dump heap to file when java.lang.OutOfMemoryError is thrown. Manageable.
+| `-XX:OnError="<cmd args>;<cmd args>"` | Run user-defined commands on fatal error.
+| `-XX:OnOutOfMemoryError="<cmd args>;<cmd args>"` | Run user-defined commands when an OutOfMemoryError is first thrown.
+| `-XX:+UseLargePages` | Use large page memory. For details, see Java Support for Large Memory Pages. Debugging Options
+| `-XX:LargePageSizeInBytes=4m` | Sets the large page size used for the Java heap.
+| `-XX:MaxHeapFreeRatio=70` | Maximum percentage of heap free after GC to avoid shrinking.
+| `-XX:MaxNewSize=size` | Maximum size of new generation (in bytes). Since 1.4, MaxNewSize is computed as a function of NewRatio. This could effect the total heap size [Memory Weightings].
+| `-XX:MinHeapFreeRatio=40` | Minimum percentage of heap free after GC to avoid expansion.
+| `-XX:NewRatio=2` | Ratio of old/new generation heap sizes. 2 is equal to approximately 66%.
+| `-XX:NewSize=2m` | Default size of new generation heap region (in bytes). This could effect the total heap size [Memory Weightings].
+| `-XX:ReservedCodeCacheSize=32m (aka -Xmaxjitcodesize)` - Java 8 Only | Reserved code cache size (in bytes) - maximum code cache size. This could effect the [Memory Weightings].
+| `-XX:SurvivorRatio=8` | Ratio of eden/survivor space size. Solaris only.
+| `-XX:TargetSurvivorRatio=50` | Desired percentage of survivor space used after scavenge.
+| `-XX:ThreadStackSize=512` | Thread Stack Size (in Kbytes). (0 means use default stack size)
+
+[Memory Weightings]: jre-open_jdk_jre.md#memory-weightings
 [Configuration and Extension]: ../README.md#configuration-and-extension
 [`config/java_opts.yml`]: ../config/java_opts.yml

java-buildpack.iml

@@ -1,8 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <module type="RUBY_MODULE" version="4">
-  <component name="CompassSettings">
-    <option name="compassSupportEnabled" value="true" />
-  </component>
   <component name="ModuleRunConfigurationManager">
     <configuration default="false" name="All Tests" type="RSpecRunConfigurationType" factoryName="RSpec" singleton="true">
       <predefined_log_file id="RUBY_RSPEC" enabled="true" />
@@ -305,5 +302,4 @@
     <LOAD_PATH number="4" string0="$MODULE_DIR$/lib" string1="$MODULE_DIR$/spec" string2="$MODULE_DIR$/bin" string3="$MODULE_DIR$/spec/bin" />
     <I18N_FOLDERS number="0" />
   </component>
-</module>
-
+</module>