.JAVA File Format – File structure

Characters and encoding

The language is defined over Unicode characters, held as UTF-16 code units (JLS 3.1). Characters outside the Basic Multilingual Plane, such as emoji, are two code units, a surrogate pair. Which characters count as letters and digits in identifiers follows the Unicode version of the JDK’s Character class, Unicode 17.0 since JDK 26.

The bytes of the file are decoded by the compiler before the language sees them:

A file written on an older Windows system in a legacy code page can therefore fail to compile, or compile with different string contents, on JDK 18 and later; the fix is to pass its real encoding with -encoding, or to convert the file to UTF-8. Build tools such as Maven and Gradle have their own settings for the source encoding.

Any character can also be written in pure ASCII with a Unicode escape, such as \u00e9 for é, so a file that uses only escapes reads the same in every encoding.

How the compiler reads the text

The raw characters are translated in three steps (JLS 3.2), each working on the output of the one before:

1. Unicode escapes (\u followed by four hexadecimal digits) are replaced by the characters they stand for. This happens first, everywhere in the file, including inside comments and string literals.
2. The stream is split into lines at line terminators.
3. The lines are split into input elements: white space, comments and tokens (identifiers, keywords, literals, separators and operators). These are described on the Lexical structure page.

At each step the longest possible translation is taken. So a--b is read as a, --, b, which is not a valid expression, even though a - -b would be. The one exception is the closing angle brackets of type arguments: in List<List<String>> the >> is split into two > tokens.

Unicode escapes

UnicodeEscape:
    \ UnicodeMarker HexDigit HexDigit HexDigit HexDigit

UnicodeMarker:
    u {u}

• Several us are allowed: \uuuu0041 is A. Tools that convert a file to ASCII add a u to escapes that were already there, so the conversion can be undone.
• A backslash only starts an escape if it is preceded by an even number of backslashes (counting zero). In "\\u2122" the second backslash is escaped by the first, so the string is the six characters \u2122.
• A \ followed by one or more us but not by four hexadecimal digits is a compile-time error, even in a comment.
• An escape produces exactly one UTF-16 code unit. A supplementary character needs two escapes, one for each half of the surrogate pair: "\uD83D\uDE00".

Because escapes are replaced before anything else, they can change the structure of the program:

char newline = '\u000a';   // error: the escape becomes a real line break
char newline = '\n';       // correct: an escape sequence, handled later

// The comment below ends early, because \u000a is a line terminator:
// \u000a System.out.println("this line runs");

Line terminators

A line ends with a carriage return (CR, \u000d), a line feed (LF, \u000a) or CR followed by LF, which counts as one terminator (JLS 3.4). All three may be mixed in one file. Line numbers in error messages and in the LineNumberTable of the compiled class count these terminators.

Inside a text block, every line terminator becomes a single LF in the string, whatever the file uses, so the value of a text block does not depend on how the file was saved.

As a concession to old systems, an ASCII SUB character (\u001a, Ctrl-Z) is ignored if it is the very last character of the file (JLS 3.5).

The three kinds of compilation unit

CompilationUnit:
    OrdinaryCompilationUnit
    CompactCompilationUnit
    ModularCompilationUnit

OrdinaryCompilationUnit:
    [PackageDeclaration] {ImportDeclaration} {TopLevelClassOrInterfaceDeclaration}

CompactCompilationUnit:
    {ImportDeclaration} {ClassMemberDeclarationNoMethod} MethodDeclaration {ClassMemberDeclaration}

ModularCompilationUnit:
    {ImportDeclaration} ModuleDeclaration

Every compilation unit implicitly imports the public types of java.lang, as if it began with import java.lang.*; (JLS 7.3). An empty file is a valid ordinary compilation unit.

package com.example.shapes;

import java.util.ArrayList;
import java.util.List;
import static java.lang.Math.PI;

public sealed interface Shape permits Circle, Square {
    double area();
}

record Circle(double r) implements Shape {
    public double area() { return PI * r * r; }
}

record Square(double side) implements Shape {
    public double area() { return side * side; }
}

String greeting = "Hello";

void main() {
    String name = IO.readln("Your name: ");
    IO.println(greeting + ", " + name);
    List<Integer> squares = Stream.of(1, 2, 3).map(n -> n * n).toList();
    IO.println(squares);
}

import com.example.spi.Plugin;

/** The shapes library. */
module com.example.shapes {
    requires transitive java.desktop;
    requires static com.example.annotations;
    exports com.example.shapes;
    exports com.example.shapes.internal to com.example.tests;
    opens com.example.shapes.model;
    uses Plugin;
    provides Plugin with com.example.shapes.ShapePlugin;
}

package-info.java

Annotations on a package, and the package’s documentation comment, go in a file named package-info.java in the package’s folder (JLS 7.4.1 recommends this scheme). Only one annotated package declaration is allowed for each package. The file holds the documentation comment, the annotations, the package declaration and any imports the annotations need, and no classes; package-info is not a legal class name. It compiles to package-info.class.

/**
 * Shapes and their areas.
 */
@NullMarked
package com.example.shapes;

import org.jspecify.annotations.NullMarked;

File names and folders

The specification leaves storage to the host. When packages are stored in a file system, it allows the compiler to require that a type is in a file named after it, with an extension such as .java, if the type is public or is used from other files (JLS 7.6). javac enforces this for public types:

Package names are conventionally lower case and start with a reversed internet domain (com.example), so the folder names are lower case too.

What the compiler writes

javac writes one .class file for every class and interface in the source, including nested ones. The names below are those javac chooses; the language only fixes the binary names of member types (JLS 13.1).

Lambda bodies are compiled into private methods of the enclosing class, not into class files of their own.

Running a source file directly

The java launcher can compile and run source without a separate javac step:

The #! line is not Java; a file that starts with one cannot be compiled by javac.