Why Java feels familiar#

What transfers unchanged#

Your first job on a Java team is often to read code, not to write it. Here is the service that places orders in an online shop, first in C# and then in Java. The C# version is the kind of class you write every week.

// The parameter list after the class name is a primary constructor.
public sealed class OrderService(IOrderRepository repository)
{
    public async Task<Order> PlaceAsync(Customer customer, List<OrderLine> lines)
    {
        if (lines.Count == 0)
            throw new ArgumentException("An order needs at least one line.");
        var order = new Order(customer, lines);
        await repository.SaveAsync(order);
        return order;
    }
}

public final class OrderService {
    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public Order place(Customer customer, List<OrderLine> lines) {
        if (lines.isEmpty())
            throw new IllegalArgumentException("An order needs at least one line.");
        var order = new Order(customer, lines);
        repository.save(order);
        return order;
    }
}

Classes, constructors, exceptions, generics such as List<OrderLine>, and var all carry over one to one. That resemblance is real, and it is also the danger: it makes it easy to write Java as if it were C#. The next section shows where that goes wrong.

The six things that will actually cost you time#

Here is a small invoice class that shows four of the six at once. It loads a template from disk and saves itself through a repository field, left out to keep it short. Read the C# side first, then compare it line by line with the Java side.

public class Invoice
{
    public Money Total { get; set; }

    // No modifier, so this is private by default.
    string LoadTemplate(string path) =>
        File.ReadAllText(path);

    public async Task SaveAsync() =>
        await repository.SaveAsync(this);
}

public class Invoice {
    private Money total;
    public Money getTotal() { return total; }

    String loadTemplate(Path path) throws IOException {
        return Files.readString(path);
    }

    public void save() { repository.save(this); }
}

The other two traps do not fit in a class. Java removes generic type arguments when it compiles, a step called type erasure, so at run time a list does not know what it holds. And the build is run by a separate tool, Maven or Gradle, rather than by the IDE.

static string NameOf<T>() => typeof(T).Name;

NameOf<int>();                             // "Int32": T is known at run time

object xs = new List<int>();
Console.WriteLine(xs is List<string>);     // False: the type argument is checked

Here are all six, each with the chapter that explains it:

One more false friend deserves a warning of its own, because it looks identical in both languages.

public class Invoice
{
    protected Money Discount() => Money.Zero;
}

package com.acme.billing;

public class Invoice {
    protected Money discount() { return Money.ZERO; }
}

<!-- pom.xml: none of these ship with the JDK -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>       <!-- the ASP.NET Core role -->
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>  <!-- the EF Core role -->
</dependency>

// The namespace need not match the folder.
namespace Acme.Billing;

// Interfaces start with I, methods use PascalCase.
public interface IOrderRepository
{
    Order? FindById(long id);
}

public class OrderService(IOrderRepository repository)
{
    // Private fields use _camelCase, with a leading underscore.
    private readonly IOrderRepository _repository = repository;
}

// The package matches the folder com/acme/billing/.
package com.acme.billing;

// No I prefix, and methods use camelCase.
public interface OrderRepository {
    Order findById(long id);
}

public class OrderService {
    // Fields have no underscore.
    private final OrderRepository repository;

    public OrderService(OrderRepository repository) { this.repository = repository; }
}

How to read this book#

The book has two reading modes and one view for refreshing later. The buttons are in the sidebar, and m moves from one to the next.

Everyday keeps everything you will meet in a typical Spring Boot service in your first months. That means each chapter's summary, its examples and their explanations, the mapping tables, and the traps you will actually run into. Rarely needed material is folded into a one-line heading you can click if a particular topic matters to you right now.

Complete opens all of it: the edge cases, the mechanisms, and the historical asides marked Legacy that explain code you will inherit but should not write.

Reference is for later. It hides the explanations and shows only each chapter's summary, what to remember and its quick reference, so you can refresh one topic, or the whole book, in one pass.

There is one more way to use it. Press ⌘K and type a C# name, or paste an error message. Mapping-table rows, C# refreshers, error entries, callouts, diagrams and glossary words are all indexed, so IEnumerable, IOptions and ConfigureAwait resolve to their Java answers without reading anything.

If you have been handed a Spring Boot service on Monday, read Parts 0 and 1 in Everyday mode. Then skip to Spring Boot orientation and use the rest as a reference.

Getting a JDK, and the release train#

Five minutes to a running service#

It is your first morning, and you want a service running before you read anything else. These three steps install a JDK, generate a Spring Boot project and start it:

# 1. a JDK, without touching the system package manager
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 25.0.4-tem      # the exact identifier comes from "sdk list java"

# 2. a project, generated from the command line
curl https://start.spring.io/starter.tgz \
     -d dependencies=web \
     -d type=maven-project \
     -d javaVersion=25 \
     -d artifactId=demo -d name=demo \
     | tar -xzf - -C . && cd demo

# 3. run it
./mvnw spring-boot:run

Then add one file, src/main/java/com/example/demo/Hello.java:

package com.example.demo;

import org.springframework.web.bind.annotation.*;

@RestController
public class Hello {

    @GetMapping("/hello")
    public String hello(@RequestParam(defaultValue = "world") String name) {
        return "hello " + name;
    }
}

Call it from another terminal:

curl "http://localhost:8080/hello?name=java"
# hello java

The response is the text hello java. Spring Boot listens on port 8080 unless you configure another.

That service ran on Java 25. The next section explains what the version numbers mean, and which one to choose.

The release train#

You will see Java 8, 11, 17, 21 and 25 in job adverts and in existing code, but rarely 22 or 23. The reason is the release schedule.

Java ships a new version every six months, in March and September. Since Java 17, every fourth release is a long-term support (LTS) release, so one arrives every two years. Earlier LTS releases were further apart, which is why the table below is not evenly spaced. The releases in between get six months of updates and then nothing. They exist so that new features can mature in the open.

Each change to Java is described in a numbered JDK Enhancement Proposal (JEP), such as JEP 444, which added virtual threads in Java 21. The book gives these numbers where they help you look something up.

The JDK that runs the build and the Java version you target are separate settings, as they are in .NET. You can build on JDK 25 and still produce bytecode, the compiled form of your code, that runs on Java 21:

<!-- pom.xml: compile for Java 21, whichever JDK runs the build -->
<properties>
    <maven.compiler.release>21</maven.compiler.release>
</properties>

<!-- under the Spring Boot parent, set this instead; the parent copies it across -->
<properties>
    <java.version>21</java.version>
</properties>

maven.compiler.release tells the compiler which Java version the output must run on, much as <TargetFramework> does in a .csproj file. Under the Spring Boot parent you set java.version instead, and the parent copies it into the compiler setting.

Installing and switching#

You will soon need more than one JDK: Java 21 for one service and Java 25 for another, just as you keep several .NET SDKs. SDKMAN installs them side by side and switches between them. These are the commands you will use:

# install SDKMAN once
curl -s "https://get.sdkman.io" | bash

sdk list java                        # every version and vendor, with its identifier
sdk install java 25.0.4-tem          # Temurin 25
sdk install java 21.0.12+1.1-tem     # Temurin 21 alongside it
sdk use java 21.0.12+1.1-tem         # this shell only
sdk default java 25.0.4-tem          # new shells

java -version                        # what am I actually running

In .NET, a global.json file pins the SDK a folder uses.

{
  "sdk": { "version": "10.0.100", "rollForward": "latestFeature" }
}

SDKMAN's version of it is a .sdkmanrc file in the project folder:

sdk env init      # writes .sdkmanrc naming the current JDK, such as java=25.0.4-tem
sdk env           # switches this shell to the JDK that .sdkmanrc names

sdk env init writes the file once. Commit it, and anyone who runs sdk env in the folder gets the same JDK.

With a JDK installed and chosen for each project, the last thing you need on day one is a way to add a library.

$ jshell
|  Welcome to JShell -- Version 25

jshell> var xs = List.of(1, 2, 3, 4)
xs ==> [1, 2, 3, 4]

jshell> xs.stream().filter(x -> x % 2 == 0).toList()
$2 ==> [2, 4]

jshell> /exit

// Program.cs
Console.WriteLine("Hello");

// dotnet run

// Hello.java
void main() {
    IO.println("Hello");
}

// java Hello.java

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

Adding a library#

Your service needs input validation. In .NET you would run dotnet add package. The Java build tools have no such command.

Adding the validation library looks like this:

<!-- pom.xml: the whole of "adding a package" -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
    <!-- no version: the Spring Boot parent chooses it -->
</dependency>

The groupId and artifactId together name the library, like a NuGet package id. There is no version, because the Spring Boot parent file chooses a compatible one. The next ./mvnw command downloads it.

How Java runs your code#

From source to a running program#

Java takes the same route as .NET in more visible steps. The compiler turns source into bytecode, Java's IL, and writes one class file per class. Class files are zipped into a JAR, and the java command starts a JVM to run them.

