Java Compatibility Notes

Spaceport is built to run on the Java Virtual Machine (JVM) and aims for broad compatibility across actively supported Java LTS releases and recent feature releases. These notes will help you choose, upgrade, and configure the right Java version for your development and production environments.

# Supported & Recommended Versions

While Java 8 remains functional, you should plan a migration path to a newer LTS version (11 or 17) for long-term support and security.

## Why Java 11 is the Baseline

Most of the libraries embedded within the Spaceport JAR are compiled to target Java 8 or 11 for maximum compatibility. Operationally, Java 11 provides an excellent balance of maturity, long-term security patch availability, and wide support from hosting providers.

# Running on Modern Java 17+

While Java 11 is a stable baseline, many developers will want to use newer versions like Java 17 to take advantage of modern language features. When upgrading, the most common issue you may encounter relates to the encapsulation of JDK internals.

## The --add-opens Flag for JDK Internals

Starting with Java 9, the Java Platform Module System (JPMS) was introduced, which encapsulated many internal APIs that were previously accessible via reflection. While Java 9 through 11 provided some leniency with these accesses, later versions have tightened these restrictions.

While Spaceport's core does not require access to these internal APIs, the dynamic nature of Groovy and many common Java libraries often relies on deep reflection. It is therefore easy to get into a situation where your own application code or one of its dependencies triggers an access error on Java versions newer than 11.

If your application attempts to access an encapsulated API, you will see a runtime error, typically an java.lang.reflect.InaccessibleObjectException.

To resolve this, you must explicitly grant access using the --add-opens command-line flag when starting Spaceport. This flag tells the JVM to open a specific package within a module for reflective access.

A common flag needed for Groovy applications is:

--add-opens=java.base/java.lang=ALL-UNNAMED

You would add this flag to your startup command like so:

java --add-opens=java.base/java.lang=ALL-UNNAMED -jar spaceport.jar --start config.spaceport

While you can be more specific, opening up core packages like java.base/java.lang to ALL-UNNAMED is often a necessary and practical step to ensure compatibility for applications leveraging Groovy's dynamic features on modern JVMs.

# Other Considerations

## Using New Feature Releases

Spaceport does not depend on incubator modules, so non-LTS feature releases typically "just work." Still, it's wise to perform a quick smoke test:

• Start your application and ensure no module system or reflective access warnings flood the logs.
• Hit a basic Launchpad template route.
• Trigger a Source Module endpoint.
• Store and retrieve a simple Document to verify database connectivity.

If issues appear, it's best to fall back to the most recent LTS version for stability.

## JVM Tuning Quick Start

For most small to medium-sized deployments, the default JVM settings are sufficient. However, you might consider explicit memory sizing if you notice frequent garbage collection pauses under load or if your Source Modules use large in-memory caches.

A conservative starting point for tuning:

java -Xms512m -Xmx1024m -jar spaceport.jar --start config.spaceport

Always add metrics and monitoring to your application before you start tuning the JVM. Tune based on observation, not assumption.

## Verifying Your Runtime

Before launching to production, quickly confirm your environment is set up as expected:

• Run java -version to confirm the vendor and version number.
• (Optional) Run echo $JAVA_HOME to ensure it points to the correct JDK installation, as this helps other command-line tools.
• Start Spaceport and confirm in the logs that it connects successfully to CouchDB without authentication failures.

# Compatibility Summary

For maximum production stability, choose Java 11 or 17. Test newer feature releases locally, but anchor your deployments on an LTS version. When upgrading past Java 11, be prepared to use the --add-opens flag to maintain compatibility for reflective code. This approach ensures your Spaceport application remains dependable while allowing you to adopt JVM improvements at a sustainable pace.

# Next Steps

Now that you understand the Java compatibility landscape for Spaceport, consider exploring these key areas to enhance your application development:

• Explore the Spaceport CLI for managing your application lifecycle.
• Review the Class Enhancements documentation to leverage Groovy extensions in your application.
• Dive into Source Modules to build your application logic.
• Learn about Alerts and Routing to handle HTTP requests effectively.
• Understand Documents for database interactions.