JEP 512 Explained: Compact Source Files and Simpler Java Programs

JEP 512 Explained: Compact Source Files and Simpler Java Programs explores how Java 25 reduces boilerplate using compact source files, instance #main() methods, automatic imports, and simpler console I/O—making Java easier to learn and write while preserving its core design principles.

• 1. Introduction to JEP 512
• 2. What are compact source files in Java 25?
• 3. Instance #main() methods: A new way to start Java programs
• 4. What do the compiler and JVM do behind the scenes?
• 5. Console I/O made simpler with java.lang.IO
• 6. Design Choices Behind JEP 512
• 7. Rules and Limitations of JEP 512
• 8. When JEP 512 Is a Good Fit (and When It Is Not)
• 9. Conclusion

1. Introduction to JEP 512

For decades, Java has been known for its explicit and structured nature. While this has always been one of Java’s biggest strengths—especially for large, maintainable systems—it has also made the language feel verbose, particularly for very small programs.

Even the simplest Java program requires multiple mandatory elements: a class, a main method, and boilerplate syntax. This is not wrong, but it does create friction in certain situations.

In classic Java, every executable program must be wrapped inside a class and must declare a public static void main(String[] args) method.

A minimal program looks like this:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

This structure enforces discipline and clarity, but it also means:

1. We write more syntax than logic

2. Beginners must understand multiple concepts upfront:

• Classes
• Access modifiers
• Static methods
• Method signatures

For experienced developers, this is routine. For newcomers, it often feels overwhelming.

1.1. The “Hello World” problem for beginners

The first program a learner writes is supposed to build confidence. However, in Java, the very first step already introduces several advanced ideas at once.

From a beginner’s perspective:

• Why do we need a class?
• What does static mean?
• Why is String[] args required?

None of these are needed to understand printing a line to the console, yet they are unavoidable. This is commonly referred to as the “Hello World problem”—the gap between what we want to do and what Java forces us to learn first.

1.2. Goal of JEP 512 — In simple words

JEP 512 addresses this exact pain point. The goal is not to replace Java’s object-oriented model or remove structure. Instead, it aims to:

1. Make small programs simpler
2. Reduce boilerplate for entry-level code
3. Improve Java’s usability for:

• Beginners
• Teaching
• Quick experiments
• Scripts and demos

In simple terms: JEP 512 allows us to write small Java programs without immediately worrying about classes and static main methods—while keeping Java’s core principles intact.

2. What are compact source files in Java 25?

Compact Source Files are a source-level enhancement introduced by JEP 512 to make Java simpler for small programs. The idea is straightforward: when a program is small and self-contained, Java should not force developers—especially beginners—to deal with concepts that are not immediately necessary.

In the Java language, every class resides in a package, and every package belongs to a module. Packages and modules exist to provide namespacing and encapsulation, which are critical for building large, maintainable systems. However, small programs that consist of just a few lines of code do not benefit much from these concepts. Recognizing this, Java has always allowed developers to omit package and module declarations, placing such code in the unnamed package of the unnamed module.

JEP 512 extends this same philosophy to class declarations.

Traditionally, Java required every field and method to be declared inside a class. While this is essential for object-oriented design, it introduces additional mental overhead for beginners. Before printing a single line, learners are forced to encounter ideas such as classes, access modifiers, and static methods—concepts that are not required to understand variables, control flow, or simple logic.

With Compact Source Files, we can now write small Java programs that focus purely on the fundamentals:

• Variables and expressions
• Conditional logic and loops
• Simple method-like behavior without a full class structure

A compact source file is simply a .java file that contains top-level code, without any explicit class declaration. For example:

void main() {
    int x = 5;
    int y = 10;
    System.out.println(x + y);
}
Output: 15

This is a valid Java program in Java 25. The code is direct, readable, and free from structural boilerplate that adds little value at this scale.

Compact source files are intentionally designed for small programs. They work best for:

• Learning and teaching Java
• Writing short examples or demos
• Quick experiments and throwaway utilities