dotnet build
ls bin/Debug/net10.0/
# MyApp.dll                   the IL, compiled by Roslyn
# MyApp.deps.json             every dependency, and where to find it
# MyApp.runtimeconfig.json    which .NET runtime to start

Every class file stores the Java release it was compiled for, and a runtime refuses bytecode newer than itself:

javac --release 25 -d out src/com/acme/*.java
/opt/java21/bin/java -cp out com.acme.App

One program, start to finish#

Maven and Gradle, Java's build tools, hide every step below, as dotnet build hides the compiler. Doing it by hand once makes every classpath error readable. Take two classes in the package com.acme. A package is Java's namespace, with one extra rule: the class files must sit in folders that match the package name.

// Program.cs, top-level statements
Console.WriteLine(new Greeter().Greet("java"));

// the entry point is recorded in the
// assembly, so this is all it takes:
//   dotnet run

package com.acme;

public class App {
    public static void main(String[] args) {
        System.out.println(new Greeter().greet("java"));
    }
}
// java is told where to look and what to start:
//   java -cp out com.acme.App

App uses a second class, Greeter, in a file of its own:

// src/com/acme/Greeter.java
package com.acme;

public class Greeter {
    public String greet(String name) { return "hello " + name; }
}

Greeter is in the same package as App, so App can use it without an import. Compile both. The -d option says where the class files go:

javac -d out src/com/acme/*.java

javac writes one class file per class, and turns the package name into folders: com.acme becomes com/acme.

out/
└── com/
    └── acme/
        ├── App.class
        └── Greeter.class

That mapping is the whole trick. A class's fully qualified name, its package plus its name, is also the path of its class file: com.acme.App is the file App.class in the folder com/acme. Run it with -cp, the classpath, followed by the class whose main method starts the program:

java -cp out com.acme.App
# hello java

Here is what java did:

1. Started a JVM whose classpath has one entry, the folder out.
2. Turned the name com.acme.App into the path com/acme/App.class.
3. Found out/com/acme/App.class, loaded it, and called its main method.
4. When main first used Greeter, looked up com/acme/Greeter.class the same way.

To ship it, zip the classes into a JAR and write the main class into the JAR's manifest, a small text file inside the archive:

jar --create --file app.jar --main-class com.acme.App -C out .
java -jar app.jar
# hello java

The classpath is a search list#

After an upgrade, your service has two copies of the billing library on its classpath: version 2.1, and an old version 1.9 that nobody removed. Which one does Java use?

The first time your code uses a class, the JVM turns its fully qualified name into a path: com.acme.billing.Invoice becomes com/acme/billing/Invoice.class. It then checks each classpath entry, a folder or a JAR, in the order listed. The first entry that has the file wins, and the search stops.

Think of a row of shelves that you search in order for a book. You take the first copy you find, even if a newer edition sits on a later shelf. The comparison stops at the shelves themselves: a JAR is a zip file, not a folder, and the JVM looks inside it.

When the list is wrong, you get one of four errors:

java -cp target/classes com.acme.App   # the classes are in out, not target/classes
java -cp out App                       # the package is missing from the name
java -cp out/com/acme App              # the entry points inside the package

Class.forName("org.postgresql.Driver");   // the driver's JAR is not on the classpath

rm out/com/acme/Greeter.class
java -cp out com.acme.App

javac -d out src/com/acme/Greeter.java
java -cp out com.acme.App

Running with -cp or -jar#

There are two ways to start a Java program, and the JVM reads different things in each:

In practice, the two look like this:

# name the classpath and the main class yourself
java -cp "target/classes:lib/*" com.acme.App

# or let the JAR's manifest decide both
java -jar target/app.jar

target/classes:lib/* is a classpath with two entries: the compiled classes, then every JAR in the lib folder. The second command names neither, because the JAR's manifest supplies both.

Manifest-Version: 1.0
Main-Class: com.acme.App
Class-Path: lib/jackson-databind.jar lib/slf4j-api.jar

jar --create --file app.jar -C out .     # no --main-class
java -jar app.jar

public class Rates {
    // NumberFormatException the first time Rates is used
    static final int DEFAULT = Integer.parseInt("12%");
}

// works in the IDE, where resources are files on disk
String cfg = Files.readString(Path.of("src/main/resources/rates.json"));

// works everywhere: read it from the classpath
try (var in = getClass().getResourceAsStream("/rates.json")) {
    String cfg = new String(in.readAllBytes(), UTF_8);
}

try (var in = getClass().getResourceAsStream("/rates.jsn")) {
    String cfg = new String(in.readAllBytes(), UTF_8);
}

// environment variable
var url = Environment
    .GetEnvironmentVariable("RATES_URL");

// the nearest thing to a system property:
// AppContext.GetData, fed by runtimeconfig.json

// environment variable
String url = System.getenv("RATES_URL");

// system property, set with -Drates.url=...
String url2 = System.getProperty("rates.url");

dotnet restore
ls ~/.nuget/packages/newtonsoft.json/
# 13.0.3/                     one folder per version, shared by every project
cat nuget.config              # the package feeds, and their credentials
cat obj/project.assets.json   # the resolved graph, written by restore

ls ~/.m2/repository/org/slf4j/slf4j-api/
# 2.0.16/

mvn dependency:build-classpath     # print the exact classpath Maven will use

java -XX:MaxRAMPercentag=70 -jar app.jar

IntelliJ for Visual Studio users#

IntelliJ comes in two editions. The free Community Edition covers core Java, Maven, Gradle, Git and JUnit. Ultimate adds Spring, Jakarta Persistence (JPA) and database tooling, and it is what most Java teams pay for. VS Code with the Red Hat Java and Spring Boot extension packs is a lighter option, and you will meet Eclipse in older organisations.

The project model is different#

You open the team's repository and IntelliJ shows one project with three modules. Visual Studio would have shown a solution with three projects. The names moved, and so did the owner: in Java, the build tool decides how the code is organised, and the IDE reads its files.

The Java answer to a solution file is a parent pom.xml that lists its modules. IntelliJ opens it and shows each module the way Solution Explorer shows a project:

<!-- billing/pom.xml: the parent, doing the job of Billing.sln -->
<packaging>pom</packaging>
<modules>
    <module>billing-core</module>   <!-- a folder with its own pom.xml -->
    <module>billing-api</module>    <!-- each module builds one JAR -->
</modules>

<packaging>pom</packaging> says this file builds nothing itself; it only lists its modules. Each <module> names a folder with its own pom.xml, which builds one Java archive (JAR).

With the project open, the next thing to get used to is the keyboard.

The key to learn first#

IntelliJ's shortcuts differ enough to be frustrating for a week. There is a Visual Studio keymap under Settings → Keymap, but most people adapt, and the muscle memory transfers faster than you expect. The full mapping is in the quick reference at the end of this chapter. One key matters more than all the others.

Here is the first of those upgrades. A list of names is sorted by length, first with an anonymous class, then with the lambda that Alt+Enter offers instead:

List<String> names = new ArrayList<>(List.of("Grace", "Ada", "Linus"));

// Before: put the cursor on new Comparator, press Alt+Enter, and choose Replace with lambda.
names.sort(new Comparator<String>() {
    public int compare(String a, String b) { return a.length() - b.length(); }
});

// After the fix:
names.sort((a, b) -> a.length() - b.length());

public class Customer
{
    public string Name { get; set; }
    public string Email { get; set; }
}

public class Customer {
    private String name;
    private String email;

    // Generated with Cmd+N, then Getter and Setter.
    public String getName()          { return name; }
    public void   setName(String n)  { this.name = n; }
    public String getEmail()         { return email; }
    public void   setEmail(String e) { this.email = e; }
}

// Right-click the breakpoint, then type the condition:
order.customer().id() == 1042 && order.lines().size() > 10

if (amount < 0) {
    // Error Prone reports DeadException: the exception is created but never thrown.
    new IllegalArgumentException("negative amount");
}

Classes, constructors and initialisation#

Declaration#

The team's order service extends a base class the team wrote, ServiceBase, and must be closed when the application stops. In C# one colon introduces both the base class and the interface. Here is that declaration in both languages, with three smaller ones below it:

public class OrderService : ServiceBase, IDisposable
{
}

public sealed class Invoice { }
public abstract class Discount { }
public static class MoneyMath { }

public class OrderService extends ServiceBase
        implements AutoCloseable {
}

public final class Invoice { }
public abstract class Discount { }
// Java has no static classes; see below.

The rest of the declaration rules map like this:

// Customer.g.cs, generated
public partial class Customer { public string Name { get; set; } = ""; }

// Customer.cs, written by hand
public partial class Customer { public bool IsVip => Name.StartsWith("VIP"); }

public final class MoneyMath {
    private MoneyMath() { throw new AssertionError("no instances"); }

    public static BigDecimal round(BigDecimal v) {
        return v.setScale(2, RoundingMode.HALF_EVEN);
    }
}

public readonly record struct Percentage(decimal Value);

public record Percentage(BigDecimal value) { }

With a class declared, the next difference is in how its constructors call each other.

Constructors and chaining#

An express order is an order that ships faster. It has two constructors: one that takes only the customer, and one that also takes the order lines. The short one should call the full one, and the full one should call Order's constructor. Both languages can do this, but in Java the call is the first statement of the body, not part of the signature:

public class ExpressOrder : Order
{
    public ExpressOrder(Customer customer)
        : this(customer, []) { }

    public ExpressOrder(Customer customer, List<OrderLine> lines)
        : base(customer, lines) { }
}

public class ExpressOrder extends Order {

    public ExpressOrder(Customer customer) {
        this(customer, List.of());
    }

    public ExpressOrder(Customer customer, List<OrderLine> lines) {
        super(customer, lines);
    }
}

public ExpressOrder(Customer customer, List<OrderLine> lines) {
    if (lines.isEmpty()) throw new IllegalArgumentException("no lines");  // legal since Java 25
    super(customer, lines);
}

public class Registry {

    private static final Map<String, Handler> HANDLERS;

    static {
        HANDLERS = new HashMap<>();
        HANDLERS.put("json", new JsonHandler());
    }

    private final long created;

    {
        created = System.nanoTime();
    }

    public Registry() { }
}

public class Money(decimal amount, string currency)
{
    public decimal Amount { get; } = amount;
    public string Currency { get; } = currency;

    public override string ToString() => $"{Amount} {Currency}";
    public override bool Equals(object? o) =>
        o is Money m && Amount == m.Amount && Currency == m.Currency;
    public override int GetHashCode() => HashCode.Combine(Amount, Currency);
}

string kind = money.GetType().Name;  // "Money"

public class Money {
    private final BigDecimal amount;
    private final String currency;

    public Money(BigDecimal amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }

    @Override public String toString() { return amount + " " + currency; }
    @Override public boolean equals(Object o) {
        return o instanceof Money m
            && amount.equals(m.amount) && currency.equals(m.currency);
    }
    @Override public int hashCode() { return Objects.hash(amount, currency); }
}

String kind = money.getClass().getSimpleName();  // "Money"

Access modifiers and packages#

The mapping#

A teammate's invoice class has a total field with no access keyword. In C# that field would be private. In Java, any class in the same package can read it and change it:

public class Invoice {
    Money total;           // No keyword: package-private. Any class in this package can change it.
    private Money paid;    // This is what was meant.
}

Money total; has no keyword, so it is package-private: visible to every class in the same package, and nowhere else. C# has no such level. To hide the field, write private, as on the paid line.

Here are Java's four levels, from widest to narrowest, with the nearest C# keyword:

And the other way round, starting from the C# keywords you know:

public class Account
{
    internal decimal Limit;           // any code in this assembly
    protected internal decimal Fee;   // subclasses anywhere, or any code in this assembly
    private protected decimal Rate;   // subclasses, but only those in this assembly
}

Package-private access only makes sense once you know what a package is, and that is where Java differs most from C#.

Packages are not namespaces#

A C# namespace is a logical grouping: it need not match the folder layout, and one file can declare several. A Java package is tied to folders. Every build tool and IDE expects the package to match the folder the file sits in. The compiled class files must sit in matching folders, because that is how the Java runtime finds them, as How Java runs your code shows.

// Anywhere/AtAll/OrderService.cs
namespace Acme.Orders;

public class OrderService { }

// src/main/java/com/acme/orders/OrderService.java
package com.acme.orders;

public class OrderService { }

The C# file can sit in any folder and declare any namespace. The Java file declares package com.acme.orders; and sits in the folders com/acme/orders/, under src/main/java, which is where Maven looks for source code.

global using System.Linq;  // every file in the project
using System.Text.RegularExpressions;  // a namespace
using static System.Math;  // a type's static members
using Rx = System.Text.RegularExpressions.Regex;

var r = new Rx("a+");
var m = Max(1, 2);

import java.util.*;  // every type in java.util
import java.util.regex.Pattern;  // one type
import static java.lang.Math.max;  // one static member

var p = Pattern.compile("a+");
int m = max(1, 2);
java.sql.Date d = null;  // no alias: a clashing name is written in full

// in the production project
[assembly: InternalsVisibleTo("Billing.Tests")]

internal static class InvoiceNumbers { ... }   // Billing.Tests may now call it

// src/main/java/com/acme/billing/InvoiceNumbers.java
package com.acme.billing;
class InvoiceNumbers {                       // no modifier: package-private
    static String next() { ... }
}

// src/test/java/com/acme/billing/InvoiceNumbersTest.java
package com.acme.billing;                    // same package, so the test can see it
class InvoiceNumbersTest {
    @Test void startsWithInv() { assertTrue(InvoiceNumbers.next().startsWith("INV")); }
}

// src/main/java/com/acme/billing/api/InvoiceController.java
package com.acme.billing.api;    // reverse domain, lowercase, and it matches the folders

Interfaces, abstract classes and sealing#

Interfaces#

The order service looks up prices through an interface, so that tests can swap in a fake. In C# you would call it IPriceLookup; in Java it is PriceLookup, with no I. Both versions below also use EmptyLookup, a class that finds nothing, which is left out:

public interface IPriceLookup
{
    Money? Find(string productId);

    // This is a default interface method.
    // Its default method body is used unless a class overrides it.
    bool Has(string productId) => Find(productId) is not null;

    // Interfaces may have static members.
    static IPriceLookup Empty => new EmptyLookup();

    // And private helpers.
    private static void Log(string m) { }
}

public interface PriceLookup {
    Money find(String productId);

    // This method has a default body.
    default boolean has(String productId) {
        return find(productId) != null;
    }

    // Interfaces may have static methods.
    static PriceLookup empty() {
        return new EmptyLookup();
    }

    // And private helpers.
    private void log(String m) { }
}

Here is when each capability arrived, and what C# has that Java lacks:

interface IProducer<out T> { T Next(); }
interface IConsumer<in T>  { void Take(T item); }

IEnumerable<object> items = new List<string>();   // allowed by IEnumerable<out T>

Action<object> print = o => Console.WriteLine(o);
Action<string> printText = print;                 // allowed by Action<in T>

Java has no variance on the declaration. It says the same thing where the type is used, with a wildcard: a parameter of type List<? extends Number> accepts a List<Integer>. See Variance is at the use site.

interface ILogger { void Log(string m); }

class FileLog : ILogger
{
    void ILogger.Log(string m) { }       // no access modifier
}

new FileLog().Log("x");                  // does not compile
((ILogger)new FileLog()).Log("x");       // compiles

interface Printer { void close(); }
interface Channel { void close(); }

class Device implements Printer, Channel {
    public void close() { }              // one method serves both, and it must be public
}

public class Both implements A, B {
    @Override public String name() {
        return A.super.name();     // pick a specific default
    }
}

public class OrderService
{
    public event Action<Order>? Placed;

    public void Place(Order order)
    {
        Placed?.Invoke(order);
    }
}

service.Placed += order => Console.WriteLine(order.Id);

public class OrderService {
    private final List<Consumer<Order>> placedListeners = new ArrayList<>();

    public void onPlaced(Consumer<Order> listener) { placedListeners.add(listener); }

    public void place(Order order) {
        placedListeners.forEach(l -> l.accept(order));
    }
}

service.onPlaced(order -> System.out.println(order.id()));

So far, interfaces have behaved much as they do in C#. The next feature has no C# counterpart at all.

Sealed types: Java's discriminated unions#

An order can be paid by card, by bank transfer or with a voucher, and in no other way. The code that charges a payment must handle all three. In C# you would write a base type and hope that nobody adds a fourth kind without updating every switch. Java can make the compiler enforce it.

Be careful with the word first. sealed means a different thing in each language:

A sealed interface lists its complete set of subtypes. Here are the three payment kinds:

public sealed interface Payment
        permits Card, BankTransfer, Voucher {
}

public record Card(String last4) implements Payment { }
public record BankTransfer(String iban) implements Payment { }
public record Voucher(String code) implements Payment { }

Because the set is closed, a switch over a payment can be complete without a default arm. In the C# version, assume the same three kinds exist as records that derive from an abstract Payment record:

// The compiler cannot know the set is closed,
// so it warns unless you add a discard arm.
decimal Fee(Payment p) => p switch
{
    Card c         => 0.30m,
    BankTransfer b => 0m,
    Voucher v      => 0m,
    _ => throw new ArgumentException()
};

// No default needed: add a fourth Payment and this
// stops compiling until you handle it.
BigDecimal fee(Payment p) {
    return switch (p) {
        case Card c         -> new BigDecimal("0.30");
        case BankTransfer b -> BigDecimal.ZERO;
        case Voucher v      -> BigDecimal.ZERO;
    };
}

Sealed types limit who may extend a type. The last difference runs the other way: an ordinary Java class is more open than you expect.

Abstract classes, and methods that are virtual by default#

Abstract classes are essentially identical to C#'s. The choice between an abstract class and an interface with default methods follows the same reasoning: state and constructors force an abstract class, and otherwise you prefer the interface.

Here is a discount with one method of each kind: one that subclasses must override, one they may override, and one they may not:

public abstract class Discount
{
    public abstract decimal Amount(decimal total);  // must be overridden
    public virtual string Describe() => "discount";  // may be overridden
    public string Code() => "D";  // cannot be overridden
}

public class TenPercent : Discount
{
    public override decimal Amount(decimal total) => total * 0.10m;
}

public abstract class Discount {
    public abstract BigDecimal amount(BigDecimal total);  // must be overridden
    public String describe() { return "discount"; }  // may be: no keyword needed
    public final String code() { return "D"; }  // final: cannot be overridden
}

public class TenPercent extends Discount {
    @Override public BigDecimal amount(BigDecimal total) {
        return total.multiply(new BigDecimal("0.10"));
    }
}

public sealed interface Event permits UserEvent, SystemEvent { }

public final class UserEvent implements Event { }        // closed
public non-sealed class SystemEvent implements Event { } // anyone may extend this branch

Methods and parameters#

Signatures#

The order service needs a method that counts orders matching a filter, with an optional case-sensitive flag and an optional limit. In C# you write one method with default values, and call it with a named argument. Java has neither, so the Java version is an overload ladder: each shorter version calls the next with the default filled in.

public int CountOrders(
    string filter,
    bool caseSensitive = false,
    int limit = 100)
{
    ...
}

var n = CountOrders("paid", limit: 50);

public int countOrders(String filter) {
    return countOrders(filter, false, 100);
}
public int countOrders(String filter, boolean caseSensitive) {
    return countOrders(filter, caseSensitive, 100);
}
public int countOrders(String filter, boolean caseSensitive, int limit) {
    ...
}

int n = countOrders("paid", false, 50);  // no named arguments

// A builder is the usual replacement for named and optional arguments.
var req = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com"))
        .timeout(Duration.ofSeconds(10))
        .header("Accept", "application/json")
        .GET()
        .build();

Default parameter values are one gap. The next is bigger: how arguments are passed at all.

No ref, no out#

A customer types a quantity into a form, and you need to parse it. In C# you write int.TryParse(s, out var value). Java has no out parameters, because Java passes every argument by value. An object reference is passed by value too: the method can change the object it points at, but it cannot make the caller's variable point somewhere else.

if (int.TryParse(s, out var value))
{
    Use(value);
}

void Swap(ref int a, ref int b) { ... }
void Print(in BigStruct s) { ... }  // read-only, by reference

// Return a value that can be empty, instead of an out parameter.
OptionalInt parsed = parseQuantity(s);
if (parsed.isPresent()) {
    use(parsed.getAsInt());
}

// Return a record when there are several results.
record Pair(int a, int b) { }
Pair swapped = swap(a, b);

(int Min, int Max) Range(int[] xs) => (xs.Min(), xs.Max());

var (lo, hi) = Range([3, 1, 4]);     // lo is 1, hi is 4

High-performance C# also passes Span<T>, a view over memory that avoids copying. Java's nearest tools are ByteBuffer and MemorySegment, which you will rarely need in a web service.

Span<byte> buffer = stackalloc byte[256];        // on the stack: no heap allocation
ReadOnlySpan<char> head = text.AsSpan(0, 3);     // a view of text, not a copy

void Log(string fmt, params object[] args) { }
Log("a {0}", 1);

void log(String fmt, Object... args) { }
log("a %s", 1);

No extension methods#

You want an IsBlank() check on every string, where name is a string that may be null. In C# an extension method adds it to string. Java cannot add a method to a type it does not own, so the helper lives in a class of its own:

public static class StringExtensions
{
    public static bool IsBlank(this string? s) =>
        string.IsNullOrWhiteSpace(s);
}

if (name.IsBlank()) { ... }  // reads as if String had it

public final class Strings {
    private Strings() { }

    public static boolean isBlank(String s) {
        return s == null || s.isBlank();
    }
}

if (Strings.isBlank(name)) { ... }  // the helper's class comes first

public readonly record struct Money(decimal Amount)
{
    public static Money operator +(Money a, Money b) => new(a.Amount + b.Amount);
}

var total = price + shipping;     // calls the operator above

decimal total = price * quantity + shipping;
if (total > limit) { ... }

BigDecimal total = price.multiply(quantity).add(shipping);
if (total.compareTo(limit) > 0) { ... }

Methods cannot be added to other types, but they can be passed around as values, and that is where Java and C# look most alike again.

Lambdas and method references#

The shop applies pricing rules: each rule takes an order and returns a price. In C# a rule is a delegate. Java has no delegates. Instead, a rule is an interface with exactly one method to implement, called a functional interface, or a single abstract method (SAM) type. Any lambda with the right shape can stand in for it. Here are the common delegate types and their Java equivalents:

delegate decimal PriceRule(Order o);  // a named delegate type

Func<int, string> show = n => n.ToString();
Action<string> print = Console.WriteLine;  // method group
Predicate<string> empty = string.IsNullOrEmpty;
Func<List<int>> make = () => new List<int>();

names.ForEach(print);

interface PriceRule { BigDecimal apply(Order o); } // a functional interface

Function<Integer, String> show = n -> n.toString();
Consumer<String> print = System.out::println;  // method reference
Predicate<String> empty = String::isEmpty;
Supplier<List<Integer>> make = ArrayList::new;  // constructor reference

names.forEach(print);

int count = 0;
list.forEach(x -> count++);      // does not compile

var counter = new AtomicInteger(); // the usual workaround
list.forEach(x -> counter.incrementAndGet());

Fields, properties and immutability#

The property gap#

The order service keeps customers. In C#, a customer's id is fixed when it is created, its name can change, and a label is worked out from the two. Each is a property. Here is the same class in Java, where each property becomes a field plus methods:

public class Customer
{
    public long Id { get; init; }
    public string Name { get; set; }
    public string Label => $"{Name} ({Id})";
}

public class Customer {
    private final long id;
    private String name;

    public Customer(long id) { this.id = id; }

    public long   getId()           { return id; }
    public String getName()         { return name; }
    public void   setName(String v) { this.name = v; }
    public String getLabel() {
        return name + " (" + id + ")";
    }
}

A class like this, with private fields, getters and setters and no framework base class, is often called a plain old Java object (POJO). When it follows the naming rules exactly, it is also called a JavaBean. C# also has required and init, and since C# 14 the field keyword. Java has none of them: a final field set in the constructor does their job.

public class Customer
{
    public required string Id { get; init; }   // must be set at creation, then fixed

    public string Name
    {
        get;
        set => field = value.Trim();           // field: the compiler's backing field
    }
}

var c = new Customer { Id = "C1", Name = " Ada " };   // leave out Id: compile error

Writing all these methods for every class is tedious, and for one common kind of class you no longer have to.

Records make most of this disappear#

Most customer objects in the order service never change once they are created: they are data. A record suits immutable data, such as a data transfer object (DTO), a value object or a query result. It replaces the whole ceremony, including equals, hashCode and toString. Below, customer is an existing Customer:

public record Customer(long Id, string Name, string Email)
{
    public string Label => $"{Name} ({Id})";
}

var renamed = customer with { Name = "Ada" };

public record Customer(long id, String name, String email) {
    public String label() {
        return name + " (" + id + ")";
    }
}

// No with expression: build a new one. See the Records chapter.
var renamed = new Customer(customer.id(), "Ada", customer.email());

private final List<String> names = new ArrayList<>();

names.add("ada");             // fine, mutating the list
names = new ArrayList<>();    // does not compile, rebinding the reference

public const int MaxRetries = 3;
public static readonly TimeSpan Timeout =
    TimeSpan.FromSeconds(30);

public static final int MAX_RETRIES = 3;
public static final Duration TIMEOUT = Duration.ofSeconds(30);

@Getter @Setter @Builder
public class Customer {
    private String name;
    private String email;
}

Records#

The basics#

Every line on an order carries a product id, a quantity and a unit price, and it never changes once it is on the order. That is exactly what a record is for. Here is OrderLine in both languages, where Money is itself a small record of an amount and a currency:

public record OrderLine(string ProductId, int Quantity, Money UnitPrice);

var line = new OrderLine("mug", 2, new Money(9.50m, "EUR"));
Console.WriteLine(line);
Console.WriteLine(line.Quantity);
var more = line with { Quantity = 3 };

public record OrderLine(String productId, int quantity, Money unitPrice) { }

var line = new OrderLine("mug", 2, new Money(new BigDecimal("9.50"), "EUR"));
System.out.println(line);
System.out.println(line.quantity());  // note the ()
// no with expression: see below

Most of what you know about C# records carries over. These are the differences:

public record Point(int X, int Y);                              // positional
public record Customer { public string Name { get; init; } = ""; }  // nominal: a body
public record Shape(string Name);
public record Circle(string Name, double R) : Shape(Name);      // inherits a record
public readonly record struct Money(decimal Amount);            // a value-type record

var p = new Point(1, 2);
Console.WriteLine(p == new Point(1, 2));                        // True: value equality
var q = p with { Y = 5 };                                       // a copy with one change

A record takes whatever values it is given. The next step is to check them.

Checking values: the compact constructor#

An amount of money must never be negative, and it should always have two decimal places, so that 9.5 and 9.50 compare as equal. Java records have a special constructor for this, the compact constructor, which C# does not have. It checks or adjusts the values without restating the parameter list or the assignments:

public record Money(BigDecimal amount, String currency) {

    // A compact constructor: no parameter list, and no assignments to fields.
    public Money {
        if (amount.signum() < 0) throw new IllegalArgumentException("negative amount");
        amount = amount.setScale(2, RoundingMode.HALF_EVEN);
    }

    // Any extra constructor must call the main one first.
    public Money(String amount) {
        this(new BigDecimal(amount), "EUR");
    }
}

With values checked on the way in, the next question is how to change one. The answer is that you do not: you make a new record.

The missing with expression#

// 1. Just construct it: fine for small records.
var more = new OrderLine(line.productId(), 3, line.unitPrice());

// 2. A hand-written "wither": common in domain code.
public record OrderLine(String productId, int quantity, Money unitPrice) {
    public OrderLine withQuantity(int q) { return new OrderLine(productId, q, unitPrice); }
}

// 3. A builder, for records with many components.

Records are not the right tool for every class. The next section says where they fit.

Where records fit#

Records suit data that is created once and then only read. Here is where they fit, and where they do not:

public record Order(long id, List<OrderLine> lines) {
    public Order {
        lines = List.copyOf(lines);   // now genuinely immutable
    }
}

String describe(Payment p) {
    return switch (p) {
        case Card(String last4) when last4.equals("0000") -> "a test card";
        case Card(String last4)                           -> "card ending " + last4;
        case BankTransfer(String iban)                    -> "transfer from " + iban;
        case Voucher(String code)                         -> "voucher " + code;
    };
}

Sealed types and pattern matching#

Type patterns#

A customer asks for a refund. Card payments are refunded to the same card, so the refund code must first ask: is this payment a card? If it is, the code needs the card's last four digits. In C# you write is, a type and a variable name. Java writes instanceof in the same place:

void Refund(Payment payment, decimal amount)
{
    if (payment is Card card)
    {
        RefundToCard(card.Last4, amount);
    }
}

void refund(Payment payment, BigDecimal amount) {
    if (payment instanceof Card card) {
        refundToCard(card.last4(), amount);
    }
}

The variable exists only where the test is known to have passed. Usually that is inside the if. It can also be the code after the if, when the if leaves the method on failure. Here, only card payments may be refunded at all:

void RefundCardOnly(Payment payment, decimal amount)
{
    if (payment is not Card card)
    {
        throw new ArgumentException("only card payments can be refunded");
    }
    RefundToCard(card.Last4, amount);  // card can be used here
}

void refundCardOnly(Payment payment, BigDecimal amount) {
    if (!(payment instanceof Card card)) {
        throw new IllegalArgumentException("only card payments can be refunded");
    }
    refundToCard(card.last4(), amount);  // card can be used here
}

if (payment instanceof Card) {
    Card card = (Card) payment;
    refundToCard(card.last4(), amount);
}

One test suits one kind of payment. When every kind needs its own handling, a switch reads better than a chain of if statements.

Pattern matching in switch#

The receipt describes how the customer paid, and each kind of payment is described differently. A payment can also be missing, when the order is not paid yet, and test cards, whose last four digits are 0000, get their own wording. In Interfaces, abstract classes and sealing, the fee method switched over a payment's type. This switch also handles null and adds a condition to one arm:

string Describe(Payment? payment) => payment switch
{
    null => "not paid yet",
    Card c when c.Last4 == "0000" => "a test card",
    Card c => $"card ending {c.Last4}",
    BankTransfer t => $"transfer from {t.Iban}",
    Voucher v => $"voucher {v.Code}",
    _ => throw new ArgumentException("unknown payment")
};

String describe(Payment payment) {
    return switch (payment) {
        case null -> "not paid yet";
        case Card c when c.last4().equals("0000") -> "a test card";
        case Card c -> "card ending " + c.last4();
        case BankTransfer t -> "transfer from " + t.iban();
        case Voucher v -> "voucher " + v.code();
    };
}

The two versions differ at the end. C# needs the _ arm, because nothing stops another assembly from adding a fourth kind of payment. Java needs no default, because Payment is sealed and lists exactly three kinds. If someone adds a fourth, every switch over Payment stops compiling until it handles the new kind.

Java's patterns cover types, records and extra conditions. C# has three more kinds of pattern that Java does not.

Patterns Java does not have#

C# can match on an object's properties, on the shape of a list, and on a comparison such as > 10. Java has none of these patterns, so you test the same things in a when guard. Here the shop labels an order by its number of lines:

string Size(Order order) => order switch
{
    { Lines.Count: 0 } => "empty",  // a property pattern
    { Lines: [_] } => "one line",  // a list pattern: exactly one element
    { Lines.Count: > 10 } => "large",  // a relational pattern (> 10)
    _ => "normal"
};

String size(Order order) {
    return switch (order) {
        case Order o when o.lines().isEmpty() -> "empty";
        case Order o when o.lines().size() == 1 -> "one line";
        case Order o when o.lines().size() > 10 -> "large";
        case Order o -> "normal";
    };
}

When every arm is a guard like this, plain if statements work just as well, and many Java developers would write them.

var where = point switch
{
    (0, 0)   => "origin",               // positional pattern
    { X: 0 } => "on the y axis",        // property pattern
    _        => "elsewhere"
};

bool framed = numbers is [1, .., 9];    // list pattern: starts with 1, ends with 9

var feel = celsius switch { > 30 => "hot", < 0 => "freezing", _ => "mild" };  // relational

Type patterns and when guards are enough for most code. The rest of this chapter covers record patterns, nested patterns, and one pattern that is still a preview.

string Describe(Payment payment) => payment switch
{
    Card(var last4) => $"card ending {last4}",  // a positional pattern
    BankTransfer(var iban) => $"transfer from {iban}",
    Voucher(var code) => $"voucher {code}",
    _ => throw new ArgumentException("unknown payment")
};

String describe(Payment payment) {
    return switch (payment) {
        case Card(var last4) -> "card ending " + last4;
        case BankTransfer(var iban) -> "transfer from " + iban;
        case Voucher(var code) -> "voucher " + code;
    };
}

if (line instanceof OrderLine(var productId, _, Money(_, var currency))
        && !currency.equals("EUR")) {
    System.out.println(productId + " is priced in " + currency);
}

// Preview in Java 25: compile and run with --enable-preview.
double quantity = 3.0;                 // for example, read from a spreadsheet
if (quantity instanceof int whole) {   // matches: 3.0 converts to an int with no loss
    System.out.println(whole + " items");
}
boolean exact = 2.5 instanceof int;    // false: the conversion would lose the .5

Switch expressions and statements#

The arrow form#

The warehouse packs orders on weekdays, and the order confirmation tells the customer when their order will be packed. That depends on the day they placed it. Here day is a DayOfWeek, an enum that both .NET and Java provide:

DayOfWeek day = DayOfWeek.Friday;
var packing = day switch
{
    DayOfWeek.Saturday or DayOfWeek.Sunday => "packed on Monday",
    DayOfWeek.Friday => "packed today, delivered next week",
    _ => "packed today"
};

import java.time.DayOfWeek;

DayOfWeek day = DayOfWeek.FRIDAY;
var packing = switch (day) {
    case SATURDAY, SUNDAY -> "packed on Monday";
    case FRIDAY -> "packed today, delivered next week";
    default -> "packed today";
};

The whole switch produces a value, so the statement ends with a semicolon after the closing brace, as in C#. Some arms need more than one step to work out their value, and that needs a block.

decimal Fee(Payment payment, decimal total) => payment switch
{
    Card => CardFee(total),
    BankTransfer or Voucher => 0m,
    _ => throw new ArgumentException("unknown payment")
};

decimal CardFee(decimal total) => Math.Max(total * 0.014m, 0.30m);

BigDecimal fee(Payment payment, BigDecimal total) {
    return switch (payment) {
        case Card c -> {
            BigDecimal percentFee = total.multiply(new BigDecimal("0.014"));
            yield percentFee.max(new BigDecimal("0.30"));
        }
        case BankTransfer t -> BigDecimal.ZERO;
        case Voucher v -> BigDecimal.ZERO;
    };
}

IEnumerable<int> Evens(int max)
{
    for (var i = 0; i <= max; i += 2)
        yield return i;       // hand back one value, then pause here
}

foreach (var n in Evens(6)) Console.Write(n);   // 0246

A switch that returns a value must handle every possible value. When the value is an enum or a sealed type, the compiler can check that for you.

Exhaustiveness#

Every order status needs a label on the order page, and a new status must never slip through without one. OrderStatus has four constants, and this switch handles each of them:

enum OrderStatus { NEW, PAID, SHIPPED, CANCELLED }

// No default: all four constants are covered.
// Add a fifth constant and this method stops compiling.
String label(OrderStatus status) {
    return switch (status) {
        case NEW       -> "waiting for payment";
        case PAID      -> "being packed";
        case SHIPPED   -> "on its way";
        case CANCELLED -> "cancelled";
    };
}

A sealed type follows the same rule: every permitted type needs an arm, as the payment switches in Sealed types and pattern matching showed.

The arrow form is the one to write. Older code uses the colon form, which you still need to be able to read.

switch (status) {
    case NEW:
        sendPaymentReminder();
        // no break: falls through into PAID. Intended? Nobody can tell.
    case PAID:
        reserveStock();
        break;
    default:
        throw new IllegalStateException("unexpected status " + status);
}

foreach (var order in orders)
    foreach (var line in order.Lines)
        if (line.Quantity == 0)
            goto done;
done:
Console.WriteLine("scan finished");

scan:
for (var order : orders)
    for (var line : order.lines())
        if (line.quantity() == 0)
            break scan;          // leaves both loops
System.out.println("scan finished");

String kind = switch (extension) {
    case "jpg", "png" -> "image";       // strings are compared with equals()
    case "pdf"        -> "document";
    default           -> "other";
};

var, strings and text blocks#

var#

The order service often creates a list of order lines and then loops over them. Writing the type on both sides of = is repetitive, and var removes one of them, in both languages:

var lines = new List<OrderLine>();
var count = 0;
foreach (var line in lines) { count += line.Quantity; }

var lines = new ArrayList<OrderLine>();
var count = 0;
for (var line : lines) { count += line.quantity(); }

Java allows var in the same places as C#, with one small difference for lambda parameters:

var mixed = new ArrayList<>();            // ArrayList<Object>: almost never what you meant
var lines = new ArrayList<OrderLine>();   // what you meant

With variables settled, the next step is building text from them, and that is where Java differs most from C#.

No string interpolation#

The order confirmation greets the customer and states the total. In C# you build that sentence with string interpolation. Java has none, so you join the pieces with +, or fill in a template. Here name is a String, orderId a long and total a BigDecimal:

var greeting = $"Hello {name}, your order {orderId} comes to {total:F2} EUR";

var greeting = "Hello " + name + ", your order " + orderId + " comes to " + total + " EUR";
var formatted = "Hello %s, your order %d comes to %.2f EUR".formatted(name, orderId, total);

// Joining with +: fine for a few pieces, and the compiler makes it efficient.
String opening = "Hello " + name + ", your order " + orderId;

// formatted or String.format: when you need a fixed number of decimal places.
String totalLine = "Total: %.2f EUR".formatted(total);
String amount = String.format("%,.2f", total);   // 1,234.50 with an English locale

// StringBuilder: in a loop, or when building something large.
var sb = new StringBuilder();
for (var line : lines) sb.append(line.productId()).append(',');

// A text block plus formatted: for text that spans several lines.
String email = """
    Hello %s,

    Your order %d has shipped.
    """.formatted(name, orderId);

Most everyday string methods keep their C# names, starting with a lower-case letter. Here are the ones you will reach for first. productId, note and total are single values, and productIds is a list of strings:

var label = string.Format("{0} x {1}", productId, quantity);
var csv = string.Join(", ", productIds);
var noNote = string.IsNullOrWhiteSpace(note);
var isGift = note.Contains("gift");
var shown = $"{total:F2}";

var label = String.format("%s x %s", productId, quantity);
var csv = String.join(", ", productIds);
var noNote = note == null || note.isBlank();
var isGift = note.contains("gift");
var shown = "%.2f".formatted(total);

One more everyday operation behaves differently: checking whether two strings are equal.

Comparing strings#

A customer types a voucher code, and the code upper-cases it before checking it against "SPRING". In C# you compare the two with ==. In Java, == compiles too, but it asks a different question:

string typed = "spring".ToUpper();  // what the customer typed, upper-cased
bool equal = typed == "SPRING";  // True: string's == compares the text

import java.util.Objects;

String typed = "spring".toUpperCase();  // what the customer typed, upper-cased
boolean same = typed == "SPRING";  // false: two different objects
boolean equal = typed.equals("SPRING");  // true: the same text
boolean safe = Objects.equals(typed, "SPRING"); // true, and no exception if typed is null

string a = "abc";
string b = new string("abc".ToCharArray());   // a different object, same characters
Console.WriteLine(a == b);                    // True: string overloads == to compare text

Short strings are now covered. Longer text, such as a JSON document, needs a different kind of literal.

Text blocks#

The shop sends orders to a partner as JSON, and a test needs a sample document. Written as an ordinary string, every quote would need a backslash. Both languages have a multi-line literal for this:

var json = """
    {
      "orderId": 1042,
      "status": "PAID"
    }
    """;

String json = """
    {
      "orderId": 1042,
      "status": "PAID"
    }
    """;

The syntax is the same three quotes, and both languages remove the shared indentation. The differences are in the details:

Regular expressions are where the missing raw string hurts most, as the next section shows.

var re = new Regex(@"(?<area>\d{3})-(?<num>\d{4})");

var m = re.Match(phone);
if (m.Success)
{
    var area = m.Groups["area"].Value;
}

var all = re.Matches(notes);
var hidden = re.Replace(phone, "$1-XXXX");

import java.util.regex.*;

Pattern re = Pattern.compile("(?<area>\\d{3})-(?<num>\\d{4})");

Matcher m = re.matcher(phone);
if (m.find()) {
    String area = m.group("area");
}

List<MatchResult> all = re.matcher(notes).results().toList();
String hidden = re.matcher(phone).replaceAll("$1-XXXX");

var sku = new Regex(@"sku-\d+",
    RegexOptions.IgnoreCase | RegexOptions.Compiled);

bool mentionsProduct = sku.IsMatch(note);
string[] pieces = sku.Split(note);  // the text between the codes

Pattern sku = Pattern.compile("sku-\\d+",
    Pattern.CASE_INSENSITIVE);  // always compiled

boolean mentionsProduct = sku.matcher(note).find();  // not matches()
String[] pieces = sku.split(note);  // the text between the codes

// A fixed number of pieces: plain + builds the string once.
String summary = "Order " + orderId + " has " + count + " lines";

// A loop: use a StringBuilder, because += would build a whole new string each time round.
var sb = new StringBuilder();
for (var line : lines) sb.append(line.productId()).append('\n');

Enums#

The shape of the difference#

An order moves through four statuses: new, paid, shipped and cancelled. In C#, each status is a name for a number, and you can choose the numbers. In Java, each status is an object:

public enum OrderStatus
{
    New = 1,
    Paid = 2,
    Shipped = 3,
    Cancelled = 4
}

var status = (OrderStatus) 2;          // Paid
int number = (int) OrderStatus.Paid;   // 2

public enum OrderStatus {
    NEW, PAID, SHIPPED, CANCELLED
}

OrderStatus status = OrderStatus.valueOf("PAID");
int position = OrderStatus.PAID.ordinal();  // 1, but see the warning below

Because each constant is an object, it can carry data. That is where Java enums leave C# behind.

Enums with state and behaviour#

The order page shows a label for each status, and the database stores a one-letter code. In C# you would keep the labels in a separate switch or dictionary, or attach them with a [Description] attribute. A Java enum holds them itself:

public enum OrderStatus {
    NEW("N", "waiting for payment"),
    PAID("P", "being packed"),
    SHIPPED("S", "on its way"),
    CANCELLED("C", "cancelled");

    private final String code;
    private final String label;

    OrderStatus(String code, String label) {   // an enum constructor is always private
        this.code = code;
        this.label = label;
    }

    public String code()  { return code; }
    public String label() { return label; }
}

String shown = OrderStatus.SHIPPED.label();   // "on its way"

Storing code() in the database fixes the ordinal() problem: a new constant gets a new code, and the existing codes stay as they are.

public enum Delivery {
    STANDARD {
        public BigDecimal price(BigDecimal total) {
            return total.compareTo(new BigDecimal("50")) >= 0 ? BigDecimal.ZERO : new BigDecimal("4.95");
        }
    },
    EXPRESS {
        public BigDecimal price(BigDecimal total) {
            return new BigDecimal("9.95");
        }
    };

    public abstract BigDecimal price(BigDecimal total);
}

BigDecimal cost = Delivery.STANDARD.price(new BigDecimal("62.00"));   // 0: free from 50

Everyday work with enums is parsing them from text, listing them, and using them as keys. That looks different in each language.

Everyday enum operations#

An order status can arrive as text in a request, such as "PAID". Here text holds that string, and counts will count orders by status:

var status = Enum.Parse<OrderStatus>("Paid");
bool ok = Enum.TryParse<OrderStatus>(text, out var parsed);
OrderStatus[] all = Enum.GetValues<OrderStatus>();
string name = OrderStatus.Paid.ToString();  // "Paid"
var counts = new Dictionary<OrderStatus, int>();

import java.util.EnumMap;

var status = OrderStatus.valueOf("PAID");  // throws if unknown
OrderStatus parsed;
try {
    parsed = OrderStatus.valueOf(text);
} catch (IllegalArgumentException e) {
    parsed = null;  // not a known status
}
OrderStatus[] all = OrderStatus.values();  // a new array each call
String name = OrderStatus.PAID.name();  // "PAID"
var counts = new EnumMap<OrderStatus, Integer>(OrderStatus.class);

[Flags]
enum Handling { None = 0, GiftWrap = 1, Express = 2, Fragile = 4 }

var handling = Handling.GiftWrap | Handling.Fragile;
if (handling.HasFlag(Handling.Fragile)) { }

import java.util.EnumSet;

enum Handling { GIFT_WRAP, EXPRESS, FRAGILE }

var handling = EnumSet.of(Handling.GIFT_WRAP, Handling.FRAGILE);
if (handling.contains(Handling.FRAGILE)) { }

String label = switch (status) {
    case NEW       -> "waiting for payment";
    case PAID      -> "being packed";
    case SHIPPED   -> "on its way";
    case CANCELLED -> "cancelled";
};

public enum ExchangeRates {
    INSTANCE;

    private final Map<String, BigDecimal> rates = new ConcurrentHashMap<>();

    public void put(String currency, BigDecimal rate) { rates.put(currency, rate); }
    public BigDecimal get(String currency)             { return rates.get(currency); }
}

ExchangeRates.INSTANCE.put("USD", new BigDecimal("1.08"));

Generics and type erasure#

Declaration#

Everything the shop stores has an id, and a simple in-memory repository can store any type that has one. In both languages the class takes a type parameter, T, with a constraint that says T must have an id:

public interface IHasId { long Id { get; } }

public class InMemoryRepository<T> where T : IHasId
{
    private readonly Dictionary<long, T> items = new();

    public void Save(T item) => items[item.Id] = item;
    public T? Find(long id) => items.GetValueOrDefault(id);
}

public interface HasId { long id(); }

public class InMemoryRepository<T extends HasId> {
    private final Map<Long, T> items = new HashMap<>();

    public void save(T item) { items.put(item.id(), item); }
    public T find(long id) { return items.get(id); }
}

So far the two languages match. The difference appears when the program runs.

What erasure takes away#

Java checks type arguments when it compiles, and then removes them. This is called type erasure. While the program runs, an InMemoryRepository<Customer> is a plain InMemoryRepository, and inside it T is treated as HasId, its constraint. So anything that needs to know T at run time does not compile. Here x is any object:

class Box<T> {
    void tryThings(Object x) {
        T t = new T();                           // no: T is unknown at run time
        T[] a = new T[10];                       // no: nor can an array of T be created
        boolean b = x instanceof List<String>;   // no: a list does not know its element type
        Class<T> c = T.class;                    // no: T has no class literal
    }
    static int count;                            // one count shared by every Box, whatever T is
}

The workaround is to pass the type in yourself. That is why Java APIs are full of Class<T> parameters where C# would use typeof(T). Here mapper is the ObjectMapper of Jackson, the JSON library most Java services use, and json holds one customer:

// typeof(T) is available here: T exists at run time
T Read<T>(string json) =>
    JsonSerializer.Deserialize<T>(json)!;

var customer = Read<Customer>(json);

<T> T read(String json, Class<T> type) {
    return mapper.readValue(json, type);
}

var customer = read(json, Customer.class);

T FirstOrZero<T>(List<T> xs) => xs.Count > 0 ? xs[0] : default;   // null, 0 or false

dynamic x = "hello";
int n = x.Length;              // resolved at run time, with no compile-time check

Java has neither. A type parameter always stands for a reference type, so the only default it can have is null. For late binding, Java uses reflection, or a Map<String, Object>.

Erasure also explains the last big difference: how Java expresses variance.

Variance is at the use site#

A receipt printer should accept any list of payments, including a list that holds only cards. C# declares once, on the interface, that an IEnumerable of cards may be used as an IEnumerable of payments. Java says it at the point of use, with a wildcard:

// Declared once, on the interface: IEnumerable<out T>.
// Contravariance is declared the same way: IComparer<in T>.
void PrintAll(IEnumerable<Payment> payments)
{
    foreach (var p in payments) Console.WriteLine(p);
}

List<Card> cards = new() { new Card("4242") };
PrintAll(cards);  // fine: IEnumerable<Card> converts to IEnumerable<Payment>

// Written where the type is used: List<? extends Payment>.
void printAll(List<? extends Payment> payments) {
    for (var p : payments) System.out.println(p);
}

List<Card> cards = List.of(new Card("4242"));
printAll(cards);  // fine: a List<Card> is a List<? extends Payment>

The other direction, C#'s in, is ? super. This method adds test cards to any list that can hold cards:

void addTestCards(List<? super Card> target) {
    target.add(new Card("0000"));
}

List<Payment> payments = new ArrayList<>();
addTestCards(payments);   // fine: a List<Payment> can hold cards

Here are the four forms a list type can take:

The rest of this chapter covers what erasure costs for numbers, and the tricks libraries use to get type arguments back.

List<Integer> quantities = new ArrayList<>();
quantities.add(42);                        // boxed: stored as an Integer object

int[] raw = new int[1_000_000];            // one block of ints, no objects
int total = IntStream.of(raw).sum();       // a stream of plain ints: nothing is boxed

// The { } creates a subclass whose superclass keeps List<Customer>.
List<Customer> customers = mapper.readValue(json, new TypeReference<List<Customer>>() { });

// Spring's version of the same trick, when calling another service.
List<Customer> body = restClient.get().uri("/customers").retrieve()
        .body(new ParameterizedTypeReference<List<Customer>>() { });

List raw = new ArrayList();          // legal, but the compiler warns
raw.add("mug");
raw.add(1);
String s = (String) raw.get(1);      // compiles, then throws ClassCastException when it runs

Annotations and attributes#

Syntax#

The order API has a controller: a class that answers web requests. Its annotations tell the web framework which web address each method handles. Here is the same controller in ASP.NET Core and in Spring, where orders is the controller's OrderRepository:

[Route("/orders")]
public class OrderController : ControllerBase
{
    [HttpGet("{id}")]
    public Order Get(long id, [FromQuery] bool withLines) => orders.Find(id);
}

@RestController
@RequestMapping("/orders")
public class OrderController {

    @GetMapping("/{id}")
    public Order get(@PathVariable long id, @RequestParam boolean withLines) {
        return orders.find(id);
    }
}

Arguments can be named. Here a method is marked as out of date, with the version that deprecated it and a warning that it will be removed:

[Obsolete("Use FindById instead", DiagnosticId = "SHOP001")]
public Order Find(long id) => FindById(id);

/** @deprecated Use {@link #findById(long)} instead. */
@Deprecated(since = "2.0", forRemoval = true)
public Order find(long id) { return findById(id); }

