Java Single File Source Code

1. Introduction

JDK 11, which is the implementation of Java SE 11, released in September 2018.

In this tutorial, we’ll cover the new Java 11 feature of launching single-file source-code programs.

2. Before Java 11

A single-file program is one where the program fits in a single source file.

Before Java 11, even for a single-file program, we had to follow a two-step process to run the program.

For example, if a file called HelloWorld.java contains a class called HelloWorld with a main() method, we would have to first compile it:

$ javac HelloWorld.java

This would generate a class file that we would have to run using the command:

$ java HelloWorld
Hello Java 11!

Note that since we already created the .class file through compilation, the java command runs it. As proof, we could change the content we print in our original file, but if we don’t compile it another time, running again the same java command will still print ‘Hello world’.

Such programs are standard in the early stages of learning Java or when writing small utility programs. In this context, it’s a bit ceremonial to have to compile the program before running it.

But, wouldn’t it be great to just have a one-step process instead? Java 11 tries to address this, by allowing us to run such programs directly from the source.

3. Launching Single-File Source-Code Programs

First, let’s point out that in Java 11, we can still compile and run our Java programs as we were used to doing with earlier Java versions.

Additionally, starting in Java 11, we can use the following command to execute a single-file program:

$ java HelloWorld.java
Hello Java 11!

Notice how we passed the Java source code file name and not the Java class to the java command.

The JVM compiles the source file into memory and then runs the first public main() method it finds.

We’ll get compilation errors if the source file contains errors, but otherwise, it will run just as if we’d already compiled it.

Let’s also note that this command is more permissive regarding file name and class name compatibility.

For instance, if we’d rename our file WrongName.java without changing its content, we can run it:

java WrongName.java

This will work, and print the expected result to the console. However, if we try to compile WrongName.java with the ‘javac’ command, we get an error message because the name of the class defined inside the file is not coherent with the name of the file.

That being said, it is still discouraged to not follow the nearly universal naming conventions. Renaming our file or class accordingly should be the way to go.

4. Command-Line Options

The Java launcher introduced a new source-file mode to support this feature. The source-file mode is enabled if one of the following two conditions are true:

1. The first item on the command line followed by the JVM options is a file name with the .java extension
2. The command line contains the –source version option

If the file does not follow the standard naming conventions for Java source files, we need to use the –source option. We’ll talk more about such files in the next section.

Any arguments placed after the name of the source file in the original command line are passed to the compiled class when it is executed.

For example, we have a file called Addition.java that contains an Addition class. This class contains a main() method that calculates the sum of its arguments:

$ java Addition.java 1 2 3

Also, we can pass options likes  –class-path before the file name:

$ java --class-path=/some-path Addition.java 1 2 3

Now, we’ll get an error if there is a class on the application classpath with the same name as the class we are executing.

For example, let’s say at some point during development, we compiled the file present in our current working directory using javac:

$ javac HelloWorld.java

We now have both HelloWorld.java and HelloWorld.class present in the current working directory:

$ ls
HelloWorld.class  HelloWorld.java

But, if we try to use the source-file mode, we’ll get an error:

$ java HelloWorld.java                                            
error: class found on application class path: HelloWorld

5. Shebang Files

It’s common in Unix-derived systems, like macOS and Linux to use the “#!” directive to run an executable script file.

For example, a shell script typically starts with:

#!/bin/sh

We can then execute the script:

$ ./some_script

Such files are called “shebang files”.

We can now execute Java single-file programs using this same mechanism.

If we add the following to the beginning of a file:

#!/path/to/java --source version

For example, let’s add the following code in a file named add:

#!/usr/local/bin/java --source 11

import java.util.Arrays;

public class Addition
{
    public static void main(String[] args) {
        Integer sum = Arrays.stream(args)
          .mapToInt(Integer::parseInt)
          .sum();
        
        System.out.println(sum);
    }
}

And mark the file as executable:

$ chmod +x add

Then, we can execute the file just like a script:

$ ./add 1 2 3
6

We can also explicitly use the launcher to invoke the shebang file:

$ java --source 11 add 1 2 3
6

The –source option is required even if it’s already present in the file. The shebang in the file is ignored and is treated as a normal java file without the .java extension.

However, we can’t treat a .java file as a shebang file, even if it contains a valid shebang. Thus the following will result in an error:

$ ./Addition.java
./Addition.java:1: error: illegal character: '#'
#!/usr/local/bin/java --source 11
^

One last thing to note about shebang files is that the directive makes the file platform-dependent. The file will not be usable on platforms like Windows, which does not natively support it.

6. Conclusion

In this article, we saw the new single file source code feature introduced in Java 11.