They are not meant to replace traditional Java structure. As applications grow, proper use of classes, packages, and modules remains essential for maintainability and clarity.

In essence, compact source files recognize a simple reality: small programs do not need big abstractions on day one. They allow us to start simple and adopt Java’s full structural power only when the code truly needs it.

3. Instance #main() methods: A new way to start Java programs

With compact source files, Java removes the need for an explicit class declaration—but a Java program still needs a clear entry point. This is where instance #main() methods come in. JEP 512 introduces a simplified way to define the starting point of a program without relying on the traditional public static void main(String[] args) signature.

Instead of treating main as a static method tied to a class, Java now allows #main() to be written as an instance method. This keeps Java’s execution model intact while significantly reducing boilerplate for small programs.

In this new model, the program starts by implicitly creating an instance and then invoking its #main() method. From a developer’s perspective, this feels more natural—especially for beginners—because it avoids concepts like static, access modifiers, and method signatures that are not immediately relevant when learning basic programming.

Key characteristics of instance #main() methods include:

• The method name must still be main
• The method can be non-static
• No command-line arguments are required
• The return type is void

This allows us to write programs that focus directly on logic, without structural noise.

Because the execution still begins at a method boundary, Java preserves:

• A well-defined program entry point
• Predictable stack frames
• Compatibility with debugging and tooling models

In other words, Java becomes simpler at the surface while remaining disciplined underneath.

Instance #main() methods are especially useful for:

• Learning and teaching Java fundamentals
• Writing short, self-contained programs
• Experimenting with language features

At the same time, they do not replace the traditional main method for real-world applications. As programs grow and require configuration, arguments, or a clearer structure, the classic public static void main(String[] args) remains the preferred approach.

Instance #main() methods strike a careful balance: they reduce ceremony without compromising Java’s execution principles.

4. What do the compiler and JVM do behind the scenes?

Even with the simplifications introduced by JEP 512, Java’s startup model remains firmly grounded in its existing rules. The Java launcher still starts the JVM and then looks for a launchable main method in the target class. What changes with JEP 512 is how that class comes into existence and how the launcher chooses which main method to invoke.

When a compact source file is compiled, the compiler implicitly declares a class on our behalf. This class is not visible in source code, has no usable name, and exists only so that the JVM and launcher can operate exactly as they always have.

From the launcher’s perspective, program startup follows a strict and well-defined protocol:

• If a class declares or inherits a main(String[] args) method, that method is chosen.
• Otherwise, if the class declares or inherits a no-argument main() method, that method is chosen.
• If neither exists, the launcher reports an error and terminates.

Once a main method is chosen, invocation depends on whether the method is static or instance-based. If the method is static, the launcher invokes it directly. If the method is an instance #main(), the launcher first creates an object and then invokes the method on that object. For this to work, the class must have a non-private, no-argument constructor; otherwise, startup fails.

Any main method that can be selected and invoked under these rules is known as a launchable main method.

4.1. The Implicit Class of a compact source file

A compact source file always declares a class implicitly. Although we never write the class declaration, the compiler guarantees that this implicit class has a predictable shape.

The implicitly declared class:

• Is a final top-level class in the unnamed package
• Extends java.lang.Object and implements no interfaces
• Has a default no-argument constructor and no other constructors
• Contains all fields and methods written in the compact source file
• Must define a launchable main method, or compilation fails

Because this class has no source-level name, the compiler generates a class name internally. That name is implementation-specific and must never be relied upon—not even inside the compact source file itself.

4.2. How instance #main() works at runtime

Consider this compact source file:

void main() {
    System.out.println("Hello, World!");
}

At runtime, the launcher:

• Starts the JVM
• Identifies the implicit class generated by the compiler
• Detects that the class has a no-argument instance main()
• Creates an instance using the default constructor
• Invokes #main() on that instance

This explains why instance #main() methods work without changing the JVM. The launcher already knows how to invoke instance methods—it simply follows existing rules.

4.3. Fields, methods, and this in compact source files