throw new ArgumentNullException(nameof(order));   // "order", and a rename updates it

Java has no nameof. Names inside annotations and messages are plain strings, so a rename can leave them out of date. IntelliJ's rename updates most of them, and a test is the only real guarantee.

The syntax is the easy part. The next difference is one C# has no word for.

Retention: the concept C# lacks#

The shop wants a log entry every time an order changes. You write your own annotation, @Audited, put it on the methods that change orders, and have code look for it while the program runs. Frameworks such as Spring, Jackson, JUnit and Jakarta Persistence (JPA) find annotations the same way. Whether that code can see an annotation depends on its retention, which says how long it survives:

C# attributes are always kept in the compiled assembly and can always be read by reflection. A Java annotation can disappear before the program runs.

@Retention(RetentionPolicy.RUNTIME)          // the line people forget
public @interface Audited { }

Audited a = method.getAnnotation(Audited.class);   // null without that line

That is all you need to use annotations. The next sections show how to declare one in full, and how the compiler can act on them.

[AttributeUsage(AttributeTargets.Method)]
public class AuditedAttribute : Attribute
{
    public string Action { get; }
    public AuditedAttribute(string action) => Action = action;
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Audited {
    String action();
    String actor() default "system";
}

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public class TagAttribute(string name) : Attribute { }

[Tag("billing"), Tag("slow")]
void Run() { }

@Repeatable(Tags.class)
public @interface Tag { String value(); }

public @interface Tags { Tag[] value(); }  // the container

@Tag("billing") @Tag("slow")
void run() { }

Ones you will see constantly#

A handful of annotations appear in almost every Java codebase. The first six come with Java itself. The rest come from libraries that later chapters cover, including Spring, whose objects are called beans:

Here are three of them at work. Pricing works out the price of an order, and Cart keeps a small cache:

@FunctionalInterface
interface Pricing { BigDecimal price(Order order); }   // a second abstract method will not compile

class Cart {
    private final Map<String, Object> cache = new HashMap<>();

