docs: rewrite IMPLEMENTING_JRES.md for BaseJRE pattern#1339
Open
stokpop wants to merge 5 commits into
Open
Conversation
PR cloudfoundry#1288 refactored all standard JREs to embed BaseJRE (14 lines each), but the guide still showed the old 100+ line manual implementation with explicit Supply()/Finalize() boilerplate. Rewrite to document the actual pattern: newBaseJRE() + optional extraFinalizeOpts. Removes sections on manual memory calculator and JVMKill integration (now internal to BaseJRE). Adds variation-point table and examples for all three patterns (standard, exact-dir, error-hint).
…ooting Rebalances the IMPLEMENTING_JRES.md rewrite — adds back lean sections for: - Helper function reference table (GetJREVersion, WriteJavaOpts, etc.) - profile.d script output example - Memory calculator: runtime output and user customization env vars - JVMKill: purpose, heap dump / volume service binding - Troubleshooting: JAVA_HOME, memory calculator, version resolution
- Use Java 21 in version examples and profile.d output - Prefer JBP_CONFIG_<JRE>_JRE for memory calculator config (covers stack_threads, class_count, headroom) - Note MEMORY_CALCULATOR_* env vars take precedence but don't cover class_count - Add stack_threads/class_count/headroom descriptions
There was a problem hiding this comment.
Pull request overview
This PR rewrites docs/IMPLEMENTING_JRES.md to document the newer BaseJRE template-method pattern (introduced in #1288) and remove the older long-form “manual boilerplate” JRE provider implementation guidance.
Changes:
- Replaces large per-provider implementation walkthroughs with a
BaseJREvariation-points model and a short 3-step “how to add a JRE” guide. - Adds concise examples for standard prefix matching, exact-dir matching, and install-error hints.
- Updates operational reference sections (memory calculator, JVMKill, troubleshooting) and refreshes examples to Java 21.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Detection | ||
|
|
||
| ### Version Selection | ||
| `BaseJRE.Detect()` calls `DetectJREByEnv(jreKey)` which returns `true` when: |
…NTING_JRES.md Addresses PR review: - Add missing MemoryCalculatorCommand() to the jres.JRE interface excerpt. - Add the missing `type MinimalJRE` so the no-extra-opts example compiles. - Correct detection/version docs to match DetectJREByEnv/GetJREVersion: the documented JBP_CONFIG_<NAME>_JRE name (recommended) or the auto-generated JBP_CONFIG_<KEY> alias. JBP_CONFIG_COMPONENTS is deprecated and unused for selection; there is no BP_JAVA_<JREKEY> variable.
| ``` | ||
| -Xmx512M -Xms512M -XX:MaxMetaspaceSize=128M -Xss1M -XX:ReservedCodeCacheSize=32M | ||
| ``` | ||
| `stack_threads` — number of user threads (default: 200); affects `-Xss` heap budget. |
| ```bash | ||
| cf env myapp | grep JBP_CONFIG_COMPONENTS | ||
| ``` | ||
| **Wrong Java version selected** — check resolution order: `BP_JAVA_VERSION` → `JBP_CONFIG_<KEY>_JRE` → manifest default. Enable debug: `cf set-env myapp BP_LOG_LEVEL DEBUG`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
IMPLEMENTING_JRES.mdto reflect theBaseJREtemplate-method pattern introduced in PR refactor: extract BaseJRE to eliminate duplication across standard JRE providers #1288What changed
BaseJREautomatically)BaseJREvariation points table, 3-step implementation guide, lean examples for standard/exact-dir/error-hint patternsJBP_CONFIG_<JRE>_JREas preferred (coversstack_threads,class_count,headroom) with a note thatMEMORY_CALCULATOR_*env vars override but don't coverclass_countRelated
Follows #1288 (
BaseJRErefactor that this doc now describes)Please review if complete or must be extended.