Because all fields and methods belong to the implicitly declared class, they behave exactly like instance members. This allows us to write code that feels simple and local, without introducing object-oriented syntax explicitly.

For example, we can call a nearby method:

String hello() {
    return "Java, HandsOn!";
}

void main() {
    System.out.println(hello());
}
Output: Java, HandsOn!

Or access a field directly:

String hello = "Java, HandsOn!";

void main() {
    System.out.println(hello);
}
Output: Java, HandsOn!

In all cases, this refers to the current instance of the implicit class. We may use this explicitly or implicitly, but we cannot instantiate the class using the new keyword because the class has no source-level name.

This reflects a deliberate design choice: if beginners have not yet learned about classes, object creation should not be required just to write simple programs.

4.4. Why this design matters

JEP 512 carefully balances simplicity with discipline:

• The JVM and launcher remain unchanged
• Startup rules stay predictable and debuggable
• Java avoids becoming a script-based language
• Beginners can focus on logic before structure

In short, compact source files and instance main() methods simplify how we write Java programs, while preserving exactly how Java programs are launched and executed.

5. Console I/O made simpler with java.lang.IO

Writing programs that interact with the console is often the very first step for beginners. Printing output or reading user input should be simple and intuitive. However, traditional Java has never made this easy. Even something as basic as printing a line requires calling System.out.println, which immediately raises questions for new learners: What is System? What is out? Why is printing not just a simple method call?

Reading from the console is even more intimidating. While it seems natural to expect input to come from System.in, obtaining a single line of text requires a significant amount of boilerplate code. Developers must deal with streams, readers, exception handling, and checked exceptions—concepts that are far removed from the goal of simply reading a string from the user.

Experienced developers are accustomed to this complexity, but for beginners, it introduces unnecessary friction and confusion at the very moment when they should be building confidence.

To address this, JEP 512 introduces a new class: java.lang.IO.

The IO class provides a small set of straightforward, line-oriented methods designed specifically for basic console interaction. Instead of navigating streams and exception handling, we can now express our intent directly.

The class defines the following static methods:

• IO.print(Object obj)
• IO.println(Object obj)
• IO.println()
• IO.readln(String prompt)
• IO.readln()

These methods cover the most common console I/O needs while keeping the API intentionally minimal.

With java.lang.IO, Printing to the console looks exactly like what beginners expect it to look like:

void main() {
    IO.println("Java, HandsOn!");
}
Output: Java, HandsOn!

There is no indirection, no mysterious fields, and no streams involved. We are simply printing a line of text.

Reading user input is now equally straightforward. Instead of multiple classes and a try-catch block, we can read a line of input with a single method call:

void main() {
    String name = IO.readln("Please enter website name: ");
    IO.print("Great website to learn java, ");
    IO.println(name);
}
Output:
Please enter website name: https://javahandson.com/
Great website to learn java, https://javahandson.com/

This code is easy to read and easy to explain. The intent is immediately clear, even to someone who has just started learning Java.

5.1. Why the IO qualifier is a good thing

Beginners do need to learn that the methods are accessed through the IO qualifier, but this is not an unreasonable burden. They will encounter qualified method calls very early anyway—such as Math.sin(x) for mathematical operations.

In this sense, IO.print and IO.readln fit naturally into Java’s existing style, without introducing new concepts or special syntax.

5.2. Scope of java.lang.IO

The IO class resides in the java.lang package, which means it is automatically available without any import statement. This applies to all Java programs, not just compact source files or those using instance main() methods.

For example, the same simplified I/O works perfectly in traditional Java code:

class Hello {
    public static void main(String[] args) {
        String name = IO.readln("Please enter website name: ");
		IO.print("Great website to learn java, ");
		IO.println(name);
    }
}

This makes java.lang.IO a general improvement to Java’s usability, not a feature limited to beginners or new syntax styles.

By introducing java.lang.IO, Java removes one of the most common early stumbling blocks:

• No streams for basic input/output
• No checked exceptions for simple console interaction
• Clear, readable code from the very first program

Together with compact source files and instance #main() methods, simplified console I/O helps Java feel approachable without being diluted.

6. Design Choices Behind JEP 512

JEP 512 looks simple on the surface, but its design reflects several careful decisions made by the Java platform team. Each feature in this proposal was chosen not just to reduce syntax, but to ensure that small programs can grow naturally into fully structured Java applications.

This section explores the key design choices behind JEP 512. We look at how compact source files gain access to core Java APIs, how small programs can evolve into regular Java code, and which alternative designs were deliberately rejected. Together, these choices explain why JEP 512 simplifies Java without turning it into a different language.

6.1. Automatic imports in compact source files

Compact source files are designed to reduce setup work for very small programs. One common source of friction for beginners is import statements, which often appear before learners understand what they are importing.

To address this, Java 25 treats every compact source file as if it has access to the java.base module by default. Conceptually, this is similar to having the following declaration present:

import module java.base;

This makes all public types exported by java.base available without explicit imports. As a result, commonly used classes such as List can be used directly:

void main() {
    var names = List.of("Suraj", "Shweta", "Iqbal", "Reshma", "Kartik", "Shrunalini");
    for (var name : names) {
        IO.println(name + ": " + name.length());
    }
}
Output:
Suraj: 5
Shweta: 6
Iqbal: 5
Reshma: 6
Kartik: 6
Shrunalini: 10

This works because List belongs to java.util, which is exported by java.base. The same rule applies to frequently used packages like java.io, java.math, and java.time.

This automatic access applies only to compact source files. Regular Java source files still require explicit imports, preserving clarity as programs grow.

6.2. Growing a compact program into a regular Java program

Compact source files are intended as a starting point, not a separate programming model. Code written in a compact source file is treated as belonging to an ordinary Java class that is declared implicitly.

As a program grows, the implicit structure can be made explicit with minimal change. For example, the following compact program:

void main() {
    var names = List.of("Suraj", "Shweta", "Iqbal", "Reshma", "Kartik", "Shrunalini");
    for (var name : names) {
        IO.println(name + ": " + name.length());
    }
}

can be converted into a regular Java class by simply adding a class declaration:

import module java.base;

class NameLengths {
    void main() {
        var names = List.of("Suraj", "Shweta", "Iqbal", "Reshma", "Kartik", "Shrunalini");
		for (var name : names) {
			IO.println(name + ": " + name.length());
		}
    }
}

The program logic and the main() method remain unchanged. This allows learners to adopt structure gradually, without rewriting working code.

6.3. Trade-offs and Design Decisions

JEP 512 focuses on making small Java programs easier to write, but it does not try to remove structure completely. The design deliberately avoids shortcuts that would make Java harder to understand or harder to grow later.

One idea that was considered was allowing top-level statements, where the entire file would act like the body of a hidden main method. This would remove even the need to declare main(). However, this approach would make it impossible to define methods or reusable logic. All code would be forced into a single hidden scope, which would quickly become limiting and confusing.

Another idea was to allow console output without any qualifier, such as calling println() directly instead of IO.println(). While this looks simpler, it would make compact programs harder to convert into regular Java programs later. It would also blur the line between language features and library APIs.

Java also rejected the idea of automatically importing only a small set of packages. Deciding which packages deserve special treatment would be arbitrary and difficult to maintain. By making the entire java.base module available instead, Java applies one clear and consistent rule.

Using JShell as the foundation was considered as well. JShell is excellent for experimentation, but it does not represent a complete Java program that can be compiled, versioned, and maintained over time.

Finally, Java deliberately avoided creating a separate “compact Java” dialect. A different dialect might allow even shorter programs, but it would create a gap between learning Java and writing real Java applications. JEP 512 ensures that compact source files are simply another way to write standard Java code.

In short, the design of JEP 512 favors simplicity without shortcuts. It makes Java easier to start with, while keeping the language predictable and consistent as programs grow.