    @SuppressWarnings("unchecked")                     // silence one known warning
    List<String> names() { return (List<String>) cache.get("names"); }

    @Override
    public String toString() { return "Cart"; }        // checked: it must override something
}

Annotations also drive code generation while Java compiles, which is where Java and .NET differ most in practice.

[JsonSerializable(typeof(Order))]
internal partial class AppJson : JsonSerializerContext { }   // the generator fills it in

string json = JsonSerializer.Serialize(order, AppJson.Default.Order);

@Mapper(componentModel = "spring")
public interface OrderMapper {
    OrderDto toDto(Order order);     // MapStruct writes the implementation at compile time
}

var attr = typeof(OrderService)
    .GetMethod("Cancel")!
    .GetCustomAttribute<AuditedAttribute>();
if (attr is not null) Log(attr.Action);

Method cancel = OrderService.class.getMethod("cancel", long.class);
Audited a = cancel.getAnnotation(Audited.class);
if (a != null) log(a.action());

Nullability: Optional and JSpecify#

The gap, stated plainly#

Looking up a customer's nickname can come back empty, because some customers never set one. In C#, the type string? says so, and the compiler makes you check before you use the value. In Java, the type is just String. Here id is the customer's id:

string? name = FindNickname(id);  // may be null
int a = name!.Length;             // "trust me"
int? b = name?.Length;            // null if name is null
string shown = name ?? "none";    // a fallback
name ??= "none";                  // assign only if null

String name = findNickname(id);   // nothing says it may be null
int a = name.length();            // throws if name is null
Integer b = name == null ? null : name.length();
String shown = Objects.requireNonNullElse(name, "none");
if (name == null) name = "none";

// MyApp.csproj: <Nullable>enable</Nullable>
string? name = Find();
Console.WriteLine(name.Length);       // warning CS8602: possibly null
if (name is not null)
    Console.WriteLine(name.Length);   // fine: the compiler saw the check

For a method that may have nothing to return, Java offers a better tool than null.

Optional is for return values#

Finding a customer by id may find nobody. Instead of returning null, the Java repository method can return an Optional<Customer>: a box that holds one customer or is empty. The caller has to open the box, so it cannot forget the empty case:

Customer? Find(long id);

var customer = Find(7);
var name = customer?.Name ?? "unknown";

Optional<Customer> find(long id);

String name = find(7)
        .map(Customer::name)
        .orElse("unknown");

Here are Optional's other methods, with the nearest C#:

find(id).orElse(loadGuestCustomer());            // always calls loadGuestCustomer()
find(id).orElseGet(() -> loadGuestCustomer());   // calls it only when nobody was found

Optional covers return values. For parameters and fields, Java needs annotations, and a tool that checks them.

JSpecify: the annotation standard#

Java has had a dozen competing @Nullable annotations, from javax.annotation, JetBrains, Spring, the Checker Framework and Android. JSpecify is the industry's effort to agree on one set, and Spring Framework 7 moved its whole API to it. First, add the library to your Maven pom.xml:

<dependency>
  <groupId>org.jspecify</groupId>
  <artifactId>jspecify</artifactId>
  <version>1.0.0</version>          <!-- stable since 2024 -->
</dependency>

This is Maven's version of a PackageReference: the groupId, the artifactId and the version together name the library.

Next, declare that everything in a package is non-null unless it is marked otherwise. That goes in a special file, package-info.java, in the package's folder:

// src/main/java/com/acme/billing/package-info.java
@NullMarked                       // everything in this package is non-null by default
package com.acme.billing;

import org.jspecify.annotations.NullMarked;

Inside the package, you mark only the exceptions. Here is the Invoices class, which keeps invoices by id:

// src/main/java/com/acme/billing/Invoices.java, in the same package
import org.jspecify.annotations.Nullable;

public class Invoices {
    private final Map<String, Invoice> byId = new HashMap<>();

