The Java source file (.java)

The basics

What is a JAVA file?

Anatomy

What's inside a Java file

A Java file holds one or more classes, and all code lives inside a class. The order is fixed: an optional package line, then imports, then the classes. Here is a small program in a package, part by part.

package com.example.greet;

import java.time.LocalTime;

/** Greets people according to the time of day. */
public class Greeter {
    private final String name;

    public Greeter(String name) {
        this.name = name;
    }

    public String greet(LocalTime time) {
        String part = time.getHour() < 12 ? "morning" : "afternoon";
        return "Good " + part + ", " + name + "!";
    }

    public static void main(String[] args) {
        String who = args.length > 0 ? args[0] : "Ada";
        Greeter greeter = new Greeter(who);
        System.out.println(greeter.greet(LocalTime.now()));
    }
}

1. 1package com.example.greet;

   The package

   Names the namespace the class belongs to, and by convention the folder it sits in: com/example/greet/. Without a package line, the class is in the unnamed package, which is fine for small programs.

2. 2import java.time.LocalTime;

   An import

   Lets the file write LocalTime instead of java.time.LocalTime. Classes in java.lang, such as String and System, never need importing.

3. 3/** Greets people … */

   A Javadoc comment

   Starts with /**. The javadoc tool turns these into HTML documentation, and editors show them on hover.

4. 4public class Greeter {

   A public class

   Because it's public, the file must be called Greeter.java, exactly, including the capital G. A file can hold other classes, but only one public top-level one.

5. 5private final String name;

   A field

   Data each Greeter object carries. private hides it from other classes; final means it's set once, in the constructor.

6. 6public Greeter(String name) { … }

   A constructor

   Has the class's name and no return type. new Greeter("Ada") calls it.

7. 7public String greet(LocalTime time)

   A method

   Every parameter and return value has a declared type, checked by the compiler.

8. 8public static void main(String[] args)

   The entry point

   Where the program starts. static means it runs without an object; args holds the words typed after the class name on the command line.

9. 9System.out.println(…);

   Output

   Prints a line to the terminal. Every statement ends with a semicolon.

How to

How to compile and run a .java file

# Compile: the .java source becomes .class bytecode
javac Hello.java               # writes Hello.class
java Hello                     # run it: the class name, no extension

# With a package, compile into a folder tree and name the full class
javac -d out com/example/greet/Greeter.java
java -cp out com.example.greet.Greeter

# Skip the compile step (Java 11+): compiled in memory, nothing written
java Hello.java

# Package it as a JAR and run that
jar --create --file greet.jar --main-class com.example.greet.Greeter -C out .
java -jar greet.jar

app/
├── Main.java      class Main uses Helper
└── Helper.java    class Helper

java app/Main.java    # Java 22+: also finds and compiles Helper.java

Rules

The file-name rule, packages and folders

Versions

Java versions that matter, and compact source files

// Hello.java: a compact source file (Java 25)
void main() {
    String name = IO.readln("Name? ");
    IO.println("Hello, " + name + "! " + List.of(1, 2, 3));
}

Related formats

.java vs .class vs .jar, and other Java files

Troubleshooting

The Java errors people hit most

How to

How to open and edit a .java file, and is it safe?

Free downloads

Sample Java files to download

Free sample Java files for testing compilers, IDEs, CI pipelines, syntax highlighters and upload filters. Every sample except the deliberately broken one compiles with javac -Xlint:all -Werror and runs on Java 21 and Java 25, both compiled and with java file.java. The classes aren't public, so the hyphenated file names compile as they are.

Loading…

What's inside sample-program.java

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Run it with java sample-program.java, or compile it with javac sample-program.java and run java SampleProgram.

1. Comments 1 and 2: imports and the class

   Five imports, then a final class that isn't public, with a note on why: a public class would need the file to be called SampleProgram.java.

2. Comments 3 to 5: an enum, a switch expression and a record

   A Category enum with a static method that uses an arrow switch expression, and an Expense record with a compact constructor that rejects negative amounts.

3. Comments 6 and 8: exceptions

   A checked ParseException that parseLine must declare with throws, and an unchecked NumberFormatException caught and turned into it.

4. Comments 7 and 9: data and arithmetic

   A text block holds five input lines, one of them invalid. parseCents keeps money in whole cents with Math.multiplyExact, which throws instead of overflowing silently.

5. Comments 10 to 12: main, generics and streams

   main uses var and List<Expense>, catches the bad line and prints it to standard error, then groups totals with a stream into a TreeMap. Output: €49.75 for Ada Example, €138.90 for Ben Example.

6. What javac writes

   Compiling produces four class files: SampleProgram.class plus SampleProgram$Category.class, SampleProgram$Expense.class and SampleProgram$ParseException.class for the nested types.

All sample Java files

• Commented sample program

  sample-program.java · 5.6 KB (5,713 bytes)

  A complete program for Java 17 or later: an enum, a record, a switch expression, a text block, checked and unchecked exceptions, generics, streams and lambdas, with numbered comments explaining each part.

  • Checking a JDK, IDE or CI job compiles and runs Java
  • Teaching the parts of a Java program
  DownloadOpen

• Java 21 syntax

  sample-java21.java · 3.0 KB (3,066 bytes)

  A sealed interface with three records, a switch with record patterns and when guards, sequenced collections and 1,000 virtual threads. Compiles on Java 21 or later and fails on Java 17, so it shows which Java a tool really uses.

  • Checking parsers, linters and highlighters on current syntax
  • Testing which Java version a build server uses
  DownloadOpen

• UTF-8 text with CRLF line endings

  sample-unicode-crlf.java · 2.4 KB (2,463 bytes)

  Windows line endings and six sample strings (Latin, Greek, Japanese, Arabic, emoji), saved as UTF-8 without a BOM. Prints length() (UTF-16 units) next to the real character and byte counts, and shows that a text block's line endings become \n.

  • Testing encoding handling in editors, compilers and pipelines
  • Showing why `length()` miscounts emoji
  DownloadOpen

• Deliberately broken file (does not compile)

  sample-compile-error.java · 1.2 KB (1,228 bytes)

  Clearly labelled at the top: javac reports three errors, the public-class file-name rule, a lossy double to int conversion and a misspelt method, and the comments give the fix for each.

  • Checking how IDEs and CI jobs report compile errors
  • Teaching the most common javac messages
  DownloadOpen

Ways to test with them

• JDK and CI: compile sample-program.java and sample-java21.java with javac -Xlint:all; both should compile without warnings. sample-compile-error.java should fail with exactly 3 errors and write no class files.
• Version checks: compile sample-java21.java with javac --release 17. It fails, because pattern matching in switch needs Java 21; with --release 21 it compiles.
• Encoding: run sample-unicode-crlf.java; the six sample strings should come out readable. A ? instead of letters points at the terminal's encoding, not the file.
• Locale: run sample-java21.java with -Duser.language=nl; the areas print as 6,00 instead of 6.00, because formatted() follows the locale.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

Java files, frequently asked