7. Rules and Limitations of JEP 512

a. Every compact source file must define a launchable main method – A compact source file is still a complete Java program, which means execution must start from a valid main method. This can be either the traditional main(String[] args) or a no-argument main(). If neither form is present, compilation fails.

b. Java does not allow free-floating statements at the top level – Even though class declarations are implicit, Java still requires execution to begin inside a method. This preserves a clear and predictable program entry point.

c. Each compact source file corresponds to an implicit class – Although the class is not written in the source code, it still exists. All fields and methods declared in the file become members of this implicit class.

d. The implicit class has no source-level name and cannot be instantiated – Because the class has no visible name, it cannot be created using the new keyword. This is intentional and reinforces that compact source files are for using Java, not for defining object models.

e. The this reference is available and refers to the implicit instance – Methods and fields behave like instance members, and this works as expected. This allows simple programs to feel natural without explicitly introducing object-oriented syntax.

f. JEP 512 is a preview feature in Java 25 – It is not enabled by default and requires preview flags during compilation and execution. The feature may still evolve in future Java releases.

g. Tooling support may be incomplete – IDEs and build tools often assume traditional Java structure unless configured explicitly. This can result in warnings or confusing suggestions, especially for beginners.

h. Compact source files are not suitable for large or long-lived applications – As programs grow, the lack of explicit class names, packages, and clear API boundaries becomes a limitation rather than a benefit.

8. When JEP 512 Is a Good Fit (and When It Is Not)

a. JEP 512 is well-suited for learning and teaching Java – By reducing boilerplate, learners can focus on logic, control flow, and problem-solving before being introduced to structure and modifiers.

b. It works best for short examples and demonstrations – When explaining a single idea, compact source files keep the example readable and uncluttered.

c. It is useful for quick experiments and small utilities – For throwaway programs or exploratory code, compact syntax allows faster iteration without setup overhead.

d. JEP 512 should be avoided in production systems – Large applications benefit from explicit classes, packages, and clear entry points, which compact source files intentionally omit.

e. It is not appropriate for libraries or shared codebases – Reusable code relies on well-defined APIs and structure, which are outside the scope of compact source files.

f. The right mental model is to treat JEP 512 as a starting point – Developers can begin with compact source files and move naturally to regular Java classes as programs grow, without rewriting logic.

9. Conclusion

JEP 512 Explained: Compact Source Files and Simpler Java Programs shows a clear shift in how Java approaches beginners and small programs. Instead of forcing every program to start with classes, static, and boilerplate, Java now allows us to begin with simpler code while still following the same execution rules behind the scenes.

Compact source files, instance main() methods, simplified console I/O, and automatic access to core platform classes all work together to reduce friction at the starting point. These features do not turn Java into a scripting language, nor do they introduce a separate dialect. They simply remove concepts that are not immediately necessary when writing small programs.

At the same time, JEP 512 carefully preserves Java’s biggest strength: its ability to grow. Code written using compact source files can easily evolve into regular Java programs by adding explicit classes and structure when needed. There is no rewrite, no loss of meaning, and no change in execution behavior.

In the end, JEP 512 is about balance. It makes Java easier to start, easier to teach, and easier to explain—without weakening the language or breaking its core principles. Used in the right places, it helps Java feel more approachable while remaining just as powerful and reliable as ever.

Further Reading

For the official specification and detailed design discussion behind compact source files and instance main methods, see:

• JEP 512: Compact Source Files and Instance Main Methods – OpenJDK
  This JEP explains how Java 25 reduces ceremony for small programs by allowing simpler source files and instance-based main methods, while keeping the language fully backward compatible.

What’s Next

Compact source files make Java easier to approach and quicker to use for small programs, scripts, and learning scenarios, without changing how larger applications are structured.

In the next chapter, we return to core language semantics and object construction.

Flexible Constructor Bodies (JEP 513) improves how constructors are written by relaxing ordering constraints and making initialization logic clearer, more readable, and easier to reason about—especially in complex class hierarchies.