    public Invoice load(String id) {             // id and the result are never null
        return Objects.requireNonNull(byId.get(id), "no invoice " + id);
    }

    public @Nullable Invoice find(String id) {   // the result may be null
        return byId.get(id);
    }
}

These are the tools that check the annotations:

public Order(Customer customer)
{
    ArgumentNullException.ThrowIfNull(customer);
    _customer = customer;
}

public Order(Customer customer) {
    this.customer =
        Objects.requireNonNull(customer, "customer");
}

Collections#

The interface hierarchy#

Every Java collection type fits into one family tree, and almost every one has a .NET counterpart. The picture shows the interfaces at the top and the classes you create at the bottom:

Here are an order's product ids, read through each of the two types:

IEnumerable<string> ids = ["mug", "cup"];
foreach (var id in ids) { }       // as often as you like

IEnumerator<string> e = ids.GetEnumerator(); // one pass
while (e.MoveNext()) Console.WriteLine(e.Current);

Iterable<String> ids = List.of("mug", "cup");
for (var id : ids) { }            // as often as you like

Iterator<String> it = ids.iterator();  // one pass
while (it.hasNext()) System.out.println(it.next());

With the family tree in mind, here is how the everyday types are used.

Everyday collections#

The everyday calls translate method by method. Here are a queue of order numbers waiting to be packed, an undo stack, a price list sorted by product, and a cache of stock levels:

var queue = new Queue<long>();
queue.Enqueue(1042); var next = queue.Dequeue();

var stack = new Stack<string>();
stack.Push("add mug"); var undo = stack.Pop();

var prices = new SortedDictionary<string, decimal>
    { ["mug"] = 9.50m, ["cup"] = 4.00m };
KeyValuePair<string, decimal> first = prices.First();

var cache = new ConcurrentDictionary<string, int>();
cache.GetOrAdd("mug", _ => 12);

Deque<Long> queue = new ArrayDeque<>();
queue.offer(1042L); var next = queue.poll();

Deque<String> stack = new ArrayDeque<>();
stack.push("add mug"); var undo = stack.pop();

var prices = new TreeMap<>(Map.of(
    "mug", new BigDecimal("9.50"), "cup", new BigDecimal("4.00")));
Map.Entry<String, BigDecimal> first = prices.firstEntry();

var cache = new ConcurrentHashMap<String, Integer>();
cache.computeIfAbsent("mug", k -> 12);

var od = new OrderedDictionary<string, int> { ["b"] = 2, ["a"] = 1 };
foreach (var (key, value) in od) Console.Write(key);   // "ba": insertion order
int second = od.GetAt(1).Value;                         // 1: read by position

The quick reference at the end of this chapter lists every .NET collection type with its Java counterpart. Next comes creating collections, where Java has a trap.

Creating collections#

C# has collection expressions and initialisers. Java has factory methods such as List.of, and they return collections that cannot be changed. Here are an order's product ids, its quantities and its tags:

// collection expression
List<string> a = ["mug", "cup"];
var b = new List<string> { "mug", "cup" };
var c = new Dictionary<string, int> { ["mug"] = 2 };
IReadOnlyList<string> d = ["mug"];
var tags = new HashSet<string> { "gift" };
var frozen = ImmutableList.Create("mug", "cup");

var a = new ArrayList<>(List.of("mug", "cup"));
var b = List.of("mug", "cup");       // fixed
var c = Map.of("mug", 2);            // fixed
List<String> d = List.of("mug");
var tags = new HashSet<>(Set.of("gift"));
var frozen = List.of("mug", "cup");  // fixed

The last everyday trap is changing a collection while a loop is reading it.

Modifying while iterating#

Cleaning up an order's tags means removing the blank ones. Removing from a list while a for loop walks over it fails in both languages. C# offers RemoveAll on a List<T>. Java has the same idea, removeIf, and its Iterator can also remove:

// usually throws ConcurrentModificationException
for (var tag : tags) if (tag.isBlank()) tags.remove(tag);

// correct: removeIf is the usual answer
tags.removeIf(String::isBlank);

// correct: remove through the iterator itself
var it = tags.iterator();
while (it.hasNext()) if (it.next().isBlank()) it.remove();

The remaining sections cover a naming habit, the Java 21 methods for first and last elements, and the old collections you will meet in legacy code.

List<String> productIds = new ArrayList<>();            // yes
Map<String, Integer> stock = new HashMap<>();           // yes

ArrayList<String> overSpecified = new ArrayList<>();    // avoid

var ids = new ArrayList<>(List.of("mug", "cup", "pot"));

ids.getFirst();        // "mug", was ids.get(0)
ids.getLast();         // "pot", was ids.get(ids.size() - 1)
ids.addFirst("tray");
ids.reversed();        // a reversed view, not a copy

var stock = new LinkedHashMap<String, Integer>();
stock.put("mug", 12);
stock.put("cup", 3);
stock.firstEntry();    // mug=12, the first one added

Vector<String> old = new Vector<>();          // locks on every call
List<String> list = new ArrayList<>();        // write this instead

Stack<Integer> oldStack = new Stack<>();      // extends Vector, and iterates bottom first
Deque<Integer> stack = new ArrayDeque<>();    // push, pop and peek, with no locking