rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat java-launcher.md

java — the launcher

# The java launcher — running classes, jars, modules and source files, plus the JVM flag families that matter.

Conceptsaved 2026-08-09 #java#jdk#tooling#jvm

Overview

java starts a JVM and runs a main class — given as a class name on the classpath, a -jar with a Main-Class manifest entry, a -m module/class on the module path, or, since JEP 330, a plain .java source file compiled in memory. It is also where all JVM configuration lands: heap sizing, GC selection, and the -X/-XX flag families.

Key points

  • Four launch modes: java -cp … Main, java -jar app.jar, java -p mods -m app.mod/app.Main, and java Main.java (source-file mode).
  • Source launcher: JEP 330 (Java 11) runs a single file without explicit compilation; JEP 458 (Java 22) extends it to multi-file programs — neighbouring .java files are compiled on demand. Great for scripts; pairs with shebang lines.
  • Flag families: -D sets system properties; -X flags are non-standard but stable (-Xmx, -Xms, -Xss); -XX flags are HotSpot-specific (-XX:+UseZGC, -XX:MaxRAMPercentage). java -XX:+PrintFlagsFinal lists effective values.
  • Heap sizing: -Xmx/-Xms absolute, or container-friendly -XX:MaxRAMPercentage — the JVM is container-aware and reads cgroup limits.
  • GC selection: -XX:+UseG1GC (default), -XX:+UseZGC (generational ZGC on recent JDKs), -XX:+UseParallelGC, -XX:+UseSerialGC; pick by pause vs throughput goals.
  • --enable-preview: required to run class files compiled with preview features, and they only run on the exact JDK version that compiled them.
  • @argfiles: java @flags.txt Main reads options from a file — how build tools and scripts keep long flag lists manageable.
  • JAVA_TOOL_OPTIONS: environment variable prepended to the command line by any JVM — the standard way to inject flags (agents, heap settings) in containers/CI without editing launch scripts; JDK_JAVA_OPTIONS is the launcher-only equivalent.

Examples

java -Xmx2g -XX:+UseZGC -XX:+HeapDumpOnOutOfMemoryError -jar app.jar
java Script.java arg1            # JEP 330 source-file mode
java @jvmflags.txt -m app/app.Main

Related

  • The JDK, the JRE & their tools — parent catalog of the toolchain.
  • javac — the compile side; --release and --enable-preview must agree.
  • jcmd — change/inspect many of these knobs on a live JVM.
  • Deep dive Java — the GC and JIT machinery these flags configure.