DEV Community: Mayur Bodhare

What Does SpringApplication.run Actually Do?

Mayur Bodhare — Tue, 27 Oct 2026 07:01:48 +0000

When I started writing bigger Java programs, I noticed something annoying. Every class created the objects it needed with new. A Dev class created its own Laptop. The Laptop class created its own Battery. And when I wanted to change one small thing, like using a Desktop instead, I had to open and edit class after class.

Then someone told me about Spring, and described it like this: "You don't create the objects. Spring creates them for you when you need them."

That one sentence is the base idea behind both the Spring Framework and Spring Boot. In this post, we'll unpack it step by step: what problem Spring solves, what IoC and DI really mean, how the Spring container works, how configuration worked in the XML days (and what <beans>, <bean>, <property>, <constructor-arg>, autowire and primary do), how annotations like @Component, @Autowired, @Primary and @Qualifier replaced it, and finally what Spring Boot adds on top, including the meaning of that starter code everyone copies without understanding.

I wrote this for Spring Framework 7 and Spring Boot 4.x, which need Java 17 or newer. I've drawn the key pictures in text so you can see how everything connects.

The problem: creating objects yourself
- Tight coupling with new
- Loose coupling with an interface
What is the Spring Framework?
- A short history
- The main modules
IoC and DI
- Inversion of Control
- Dependency Injection
- IoC vs DI
- The Spring container and beans
Spring with XML: the classic way
- Project setup
- The Java classes
- Understanding spring.xml
- Running the XML configuration
- Injecting with property and constructor arguments
- Autowiring in XML: byName and byType
- Resolving conflicts with primary
- Scope: singleton and prototype
Annotation and Java configuration
- Stereotype annotations: @Component and friends
- Java configuration: @Configuration and @Bean
What is Spring Boot?
- The base idea
- What Spring Boot adds
Spring vs Spring Boot vs Spring Web
Spring Boot architecture
- Inside Spring Boot
- How @SpringBootApplication works
- The layers of a Spring Boot application
Your first Spring Boot application
- Creating the project with Spring Initializr
- Understanding the starter code
- Adding beans: Dev, Computer and Laptop
- Running the application
The three types of dependency injection
- Constructor injection
- Setter injection
- Field injection
- Which injection to use
Resolving ambiguity: @Primary and @Qualifier
The lifecycle of a bean
Building a web endpoint with Spring Web
Configuration with application.properties
Running, packaging and testing
Best practices
Which one should I use?
Common mistakes
Quick recap
Try it yourself

The problem: creating objects yourself

Tight coupling with new

Let's start with plain Java, no Spring. A developer (Dev) builds a project on a laptop:

public class Laptop {
    public void compile() {
        System.out.println("Compiling on Laptop");
    }
}

public class Dev {
    private Laptop laptop = new Laptop();      // Dev creates its own helper

    public void build() {
        System.out.println("Dev is building the project...");
        laptop.compile();
    }
}

public class App {
    public static void main(String[] args) {
        Dev dev = new Dev();
        dev.build();
    }
}

Output:

Dev is building the project...
Compiling on Laptop

It works, but look at the problems:

Dev is stuck with Laptop. To use a Desktop, you must edit the Dev class.
Dev must know how to build its helper. If Laptop needs a Battery and a Charger, Dev has to create those too.
It's hard to test Dev alone, because you can't replace the real Laptop with a fake one.

   TIGHT COUPLING

   Dev  ---- creates ---->  new Laptop()        Dev decides AND builds its own helper

Loose coupling with an interface

The first fix is to depend on an interface, and to receive the helper from outside, instead of creating it:

public interface Computer {
    void compile();
}

public class Laptop implements Computer {
    public void compile() { System.out.println("Compiling on Laptop"); }
}

public class Desktop implements Computer {
    public void compile() { System.out.println("Compiling on Desktop"); }
}

public class Dev {
    private final Computer computer;

    public Dev(Computer computer) {            // the helper is GIVEN to Dev
        this.computer = computer;
    }

    public void build() {
        System.out.println("Dev is building the project...");
        computer.compile();
    }
}

Dev dev = new Dev(new Laptop());      // or new Dev(new Desktop())
dev.build();

Now Dev doesn't care which computer it gets. It only knows the Computer interface. That's called dependency injection, and we just did it by hand.

But there's a new problem: someone has to write all that wiring code. In a real application with hundreds of classes, main would become a giant list of new calls in exactly the right order. This is what Spring automates. It builds the objects and passes them to each other for you.

What is the Spring Framework?

The Spring Framework is an open-source Java framework. Its core is a container that creates your objects, connects them to each other and manages their whole life. On top of that core, Spring offers support for web applications, databases, transactions, security, testing and more.

A short history

In the early 2000s, enterprise Java (J2EE) was heavy and complicated, especially EJBs. Rod Johnson described a simpler approach in his 2002 book, and the code that came with it grew into Spring.
Spring's idea was that you write plain Java objects (POJOs), and the framework connects them. The name is often explained as a "fresh start" after the heavy J2EE years.
Spring Framework 1.0 came out in 2004. It has been updated steadily since. Version 6 (2022) moved to Java 17 and the jakarta packages, and version 7 arrived in late 2025.
Plain Spring still needed a lot of setup, so Spring Boot 1.0 was released in 2014 to remove most of it. Spring Boot 4.0 came out in November 2025, built on Spring Framework 7, and 4.1 followed in June 2026.

The main modules

Spring is split into modules, so you only use what you need:

   SPRING FRAMEWORK
   +--------------------------------------------------------------------+
   |  CORE CONTAINER     core, beans, context, expression language      |  <- IoC and DI live here
   +--------------------------------------------------------------------+
   |  AOP                aspect-oriented programming (logging, security)|
   |  DATA ACCESS        JDBC, ORM (Hibernate/JPA), transactions        |
   |  WEB                spring-web, spring-webmvc, spring-webflux      |
   |  TEST               support for JUnit and mock environments        |
   +--------------------------------------------------------------------+

   Related projects built on it: Spring Data, Spring Security, Spring Batch, Spring Cloud ...

Everything else depends on the core container, so that's what we'll focus on first.

IoC and DI

Inversion of Control

Normally, your code is in control: it decides which objects to create, when to create them and how to connect them.

Inversion of Control (IoC) flips that. You describe what you need, and a container takes control of creating and connecting objects. The control is "inverted": from your code to the framework. People sometimes call it the Hollywood principle: "Don't call us, we'll call you."

   WITHOUT IoC                                     WITH IoC (Spring)

   your code:                                      your code:
     laptop = new Laptop()                           "I need a Dev"
     dev    = new Dev(laptop)                              |
     dev.build()                                           v
                                                    SPRING CONTAINER
   YOU create and wire everything                     creates Laptop
                                                      creates Dev, gives it the Laptop
                                                      hands you the finished Dev

Dependency Injection

A dependency is an object that another object needs. Dev depends on a Computer.

Dependency Injection (DI) means the dependency is handed in from outside, instead of being created inside. Think of a company: a developer doesn't build their own laptop. The IT department gives them one. The developer just uses it.

In Spring, the container is the IT department. It builds the Laptop, builds the Dev, and injects the laptop into the dev. There are three ways it can hand things over: through the constructor, through a setter method or directly into a field. We'll look at all three later.

IoC vs DI

These two terms are mixed up constantly:

IoC is the big principle: some framework controls object creation and wiring, not your code.
DI is the technique used to achieve it: the container gives each object what it needs.

All DI is IoC, but IoC is a bigger idea. There's also a second form of IoC called dependency lookup, where your code asks the container for an object. A call like context.getBean(Dev.class) is a lookup, not an injection.

   IoC   (the principle: the container is in control)
     |
     |-- Dependency Injection   the container GIVES objects what they need   (most common)
     +-- Dependency Lookup      your code ASKS the container:  context.getBean(...)

The Spring container and beans

The Spring container (also called the IoC container) is the part of Spring that creates objects, connects them and manages their entire lifecycle: creating them, injecting their dependencies, initializing them and finally destroying them. The objects it manages are called beans. A bean isn't a special kind of class. It's just an ordinary Java object that the container created and looks after.

To know what to create, the container needs configuration metadata. That can be XML, annotations or Java code, and we'll see all three.

There are two container interfaces:

BeanFactory: the basic container, which creates and wires beans.
ApplicationContext: extends BeanFactory with more features, like event publishing, reading properties, resource loading, internationalization and easy integration with other Spring features. This is the one you use.

When people say "the context," they mean the ApplicationContext: the box that holds all your beans.

   configuration metadata            your classes
   (XML / annotations / Java)        (Laptop, Dev ...)
              \                         /
               v                       v
          +----------------------------------+
          |   SPRING CONTAINER               |
          |   (ApplicationContext)           |
          |   creates, wires, manages        |
          |   [laptop]  [dev]  [...]         |   <- the beans
          +----------------------------------+
                      |
                      v   getBean(...)  or  injection
                  your application

Spring with XML: the classic way

Before annotations, Spring was configured with XML files. It's still fully supported, you'll meet it in older projects and interviews, and understanding it makes the modern annotation style much clearer.

Project setup

Create a plain Maven project (see my Maven post) and add Spring's core context library. I'll import the Spring BOM so the versions stay in sync:

<properties>
  <maven.compiler.release>17</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-framework-bom</artifactId>
      <version>7.0.10</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
  </dependency>
</dependencies>

(Use the newest 7.0.x version you can find.) The XML file goes in the resources folder:

   my-spring-app/
   |-- pom.xml
   +-- src/main/
        |-- java/com/example/   <- Computer, Laptop, Desktop, Dev, App
        +-- resources/spring.xml

The Java classes

We reuse Computer, Laptop and Desktop from before. Dev now has setters and two constructors, so Spring can build it in different ways:

public class Dev {
    private String name;
    private Computer comp;

    public Dev() { }

    public Dev(String name, Computer comp) {
        this.name = name;
        this.comp = comp;
    }

    public void setName(String name) { this.name = name; }
    public void setComp(Computer comp) { this.comp = comp; }

    public void build() {
        System.out.println(name + " is building the project...");
        comp.compile();
    }
}

Notice there's no Spring code at all in these classes. They're plain Java objects. All the Spring knowledge lives in the XML.

Understanding spring.xml

Here is the configuration file, src/main/resources/spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           https://www.springframework.org/schema/beans/spring-beans.xsd">

    <bean id="laptop" class="com.example.Laptop"/>

    <bean id="dev" class="com.example.Dev">
        <property name="name" value="Asha"/>
        <property name="comp" ref="laptop"/>
    </bean>

</beans>

What each part means:

<?xml ...?>: the standard first line of any XML file.
<beans>: the root tag. Everything inside is a bean definition. Its attributes (xmlns, xsi:schemaLocation) tell the XML parser which schema (a rule book) defines the valid tags. They also let your IDE autocomplete and check the file.
<bean>: defines one object.
- id: a unique name for this bean. You use it in ref and in getBean("dev").
- class: the full class name Spring should create. Spring creates it using reflection, with the no-argument constructor unless you provide <constructor-arg>.
<property>: setter injection.
- name: the property name. name="comp" makes Spring call setComp(...).
- value: a plain value (a string, number or boolean). Spring converts "Asha" to a String.
- ref: a reference to another bean, by its id.
<constructor-arg>: constructor injection (we'll use it in a moment).

You can think of this file as Spring executing the Java code you used to write yourself:

Laptop laptop = new Laptop();
Dev dev = new Dev();
dev.setName("Asha");
dev.setComp(laptop);

Running the XML configuration

package com.example;

import org.springframework.context.support.ClassPathXmlApplicationContext;

public class App {
    public static void main(String[] args) {
        try (ClassPathXmlApplicationContext context =
                     new ClassPathXmlApplicationContext("spring.xml")) {

            Dev dev = context.getBean(Dev.class);
            dev.build();
        }
    }
}

Output:

Asha is building the project...
Compiling on Laptop

ClassPathXmlApplicationContext("spring.xml") creates the container. It looks for spring.xml on the classpath (the resources folder ends up there), reads the bean definitions and creates the objects. (FileSystemXmlApplicationContext loads a file from a disk path instead.)
context.getBean(Dev.class) asks the container for the bean of type Dev. You can also ask by id: context.getBean("dev"), or by both: context.getBean("dev", Dev.class).
The context is closable, so try-with-resources shuts it down (and destroys the beans) at the end.

Notice we never wrote new Dev(). The container made it.

Injecting with property and constructor arguments

Besides <property>, you can inject through the constructor with <constructor-arg>:

<bean id="dev" class="com.example.Dev">
    <constructor-arg value="Asha"/>
    <constructor-arg ref="laptop"/>
</bean>

By default, the arguments are matched in order. You can be explicit with index="0", type="..." or name="comp". The output is the same.

Now the best part. To switch to a desktop, change one word in the XML, with no Java changes at all:

<constructor-arg ref="desktop"/>

(After adding <bean id="desktop" class="com.example.Desktop"/>.)

Asha is building the project...
Compiling on Desktop

A rule of thumb: use <constructor-arg> for things the object must have, and <property> for optional or changeable settings.

Autowiring in XML: byName and byType

Writing ref for every dependency gets tedious. Autowiring lets Spring find the dependencies itself. The autowire attribute has these main values:

no: the default. No autowiring. You write ref yourself.
byType: Spring looks at the type of each property (Computer) and finds a bean of that type.
byName: Spring looks at the name of each property (comp) and finds a bean with the same id.
constructor: like byType, but for constructor arguments.

(The values are case-sensitive: write byType, not ByType.)

byType with exactly one Computer bean:

<bean id="laptop" class="com.example.Laptop"/>

<bean id="dev" class="com.example.Dev" autowire="byType">
    <property name="name" value="Asha"/>
</bean>

There's no <property name="comp" ...>. Spring noticed that Dev has a setComp(Computer) method, found the one Computer bean (laptop) and injected it. Autowiring only applies to objects. Simple values like the name string still need <property value="...">.

Now add a second Computer bean, and Spring can't decide:

<bean id="laptop" class="com.example.Laptop"/>
<bean id="desktop" class="com.example.Desktop"/>

<bean id="dev" class="com.example.Dev" autowire="byType">
    <property name="name" value="Asha"/>
</bean>

UnsatisfiedDependencyException: Error creating bean with name 'dev' ...
Unsatisfied dependency expressed through bean property 'comp':
No qualifying bean of type 'com.example.Computer' available:
expected single matching bean but found 2: laptop,desktop

Two beans match the type, so Spring refuses to guess. One fix is byName:

<bean id="comp" class="com.example.Laptop"/>
<bean id="desktop" class="com.example.Desktop"/>

<bean id="dev" class="com.example.Dev" autowire="byName">
    <property name="name" value="Asha"/>
</bean>

Asha is building the project...
Compiling on Laptop

It works because Dev has a property named comp, and there's a bean whose id is comp. The desktop bean is ignored. The matching is by name, so the bean id and the property name must agree exactly.

Resolving conflicts with primary

The other fix is to mark one bean as the preferred choice with primary="true":

<bean id="laptop" class="com.example.Laptop" primary="true"/>
<bean id="desktop" class="com.example.Desktop"/>

<bean id="dev" class="com.example.Dev" autowire="byType">
    <property name="name" value="Asha"/>
</bean>

Asha is building the project...
Compiling on Laptop

When several beans match, Spring picks the primary one. There's also a related attribute, autowire-candidate="false", which removes a bean from autowiring completely:

<bean id="desktop" class="com.example.Desktop" autowire-candidate="false"/>

Scope: singleton and prototype

By default, Spring creates one instance of each bean and shares it. That's the singleton scope (one per container, not the same as the singleton design pattern). You can ask for a new object every time with scope="prototype":

<bean id="dev" class="com.example.Dev" scope="prototype"/>

Dev a = context.getBean(Dev.class);
Dev b = context.getBean(Dev.class);
System.out.println(a == b);

Default (singleton): prints true. Both variables hold the same object.
With scope="prototype": prints false. Each getBean creates a new one.

Singleton beans are created when the container starts (eagerly). Add lazy-init="true" to create one only when it's first needed. In web applications there are more scopes too, like request and session.

XML works, but it has downsides: it's wordy, the configuration is far from the code, and typos in class names show up only at run time. That's why Spring moved toward annotations.

Annotation and Java configuration

Stereotype annotations: @Component and friends

Instead of declaring each bean in XML, you put @Component on the class. Spring finds those classes by component scanning:

@Component
public class Laptop implements Computer {
    // ...
}

To turn scanning on in plain Spring, you add a configuration class:

@Configuration
@ComponentScan("com.example")
public class AppConfig { }

AnnotationConfigApplicationContext context =
        new AnnotationConfigApplicationContext(AppConfig.class);

(In XML, the same switch is <context:component-scan base-package="com.example"/>.)

@Component has specialized versions that say what the class is for. They're all components underneath:

@Service: business logic.
@Repository: data access (it also converts database exceptions into Spring's exception types).
@Controller and @RestController: web request handlers.

The default bean name is the class name with a lowercase first letter (Laptop becomes laptop). You can set your own with @Component("comp").

Here's how the XML ideas you just learned map to annotations:

   XML                                       ANNOTATIONS
   <bean id="laptop" class="...Laptop"/>     @Component on the class Laptop
   <property ref> / <constructor-arg ref>    constructor parameter, or @Autowired
   autowire="byType"                         @Autowired (matches by type)
   autowire="byName"                         @Autowired + @Qualifier("name")
   primary="true"                            @Primary
   scope="prototype"                         @Scope("prototype")
   lazy-init="true"                          @Lazy
   init-method / destroy-method              @PostConstruct / @PreDestroy
   ClassPathXmlApplicationContext            AnnotationConfigApplicationContext
                                             (or SpringApplication.run in Spring Boot)

Java configuration: @Configuration and @bean

What if you can't put @Component on a class, because it comes from a library? Or the creation needs custom steps? Use a @Bean method in a @Configuration class:

@Configuration
public class AppConfig {

    @Bean
    public Computer laptop() {
        return new Laptop();
    }

    @Bean
    public Dev dev(Computer computer) {
        return new Dev("Asha", computer);      // Spring supplies "computer"
    }
}

The bean's name is the method name (laptop, dev), and method parameters are injected by Spring. A quick rule: use @Component for classes you write, and @Bean for classes you don't own or that need special setup.

What is Spring Boot?

With the Spring Framework alone, you still have a lot to do before your first line of real code. You must pick compatible versions of many libraries, write configuration for the database, the web layer and transactions, install and configure a server like Tomcat, and package the app for deployment.

Spring Boot removes most of that work. It isn't a different framework. It's Spring, with the setup done for you.

The base idea

Remember the sentence at the start? Spring Boot creates the objects for you, when you need them.

You write your own classes and mark them (@Component, @Service, @RestController). Boot's container creates them and wires them together, just like plain Spring. But Boot also creates the infrastructure objects automatically, based on what's in your project:

Add the web starter, and Boot creates an embedded Tomcat server, the request dispatcher and the JSON converters.
Add a database starter and driver, and Boot creates a connection pool, and with JPA, Hibernate's factory and a transaction manager (the objects we built by hand in my Hibernate post).

   your classes  +  starters (what's on the classpath)  +  application.properties
                              |
                              v
                       SPRING BOOT
              creates and wires the beans for you
                              |
                              v
                   a running application

You describe what you need, and Boot builds it.

What Spring Boot adds

Starters: one dependency (like spring-boot-starter-webmvc) that brings a whole matching set of libraries. No more hunting for compatible versions.
Auto-configuration: Boot configures beans automatically based on your classpath and properties.
An embedded server: Tomcat is built in, so the app runs with java -jar. No separate server and no WAR deployment.
Sensible defaults: convention over configuration. You override only what you need.
No XML needed.
application.properties: one place for settings.
Production features: the Actuator module adds health checks and metrics, for example /actuator/health.
Developer tools: quick restarts, an initializer website, and good testing support.

Spring vs Spring Boot vs Spring Web

These three names cause the most confusion, so here's how they relate:

Spring Framework is the foundation: the IoC container, dependency injection, transactions, data access and more. You configure everything yourself.
Spring Web is the part of the framework for web applications and REST APIs. It has two main sets of modules: spring-web (HTTP basics and clients) and spring-webmvc (Spring MVC, the controller-based web framework). There's also Spring WebFlux, a reactive alternative. These are modules inside the Spring Framework.
Spring Boot is a layer on top that sets all of this up for you: starters, auto-configuration, an embedded server and packaging.

   +--------------------------------------------------------------------------+
   |  SPRING BOOT                                                              |
   |  starters  ·  auto-configuration  ·  embedded server  ·  Actuator         |
   +--------------------------------------------------------------------------+
   |  SPRING WEB MVC / WEBFLUX      |  SPRING DATA  |  SPRING SECURITY  |  ... |
   +--------------------------------------------------------------------------+
   |  SPRING FRAMEWORK CORE: IoC container, dependency injection, AOP ...      |
   +--------------------------------------------------------------------------+
   |  JAVA / JVM                                                               |
   +--------------------------------------------------------------------------+

Here's how they differ in practice:

Setup: Spring needs manual setup (dependencies, configuration, server). Boot generates a ready project in seconds.
Configuration: Spring uses XML or Java config you write. Boot auto-configures and you override what you need.
Server: with Spring you deploy a WAR to a server you installed. With Boot the server is embedded.
Versions: with Spring you pick compatible library versions yourself. With Boot, the starters and parent manage them.
Packaging: Spring usually produces a WAR. Boot produces an executable JAR.
Control: Spring gives you full control, with more work. Boot gives sensible defaults, with less work.

About names: when you pick "Spring Web" on the Spring Initializr website, you get Spring MVC and an embedded Tomcat. In Spring Boot 4, that starter is called spring-boot-starter-webmvc. Before Boot 4, it was spring-boot-starter-web. The old name is deprecated in the newest versions, but you'll still see it in older tutorials.

Also remember: Boot doesn't replace Spring. Everything you learned about the container, beans and injection still applies. That's why we learn those first.

Spring Boot architecture

Inside Spring Boot

Spring Boot is built from a few key parts:

SpringApplication: the class that starts your application.
Starters: dependency bundles.
Auto-configuration: the logic that creates beans for you.
The Environment: your settings, from application.properties, environment variables and command-line arguments.
The embedded server: Tomcat by default.
Actuator: optional monitoring.

Here's what happens when you call SpringApplication.run(...):

   SpringApplication.run(DemoApplication.class, args)
        |
        1. create the ApplicationContext   (the container)
        |
        2. load the environment            (application.properties, env variables, command line)
        |
        3. component scan                  find @Component, @Service, @RestController ... classes
        |
        4. auto-configuration              add beans based on the classpath and properties
        |                                  (web server, DataSource, JSON converters ...)
        5. create all singleton beans, inject their dependencies
        |
        6. start the embedded web server   (only if a web starter is present)
        |
        7. the application is running      (the context is closed when the app shuts down)

(Spring Boot 4 also split its internals into smaller, focused modules, but the process above stays the same.)

How @SpringBootApplication works

One annotation on your main class does a lot. @SpringBootApplication is a shortcut for three annotations:

@SpringBootApplication
// ... is the same as combining:
@SpringBootConfiguration     // this class is a configuration class (like @Configuration)
@EnableAutoConfiguration     // turn on auto-configuration
@ComponentScan               // scan this package and its sub-packages for @Component classes

Auto-configuration works like this. Spring Boot's jars contain a list of auto-configuration classes (in a file named META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports). Each one is guarded by conditions, such as:

@ConditionalOnClass: only apply if a certain class is on the classpath.
@ConditionalOnMissingBean: only apply if you haven't defined your own bean.
@ConditionalOnProperty: only apply if a property is set.

For example, if a database driver is on the classpath and you haven't defined a DataSource yourself, Boot creates one from your spring.datasource.* properties. If you define your own DataSource, Boot backs off and uses yours. If you ever wonder why a bean exists (or doesn't), start the app with --debug to print a report of every condition that was checked.

An important consequence: component scanning starts at the package of your main class. Classes outside that package and its sub-packages are not found. That's why the main class sits in the root package of the project.

The layers of a Spring Boot application

A typical Spring Boot web application is organized in layers, and each layer is a bean that gets the next layer injected:

   Browser / mobile app / Postman
            |   HTTP request
            v
   EMBEDDED TOMCAT  -->  DispatcherServlet  (Spring MVC's front controller)
                              |
                              v
        +-------------------------------+
        |  CONTROLLER  (@RestController)|   handles HTTP: URLs, parameters, JSON
        +-------------------------------+
                      |  calls
                      v
        +-------------------------------+
        |  SERVICE     (@Service)       |   business logic, transactions
        +-------------------------------+
                      |  calls
                      v
        +-------------------------------+
        |  REPOSITORY  (@Repository)    |   talks to the database (JPA / JDBC)
        +-------------------------------+
                      |
                      v
                  DATABASE

The rule: each layer talks only to the layer below it. Controllers don't touch the database, and repositories hold no business rules. Spring wires the layers together with dependency injection.

Your first Spring Boot application

Creating the project with Spring Initializr

The easiest way to start is the Spring Initializr website, start.spring.io. Choose:

Project: Maven
Language: Java
Spring Boot: the newest stable 4.x version (not a SNAPSHOT or release candidate)
Group: com.example
Artifact: demo
Packaging: Jar
Java: 17 or newer (21 is a good choice)
Dependencies: none for the first example. Later, we'll add Spring Web.

Click Generate, unzip the file and open the folder in your IDE. (IDEs like IntelliJ IDEA also have this built in.) You get this project:

   demo/
   |-- pom.xml
   |-- mvnw, mvnw.cmd, .mvn/            <- the Maven Wrapper (run Maven without installing it)
   +-- src/
        |-- main/
        |    |-- java/com/example/demo/DemoApplication.java
        |    +-- resources/application.properties
        +-- test/java/com/example/demo/DemoApplicationTests.java

The generated pom.xml (trimmed) looks like this:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.0</version>
    <relativePath/>
</parent>

<properties>
    <java.version>21</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

The parent (spring-boot-starter-parent) manages the versions of hundreds of libraries, and sets up sensible build defaults. That's why the dependencies below have no version numbers.
spring-boot-starter is the core starter: Spring, logging and auto-configuration.
spring-boot-starter-test brings testing tools (test scope only).
The Spring Boot Maven plugin builds the runnable JAR.

(The version 4.1.0 is just an example. Use whatever Initializr generates for you.)

Understanding the starter code

Open DemoApplication.java. This is the code everyone copies without understanding:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Let's decode it word by word. First, a version of main that actually uses the result:

ApplicationContext context = SpringApplication.run(DemoApplication.class, args);
Dev dev = context.getBean(Dev.class);
dev.build();

@SpringBootApplication marks this as the starting configuration class, and turns on auto-configuration and component scanning (see the earlier section).
SpringApplication is the Boot class that starts everything.
SpringApplication.run(DemoApplication.class, args): this one call creates the container, loads the settings, scans for components, applies auto-configuration, creates all the beans and (for web apps) starts the server.
- DemoApplication.class is the main configuration class, where scanning begins.
- args are the command-line arguments, like --server.port=9090.
context (the ApplicationContext) is the Spring container: the object that holds all your beans. run returns it.
context.getBean(Dev.class) asks the container for the bean of type Dev (dependency lookup).
A bean is any object the container created and manages.
@Component (next) is what makes Dev a bean in the first place.

And notice the most important thing again: we never wrote new Dev().

Adding beans: Dev, Computer and Laptop

Create these three files in com.example.demo, next to DemoApplication:

public interface Computer {
    void compile();
}

@Component
public class Laptop implements Computer {

    @Override
    public void compile() {
        System.out.println("Compiling on Laptop");
    }
}

@Component
public class Dev {

    private final Computer computer;

    public Dev(Computer computer) {
        this.computer = computer;
    }

    public void build() {
        System.out.println("Dev is building the project...");
        computer.compile();
    }
}

(Import org.springframework.stereotype.Component in the last two.) Here's what's going on:

@Component on Laptop and Dev makes them beans. Spring finds them because they're in the same package as the main class.
Dev needs a Computer. Spring sees the constructor, finds a Computer bean (Laptop) and injects it automatically.
There's no @Autowired on the constructor, because a class with a single constructor doesn't need it.

Running the application

Use the version of main that calls getBean, then run:

./mvnw spring-boot:run

Output (after the Spring banner and a few INFO log lines):

Dev is building the project...
Compiling on Laptop

What if you forget @Component on Laptop? Spring can't find a Computer, and the app fails to start with a clear message:

APPLICATION FAILED TO START

Description:

Parameter 0 of constructor in com.example.demo.Dev required a bean of type
'com.example.demo.Computer' that could not be found.

Action:

Consider defining a bean of type 'com.example.demo.Computer' in your configuration.

The three types of dependency injection

There are three ways the container can hand a dependency to your object. Let's write Dev all three ways.

Constructor injection

The dependency comes in through the constructor:

@Component
public class Dev {

    private final Computer computer;

    public Dev(Computer computer) {       // no @Autowired needed
        this.computer = computer;
    }
    ...
}

It needs no @Autowired when the class has one constructor (this has been true since Spring 4.3). If a class has several constructors, mark the one Spring should use with @Autowired.
Spring must create the Laptop first, then call the Dev constructor with it.

Setter injection

The dependency comes in through a setter method:

@Component
public class Dev {

    private Computer computer;

    @Autowired
    public void setComputer(Computer computer) {
        this.computer = computer;
    }
    ...
}

It needs @Autowired on the setter. Without it, Spring creates the object with the default constructor and never calls the setter, so computer stays null.
Spring creates Dev first (with the no-argument constructor), then calls the setter.

Field injection

The dependency is placed directly into the field:

@Component
public class Dev {

    @Autowired
    private Computer computer;
    ...
}

It needs @Autowired on the field.
Spring creates Dev, then uses reflection to set the private field. There's no constructor or setter involved.

All three give the same output:

Dev is building the project...
Compiling on Laptop

Which injection to use

                         NEEDS @Autowired?        BEST FOR
   Constructor           No (one constructor)     required dependencies  <-- recommended
   Setter                Yes                      optional or changeable dependencies
   Field                 Yes                      quick demos and test classes

Use constructor injection by default. The reasons:

The dependency can be final, so the object can't be left half-built.
Required dependencies are obvious from the constructor.
It's easy to test: new Dev(new FakeComputer()), with no Spring needed.
Missing beans and circular dependencies are caught at startup, not later. (Spring Boot refuses circular references by default.)

Field injection looks shorter, but it hides the dependencies, can't use final, can't be tested without Spring or reflection, and the field stays null if someone creates the object with a plain new. Setter injection is a good choice for optional dependencies, and you can use @Autowired(required = false) for those.

Resolving ambiguity: @primary and @Qualifier

What happens when two beans match? Add a Desktop next to Laptop:

@Component
public class Desktop implements Computer {

    @Override
    public void compile() {
        System.out.println("Compiling on Desktop");
    }
}

Now Dev asks for a Computer and gets two candidates. Spring Boot refuses to start:

APPLICATION FAILED TO START

Description:

Parameter 0 of constructor in com.example.demo.Dev required a single bean, but 2 were found:
    - desktop: defined in file [.../Desktop.class]
    - laptop: defined in file [.../Laptop.class]

Action:

Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans,
or using @Qualifier to identify the bean that should be consumed

The error message itself tells you the fixes.

Fix 1: @Primary. Mark one bean as the default choice:

@Component
@Primary
public class Laptop implements Computer { ... }

Compiling on Laptop

Fix 2: @Qualifier. Name the exact bean at the place where you inject it:

public Dev(@Qualifier("desktop") Computer computer) {
    this.computer = computer;
}

Compiling on Desktop

The name "desktop" is the bean's default name (the class name with a lowercase first letter). You can set your own with @Component("fast") and then use @Qualifier("fast"). With field injection, you write both annotations together:

@Autowired
@Qualifier("desktop")
private Computer computer;

How they differ:

@Primary is a default for the whole application: "if nobody says otherwise, use this one."
@Qualifier is an explicit choice at one injection point. If both are present, @Qualifier wins.

These map to the XML ideas you saw earlier: @Primary is like primary="true", and @Qualifier is like autowire="byName".

There are two more ways to deal with several beans:

Match by name: if the parameter is named desktop (public Dev(Computer desktop)), Spring falls back to matching the name. It works, but renaming the parameter silently changes the behavior, so @Qualifier is safer.
Inject them all: ask for List<Computer> or Map<String, Computer>, and Spring gives you every matching bean.

The lifecycle of a bean

Here's what "Spring manages the lifecycle of all your objects" means. Every bean goes through the same stages:

   1. INSTANTIATE        the constructor is called
          |
          v
   2. INJECT             dependencies are set (constructor, setter or field)
          |
          v
   3. INITIALIZE         @PostConstruct methods run
          |
          v
   4. READY              the bean is used by your application
          |
          v
   5. DESTROY            @PreDestroy methods run when the container shuts down

Let's watch it happen by adding messages to Laptop:

@Component
public class Laptop implements Computer {

    public Laptop() {
        System.out.println("Laptop: constructor called");
    }

    @PostConstruct
    public void init() {
        System.out.println("Laptop: @PostConstruct, ready to use");
    }

    @Override
    public void compile() {
        System.out.println("Compiling on Laptop");
    }

    @PreDestroy
    public void cleanup() {
        System.out.println("Laptop: @PreDestroy, shutting down");
    }
}

(@PostConstruct and @PreDestroy come from jakarta.annotation.) Run the app. Output (between the Spring log lines):

Laptop: constructor called
Laptop: @PostConstruct, ready to use
Dev is building the project...
Compiling on Laptop
Laptop: @PreDestroy, shutting down

Things to notice:

Singleton beans are created when the application starts, in dependency order (the Laptop before the Dev that needs it).
Our main didn't call any of these methods. The container did.
When the application ends, the container closes and calls @PreDestroy on each singleton. This is the place to close resources like files or connections.

A few related facts: the default scope is singleton (one shared bean). You can use @Scope("prototype") to get a new instance each time, but then Spring doesn't call destroy methods for it. @Lazy delays creation until first use. And because singletons are shared by all threads, keep them stateless: don't store per-request data in their fields.

Building a web endpoint with Spring Web

Now let's use Spring Web. Add the dependency (on Initializr, pick Spring Web, or add this to pom.xml):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

(In Spring Boot 3.x, this starter is called spring-boot-starter-web.) Then add a service and a controller:

@Service
public class GreetingService {

    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

@RestController
public class HelloController {

    private final GreetingService greetingService;

    public HelloController(GreetingService greetingService) {
        this.greetingService = greetingService;
    }

    @GetMapping("/hello")
    public String hello(@RequestParam(name = "name", defaultValue = "World") String name) {
        return greetingService.greet(name);
    }
}

Run the app, and the log shows that Tomcat started (on port 8080 by default). The application keeps running, until you stop it with Ctrl+C. Now call it:

curl http://localhost:8080/hello
curl "http://localhost:8080/hello?name=Asha"

Hello, World!
Hello, Asha!

Here's what happened:

   curl  -->  embedded Tomcat  -->  DispatcherServlet  -->  HelloController.hello("Asha")
                                                                   |  (it was given a GreetingService
                                                                   v   by constructor injection)
                                                            GreetingService.greet("Asha")
                                                                   |
   curl  <--  response: "Hello, Asha!"  <-------------------------+

@RestController means "this class handles web requests, and returns the data directly as the response body." (If you return an object instead of a string, Boot converts it to JSON for you.)
@GetMapping("/hello") maps HTTP GET /hello to the method.
@RequestParam reads the name from the URL.
Dependency injection works the same as before: the controller got its GreetingService through its constructor.

Configuration with application.properties

Spring Boot reads settings from src/main/resources/application.properties (or application.yml). Some examples:

server.port=9090
spring.application.name=demo
app.greeting=Welcome

server.port changes the web server's port.
app.greeting is your own setting. Read it into a bean with @Value:

@Service
public class GreetingService {

    private final String greeting;

    public GreetingService(@Value("${app.greeting:Hello}") String greeting) {
        this.greeting = greeting;
    }

    public String greet(String name) {
        return greeting + ", " + name + "!";
    }
}

The :Hello part is a default used if the property isn't set. With app.greeting=Welcome, the endpoint now returns Welcome, Asha!.

A few more useful facts:

Settings can be overridden by environment variables (SERVER_PORT=9090) and by command-line arguments (--server.port=9090). Those are the args we passed to SpringApplication.run. Command-line arguments win over the properties file.
Profiles let you keep different settings per environment. Put them in application-dev.properties and turn them on with spring.profiles.active=dev.
For groups of related settings, look at @ConfigurationProperties, which binds them to a Java class.
Don't put real passwords in the file. Use environment variables or a secrets manager.

Running, packaging and testing

Run during development:

./mvnw spring-boot:run

Package a runnable JAR:

./mvnw clean package
java -jar target/demo-0.0.1-SNAPSHOT.jar

In the Maven post, a plain JAR failed with "no main manifest attribute." A Spring Boot JAR works, because the Boot Maven plugin turns it into an executable "fat JAR": it contains your classes, all the libraries, the embedded server and the information about the main class. You can override settings at launch, like java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port=9090.

Check the application's health. Add the spring-boot-starter-actuator dependency, and http://localhost:8080/actuator/health returns {"status":"UP"}.

Test it. @SpringBootTest starts the whole container for a test, and you can inject beans straight into the test class:

@SpringBootTest
class DemoApplicationTests {

    @Autowired
    private Dev dev;

    @Test
    void devBeanIsCreated() {
        assertNotNull(dev);
    }
}

Field injection is perfectly fine in test classes. For testing just the web layer, there are focused test annotations like @WebMvcTest. The test starter brings in JUnit, so everything in my JUnit post applies here.

Best practices

Use constructor injection for required dependencies, with final fields.
Never create beans with new. Let the container do it, otherwise injection and the lifecycle are skipped.
Depend on interfaces (Computer), not concrete classes, so implementations can be swapped.
Keep beans stateless. Singletons are shared between threads.
Keep the layers clean: controller, service, repository. Put business logic in services.
Put the main class in the root package, so component scanning finds everything below it.
Use @Qualifier with meaningful names, and use @Primary sparingly for the one obvious default.
Use the specific stereotypes (@Service, @Repository, @RestController) instead of plain @Component everywhere.
Externalize configuration in application.properties, profiles and environment variables, and keep secrets out of code.
Avoid circular dependencies. Redesign instead of fighting the container.
Use getBean only in main and tests. In application code, use injection.
Let the Boot parent or BOM manage versions, and don't override library versions unless you must.
Read the startup error. Spring Boot's failure messages usually tell you exactly what to fix.

Which one should I use?

Spring Framework alone or Spring Boot? Spring Boot for almost every new project. Plain Spring for learning the core, and for older applications that already use it.
XML, annotations or Java configuration? Annotations (@Component) for your own classes, @Bean methods for classes you don't own, and XML only in legacy code.
Constructor, setter or field injection? Constructor by default, setter for optional dependencies, and field injection only in tests or quick demos.
@Primary or @Qualifier? @Primary for a clear default, @Qualifier when a specific place needs a specific bean.
@Component or @Bean? @Component on your classes. @Bean for library classes or special setup.
BeanFactory or ApplicationContext? ApplicationContext, always.
Spring MVC or WebFlux? Spring MVC (spring-boot-starter-webmvc) for most applications. WebFlux for reactive, non-blocking designs.
Singleton or prototype? Singleton (the default) for stateless beans. Prototype when each user of the bean needs its own instance.
getBean or injection? Injection in application code. getBean only where you have no other way in, like main.
.properties or .yml? Either. YAML is neater for nested settings, and properties are simpler. Use the one your team prefers.

Common mistakes

Creating beans with new. If you write new Dev() yourself, Spring doesn't know about that object, so its @Autowired fields stay null and you get a NullPointerException. Ask the container for it, or inject it.
Missing @Component, or a class outside the scan. The error says "required a bean of type ... that could not be found." Check the annotation, and check that the class is in the main class's package or one of its sub-packages.
Two beans of the same type. You get "required a single bean, but 2 were found." Use @Primary or @Qualifier, or inject a List.
Forgetting @Autowired on a setter or field. Spring doesn't complain, and the dependency stays null. (Constructor injection with a single constructor doesn't need it.)
Keeping state in singleton beans. A singleton is shared by every request and thread. Fields that change per user lead to confusing bugs. Keep beans stateless.
XML slips. ByType instead of byType, a wrong class name, a <property name="comp"> with no setComp method, a missing no-argument constructor, or a bean id that doesn't match the property name when using byName.

Quick recap

Creating objects with new ties classes together. Dependency injection gives an object its dependencies from outside, and Spring automates the wiring.
IoC is the principle: the container, not your code, controls object creation. DI is the technique (the container gives objects what they need). getBean is the other form, called dependency lookup.
The Spring container (ApplicationContext) creates beans, injects their dependencies and manages their lifecycle: instantiate, inject, @PostConstruct, ready, @PreDestroy.
XML configuration: <beans> is the root, <bean id class> defines an object, <property> is setter injection, <constructor-arg> is constructor injection, autowire="byName" or "byType" lets Spring find dependencies, and primary="true" resolves conflicts. You load it with ClassPathXmlApplicationContext("spring.xml").
Annotations: @Component (and @Service, @Repository, @RestController) create beans, @Configuration with @Bean handles special cases, and @Primary and @Qualifier resolve ambiguity.
Three kinds of DI: constructor (no @Autowired needed for a single constructor, and the best choice), setter (needs @Autowired) and field (needs @Autowired, and is discouraged).
Spring Boot is Spring with the setup done for you: starters, auto-configuration, an embedded server and an executable JAR. It creates the objects you need.
Spring is the foundation, Spring Web (Spring MVC) is its web module, and Spring Boot is the layer that sets it all up.
SpringApplication.run(DemoApplication.class, args) creates the container, scans, auto-configures, creates the beans and starts the server. It returns the ApplicationContext, and getBean(Dev.class) fetches a bean from it.
A Boot application is layered: controller, service, repository, each one injected into the layer above.

Try it yourself

Here's a small practice idea: build the Dev, Computer, Laptop and Desktop example twice. First use plain Spring with spring.xml: wire it with <property>, then with <constructor-arg>, then with autowire="byType", and make the two-bean error happen on purpose before fixing it with primary="true" and again with byName. Then rebuild the same thing in Spring Boot with @Component, and break it with a second Computer bean before fixing it with @Primary and @Qualifier.

For a bonus experiment, add @PostConstruct and @PreDestroy messages to a bean and watch the order. Then add Spring Web, write a /hello endpoint that uses a service with constructor injection, change the port with --server.port=9090, and package everything into a JAR you can start with java -jar.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Why ORMs Exist: The Object-Relational Mismatch

Mayur Bodhare — Mon, 26 Oct 2026 09:13:48 +0000

After learning JDBC, I was proud of myself. I could connect to a database, run queries and read the results. Then I built a real project with 12 tables, and my code filled up with the same pattern again and again: open a connection, prepare a statement, set five parameters, run it, loop over a ResultSet, copy each column into an object, close everything. Changing one column name meant hunting through dozens of SQL strings.

That's the problem ORM tools were invented to solve, and Hibernate is the most famous one in Java. You describe how your classes map to tables once, and Hibernate writes and runs the SQL for you.

In this post, we'll learn what ORM is and which problem it solves, its pros and cons, what Hibernate is and how it works, how to use it with and without Maven (using PostgreSQL), the common methods you'll use, how Hibernate relates to Jakarta Persistence (JPA), and a step-by-step example in the Spring Framework. I've also added things beginners usually miss: the entity lifecycle, lazy loading, the N+1 problem, caching and versioning.

A version note: I wrote this for Hibernate ORM 7.4 and Spring Framework 7.0. Both need Java 17 or newer. If you work on an older project (Hibernate 5 or 6), the section on older Hibernate methods tells you what changed.

What is an ORM?
- The problem: objects and tables do not match
- How an ORM solves it
- The same job, with and without an ORM
- Popular ORM tools
Pros and cons of ORMs
- Advantages
- Disadvantages
What is Hibernate?
- How Hibernate fits in
- The core pieces: SessionFactory, Session and Transaction
- The life of an entity
Setting up PostgreSQL for the examples
The common code: entity and main class
- The entity class
- The main class
Using Hibernate without Maven
- Step by step without Maven
Using Hibernate with Maven
- Step by step with Maven
Common Hibernate methods
- Saving, reading, updating and deleting
- Queries with HQL
- Managing the persistence context
- Transactions and the safe pattern
- Methods from older Hibernate versions
Mapping relationships and loading data
- One-to-many and many-to-one
- Lazy loading and the N+1 problem
Hibernate vs Jakarta Persistence
- What each one is
- The same code in both styles
- Which one to code against
Hibernate in the Spring Framework
- Step 1: Add the dependencies
- Step 2: Create the entity
- Step 3: Create the repository
- Step 4: Create the service
- Step 5: Configure Spring
- Step 6: Run the application
- How Spring and Hibernate work together
- The shortcut: Spring Boot and Spring Data JPA
Other things worth knowing
- Configuration settings
- Caching
- Optimistic locking with @Version
- Managing the schema in real projects
- Logging the SQL
Best practices
Which one should I use?
Common mistakes
Quick recap
Try it yourself

What is an ORM?

ORM stands for Object-Relational Mapping. It's a technique (and a kind of tool) that connects the two worlds a Java developer lives in: objects in your code and tables in a relational database. A class maps to a table, an object maps to a row, and a field maps to a column. Instead of writing SQL for every operation, you work with objects, and the ORM does the translating.

The problem: objects and tables do not match

With plain JDBC, you do all the translating by hand. Every query repeats the same steps, and your SQL strings are scattered through the code. That's tiring, but it's not the deepest problem.

The deeper problem is that objects and tables are built on different ideas. This gap has a name: the object-relational impedance mismatch.

   OBJECT WORLD (Java)                        RELATIONAL WORLD (database)
   classes, objects, fields                   tables, rows, columns
   references between objects                 foreign keys and joins
   inheritance (Dog extends Animal)           no inheritance (flat tables)
   identity with == and equals()              identity with a primary key
   walk the graph: s.getCourse().getTitle()   write a JOIN in SQL
   collections: List<Student>                 a separate table with a foreign key

Here's what that means in practice:

Inheritance: Java has it, tables don't. How do you store Dog and Cat, which both extend Animal?
Identity: two Java objects can hold the same data but be different objects. In a database, a row is identified by its primary key.
Associations: in Java, a Student holds a reference to a Course. In a database, the student table holds a foreign key column.
Navigation: in Java you walk from object to object. In SQL, you join tables.

Writing the code that bridges all this by hand, for every class, is slow and full of bugs.

How an ORM solves it

An ORM does the bridging for you. You describe the mapping once, usually with annotations on your classes. Then the ORM:

generates the SQL for creating, reading, updating and deleting objects,
turns query results back into objects,
handles relationships between objects,
tracks which objects changed and saves only those changes,
manages transactions and caching,
adapts the SQL to each database's dialect.

   Java object                                   table row
   Student(id=1, name="Asha", marks=88)          student: id=1 | name='Asha' | marks=88
        |                                              ^
        |  session.persist(student)                    |
        +--- the ORM writes the SQL for you -----------+   insert into student ...

The same job, with and without an ORM

Saving and loading one student with plain JDBC:

String insert = "INSERT INTO student (name, marks) VALUES (?, ?)";
try (Connection conn = dataSource.getConnection();
     PreparedStatement ps = conn.prepareStatement(insert)) {
    ps.setString(1, student.getName());
    ps.setInt(2, student.getMarks());
    ps.executeUpdate();
}

String select = "SELECT id, name, marks FROM student WHERE id = ?";
Student found = null;
try (Connection conn = dataSource.getConnection();
     PreparedStatement ps = conn.prepareStatement(select)) {
    ps.setLong(1, id);
    try (ResultSet rs = ps.executeQuery()) {
        if (rs.next()) {
            found = new Student(rs.getLong("id"), rs.getString("name"), rs.getInt("marks"));
        }
    }
}

The same two jobs with Hibernate:

session.persist(student);                           // INSERT
Student found = session.find(Student.class, id);    // SELECT ... WHERE id = ?

Two lines instead of twenty, and no column names to copy by hand.

Popular ORM tools

In Java:

Hibernate ORM: the most widely used ORM, and the main topic of this post.
EclipseLink: another full ORM, and the reference implementation of the JPA standard.
Spring Data JPA: not an ORM itself, but a layer on top of JPA (usually Hibernate) that writes repository code for you.

Related tools that are not full ORMs: MyBatis (you write the SQL, it maps results to objects), jOOQ (a type-safe way to write SQL in Java) and Spring's JdbcTemplate (less boilerplate for JDBC).

Other languages have their own: Entity Framework (.NET), SQLAlchemy and the Django ORM (Python), ActiveRecord (Ruby), Prisma and TypeORM (JavaScript and TypeScript).

Pros and cons of ORMs

Advantages

Much less boilerplate. No more connection, statement and result set code for every query.
You think in objects. Your code stays object-oriented, and SQL is mostly hidden.
Relationships are handled for you. You walk from a Student to a Course as if they were ordinary objects.
Portability. The ORM generates SQL for the database you use, so switching databases is often a configuration change.
Built-in features: change tracking (only modified rows are updated), caching, lazy loading, optimistic locking and schema generation.
Safer by default. Values are sent as parameters, which protects you from SQL injection.
One place for mapping. Table and column names live in your entity classes, not in dozens of SQL strings.
A standard. Code written against JPA works with several ORM providers.

Disadvantages

A learning curve. Sessions, entity states, fetching strategies and flushing are real concepts to learn.
Hidden SQL. You don't see the queries, so you can create slow ones without noticing. The famous example is the N+1 problem (covered later).
Leaky abstraction. You still need to understand SQL, indexes and transactions to tune performance.
Not ideal for everything. Bulk updates, complex reports and heavy analytics are often better in plain SQL.
Memory and startup cost. The ORM tracks your objects and builds its mapping metadata when the app starts.
"Magic" that surprises. For example, changing a field on a managed object can cause an UPDATE without any save call.
Overkill for tiny apps. For a few simple queries, JDBC (or JdbcTemplate) may be enough.
Schema changes need care. Letting the ORM modify a production schema automatically is risky.

The honest summary: an ORM saves a lot of work, but it doesn't remove the need to understand databases.

What is Hibernate?

Hibernate ORM is an open-source ORM framework for Java. Gavin King started it in 2001, and it became the most popular persistence tool in the Java world. Its ideas strongly influenced the JPA standard (more on that later), and today Hibernate is the most widely used JPA implementation. It also adds many extra features of its own.

Some current facts:

Its Maven groupId is org.hibernate.orm, and the main artifact is hibernate-core.
Hibernate 7 needs Java 17+ and implements Jakarta Persistence 3.2.
At the time of writing, the latest stable series is 7.4 (7.4.13.Final), and Hibernate 8.0 (aimed at Jakarta Persistence 4.0) is still in development.
Since version 7.0, it uses the Apache License 2.0.

How Hibernate fits in

Hibernate doesn't replace JDBC. It sits on top of it. Everything you learned about JDBC still happens underneath:

   YOUR APPLICATION   (entity classes + Hibernate or JPA API)
          |
          v
   HIBERNATE ORM
     - reads your mapping (annotations on the entities)
     - turns your calls and HQL queries into SQL for your database (the "dialect")
     - tracks changes, caches objects, manages relationships
          |
          v
   JDBC   (Connection, PreparedStatement, ResultSet ...)
          |
          v
   JDBC DRIVER (the postgresql jar)   -->   PostgreSQL

Every query Hibernate runs becomes a PreparedStatement, so values are always sent safely as parameters. Hibernate also finds out which database you're using from the connection and picks the right dialect on its own, so you usually don't configure one.

The core pieces: SessionFactory, Session and Transaction

Three objects do most of the work:

   SessionFactory
     one per database, created ONCE when the app starts
     expensive to create, thread-safe, shared by everyone
          |
          |  openSession()
          v
   Session   (also an EntityManager)
     one per unit of work (for example, one web request)
     cheap, NOT thread-safe, wraps one JDBC connection
     holds the persistence context: a cache of the objects it is tracking
          |
          |  beginTransaction()
          v
   Transaction  -->  commit() or rollback()

SessionFactory: built once from your configuration and mapping. Think of it as the "factory" that makes sessions.
Session: your working conversation with the database. You open it, do some work and close it.
Transaction: groups the work so it succeeds or fails as a unit (the same idea as in the JDBC post).
Persistence context: the "first-level cache" inside every session. Hibernate remembers every object it loaded or saved, and watches it for changes.

The life of an entity

An entity is a Java object that Hibernate manages (one that maps to a table). At any moment, an entity is in one of four states:

        new Student("Asha", 88)
                 |
            TRANSIENT       a plain object; Hibernate doesn't know it; no row exists
                 |
                 |  persist()
                 v
   find() / query results -->  PERSISTENT   (also called managed)
                 |             tracked in the persistence context; changes are saved automatically
                 |                  |
   session closes, detach(),        |  remove()
   or clear()                       v
                 |             REMOVED    (the row is deleted when the work is flushed)
                 v
            DETACHED        has an id and a row exists, but no session is tracking it
                 |
                 |  merge()  -->  returns a PERSISTENT copy

Three ideas follow from this picture:

Dirty checking. For a persistent entity, Hibernate remembers its original values. At commit time, it compares them with the current values and sends an UPDATE only if something changed. You don't call "save" to update a managed object.
Flush. The moment Hibernate sends the pending SQL to the database is called a flush. It happens automatically before a query that might be affected and at commit.
Identity guarantee. Inside one session, asking for the same row twice gives you the same object.

Setting up PostgreSQL for the examples

All examples use PostgreSQL. The quickest way to get one is Docker:

docker run --name school-db -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=school -p 5432:5432 -d postgres:17

This starts a PostgreSQL server on port 5432 with a database called school, the user postgres and the password secret. (That password is only for local practice. Use a strong one and read it from an environment variable in real projects.)

If you don't use Docker, install PostgreSQL from postgresql.org, then create the database:

psql -U postgres -c "CREATE DATABASE school;"

Our connection details for the rest of the post:

URL: jdbc:postgresql://localhost:5432/school
User: postgres
Password: secret

The common code: entity and main class

The Java code is the same whether you use Maven or not. Only the way you get the libraries differs.

The entity class

package com.example;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Entity
@Table(name = "student")
public class Student {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 50)
    private String name;

    private int marks;

    protected Student() {
        // required by Hibernate
    }

    public Student(String name, int marks) {
        this.name = name;
        this.marks = marks;
    }

    public Long getId()      { return id; }
    public String getName()  { return name; }
    public int getMarks()    { return marks; }

    public void setMarks(int marks) {
        this.marks = marks;
    }

    @Override
    public String toString() {
        return "Student{id=" + id + ", name='" + name + "', marks=" + marks + "}";
    }
}

What each annotation does:

@Entity: this class is mapped to a table.
@Table(name = "student"): the table name. (Without it, Hibernate uses the class name.)
@Id: the primary key field.
@GeneratedValue(strategy = IDENTITY): the database generates the id (an auto-increment column). Another common strategy is SEQUENCE, which suits batching better.
@Column(nullable = false, length = 50): column settings. A field with no annotation (like marks) is mapped by default, to a column with the same name.

Rules for an entity class:

It needs an @Id field.
It needs a no-argument constructor (it can be protected, so your own code can't misuse it).
It must not be final, because Hibernate creates subclasses (proxies) of entities.
Use jakarta.persistence.* imports. The old javax.persistence is from Hibernate 5 and earlier.

With hbm2ddl.auto set to update (we'll set it below), Hibernate creates a table similar to this one:

create table student (
    id bigint generated by default as identity,
    marks integer not null,
    name varchar(50) not null,
    primary key (id)
)

The main class

This program creates a student, reads it, updates it, queries and deletes it, using the classic Session and Transaction style:

package com.example;

import java.util.List;

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.jpa.HibernatePersistenceConfiguration;

public class Main {

    public static void main(String[] args) {
        try (SessionFactory sessionFactory = buildSessionFactory()) {

            Long id = createStudent(sessionFactory, "Asha", 88);
            System.out.println("Saved with id " + id);

            System.out.println("Found: " + findStudent(sessionFactory, id));

            updateMarks(sessionFactory, id, 95);
            System.out.println("After update: " + findStudent(sessionFactory, id));

            System.out.println("Top students: " + findTopStudents(sessionFactory, 90));

            deleteStudent(sessionFactory, id);
            System.out.println("Deleted student " + id);
        }
    }

    private static SessionFactory buildSessionFactory() {
        return new HibernatePersistenceConfiguration("school")
                .managedClass(Student.class)
                .jdbcUrl("jdbc:postgresql://localhost:5432/school")
                .jdbcCredentials("postgres", "secret")
                .property("hibernate.hbm2ddl.auto", "update")
                .createEntityManagerFactory();
    }

    private static Long createStudent(SessionFactory sf, String name, int marks) {
        try (Session session = sf.openSession()) {
            Transaction tx = session.beginTransaction();
            Student student = new Student(name, marks);
            session.persist(student);                  // INSERT
            tx.commit();
            return student.getId();
        }
    }

    private static Student findStudent(SessionFactory sf, Long id) {
        try (Session session = sf.openSession()) {
            return session.find(Student.class, id);   // SELECT by primary key
        }
    }

    private static void updateMarks(SessionFactory sf, Long id, int newMarks) {
        try (Session session = sf.openSession()) {
            Transaction tx = session.beginTransaction();
            Student student = session.find(Student.class, id);
            student.setMarks(newMarks);                // no "update" call: dirty checking
            tx.commit();                               // the UPDATE is sent here
        }
    }

    private static List<Student> findTopStudents(SessionFactory sf, int minMarks) {
        try (Session session = sf.openSession()) {
            return session.createQuery(
                            "from Student s where s.marks >= :min order by s.marks desc",
                            Student.class)
                    .setParameter("min", minMarks)
                    .getResultList();
        }
    }

    private static void deleteStudent(SessionFactory sf, Long id) {
        try (Session session = sf.openSession()) {
            Transaction tx = session.beginTransaction();
            Student student = session.find(Student.class, id);
            session.remove(student);                   // DELETE
            tx.commit();
        }
    }
}

Output (the id may be different on your machine, and Hibernate also prints a few start-up log lines, which are normal):

Saved with id 1
Found: Student{id=1, name='Asha', marks=88}
After update: Student{id=1, name='Asha', marks=95}
Top students: [Student{id=1, name='Asha', marks=95}]
Deleted student 1

Let's go through the new parts:

HibernatePersistenceConfiguration is the modern way (Hibernate 7 and Jakarta Persistence 3.2) to configure Hibernate in plain Java code, with no XML file. You give it a name, the entity classes (managedClass), the JDBC URL, the credentials and any extra property.
hibernate.hbm2ddl.auto = update tells Hibernate to create or update tables to match your entities. It's handy for learning, but not for production (see the schema section later).
createEntityManagerFactory() builds and returns the SessionFactory. We use try-with-resources so it's closed when the program ends.
openSession() gives us a Session for one unit of work. Each method opens its own and closes it automatically.
persist, find, remove are the basic operations, and the update works through dirty checking: we changed a field of a managed object, and Hibernate wrote the UPDATE at commit().
The HQL query (from Student s where ...) is written against the entity and its fields (Student, s.marks), not the table and column names. The :min is a named parameter, bound safely.

Using Hibernate without Maven

"Without Maven" means you manage the library files yourself. You put the jars in a folder and tell Java where they are.

Step by step without Maven

1. Install the tools. You need a JDK 17 or newer, and PostgreSQL running with the school database (see the setup section).

2. Create the project folders.

   hibernate-demo/
   |-- lib/                       <- all the jar files go here
   |-- src/
   |    +-- com/example/
   |         |-- Student.java
   |         +-- Main.java
   +-- out/                      <- compiled classes will go here

3. Get the jars into lib/. This is the hard part. hibernate-core alone isn't enough. It needs a set of other libraries (for example the Jakarta Persistence API, a logging library, a bytecode library, a parser library and a few more), and those may need others. You have two ways:

Option A, fully by hand: go to Maven Central, download hibernate-core-7.4.13.Final.jar, open its .pom file to read the dependency list, download each one, and repeat for those too. Then download the PostgreSQL driver postgresql-42.7.13.jar. Expect roughly 15 to 25 jars, and the exact list changes between versions.
Option B, use Maven only as a downloader: create a small file called fetch-pom.xml in the project folder:

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>tmp</groupId>
  <artifactId>fetch-jars</artifactId>
  <version>1</version>
  <dependencies>
    <dependency>
      <groupId>org.hibernate.orm</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>7.4.13.Final</version>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>42.7.13</version>
    </dependency>
  </dependencies>
</project>

Then run this once. It copies every needed jar, including the transitive ones, into lib/:

mvn -f fetch-pom.xml dependency:copy-dependencies -DoutputDirectory=lib

After that, you can forget Maven and build with plain Java tools.

4. Add the code. Put the Student and Main classes from the previous section into src/com/example/.

5. Compile. The "lib/*" part adds every jar in the folder to the classpath:

mkdir -p out
javac -cp "lib/*" -d out src/com/example/*.java

6. Run. Linux and macOS use : to separate classpath entries, and Windows uses ;:

java -cp "out:lib/*" com.example.Main      # Linux and macOS
java -cp "out;lib/*" com.example.Main      # Windows

7. Check the result. You'll see the output from the main class section. You can also look in the database:

docker exec -it school-db psql -U postgres -d school -c "\dt"

 Schema |  Name   | Type  |  Owner
--------+---------+-------+----------
 public | student | table | postgres

What this approach costs you:

You track every jar and version by hand. Upgrading Hibernate means repeating step 3.
Two libraries needing different versions of a third is your problem to solve.
Every teammate must set up the same lib/ folder.

If you prefer an XML or properties file for configuration, Hibernate still supports hibernate.properties and hibernate.cfg.xml (read by calling new Configuration().configure()). The code-based approach above just avoids an extra file.

This is exactly why build tools exist, as we saw in the Maven post.

Using Hibernate with Maven

With Maven, you list the two libraries you need, and Maven fetches everything else.

Step by step with Maven

1. Create the project. (If you read my Maven post, this is the same command.)

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=hibernate-demo \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DinteractiveMode=false

You can delete the generated App.java and the sample test, since we won't use them.

2. Edit pom.xml. Set the Java version and add the two dependencies:

<properties>
  <maven.compiler.release>17</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.13.Final</version>
  </dependency>
  <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.13</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

hibernate-core also brings the Jakarta Persistence API with it, so the jakarta.persistence.* imports compile.
The PostgreSQL driver uses runtime scope, because your code never uses the driver's classes directly, only the standard JDBC and Hibernate APIs.
Use the newest versions you can find on Maven Central. These are the ones I used.

3. Add the code. Put Student.java and Main.java in src/main/java/com/example/.

4. Run it. The exec plugin runs your main class:

mvn compile exec:java -Dexec.mainClass=com.example.Main

5. Check the output. You'll see the same five lines as before, mixed in with Maven's own messages.

To see everything Maven brought in for you, run:

mvn dependency:tree

You'll see hibernate-core with its whole list of transitive libraries underneath. That's the list you had to download by hand in the other approach.

Common Hibernate methods

In Hibernate 7, Session extends the standard JPA EntityManager, so most of the methods have JPA names. Here are the ones you'll use most:

   METHOD                          WHAT IT DOES
   persist(entity)                 insert a NEW entity (it becomes managed)
   find(Class, id)                 load by primary key (null if it doesn't exist)
   getReference(Class, id)         a lazy proxy, no SQL until you use it
   merge(entity)                   copy a DETACHED entity's state into a managed one, returns it
   remove(entity)                  delete an entity
   refresh(entity)                 reload its state from the database
   detach(entity)                  stop tracking this entity
   contains(entity)                is this entity managed by the session?
   flush()                         send pending SQL to the database now
   clear()                         detach everything the session tracks
   createQuery(hql, Class)         run an HQL / JPQL query
   createNativeQuery(sql, Class)   run plain SQL
   beginTransaction()              start a transaction
   close()                         close the session

Saving, reading, updating and deleting

// inside an open session, within a transaction
session.persist(new Student("Ravi", 72));            // INSERT

Student s = session.find(Student.class, 1L);         // SELECT ... WHERE id = ?
s.setMarks(80);                                      // UPDATE happens at commit (dirty checking)

session.remove(s);                                   // DELETE happens at commit

find vs getReference:

Student a = session.find(Student.class, 999L);          // runs a SELECT, returns null if missing
Student b = session.getReference(Student.class, 1L);    // returns a proxy, no SQL yet

System.out.println(a);

null

getReference only runs SQL when you actually use the object (for example b.getName()), and if the row doesn't exist, you get an exception at that point. It's useful when you only need a reference, such as setting a foreign key.

persist vs merge is a common source of confusion:

persist is for new (transient) entities. After the call, the same object you passed is managed.
merge is for detached entities (ones that came from an earlier, closed session). It copies the state into a managed instance and returns that instance. The object you passed in stays detached, so always use the returned one.

Student detached = findStudent(sessionFactory, 1L);   // its session is closed: detached
detached.setMarks(70);                                // changed outside any session

try (Session session = sessionFactory.openSession()) {
    Transaction tx = session.beginTransaction();
    Student managed = session.merge(detached);        // use "managed" from here on
    tx.commit();                                      // the UPDATE is sent
}

Queries with HQL

HQL (Hibernate Query Language) looks like SQL, but works on entities and their fields, not tables and columns. It's a superset of JPQL, the standard JPA query language.

// filter and sort
List<Student> top = session.createQuery(
        "from Student s where s.marks >= :min order by s.marks desc", Student.class)
    .setParameter("min", 80)
    .getResultList();

// a single value
Long count = session.createQuery("select count(s) from Student s", Long.class)
    .getSingleResult();

// pagination: rows 0 to 9
List<Student> firstPage = session.createQuery("from Student order by id", Student.class)
    .setFirstResult(0)
    .setMaxResults(10)
    .getResultList();

// bulk update (runs directly in the database)
int changed = session.createMutationQuery("update Student set marks = marks + 5 where marks < 40")
    .executeUpdate();

A few points:

Always use named parameters (:min) and setParameter. Never join user input into the query string.
A bulk update goes straight to the database and skips the persistence context, so objects already loaded in the session don't see the change.
For plain SQL, use createNativeQuery:

List<Student> result = session.createNativeQuery(
        "select * from student where marks > ?1", Student.class)
    .setParameter(1, 80)
    .getResultList();

There's also the Criteria API, which builds queries with Java objects instead of strings. It's more verbose, but checked by the compiler.

Managing the persistence context

Remember that each session keeps a cache of the objects it loaded. This means asking for the same row twice gives you the same object, with only one SQL query:

Student s1 = session.find(Student.class, id);
Student s2 = session.find(Student.class, id);

System.out.println(s1 == s2);

true

The tools to control this cache:

flush() sends pending changes to the database immediately (they're still inside the transaction and can be rolled back).
clear() and detach(entity) stop tracking objects. Useful in long loops, so the session doesn't grow too large.
refresh(entity) reloads the object from the database, discarding unflushed changes.
contains(entity) tells you whether an object is managed.

Transactions and the safe pattern

All changes to the database must happen inside a transaction. Use this pattern, so a failure rolls everything back and the session is always closed:

Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
try {
    session.persist(new Student("Meera", 95));
    tx.commit();
} catch (RuntimeException e) {
    tx.rollback();
    throw e;
} finally {
    session.close();
}

Jakarta Persistence 3.2 also added shortcuts to the factory that do all of this for you (begin, commit, rollback on failure and close):

sessionFactory.runInTransaction(em -> {
    em.persist(new Student("Ravi", 72));
});

Long count = sessionFactory.callInTransaction(em ->
        em.createQuery("select count(s) from Student s", Long.class).getSingleResult());

runInTransaction runs code that returns nothing, and callInTransaction returns a value. If you use Spring, @Transactional does the same job (we'll see it soon).

Methods from older Hibernate versions

Many tutorials online use older methods. Hibernate 7 removed a number of them, so such code won't compile. Here's the mapping:

   OLD (Hibernate 5 and 6)             NEW (Hibernate 7)
   session.save(x)                     session.persist(x)
   session.update(x)                   x = session.merge(x)
   session.saveOrUpdate(x)             persist() for a new entity, merge() for a detached one
   session.delete(x)                   session.remove(x)
   session.load(Class, id)             session.getReference(Class, id)
   session.get(Class, id)              session.find(Class, id)       (get is deprecated)
   CascadeType.SAVE_UPDATE             CascadeType.PERSIST and CascadeType.MERGE
   javax.persistence.*                 jakarta.persistence.*          (since Hibernate 6)
   org.hibernate:hibernate-core        org.hibernate.orm:hibernate-core   (groupId changed in 6)

If you maintain old code, Hibernate 6.x still has most of the old methods marked as deprecated, which gives you time to migrate.

Mapping relationships and loading data

One-to-many and many-to-one

Real data has relationships. Let's say many students belong to one course:

   course                     student
   +----+----------+         +----+-------+-------+-----------+
   | id | title    |         | id | name  | marks | course_id |  <- foreign key
   +----+----------+         +----+-------+-------+-----------+
   | 1  | Java 101 |<--------| 1  | Asha  | 88    | 1         |
   +----+----------+<--------| 2  | Ravi  | 72    | 1         |
                             +----+-------+-------+-----------+

In Java, you map both sides:

@Entity
public class Course {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;

    @OneToMany(mappedBy = "course", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Student> students = new ArrayList<>();

    public void addStudent(Student student) {
        students.add(student);
        student.setCourse(this);       // keep both sides in sync
    }
}

And in Student, add:

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "course_id")
private Course course;

How to read this:

@ManyToOne (in Student) is the owning side: it has the foreign key column course_id.
@OneToMany(mappedBy = "course") (in Course) is the inverse side. mappedBy says "the foreign key is managed by the course field over there."
cascade = ALL passes operations like persist and remove from a course to its students.
orphanRemoval = true deletes a student that you remove from the list.
Always update both sides of the relationship, as addStudent does.

There are also @OneToOne and @ManyToMany (which uses a join table).

Lazy loading and the N+1 problem

When you load a Course, should Hibernate also load all its students right away? That choice is the fetch type:

LAZY: load the related data only when you first use it.
EAGER: load it immediately with the main object.

The defaults are: @OneToMany and @ManyToMany are lazy, while @ManyToOne and @OneToOne are eager. A good habit is to make everything LAZY explicitly and fetch what you need on purpose.

Laziness is powerful, but it has two classic traps.

Trap 1: LazyInitializationException. A lazy collection can only be loaded while its session is open:

Course course;
try (Session session = sessionFactory.openSession()) {
    course = session.find(Course.class, 1L);
}                                                  // session closed

course.getStudents().size();                       // LazyInitializationException

Trap 2: the N+1 problem. Suppose you list every course with its number of students:

List<Course> courses = session.createQuery("from Course", Course.class).getResultList();  // 1 query

for (Course course : courses) {
    System.out.println(course.getTitle() + ": " + course.getStudents().size());          // +1 query EACH
}

   1 query to load the courses
   + 1 query for the students of course 1
   + 1 query for the students of course 2
   + ...
   = N + 1 queries      (100 courses means 101 queries!)

The code looks innocent, but it hits the database a hundred times. The most common fix is to tell Hibernate to load them together with a join fetch:

List<Course> courses = session.createQuery(
        "from Course c left join fetch c.students", Course.class).getResultList();   // 1 query

Other fixes include @BatchSize (load collections in groups) and entity graphs. Since Hibernate 6, duplicate root entities caused by the join are removed for you. Watching the SQL log (covered later) is the best way to catch N+1 early.

Hibernate vs Jakarta Persistence

What each one is

This confuses almost everyone at first, so here's the key: Jakarta Persistence is a specification (a standard). Hibernate is an implementation of it.

JPA (Java Persistence API, now called Jakarta Persistence) defines the interfaces and annotations: EntityManager, EntityManagerFactory, @Entity, @Id, JPQL and the rules for how they behave. It contains no real working code for talking to a database.
Hibernate provides the working code behind those interfaces, plus many extra features of its own.

It's like the relationship between JDBC and a driver: the standard is the contract, and the library does the work. The names changed over time: JPA started in 2006 as part of Java EE, and when Java EE moved to the Eclipse Foundation it became Jakarta EE. That's why the packages changed from javax.persistence to jakarta.persistence. Hibernate 7 implements version 3.2.

   YOUR CODE  (uses the standard JPA API: EntityManager, @Entity ...)
        |
        v
   JAKARTA PERSISTENCE   (the specification: interfaces and annotations)
        |   implemented by a "persistence provider":
        |
        +-- Hibernate ORM      (the most popular)
        +-- EclipseLink        (the reference implementation)
        +-- others (OpenJPA, DataNucleus ...)
        |
        v
      JDBC  -->  database

Hibernate's classes extend the standard ones, so you can use both in the same program:

   JAKARTA PERSISTENCE (standard)        HIBERNATE (adds more)
   EntityManagerFactory                  SessionFactory      (extends it)
   EntityManager                         Session             (extends it)
   EntityTransaction                     Transaction         (extends it)
   JPQL                                  HQL                 (a superset of JPQL)
   persistence.xml                       hibernate.properties / hibernate.cfg.xml / code
   @Entity, @Id, @Column ...             plus @NaturalId, @BatchSize, @Formula, @SoftDelete ...

Some things you get only with Hibernate: StatelessSession (no persistence context, great for bulk work), @NaturalId, @BatchSize, filters, soft-delete support and many performance and mapping options.

The same code in both styles

Saving a student with the standard JPA API:

EntityManager em = entityManagerFactory.createEntityManager();
try {
    em.getTransaction().begin();
    em.persist(new Student("Asha", 88));
    em.getTransaction().commit();
} finally {
    em.close();
}

And with Hibernate's own API:

Session session = sessionFactory.openSession();
try {
    Transaction tx = session.beginTransaction();
    session.persist(new Student("Asha", 88));
    tx.commit();
} finally {
    session.close();
}

They're nearly identical, because Session is an EntityManager. With the standard setup, you create the factory with Persistence.createEntityManagerFactory("school"), which reads a META-INF/persistence.xml file. You can switch from the standard API to Hibernate's features at any time:

Session session = entityManager.unwrap(Session.class);
SessionFactory sessionFactory = entityManagerFactory.unwrap(SessionFactory.class);

Which one to code against

Default to the standard JPA API (EntityManager, JPQL, jakarta.persistence annotations). Your code stays portable, and tools like Spring work with it directly.
Reach for Hibernate-specific features (Session, HQL features, StatelessSession, Hibernate annotations) only when you need what the standard doesn't offer.
In practice, almost everyone runs JPA on Hibernate, so "Hibernate vs JPA" is really "standard API vs extra features."

Hibernate in the Spring Framework

Using Hibernate on its own, you build the SessionFactory, open sessions, begin and commit transactions and close everything. The Spring Framework takes over all of that:

It creates and manages the connection pool and the EntityManagerFactory.
It provides declarative transactions with @Transactional: you don't write begin, commit or rollback.
It injects the EntityManager where you need it.
It can translate JPA and database exceptions into its own consistent exception types.

We'll build a small application with Spring Framework 7 (plain Spring, not Spring Boot), using the standard JPA EntityManager with Hibernate underneath. Spring 7 needs Java 17+, and its HibernateJpaVendorAdapter needs Hibernate ORM 7. (For Spring Framework 6.2, use a Hibernate 6.x version instead.)

Here's the project layout:

   spring-hibernate-demo/
   |-- pom.xml
   +-- src/main/java/com/example/
        |-- Student.java              <- the entity (same as before)
        |-- StudentRepository.java    <- talks to the database through the EntityManager
        |-- StudentService.java       <- business logic; owns the transactions
        |-- AppConfig.java            <- Spring configuration
        +-- App.java                  <- main method

Step 1: Add the dependencies

In pom.xml, import the Spring BOM (so all Spring modules share one version) and add the libraries:

<properties>
  <maven.compiler.release>17</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-framework-bom</artifactId>
      <version>7.0.10</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-orm</artifactId>
  </dependency>
  <dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.13.Final</version>
  </dependency>
  <dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
    <version>7.1.0</version>
  </dependency>
  <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.7.13</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

What each one is for:

spring-context: the core container and annotations.
spring-orm: Spring's JPA and Hibernate integration (it also brings spring-jdbc and spring-tx).
hibernate-core: Hibernate itself.
HikariCP: the connection pool, as we discussed in the JDBC post.
postgresql: the driver.

Use the newest versions available when you read this.

Step 2: Create the entity

Use the same Student class from earlier, in the package com.example. Nothing changes. It's plain JPA, so Spring and Hibernate both understand it.

Step 3: Create the repository

The repository is the class that talks to the database. It uses the standard EntityManager, which Spring injects:

package com.example;

import java.util.List;

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;

import org.springframework.stereotype.Repository;

@Repository
public class StudentRepository {

    @PersistenceContext
    private EntityManager entityManager;

    public void save(Student student) {
        entityManager.persist(student);
    }

    public Student findById(Long id) {
        return entityManager.find(Student.class, id);
    }

    public List<Student> findByMinMarks(int minMarks) {
        return entityManager.createQuery(
                        "from Student s where s.marks >= :min order by s.marks desc",
                        Student.class)
                .setParameter("min", minMarks)
                .getResultList();
    }

    public void delete(Student student) {
        entityManager.remove(student);
    }
}

@Repository marks this class as the data-access layer. Spring registers it as a bean (and, if you add the right post-processor, translates persistence exceptions into Spring's DataAccessException types).
@PersistenceContext asks Spring to inject an EntityManager. Notice there's no code that opens or closes it, and no transaction code. Spring handles those.

Step 4: Create the service

The service holds the business logic, and this is where transactions belong:

package com.example;

import java.util.List;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class StudentService {

    private final StudentRepository repository;

    public StudentService(StudentRepository repository) {
        this.repository = repository;
    }

    @Transactional
    public Long addStudent(String name, int marks) {
        Student student = new Student(name, marks);
        repository.save(student);
        return student.getId();
    }

    @Transactional(readOnly = true)
    public Student getStudent(Long id) {
        return repository.findById(id);
    }

    @Transactional
    public void changeMarks(Long id, int marks) {
        Student student = repository.findById(id);
        student.setMarks(marks);                 // dirty checking: UPDATE at commit
    }

    @Transactional(readOnly = true)
    public List<Student> topStudents(int minMarks) {
        return repository.findByMinMarks(minMarks);
    }

    @Transactional
    public void removeStudent(Long id) {
        repository.delete(repository.findById(id));
    }
}

@Transactional on a method means: "start a transaction before this method, commit when it ends normally, roll back if a runtime exception escapes."
readOnly = true is a hint that this method only reads, which allows some optimizations.
Constructor injection gives us the repository.
Look at changeMarks: it changes a field and never calls "save". Because the student is managed inside the transaction, Hibernate notices the change and writes the UPDATE at commit.

Step 5: Configure Spring

Now we tell Spring how to build the database pieces. We use Java configuration:

package com.example;

import java.util.Properties;

import javax.sql.DataSource;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

import jakarta.persistence.EntityManagerFactory;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.orm.jpa.JpaTransactionManager;
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@Configuration
@ComponentScan("com.example")
@EnableTransactionManagement
public class AppConfig {

    @Bean
    public DataSource dataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/school");
        config.setUsername("postgres");
        config.setPassword(System.getenv().getOrDefault("DB_PASSWORD", "secret"));
        config.setMaximumPoolSize(5);
        return new HikariDataSource(config);
    }

    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(DataSource dataSource) {
        LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
        factory.setDataSource(dataSource);
        factory.setPackagesToScan("com.example");              // find the @Entity classes
        factory.setJpaVendorAdapter(new HibernateJpaVendorAdapter());

        Properties properties = new Properties();
        properties.setProperty("hibernate.hbm2ddl.auto", "update");
        properties.setProperty("hibernate.show_sql", "true");
        factory.setJpaProperties(properties);
        return factory;
    }

    @Bean
    public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
        return new JpaTransactionManager(entityManagerFactory);
    }
}

Piece by piece:

@Configuration marks a class that defines beans. @ComponentScan finds our @Repository and @Service classes. @EnableTransactionManagement turns on @Transactional.
dataSource() builds the HikariCP connection pool. The password comes from an environment variable, with secret as a local fallback.
LocalContainerEntityManagerFactoryBean is Spring's way of building the JPA EntityManagerFactory. setPackagesToScan finds the @Entity classes, so there's no persistence.xml. HibernateJpaVendorAdapter tells Spring that Hibernate is our JPA provider.
jpaProperties passes normal Hibernate settings. Here, update creates the table and show_sql prints the SQL.
JpaTransactionManager is the object that actually starts and commits transactions for @Transactional.

Step 6: Run the application

package com.example;

import org.springframework.context.annotation.AnnotationConfigApplicationContext;

public class App {

    public static void main(String[] args) {
        try (AnnotationConfigApplicationContext context =
                     new AnnotationConfigApplicationContext(AppConfig.class)) {

            StudentService service = context.getBean(StudentService.class);

            Long id = service.addStudent("Asha", 88);
            System.out.println("Saved with id " + id);

            System.out.println("Found: " + service.getStudent(id));

            service.changeMarks(id, 95);
            System.out.println("After update: " + service.getStudent(id));

            System.out.println("Top students: " + service.topStudents(90));

            service.removeStudent(id);
            System.out.println("Deleted. Remaining: " + service.topStudents(0).size());
        }
    }
}

Run it:

mvn compile exec:java -Dexec.mainClass=com.example.App

Output (mixed with the SQL lines that show_sql prints, and some start-up logging):

Saved with id 1
Found: Student{id=1, name='Asha', marks=88}
After update: Student{id=1, name='Asha', marks=95}
Top students: [Student{id=1, name='Asha', marks=95}]
Deleted. Remaining: 0

If you see a message about SLF4J finding no logging provider, that's harmless. Add an SLF4J binding (such as slf4j-simple) if you want to see the pool's logs.

Notice what's missing compared to the plain Hibernate program: no SessionFactory code, no openSession, no beginTransaction, no commit, no try/finally. Spring did all of it.

How Spring and Hibernate work together

The magic is a proxy. When you call a @Transactional method, you don't call the real object directly. You call a proxy that Spring wraps around it:

   App code calls:  service.changeMarks(1, 95)
        |
        v
   SPRING PROXY around StudentService
     1. JpaTransactionManager starts a transaction
        (opens an EntityManager and ties it to the current thread)
        |
        v
   StudentService.changeMarks(...)  -->  StudentRepository  -->  the injected EntityManager
        |                                    (it's a shared proxy that forwards to
        |                                     the EntityManager of the current transaction)
        v
   SPRING PROXY again
     2. method finished normally?   YES: commit  (Hibernate flushes: UPDATE student ...)
                                    NO, a RuntimeException:  rollback

A few rules worth remembering:

By default, Spring rolls back only for unchecked exceptions (RuntimeException and errors). A checked exception does not roll back, unless you add @Transactional(rollbackFor = Exception.class).
Calling a @Transactional method from another method in the same class skips the proxy, so no transaction starts. Call it from another bean instead.
Put @Transactional on public methods of your service layer, not on private methods or in the repository.
Entities you return from a service are detached after the method ends, so lazy relationships you didn't load can't be read later.

The shortcut: Spring Boot and Spring Data JPA

Writing AppConfig by hand teaches you what's going on. In everyday projects, Spring Boot does all of it automatically, and Spring Data JPA writes the repository for you. Generate a project at start.spring.io with the Spring Data JPA and PostgreSQL Driver dependencies (it picks matching versions). Then your configuration is a few lines in application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/school
spring.datasource.username=postgres
spring.datasource.password=secret
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

And the repository becomes an interface, with no implementation at all:

public interface StudentRepository extends JpaRepository<Student, Long> {

    List<Student> findByMarksGreaterThanEqual(int marks);
}

Spring Data creates the implementation, including the query from the method name. Using it:

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Bean
    CommandLineRunner demo(StudentRepository repository) {
        return args -> {
            repository.save(new Student("Asha", 88));
            repository.findByMarksGreaterThanEqual(80).forEach(System.out::println);
        };
    }
}

Student{id=1, name='Asha', marks=88}

Boot auto-configures the connection pool, Hibernate, the transaction manager and the entity scanning. Underneath, it's the same pieces you just built by hand, which is why learning the manual version first makes Boot much easier to understand.

Other things worth knowing

Configuration settings

Hibernate is configured with properties. The ones you'll meet first:

jakarta.persistence.jdbc.url=jdbc:postgresql://localhost:5432/school
jakarta.persistence.jdbc.user=postgres
jakarta.persistence.jdbc.password=secret
hibernate.hbm2ddl.auto=update
hibernate.show_sql=true
hibernate.format_sql=true

You can provide them in several ways, and the more specific one wins:

In code, as we did with HibernatePersistenceConfiguration.
In a hibernate.properties file on the classpath.
In a hibernate.cfg.xml file (read when you call new Configuration().configure()).
In a standard JPA persistence.xml file (used with Persistence.createEntityManagerFactory(...)).
In Spring, through jpaProperties or Spring Boot's application.properties.

The hibernate.hbm2ddl.auto values:

none: do nothing with the schema.
validate: check that the tables match the entities, and fail if they don't.
update: add missing tables and columns.
create: drop and recreate the tables at start-up.
create-drop: like create, and drop them again when the factory closes.

Caching

Hibernate has two levels of cache:

First-level cache: always on. It lives in each session (the persistence context). That's why asking for the same row twice gave us the same object.
Second-level cache: optional. It's shared by all sessions, and needs a cache provider (for example JCache). You turn it on with hibernate.cache.use_second_level_cache=true and mark entities as cacheable. It can reduce database load for data that's read often and changes rarely, but cached data can become stale, so use it carefully.

Optimistic locking with @version

What if two users edit the same row at the same time? Hibernate can detect it with a version column:

@Version
private int version;

Hibernate adds the version to every update:

   update student set marks = ?, version = 2 where id = ? and version = 1

If someone else already changed the row (so its version is no longer 1), no row matches, and Hibernate throws an OptimisticLockException instead of silently overwriting their work. You catch it and ask the user to reload and try again. It's called optimistic because it assumes conflicts are rare and doesn't lock rows in the database.

Managing the schema in real projects

hbm2ddl.auto=update is convenient for learning and prototypes, but it's risky for real databases: it can't safely rename or remove columns, and create and create-drop delete your data. In real projects:

Manage the schema with a migration tool such as Flyway or Liquibase, which applies versioned SQL scripts.
Set hibernate.hbm2ddl.auto to validate (or none), so Hibernate only checks that your entities match the schema.

Logging the SQL

Seeing the SQL is the best way to learn what Hibernate does, and to catch problems like N+1. The simplest switches are hibernate.show_sql and hibernate.format_sql. In code:

.showSql(true, true, false)     // show SQL, format it, don't use color

Typical output (the exact text depends on your version and database):

insert into student (marks,name) values (?,?)
select s1_0.id,s1_0.marks,s1_0.name from student s1_0 where s1_0.id=?
update student set marks=?,name=? where id=?

For more control, use your logging framework: set the logger org.hibernate.SQL to DEBUG to log statements, and org.hibernate.orm.jdbc.bind to TRACE to also see the values bound to the ? parameters (in Hibernate 6 and newer).

Best practices

Code against the standard JPA API unless you need a Hibernate feature.
Make associations lazy (fetch = FetchType.LAZY), and load related data on purpose with join fetch, @BatchSize or entity graphs.
Watch for N+1 by checking the SQL log during development.
Keep transactions short and put them in the service layer, not the controller or repository.
Use readOnly = true for methods that only read.
Use a connection pool such as HikariCP (Spring Boot does this by default).
Never build queries by joining strings. Use named parameters.
Don't expose entities directly in web APIs. Use separate data-transfer objects (DTOs), so lazy fields and internal details don't leak.
Use projections or DTO queries for read-heavy screens, so you don't load full entities you don't need.
Be careful with equals and hashCode on entities. Base them on a business key, or handle the generated id carefully.
Don't use CascadeType.ALL everywhere. Cascade only where a child truly belongs to its parent.
Use @Version for entities that several users can edit.
Manage the schema with Flyway or Liquibase in real projects, and keep hbm2ddl.auto at validate or none.
Test against a real database (for example with Testcontainers) as well as an in-memory one, since SQL dialects differ.
Read the SQL, and use plain SQL (native queries, JDBC or jOOQ) for heavy reports and bulk jobs.

Which one should I use?

JDBC or an ORM? Use an ORM for applications with many entities, relationships and CRUD screens. Use plain JDBC (or JdbcTemplate, jOOQ or MyBatis) for simple scripts, heavy reporting and performance-critical SQL. Many projects mix both.
The Hibernate Session or the JPA EntityManager? EntityManager by default. Session when you need Hibernate-only features.
Plain Hibernate, Spring Framework or Spring Boot? Plain Hibernate to learn the basics or for small tools. Spring Framework when you want to wire everything yourself. Spring Boot with Spring Data JPA for most new applications.
persist or merge? persist for new objects, merge for detached ones (and use the returned object).
find or getReference? find when you need the data. getReference when you only need a handle, such as to set a foreign key.
IDENTITY or SEQUENCE? IDENTITY is simple. SEQUENCE allows Hibernate to batch inserts better, and is usually the better choice for write-heavy tables.
LAZY or EAGER? LAZY almost always. Fetch what you need explicitly.
HQL, native SQL or Criteria? HQL for most queries, native SQL for database-specific or very complex queries, and Criteria when you must build queries dynamically in a type-safe way.
Which hbm2ddl.auto? update for learning, validate or none for real environments.
Configuration in code, properties or XML? Code or properties for simplicity. persistence.xml if you need a standard JPA setup. In Spring, use Spring's configuration.

Common mistakes

The N+1 problem and lazy-loading errors. Looping over a lazy collection fires one query per item, and reading one after the session closed gives a LazyInitializationException. Fetch what you need up front, and read lazy data inside the transaction.
Using create or create-drop on real data. These settings drop your tables at start-up. Use validate or a migration tool outside of local experiments.
Forgetting the transaction. Changes made without a transaction (or without commit) are not saved. In Spring, a missing @Transactional has the same effect.
Following old tutorials. session.save, update, saveOrUpdate, delete and load, and javax.persistence imports, don't work in Hibernate 7. Use persist, merge, remove, getReference and jakarta.persistence.
Mixing up persist and merge. Calling persist on a detached entity fails with a "detached entity passed to persist" error. And after merge, forgetting to use the returned object means your later changes aren't tracked.
Entity rules and relationship bugs. A missing no-arg constructor, a final entity class or a missing @Id stops Hibernate from starting. And forgetting to set both sides of a bidirectional relationship leaves the foreign key null.

Quick recap

ORM maps classes to tables, objects to rows and fields to columns. It solves the object-relational impedance mismatch and removes JDBC boilerplate.
Pros: less code, object-oriented thinking, relationships, portability, caching and change tracking. Cons: a learning curve, hidden SQL, performance traps like N+1, and it's not ideal for bulk or complex reporting.
Hibernate sits on top of JDBC. Its core pieces are the SessionFactory (one per app), the Session (one per unit of work, with a persistence context) and the Transaction.
An entity is transient, persistent, detached or removed. Hibernate saves changes to persistent entities automatically (dirty checking) at flush or commit.
Without Maven, you collect the jars yourself, compile with javac -cp "lib/*" and run with java -cp. With Maven, you declare hibernate-core and the PostgreSQL driver, and Maven does the rest.
Key methods: persist, find, getReference, merge, remove, refresh, flush, clear, createQuery and HQL. Hibernate 7 removed save, update, saveOrUpdate, delete and load.
Jakarta Persistence is the specification, and Hibernate is the implementation. Session extends EntityManager. Code against JPA by default.
In Spring, you configure a DataSource, a LocalContainerEntityManagerFactoryBean with HibernateJpaVendorAdapter, and a JpaTransactionManager. Then @Transactional services and @PersistenceContext repositories do the rest. Spring Boot with Spring Data JPA automates it all.
Also remember: lazy loading and N+1, caching, @Version, schema migrations and reading the SQL log.

Try it yourself

Here's a small practice idea: start PostgreSQL with Docker, then run the plain Hibernate program from this post, first with the jar folder approach and then with Maven. Add a Course entity with a one-to-many relationship to Student, save a course with three students and print them. Then turn on SQL logging, write a loop that reproduces the N+1 problem, count the queries, and fix it with join fetch.

For a bonus experiment, rebuild the same application in the Spring Framework, and watch each @Transactional method produce its SQL. Then replace the repository with a Spring Data JPA interface, and see how much code disappears. Finally, add @Version to Student, open two sessions that edit the same row, and trigger an OptimisticLockException on purpose.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

JDBC Explained: Drivers, Statements and Best Practices

Mayur Bodhare — Sat, 24 Oct 2026 04:43:43 +0000

The first time I had to save data from a Java program into a database, I was sure there would be a different library for every database. One for MySQL, one for Oracle, one for PostgreSQL, each with its own commands to learn.

It turns out Java solved this problem a long time ago, with one standard called JDBC. You learn it once, and the same code works with almost any relational database. You mostly just swap one small jar file and one line of text.

In this post, we'll learn what JDBC is, what a JDBC driver does (and which one to use for each database), the steps of every JDBC program, a complete working example with an explanation of each line, the different execute methods, the three kinds of statements and when to use each, and the best practices that keep your code safe and fast. The example uses an in-memory database called H2, so you don't need to install anything to try it.

What is JDBC?
- The problem JDBC solves
- The main pieces of JDBC
JDBC drivers
- The four driver types
- Drivers for popular databases
- Adding a driver with Maven
- Anatomy of a JDBC URL
Steps for working with JDBC
Your first JDBC program
- The complete code
- Explaining the code
- What happens behind the scenes
Types of execute methods
- executeQuery
- executeUpdate
- execute
- executeBatch
Types of statements
- Statement
- PreparedStatement
- CallableStatement
- SQL injection and why it matters
- Choosing the right statement
Working with ResultSet
Transactions
Best practices
- Close resources with try-with-resources
- Use PreparedStatement for every query with input
- Use a connection pool
- Handle SQLException properly
- Keep credentials out of your code
- Other good habits
Which one should I use?
Common mistakes
Quick recap
Try it yourself

What is JDBC?

JDBC stands for Java Database Connectivity. It's a standard API (a set of classes and interfaces) that lets a Java program connect to a relational database, send SQL commands and read the results. It's part of Java itself, in the packages java.sql and javax.sql.

The problem JDBC solves

Every database has its own way of talking over the network. MySQL speaks one protocol, Oracle another, PostgreSQL a third. Without a standard, you'd have to learn each one and rewrite your code to switch databases.

JDBC fixes this with a middle layer. Your code talks only to JDBC's standard interfaces. A small library from the database vendor, called a driver, translates those calls into the database's own language.

   YOUR JAVA CODE
        |   uses standard interfaces: Connection, Statement, ResultSet
        v
   JDBC API   (java.sql and javax.sql, part of Java SE)
        |
        v
   JDBC DRIVER   (a jar file from the database vendor)
        |   speaks the database's own protocol over the network
        v
   DATABASE   (MySQL, PostgreSQL, Oracle, SQL Server, H2 ...)

Because your code depends only on the standard interfaces, switching databases usually means changing the driver jar and the connection URL. (Your SQL itself may still need small changes, since each database has its own dialect for some features.)

The main pieces of JDBC

You'll meet these names again and again:

DriverManager: finds the right driver for a URL and opens a connection.
DataSource: a more modern way to get connections. It's what connection pools implement, and it's preferred in real applications.
Connection: your session with the database. You use it to create statements and to control transactions.
Statement, PreparedStatement, CallableStatement: objects that send SQL to the database.
ResultSet: the rows that come back from a query.
SQLException: the exception thrown when anything goes wrong with the database.

All of these (except the driver itself) are interfaces. The driver provides the real classes behind them.

JDBC drivers

A JDBC driver is a library that implements the JDBC interfaces for one specific database. It knows how to open a network connection to that database, log in, send SQL and read the results. You add it to your project like any other library.

The four driver types

JDBC drivers are traditionally grouped into four types:

Type 1, JDBC-ODBC bridge: used the old ODBC standard on your computer to reach a database. It was removed from Java in version 8, so you won't use it.
Type 2, native-API driver: partly Java and partly native code, and it needs the database's client software installed on the machine. It's used in a few special cases (for example, Oracle's OCI driver).
Type 3, network-protocol driver: talks to a middleware server, which then talks to the database. It's rare today.
Type 4, thin driver (pure Java): written entirely in Java and talks to the database directly over the network. No extra software to install. This is the type you'll use almost every time, and all the drivers in the next section are Type 4.

Drivers for popular databases

Here are the common ones, with the Maven dependency (groupId:artifactId), the driver class name and an example URL:

MySQL
- Dependency: com.mysql:mysql-connector-j
- Driver class: com.mysql.cj.jdbc.Driver
- URL: jdbc:mysql://localhost:3306/school
MariaDB
- Dependency: org.mariadb.jdbc:mariadb-java-client
- Driver class: org.mariadb.jdbc.Driver
- URL: jdbc:mariadb://localhost:3306/school
PostgreSQL
- Dependency: org.postgresql:postgresql
- Driver class: org.postgresql.Driver
- URL: jdbc:postgresql://localhost:5432/school
Oracle
- Dependency: com.oracle.database.jdbc:ojdbc11 (use ojdbc8 for Java 8)
- Driver class: oracle.jdbc.OracleDriver
- URL: jdbc:oracle:thin:@//localhost:1521/XEPDB1
SQL Server
- Dependency: com.microsoft.sqlserver:mssql-jdbc
- Driver class: com.microsoft.sqlserver.jdbc.SQLServerDriver
- URL: jdbc:sqlserver://localhost:1433;databaseName=school
H2 (a small, pure-Java database, great for learning and tests)
- Dependency: com.h2database:h2
- Driver class: org.h2.Driver
- URL: jdbc:h2:mem:testdb (in memory) or jdbc:h2:~/school (a file)
SQLite
- Dependency: org.xerial:sqlite-jdbc
- Driver class: org.sqlite.JDBC
- URL: jdbc:sqlite:school.db

A few notes:

The driver class names are only needed in old-style code (we'll see why in a moment). It's still useful to recognize them in error messages.
Always check the vendor's documentation for the current version and options. For example, newer SQL Server drivers encrypt the connection by default, so local development often needs extra URL settings such as trustServerCertificate=true (use that only for development, never in production).

Adding a driver with Maven

If you use Maven (see my Maven post), add the dependency in your pom.xml. We'll use H2 for this post's examples:

<dependencies>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.4.240</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

Two things to notice:

Use the newest version you can find on Maven Central. 2.4.240 is just the version I used.
The scope is runtime, because your code uses only the standard java.sql interfaces. The driver is needed to run the program, but not to compile it. That's the kind of "runtime" scope we saw in the Maven post.

For another database, swap in its dependency from the list above.

Anatomy of a JDBC URL

A JDBC URL tells DriverManager which database to reach and where it lives:

   jdbc:mysql://localhost:3306/school?useSSL=true
    |     |        |        |     |        |
    |     |        |        |     |        +-- optional settings (key=value)
    |     |        |        |     +----------- database (schema) name
    |     |        |        +----------------- port
    |     |        +-------------------------- host (the machine running the database)
    |     +----------------------------------- sub-protocol: which database/driver
    +----------------------------------------- always "jdbc"

The exact format changes slightly from database to database (see the list above), but the idea is always jdbc: + the database type + the location.

Steps for working with JDBC

Every JDBC program follows the same steps:

   1. Add the driver          put the driver jar on the classpath (Maven dependency)
          |
          v
   2. Register the driver     happens automatically in modern JDBC
          |
          v
   3. Open a Connection       DriverManager.getConnection(url, user, password)
          |
          v
   4. Create a statement      createStatement() or prepareStatement(sql)
          |
          v
   5. Execute the SQL         executeQuery(), executeUpdate() or execute()
          |
          v
   6. Process the results     loop over the ResultSet, or read the update count
          |
          v
   7. Handle exceptions       catch SQLException
          |
          v
   8. Close everything        ResultSet, then Statement, then Connection

A quick note on step 2. In older tutorials, you'll see this line before connecting:

Class.forName("com.mysql.cj.jdbc.Driver");

You don't need it anymore. Since JDBC 4.0 (Java 6), every driver jar announces itself in a file, and Java finds and registers it automatically as soon as it's on the classpath. Just add the jar, and DriverManager will find it.

Your first JDBC program

We'll build a program that connects to an in-memory H2 database, creates a table, inserts two rows and reads them back. You need nothing installed except the H2 dependency above.

The complete code

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class JdbcDemo {

    private static final String URL = "jdbc:h2:mem:testdb";
    private static final String USER = "sa";
    private static final String PASSWORD = "";

    public static void main(String[] args) {
        try (Connection conn = DriverManager.getConnection(URL, USER, PASSWORD)) {

            createTable(conn);
            insertStudent(conn, 1, "Asha", 88);
            insertStudent(conn, 2, "Ravi", 72);
            printStudents(conn);

        } catch (SQLException e) {
            System.err.println("Database error: " + e.getMessage());
        }
    }

    private static void createTable(Connection conn) throws SQLException {
        String sql = "CREATE TABLE student (id INT PRIMARY KEY, name VARCHAR(50), marks INT)";
        try (Statement stmt = conn.createStatement()) {
            stmt.executeUpdate(sql);
        }
    }

    private static void insertStudent(Connection conn, int id, String name, int marks)
            throws SQLException {
        String sql = "INSERT INTO student (id, name, marks) VALUES (?, ?, ?)";
        try (PreparedStatement ps = conn.prepareStatement(sql)) {
            ps.setInt(1, id);
            ps.setString(2, name);
            ps.setInt(3, marks);
            int rows = ps.executeUpdate();
            System.out.println("Inserted " + rows + " row(s): " + name);
        }
    }

    private static void printStudents(Connection conn) throws SQLException {
        String sql = "SELECT id, name, marks FROM student ORDER BY id";
        try (Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery(sql)) {
            while (rs.next()) {
                int id = rs.getInt("id");
                String name = rs.getString("name");
                int marks = rs.getInt("marks");
                System.out.println(id + " | " + name + " | " + marks);
            }
        }
    }
}

Output:

Inserted 1 row(s): Asha
Inserted 1 row(s): Ravi
1 | Asha | 88
2 | Ravi | 72

Explaining the code

Let's go through it piece by piece.

The three constants. URL, USER and PASSWORD describe where the database is and how to log in. jdbc:h2:mem:testdb means "an H2 database that lives in memory, named testdb." sa is H2's default user, with an empty password. (For a real database, you'd never write the password in your code. More on that in the best practices.)

DriverManager.getConnection(URL, USER, PASSWORD). This asks Java to find a driver that understands the URL, then opens a connection to the database. It returns a Connection, your session with the database. It throws SQLException if the database can't be reached, the login fails or no driver matches.

try (Connection conn = ...). This is try-with-resources. Anything declared in the parentheses is closed automatically when the block ends, even if an exception happens. So we never need to write conn.close() ourselves. (An in-memory H2 database disappears when its last connection closes. Since we use one connection for the whole program, our data stays.)

conn.createStatement(). This creates a Statement object, a messenger that carries plain SQL text to the database.

stmt.executeUpdate(sql). This sends SQL that changes something (here, a CREATE TABLE). It returns the number of rows affected, which is 0 for this kind of command.

conn.prepareStatement(sql) with the ? marks. This creates a PreparedStatement. The ? characters are placeholders for values we'll supply later. Then we fill them in with setInt and setString. The numbers start at 1, not 0: 1 is the first ?, 2 is the second, and so on. executeUpdate() sends the command and returns how many rows were inserted (1).

stmt.executeQuery(sql) and ResultSet. This sends a SELECT and returns a ResultSet, the rows that came back. The loop while (rs.next()) moves to the next row each time, and returns false when there are no more rows. Inside the loop, rs.getInt("id") and rs.getString("name") read the columns of the current row by name.

catch (SQLException e). Almost every JDBC call can throw this checked exception, so the compiler makes us deal with it. Here we simply print the message.

The small helper methods. Putting each job in its own method keeps main short and makes each step easy to read and reuse.

What happens behind the scenes

When you call DriverManager.getConnection(...), a lot happens in a few milliseconds:

   getConnection("jdbc:h2:mem:testdb", "sa", "")
        |
        v
   DriverManager asks each registered driver: "Do you accept this URL?"
        |        (drivers register themselves when their jar is on the classpath)
        v
   The matching driver opens a network connection (TCP) to the database,
   sends the user name and password, and waits for the database to accept them
        |
        v
   You get back a Connection object  (a real class from the driver,
   used through the standard java.sql.Connection interface)

Then, when you run a query:

   stmt.executeQuery("SELECT ...")
        |  the driver sends the SQL text over the network
        v
   DATABASE: parses the SQL, plans how to run it, runs it
        |  sends the rows back (often in chunks)
        v
   ResultSet: a cursor that points at one row at a time; rs.next() moves it

Opening a connection is expensive: it needs a network round trip, a login and some setup. Sending SQL is much cheaper. That's why connection pools (covered in the best practices) are so important.

Types of execute methods

A statement can send its SQL in four main ways. The right one depends on what kind of SQL you're sending:

   METHOD           USE IT FOR                          RETURNS
   executeQuery     SELECT                              ResultSet
   executeUpdate    INSERT, UPDATE, DELETE, and DDL     int (rows affected)
   execute          unknown SQL, or several results     boolean (true = a ResultSet)
   executeBatch     many statements at once             int[] (one count for each)

(DDL means commands that change the structure, like CREATE TABLE.)

executeQuery

Use it for a SELECT. It returns a ResultSet and can never return an update count.

try (Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT name FROM student ORDER BY id")) {
    while (rs.next()) {
        System.out.println(rs.getString("name"));
    }
}

Asha
Ravi

If you pass something that isn't a query (like an INSERT) to executeQuery, you get an SQLException.

executeUpdate

Use it for INSERT, UPDATE, DELETE, and for DDL commands like CREATE TABLE. It returns an int: the number of rows affected.

try (Statement stmt = conn.createStatement()) {
    int rows = stmt.executeUpdate("UPDATE student SET marks = marks + 5 WHERE marks < 80");
    System.out.println("Rows updated: " + rows);
}

Rows updated: 1

Only Ravi (72) matched, so one row changed. For DDL, it returns 0. If you ever expect more than about two billion affected rows, there's also executeLargeUpdate, which returns a long.

execute

Use it when you don't know in advance what the SQL does, or when it might produce several results (some stored procedures do). It returns a boolean:

true means the first result is a ResultSet. Get it with getResultSet().
false means the first result is an update count. Get it with getUpdateCount().

static void run(Connection conn, String sql) throws SQLException {
    try (Statement stmt = conn.createStatement()) {
        boolean hasResultSet = stmt.execute(sql);

        if (hasResultSet) {
            try (ResultSet rs = stmt.getResultSet()) {
                int count = 0;
                while (rs.next()) {
                    count++;
                }
                System.out.println("Query returned " + count + " row(s)");
            }
        } else {
            System.out.println("Update count: " + stmt.getUpdateCount());
        }
    }
}

run(conn, "SELECT * FROM student");
run(conn, "DELETE FROM student WHERE id = 99");

Query returned 2 row(s)
Update count: 0

The same method handled both a query and an update, because execute told us which kind of result we got. In everyday code, executeQuery and executeUpdate are clearer, so reach for execute only when you need its flexibility.

executeBatch

Use it to send many statements in one trip to the database. Sending 1000 inserts one by one means 1000 network round trips. A batch sends them together, which is much faster. You add statements with addBatch(), then send them all with executeBatch():

String sql = "INSERT INTO student (id, name, marks) VALUES (?, ?, ?)";
try (PreparedStatement ps = conn.prepareStatement(sql)) {
    ps.setInt(1, 3);  ps.setString(2, "Meera"); ps.setInt(3, 95); ps.addBatch();
    ps.setInt(1, 4);  ps.setString(2, "Kabir"); ps.setInt(3, 64); ps.addBatch();
    ps.setInt(1, 5);  ps.setString(2, "Zoya");  ps.setInt(3, 81); ps.addBatch();

    int[] counts = ps.executeBatch();
    System.out.println(Arrays.toString(counts));
}

[1, 1, 1]

(This needs import java.util.Arrays;.) The returned array holds one count for each statement. Some drivers return the special value Statement.SUCCESS_NO_INFO (which is -2) instead, meaning "it worked, but I can't tell you how many rows." For very big batches, send them in chunks of a few hundred or thousand rows.

From here on, our table has five students: Asha, Ravi, Meera, Kabir and Zoya.

Types of statements

JDBC has three kinds of statement objects. They differ in how they build and send SQL.

   Statement            plain SQL text, no parameters
        ^
        |  extends
   PreparedStatement    SQL with ? placeholders, precompiled, safe with user input
        ^
        |  extends
   CallableStatement    calls stored procedures and functions

Statement

A Statement sends a complete SQL string exactly as you wrote it. It has no placeholders.

try (Statement stmt = conn.createStatement()) {
    stmt.executeUpdate("CREATE TABLE course (id INT PRIMARY KEY, title VARCHAR(50))");
}

Good for: fixed SQL that has no input from users, like creating tables, running a fixed report or a one-off admin command.
Watch out: every time you run it, the database has to read and plan the SQL again. And if you build the SQL by joining in user input, you open the door to SQL injection (next).

PreparedStatement

A PreparedStatement takes SQL with ? placeholders. The database compiles it once, and you supply the values separately with setInt, setString, setObject and similar methods.

String sql = "SELECT name, marks FROM student WHERE marks >= ?";
try (PreparedStatement ps = conn.prepareStatement(sql)) {
    ps.setInt(1, 80);
    try (ResultSet rs = ps.executeQuery()) {
        while (rs.next()) {
            System.out.println(rs.getString("name") + " " + rs.getInt("marks"));
        }
    }
}

Asha 88
Meera 95
Zoya 81

(Ravi is at 77 after our earlier update, and Kabir at 64, so neither matches.)

Why it's better for most work:

Safe from SQL injection, because values are never mixed into the SQL text.
Faster when repeated, since the database (or driver) can reuse the prepared plan.
Handles types and special characters for you. A name like O'Brien just works, with no manual escaping.
Supports batches easily, as we saw.

One limit: placeholders can only stand for values. You can't use ? for a table name, a column name or an SQL keyword.

CallableStatement

A CallableStatement calls a stored procedure or function, which is a piece of code saved inside the database itself. It uses a special call syntax that JDBC translates for each database:

try (CallableStatement cs = conn.prepareCall("{call get_student_count(?)}")) {
    cs.registerOutParameter(1, Types.INTEGER);
    cs.execute();
    int count = cs.getInt(1);
    System.out.println("Students: " + count);
}

This assumes your database already has a procedure named get_student_count with one output parameter. Notes:

registerOutParameter declares a parameter that the procedure fills in (an OUT parameter). Parameters you send in are IN parameters, set with setXxx as usual. A parameter can also be both (INOUT).
For a function that returns a value, the syntax is {? = call my_function(?)}.
CallableStatement extends PreparedStatement, so everything you know about placeholders still applies.
How you write procedures differs a lot between databases, but the Java side stays the same.

SQL injection and why it matters

SQL injection happens when user input becomes part of the SQL itself. Watch what happens with a nasty input:

String userInput = "x' OR '1'='1";

// UNSAFE: Statement with the input joined into the SQL
String unsafeSql = "SELECT * FROM student WHERE name = '" + userInput + "'";
System.out.println(unsafeSql);
try (Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery(unsafeSql)) {
    int count = 0;
    while (rs.next()) {
        count++;
    }
    System.out.println("Statement returned " + count + " row(s)");
}

// SAFE: PreparedStatement with a placeholder
try (PreparedStatement ps = conn.prepareStatement("SELECT * FROM student WHERE name = ?")) {
    ps.setString(1, userInput);
    try (ResultSet rs = ps.executeQuery()) {
        int count = 0;
        while (rs.next()) {
            count++;
        }
        System.out.println("PreparedStatement returned " + count + " row(s)");
    }
}

SELECT * FROM student WHERE name = 'x' OR '1'='1'
Statement returned 5 row(s)
PreparedStatement returned 0 row(s)

The input was meant to be a name. But with the plain Statement, the quote characters changed the meaning of the SQL. '1'='1' is always true, so the query returned every row. In a login form, the same trick lets someone in without a password. With the PreparedStatement, the whole input is treated as one plain value to compare to a name, so nothing matched.

   Statement (joined text):      [ SQL + user input ]  ---->  database parses it ALL as SQL
   PreparedStatement:            [ SQL with ? ]  ---->  database parses and plans it
                                 [ value ]       ---->  value is handled as DATA only

Many drivers don't allow several commands in one string by default, so the ; DROP TABLE trick is often blocked. But data leaks and login bypasses still work, so don't count on that. The rule is simple: never build SQL by joining in user input.

Choosing the right statement

Statement: fixed SQL with no outside input (DDL, a fixed report, quick scripts).
PreparedStatement: the default choice. Use it for any SQL that has values, anything with user input, anything you run repeatedly and any batch.
CallableStatement: when you need to call a stored procedure or function.

If you're ever unsure, use PreparedStatement. It's almost never the wrong answer.

Working with ResultSet

A ResultSet is like a cursor that starts before the first row. Each call to next() moves it down one row and returns true, or false when you run out:

   before first row
        |
        v   rs.next()  -->  row 1     (true)
        |   rs.next()  -->  row 2     (true)
        |   rs.next()  -->  row 3     (true)
        v   rs.next()  -->  after last (false)

So you must call next() before you read anything. If you skip it, you'll get an error like "before start of result set."

Reading columns:

By name: rs.getString("name"). This is clearer and survives column reordering.
By position: rs.getString(2). Column numbers start at 1.
Pick the getter that matches the column: getInt, getLong, getDouble, getString, getBoolean, getBigDecimal (best for money), and so on.
For dates and times, use the modern java.time types: rs.getObject("birth_date", LocalDate.class).

A subtle trap is NULL. getInt returns 0 for a NULL column, which is indistinguishable from a real zero. To keep a NULL as a NULL, read it as an object:

Integer marks = rs.getObject("marks", Integer.class);   // stays null if the column is NULL

Or call rs.wasNull() right after reading.

You can also inspect the shape of a result with metadata:

try (Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT id, name, marks FROM student")) {
    ResultSetMetaData meta = rs.getMetaData();
    for (int i = 1; i <= meta.getColumnCount(); i++) {
        System.out.println(meta.getColumnName(i) + " : " + meta.getColumnTypeName(i));
    }
}

ID : INTEGER
NAME : CHARACTER VARYING
MARKS : INTEGER

(The type names depend on the database. H2 also shows column names in uppercase.)

By default, a ResultSet is forward-only and read-only: you move down once, and you can't edit rows through it. You can ask for scrollable or updatable result sets with createStatement(type, concurrency), but that's rarely needed. A ResultSet is also tied to its statement: closing the statement closes the result set.

Transactions

A transaction is a group of SQL commands that must succeed together or not at all. The classic example is moving money: subtract from one account, add to another. If the first step works and the second fails, you must undo the first.

By default, JDBC runs in auto-commit mode: every statement is committed (made permanent) the moment it runs. For a multi-step job, turn it off and commit yourself:

conn.setAutoCommit(false);
try {
    debit(conn, 1, 500);     // UPDATE account SET balance = balance - 500 WHERE id = 1
    credit(conn, 2, 500);    // UPDATE account SET balance = balance + 500 WHERE id = 2
    conn.commit();           // both changes become permanent together
} catch (SQLException e) {
    conn.rollback();         // undo everything since the last commit
    throw e;
} finally {
    conn.setAutoCommit(true);
}

   setAutoCommit(false)
          |
     step 1 ---- step 2 ---- step 3
          |                    |
       all OK?              something failed?
          |                    |
       commit()            rollback()
     (permanent)         (as if nothing happened)

Transactions give you the ACID guarantees: Atomic (all or nothing), Consistent (rules stay true), Isolated (other users don't see half-finished work) and Durable (committed data survives a crash). If you forget commit() after turning off auto-commit, your changes are lost when the connection closes.

Best practices

Close resources with try-with-resources

Connection, Statement and ResultSet all hold real resources (network sockets, memory on the database server). If you forget to close them, they leak, and eventually the database runs out of connections. Always use try-with-resources, which closes everything for you in reverse order, even when exceptions happen:

try (Connection conn = dataSource.getConnection();
     PreparedStatement ps = conn.prepareStatement(sql);
     ResultSet rs = ps.executeQuery()) {
    // use rs
}   // closed automatically: rs, then ps, then conn

Avoid the old style with finally blocks, null checks and nested try/catch. It's long and easy to get wrong.

Use PreparedStatement for every query with input

Never build SQL by joining text with user input. Always use ? placeholders, and set the values with the right setXxx method. We saw why in the SQL injection section. It also gives you speed and correct handling of quotes and types for free.

Use a connection pool

Opening a new connection for every request is slow. A connection pool opens a fixed set of connections once and lends them out. When you call close() on a pooled connection, it isn't really closed. It goes back to the pool for the next user.

Popular pools include HikariCP. You create the pool once, when the application starts, and share it:

HikariConfig config = new HikariConfig();
config.setJdbcUrl(System.getenv("DB_URL"));
config.setUsername(System.getenv("DB_USER"));
config.setPassword(System.getenv("DB_PASSWORD"));
config.setMaximumPoolSize(10);

DataSource dataSource = new HikariDataSource(config);   // create once, reuse everywhere

try (Connection conn = dataSource.getConnection()) {    // borrowed from the pool
    // use conn
}                                                        // returned to the pool

Notice the code uses the standard DataSource interface. That's why frameworks and servers prefer it to DriverManager: you can swap in a pool without changing your database code.

Handle SQLException properly

Don't swallow it with an empty catch. SQLException carries more than a message:

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO student VALUES (?, ?, ?)")) {
    ps.setInt(1, 1);                  // id 1 already exists
    ps.setString(2, "Duplicate");
    ps.setInt(3, 50);
    ps.executeUpdate();
} catch (SQLException e) {
    System.err.println("Message : " + e.getMessage());
    System.err.println("SQLState: " + e.getSQLState());
    System.err.println("Code    : " + e.getErrorCode());
}

Message : Unique index or primary key violation: ...
SQLState: 23505
Code    : 23505

(H2 shown. Other databases word the message differently.)

getSQLState() is a standard 5-character code. 23505 means a duplicate key, and the first two digits show the category (23 is "integrity constraint violation"). This is the safest value to write logic against.
getErrorCode() is a number specific to the database vendor.
Log the full exception for developers, but show users a friendly message. Raw database errors can reveal table names and other details an attacker could use.

Keep credentials out of your code

Never hard-code passwords in source files, and never commit them to Git. Read them from environment variables, a config file outside the repository or a secrets manager:

String url = System.getenv("DB_URL");
String user = System.getenv("DB_USER");
String password = System.getenv("DB_PASSWORD");

Also give the application's database user only the permissions it needs (for example, no permission to drop tables), and use an encrypted connection (TLS) when the database is on another machine.

Other good habits

Select only what you need. Name the columns instead of SELECT *, and add WHERE and limits, so you don't pull huge amounts of data.
Use batches for bulk inserts and updates, in chunks.
Use transactions for anything that must succeed as a unit, and keep them short.
Use java.time types (LocalDate, LocalDateTime) with setObject and getObject, instead of the older java.util.Date and java.sql.Date.
Separate database code from business logic. Put SQL in its own classes (often called DAOs or repositories), so the rest of the program doesn't depend on JDBC details.
Set timeouts. stmt.setQueryTimeout(30) stops a stuck query from hanging forever.
Don't use Class.forName for modern drivers. Just keep the driver jar on the classpath.
Use column names in ResultSet reads for clarity, unless performance on huge result sets proves otherwise.

Which one should I use?

Statement or PreparedStatement? PreparedStatement whenever there's any input value or any repetition. Statement only for fixed, input-free SQL like DDL.
CallableStatement? Only to call stored procedures or functions.
executeQuery, executeUpdate or execute? executeQuery for SELECT, executeUpdate for everything that changes data or structure, and execute only when the kind of result is unknown or there may be several. Use executeBatch for bulk work.
DriverManager or DataSource? DriverManager is fine for learning and small scripts. Use a pooled DataSource in real applications.
Get columns by name or by index? Name, for readability. Index is a little faster and fine for tiny queries.
JDBC directly, or a framework? Plain JDBC is perfect for learning, small tools and cases where you want full control. For bigger applications, tools built on top of JDBC (like Spring's JdbcTemplate, jOOQ or JPA with Hibernate) remove repetitive code. They all use JDBC underneath, so understanding it makes every one of them easier.
Auto-commit or manual transactions? Auto-commit for single statements. Manual commit and rollback whenever several statements belong together.

Common mistakes

"No suitable driver found." The driver jar isn't on the classpath, or the URL is wrong. Check the dependency (and its scope) and the exact URL format for your database.
Joining user input into SQL. "... WHERE name = '" + name + "'" is an SQL injection bug waiting to happen. Use PreparedStatement with ?.
Not closing resources. Leaked connections, statements and result sets slowly exhaust the database. Use try-with-resources.
Off-by-one and cursor mistakes. Parameter and column positions start at 1, and a ResultSet must be advanced with next() before you read it.
Using the wrong execute method. Calling executeQuery with an INSERT, or executeUpdate with a SELECT, throws an SQLException. Match the method to the SQL, or use execute.
Transaction surprises. With auto-commit on, a half-finished multi-step job leaves half the changes saved. With auto-commit off, forgetting commit() throws all the changes away.

Quick recap

JDBC is Java's standard API (java.sql and javax.sql) for talking to relational databases. Your code uses the interfaces, and a vendor's driver does the translation.
Drivers come in four types, but you'll use Type 4 (pure Java): mysql-connector-j, postgresql, ojdbc11, mssql-jdbc, h2, sqlite-jdbc and others. Add the right one with Maven, usually in runtime scope.
A JDBC URL looks like jdbc:<database>://host:port/name. Since JDBC 4, drivers register themselves, so Class.forName is no longer needed.
The steps: add the driver, open a Connection, create a statement, execute the SQL, process the results, handle SQLException and close everything.
Execute methods: executeQuery (SELECT, returns a ResultSet), executeUpdate (changes data, returns a row count), execute (unknown or multiple results, returns a boolean) and executeBatch (many statements at once).
Statements: Statement (plain, fixed SQL), PreparedStatement (placeholders, safe, faster, the default) and CallableStatement (stored procedures).
Joining user input into SQL causes SQL injection. PreparedStatement prevents it.
A ResultSet is a cursor: call next() first, and columns start at 1. Watch out for NULL values.
Use transactions (setAutoCommit(false), commit, rollback) when several statements must succeed together.
Best practices: try-with-resources, PreparedStatement for all input, a connection pool, careful SQLException handling, credentials outside the code and small, focused queries.

Try it yourself

Here's a small practice idea: build a StudentDao class with five methods: insert, findById, findAll, updateMarks and delete, all using PreparedStatement and try-with-resources, against the H2 table from this post. Then add a insertAll(List<Student>) method that uses a batch, and a method that moves marks from one student to another inside a transaction, rolling back if either update fails.

For a bonus experiment, switch to a real database. Install MySQL or PostgreSQL (or run one in Docker), swap the H2 dependency for the right driver, and change only the URL, user and password. The rest of your code should run unchanged, and that's the whole point of JDBC. Then put your connection settings in environment variables, and add a HikariCP pool.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Git Branches Are Just Pointers: A Simple Explanation

Mayur Bodhare — Fri, 23 Oct 2026 11:56:19 +0000

Years ago, I had a folder on my laptop that looked like this: project, project_final, project_final_v2, project_final_v2_REAL and project_final_v2_REAL_use_this_one. I was scared to delete any of them, because I couldn't remember which one had the fix I made on Tuesday. Then a friend and I edited the same file at the same time, and one of us overwrote the other's work.

If that sounds familiar, you already understand the problem that version control solves. And the tool that almost every developer uses today for it is Git.

In this post, we'll learn what version control is and the three types of version control systems, where Git came from, how Git stores your work, what repositories are (and how GitHub, GitLab and Bitbucket fit in), the working directory and the staging area, the everyday workflow, branches, HEAD, tags and the common commands with examples. I've drawn the important pictures in text, and most commands come with the output you'll see.

Version control systems
- What is a version control system?
- Why we need one
Types of version control systems
- 1. Local VCS
- 2. Centralized VCS
- 3. Distributed VCS
- Comparing the three types
What is Git?
- A short history of Git
- How Git stores your work
- What is inside the .git folder
Repositories
- Local and remote repositories
- GitHub, GitLab and Bitbucket
Setting up Git for the first time
The three areas of Git
- Working directory
- Staging area
- Local repository
- The four states of a file
The Git workflow
- A solo workflow
- A team workflow
Branches
- What a branch really is
- Creating, switching and merging
- Merge conflicts
Pointers in Git and HEAD
- What HEAD is
- Detached HEAD
- Moving relative to HEAD
Tags
- Lightweight and annotated tags
- Working with tags
Common Git commands with examples
- Starting a repository
- Checking status and differences
- Staging and committing
- Viewing history
- Branching and merging
- Working with remotes
- Undoing things
- Saving work with stash
- Ignoring files with .gitignore
Which one should I use?
Common mistakes
Quick recap
Try it yourself

Version control systems

What is a version control system?

A version control system (VCS) is a tool that records the changes you make to your files over time, so you can bring back any earlier version whenever you want. Instead of keeping only the latest copy, it keeps the whole history.

Every saved version is usually called a commit or a revision. With a VCS, you can answer questions like:

What did this file look like last month?
Who changed this line, when, and why?
Which change broke the build?
How do I go back to the version that worked?

Why we need one

Without version control, people copy folders, rename files with "final" in the name and email zip files to each other. That causes real problems:

No history. You can't see what changed, or why.
Lost work. One person overwrites another person's changes.
Fear of experiments. Trying a new idea feels risky, because you can't easily undo it.
No clear record. Nobody knows which copy is the right one.

A VCS fixes all of this:

   WITHOUT version control               WITH version control

   project/                              project/        one folder, one history
   project_final/
   project_final_v2/                     v1 -- v2 -- v3 -- v4 -- v5
   project_final_v2_REAL/                 ^                      ^
   project_final_v2_REAL_use_this_one/    go back to any point   latest

You get a full history, easy undo, safe teamwork, cheap experiments (with branches, as we'll see) and a backup if the history is stored on a server. It also fits naturally with the other tools in a developer's day, like build tools and automated tests.

Types of version control systems

Version control systems have grown through three generations: local, centralized and distributed.

1. Local VCS

A local VCS keeps a small database of versions on your own computer. When you change a file, the tool saves the new version in that database. A classic example is RCS (Revision Control System), from the 1980s.

   YOUR COMPUTER
  +-----------------------------------------+
  |   working files        local database   |
  |   report.txt   <---->  v1, v2, v3 ...   |
  +-----------------------------------------+

Good: simple, and you don't need a server or a network.
Not good: it works for one person on one machine. There's no way to collaborate, and if your disk dies, the history dies with it.

2. Centralized VCS

A centralized VCS keeps all the versions on one central server. Each developer "checks out" a working copy from it, and sends changes back to the server with a commit. Examples are CVS, Subversion (SVN) and Perforce.

                   +-------------------------+
                   |     CENTRAL SERVER      |
                   |  the ONLY full history  |
                   +-------------------------+
                     ^      ^       ^      ^
              commit |      |       |      | update
                     v      v       v      v
                  Alice    Bob    Carol    Dan
              (working copy only: the latest files)

Good: everyone works from the same place, and admins can control who can do what. It's easy to understand.
Not good: the server is a single point of failure. If it goes down, nobody can commit or look at history. If its disk is lost and there's no backup, the history is gone. You also need the network for most actions.

3. Distributed VCS

In a distributed VCS, every developer gets a full copy of the entire repository, including all of its history. You commit to your own copy, with no server needed, and later share your commits with others. Examples are Git, Mercurial and Bazaar.

                +--------------------------+
                |  SHARED REMOTE (GitHub)  |
                |   full copy + history    |
                +--------------------------+
                   ^  push/pull   ^  push/pull
                   |              |
        +--------------------+  +--------------------+
        |  Alice's computer  |  |   Bob's computer   |
        |  FULL copy +       |  |   FULL copy +      |
        |  full history      |  |   full history     |
        +--------------------+  +--------------------+

Good: you can work offline, commits are instant, there are many backups (every clone is one) and branching is cheap. Teams can choose any workflow they like.
Not good: there's more to learn at first, and a clone downloads the whole history. Also, which copy is "the official one" is a rule your team agrees on (by convention, the shared remote), not something the tool enforces.

Comparing the three types

                      LOCAL            CENTRALIZED           DISTRIBUTED
   Examples           RCS              CVS, SVN, Perforce    Git, Mercurial
   Where is history?  your disk only   on the server         in EVERY clone
   Teamwork?          no               yes                   yes
   Works offline?     yes              very limited          yes (almost everything)
   If a server dies   n/a              history at risk       any clone can restore it

What is Git?

Git is a free, open-source, distributed version control system. It runs on every major operating system, it's fast, and it's the most widely used VCS in the world.

A short history of Git

Before 2002, the Linux kernel (one of the biggest open-source projects) was managed by sharing patches and archive files by hand.
From 2002, the kernel team used BitKeeper, a proprietary distributed system that gave the kernel developers free use.
In 2005, that free arrangement ended after a dispute. Linus Torvalds, the creator of Linux, decided to write a replacement himself.
His goals were: speed, a simple design, strong support for thousands of parallel branches (non-linear development), being fully distributed, and the ability to handle huge projects like the Linux kernel.
Git was working within days, and in April 2005 it was already being used to manage its own source. By mid-2005, the Linux kernel was managed with Git. Junio Hamano took over as the maintainer in July 2005 and has led the project since. Git 1.0 followed in December 2005.
The name "git" is British slang for an unpleasant person. Linus joked that he names his projects after himself.
GitHub launched in 2008 and made Git easy to share, and Git became the standard for modern software teams.

How Git stores your work

Many older systems store a list of changes for each file. Git thinks differently: every commit is a snapshot of your whole project at that moment. If a file didn't change, Git doesn't store it again. It simply points to the earlier identical copy. (Internally, Git also compresses data efficiently, but the model to keep in your head is "snapshots.")

Git keeps four kinds of objects in its database:

Blob: the contents of one file.
Tree: a folder. It lists file names and points to blobs and other trees.
Commit: a snapshot. It points to one tree, to its parent commit(s), and holds the author, date and message.
Tag: a named label (we'll see these later).

   commit a1b2c3d
     |-- tree  (the snapshot of the whole project folder)
     |      |-- blob  README.md
     |      +-- tree  src/
     |             +-- blob  App.java
     |-- parent  3f2a9c1   <-- the previous commit
     |-- author, date
     +-- message: "Update README"

Each object is named by a hash, a 40-character code (SHA-1) calculated from its content, like 3f2a9c1e5d6b7a8c9d0e1f2a3b4c5d6e7f8a9b0c. (Git can also use SHA-256 as an option.) This has two nice effects: the same content always gets the same name, and if anyone changes even one letter of an old commit, its hash changes. That's how Git notices tampering and corruption. You usually only need the first 7 characters of a hash.

You can look inside a commit with git cat-file:

git cat-file -p HEAD

tree 9c8f2e1d7a5b3c4e6f8a0b1c2d3e4f5a6b7c8d9e
parent 3f2a9c1e5d6b7a8c9d0e1f2a3b4c5d6e7f8a9b0c
author Asha Rao <asha@example.com> 1792730700 +0530
committer Asha Rao <asha@example.com> 1792730700 +0530

Update README

(Your hashes and dates will be different.) A commit is just a small text object: a tree, a parent and a message.

What is inside the .git folder

When you create a repository, Git makes a hidden folder called .git inside your project. This folder is the repository: all the history lives there. If you delete it, your project folder becomes a normal folder again.

   my-project/
   |-- README.md                 <- your files (the working directory)
   |-- src/
   +-- .git/                     <- the repository itself
        |-- HEAD                 <- which branch (or commit) you're on now
        |-- config               <- settings for this repository
        |-- index                <- the staging area
        |-- objects/             <- all content: blobs, trees, commits, tags
        |-- refs/
        |    |-- heads/          <- one small file per branch
        |    +-- tags/           <- one small file per tag
        +-- hooks/               <- optional scripts that run on events

Remember HEAD, index and refs. They explain most of what follows.

Repositories

A repository (or repo) is a project folder that Git is tracking, together with its complete history. It's the main thing in Git.

Local and remote repositories

A local repository is the one on your computer (the .git folder in your project).
A remote repository is a copy stored on a server, such as GitHub, which the whole team shares. Git gives each remote a short name. The default is origin.

   YOUR COMPUTER                                    SERVER (GitHub, GitLab ...)
  +--------------------+     git push  ------->   +-------------------------+
  |  local repository  |                           |    remote repository    |
  |  (full history)    |  <------- git fetch/pull  |      called "origin"    |
  +--------------------+                           +-------------------------+
            ^
            |  git clone  (makes a local copy of a remote, once)

git clone copies a remote repository to your computer (once).
git push uploads your new commits.
git fetch and git pull bring other people's commits down.

You connect to a remote over HTTPS or SSH. GitHub no longer accepts your account password for Git over HTTPS. You use a personal access token instead, or an SSH key.

GitHub, GitLab and Bitbucket

First, a very common mix-up: Git is the tool, and GitHub is a website. Git works fine without any of them. GitHub, GitLab and Bitbucket are hosting services that store your remote repositories and add useful team features around them: a website to browse code, issue tracking, code review, permissions and automation.

GitHub: the biggest, and home to most open-source projects. It's owned by Microsoft (since 2018). Its review feature is called a pull request, and its built-in automation is GitHub Actions.
GitLab: an all-in-one DevOps platform with built-in CI/CD (GitLab CI/CD). Its review feature is called a merge request. You can also host it yourself, which many companies prefer.
Bitbucket: from Atlassian, so it works very closely with Jira and other Atlassian tools. It has pull requests and its own pipelines (Bitbucket Pipelines).

Others exist too, like Azure DevOps Repos and the self-hosted Gitea. All of them speak Git, so your commands are exactly the same on each. You can even push one repository to two of them.

Setting up Git for the first time

Install Git from the official site (git-scm.com) or your package manager, then check it:

git --version

git version 2.x.y

Tell Git who you are. This name and email are stored in every commit you make:

git config --global user.name "Asha Rao"
git config --global user.email "asha@example.com"
git config --global init.defaultBranch main

--global means "for my user on this computer." Without it, the setting applies to just one repository (--local). There's also a --system level for the whole machine.
The last line makes new repositories start with a branch called main. Older Git versions used master by default.
To see all your settings, run git config --list.

The three areas of Git

This is the idea that makes Git click. Your files move through three areas on your computer, and then to a fourth place, the remote:

   WORKING DIRECTORY      STAGING AREA          LOCAL REPOSITORY        REMOTE REPOSITORY
   (your files,           (index: what goes     (.git: the history)     (GitHub, GitLab ...)
    where you edit)        into the next commit)
          |                      |                      |                      |
          |   git add            |    git commit        |    git push          |
          |--------------------->|--------------------->|--------------------->|
          |                      |                      |                      |
          |                      |                      |<---------------------|
          |                      |                      |   git fetch / pull   |
          |<--------------------------------------------|                      |
                     git switch / git restore (bring files back)

Working directory

The working directory (also called the working tree) is simply your project folder, with the actual files you open and edit. It starts as a checked-out snapshot of one commit. Whatever you change here, Git notices, but nothing is saved to history yet.

Staging area

The staging area (also called the index) is a waiting room for your next commit. You choose exactly which changes should go in, using git add.

Why does Git have this extra step? Imagine you fixed a bug and, at the same time, tidied some unrelated code. With a staging area, you can stage and commit the bug fix first, and the tidying as a separate commit. Small, focused commits are much easier to review and to undo later. A good way to think about it is packing a box before you seal it: git add puts things in the box, and git commit seals it and puts it on the shelf.

Behind the scenes, the staging area is just the .git/index file, a list of what the next snapshot will contain.

Local repository

The local repository is the .git folder: the permanent, committed history on your own machine. When you run git commit, Git takes whatever is in the staging area and saves it as a new snapshot here.

The four states of a file

At any moment, each file is in one of four states:

Untracked: a new file that Git doesn't know about yet.
Committed (also called unmodified): the file is the same as in the last commit.
Modified: you changed it, but didn't stage it.
Staged: you marked the change for the next commit.

   Untracked ---- git add ----> Staged ---- git commit ----> Committed
                                  ^                              |
                                  |                           edit the file
                               git add                           |
                                  |                              v
                                  +---------------------------- Modified

The Git workflow

A solo workflow

Here's the everyday loop, as a hands-on session. We'll create a project and watch the file move through the states:

mkdir my-project
cd my-project
git init

Initialized empty Git repository in /home/asha/my-project/.git/

Create a file, then ask Git what it sees:

echo "# My Project" > README.md
git status

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    README.md

nothing added to commit but untracked files present (use "git add" to track)

The file is untracked. Now stage it:

git add README.md
git status

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   README.md

It's staged. Now commit it:

git commit -m "Add README"

[main (root-commit) 3f2a9c1] Add README
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

It's committed. Now edit the file and check again:

echo "A small demo project." >> README.md
git status

On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

It's modified. See exactly what changed, then stage and commit again:

git diff

diff --git a/README.md b/README.md
index 8c7e5a6..2b1f4d9 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,2 @@
 # My Project
+A small demo project.

git add README.md
git commit -m "Describe the project"
git log --oneline

a1b2c3d (HEAD -> main) Describe the project
3f2a9c1 Add README

The loop is always the same: edit, check, stage, commit, and push when you want to share. A good commit message is short (about 50 characters for the first line), written as a command ("Add login form", not "added stuff"), and says what the change does.

A team workflow

When several people work together, the most common method is the feature-branch workflow. Nobody works directly on main. Each new piece of work gets its own branch, and it joins main through a pull request (called a merge request on GitLab):

   main      o---o---o---------------------o---o        (always stable)
                      \                   /
   feature             o---o---o---------+              (your work, reviewed, then merged)

The steps:

Clone the repository once: git clone <url>.
Update your local main: git switch main, then git pull.
Create a branch for your work: git switch -c feature/login.
Edit, then git add and git commit, as often as you like.
Upload the branch: git push -u origin feature/login.
Open a pull request on the website. Teammates review it, and automated tests run.
After approval, merge it (usually with a button on the website).
Clean up: git switch main, git pull, then git branch -d feature/login.

Branches

What a branch really is

A branch is a lightweight, movable pointer to a commit. That's all. It is not a copy of your files. Creating a branch just writes the 40-character hash of a commit into a tiny file in .git/refs/heads/. When you make a new commit on a branch, the pointer moves forward to it automatically.

That's why branching in Git is instant and almost free, while in older systems, a branch could mean copying the entire project.

   Each commit points back to its parent. Branches point to commits.

        C1 <-- C2 <-- C3 <-- C4                 <- main
                       \
                        C5 <-- C6               <- feature

You can see the file for yourself:

cat .git/refs/heads/main

a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Creating, switching and merging

git branch                       # list branches (* marks the current one)
git branch feature/login         # create a branch (doesn't switch to it)
git switch feature/login         # move to that branch
git switch -c feature/login      # create AND switch in one step

(git switch needs Git 2.23 or newer. Older tutorials use git checkout for the same jobs.)

Switched to a new branch 'feature/login'

Let's add a commit on the branch, then merge it back into main:

echo "login page" > login.txt
git add login.txt
git commit -m "Add login page"

git switch main
git merge feature/login

If main hasn't moved since you branched, Git simply slides the main pointer forward. This is called a fast-forward merge:

Updating a1b2c3d..9e8d7c6
Fast-forward
 login.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 login.txt

   Before:    C1 <- C2 <- C3                      main
                           \
                            C4 <- C5              feature

   After a fast-forward merge (main just moves to C5):

              C1 <- C2 <- C3 <- C4 <- C5          main, feature

If both branches have new commits, Git can't just slide the pointer. It creates a new merge commit with two parents, combining both lines of work:

Merge made by the 'ort' strategy.
 login.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 login.txt

(Older Git versions say recursive instead of ort.)

        C1 <- C2 <- C3 <- C6 <------------ M        main (merge commit M)
                       \                  /
                        C4 <- C5 <-------+          feature

Once a branch is merged, you can delete it. The commits stay in history. Only the pointer goes away:

git branch -d feature/login

Deleted branch feature/login (was 9e8d7c6).

There's another way to combine work called rebase. It replays your commits on top of another branch to make a straight line of history. It's powerful, but never rebase commits that other people already have.

Merge conflicts

A merge conflict happens when both branches changed the same lines of the same file. Git can't guess which version is right, so it stops and asks you:

Auto-merging greeting.txt
CONFLICT (content): Merge conflict in greeting.txt
Automatic merge failed; fix conflicts and then commit the result.

Open the file. Git marks the conflicting part:

<<<<<<< HEAD
Welcome to my app
=======
Welcome to my awesome app
>>>>>>> feature/greeting

Between <<<<<<< HEAD and ======= is your current branch's version.
Between ======= and >>>>>>> is the incoming branch's version.

To resolve it:

Edit the file so it contains exactly what you want, and delete the three marker lines.
Stage the file: git add greeting.txt.
Finish the merge: git commit (Git suggests a merge message for you).

If you'd rather start over, run git merge --abort to go back to how things were before the merge.

Pointers in Git and HEAD

Here's a secret that makes Git much easier to understand: almost everything is a pointer (called a ref). A branch is a pointer to a commit. A tag is a pointer to a commit. Even the remote branch names, like origin/main, are pointers that remember where the remote was last time you checked. They're all small files under .git/refs. The most important pointer is HEAD.

What HEAD is

HEAD is a pointer that means "where I am right now." Usually, it points to the current branch, and that branch points to a commit:

   HEAD  --->  main  --->  C4
                            ^
                          your latest commit

You can see it directly:

cat .git/HEAD

ref: refs/heads/main

That file says: "HEAD points to the branch main." When you make a commit, Git creates it, then moves the branch that HEAD points to. When you switch branches (git switch feature), Git changes what HEAD points to, and updates your working files to match.

git log --oneline --decorate shows where the pointers are. In the output, (HEAD -> main) means HEAD is on main:

a1b2c3d (HEAD -> main, origin/main) Describe the project
3f2a9c1 Add README

Detached HEAD

Sometimes HEAD points straight at a commit instead of at a branch. This is called a detached HEAD. It happens when you check out a specific commit or a tag:

git switch --detach 3f2a9c1

Note: switching to '3f2a9c1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

HEAD is now at 3f2a9c1 Add README

(Trimmed. Older Git versions use git checkout 3f2a9c1.)

   Normal:      HEAD --> main --> C4

   Detached:    HEAD ------------> C2        (no branch name is attached)
                main ------------> C4

It's fine for looking around at old code. But if you make commits while detached, they don't belong to any branch, and when you switch away, they're easy to lose. Two fixes:

To keep your work, create a branch before you leave: git switch -c rescue-branch.
To go back to normal, switch to a branch: git switch main.

If you ever lose commits, git reflog shows the places HEAD has been, and you can usually find them there.

Moving relative to HEAD

You can describe commits relative to HEAD, without remembering hashes:

HEAD is the current commit.
HEAD~1 (or just HEAD~) is its parent, one step back.
HEAD~2 is two steps back, and so on.
HEAD^ also means the parent. The difference shows up only on merge commits: HEAD^1 is the first parent and HEAD^2 is the second.

git show --stat HEAD~1          # what was in the previous commit
git diff HEAD~2                 # compare now with two commits ago
git reset --soft HEAD~1         # undo the last commit but keep the changes

Common Git commands with examples

Here's a quick reference, grouped by job. Most of these you've already seen in action.

Starting a repository

git init                              # turn the current folder into a repository
git clone https://github.com/asha/my-project.git          # copy a remote repository
git clone https://github.com/asha/my-project.git demo     # ... into a folder named "demo"

Cloning into 'my-project'...
remote: Enumerating objects: 12, done.
Receiving objects: 100% (12/12), done.

Checking status and differences

git status            # full status
git status -s         # short status
git diff              # changes you have NOT staged yet
git diff --staged     # changes that ARE staged (what the next commit will contain)
git diff main..feature/login     # differences between two branches

The short status uses two letters. The first is the staging area, and the second is the working directory:

 M README.md
M  src/App.java
?? notes.txt

M means modified but not staged.
M means staged.
?? means untracked.

Staging and committing

git add README.md          # stage one file
git add .                  # stage everything in this folder and below
git add -p                 # stage piece by piece, choosing each change
git commit -m "Fix typo in README"      # commit what is staged
git commit -am "Update docs"            # stage tracked files AND commit
git commit --amend -m "Better message"  # replace the last commit
git rm old.txt             # delete a file and stage the deletion
git mv old.txt new.txt     # rename a file and stage it

git commit -am skips untracked files, so new files still need git add. Use --amend only on commits you haven't pushed.

Viewing history

git log                     # full history
git log --oneline           # one line per commit
git log --oneline --graph --decorate --all     # a picture of all branches
git log -3                  # only the last 3 commits
git log --author="Asha"     # commits by one person
git log -p                  # include the changes in each commit
git show 3f2a9c1            # details of one commit
git blame README.md         # who last changed each line
git reflog                  # where HEAD has been (a safety net)

A default git log entry looks like this:

commit 3f2a9c1e5d6b7a8c9d0e1f2a3b4c5d6e7f8a9b0c (HEAD -> main)
Author: Asha Rao <asha@example.com>
Date:   Fri Oct 23 10:15:00 2026 +0530

    Add README

And the graph view shows how branches split and join:

*   9e8d7c6 (HEAD -> main) Merge branch 'feature/login'
|\
| * 5d4c3b2 (feature/login) Add login page
* | a1b2c3d Describe the project
|/
* 3f2a9c1 Add README

Branching and merging

git branch                  # list local branches
git branch -a               # also list remote branches
git switch -c feature/x     # create and switch to a branch
git switch main             # go back to main
git merge feature/x         # merge feature/x into the current branch
git merge --abort           # cancel a merge that has conflicts
git branch -d feature/x     # delete a merged branch
git branch -D feature/x     # force-delete (even if not merged)
git cherry-pick 5d4c3b2     # copy ONE commit onto the current branch

Working with remotes

git remote add origin https://github.com/asha/my-project.git
git remote -v

origin  https://github.com/asha/my-project.git (fetch)
origin  https://github.com/asha/my-project.git (push)

git push -u origin main

Enumerating objects: 6, done.
Writing objects: 100% (6/6), 512 bytes | 512.00 KiB/s, done.
To https://github.com/asha/my-project.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

(Trimmed.) The -u option links your local main to origin/main, so from now on a plain git push and git pull know where to go.

git fetch               # download new commits, but don't change your files
git pull                # fetch + merge into your current branch
git pull --rebase       # fetch + rebase (keeps history in a straight line)
git branch -vv          # show which remote branch each local branch follows

   git fetch  =  download what others did (your files stay untouched)
   git pull   =  git fetch  +  git merge   (your current branch is updated)

If someone pushed before you, Git refuses your push:

To https://github.com/asha/my-project.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/asha/my-project.git'

The fix is simple: run git pull to get their work, then push again.

Undoing things

Git gives you several kinds of "undo", and they work at different levels:

git restore README.md                 # throw away unstaged changes in a file
git restore --staged README.md        # unstage a file (changes stay in the file)
git commit --amend -m "New message"   # fix the last commit (if not pushed)
git reset --soft HEAD~1               # undo last commit, keep changes STAGED
git reset HEAD~1                      # undo last commit, keep changes UNSTAGED
git reset --hard HEAD~1               # undo last commit, DELETE the changes
git revert 5d4c3b2                    # make a NEW commit that cancels an old one

The three reset modes differ in how far they go:

                    HEAD moves?    staging area     working directory
   reset --soft        yes          unchanged         unchanged
   reset (mixed)       yes          reset             unchanged
   reset --hard        yes          reset             reset      (changes are LOST)

Two warnings to remember:

git restore <file> and git reset --hard destroy uncommitted work, and you can't get it back.
If a commit is already pushed and shared, don't rewrite it with reset or --amend. Use git revert instead. It adds a new commit that undoes the old one, and keeps everyone's history intact.

(Older tutorials use git checkout -- <file> instead of git restore.)

Saving work with stash

Sometimes you're halfway through a change and need to switch branches. git stash puts your uncommitted changes on a shelf and gives you a clean working directory:

git stash

Saved working directory and index state WIP on main: a1b2c3d Describe the project

git stash list

stash@{0}: WIP on main: a1b2c3d Describe the project

git stash pop        # bring the changes back and remove them from the shelf
git stash apply      # bring them back but keep a copy on the shelf
git stash drop       # throw the newest stash away
git stash -u         # also stash untracked (new) files

Ignoring files with .gitignore

Some files should never be committed: build output, editor settings, logs and secrets. Put patterns for them in a file named .gitignore at the top of your project. For a Java and Maven project, it might look like this:

target/
*.class
.idea/
*.log
.env

target/ ignores a whole folder (the Maven build output).
*.class ignores every file ending in .class.
A line starting with ! makes an exception, for example !important.log.
A line starting with # is a comment.
.gitignore only affects untracked files. If a file is already tracked, stop tracking it with git rm --cached <file>, then commit.

Never commit passwords, tokens or keys. Once something is in the history, removing it completely is hard, and a leaked secret should be treated as stolen.

Which one should I use?

Merge or rebase? Merge is safe and keeps the true history, including merge commits. Rebase gives a cleaner straight line, but rewrites commits. Use rebase only on your own, unpublished work, and merge for shared branches.
reset or revert? Use reset for local commits nobody else has. Use revert for anything already pushed.
fetch or pull? Use fetch when you want to look before you change anything. Use pull when you just want to update.
git add . or git add -p? git add . is quick, but it can sweep in files you didn't intend. git add -p lets you review each change and build clean commits.
Lightweight or annotated tag? Annotated for releases (it records who, when and why). Lightweight for personal bookmarks.
HTTPS or SSH? HTTPS with a token is simplest to start. SSH keys are more convenient once they're set up, because you don't type credentials.
stash, a WIP commit or a branch? stash is for short interruptions. For longer work, make a branch and commit to it.
GitHub, GitLab or Bitbucket? Choose by what your team already uses: open-source reach (GitHub), a built-in all-in-one platform or self-hosting (GitLab), or tight Jira integration (Bitbucket).
git switch and git restore or git checkout? On a modern Git, use switch and restore. Each does one job, while checkout does several.

Common mistakes

Committing things that don't belong. Build folders, .class files, editor settings and, worst of all, secrets. Set up .gitignore on day one, and if a secret was committed, change it immediately.
Huge, vague commits. "fix stuff" with 40 changed files is impossible to review or undo. Make small, focused commits with clear messages.
Rewriting shared history. Using --amend, rebase, reset --hard or push --force on commits others already have causes painful conflicts for the whole team. Use git revert, and if you must force push, use --force-with-lease, which refuses to overwrite work you haven't seen.
Working in a detached HEAD, then moving away. The commits are on no branch and are easy to lose. Make a branch first with git switch -c, and remember that git reflog can usually rescue them.
Panicking about merge conflicts. A conflict is normal. Open the file, search for <<<<<<<, choose what you want, remove the markers, git add and commit. Use git merge --abort if you want to start again.
Forgetting what's local. A commit isn't shared until you git push it, and tags aren't pushed unless you ask. If a push is rejected, git pull first, then push again.

Quick recap

A version control system records the history of your files. There are three types: local (history on one machine), centralized (one server, like SVN) and distributed (every clone has the full history, like Git).
Git was created by Linus Torvalds in 2005, after the free BitKeeper arrangement for the Linux kernel ended. It's fast, distributed and built for non-linear work.
Git stores snapshots, made of blobs, trees, commits and tags, each named by a hash. Everything lives in the hidden .git folder.
A repository can be local or remote (usually called origin). GitHub, GitLab and Bitbucket host remotes and add review, issues and automation. They are not the same as Git.
Files move through the working directory, the staging area and the local repository, using git add and git commit. Then git push shares them.
A file is untracked, committed, modified or staged.
A branch is a movable pointer to a commit. HEAD points to where you are now. Merging joins branches. Conflicts are resolved by hand.
A tag is a pointer that never moves, ideal for releases. Push tags explicitly.
Everyday commands: init, clone, status, add, commit, log, diff, branch, switch, merge, fetch, pull, push, restore, reset, revert, stash and tag.

Try it yourself

Here's a small practice idea: make a new folder, run git init, and create three commits that each add or change a file. Then create a branch called feature/greeting, change the same line of a file on both main and feature/greeting, and merge them to cause a conflict on purpose. Resolve it, finish the merge and tag the result v1.0.0 with an annotated tag. Finally, create an empty repository on GitHub, add it as origin, and push your branch and your tag.

For a bonus experiment, run git log --oneline --graph --decorate --all to see your history as a picture. Then look inside .git: run cat .git/HEAD, cat .git/refs/heads/main and git cat-file -p HEAD, and match what you see to the diagrams in this post. If you ever get stuck on a command, git help <command> (for example, git help merge) opens its full manual.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

JUnit 5 Explained: Unit Testing, TDD and Annotations

Mayur Bodhare — Thu, 22 Oct 2026 07:01:53 +0000

The first time a bug reached production because of a change I made, I was told the same thing three times: "Did you test it?" I had. I had run the program, clicked around and it looked fine. But "it looked fine when I tried it" is not a test. It's a hope.

Unit tests turn that hope into a safety net. They're small programs that check your code for you, in milliseconds, every time you change something. In Java, the most popular tool for writing them is JUnit.

In this post, we'll look at how testing used to work, what unit testing and TDD are, how JUnit 5 differs from JUnit 4, how JUnit 5 is built, how to set it up with Maven and Surefire, and then the main assertions and annotations you'll use every day.

A quick version note: JUnit's newest major version is JUnit 6 (released in September 2025). It needs Java 17, and the Jupiter API you learn here carries over to it. I'm using JUnit 5 because it still runs on older Java versions and is everywhere in existing projects. To try JUnit 6, you mostly change the version number.

Testing in the traditional SDLC
Unit testing
Test-driven development (TDD)
JUnit 4 vs JUnit 5
JUnit 5 architecture
JUnit 5 in a Maven project
Your first JUnit 5 test
Assertions
- assertEquals and assertNotEquals
- assertTrue and assertFalse
- assertNull, assertNotNull, assertSame, assertNotSame
- assertArrayEquals and assertIterableEquals
- assertThrows and assertDoesNotThrow
- assertAll
- assertTimeout
- fail()
- Failure messages
- Assumptions
Annotations
- @Test, @DisplayName and @Disabled
- @BeforeEach, @AfterEach, @BeforeAll and @AfterAll
Test instance lifecycle (@TestInstance)
More features worth knowing
Which one should I use?
Common mistakes
Quick recap
Try it yourself

Testing in the traditional SDLC

SDLC stands for Software Development Life Cycle: the steps a team follows to build software. In the traditional style, often called the waterfall model, each step happens after the previous one is finished:

   Requirements --> Design --> Coding --> TESTING --> Release --> Maintenance
                                            ^
                         a separate testing (QA) team starts here,
                         only after ALL the code is "done"

Developers write all the code. Then they hand it over to a separate testing team, who run it, find problems and send them back. It's sometimes called "throwing the code over the wall."

This has real problems:

Feedback comes late. A bug written in week 2 might be found in week 12. By then, the developer has forgotten the details of that code.
Fixes are expensive. The later a bug is found, the more code is built on top of it, and the more places need to change.
Handoffs cause friction. Developers wait for test results. Testers wait for builds. Each side may blame the other.
Repeat work is manual. After every fix, someone must re-test the old features by hand to make sure nothing broke. This is called regression testing, and by hand it's slow and boring.

Today, most teams work differently. Developers test their own code as they write it, with automated tests that run on every change. A dedicated QA role still matters (for exploring the product, checking the whole system and thinking like a user), but it no longer carries the whole burden, and it doesn't wait until the end.

   MODERN:   write code + write tests --> run tests automatically on every commit
                  |                                  |
                  +---- fast feedback, within minutes ----+

Unit testing

A unit test checks one small piece of code, usually a single method or class, in isolation. It's written by the developer, in code, and it runs automatically. A unit test answers one question: "Given this input, does this method give the output I expect?"

Why developers write them

Bugs are caught early, while the code is still fresh in your mind.
Refactoring becomes safe. You can improve the code and instantly know if you broke something.
They work as living documentation. A test shows exactly how a method is supposed to behave.
Regression testing becomes free. The whole suite runs in seconds.
They give confidence. You can change code without fear.

What makes a good unit test?

A handy memory trick is FIRST:

Fast: a test runs in milliseconds, so you can run thousands.
Independent: no test depends on another test or on the order.
Repeatable: it gives the same result every time, on any machine.
Self-validating: it passes or fails by itself, with no human checking the output.
Timely: written at the right time, ideally right alongside the code.

The Arrange-Act-Assert pattern

Most tests follow three steps:

@Test
void addsTwoNumbers() {
    Calculator calc = new Calculator();      // Arrange: set things up

    int result = calc.add(2, 3);             // Act: do the thing

    assertEquals(5, result);                 // Assert: check the result
}

The test pyramid

Unit tests aren't the only kind. A healthy project has many cheap tests at the bottom and few expensive ones at the top:

             /\
            /  \         END-TO-END tests: few, slow, test the whole app
           /----\
          /      \       INTEGRATION tests: some, test parts working together
         /--------\
        /          \     UNIT tests: many, very fast, test small pieces alone
       /____________\

This post is about the bottom layer: unit tests.

Test-driven development (TDD)

TDD flips the usual order. Instead of writing code and then tests, you write the test first, watch it fail, and only then write the code to make it pass. It follows a short loop called Red, Green, Refactor:

        +------------------------------------+
        |                                    |
        v                                    |
  1. RED      write a small test that FAILS (the code doesn't exist yet)
        |
        v
  2. GREEN    write the SIMPLEST code that makes the test pass
        |
        v
  3. REFACTOR clean up the code, tests stay green
        |
        +------------------------------------> repeat with the next small test

Let's try it. The rule we want: orders of 1000 or more get 10% off, smaller orders get no discount, and negative amounts are invalid.

Step 1 (red). Write the first test before the class exists:

class DiscountCalculatorTest {

    @Test
    void noDiscountBelow1000() {
        assertEquals(500, new DiscountCalculator().applyDiscount(500));
    }
}

It doesn't even compile yet (cannot find symbol: class DiscountCalculator). That counts as red. Now write the simplest code that passes:

public class DiscountCalculator {
    public int applyDiscount(int amount) {
        return amount;
    }
}

Green.

Step 2 (red). Add the next test:

@Test
void tenPercentOffAt1000() {
    assertEquals(900, new DiscountCalculator().applyDiscount(1000));
}

[ERROR] DiscountCalculatorTest.tenPercentOffAt1000 expected: <900> but was: <1000>

Red. Now make it pass:

public int applyDiscount(int amount) {
    if (amount >= 1000) {
        return amount - amount / 10;
    }
    return amount;
}

Green.

Step 3 (red). Negative amounts should fail:

@Test
void rejectsNegativeAmounts() {
    assertThrows(IllegalArgumentException.class,
        () -> new DiscountCalculator().applyDiscount(-1));
}

[ERROR] Expected java.lang.IllegalArgumentException to be thrown, but nothing was thrown.

Make it pass, then refactor the magic numbers into constants. After the cleanup, all three tests still pass, which proves the refactoring didn't break anything:

public class DiscountCalculator {
    private static final int THRESHOLD = 1000;
    private static final int PERCENT = 10;

    public int applyDiscount(int amount) {
        if (amount < 0) {
            throw new IllegalArgumentException("Amount cannot be negative");
        }
        if (amount >= THRESHOLD) {
            return amount - amount * PERCENT / 100;
        }
        return amount;
    }
}

[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0

TDD's benefits: you only write the code that's needed, every feature has a test from the start, and the code tends to be easier to test (and often simpler) because you thought about how it would be used first.

JUnit 4 vs JUnit 5

JUnit 4 served Java for over a decade. JUnit 5 (also called Jupiter, after the name of its new programming model) was a complete rewrite. The main reasons:

JUnit 4 was one big jar, hard to extend, and it couldn't use modern Java features.
Its extension tools (@RunWith and @Rule) were awkward, and you couldn't combine several runners.
Tools like IDEs had to depend on its internal classes.

No backward compatibility

JUnit 5 is not backward compatible with JUnit 4. It uses new packages and new annotations:

JUnit 4: org.junit.Test
JUnit 5: org.junit.jupiter.api.Test

A test class written with JUnit 4 annotations won't run on the Jupiter engine, and the other way around. They're simply different APIs.

The saving grace is the Vintage engine (we'll meet it in the architecture section). It lets the new platform run your old JUnit 4 tests, so you can migrate gradually, with old and new tests living side by side.

The same test, written both ways

JUnit 4:

import static org.junit.Assert.assertEquals;
import org.junit.Before;
import org.junit.Test;

public class CalculatorTest {
    private Calculator calc;

    @Before
    public void setUp() {
        calc = new Calculator();
    }

    @Test(expected = ArithmeticException.class)
    public void divideByZero() {
        calc.divide(1, 0);
    }
}

JUnit 5:

import static org.junit.jupiter.api.Assertions.assertThrows;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

class CalculatorTest {
    private Calculator calc;

    @BeforeEach
    void setUp() {
        calc = new Calculator();
    }

    @Test
    void divideByZero() {
        assertThrows(ArithmeticException.class, () -> calc.divide(1, 0));
    }
}

Notice that in JUnit 5, the class and methods don't need to be public. Package-private is fine.

The renamed pieces

  JUNIT 4                         JUNIT 5
  org.junit.Test                  org.junit.jupiter.api.Test
  @Before                         @BeforeEach
  @After                          @AfterEach
  @BeforeClass                    @BeforeAll
  @AfterClass                     @AfterAll
  @Ignore                         @Disabled
  @Category                       @Tag
  @RunWith / @Rule                @ExtendWith  (the extension model)
  @Test(expected = X.class)       assertThrows(X.class, ...)
  @Test(timeout = 500)            @Timeout  or  assertTimeout(...)
  Assert  (the class)             Assertions  (the class)
  assertEquals(msg, exp, act)     assertEquals(exp, act, msg)   <- message moved to the END

That last row is a classic trap. In JUnit 4, the optional failure message came first. In JUnit 5, it comes last. If you migrate carelessly, your code may still compile (when everything is a String), but behave confusingly.

What's new in JUnit 5

@DisplayName: readable names with spaces and symbols.
assertAll: check several things and see all failures at once.
assertThrows: with lambdas, replaces @Test(expected=...).
@Nested: group tests into inner classes.
@ParameterizedTest: one test, many inputs.
@RepeatedTest, @Tag, @Timeout, @TempDir.
Dynamic tests (@TestFactory): create tests at run time.
Test classes and methods can be package-private.
Dependency injection for test constructors and methods, through extensions.
A real extension model that replaces runners and rules.
It needs only Java 8 (JUnit 6 needs Java 17).

What changed in JUnit 6

Going from JUnit 5 to 6 is much gentler than going from 4 to 5. The org.junit.jupiter.api package and the annotations stay, so most JUnit 5 tests compile and run unchanged. The main changes:

Java 17 is the minimum (JUnit 5 needed only Java 8). Kotlin projects need Kotlin 2.2 or newer.
One version number for everything. In JUnit 5, the versions didn't match: Jupiter and Vintage were 5.x, but the Platform was 1.x (for example, Platform 1.14 went with Jupiter 5.14). In JUnit 6, the Platform, Jupiter and Vintage all share the same version, like 6.1.0. That makes dependency management much simpler.
Kotlin coroutine support. Kotlin tests can use suspend functions directly.
A cancellation API in the Platform, so a running test run can be stopped early.
Clean-up of old modules. junit-platform-runner and junit-platform-jfr were removed, and junit-jupiter-migrationsupport (a helper that let some JUnit 4 rules work inside Jupiter tests) is deprecated.
Standard Java rules are now followed for which fields and methods are visible or overridden.
If you use @CsvSource with complex or unusual CSV data, double-check those tests after upgrading.

To upgrade from JUnit 5, the usual steps are:

Make sure your project builds on Java 17 or newer.
Change the JUnit version to a 6.x version (a BOM makes this a one-line change).
Read the official Migration Guide on the JUnit site.
Move off anything that was removed or deprecated.
Run your tests.

JUnit 5 architecture

JUnit 5 isn't one jar. It's a set of three parts, each with its own job:

  JUnit 5  =  JUnit PLATFORM  +  JUnit JUPITER  +  JUnit VINTAGE

1. JUnit Platform

The foundation. It does two things:

It defines how test frameworks plug in, through the TestEngine API.
It provides the Launcher, which finds tests and starts them. Build tools and IDEs call this Launcher.

2. JUnit Jupiter

The new programming model (the annotations and assertions you write) and the engine that runs them. When you write @Test from org.junit.jupiter.api, you're using Jupiter. It also contains the extension model for adding custom behavior.

3. JUnit Vintage

An engine that runs old JUnit 3 and JUnit 4 tests on the new platform. It's what makes gradual migration possible.

Here's the whole picture:

    IDEs (IntelliJ IDEA, Eclipse, VS Code)       Build tools (Maven Surefire, Gradle)
                        \                               /
                         v                             v
  +-------------------------------------------------------------------------+
  |                          JUNIT PLATFORM                                  |
  |         Launcher API (finds and starts tests)  +  TestEngine API         |
  +-------------------------------------------------------------------------+
             |                       |                        |
             v                       v                        v
      JUnit Jupiter            JUnit Vintage           Third-party engines
   (JUnit 5 tests and        (runs JUnit 3/4         (Spock, Cucumber, TestNG...)
    extension model)          tests)

Why this design is smart

The IDEs and build tools talk only to the Platform's Launcher, not to any particular test framework. When IntelliJ IDEA shows green and red bars, or Maven runs your tests, they ask the Launcher to discover and run tests, and the Launcher asks each available engine to do its part. Because of this:

Adding a new test framework doesn't require changing every IDE and build tool. It just needs a new engine.
You can run JUnit 5 and JUnit 4 tests in the same project.

What happens when a test runs (behind the scenes)

  Surefire or IDE
       |
       v
  Launcher --> Jupiter engine: scans for classes with @Test methods (using reflection)
                     |
                     |  for EACH test method:
                     |     1. create a NEW instance of the test class
                     |     2. run @BeforeEach methods
                     |     3. run the @Test method
                     |     4. run @AfterEach methods
                     |
                     v
             report PASS / FAIL / SKIPPED back up to the Launcher --> shown in the IDE or Maven

The extension model

In JUnit 4, you extended behavior with @RunWith (only one allowed per class) and @Rule. In Jupiter, there's one concept: the extension. You add it with @ExtendWith, and you can add many. Libraries like Mockito and Spring plug in this way. We'll write a tiny one later.

JUnit 5 in a Maven project

You need two things in your pom.xml: the JUnit dependency and a recent Surefire plugin.

<properties>
    <maven.compiler.release>17</maven.compiler.release>
    <junit.version>5.14.3</junit.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.5.0</version>
        </plugin>
    </plugins>
</build>

What each part does:

junit-jupiter is a convenient "aggregate" dependency. It brings in three libraries at once: junit-jupiter-api (what you write tests with), junit-jupiter-params (parameterized tests) and junit-jupiter-engine (what runs them).
<scope>test</scope> means the library is used only for testing, and it's not packaged into your final JAR.
Surefire is the Maven plugin that runs your unit tests during the test phase. JUnit 5 needs Surefire version 2.22.0 or newer, and I pin a recent one so builds are repeatable.
To use JUnit 6 instead, change junit.version to a 6.x version and make sure you use Java 17 or newer.
To keep running old JUnit 4 tests, add junit-vintage-engine as another test dependency.

How Surefire finds your tests

Test code goes in src/test/java.
By default, Surefire runs classes named *Test, Test*, *Tests or *TestCase.
When Surefire sees the Jupiter engine on the test classpath, it switches to its JUnit Platform provider, which uses the Launcher from the architecture section.

Run your tests:

mvn test

You can run a single class or method:

mvn test -Dtest=CalculatorTest
mvn test -Dtest=CalculatorTest#addsTwoNumbers

A trimmed result looks like this (numbers and times will differ):

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.CalculatorTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Detailed reports are saved in target/surefire-reports. Note the difference between two counts: a Failure means an assertion didn't hold, and an Error means an unexpected exception happened.

(Surefire runs unit tests. For slower integration tests, Maven teams usually use the Failsafe plugin, with files named *IT.)

A quick note for Gradle users

In Gradle, add the same dependency under testImplementation, and turn on JUnit Platform in the test task:

tasks.test {
    useJUnitPlatform()
}

Your first JUnit 5 test

Here's the class we'll test throughout the rest of the post:

package com.example;

public class Calculator {

    public int add(int a, int b) {
        return a + b;
    }

    public int divide(int a, int b) {
        return a / b;
    }

    public boolean isEven(int n) {
        return n % 2 == 0;
    }
}

And its test, in src/test/java/com/example/CalculatorTest.java:

package com.example;

import static org.junit.jupiter.api.Assertions.*;

import org.junit.jupiter.api.Test;

class CalculatorTest {

    private final Calculator calc = new Calculator();

    @Test
    void addsTwoNumbers() {
        assertEquals(5, calc.add(2, 3));
    }
}

Three things to notice:

@Test marks a method as a test.
The import static ...Assertions.* line lets us write assertEquals(...) without the class name.
The class and method are package-private. No public needed.

When a test fails, the report tells you exactly what happened. If we wrote assertEquals(6, calc.add(2, 3)):

[ERROR] Failures:
[ERROR]   CalculatorTest.addsTwoNumbers:15 expected: <6> but was: <5>
[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0

Assertions

An assertion is a check inside a test. If it holds, the test continues. If it doesn't, the test fails right there.

In JUnit 5, all the assertions are static methods of one class: org.junit.jupiter.api.Assertions. (Careful: in JUnit 4, the class was called Assert, singular. In JUnit 5 it's Assertions, plural.)

assertEquals and assertNotEquals

assertEquals(expected, actual) passes when the two values are equal. Always put the expected value first, because the failure message uses that order.

@Test
void equalityChecks() {
    assertEquals(5, calc.add(2, 3));
    assertNotEquals(4, calc.add(2, 3));
    assertEquals("Java", "Ja" + "va");
}

For double and float, you must give a tolerance (called a delta), because of rounding errors:

@Test
void doublesNeedADelta() {
    assertEquals(0.3, 0.1 + 0.2, 0.0001);   // passes
    assertEquals(0.3, 0.1 + 0.2);           // FAILS
}

expected: <0.3> but was: <0.30000000000000004>

0.1 + 0.2 isn't exactly 0.3 in floating-point math. The delta says "close enough is fine."

For objects, assertEquals uses the object's .equals() method.

assertTrue and assertFalse

@Test
void booleanChecks() {
    assertTrue(calc.isEven(4));
    assertFalse(calc.isEven(7));
}

Use these when the thing you're checking is naturally a yes/no. If you're comparing two values, prefer assertEquals, because its failure message shows both values.

assertNull, assertNotNull, assertSame, assertNotSame

@Test
void nullAndSameChecks() {
    Map<String, String> map = new HashMap<>();
    assertNull(map.get("missing"));

    map.put("k", "v");
    assertNotNull(map.get("k"));

    String a = new String("hi");
    String b = new String("hi");
    assertEquals(a, b);        // same text
    assertNotSame(a, b);       // but two different objects

    String c = a;
    assertSame(a, c);          // exactly the same object
}

assertEquals asks "are they equal?" (like .equals()). assertSame asks "are they the very same object?" (like ==).

assertArrayEquals and assertIterableEquals

Arrays don't override equals, so assertEquals compares their references, not their contents. Use assertArrayEquals:

@Test
void arrayChecks() {
    int[] expected = {1, 2, 3};
    int[] actual = {1, 2, 3};

    assertArrayEquals(expected, actual);     // passes: compares the contents
    assertEquals(expected, actual);          // FAILS: two different array objects
}

expected: <[I@6d06d69c> but was: <[I@7852e922>

For collections, assertIterableEquals compares the items one by one, in order, even if the two lists are different types:

assertIterableEquals(List.of(1, 2, 3), new ArrayList<>(List.of(1, 2, 3)));

There's also assertLinesMatch for comparing lists of text lines.

assertThrows and assertDoesNotThrow

assertThrows checks that some code throws a specific exception. It takes the exception class and a lambda (the code to run). It also returns the exception, so you can inspect it:

@Test
void divisionByZeroThrows() {
    ArithmeticException ex = assertThrows(
        ArithmeticException.class,
        () -> calc.divide(10, 0));

    assertEquals("/ by zero", ex.getMessage());
}

This is the replacement for JUnit 4's @Test(expected = ...), and it's better, because it checks that exactly this line throws, not just any line in the method.

Related methods:

assertThrowsExactly(X.class, ...) requires the exact type. (assertThrows also accepts a subclass.)
assertDoesNotThrow(() -> calc.divide(10, 2)) checks that nothing is thrown.

assertAll

Normally, the first failed assertion stops the test, so you only see one problem at a time. assertAll runs a group of checks and reports all the failures together:

@Test
void groupedChecks() {
    String name = "Asha Rao";

    assertAll("name checks",
        () -> assertTrue(name.startsWith("Ravi")),
        () -> assertTrue(name.endsWith("Sharma")),
        () -> assertEquals(8, name.length())
    );
}

org.opentest4j.MultipleFailuresError: name checks (2 failures)
   org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
   org.opentest4j.AssertionFailedError: expected: <true> but was: <false>

Two checks failed, and both were reported in a single run. It's useful when checking several fields of one object.

assertTimeout

Checks that code finishes within a time limit:

@Test
void finishesQuickly() {
    assertTimeout(Duration.ofMillis(500), () -> Thread.sleep(100));
}

assertTimeout waits for the code to finish, then fails if it took too long.
assertTimeoutPreemptively runs the code in another thread and stops it as soon as the time is up. Use it with care, because things tied to the original thread (like some transactions) may not work.

You can also put @Timeout on a test method (see the annotations part).

fail()

fail() makes a test fail on purpose. It's handy for:

a placeholder for a test you haven't written yet,
a line that should never be reached.

@Test
void notWrittenYet() {
    fail("TODO: write this test");
}

org.opentest4j.AssertionFailedError: TODO: write this test

Failure messages

Every assertion accepts an optional message as the last argument:

assertEquals(5, calc.add(2, 2), "adding 2 and 2");

adding 2 and 2 ==> expected: <5> but was: <4>

If building the message is expensive, pass a lambda. It's only evaluated when the assertion fails:

assertTrue(calc.isEven(3), () -> "Expected an even number but got " + 3);

Assumptions

Assumptions are different from assertions. If an assumption is false, the test is aborted (skipped), not failed. Use them when a test only makes sense in certain conditions:

import static org.junit.jupiter.api.Assumptions.assumeTrue;

@Test
void onlyOnCiServer() {
    assumeTrue("CI".equals(System.getenv("ENV")), "Runs only on the CI server");
    // the rest of the test runs only if the assumption holds
}

In the Surefire summary, this shows up as Skipped.

Annotations

Annotations tell JUnit what each method is for. Here are the core ones in one place:

@Test: this method is a test.
@DisplayName: a readable name for the test.
@Disabled: skip this test.
@BeforeEach: run before each test.
@AfterEach: run after each test.
@BeforeAll: run once before all the tests in the class.
@AfterAll: run once after all the tests in the class.
@TestInstance: control how test class objects are created.

@test, @DisplayName and @Disabled

class CalculatorTest {

    private final Calculator calc = new Calculator();

    @Test
    @DisplayName("2 + 3 = 5")
    void addsTwoNumbers() {
        assertEquals(5, calc.add(2, 3));
    }

    @Test
    @Disabled("Bug #123: not fixed yet")
    void brokenForNow() {
        fail("Should not run");
    }
}

@DisplayName shows a friendly name in IDEs and reports, with spaces and symbols if you like.
@Disabled skips the test. Always give a reason, so nobody forgets why it's off. It appears as Skipped.

@BeforeEach, @AfterEach, @BeforeAll and @AfterAll

These are lifecycle methods: they run at set moments around your tests. Use them for setup and cleanup. Let's print messages to see the order:

class LifecycleTest {

    @BeforeAll
    static void beforeAll() {
        System.out.println("beforeAll");
    }

    @BeforeEach
    void beforeEach() {
        System.out.println("  beforeEach");
    }

    @Test
    void testA() {
        System.out.println("    testA");
    }

    @Test
    void testB() {
        System.out.println("    testB");
    }

    @AfterEach
    void afterEach() {
        System.out.println("  afterEach");
    }

    @AfterAll
    static void afterAll() {
        System.out.println("afterAll");
    }
}

Output (testA and testB may swap places):

beforeAll
  beforeEach
    testA
  afterEach
  beforeEach
    testB
  afterEach
afterAll

Here is the timeline:

  @BeforeAll                    <- once, at the start
     @BeforeEach  testA  @AfterEach
     @BeforeEach  testB  @AfterEach
  @AfterAll                     <- once, at the end

The rules:

@BeforeEach and @AfterEach run around every test. They're the right place to create fresh objects (like a new Calculator) so tests don't affect each other.
@BeforeAll and @AfterAll run once per class. They're for expensive setup, such as starting a test database.
By default, @BeforeAll and @AfterAll methods must be static. If they aren't, you get:

JUnit Jupiter @BeforeAll method 'beforeAll' must be static unless the test class is annotated with @TestInstance(Lifecycle.PER_CLASS).

That error message points to our next topic.

Test instance lifecycle (@TestInstance)

By default, JUnit creates a brand-new object of your test class for every single test method. This is the default setting, called PER_METHOD. It exists so that tests can't affect each other through fields. Watch:

class PerMethodTest {

    int counter = 0;

    @Test
    void first() {
        counter++;
        System.out.println("counter = " + counter);
    }

    @Test
    void second() {
        counter++;
        System.out.println("counter = " + counter);
    }
}

Output:

counter = 1
counter = 1

Both tests print 1, because each test got its own fresh object with counter starting at 0.

You can change this with @TestInstance, which takes one of two options from the TestInstance.Lifecycle enum:

PER_METHOD (the default): a new instance for each test method.
PER_CLASS: one instance shared by all the test methods in the class.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class PerClassTest {

    int counter = 0;

    @Test
    void first() {
        counter++;
        System.out.println("counter = " + counter);
    }

    @Test
    void second() {
        counter++;
        System.out.println("counter = " + counter);
    }
}

Output (the order of the two tests can change, but the counts keep rising):

counter = 1
counter = 2

Now the one object is shared, so counter carries over. Here are the two modes side by side:

  PER_METHOD (default)                       PER_CLASS

  @BeforeAll (static)                        @BeforeAll (can be non-static)
    new instance #1 -> testA                   ONE instance -> testA
    new instance #2 -> testB                                 -> testB
  @AfterAll (static)                         @AfterAll (can be non-static)

When should you use PER_CLASS?

When you want @BeforeAll and @AfterAll to be non-static, so they can use instance fields.
When you have expensive setup you want to share, and you accept the risk of shared state.
When you want to write ordered or dependent steps (though independent tests are usually better).

The cost is that tests can now affect each other through the shared fields, so the independent rule of FIRST is easier to break. If you use it, reset the state in @BeforeEach.

More features worth knowing

Parameterized tests

Instead of copying a test with different inputs, write it once and feed it many values. (It uses the junit-jupiter-params library, which is included in junit-jupiter.)

@ParameterizedTest
@ValueSource(ints = {2, 4, 6, 8})
void evenNumbersAreEven(int n) {
    assertTrue(calc.isEven(n));
}

@ParameterizedTest
@CsvSource({"1, 2, 3", "5, 5, 10", "-1, 1, 0"})
void addsManyPairs(int a, int b, int expected) {
    assertEquals(expected, calc.add(a, b));
}

The first test runs 4 times, and the second 3 times. Each run is reported separately, so you see exactly which input failed. You can also use @MethodSource to feed data from a method.

Nested tests

@Nested lets you group tests into inner classes, which is nice for describing different situations:

class ListTest {

    List<String> list;

    @Nested
    class WhenEmpty {
        @BeforeEach
        void setUp() {
            list = new ArrayList<>();
        }

        @Test
        void isEmpty() {
            assertTrue(list.isEmpty());
        }
    }

    @Nested
    class WhenNotEmpty {
        @BeforeEach
        void setUp() {
            list = new ArrayList<>(List.of("a"));
        }

        @Test
        void hasOneItem() {
            assertEquals(1, list.size());
        }
    }
}

Repeated tests, tags, timeouts and ordering

@RepeatedTest(3) runs the same test three times.
@Tag("slow") labels a test. With Maven, you can include or exclude by tag: mvn test -Dgroups=slow or -DexcludedGroups=slow.
@Timeout(2) fails the test if it runs longer than 2 seconds (the default unit is seconds).
@TempDir gives your test a temporary folder that is deleted afterwards.
@TestMethodOrder with @Order sets the order of test methods. Don't rely on order in normal tests. It's meant for special cases.
Conditional tests like @EnabledOnOs(OS.LINUX) or @EnabledIfEnvironmentVariable run a test only in some environments.

Extensions

An extension is a class that hooks into the test lifecycle. Here's a tiny one that logs when each test starts and ends:

import org.junit.jupiter.api.extension.*;

class LoggingExtension implements BeforeEachCallback, AfterEachCallback {

    @Override
    public void beforeEach(ExtensionContext context) {
        System.out.println("START " + context.getDisplayName());
    }

    @Override
    public void afterEach(ExtensionContext context) {
        System.out.println("END   " + context.getDisplayName());
    }
}

@ExtendWith(LoggingExtension.class)
class ExtensionDemoTest {

    @Test
    void works() {
        System.out.println("  running");
    }
}

Output:

START works()
  running
END   works()

Real libraries use the same mechanism. For example, @ExtendWith(MockitoExtension.class) sets up mock objects for you. And you can add as many extensions as you like.

Which one should I use?

JUnit 4 or JUnit 5? For new projects, use JUnit 5 (or JUnit 6 if you're on Java 17 or newer). Keep JUnit 4 only for old code, and run it through the Vintage engine while you migrate.
assertThrows or try/catch? Always assertThrows. It's shorter, and it fails if nothing is thrown.
assertEquals or assertTrue(a.equals(b))? assertEquals. On failure, it shows both values.
@BeforeEach or a field initializer? Either works for simple setup. Use @BeforeEach when setup needs several steps. Use final fields for simple, unchanging objects.
PER_METHOD or PER_CLASS? Stay with the default PER_METHOD for independent tests. Use PER_CLASS only when you need non-static @BeforeAll or expensive shared setup.
One test with a loop, or @ParameterizedTest? Parameterized. Each input is reported on its own.
JUnit's assertions or a fluent library? JUnit's built-in assertions are enough to start. Libraries like AssertJ and Hamcrest read more naturally for complex checks (JUnit 5 has no built-in assertThat).
Real dependencies or mocks? A unit test should be isolated. When your class talks to a database or a web service, replace it with a mock (a fake). Mockito is the common tool, and it plugs into JUnit 5 as an extension.

Common mistakes

Mixing JUnit 4 and JUnit 5 imports. If you import org.junit.Test (JUnit 4) but only the Jupiter engine is present, your test is never discovered, and it silently doesn't run. Check that your imports start with org.junit.jupiter.api.
Getting the argument order wrong. It's assertEquals(expected, actual), and the message comes last in JUnit 5. Swapping the first two gives misleading failure messages ("expected 5 but was 4" when it's the other way round).
Comparing arrays or doubles the wrong way. assertEquals on arrays compares references, so use assertArrayEquals. And double values need a delta.
Letting tests depend on each other. Tests that share state, or only work in a certain order, will fail randomly. Keep each test independent, and be careful with PER_CLASS.
Tests that never run. The causes are an old Surefire (older than 2.22.0 can't find JUnit 5 tests), a class name that doesn't match *Test, or tests placed outside src/test/java. If Maven says "No tests to run," check these.
Tests that can't fail. A test with no assertion always passes, which gives false comfort. And a try/catch inside a test can swallow the very exception you meant to catch. Use assertThrows, and make sure every test asserts something.

Quick recap

In the traditional SDLC, a separate team tested after coding was done, so bugs were found late and fixes were costly. Now developers write automated tests as they go.
A unit test checks one small piece of code in isolation. Good tests are FIRST: fast, independent, repeatable, self-validating and timely. Use the Arrange-Act-Assert pattern.
TDD is Red, Green, Refactor: write a failing test, write the simplest code to pass it, then clean up.
JUnit 5 is a rewrite and not backward compatible with JUnit 4: new package org.junit.jupiter.api, new annotations.
Architecture: Platform (the Launcher and TestEngine API that IDEs and build tools use) + Jupiter (the new tests and extension model) + Vintage (runs JUnit 3 and 4 tests).
With Maven: add junit-jupiter in test scope, and use Surefire 2.22.0 or newer. Run mvn test.
Assertions live in Assertions: assertEquals, assertNotEquals, assertTrue, assertFalse, assertNull, assertNotNull, assertSame, assertArrayEquals, assertIterableEquals, assertThrows, assertDoesNotThrow, assertAll, assertTimeout and fail(). The message goes last.
Annotations: @Test, @DisplayName, @Disabled, @BeforeEach, @AfterEach, @BeforeAll, @AfterAll.
@TestInstance: PER_METHOD (default, a new object per test) or PER_CLASS (one shared object, and non-static @BeforeAll and @AfterAll).
Also useful: @ParameterizedTest, @Nested, @RepeatedTest, @Tag, @Timeout and extensions through @ExtendWith.

Try it yourself

Here's a small practice idea: build a PasswordValidator class using TDD. The rules are: at least 8 characters, at least one digit and at least one uppercase letter. Write one failing test per rule first, make each pass with the simplest code, then refactor. Use a @ParameterizedTest with @CsvSource to check many valid and invalid passwords, and assertThrows for a null password.

For a bonus experiment, copy the LifecycleTest class from this post and add @TestInstance(TestInstance.Lifecycle.PER_CLASS). Make @BeforeAll non-static, and add a counter field to prove that the instance is shared. Then run a single test with mvn test -Dtest=CalculatorTest#addsTwoNumbers.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Gradle vs Maven: Which Java Build Tool Should You Pick?

Mayur Bodhare — Wed, 21 Oct 2026 11:25:14 +0000

When I learned Maven, everything felt tidy: one pom.xml, one fixed lifecycle, one set of rules. Then I opened an Android project, and the build file looked completely different. It had no XML, and it had words like plugins, implementation and tasks.register. Someone told me, "That's Gradle. It's like Maven, but it's actually code."

That sentence is the key to understanding Gradle. It solves the same problems as Maven (compile, test, package and download libraries), but it does it in a different way: your build file is a small program, and your build is a graph of tasks.

In this post, we'll learn what Gradle is, how it works, build.gradle.kts, the gradle init command, Gradle's terms, dependencies, tasks, repositories and the build lifecycle. At the end, there's a clear Gradle vs Maven comparison to help you choose. I've drawn the important pictures in text so you can see how the pieces fit.

If you've already read about Maven, Part 1 is a quick refresher, and you can skip ahead. I'm using Gradle 9.x with the Kotlin DSL. Gradle 9 needs Java 17 or newer to run.

Part 1: Build tools and why we need them (quick refresher)

A build tool automates the steps between your source code and a finished application. You describe the steps once, and the tool repeats them the same way every time.

Every Java project goes through the same journey:

   source code        byte code          unit tests          package            build output
    (.java)    -->    (.class)    -->    (JUnit)     -->    (zip it up)  -->   .jar or .war
       |                  |                  |                   |
    you write          javac             check that         deployable
                       compiles          the code works     format

Compile: javac turns .java files into .class bytecode.
Test: unit tests check that the code works.
Package: the classes are bundled into one file. A JAR is for libraries and normal applications. A WAR is for web apps on a server like Tomcat.

Doing this by hand means downloading JAR files yourself, writing long javac commands and hoping that everyone on the team has the same setup. A build tool fixes that. The most useful part is dependency management: you say what libraries you need (name and version), and the tool downloads them, along with the libraries they need.

The three popular Java build tools are Ant (every step written by hand), Maven (XML and a fixed lifecycle) and Gradle (a script and a task graph). This post is about Gradle.

Part 2: What is Gradle?

Gradle is a build automation and dependency management tool. It builds Java, Kotlin, Android and many other kinds of projects. Instead of describing your project in XML, you write a build script in a real programming language:

Kotlin DSL: build.gradle.kts (the default for new projects)
Groovy DSL: build.gradle

(A DSL, a domain-specific language, is a language shaped for one job. It looks like configuration, but underneath it's real code.)

What does Gradle do?

The same five jobs as Maven:

Project structure. It uses the same standard folders (src/main/java and so on).
Dependencies. It downloads the libraries you list, and what they need.
Unit tests. It runs your tests (for example, with JUnit).
Compile. It compiles your code.
Package. It builds a JAR (or a WAR, with the right plugin).

It can also run your application, create distribution files and publish your library to a repository.

How does Gradle do it?

Gradle is built on three ideas:

1. Everything is a task. A task is one unit of work: compileJava, test, jar. Gradle's tasks can depend on other tasks. When you ask for one task, Gradle works out which other tasks must run first, and builds a graph (a map of who depends on whom).

2. Plugins add the tasks. Gradle itself is small. When you add the java plugin, it gives your project tasks like compileJava, test and jar, plus the standard folder layout and conventions.

3. It avoids repeating work. Each task declares its inputs (like source files) and outputs (like class files). If nothing changed since the last run, Gradle skips the task and marks it UP-TO-DATE. It also keeps a background process (the Gradle daemon) alive between builds so each build starts quickly.

When you run a build, Gradle goes through three phases:

   ./gradlew build
        |
        v
   1. INITIALIZATION   Find settings.gradle.kts. Decide which projects are part of the build.
        |
        v
   2. CONFIGURATION    Read the build scripts. Create the tasks. Build the task graph.
        |
        v
   3. EXECUTION        Run only the tasks that are needed, in dependency order.
                       Skip any that are UP-TO-DATE.

The Gradle Wrapper

Gradle projects almost always include a small helper called the wrapper: the files gradlew (Linux and macOS) and gradlew.bat (Windows). Instead of installing Gradle yourself, you run ./gradlew. The first time, it downloads the exact Gradle version the project needs. This means every developer and every build server uses the same version. Commit the wrapper files to your repository.

./gradlew --version

You'll see the Gradle version and the Java version it uses. Make sure the Java version is 17 or newer for Gradle 9.

The standard project structure

Gradle uses the same folder conventions as Maven:

   my-app/
   |-- settings.gradle.kts          <- project name, and which sub-projects exist
   |-- build.gradle.kts             <- the build script
   |-- gradlew, gradlew.bat         <- the wrapper scripts
   |-- gradle/wrapper/              <- wrapper files (commit these)
   |-- src/
   |    |-- main/
   |    |    |-- java/              <- your application code
   |    |    +-- resources/         <- config files, images
   |    +-- test/
   |         |-- java/              <- your unit tests
   |         +-- resources/
   +-- build/                       <- created by Gradle: all build output

src/main is code that ships. src/test is code that only checks it. build/ is the output folder (the same idea as Maven's target/), and you can delete it any time.

(When you create a project with gradle init, the code usually goes inside an app/ folder, which is a sub-project, with its own build.gradle.kts. The layout inside it is the same.)

The build script: build.gradle.kts

Two small files describe a project. First, settings.gradle.kts gives it a name:

rootProject.name = "my-app"

Then build.gradle.kts describes how to build it:

plugins {
    java
    application
}

group = "com.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:5.11.0"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.withType<JavaCompile> {
    options.release = 17
}

application {
    mainClass = "com.example.App"
}

tasks.test {
    useJUnitPlatform()
}

Here's what each part means:

plugins { ... }: which plugins to apply. java adds compile, test and jar tasks. application adds the ability to run your program (a run task).
group and version: the project's coordinates. The name comes from rootProject.name.
repositories { ... }: where to download libraries from. mavenCentral() is the big public repository. You must declare it, because Gradle doesn't assume any repository.
dependencies { ... }: your libraries. The word before the brackets (like testImplementation) says when the library is needed. The platform(...) line imports a BOM (a list of matching versions), so the other JUnit lines don't need version numbers.
options.release = 17: the Java version to compile for. Set it to your JDK version, like 17 or 21.
application { mainClass }: which class has main.
tasks.test { useJUnitPlatform() }: tells the test task to use JUnit 5. Without this line, JUnit 5 tests don't run.

The junit-platform-launcher line is needed with Gradle 9 so that tests can start.

The same thing in Groovy

If you see build.gradle (no .kts), it's the Groovy version. It looks a bit lighter, with fewer brackets and quotes:

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter:5.11.0'
}

Both do the same job. Kotlin DSL is the default for new projects, because IDEs can autocomplete it and show errors as you type.

Behind the scenes: the script is code

When Gradle runs build.gradle.kts, it compiles and runs it like a program. Lines like dependencies { ... } are real function calls, and the block in curly braces is code. That's why you can use variables, if statements and loops in a build script, which isn't possible in a plain XML file. It's powerful, but it also means a build script can become complicated if you aren't careful.

Creating a project: gradle init

Maven has archetype:generate. Gradle has gradle init. Here's the full command:

gradle init \
  --type java-application \
  --dsl kotlin \
  --test-framework junit-jupiter \
  --package com.example \
  --project-name my-app \
  --java-version 17

(On Windows Command Prompt, write it on one line without the \ characters.)

Let's break it down:

gradle init: runs the built-in init task, which creates a new project.
--type java-application: the kind of project. java-application is a command-line app. Other choices include java-library, kotlin-application, groovy-application and more.
--dsl kotlin: which language to write the build scripts in (kotlin or groovy).
--test-framework junit-jupiter: which test library to set up. junit-jupiter means JUnit 5. Others include junit (JUnit 4), testng and spock.
--package com.example: the Java package for the sample classes.
--project-name my-app: the name of the project. It defaults to the folder name.
--java-version 17: the Java version to use in the project.

If you run plain gradle init with no options, Gradle asks you questions one by one (type, language, DSL, test framework), so it works interactively too. To see every option, run gradle help --task init.

The result is a working project with a sample App.java, a sample test, the build scripts and the wrapper files. A handy extra: if you run gradle init inside an existing Maven project, Gradle can convert the pom.xml into Gradle build files for you.

Note that gradle init needs Gradle installed once. After that, the generated project carries its own wrapper, so everyone else just uses ./gradlew.

Gradle terminology

Gradle's words are a little different from Maven's. Here they are side by side.

Project, plugin and task

A project is something Gradle builds. A big build can have a root project and several sub-projects (modules).
A plugin adds tasks, folders and conventions to a project (java, application, war).
A task is one unit of work (compileJava, test, jar).

Coordinates: group, name, version

Gradle uses the same coordinate system as Maven, so both tools can share libraries:

   com.google.code.gson : gson : 2.11.0
        group              name     version      (Maven calls the middle part "artifactId")

group: who it belongs to, usually a reversed domain: com.example.
name: the project name from rootProject.name.
version: the version, like 1.0-SNAPSHOT.

Version: SNAPSHOT vs release

The same convention applies: a version ending in -SNAPSHOT means work in progress, and a version without it (like 1.0.0) is a finished release that should never change once published.

Gradle also allows "dynamic" versions like 2.+ or latest.release, which pick whatever is newest. Avoid them, because your build can change without you touching it.

Packaging: there's no `<packaging>` tag

Maven has a packaging setting (jar, war). Gradle doesn't. Instead, the plugin decides what gets built:

the java plugin gives you a jar task
the war plugin gives you a war task, for web applications
the application plugin adds run, plus tasks to build a runnable ZIP or TAR of your app
the maven-publish plugin adds the tasks to publish your result

Templates: archetype vs init type

Maven's archetype is a project template. In Gradle, the same idea is the --type option of gradle init.

Gradle dependencies

A dependency is declared inside dependencies { }, using the format "group:name:version":

dependencies {
    implementation("com.google.code.gson:gson:2.11.0")
}

Compare that to Maven, where the same dependency takes six lines of XML. Now you can use it right away:

import com.google.gson.Gson;
import java.util.Map;

public class App {
    public static void main(String[] args) {
        Gson gson = new Gson();
        System.out.println(gson.toJson(Map.of("name", "Asha")));
    }
}

Output:

{"name":"Asha"}

Configurations: when is the dependency needed?

In Maven, you use a scope. In Gradle, the word before the brackets is called a configuration. The common ones:

implementation: needed to compile and run your code. It's packaged with your app. This is the default choice.
api: like implementation, but also shows the library to anyone who uses your library. It's available only with the java-library plugin.
compileOnly: needed to compile, but not packaged (the server provides it at run time).
runtimeOnly: not needed to compile, but needed when running (like a database driver).
testImplementation and testRuntimeOnly: only for tests, like JUnit.
annotationProcessor: for tools that run during compilation.

(Older Gradle versions used compile and testCompile. They were removed. If you see them in an old tutorial, use implementation and testImplementation instead.)

Transitive dependencies and version conflicts

As in Maven, if you add library A, and A needs B, Gradle fetches B too. See the whole tree with:

./gradlew dependencies

To find out why a specific library is there, use:

./gradlew dependencyInsight --dependency gson

When two libraries need different versions of the same third library, Gradle's default is simple: the highest version wins. (Maven picks the version nearest to your project. This is a real difference, and it's covered in the comparison below.)

   my-app
     |-- lib-a 1.0
     |      +-- lib-b 2.0
     +-- lib-c 1.0
            +-- lib-b 1.5

   Gradle picks lib-b 2.0, the highest.
   Maven would pick lib-b 2.0 here too, but only because lib-a was declared first.

For larger projects, many teams keep all versions in one file, gradle/libs.versions.toml, called a version catalog. Then every module refers to a library by a short name, and the versions are in one place.

Gradle tasks

A task is a named piece of work. When you apply the java plugin, you get a family of tasks:

clean: deletes the build folder.
compileJava: compiles the main code.
processResources: copies the files from src/main/resources.
classes: a grouping task that means "main code is compiled and ready."
compileTestJava: compiles the test code.
test: runs the unit tests.
jar: bundles the classes into a JAR.
assemble: builds all the outputs (like the JAR), without running tests.
check: runs all the verification (like the tests).
build: does both assemble and check.

With the application plugin, you also get run (starts your program). And with maven-publish, you get publishToMavenLocal and publish.

The commands you'll use most:

./gradlew clean: delete old output.
./gradlew compileJava: compile only.
./gradlew test: compile and run the tests.
./gradlew build: compile, test and package.
./gradlew run: run the application.
./gradlew tasks: list all available tasks (add --all to see more).

(On Windows, use gradlew.bat instead of ./gradlew.)

Here is a trimmed ./gradlew build:

> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
> Task :assemble
> Task :compileTestJava
> Task :processTestResources NO-SOURCE
> Task :testClasses
> Task :test
> Task :check
> Task :build

BUILD SUCCESSFUL in 2s

Each > Task line is one task running, in dependency order. Now run it again without changing anything:

> Task :compileJava UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :assemble UP-TO-DATE
> Task :compileTestJava UP-TO-DATE
> Task :test UP-TO-DATE
> Task :check UP-TO-DATE
> Task :build UP-TO-DATE

BUILD SUCCESSFUL in 400ms

Gradle noticed that nothing changed, so it skipped the work. That's the "avoid repeating work" idea in action. NO-SOURCE means the task had no input files, such as an empty resources folder.

The task graph behind `build`

Gradle doesn't run a fixed list of steps. It works backwards from the task you ask for and builds a graph:

   build
    |-- assemble
    |     +-- jar
    |          +-- classes
    |               |-- compileJava
    |               +-- processResources
    +-- check
          +-- test
               |-- classes                     (same tasks, run only once)
               +-- testClasses
                     |-- compileTestJava
                     +-- processTestResources

When you ask for test, Gradle runs only compileJava, processResources, classes, compileTestJava, processTestResources, testClasses and test. It doesn't build the JAR, because test doesn't need it.

Testing with JUnit

Create src/main/java/com/example/Calculator.java:

package com.example;

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}

And src/test/java/com/example/CalculatorTest.java:

package com.example;

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;

class CalculatorTest {
    @Test
    void addsTwoNumbers() {
        assertEquals(5, new Calculator().add(2, 3));
    }
}

./gradlew test

BUILD SUCCESSFUL in 2s

Gradle is quiet when everything passes. Now break the test on purpose by changing 5 to 6:

CalculatorTest > addsTwoNumbers() FAILED
    org.opentest4j.AssertionFailedError at CalculatorTest.java:9

1 test completed, 1 failed

> Task :test FAILED
BUILD FAILED in 1s

The build fails, and the report is saved in build/reports/tests/test/index.html.

Here's a difference from Maven worth noticing. In Maven, a failing test stops the lifecycle before package, so no JAR is built. In Gradle, the jar task doesn't depend on test, so with ./gradlew build the JAR may already exist even though the build failed. The overall result is still BUILD FAILED, so don't ship it. If you publish a library, make sure the publishing task only runs after check has passed.

Running your application and your JAR

With the application plugin, running is one command:

./gradlew run

Hello World!

(This is the output of the sample App from gradle init. Yours prints whatever your main method prints.)

The JAR from the jar task doesn't say which class has main, so this fails:

java -jar build/libs/my-app-1.0-SNAPSHOT.jar

no main manifest attribute, in build/libs/my-app-1.0-SNAPSHOT.jar

You can fix that by adding the main class to the manifest:

tasks.jar {
    manifest {
        attributes["Main-Class"] = "com.example.App"
    }
}

If your app uses outside libraries, you need a "fat JAR" that bundles them. The popular Shadow plugin does that. Alternatively, the application plugin's installDist task creates a folder with your JAR, its libraries and a start script in build/install/.

Gradle repositories

A repository is a storage place for libraries, organized by coordinates. Gradle uses the same repositories as Maven, so everything on Maven Central works. You list them in the repositories { } block, and Gradle searches them in the order you wrote them:

repositories {
    mavenCentral()
    maven {
        url = uri("https://repo.mycompany.com/maven")
    }
}

The common ones:

mavenCentral(): the huge public repository on the internet. This is where most open-source libraries live.
maven { url = ... }: any other Maven-style server, such as your company's private repository.
google(): Google's repository, used mostly for Android.
mavenLocal(): the ~/.m2/repository folder that Maven uses. Use it only when you really must, because it can make builds depend on what's on your machine.

Gradle also keeps its own cache of downloaded libraries, in ~/.gradle/caches. Each library is downloaded once, and later builds reuse it. That's the same idea as Maven's local repository, in a different folder.

   Need gson 2.11.0
        |
        v
   1. Gradle's cache (~/.gradle/caches) --- found? ---> use it (no internet needed)
        | not found
        v
   2. Repositories, in the order you declared them
        (company server, mavenCentral, ...)  --- found? ---> download it
        |                                                      |
        |                                                      v
        +--------------------------------------------> save it in the cache

To publish your own library, apply the maven-publish plugin. publishToMavenLocal copies it into ~/.m2 (like Maven's install), and publish uploads it to a remote repository (like Maven's deploy). You configure the target address and login in the build script.

The Gradle build lifecycle

This is where Gradle is most different from Maven, so let's be careful.

Maven has fixed lifecycles (default, clean, site), each with named phases that always run in the same order.

Gradle has no fixed phase list. It has two different ideas:

1. The three build phases (we saw these earlier): initialization, configuration and execution. They describe how Gradle runs any build, whatever tasks you ask for.

2. The task graph. The order in which tasks run comes from the dependencies between tasks. A plugin says "test needs classes," and Gradle works out the rest.

To give you the same comfort as Maven's phases, the java plugin provides a few lifecycle tasks: grouping tasks that do no work themselves, but depend on others:

   assemble   =  build everything (jar and other outputs), no tests
   check      =  run all verification (tests, and other checks)
   build      =  assemble + check

Here's how Maven's ideas map across:

   MAVEN                              GRADLE

   default lifecycle                  the task graph for the tasks you ask for
     validate                         (settings and configuration phases)
     compile                          compileJava
     test                             test
     package                          jar  (part of "assemble")
     verify                           check
     install                          publishToMavenLocal
     deploy                           publish

   clean lifecycle (mvn clean)        the "clean" task (./gradlew clean)
   site lifecycle  (mvn site)         no direct equivalent: use the "javadoc" task and report plugins

The big difference: in Maven you run a phase and everything before it runs. In Gradle you run a task and only the tasks it depends on run.

What's inside `build/` after a build?

   build/
   |-- classes/java/main/            <- compiled main code
   |-- classes/java/test/            <- compiled test code
   |-- libs/                         <- the packaged JAR
   |-- reports/tests/test/           <- the test report (open index.html)
   +-- test-results/                 <- raw test results

Gradle vs Maven: the comparison

Now the part that most people want. Both tools build Java projects, use the same repositories and the same library coordinates. The differences are in how you describe the build and how the build runs.

The build file

Maven: pom.xml, which is XML. It's declarative: you describe what the project is, not what to do. It's verbose, but predictable, and every Maven project looks alike.
Gradle: build.gradle.kts (or build.gradle), which is code. It's shorter and you can use variables and logic, but a complex script can be harder to read.

The same single dependency:

<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.11.0</version>
</dependency>

implementation("com.google.code.gson:gson:2.11.0")

The build model

Maven: a fixed lifecycle of phases. Easy to learn: run a phase, and everything before it runs.
Gradle: a graph of tasks. More flexible: you can add your own tasks, connect them anywhere and run only what's needed.

Speed

Gradle is built to skip work. It uses incremental builds (UP-TO-DATE checks), a long-running daemon, a build cache that can reuse results (even from other machines) and parallel execution. On large projects with many modules, this often makes Gradle noticeably faster, especially on repeated builds.
Maven has also gained speed features (for example, parallel builds with -T, and an optional daemon tool called mvnd), and it does the same work each time, which keeps it simple.
For a small project, you'll hardly notice a difference. The gap grows with project size. Always measure your own project instead of trusting general claims.

Flexibility vs convention

Maven strongly prefers convention. If you need something unusual, you usually write or configure a plugin, which takes effort. The benefit is that it's hard to make a build too clever.
Gradle makes custom logic easy: you can write a task right in the build script. The risk is the opposite: it's easy to make a build too clever.

Dependencies

Scopes vs configurations: Maven has a few scopes (compile, provided, runtime, test). Gradle has more fine-grained configurations (implementation, api, compileOnly, runtimeOnly, testImplementation).
api vs implementation: Gradle can hide a library's internal dependencies from the projects that use it (implementation), and this can cut compile time in big builds. Maven has no direct equivalent.
Version conflicts: Maven's default is "nearest to your project wins." Gradle's default is "highest version wins."

Maven scopes and their Gradle equivalents:

   MAVEN SCOPE           GRADLE CONFIGURATION
   compile               implementation  (or api, in a java-library)
   provided              compileOnly
   runtime               runtimeOnly
   test                  testImplementation / testRuntimeOnly

Learning curve

Maven is easier to start with and easier to predict. Most Maven builds look nearly the same, so you can read an unfamiliar project quickly.
Gradle has more concepts to learn (tasks, configurations, plugins, the DSL, the three phases). Once you know them, you can do more, but the first weeks are steeper.

Ecosystem and tooling

Both are well supported in IntelliJ IDEA, Eclipse and VS Code, and both work with Spring Boot.
Gradle is the standard build tool for Android. It's also popular in Kotlin projects.
Maven is extremely common in enterprise and older Java projects, with a vast number of ready-made plugins.
Both can use the wrapper (gradlew and mvnw) so that every machine uses the same tool version.

Command cheat sheet

   MAVEN                           GRADLE
   mvn -v                          ./gradlew --version
   mvn archetype:generate          gradle init
   mvn clean                       ./gradlew clean
   mvn compile                     ./gradlew compileJava
   mvn test                        ./gradlew test
   mvn package                     ./gradlew build   (or ./gradlew jar)
   mvn install                     ./gradlew publishToMavenLocal
   mvn deploy                      ./gradlew publish
   mvn dependency:tree             ./gradlew dependencies
   mvn package -DskipTests         ./gradlew build -x test
   mvn test -Dtest=FooTest         ./gradlew test --tests FooTest
   mvn -o                          ./gradlew --offline
   mvn -U                          ./gradlew --refresh-dependencies

   pom.xml                         build.gradle.kts + settings.gradle.kts
   target/                         build/
   ~/.m2/repository               ~/.gradle/caches

Note that ./gradlew build is the closest match to Maven's verify, because it also runs the checks. To package only, with no tests, use ./gradlew jar or ./gradlew assemble.

Which one should I use?

Starting a new Android project? Gradle. It's the standard.
Joining an existing project? Use whatever it already uses. Don't switch just because you like the other one.
Learning Java build tools for the first time? Start with Maven if you want the simplest, most predictable model. Learn Gradle next. The concepts (coordinates, repositories, dependencies, plugins) carry over almost completely.
Large multi-module project with slow builds? Gradle's incremental builds and caching can help a lot.
Need a lot of custom build logic? Gradle makes it easier.
Want every project to look the same, with few surprises? Maven.
Building with Spring Boot? Either works well. Pick the one your team knows.
Want to move from Maven to Gradle? Run gradle init inside the Maven project. It can convert the build for you. Then check the result by hand.

A sensible attitude: both are good tools, and the "right" one is usually the one your team already uses well.

Common mistakes

Running gradle instead of ./gradlew. The globally installed Gradle may be a different version from the one the project needs. Use the wrapper. On Linux and macOS, if you get "permission denied," run chmod +x gradlew.
Running Gradle on an old Java. Gradle 9 needs Java 17 or newer to run. Check ./gradlew --version and your JAVA_HOME.
Using removed configurations. compile and testCompile no longer exist. Use implementation and testImplementation.
Forgetting useJUnitPlatform(). Without it, JUnit 5 tests aren't found, and the build "passes" with no tests run. Also remember the junit-platform-launcher line for Gradle 9.
Forgetting the repositories block. If you don't declare mavenCentral(), you get "Could not resolve" errors, because Gradle assumes no default repository.
Unpredictable versions. Dynamic versions like 2.+ or latest.release, and heavy use of mavenLocal(), make builds change from day to day or machine to machine. Pin exact versions.

Quick recap

Gradle automates building Java (and other) projects: compile, test, package and dependency management.
Build scripts are code: build.gradle.kts (Kotlin) or build.gradle (Groovy), plus settings.gradle.kts.
Gradle works with tasks in a graph, added by plugins. It skips tasks that are UP-TO-DATE, and it uses a daemon and caches to stay fast.
A build has three phases: initialization, configuration and execution.
Always use the wrapper (./gradlew) so everyone uses the same Gradle version.
The standard layout is the same as Maven: src/main/java, src/test/java, with output in build/.
gradle init --type java-application ... creates a project, like Maven's archetype:generate.
Coordinates are group:name:version. There's no packaging tag: plugins decide what is built.
Dependencies use configurations: implementation, api, compileOnly, runtimeOnly, testImplementation. In conflicts, the highest version wins.
You must declare repositories, usually mavenCentral(). Gradle caches downloads in ~/.gradle/caches.
Key tasks: clean, compileJava, test, jar, assemble, check, build and run.
Compared with Maven: Gradle is code, a task graph and often faster on big builds. Maven is XML, a fixed lifecycle and simpler to predict.

Try it yourself

Here's a small practice idea: run gradle init with the command from this post, then run ./gradlew build twice and watch the second run show UP-TO-DATE. Add the Calculator class and CalculatorTest, run ./gradlew test, then break the test on purpose and read the failure report in build/reports/tests/test/index.html. Finally, add the Gson dependency, print some JSON in App, and run it with ./gradlew run.

For a bonus experiment, run ./gradlew dependencies and ./gradlew tasks --all, and see how much Gradle shows you about your own project. If you already have a Maven project, copy it, run gradle init inside the copy, and compare the generated build.gradle.kts with the original pom.xml.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Why Java Developers Use Maven (and Not javac by Hand)

Mayur Bodhare — Thu, 15 Oct 2026 10:07:20 +0000

When I wrote my first real Java project, I had a folder of .java files, a folder of JAR files I had downloaded by hand and a very long javac command that I kept in a text file. When a teammate cloned the project, it didn't compile on their machine. Their JAR versions were different, their folders were different and the command had to be changed.

That's the problem Maven solves. You describe your project in one file, and one short command builds it the same way on every machine: it downloads the libraries, compiles the code, runs the tests and packages everything into a JAR or WAR.

In this post, we'll cover what build tools are, why we need them, how Maven works, what pom.xml is, the full archetype:generate command, Maven's terms (group id, artifact id, version, packaging), dependencies, goals, repositories and the three build lifecycles. I've drawn the important pictures in text so you can see how the pieces fit.

A note about versions: I'm using Maven 3.9.x, the stable line at the time of writing. Everything here works the same in newer versions.

Part 1: Build tools and why we need them

What is a build tool?

A build tool is a program that automates the steps between your source code and a finished, runnable application. Instead of running those steps by hand, you describe them once, and the tool repeats them exactly the same way every time.

The journey of your code

Every Java project goes through the same steps:

   source code        byte code          unit tests          package            build output
    (.java)    -->    (.class)    -->    (JUnit)     -->    (zip it up)  -->   .jar or .war
       |                  |                  |                   |
    you write          javac             check that         deployable
                       compiles          the code works     format

Compile: javac turns .java files into .class bytecode.
Test: unit tests check that your code behaves correctly.
Package: the .class files and resources are bundled into one file. A JAR (Java ARchive) is for libraries and normal applications. A WAR (Web ARchive) is for web applications that run on a server like Tomcat.

Doing it by hand

Without a build tool, here's what a tiny project with one library needs:

javac -cp lib/gson-2.11.0.jar -d out src/com/example/App.java
java  -cp out:lib/gson-2.11.0.jar com.example.App
jar cf app.jar -C out .

(On Windows, the classpath separator is ; instead of :.)

That's already awkward for one library and one file. Now imagine 200 files, 30 libraries, tests and three developers. The real problems are:

Downloading libraries by hand. You have to find each JAR, pick a version and put it in a folder.
Libraries need other libraries. Library A needs B, which needs C. You'd have to find all of them yourself.
Version clashes. Two libraries need different versions of the same one. This is nicknamed "JAR hell."
"Works on my machine." Everyone's folders and versions are slightly different.
Long manual steps. Compile, test and package in the right order, every time.

Dependency management

A dependency is a library your project needs. Dependency management means the tool finds, downloads and organizes those libraries for you. You just say what you need, with a name and a version, and the tool does the rest, including the libraries that your libraries need.

   WITHOUT a build tool                        WITH Maven

   you --> search the web for gson.jar         you --> write 5 lines in pom.xml
   you --> download it, copy to lib/                    |
   you --> find the jars gson needs                     v
   you --> fix the classpath by hand           Maven --> downloads gson + what it needs
   you --> repeat for every library                     and puts them on the classpath

The popular build tools

Ant: an early tool. You write every step yourself in build.xml. Flexible, but a lot of manual work.
Maven: you follow standard conventions and describe the project in pom.xml. Dependencies are built in. This is what we're learning.
Gradle: similar goals to Maven, but build files are written in Groovy or Kotlin code instead of XML, and it's known for fast, incremental builds.

All three are used in real projects. Maven is the most common starting point, and its ideas (repositories, coordinates, lifecycles) show up everywhere.

Part 2: What is Apache Maven?

Apache Maven is a build automation and dependency management tool, mostly used for Java. Its name comes from a word meaning "accumulator of knowledge." The key idea is the POM (Project Object Model): a file called pom.xml that describes your project.

What does Maven do?

Project structure. It gives every project the same standard folder layout.
Dependencies. It downloads the libraries you list, and the ones they need.
Unit tests. It runs your tests (for example, with JUnit) automatically.
Compile. It compiles your code with the right Java settings.
Package. It builds a deployable file (JAR or WAR).

And a few more: it can install the result into your local library folder, deploy it to a shared server, and generate project reports and documentation.

How does Maven do it?

Maven works on two simple ideas:

1. Convention over configuration. If you put files in the standard places and follow the standard naming, you don't have to configure anything. Maven already knows where your code and tests are, and where to put the output.

2. Plugins do the real work. Maven itself is a small "coordinator." It reads your pom.xml, decides which steps to run in which order, and hands each step to a plugin. The compiler plugin compiles, the surefire plugin runs tests, the jar plugin builds the JAR.

Here is what happens when you type one command:

   mvn package
      |
      v
   1. Maven reads pom.xml
      |
      v
   2. Works out the lifecycle: validate -> compile -> test -> package
      |
      v
   3. For each step, runs the plugin goal attached to it
        compile  ->  compiler plugin   (javac)
        test     ->  surefire plugin   (runs JUnit tests)
        package  ->  jar plugin        (builds the .jar)
      |
      v
   4. Needs a library or plugin? Looks in the local repository,
      and downloads it from the internet if it's missing
      |
      v
   5. Puts all results in the "target" folder

Install and check

Maven needs a JDK, and the JAVA_HOME environment variable should point to it. After installing Maven, check it:

mvn -v

You'll see something like this (your numbers will differ):

Apache Maven 3.9.x
Maven home: /opt/maven
Java version: 17.0.x, vendor: ...

Look at the Java version line. Maven uses whichever JDK it finds, so make sure it's the one you intend.

The standard project structure

Every Maven project looks like this:

   my-app/
   |-- pom.xml                      <- the project description
   |-- src/
   |    |-- main/
   |    |    |-- java/              <- your application code (.java)
   |    |    +-- resources/         <- config files, images, etc.
   |    +-- test/
   |         |-- java/              <- your unit tests
   |         +-- resources/         <- files used only by tests
   +-- target/                      <- created by Maven: all build output

src/main is code that goes into your finished application.
src/test is code that only checks it. It's never packaged.
target is created by Maven. It holds the compiled classes, test reports and the JAR. You can delete it any time and nothing is lost.

Because everyone uses this layout, you can open any Maven project in the world and find your way around.

pom.xml

The POM (Project Object Model) is the heart of a Maven project. Here's a small but complete example:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>my-app</name>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.11.0</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.0</version>
      </plugin>
    </plugins>
  </build>
</project>

What each part means:

modelVersion: the version of the POM format. It's always 4.0.0.
groupId, artifactId, version: the project's identity (we'll explain them in a moment).
packaging: what kind of file to build (jar is the default).
name: a friendly name for humans.
properties: settings and variables. maven.compiler.release is the Java version to compile for (set it to your JDK version, like 17 or 21), and the encoding avoids platform surprises.
dependencies: the libraries you need.
build / plugins: extra configuration for the build. Here we pin the test plugin version, which also makes sure JUnit 5 tests are found. Pinning plugin versions makes builds repeatable.

Behind the scenes: your POM is tiny

Your pom.xml looks short because it inherits from a hidden built-in file called the Super POM. It holds all the defaults: the folder layout, the repository address and the default plugins. Maven merges the Super POM and your POM into one effective POM. You can see the full result:

mvn help:effective-pom

It's long, but it shows you everything Maven is actually using.

Creating a project: mvn archetype:generate

You can create the folders and pom.xml by hand, but Maven can generate a ready-made project from a template. That's what archetype:generate does. Here's the full command:

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=my-app \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DinteractiveMode=false

(On Windows Command Prompt, write it on one line without the \ characters.)

Let's break it down piece by piece:

mvn: runs Maven.
archetype:generate: this is plugin:goal. It means "use the archetype plugin and run its generate goal."
-D: sets a property. Each option is written as -Dname=value.
-DgroupId=com.example: the group id of your new project (usually your reversed domain or company).
-DartifactId=my-app: the name of your project. Maven also creates a folder with this name.
-DarchetypeArtifactId=maven-archetype-quickstart: which template to use. The quickstart template makes a simple Java project with a sample class and a sample test.
-DarchetypeVersion=1.5: the version of that template. Version 1.5 generates a project that uses JUnit 5. (If your Maven can't find it, remove this option, and Maven will pick a version for you.)
-DinteractiveMode=false: don't ask questions. Without it, Maven asks you for the template version, the package name and a final confirmation.

Two extra options you may see:

-Dversion=1.0-SNAPSHOT: the starting version (this is already the default).
-Dpackage=com.example.app: the Java package for the sample classes. If you skip it, it defaults to the group id.

The first run downloads the archetype and some plugins from the internet, so it takes a little while. When it finishes, you'll see BUILD SUCCESS, and this project:

   my-app/
   |-- pom.xml
   +-- src/
        |-- main/java/com/example/App.java
        +-- test/java/com/example/AppTest.java

The generated App.java is a simple "Hello World" with a main method. Open the generated pom.xml and check the Java version property. If it's older than your JDK, change maven.compiler.release to your Java version (for example 17 or 21).

Maven terminology

Archetype

An archetype is a project template. It's a pattern for creating new projects, like a "starter kit." Besides maven-archetype-quickstart, there are archetypes for web applications and more.

Maven coordinates: groupId, artifactId, version

Every project and library in the Maven world is identified by three values, called its coordinates (or GAV):

groupId: who it belongs to. Usually a reversed domain, like Java packages: com.example, org.junit.jupiter.
artifactId: the name of the project or library: my-app, gson.
version: which version: 1.0-SNAPSHOT, 2.11.0.

Together they point to exactly one thing, anywhere in the world:

   com.google.code.gson : gson : 2.11.0
        groupId          artifactId   version

The coordinates also decide where the file lives in a repository, which is just a folder path:

   com.example : my-app : 1.0-SNAPSHOT
         |
         v   dots in groupId become folders
   com/example/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar

Version: SNAPSHOT vs release

A version that ends in -SNAPSHOT (like 1.0-SNAPSHOT) means work in progress. It can change as you keep developing. Maven treats it as "may have a newer build," and can check for updates.
A version without -SNAPSHOT (like 1.0.0) is a release. It's a fixed, finished version. Once a release is published to a public repository such as Maven Central, it can never be changed or replaced.

A typical life of a version: 1.0.0-SNAPSHOT while you build it, then you publish 1.0.0 (the release), then you start 1.1.0-SNAPSHOT for the next work. A good tip is to follow a clear numbering scheme, such as major.minor.patch.

Packaging type

packaging tells Maven what to build from your project. It also decides which plugin goals run at each step of the lifecycle.

jar (the default): a library or a normal application.
war: a web application for a server like Tomcat.
pom: no code of its own. Used for parent projects that group other projects.
ear: an enterprise application (less common today).

Maven dependencies

A dependency is declared with its coordinates:

<dependencies>
  <dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.11.0</version>
  </dependency>
</dependencies>
</xml>

Save the file, and Maven downloads the library the next time you build. Now you can use it in your code right away:

import com.google.gson.Gson;
import java.util.Map;

public class App {
    public static void main(String[] args) {
        Gson gson = new Gson();
        System.out.println(gson.toJson(Map.of("name", "Asha")));
    }
}

Output:

{"name":"Asha"}

No JAR downloads and no classpath editing.

Scope: when is the dependency needed?

The <scope> tag says when a library is needed:

compile (default): needed to compile and run. It's packaged with your app.
test: only for compiling and running tests, like JUnit. Not packaged.
provided: needed to compile, but the server provides it when running (for example, the servlet API on Tomcat). Not packaged.
runtime: not needed to compile, but needed when running (for example, a database driver).

Using the right scope keeps your final package small and clean.

Transitive dependencies

Libraries often depend on other libraries. If you add library A, and A needs B, Maven fetches B too. These are called transitive dependencies. You can see the whole tree:

mvn dependency:tree

[INFO] com.example:my-app:jar:1.0-SNAPSHOT
[INFO] +- com.google.code.gson:gson:jar:2.11.0:compile
[INFO] \- org.junit.jupiter:junit-jupiter:jar:5.11.0:test
[INFO]    +- org.junit.jupiter:junit-jupiter-api:jar:5.11.0:test
[INFO]    ...

(The list is trimmed here. Maven also shows the libraries that each one needs, indented underneath.)

What if two libraries need different versions of the same third library? Maven uses a simple rule: the version nearest to your project wins. If they're equally near, the first one declared wins.

   my-app
     |-- lib-a 1.0
     |      +-- lib-b 2.0      (two steps away)
     +-- lib-c 1.0
            +-- lib-b 1.5      (two steps away: a tie, so the first one, 2.0, wins)

   To take control, declare lib-b yourself in your pom.xml. A direct dependency is nearest.

Maven goals and phases

Here's an important distinction:

A goal is one specific task done by a plugin. It's written as plugin:goal, like compiler:compile or surefire:test.
A phase is a named step in a lifecycle, like compile or test. Each phase has goals attached to it.

When you run a phase, Maven runs every earlier phase first, then the goals attached to that one. You can also run a goal directly, like mvn archetype:generate.

The commands you'll use most:

mvn clean: deletes the target folder, so you start fresh.
mvn compile: compiles the main code.
mvn test: compiles, then runs the unit tests.
mvn package: runs the tests, then builds the JAR (or WAR).
mvn install: packages, then copies the result into your local repository, so other projects on your machine can use it.
mvn deploy: uploads the package to a remote repository for others to use.

Here is what a run looks like. This is a trimmed mvn package:

[INFO] --- resources:3.x:resources (default-resources) @ my-app ---
[INFO] --- compiler:3.x:compile (default-compile) @ my-app ---
[INFO] Compiling 1 source file with javac [debug release 17] to target/classes
[INFO] --- surefire:3.5.0:test (default-test) @ my-app ---
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] --- jar:3.x:jar (default-jar) @ my-app ---
[INFO] Building jar: /.../my-app/target/my-app-1.0-SNAPSHOT.jar
[INFO] BUILD SUCCESS

(Version numbers on your screen will differ.) Each --- plugin:version:goal --- line is one goal running. You can see Maven working through the lifecycle: resources, compile, test, jar.

Testing with JUnit

Let's write a real class and test. Create src/main/java/com/example/Calculator.java:

package com.example;

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}

And the test, src/test/java/com/example/CalculatorTest.java:

package com.example;

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;

class CalculatorTest {
    @Test
    void addsTwoNumbers() {
        assertEquals(5, new Calculator().add(2, 3));
    }
}

mvn test

[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Now break the test on purpose, by changing 5 to 6, and run mvn package:

[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0
[INFO] BUILD FAILURE

Look what didn't happen: no JAR was created. The test phase failed, so Maven stopped before the package phase. That's the value of the lifecycle: broken code can't become a package by accident.

Maven's test plugin finds tests by name. By default it looks for classes named *Test, Test*, *Tests or *TestCase, in src/test/java.

Running your JAR

After mvn package, your JAR is in target/. If you try to run it like a normal application:

java -jar target/my-app-1.0-SNAPSHOT.jar

no main manifest attribute, in target/my-app-1.0-SNAPSHOT.jar

The JAR doesn't say which class has main. You can run it by naming the class:

java -cp target/my-app-1.0-SNAPSHOT.jar com.example.App

Or make the JAR runnable by telling the jar plugin about your main class, in pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.4.2</version>
      <configuration>
        <archive>
          <manifest>
            <mainClass>com.example.App</mainClass>
          </manifest>
        </archive>
      </configuration>
    </plugin>
  </plugins>
</build>

(If your app uses outside libraries, you'd need another plugin, such as the shade or assembly plugin, to bundle them into one "fat" JAR.)

Maven repositories

A repository is a storage place for libraries and plugins, organized by their coordinates. Maven uses three kinds:

Local repository: a folder on your own computer, by default ~/.m2/repository. It's a cache of everything you've downloaded, plus anything you install.
Central repository: Maven Central, the huge public repository on the internet. It's where most open-source libraries live, and Maven uses it by default.
Remote repository: any other server. Companies often run their own (with tools such as Nexus or Artifactory) for private libraries, and to cache Central.

When Maven needs a library, it follows this search:

   Need gson 2.11.0
        |
        v
   1. Local repository  (~/.m2/repository)  --- found? ---> use it (no internet needed)
        | not found
        v
   2. Remote repositories you configured (company server)  --- found? ---+
        | not found                                                      |
        v                                                                v
   3. Maven Central (internet)  --- found? ---> download ---------> save a copy in
                                                                      the local repository

Because of that last step, each library is downloaded only once. Later builds use the local copy, and you can even work offline with mvn -o.

How the lifecycle phases connect to repositories:

install copies your JAR into the local repository.
deploy uploads it to a remote repository (you must configure the server address and your login).

You can configure repositories, mirrors and passwords in a settings.xml file in your .m2 folder.

The Maven build lifecycle

A build lifecycle is a fixed sequence of phases. Maven has three built-in lifecycles: default, clean and site.

1. The default lifecycle (building your project)

These are the main phases, in order:

   validate --> compile --> test --> package --> verify --> install --> deploy

validate: checks that the project is correct and the needed information is there.
compile: compiles the source code in src/main/java.
test: runs unit tests, using the compiled code. The tests don't need to be packaged.
package: bundles the compiled code into the packaging type (JAR, WAR).
verify: runs any extra checks on the package, like integration tests and quality rules.
install: copies the package into the local repository.
deploy: copies the final package to a remote repository for sharing.

(The real lifecycle has more phases in between, such as generate-sources, process-resources and test-compile. The ones above are the ones you'll use directly.)

The key rule: when you run a phase, Maven runs all the phases before it, in order.

   mvn compile   runs:  validate, compile
   mvn test      runs:  validate, compile, test
   mvn package   runs:  validate, compile, test, package
   mvn install   runs:  validate, compile, test, package, verify, install

You never need to run mvn compile and then mvn test separately. Just run the last phase you want.

What runs in each phase?

Each phase has plugin goals attached, and which ones depend on your packaging type. For a normal jar project:

   PHASE        GOAL THAT RUNS               WHAT IT DOES
   compile      compiler:compile             javac on src/main/java
   test         surefire:test                runs the unit tests
   package      jar:jar                      builds the .jar
   install      install:install              copies it to ~/.m2
   deploy       deploy:deploy                uploads to a remote repository

   For packaging "war":   package runs  war:war  instead of  jar:jar

This answers the question "how does Maven know what to do?" The packaging type chooses which goals are attached to which phases. That's why <packaging> matters.

2. The clean lifecycle

This one cleans up. It has three phases: pre-clean, clean and post-clean. In practice you use only clean, which deletes the target folder.

mvn clean

It's the way to get rid of old compiled files, so nothing stale is left behind. You'll often combine it with the default lifecycle:

mvn clean package

Maven runs clean (the clean lifecycle) first, then the default lifecycle up to package.

3. The site lifecycle

This one creates project documentation and reports. Its phases are pre-site, site, post-site and site-deploy.

mvn site

It generates a website describing your project (test reports, dependency lists, and so on) in target/site. It's optional, and less common in day-to-day work than the other two.

What's inside `target/` after a build?

   target/
   |-- classes/                      <- compiled main code (.class)
   |-- test-classes/                 <- compiled test code
   |-- surefire-reports/             <- test result reports
   +-- my-app-1.0-SNAPSHOT.jar       <- the packaged result

A few tips and commands

Skip tests when you must (for example, to package quickly): mvn package -DskipTests. This still compiles the tests. -Dmaven.test.skip=true skips compiling them too. Don't make this a habit, since tests are your safety net.
Run one test class: mvn test -Dtest=CalculatorTest
Force re-download of snapshots and failed items: mvn package -U
Work offline: mvn -o package
See the dependency tree: mvn dependency:tree
See the full merged POM: mvn help:effective-pom

Which one should I use?

mvn package, verify or install? Use package to build the JAR. Use verify when you also want the extra checks. Use install when another project on your machine needs this one as a dependency.
mvn clean package or just package? Use clean when you want a guaranteed fresh build, for example after renaming or deleting files, so old .class files don't linger.
JAR or WAR? A JAR for libraries and normal applications. A WAR for web apps that go on a server like Tomcat. (Frameworks such as Spring Boot also build runnable JARs with an embedded server.)
SNAPSHOT or release? Use -SNAPSHOT while developing. Publish a release version when something is finished and tagged, because releases never change.
Which scope? test for testing libraries, provided for things the server gives you, runtime for things only needed when running, and compile for everything else.
Archetype or generator website? For plain Java, an archetype is great. For Spring Boot projects, most people use the Spring Initializr website, which creates a ready Maven project.
Maven or Gradle? Both work well. Maven is more standard and predictable. Gradle is more flexible and often faster on big builds. Learning Maven first gives you the concepts that both share.

Common mistakes

JAVA_HOME or Java version problems. If mvn -v shows the wrong Java, or fails, fix JAVA_HOME. Also set maven.compiler.release in pom.xml to match your JDK.
Running java -jar on a JAR with no main class. You get "no main manifest attribute." Set the main class in the jar plugin, or run it with -cp and the class name.
Wrong folders or test names. Code outside src/main/java, or tests outside src/test/java or not named like *Test, are silently ignored. "No tests to run" usually means this.
Skipping tests all the time. -DskipTests hides real problems. Use it rarely.
Version surprises. Using SNAPSHOT dependencies in something you release, or two libraries needing different versions of a third. Check with mvn dependency:tree, and declare the version you want directly.
Stale or broken builds. Old classes in target/ or a half-downloaded file in ~/.m2 can cause strange errors. Run mvn clean, and use -U to force a fresh download.

Quick recap

A build tool automates compile, test, package and dependency handling, so builds are repeatable on every machine.
Dependency management means you declare what you need, and the tool downloads it, including what your libraries need.
The code journey: .java → .class → unit tests → package → .jar / .war.
Maven follows convention over configuration. It reads pom.xml, runs the lifecycle, and uses plugins to do each step.
The standard layout: src/main/java, src/main/resources, src/test/java, and output in target/.
pom.xml holds the project's identity (groupId, artifactId, version, packaging), properties, dependencies and plugins. It inherits defaults from the Super POM.
mvn archetype:generate creates a project from a template. -D options set properties.
Coordinates (groupId:artifactId:version) identify anything uniquely. -SNAPSHOT means in development, and a release never changes.
Packaging (jar, war, pom) decides what is built.
Goals are plugin tasks (plugin:goal). Phases are lifecycle steps. Running a phase runs all earlier ones.
Repositories: local (~/.m2), central (Maven Central) and remote (company servers). install goes to local, deploy goes to remote.
Lifecycles: default (validate → compile → test → package → verify → install → deploy), clean (deletes target) and site (generates documentation).

Try it yourself

Here's a small practice idea: generate a project with the archetype:generate command from this post. Add the Calculator class and CalculatorTest, run mvn test, and then break the test on purpose and run mvn package to see that no JAR gets built. Fix it, run mvn clean package, and find your JAR in target/. Finally, run mvn dependency:tree and mvn help:effective-pom and see how much Maven was doing for you.

For a bonus experiment, add the Gson dependency, print some JSON from your App, and then look inside ~/.m2/repository/com/google/code/gson to see the exact folder path your coordinates turned into.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Java var, Records and Sealed Classes Explained Simply

Mayur Bodhare — Wed, 14 Oct 2026 16:12:27 +0000

Java has a reputation for being wordy, and for a long time it earned it. To store a simple pair of numbers, I had to write a class with two fields, a constructor, two getters, equals, hashCode and toString. That's around forty lines for something that is just "x and y." And a line like this made my eyes tired:

Map<String, List<Integer>> scores = new HashMap<String, List<Integer>>();

Modern Java fixed a lot of this. In this post, we'll learn three features that make code shorter and safer:

var (local variable type inference), so you stop repeating types.
record classes, which give you data classes in one line.
sealed classes, which let you say exactly which classes may extend yours.

At the end, we'll combine all three in one small program. If you read the post about streams, you'll notice that these features fit with them very well.

A quick note on versions, because each feature arrived at a different time: var came in Java 10, records are final in Java 16, sealed classes in Java 17, and the pattern-matching switch that I use with sealed types is final in Java 21. Any recent LTS version has all of them.

Unless I show a full class, the snippets go inside a main method. Records and other types are declared outside it.

Part 1: var (local variable type inference)

What is var?

var lets the compiler work out the type of a local variable from the value on the right side. This is called LVTI, short for Local Variable Type Inference.

var name = "Asha";
var count = 10;
var prices = new ArrayList<Double>();
var scores = new HashMap<String, List<Integer>>();

The long line from the start of this post becomes much shorter, because the type was already written on the right side. Why say it twice?

var is NOT dynamic typing

This is the most common misunderstanding. var doesn't make Java behave like JavaScript. The variable still has one fixed type, chosen at compile time:

var name = "Asha";
System.out.println(name.toUpperCase());

name = 5;

Output:

ASHA

and then a compile error on the last line:

incompatible types: int cannot be converted to String

name is a String forever. You can call String methods on it, and you can't put a number in it.

Behind the scenes

The compiler simply replaces var with the real type while compiling. The bytecode is exactly the same as if you had written the type yourself, so var has no cost at run time.

   var count = 10;                       -->   int count = 10;
   var names = new ArrayList<String>();  -->   ArrayList<String> names = new ArrayList<String>();

   The type is worked out when you COMPILE. Nothing changes when the program RUNS.

Where you can use it

var works for local variables, in several places:

var message = "Hello";                          // normal local variable

for (var i = 0; i < 3; i++) { }                 // classic for loop

for (var n : List.of(1, 2, 3)) { }              // enhanced for loop

BiFunction<Integer, Integer, Integer> add =
        (var a, var b) -> a + b;                // lambda parameters (Java 11+)

Where you can't

   var x;                  error: cannot infer type (no initial value)
   var x = null;           error: cannot infer type (the value is 'null')
   var f = () -> 1;        error: cannot infer type (lambda needs a target type)
   var a = {1, 2, 3};      error: cannot infer type (array initializer needs a type)

   Also NOT allowed: fields, method parameters and return types.

The compiler can only infer a type when the right side makes it clear. In all these cases, there's nothing (or not enough) to infer from. Also, var is only for local variables, so it can't be used for class fields or in method signatures.

A gotcha: the diamond

var list = new ArrayList<>();
list.add("a");
list.add(1);

System.out.println(list);

Output:

[a, 1]

With a normal declaration, List<String> list = new ArrayList<>(); tells the compiler to use String for the diamond <>. With var, there's no target type, so the compiler picks ArrayList<Object>, and the list accepts anything. Write new ArrayList<String>() when you use var.

Another small thing to know: var list = new ArrayList<String>(); has the type ArrayList<String>, not List<String>. If you want your variable to use the interface type (a good habit), write it out: List<String> list = new ArrayList<>();.

Is var a good idea?

It depends on readability:

Good: the type is obvious from the right side. var users = new ArrayList<User>(); and var reader = new BufferedReader(...); need no extra explanation.
Not good: the right side hides the type. In var result = process(data);, a reader has to look up process to learn what result is.

A good rule: use var when it removes repetition, and use the explicit type when it adds information. And since the type is no longer visible, choose clear variable names.

Part 2: Records

The problem: so much code for plain data

Here is a simple class that just carries two numbers:

class PointClass {
    private final int x;
    private final int y;

    PointClass(int x, int y) {
        this.x = x;
        this.y = y;
    }

    int getX() { return x; }
    int getY() { return y; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof PointClass)) return false;
        PointClass other = (PointClass) o;
        return x == other.x && y == other.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }

    @Override
    public String toString() {
        return "PointClass[x=" + x + ", y=" + y + "]";
    }
}

That's a lot of text, and every line is boilerplate (code you write only because the language requires it). A record does the same in one line:

record Point(int x, int y) { }

Point p = new Point(3, 4);

System.out.println(p);
System.out.println(p.x());
System.out.println(p.equals(new Point(3, 4)));
System.out.println(p.hashCode() == new Point(3, 4).hashCode());

Output:

Point[x=3, y=4]
3
true
true

Two points with the same values are equal, even though they are different objects. Records compare by value, not by identity.

What the compiler writes for you

The list in the parentheses, (int x, int y), is called the record's components. For them, the compiler generates:

   record Point(int x, int y) { }
            |
            |   the compiler expands it into roughly this:
            v
   final class Point extends java.lang.Record {
       private final int x;
       private final int y;

       Point(int x, int y) { ... }         // the "canonical" constructor
       int x() { return x; }               // accessors: note, NO "get" prefix
       int y() { return y; }
       boolean equals(Object o) { ... }    // compares all components
       int hashCode() { ... }
       String toString() { ... }           // Point[x=3, y=4]
   }

You can verify the hidden parts yourself:

System.out.println(Point.class.getSuperclass());
System.out.println(java.lang.reflect.Modifier.isFinal(Point.class.getModifiers()));

Output:

class java.lang.Record
true

So a record is a real class. It's final (nobody can extend it), and its parent is java.lang.Record. (Behind the scenes, the generated equals, hashCode and toString are wired up with the same invokedynamic mechanism we saw with lambdas.)

Validation with a compact constructor

What if you want to reject bad values? Write a compact constructor. It has the record's name but no parentheses. It runs before the fields are set:

record Age(int value) {
    Age {
        if (value < 0) {
            throw new IllegalArgumentException("Age cannot be negative");
        }
    }
}

System.out.println(new Age(25));

try {
    new Age(-1);
} catch (IllegalArgumentException e) {
    System.out.println("Error: " + e.getMessage());
}

Output:

Age[value=25]
Error: Age cannot be negative

You can also adjust a value in the compact constructor by reassigning the parameter. And records can have their own methods and static helpers:

record Person(String name, int age) {
    Person {
        name = name.trim();
    }

    String greeting() {
        return "Hi, " + name;
    }

    static Person of(String name) {
        return new Person(name, 0);
    }
}

System.out.println(new Person("  Asha ", 25));
System.out.println(Person.of("Ravi").greeting());

Output:

Person[name=Asha, age=25]
Hi, Ravi

The rules of records

A record is implicitly final and can't extend another class (it already extends Record).
It can implement interfaces, and it can be generic, like record Pair<A, B>(A first, B second).
The component fields are private final. You can't add extra instance fields, and there are no setters.
You can add methods, static methods and static fields.
Any extra constructor must call the canonical one with this(...).

A trap: records are shallowly immutable

The fields can't be reassigned, but if a field holds a changeable object, that object can still change:

record Team(String name, List<String> members) { }

var members = new ArrayList<>(List.of("Asha"));
var team = new Team("Core", members);

members.add("Ravi");
System.out.println(team);

Output:

Team[name=Core, members=[Asha, Ravi]]

The team changed even though we never touched the record! The fix is a defensive copy in the compact constructor:

record SafeTeam(String name, List<String> members) {
    SafeTeam {
        members = List.copyOf(members);
    }
}

var members = new ArrayList<>(List.of("Asha"));
var team = new SafeTeam("Core", members);

members.add("Ravi");
System.out.println(team);

Output:

SafeTeam[name=Core, members=[Asha]]

Now the record keeps its own unchangeable copy.

Records work nicely with streams

Because the accessors are plain methods, they fit method references:

record Student(String name, int marks) { }

List<Student> students = List.of(
        new Student("Asha", 88),
        new Student("Ravi", 72),
        new Student("Meera", 95));

students.stream()
        .filter(s -> s.marks() > 80)
        .map(Student::name)
        .forEach(System.out::println);

Output:

Asha
Meera

Records are ideal for small data carriers: results that return several values, map keys, DTOs (objects that carry data between layers) and test data.

Part 3: Sealed classes

The problem: inheritance is too open

Normally, if you write interface Shape, anyone can implement it, anywhere, at any time. That's flexible, but sometimes it's a problem. Imagine you want to say "a Shape is only a Circle or a Rectangle, nothing else." With normal inheritance, you can't say that, and the compiler can never be sure it has seen every possible shape.

A sealed class or interface solves this. It lists exactly which classes may extend or implement it, using the permits keyword:

sealed interface Shape permits Circle, Rectangle { }

record Circle(double radius) implements Shape { }
record Rectangle(double width, double height) implements Shape { }

   Normal hierarchy:    Shape  <---  anyone can extend it (unknown subclasses)

   Sealed hierarchy:    Shape  <---  ONLY Circle and Rectangle
                                     the compiler knows ALL the cases

If another class tries to join the family uninvited:

final class Triangle implements Shape { }

class is not allowed to extend sealed class: Shape (as it is not listed in its 'permits' clause)

The three choices for a subclass

Every class that is permitted by a sealed class must declare what happens next in the family, with one of three keywords:

final: no more subclasses. The family ends here.
sealed: it restricts its own subclasses again, with its own permits list.
non-sealed: it opens the hierarchy back up, so anyone may extend it.

sealed class Vehicle permits Car, Truck, Bike { }

final class Car extends Vehicle { }

sealed class Truck extends Vehicle permits Pickup { }
final class Pickup extends Truck { }

non-sealed class Bike extends Vehicle { }

              Vehicle  (sealed)
             /    |     \
          Car   Truck    Bike
        final  sealed   non-sealed
                  |
               Pickup
                final

Records are automatically final, which is why they pair so well with sealed interfaces. A few more rules:

A permitted subclass must directly extend the sealed class.
It must be in the same module (or the same package, if your project doesn't use modules).
If all the subclasses are in the same file as the sealed class, you can leave out permits, and the compiler works it out.

The payoff: exhaustive switch

Because the compiler knows every possible subtype, a switch over a sealed type doesn't need a default:

static double area(Shape shape) {
    return switch (shape) {
        case Circle c    -> Math.PI * c.radius() * c.radius();
        case Rectangle r -> r.width() * r.height();
    };
}

System.out.println(area(new Circle(1)));
System.out.println(area(new Rectangle(3, 4)));

Output:

3.141592653589793
12.0

(This pattern-matching switch needs Java 21 or newer.) The best part comes later. Imagine you add a Triangle to the permits list but forget to update area. The code stops compiling:

the switch expression does not cover all possible input values

The compiler found the bug for you, long before a user would. That's the real value of sealed types: when the set of cases changes, every place that must handle them is flagged.

In Java 21 and newer, you can even take a record apart inside the case:

case Circle(double radius)             -> Math.PI * radius * radius;
case Rectangle(double width, double height) -> width * height;

A practical example: success or failure

A common use is a result type that is either a success or a failure:

sealed interface Result permits Success, Failure { }
record Success(String data) implements Result { }
record Failure(String error) implements Result { }

static String describe(Result r) {
    return switch (r) {
        case Success s -> "OK: " + s.data();
        case Failure f -> "Error: " + f.error();
    };
}

System.out.println(describe(new Success("saved")));
System.out.println(describe(new Failure("timeout")));

Output:

OK: saved
Error: timeout

Behind the scenes

The permits list is stored inside the .class file. When a class is loaded, the JVM checks it, so the rule is enforced both by the compiler and at run time. You can even read it with reflection:

System.out.println(Shape.class.isSealed());

for (Class<?> c : Shape.class.getPermittedSubclasses()) {
    System.out.println(c.getSimpleName());
}

Output:

true
Circle
Rectangle

Sealed vs enum vs final

These three often get confused:

final means no subclasses at all.
enum means a fixed set of objects (like MONDAY, TUESDAY), each created once.
sealed means a fixed set of types, and each type can have many objects, usually with different data (a Circle has a radius, and a Rectangle has a width and height).

Putting it all together

Let's use everything in one small program: a tiny calculator that models expressions as a sealed hierarchy of records, walks them with a switch, and uses var for the local variables.

sealed interface Expr permits Num, Add, Mul { }
record Num(int value) implements Expr { }
record Add(Expr left, Expr right) implements Expr { }
record Mul(Expr left, Expr right) implements Expr { }

public class Calculator {
    static int eval(Expr e) {
        return switch (e) {
            case Num n -> n.value();
            case Add a -> eval(a.left()) + eval(a.right());
            case Mul m -> eval(m.left()) * eval(m.right());
        };
    }

    public static void main(String[] args) {
        var expr = new Add(new Num(2), new Mul(new Num(3), new Num(4)));

        System.out.println(eval(expr));
        System.out.println(expr);
    }
}

Output:

14
Add[left=Num[value=2], right=Mul[left=Num[value=3], right=Num[value=4]]]

Look at how each feature helped:

Records gave us four tiny data types in four lines, and a readable toString for free.
Sealed told the compiler that Expr is only Num, Add or Mul, so eval needs no default.
switch with patterns unpacked each case without casts.
var kept the long type name out of main.

Try adding a Sub record to the permits list, and watch the compiler point at eval.

Which one should I use?

var or the explicit type? Use var when the right side already shows the type (new ArrayList<String>(), a constructor call, a clearly named factory). Use the explicit type when it helps the reader, or when you want an interface type like List<String>.
Record or class? Use a record for plain, unchangeable data carriers: DTOs, map keys, multiple return values, test data. Use a class when you need changeable state, inheritance, hidden internal data or behavior that doesn't revolve around the data. Many frameworks that need changeable, proxied objects (such as JPA entities) don't fit records.
Sealed, enum or open interface? Use an enum for a fixed set of constants. Use a sealed hierarchy for a fixed set of types that carry different data. Use a normal open interface when other people should be able to add their own implementations (a plugin system, for example).
Records and sealed together? This is a great combination for modeling "one of several shapes of data," like results, events, commands and expressions.

Common mistakes

Using var when the type becomes unclear. If a reader can't tell what the variable is without hunting, write the type. Also remember var list = new ArrayList<>() gives you ArrayList<Object>.
Thinking var makes Java dynamic. The type is fixed at compile time. You can't assign a different type later, and you can't use var for fields, parameters or return types.
Assuming records are fully immutable. If a component is a list or another changeable object, it can still change. Make a defensive copy in the compact constructor, and remember that you can't add instance fields or setters.
Using the wrong accessor name. A record's accessor is p.x(), not p.getX(). And equality is based on values, so two records with the same data are equals.
Forgetting what a permitted subclass must say. Each one has to be final, sealed or non-sealed, and it must sit in the same module (or package). Otherwise, the code won't compile.
Adding a default branch to a switch over a sealed type. It silences the compiler's exhaustiveness check. When you add a new subtype later, it falls into default without any warning. Leave default out so the compiler can protect you.

Quick recap

var lets the compiler infer the type of a local variable. The type is still fixed at compile time, and the bytecode is the same as if you'd written it out.
var needs an initial value that shows the type. It can't be used for fields, parameters, return types, null or lambdas without a target type. Use it when it removes repetition, not when it hides the type.
A record is a one-line data class. The compiler generates the final fields, canonical constructor, accessors like x(), and equals, hashCode and toString. It's implicitly final, extends java.lang.Record and can't have extra instance fields.
Use a compact constructor for validation, and make a defensive copy of changeable components.
A sealed class or interface lists its allowed subclasses with permits. Each one must be final, sealed or non-sealed.
Sealed types give you an exhaustive switch with no default, so the compiler tells you when you forget a case.
Records plus sealed interfaces plus pattern-matching switch is a powerful modern-Java pattern.

Try it yourself

Here's a small practice idea: model a payment system. Create a sealed interface Payment permits Card, Upi, Cash, with a record for each, such as Card(String number, int amount), Upi(String id, int amount) and Cash(int amount). Write a method fee(Payment p) that returns a different fee for each, using a switch with no default. Use var for your local variables in main.

For a bonus experiment, add a new record NetBanking to the permits list, and read the compiler error on your switch. Then handle the new case and see it compile again.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

That wraps up this two-part series on modern Java.

Java Stream API for Beginners: From Loops to Pipelines

Mayur Bodhare — Wed, 14 Oct 2026 11:01:25 +0000

For a long time, my Java code for "take this list, keep the long names, make them uppercase, collect the result" was six lines of loop, an if and a temporary list. Then I saw this:

names.stream().filter(n -> n.length() > 2).map(String::toUpperCase).toList();

One line. It read almost like English, but it also raised questions. What is a stream? What does String::toUpperCase mean? And why do some methods in this style return something called Optional instead of just the value?

In this post, we'll answer those questions in order: method references and constructor references (the :: syntax), the Stream API, and the Optional class. They fit together, so by the end you'll be able to read and write the one-liner above with confidence. If you haven't read about lambdas, skim that first, because everything here builds on them.

All the snippets assume these imports and go inside a main method unless I show a full class:

import java.util.*;
import java.util.function.*;
import java.util.stream.*;

Part 1: Method references and constructor references

A method reference is a shorter way to write a lambda that does nothing except call one existing method. You write the class (or object), then ::, then the method name, with no brackets.

s -> s.length()         // lambda
String::length          // method reference, same meaning

There are four kinds. Here they are with their lambda twins:

   KIND                          REFERENCE              SAME AS THIS LAMBDA
   1. static method              Integer::parseInt      s -> Integer.parseInt(s)
   2. method of a given object   prefix::concat         s -> prefix.concat(s)
   3. method of "any" object     String::length         s -> s.length()
      of a type
   4. constructor                Person::new            n -> new Person(n)

Let's see them one by one:

// 1. static method
Function<String, Integer> parse = Integer::parseInt;
System.out.println(parse.apply("42") + 1);

// 2. method of a specific object we already have
String prefix = "Hello, ";
Function<String, String> greet = prefix::concat;
System.out.println(greet.apply("Asha"));

// 3. method of an object that will be given to us later
Function<String, Integer> len = String::length;
System.out.println(len.apply("lambda"));

BiFunction<String, String, Boolean> same = String::equalsIgnoreCase;
System.out.println(same.apply("Java", "JAVA"));

Output:

43
Hello, Asha
6
true

Kind 3 is the one that confuses people. In String::length, no object is named, so where does the string come from? From the first parameter of the functional interface. Function<String, Integer> gives us one String, and Java calls .length() on it. In String::equalsIgnoreCase, the first parameter is the object, and the second is the argument: (a, b) -> a.equalsIgnoreCase(b).

Constructor references

A constructor reference uses ::new. It's a lambda that creates an object:

class Person {
    private final String name;

    Person(String name) {
        this.name = name;
    }

    @Override
    public String toString() {
        return "Person(" + name + ")";
    }
}

Function<String, Person> maker = Person::new;
Supplier<List<String>> listMaker = ArrayList::new;
IntFunction<int[]> arrayMaker = int[]::new;

System.out.println(maker.apply("Asha"));

List<String> list = listMaker.get();
list.add("x");
System.out.println(list);

System.out.println(arrayMaker.apply(3).length);

Output:

Person(Asha)
[x]
3

How does Java know which constructor Person::new means? It looks at the functional interface. Function<String, Person> takes a String, so Java picks Person(String). Supplier<List<String>> takes nothing, so ArrayList::new means the no-argument constructor. The same words, ArrayList::new, can mean different constructors depending on the target type.

Behind the scenes

Method references work like lambdas. The compiler doesn't create a separate class for them. It writes an invokedynamic instruction, and the JVM builds the function object at run time. The compiler picks the method by matching the parameter types of the functional interface. If two methods could fit, you get an "ambiguous method reference" error, and the fix is to write a normal lambda.

Use a method reference when it makes the code shorter and clearer. If the lambda does more than one call, or the reference looks cryptic, keep the arrow form.

Part 2: The Stream API

What is a stream?

A stream is a pipeline for processing a sequence of data, usually from a collection. It's not a data structure. It doesn't store anything, and it never changes the original collection. Think of a factory conveyor belt: items come in, pass through stations and come out the other end.

Every stream pipeline has three parts:

   SOURCE            INTERMEDIATE operations           TERMINAL operation
   (where data   -->  (each one returns a stream)  -->  (produces a result
    comes from)                                          and starts the work)

   list.stream()  --> filter(...) --> map(...) --> sorted() --> collect(...) / count() / forEach(...)

Source: list.stream(), Arrays.stream(array), Stream.of(...), IntStream.rangeClosed(1, 5) and others.
Intermediate operations: filter, map, sorted, distinct, limit, skip, flatMap. Each one returns a new stream, so you can chain them.
Terminal operation: collect, toList, forEach, count, sum, reduce, min, max, findFirst, anyMatch and others. It ends the pipeline.

From a loop to a stream

Here's the task from my intro, done the old way and the stream way:

List<String> names = List.of("Meera", "Jo", "Ravi", "Asha", "Jo");

// the old way
List<String> result = new ArrayList<>();
for (String n : names) {
    if (n.length() > 2) {
        result.add(n.toUpperCase());
    }
}

// the stream way
List<String> result2 = names.stream()
        .filter(n -> n.length() > 2)
        .map(String::toUpperCase)
        .toList();

System.out.println(result2);

Output:

[MEERA, RAVI, ASHA]

filter keeps the items where the condition is true (a Predicate).
map transforms each item into something else (a Function).
toList() collects the result into a list. (It needs Java 16 or newer. In older versions, write .collect(Collectors.toList()).)

The stream version says what you want. The loop says how to do it step by step.

The operations you'll use most

List<Integer> nums = List.of(5, 3, 8, 3, 1, 9, 8);

System.out.println(nums.stream().distinct().sorted().limit(4).toList());
System.out.println(nums.stream().filter(n -> n > 4).count());
System.out.println(nums.stream().mapToInt(Integer::intValue).sum());
System.out.println(nums.stream().reduce(0, Integer::sum));
System.out.println(nums.stream().max(Integer::compare));
System.out.println(nums.stream().anyMatch(n -> n > 8));

Output:

[1, 3, 5, 8]
4
37
37
Optional[9]
true

Let's read them:

distinct().sorted().limit(4) removed duplicates, sorted, then kept the first four.
count() counted the numbers bigger than 4 (5, 8, 9, 8).
mapToInt(...).sum() and reduce(0, Integer::sum) both add everything up. reduce repeatedly combines two values into one, starting from 0.
max(...) returns an Optional, which we'll meet in the next part. Here it printed as Optional[9].
anyMatch checks whether at least one item passes. (allMatch and noneMatch work the same way.)

A tip: for numbers, prefer mapToInt(...) and the primitive streams (IntStream, LongStream, DoubleStream). They avoid the boxing cost we discussed in the wrapper classes topic, and they give you sum(), average() and similar methods for free.

Collecting results: Collectors

collect takes a collector, a recipe for building the final result:

List<String> names = List.of("Meera", "Jo", "Ravi", "Asha", "Jo");

System.out.println(names.stream().distinct()
        .collect(Collectors.joining(", ", "[", "]")));

Map<Integer, List<String>> byLength = names.stream().distinct()
        .collect(Collectors.groupingBy(String::length, TreeMap::new, Collectors.toList()));
System.out.println(byLength);

Map<String, Long> frequency = names.stream()
        .collect(Collectors.groupingBy(n -> n, TreeMap::new, Collectors.counting()));
System.out.println(frequency);

Output:

[Meera, Jo, Ravi, Asha]
{2=[Jo], 4=[Ravi, Asha], 5=[Meera]}
{Asha=1, Jo=2, Meera=1, Ravi=1}

joining glued the names into one string.
groupingBy made a map from each key (the length) to the list of items that share it.
counting counted the items in each group.

Look closely at TreeMap::new. That's a constructor reference from earlier, used to say "put the result in a TreeMap," so the keys come out sorted.

flatMap: flattening nested lists

When each item turns into several items, or you have a list of lists, use flatMap:

List<List<Integer>> nested = List.of(List.of(1, 2), List.of(3), List.of(4, 5));

List<Integer> flat = nested.stream()
        .flatMap(List::stream)
        .toList();

System.out.println(flat);

Output:

[1, 2, 3, 4, 5]

map would give you a stream of streams. flatMap merges them into one.

Streams are lazy

This is the most surprising thing about streams. Intermediate operations do nothing until a terminal operation starts the pipeline:

Stream<String> s = Stream.of("a", "bb", "ccc")
        .filter(x -> {
            System.out.println("filter " + x);
            return x.length() > 1;
        });

System.out.println("Nothing printed yet");
s.forEach(x -> System.out.println("got " + x));

Output:

Nothing printed yet
filter a
filter bb
got bb
filter ccc
got ccc

Two lessons are hidden here:

Nothing ran when we built the pipeline. The filter code only ran after forEach, the terminal operation, started the work.
Each item travels through the whole pipeline before the next one starts. It's not "filter everything, then print everything." It's item by item:

   "a"    -> filter (fails)  -> stops here
   "bb"   -> filter (passes) -> forEach prints "got bb"
   "ccc"  -> filter (passes) -> forEach prints "got ccc"

Laziness also allows short-circuiting. Operations like findFirst and limit can stop early:

Stream.of(1, 2, 3, 4, 5)
        .filter(n -> {
            System.out.println("check " + n);
            return n % 2 == 0;
        })
        .findFirst()
        .ifPresent(n -> System.out.println("first even: " + n));

Output:

check 1
check 2
first even: 2

It never even looked at 3, 4 or 5.

Streams can be used only once

After a terminal operation, the stream is finished:

Stream<Integer> s = Stream.of(1, 2, 3);
s.forEach(System.out::println);
s.forEach(System.out::println);

1
2
3
Exception in thread "main" java.lang.IllegalStateException: stream has already been operated upon or closed

If you need it again, create a new stream from the source.

Behind the scenes

When you chain filter(...) and map(...), Java doesn't process any data. It just builds a chain of stages, like a recipe. Only when the terminal operation runs does it pull items from the source through all the stages. Because of this, the stages can be fused into one pass over the data, and short-circuit operations can stop early. A few operations, like sorted(), need to see all items before they can pass any on, so they act as a wall in the pipeline.

Also, the lambdas you write become the standard functional interfaces we learned about: Predicate for filter, Function for map, Consumer for forEach.

Two rules keep streams safe: don't change the source while a pipeline runs, and avoid side effects inside the lambdas (like adding to an outside list). Use collect to build results instead.

You may also see .parallelStream(), which splits the work across several threads. It can speed up big, CPU-heavy jobs, but for small data it's usually slower, and shared mutable state can cause bugs. Don't reach for it by default.

Part 3: The Optional class

The problem: null

You've probably met this error many times:

Exception in thread "main" java.lang.NullPointerException

It happens when a method returns null ("no result") and the caller forgets to check. The method signature String findEmail(String user) doesn't tell you that null is possible. You only find out when the program crashes.

Optional<T> fixes this by making "maybe no value" visible in the type. It's a small container that either holds one value or is empty. When you see Optional<String> as a return type, you know right away: "there might be nothing here, and I must deal with that."

Creating an Optional

Optional<String> a = Optional.of("Asha");           // value must NOT be null
Optional<String> b = Optional.ofNullable(null);     // null becomes "empty"
Optional<String> c = Optional.empty();              // explicitly empty

System.out.println(a);
System.out.println(b);

Output:

Optional[Asha]
Optional.empty

Use ofNullable when the value might be null. Optional.of(null) throws a NullPointerException immediately.

Using an Optional

Don't pull the value out and test it by hand. Use the methods that handle both cases for you:

Optional<String> name = Optional.of("Asha");
Optional<String> none = Optional.empty();

System.out.println(name.map(String::toUpperCase).orElse("unknown"));
System.out.println(none.map(String::toUpperCase).orElse("unknown"));

name.ifPresent(n -> System.out.println("Hello " + n));
none.ifPresentOrElse(
        n -> System.out.println("Hello " + n),
        () -> System.out.println("No name"));

Output:

ASHA
unknown
Hello Asha
No name

The main tools:

map(...) transforms the value if there is one, and does nothing if empty.
filter(...) keeps the value only if it passes a test.
orElse(default) gives the value, or a default.
orElseGet(supplier) gives the value, or calls a supplier to make a default.
orElseThrow(...) gives the value, or throws an exception you choose.
ifPresent(...) and ifPresentOrElse(...) run code depending on the case.
isPresent() and isEmpty() check without reading.
get() returns the value, but throws NoSuchElementException if empty. Avoid it.

A real example: a method that returns Optional

static Optional<String> findEmail(String user) {
    Map<String, String> emails = Map.of("asha", "asha@example.com");
    return Optional.ofNullable(emails.get(user));
}

System.out.println(findEmail("asha").orElse("no email"));
System.out.println(findEmail("ravi").orElse("no email"));

findEmail("ravi").ifPresentOrElse(
        e -> System.out.println("Email: " + e),
        () -> System.out.println("Missing"));

Output:

asha@example.com
no email
Missing

Notice that the caller can't forget the empty case. The type forces the question.

Chaining instead of nested null checks

Optional shines when you chain steps that each might fail:

static String clean(String input) {
    return Optional.ofNullable(input)
            .map(String::trim)
            .filter(s -> !s.isEmpty())
            .map(String::toUpperCase)
            .orElse("EMPTY");
}

System.out.println(clean("  hi "));
System.out.println(clean("   "));
System.out.println(clean(null));

Output:

HI
EMPTY
EMPTY

The same logic with if (input != null) { ... } would take several nested checks. Here, if any step fails (null, or blank after trimming), the whole chain turns into "empty" and falls to orElse.

orElse vs orElseGet: a hidden trap

static String expensive() {
    System.out.println("computing default");
    return "default";
}

Optional<String> present = Optional.of("value");

System.out.println(present.orElse(expensive()));
System.out.println(present.orElseGet(() -> expensive()));

Output:

computing default
value
value

Even though the Optional had a value, the first line still ran expensive(). With orElse, Java computes the argument before the call, whether it's needed or not. With orElseGet, you pass a Supplier, and it runs only if the Optional is empty. For cheap constants, orElse is fine. For anything that does real work, use orElseGet.

Optional and streams

You already met Optional in the stream section: findFirst, max, min and reduce (the version without a starting value) all return one, because a stream might be empty:

List<Integer> nums = List.of(5, 3, 8, 3, 1, 9, 8);

System.out.println(nums.stream().filter(n -> n > 100).findFirst());
System.out.println(nums.stream().mapToInt(Integer::intValue).average());
System.out.println(nums.stream().mapToInt(Integer::intValue).average().orElse(0));

Output:

Optional.empty
OptionalDouble[5.285714285714286]
5.285714285714286

Primitive streams have their own versions: OptionalInt, OptionalLong and OptionalDouble.

Behind the scenes

Optional isn't magic. It's a small final class with one field holding the value, which is null when empty. The empty case is one shared object, so Optional.empty() doesn't create a new one each time.

   Optional.of("Asha")   ->  [ Optional | value --> "Asha" ]
   Optional.empty()      ->  the shared EMPTY object [ Optional | value = null ]

Because it's an extra object, it has a small cost. And it's meant for one job only: return types that mean "might have no result." That leads to a few guidelines:

Don't use Optional for fields, method parameters or items inside collections. Just use normal types, or overloads.
Don't return an Optional of a collection. Return an empty list instead.
Never return null from a method whose return type is Optional.
Don't write if (opt.isPresent()) { opt.get() }. That's just a null check in disguise. Use map, orElse or ifPresent.

Which one should I use?

Lambda or method reference? Use a method reference when the lambda only calls one method and the result is clearer (String::toUpperCase). Use a lambda when there's more logic.
Loop or stream? Use a stream for transform-filter-collect jobs, since it reads clearly. Keep a loop when you need break, an index, several changing variables or the simplest possible code. Don't force a stream into a job where it makes the code harder to read.
toList() or collect(Collectors.toList())? On Java 16 or newer, toList() is shorter, but the result can't be modified. If you need a changeable list, use collect(Collectors.toCollection(ArrayList::new)).
map or mapToInt? For numeric work (sums, averages), mapToInt avoids boxing and gives you sum() and average().
orElse, orElseGet or orElseThrow? orElse for cheap defaults, orElseGet for computed ones and orElseThrow when "empty" is truly an error.
Optional or null? Use Optional as a return type when "no result" is a normal answer. Don't use it everywhere.

Common mistakes

Forgetting the terminal operation. list.stream().filter(...).map(...) alone does nothing, because the pipeline never starts. Always end with toList(), collect, forEach, count or similar.
Reusing a stream. After a terminal operation, it's closed. You'll get IllegalStateException. Make a new stream from the source.
Changing things from inside a stream. Adding to an outside list in forEach, or modifying the source collection, causes confusing bugs. Let collect build your result.
Calling get() on an Optional without checking, or using Optional.of(null). Both throw exceptions. Prefer orElse... and ofNullable.
Using orElse with an expensive call. It always runs, even when the value is present. Use orElseGet.
Writing huge, unreadable chains, or using parallelStream() by default. If a pipeline needs a comment to explain it, split it into named steps. Parallel streams help only for large, CPU-heavy work.

Quick recap

A method reference (Class::method) is a short lambda. There are four kinds: static, specific object, "any object of a type" and constructor (::new).
A constructor reference picks the constructor that matches the functional interface's parameters.
A stream is a lazy pipeline: source → intermediate operations → terminal operation. It doesn't store data or change the source, and it can be used only once.
Nothing runs until the terminal operation starts, and each item flows through the whole pipeline in turn.
Common tools: filter, map, flatMap, sorted, distinct, limit, reduce, collect with Collectors like groupingBy, counting and joining.
Optional<T> is a container that holds one value or nothing. It makes "maybe no result" visible in a method's return type.
Use map, filter, orElse, orElseGet, orElseThrow and ifPresent instead of get(). Use orElseGet when the default is expensive.
Use Optional for return types, not for fields, parameters or collection items.

Try it yourself

Here's a small practice idea: take a list of words, such as the lines of a short paragraph split by spaces. Use a stream to remove blanks, make everything lowercase, count how often each word appears with groupingBy and counting into a TreeMap, and print them sorted. Then write a method Optional<String> longestWord(List<String> words) that returns the longest word, and print it with orElse("none").

For a bonus experiment, add a System.out.println inside a filter and a map, and watch how the items flow one by one. Then add .limit(2) and see how many items get processed.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Next in this series: var, records and sealed classes.

Java Collections Framework Explained Simply

Mayur Bodhare — Wed, 14 Oct 2026 10:59:42 +0000

When I first saw Collection and Collections in the same Java file, I thought one of them was a typo. Then I found Arrays, Objects and Collectors and was sure the Java team had a thing for confusing names.

On top of that, I had a bigger problem. Arrays were fine until I needed to add an item to the middle, remove one, avoid duplicates or look something up by name. I kept writing the same helper code over and over, and every version had its own bugs.

The Collections Framework is Java's answer to all of this. It's a ready-made toolbox of data structures and algorithms. In this post, we'll learn the big idea, the Collection interface, the Collections class (and why they're different), the built-in algorithms, and the most popular collections you'll use every day. I've drawn the key pictures in text so you can see how things connect.

All the snippets assume import java.util.*; at the top, and they go inside a main method unless I show a full class.

The concept: what is the Collections Framework?

A collection is an object that holds a group of other objects. The Collections Framework is the set of classes and interfaces in java.util that gives you the common ways to group objects: lists, sets, queues and maps.

Why use it instead of plain arrays?

Arrays have a fixed size. A collection grows and shrinks as needed.
Ready-made operations. Adding, removing, searching, sorting and checking for duplicates are already written, tested and fast.
Different shapes for different needs. Need order? A list. No duplicates? A set. Look up by key? A map.
Swappable parts. Code written against an interface works with any implementation.

The framework has three parts. This is the most useful way to remember it:

   1. INTERFACES        the contracts: what a list, set, queue or map CAN DO
                        (List, Set, Queue, Map ...)

   2. IMPLEMENTATIONS   the real classes that do the work
                        (ArrayList, HashSet, HashMap ...)

   3. ALGORITHMS        ready-made methods that work on any collection
                        (sort, search, shuffle ... in the Collections class)

The family tree

Here's how the main interfaces and classes are related. Spend a minute on this picture, because everything else hangs on it:

                      Iterable
                         |
                     Collection                         Map   (separate tree!)
            /------------+-------------\                 |
          List          Set           Queue          +---+----------+
           |             |              |            |   |          |
      ArrayList      HashSet        PriorityQueue  HashMap LinkedHashMap TreeMap
      LinkedList     LinkedHashSet  ArrayDeque
                     TreeSet        (also LinkedList)

Two details in this picture trip people up:

Map is not a Collection. A map stores key-value pairs, not single items, so it has its own tree. It's still part of the framework.
Iterable sits at the very top. Anything that is Iterable can be used in a for-each loop.

The Collection interface

Collection<E> is the root contract for groups of single items. Lists, sets and queues all extend it, so they all share the same basic methods:

add(item) and addAll(otherCollection)
remove(item) and removeAll(otherCollection)
contains(item) and containsAll(otherCollection)
size(), isEmpty() and clear()
iterator() to walk through the items
removeIf(condition), stream() and toArray()

Because they share this contract, you can write code against Collection and not care which kind you get:

Collection<String> names = new ArrayList<>();
names.add("Asha");
names.add("Ravi");
names.add("Asha");

System.out.println(names.size());
System.out.println(names.contains("Ravi"));
names.remove("Asha");
System.out.println(names);

Output:

3
true
[Ravi, Asha]

remove("Asha") removed only the first match. Now change one word, the implementation on the first line:

Collection<String> names = new HashSet<>();
// ...the same add calls as above...
System.out.println(names.size());

Output:

Everything else stayed the same, but a set ignores the second "Asha", so the size is 2. That's the power of programming to an interface: the rest of your code doesn't change when the structure does.

Looping and removing safely

Because every Collection is Iterable, you can loop with for-each. Behind the scenes, the compiler turns it into an iterator loop, using iterator(), hasNext() and next().

Here's a trap that almost everyone falls into: changing the collection while looping over it.

List<Integer> nums = new ArrayList<>(List.of(1, 2, 3, 4));

for (Integer n : nums) {
    if (n == 2) {
        nums.remove(n);
    }
}

Output:

Exception in thread "main" java.util.ConcurrentModificationException

Most collections are fail-fast. They count how many times they've been changed. The iterator remembers that count, and if it sees a different number, it throws this exception, instead of continuing with confusing data.

There are two safe ways:

List<Integer> nums = new ArrayList<>(List.of(1, 2, 3, 4));

Iterator<Integer> it = nums.iterator();
while (it.hasNext()) {
    if (it.next() % 2 == 0) {
        it.remove();          // removes through the iterator: allowed
    }
}
System.out.println(nums);

Output:

[1, 3]

Or, shorter, with removeIf: nums.removeIf(n -> n % 2 == 0);

The Collections class (with an "s")

Now the name that causes the most confusion. Let's separate them clearly:

Collection (no s) is an interface. It's the contract for a group of items.
Collections (with an s) is a utility class. It holds only static helper methods for working on collections. You never create an object of it.

A simple memory trick: the plural-named classes in Java are usually toolboxes of static methods. Collections works on collections, Arrays works on arrays, and Objects works on objects. You call their methods like Collections.sort(list).

   Collection<E>       interface   "what a group of items can do"      (you implement/use it)
   Collections         class       "helpers that work on collections"  (you just call its methods)

Algorithms

In the framework, an algorithm is a ready-made, reusable method that works on collections. They're all static methods in the Collections class, and the nice part is that they work on any List, whether it's an ArrayList or a LinkedList.

Here are the most useful ones:

List<Integer> nums = new ArrayList<>(List.of(5, 2, 9, 1, 7));

Collections.sort(nums);
System.out.println(nums);

System.out.println(Collections.binarySearch(nums, 7));

Collections.reverse(nums);
System.out.println(nums);

System.out.println(Collections.max(nums) + " " + Collections.min(nums));

Collections.swap(nums, 0, 4);
System.out.println(nums);

System.out.println(Collections.frequency(nums, 5));

Output:

[1, 2, 5, 7, 9]
3
[9, 7, 5, 2, 1]
9 1
[1, 7, 5, 2, 9]
1

What each one did:

sort put the list in ascending order.
binarySearch found 7 at index 3. The list must be sorted first, or the result is meaningless.
reverse flipped the order.
max and min found the biggest and smallest.
swap exchanged the items at positions 0 and 4.
frequency counted how many times 5 appears.

Others worth knowing: shuffle (random order), rotate, fill, nCopies, emptyList and addAll.

Sorting your own way

By default, sort uses the items' natural order (numbers ascending, strings alphabetical). For anything else, pass a Comparator, which is a rule for comparing two items:

List<String> names = new ArrayList<>(List.of("Meera", "Jo", "Ravi", "Asha"));

Collections.sort(names);
System.out.println(names);

Collections.sort(names, Comparator.comparing(String::length));
System.out.println(names);

Collections.sort(names, Collections.reverseOrder());
System.out.println(names);

Output:

[Asha, Jo, Meera, Ravi]
[Jo, Asha, Ravi, Meera]
[Ravi, Meera, Jo, Asha]

Look at the second line. Asha and Ravi both have 4 letters, and they kept their earlier order. That's because the sort is stable: equal items don't swap places.

Behind the scenes

Collections.sort(list) simply calls list.sort(...). For objects, Java uses TimSort, a fast and stable algorithm that takes about n log n steps. (For arrays of primitives, Arrays.sort uses a different algorithm, called dual-pivot quicksort.)
binarySearch repeatedly cuts the search range in half, so it takes about log n steps. It's very fast on an ArrayList, but slower on a LinkedList, which can't jump to the middle.

Read-only views and thread-safe wrappers

Collections can also wrap a collection to change its behavior:

List<String> original = new ArrayList<>(List.of("a", "b"));
List<String> readOnly = Collections.unmodifiableList(original);

original.add("c");
System.out.println(readOnly);

try {
    readOnly.add("d");
} catch (UnsupportedOperationException e) {
    System.out.println("Read-only!");
}

Output:

[a, b, c]
Read-only!

An unmodifiable list is a view, not a copy. You can't change it through readOnly, but when someone changes original, the view shows the change. If you want a real, independent, unchangeable copy, use List.copyOf(original). There's also Collections.synchronizedList(...) to make a list safe for several threads (although for new code, the classes in java.util.concurrent are usually a better choice).

Well-known collections

Now the real workers. Let's visit the four families.

List: ordered, with duplicates, accessed by position

A List keeps items in the order you add them, allows duplicates and lets you use an index.

ArrayList is the everyday choice. Behind the scenes, it keeps an array. When the array fills up, it creates a bigger one (about 1.5 times larger) and copies everything over.

List<String> fruits = new ArrayList<>();
fruits.add("Apple");
fruits.add("Banana");
fruits.add("Apple");
fruits.add(1, "Mango");

System.out.println(fruits);
System.out.println(fruits.get(2));
System.out.println(fruits.indexOf("Apple"));

Output:

[Apple, Mango, Banana, Apple]
Banana
0

   ArrayList is an array inside:

   [ Apple ][ Mango ][ Banana ][ Apple ][  ][  ]     size = 4, capacity = 6
      0        1        2        3
   get(2) jumps straight to slot 2. Adding in the middle shifts the items after it.

LinkedList stores each item in a small node that points to the previous and next ones:

   head --> [ prev | Apple  | next ] <--> [ prev | Mango | next ] <--> [ prev | Banana | next ] <-- tail

Adding or removing at the ends is very quick. But get(i) must walk node by node, so it's slow for big lists.

Set: no duplicates

A Set never holds the same item twice. add returns false if the item was already there:

Set<Integer> ids = new HashSet<>();

System.out.println(ids.add(10));
System.out.println(ids.add(10));
System.out.println(ids.size());

Output:

true
false
1

There are three common sets, and the only real difference is the order:

List<String> input = List.of("pear", "apple", "fig", "apple");

System.out.println(new LinkedHashSet<>(input));
System.out.println(new TreeSet<>(input));

Output:

[pear, apple, fig]
[apple, fig, pear]

HashSet: fastest, but the order is not guaranteed.
LinkedHashSet: keeps the order you inserted (pear, apple, fig).
TreeSet: keeps items sorted (apple, fig, pear).

Map: key to value

A Map stores pairs. Each key is unique, and it points to a value.

Map<String, Integer> marks = new HashMap<>();
marks.put("Asha", 88);
marks.put("Ravi", 72);
marks.put("Asha", 91);

System.out.println(marks.get("Asha"));
System.out.println(marks.size());
System.out.println(marks.getOrDefault("Meera", 0));

Output:

91
2
0

Putting "Asha" a second time replaced her old value. And getOrDefault gave 0 for a missing key, instead of null.

A very common job is counting. Here's a word counter that uses merge:

String text = "to be or not to be";
Map<String, Integer> counts = new TreeMap<>();

for (String word : text.split(" ")) {
    counts.merge(word, 1, Integer::sum);
}

System.out.println(counts);

Output:

{be=2, not=1, or=1, to=2}

Maps come in the same three flavors as sets: HashMap (fastest, no order), LinkedHashMap (insertion order) and TreeMap (sorted by key).

Behind the scenes: how HashMap finds things

A HashMap keeps an array of buckets. When you put a key, Java calls the key's hashCode(), turns it into a bucket number and stores the entry there. To find it again, it repeats the same steps, then uses equals() to pick the right entry if a bucket holds several.

   put("Asha", 91)
        |
   "Asha".hashCode()  -->  a number  -->  bucket index 3

   buckets:   [0] [1] [2] [3: Asha=91 -> Ravi=72] [4] [5] ...
                               ^
                   two keys landed in the same bucket (a "collision"),
                   so equals() decides which one you meant

This is why lookup is so quick (about one step on average, not a search through everything). A few details:

It starts with 16 buckets, and doubles when it's 75% full.
Since Java 8, a bucket that gets too crowded switches from a chain to a balanced tree, so even bad cases stay fast.
If you use your own class as a key, you must override both equals() and hashCode(), and keep them consistent. Otherwise, lookups will fail even for identical-looking objects.
A HashSet is secretly a HashMap (the items are the keys). In the same way, TreeSet is backed by a TreeMap, and LinkedHashSet by a LinkedHashMap.

Queue and Deque: waiting lines and stacks

A Queue processes items in order: first in, first out (FIFO). A Deque (double-ended queue) can add and remove at both ends, so it works as a stack too (last in, first out, LIFO).

Queue<String> line = new ArrayDeque<>();
line.offer("A");
line.offer("B");
line.offer("C");

System.out.println(line.poll());
System.out.println(line.peek());

Deque<Integer> stack = new ArrayDeque<>();
stack.push(1);
stack.push(2);
stack.push(3);

System.out.println(stack.pop());

Output:

A
B
3

offer adds, poll removes and returns the front, and peek looks at the front without removing.
For a stack, prefer ArrayDeque over the old Stack class.

A PriorityQueue doesn't use arrival order. It always gives you the smallest item first (or whatever your comparator says is first):

PriorityQueue<Integer> pq = new PriorityQueue<>(List.of(5, 1, 3));

System.out.println(pq.poll());
System.out.println(pq.poll());

Output:

1
3

Don't print the whole queue to check the order. Inside, it's a heap, and only the front is guaranteed to be the smallest.

How fast is each one?

Here is a rough guide to the speed of the common operations (n is the number of items):

ArrayList: get(i) is instant (O(1)). Adding at the end is fast (O(1) on average). Inserting or removing in the middle, or searching with contains, takes O(n).
LinkedList: adding or removing at the ends is O(1). get(i) and contains are O(n).
HashSet / HashMap: add, remove and lookup are O(1) on average.
TreeSet / TreeMap: add, remove and lookup are O(log n), and the items stay sorted.
ArrayDeque: adding and removing at either end is O(1).
PriorityQueue: add and poll are O(log n), and peek is O(1).

Which one should I use?

Start from what you need, and the choice is usually clear:

   Need to look things up by a KEY?          -> Map
        default: HashMap     sorted keys: TreeMap     insertion order: LinkedHashMap

   Need NO DUPLICATES?                       -> Set
        default: HashSet     sorted: TreeSet          insertion order: LinkedHashSet

   Need first-in-first-out, a stack,
   or "smallest first"?                      -> Queue / Deque
        ArrayDeque  or  PriorityQueue

   Otherwise, an ordered group?              -> List
        default: ArrayList

Some extra advice:

Default to ArrayList and HashMap. They're the best general-purpose choices. In practice, ArrayList beats LinkedList in most real cases, even for inserts, because arrays are friendly to the CPU.
Declare variables with the interface: List<String> names = new ArrayList<>();. Then you can swap the implementation by editing one word.
Collections hold objects, not primitives. Write List<Integer>, not List<int>. (This is where wrapper classes and autoboxing come in.)
Sorted data you keep changing? Use a TreeSet or TreeMap. Sorted once? Keep an ArrayList and call Collections.sort once.

Common mistakes

Mixing up Collection, Collections and Arrays. Collection is the interface. Collections and Arrays are classes of static helper methods.
Changing a collection while looping over it. It throws ConcurrentModificationException. Use an Iterator with remove(), or removeIf.
Using your own class as a key without equals() and hashCode(). Lookups fail, and duplicates sneak into sets. Also, don't change a key's fields after you've put it into a map or set.
Relying on the order of a HashSet or HashMap. It looks stable in small tests, then changes. If you need an order, choose LinkedHash... or Tree....
Calling get(i) in a loop over a LinkedList. Each call walks the list, so the loop becomes slow (O(n²)). Use for-each, or an ArrayList.
Forgetting that some lists can't be changed. List.of(...), List.copyOf(...) and Collections.unmodifiableList(...) throw UnsupportedOperationException on changes. Arrays.asList(1, 2, 3) has a fixed size, so add also fails. Wrap it in new ArrayList<>(...) when you need a normal list.

Also remember Collections.binarySearch only works on a list that's already sorted in the same order.

Quick recap

The Collections Framework is Java's ready-made toolbox in java.util: interfaces, implementations and algorithms.
Collection is the root interface for groups of items (List, Set, Queue). Map is separate, because it stores pairs.
Every Collection is Iterable, so for-each works, but don't change a collection while looping over it.
Collections (with an s) is a utility class of static methods: sort, binarySearch, reverse, shuffle, max, min, frequency, swap and wrappers like unmodifiableList.
List: ArrayList (array inside, the default) and LinkedList (nodes). Set: HashSet, LinkedHashSet, TreeSet. Map: HashMap, LinkedHashMap, TreeMap. Queue/Deque: ArrayDeque, PriorityQueue.
HashMap uses hashCode() to find a bucket and equals() to pick the entry, so your key classes need both.
Choose by need: key lookup, no duplicates, queue behavior or an ordered list. When unsure, start with ArrayList and HashMap.

Try it yourself

Here's a small practice idea: build a tiny contact book. Store contacts in a Map<String, String> (name to phone number) and print them sorted by name using a TreeMap. Then add every name to a List, sort it with Collections.sort by name length, and use Collections.binarySearch to find one name.

For a bonus experiment, create a Student class without equals() and hashCode(), and add two students with the same data to a HashSet. Notice that both get in. Then add the two methods and watch the duplicate disappear.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

Java Threads Explained: Scheduler, sleep and synchronized

Mayur Bodhare — Tue, 13 Oct 2026 17:28:35 +0000

My first multithreaded program printed its lines in a different order every time I ran it. My second one had a counter that should have ended at 200,000 and ended at 143,267. I ran it again and got 151,880. Same code, different answers.

I was sure my computer was broken. It wasn't. I had just met threads, and with them, two ideas that change how you think about programs: the order isn't guaranteed, and shared data can get corrupted.

In this post, we'll learn what threads are, how to create them, what the scheduler does, how priority and sleep work, the six states of a thread, and how synchronized fixes the counter bug. I've drawn the important pictures in text, and every claim comes with code you can run.

Unless I show a full class, the snippets go inside a main method that declares throws InterruptedException.

What is a thread?

A normal program does one thing at a time. If it downloads a file, the rest of the program waits. A thread is a separate path of execution inside your program, so several things can happen at the same time (or at least look like it).

Two words are worth separating:

A process is a running program, like your Java app. It has its own memory.
A thread lives inside a process. A process can have many threads, and they share the process's memory.

Every Java program starts with one thread called main:

System.out.println(Thread.currentThread().getName());

Output:

main

(The JVM also starts a few background threads of its own, like the garbage collector, but main is the one that runs your code.)

Behind the scenes: what threads share

Threads share the heap, where all objects live. But each thread gets its own stack, which holds its method calls and local variables.

   PROCESS (your running Java program)
  +----------------------------------------------------+
  |  HEAP: shared by all threads (objects live here)   |
  |                                                    |
  |   Thread "main"     Thread-0         Thread-1      |
  |   +-----------+     +-----------+    +-----------+ |
  |   | own stack |     | own stack |    | own stack | |
  |   | own PC    |     | own PC    |    | own PC    | |
  |   +-----------+     +-----------+    +-----------+ |
  +----------------------------------------------------+

(PC is the "program counter", which remembers which instruction the thread is on.)

This design is the source of both the benefit and the danger. Sharing the heap makes it easy for threads to cooperate. But when two threads change the same object at once, things can go wrong, as we'll see.

Creating threads

There are three common ways.

Way 1: extend `Thread`

class Worker extends Thread {
    @Override
    public void run() {
        System.out.println("Hello from " + Thread.currentThread().getName());
    }
}

new Worker().start();

Output:

Hello from Thread-0

You put the work inside run(), and you launch the thread with start(). Unnamed threads get names like Thread-0, Thread-1 and so on.

Way 2: implement `Runnable`

Runnable is a functional interface with one method, run(). You hand it to a Thread:

Runnable task = () -> System.out.println("Hello from " + Thread.currentThread().getName());
Thread t = new Thread(task, "worker-1");
t.start();

Output:

Hello from worker-1

Here the lambda is the Runnable, and "worker-1" is a name we picked.

Which way is better?

Prefer Runnable (or a lambda). It separates what to do (the task) from how to run it (the thread). It also leaves your class free to extend something else, since Java allows only one parent class.

`start()` vs `run()`: the classic mix-up

Thread t = new Thread(
    () -> System.out.println("Running in " + Thread.currentThread().getName()),
    "worker");

t.run();
t.start();

Output:

Running in main
Running in worker

Calling run() directly is just a normal method call, so it ran on the main thread. Only start() creates a new thread. If you want concurrency, always call start().

Also, a thread can be started only once. Calling start() a second time throws an IllegalThreadStateException.

Behind the scenes: what start() does

start() asks the JVM to create a real operating-system thread. When that thread is ready, it calls your run() method. When run() ends, the thread ends. (Java 21 also added lightweight virtual threads, which are managed by the JVM instead of the OS. For a beginner's first steps, the ordinary threads above are what matter.)

Waiting for a thread with join()

Often main needs to wait until a worker finishes. That's what join() is for:

Thread t = new Thread(() -> System.out.println("Worker done"));
t.start();
t.join();
System.out.println("Main continues");

Output:

Worker done
Main continues

Without join(), main might print first. join() makes the calling thread wait until t is finished. It throws InterruptedException, which is why our examples declare throws InterruptedException.

The thread scheduler

Here's the question that confused me most: if I start two threads, who decides which one runs first?

The answer is the thread scheduler. It's the part of the JVM and the operating system that decides which thread gets the CPU, and for how long. Most systems use time slicing: each runnable thread gets a short turn, then the scheduler may switch to another one.

   Time ------------------------------------------------>

   One CPU core:    | A | B | A | C | B | A | C |
                      each box = a short time slice

   Two CPU cores:   core 1:  | A | A | C | A |
                    core 2:  | B | B | B | C |
                      (A and B can truly run at the same time)

The key point: you don't control the scheduler, and the order isn't guaranteed. Let's prove it:

Runnable task = () -> {
    for (int i = 1; i <= 3; i++) {
        System.out.println(Thread.currentThread().getName() + " step " + i);
    }
};

new Thread(task, "A").start();
new Thread(task, "B").start();

One possible output:

A step 1
B step 1
A step 2
A step 3
B step 2
B step 3

Run it several times. Each thread's own steps stay in order (A1, A2, A3), but how A and B interleave changes from run to run. Sometimes A finishes entirely before B begins, and sometimes they alternate.

Two related words are often mixed up:

Concurrency means several tasks making progress during the same period, possibly by switching on one core.
Parallelism means several tasks running at the exact same moment on different cores.

States of a thread

During its life, a thread moves through several states. Java defines six of them in the Thread.State enum:

NEW: the Thread object exists, but start() hasn't been called yet.
RUNNABLE: the thread is running, or ready to run and waiting for the scheduler to give it a turn.
BLOCKED: the thread is waiting to get a lock held by another thread (we'll see this with synchronized).
WAITING: the thread waits indefinitely for another thread to do something, such as join() or wait() with no timeout.
TIMED_WAITING: the thread waits for a fixed time, such as sleep(1000) or join(1000).
TERMINATED: the thread has finished its run() method.

Here's how a thread moves between them:

                      start()
      NEW  ---------------------------->  RUNNABLE  <----------------------+
                                           |  |  |                         |
                                           |  |  |                         |
        waiting for a lock  <--------------+  |  +--------->  TIMED_WAITING|
              BLOCKED  ----- lock acquired ---+   sleep(ms), |  join(ms)   |
                                           |      wait(ms)    +--- time up -+
                                           |
                       wait(), join()      |
                  +--- WAITING <-----------+
                  |       |
                  |       +--- notified / joined thread ends ---> back to RUNNABLE
                  |
                  +---------   run() ends   ----------------->  TERMINATED

You can watch a thread change state with getState():

Thread t = new Thread(() -> {
    try {
        Thread.sleep(500);
    } catch (InterruptedException e) {
        // ignore for this demo
    }
});

System.out.println(t.getState());
t.start();
System.out.println(t.getState());
Thread.sleep(100);
System.out.println(t.getState());
t.join();
System.out.println(t.getState());

Output (in most runs, since it depends on timing):

NEW
RUNNABLE
TIMED_WAITING
TERMINATED

Notice there's no RUNNING state in Java. Many textbooks describe five states (new, runnable, running, blocked, dead), where "running" means "currently on the CPU." In Java, both "on the CPU" and "ready for the CPU" are just RUNNABLE, because the scheduler, not Java, decides that.

sleep()

Thread.sleep(milliseconds) makes the current thread pause for at least that long.

for (int i = 3; i >= 1; i--) {
    System.out.println(i);
    Thread.sleep(1000);
}
System.out.println("Go!");

Output (with about one second between lines):

3
2
1
Go!

Some important facts:

It pauses the current thread. sleep is a static method, so t.sleep(1000) also pauses the thread that calls it, not t. That's a common surprise.
While sleeping, the thread is in the TIMED_WAITING state and doesn't use the CPU.
It sleeps for at least the time given. The exact wake-up depends on the scheduler.
A sleeping thread keeps any locks it holds. This matters for synchronized, and it's the main difference from wait(), which releases the lock.
It throws the checked exception InterruptedException, so you must catch or declare it.

Interrupting a sleeping thread

Another thread can wake a sleeper early by calling interrupt(). The sleeping thread then gets an InterruptedException:

Thread t = new Thread(() -> {
    try {
        Thread.sleep(5000);
        System.out.println("Woke up normally");
    } catch (InterruptedException e) {
        System.out.println("Interrupted!");
    }
});

t.start();
t.interrupt();
t.join();

Output:

Interrupted!

Treat an interrupt as a polite request to stop. A good habit: don't swallow it silently. Either stop the work or restore the signal with Thread.currentThread().interrupt();.

Thread priority

Every thread has a priority from 1 to 10. The constants are:

Thread.MIN_PRIORITY = 1
Thread.NORM_PRIORITY = 5 (the default)
Thread.MAX_PRIORITY = 10

Thread t = new Thread(() -> { });

System.out.println(t.getPriority());
t.setPriority(Thread.MAX_PRIORITY);
System.out.println(t.getPriority());
System.out.println(Thread.currentThread().getPriority());

Output:

5
10
5

A new thread inherits the priority of the thread that created it. Here t started at 5 because main is at 5. Setting a value outside 1 to 10 throws an IllegalArgumentException.

The important truth is that priority is only a hint to the scheduler. A higher priority means "please prefer this thread," not "run this first." Java priorities are mapped onto the operating system's own priorities, and on many systems the effect is small or none. So:

Never rely on priority for correctness. If your program works only when thread A runs before thread B, use join() or proper coordination.
Use priority only as a mild tuning hint, if at all.

The problem: race conditions

Now the bug that gave me 143,267 instead of 200,000. We'll make two threads add to the same counter:

public class RaceDemo {
    static class Counter {
        private int count = 0;

        void increment() {
            count++;
        }

        int get() {
            return count;
        }
    }

    public static void main(String[] args) throws InterruptedException {
        Counter counter = new Counter();

        Runnable task = () -> {
            for (int i = 0; i < 100_000; i++) {
                counter.increment();
            }
        };

        Thread t1 = new Thread(task);
        Thread t2 = new Thread(task);
        t1.start();
        t2.start();
        t1.join();
        t2.join();

        System.out.println("Count: " + counter.get());
    }
}

Output (it will be different every time):

Count: 143267

We expected 200,000. Where did the missing increments go?

The culprit is count++. It looks like one step, but it's really three: read the value, add one, write it back. Two threads can mix those steps:

   count = 5

   Thread A:  read count (5)
   Thread B:  read count (5)
   Thread A:  add 1, write 6
   Thread B:  add 1, write 6        <-- B overwrote A's work!

   Two increments happened, but count went from 5 to 6 instead of 7.

This is called a race condition: the result depends on the exact timing of the threads. The code that touches the shared data, called the critical section, needs protection.

synchronized

The synchronized keyword makes sure that only one thread at a time can run a piece of code. Just add it to the method:

synchronized void increment() {
    count++;
}

Run the same program again:

Count: 200000

Every time, exactly 200,000.

How it works: the lock (monitor)

Every Java object has a hidden lock, also called a monitor. When a thread enters a synchronized method, it takes the lock of the object (this). Any other thread that tries to enter a synchronized method of that same object has to wait until the lock is released.

   counter object  (has one lock)

   Thread A  --> enters increment()  --> HOLDS the lock   --> runs count++  --> releases
   Thread B  --> tries increment()   --> BLOCKED, waiting for the lock ..........> then runs

When the lock is free, a waiting thread gets it and continues.

synchronized blocks

Locking a whole method can be too much. A synchronized block protects only the lines that need it, using any object as the lock:

class Counter {
    private int count = 0;
    private final Object lock = new Object();

    void increment() {
        // other work that doesn't need the lock could go here
        synchronized (lock) {
            count++;
        }
    }
}

Keep the locked section as small as possible, because while one thread holds the lock, the others are stuck waiting.

There's also a version for static methods. A static synchronized method locks the class object (Counter.class), since there's no this.

Seeing the BLOCKED state

Now we can finally see the BLOCKED state in action:

Object lock = new Object();

Thread holder = new Thread(() -> {
    synchronized (lock) {
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) { }
    }
});

Thread waiter = new Thread(() -> {
    synchronized (lock) {
        System.out.println("Got the lock");
    }
});

holder.start();
Thread.sleep(100);
waiter.start();
Thread.sleep(100);

System.out.println(waiter.getState());

Output:

BLOCKED
Got the lock

holder grabbed the lock and went to sleep while still holding it (remember, sleep doesn't release locks). waiter then arrived and found the lock taken, so it sat in the BLOCKED state. About a second later, holder finished, waiter got the lock, and "Got the lock" printed.

Behind the scenes

For a synchronized block, the compiler writes two bytecode instructions, monitorenter and monitorexit, around your code. It also adds a hidden exception handler, so the lock is always released, even if your code throws an exception.
For a synchronized method, the method is simply marked with a flag in the .class file, and the JVM takes and releases the lock around the call.
The lock is reentrant: a thread that already holds a lock can enter other synchronized code on the same object without blocking itself.
synchronized does two jobs. It gives mutual exclusion (one thread at a time), and it guarantees visibility (when a thread releases a lock, its changes are visible to the next thread that takes it).

A word on deadlock

If thread A holds lock 1 and waits for lock 2, while thread B holds lock 2 and waits for lock 1, both wait forever. That's a deadlock. The simplest defense is to always take multiple locks in the same order in every thread.

Which one should I use?

Thread or Runnable? Use Runnable (or a lambda). It keeps the task separate from the thread, and your class stays free to extend another class.
Raw threads or an ExecutorService? In real applications, prefer an executor (a thread pool), because creating threads is expensive and a pool reuses them. Raw threads are good for learning and for very simple cases. For huge numbers of blocking tasks, newer Java versions offer virtual threads.
synchronized method or block? Use a block when only part of the method needs protection. It keeps the locked time short.
synchronized or AtomicInteger? For a single counter, AtomicInteger and its incrementAndGet() method are simpler and often faster. Use synchronized when several variables must change together.
sleep or something smarter? sleep is fine for pauses and demos. To wait for a condition or for another thread, use join(), wait()/notify() or tools like CountDownLatch, instead of sleeping and hoping.
Priority? Leave it at the default. Never make correctness depend on it.

Common mistakes

Calling run() instead of start(). The code runs on the current thread, and no new thread is created.
Starting the same thread twice. The second start() throws IllegalThreadStateException. Create a new Thread object instead.
Assuming a thread order. The scheduler decides, and the order changes between runs. Don't use sleep or priority to force an order. Use join() or proper coordination.
Sharing changeable data without protection. The result is a race condition like our counter. Also check that all threads use the same lock object. Locking on a new object each time, like synchronized (new Object()), protects nothing.
Swallowing InterruptedException. An empty catch hides the stop request. Either stop the work, or restore the flag with Thread.currentThread().interrupt().
Holding a lock for too long. Calling sleep or doing slow work inside synchronized makes every other thread wait. Also watch out for deadlock, and take locks in a fixed order.

Quick recap

A thread is an independent path of execution inside a process. Threads share the heap, and each has its own stack.
Create threads with Runnable (or a lambda) and Thread, and launch them with start(), not run(). Use join() to wait for one to finish.
The thread scheduler (JVM plus OS) decides who runs and for how long. The order isn't guaranteed.
A thread's states: NEW, RUNNABLE, BLOCKED, WAITING, TIMED_WAITING, TERMINATED.
sleep(ms) pauses the current thread without releasing locks, and it can be interrupted.
Priority (1 to 10, default 5) is only a hint, so don't depend on it.
A race condition happens when threads change shared data at the same time. count++ is three steps, not one.
synchronized lets one thread at a time into a critical section by using the object's lock, and it also makes changes visible to other threads. Keep locked sections small.

Try it yourself

Here's a small practice idea: build a BankAccount with a balance and a deposit method. Start two threads that each deposit 1 rupee 100,000 times, and print the final balance. Run it a few times to see the wrong answers, then add synchronized and see it become correct every time.

For a bonus experiment, print getState() for a thread at each stage: before start(), while sleeping, while blocked on a lock, and after it finishes. Then try giving two threads different priorities and see whether the output on your machine changes at all.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

throw vs throws in Java, and What “Ducking” Means

Mayur Bodhare — Tue, 13 Oct 2026 17:27:40 +0000

The first time one of my Java programs crashed, I got a wall of red text that ended with something like Exception in thread "main". I had no idea what it meant, which line to look at or how to stop it from happening again.

Later I learned try and catch, and I thought I understood. Then more questions showed up. What's the difference between throw and throws? What does "ducking an exception" mean? Why does my Scanner crash when the user types a word instead of a number? And why do people say finally isn't enough anymore?

In this post, we'll answer all of that in one place: exceptions, the exception hierarchy, try, catch, finally, throw, throws, ducking, the Scanner class and try-with-resources. I've drawn the key pictures in text so you can see how things flow.

Unless I show a full class, the snippets go inside a main method.

What is an exception?

An exception is an unexpected event that happens while a program is running and disrupts its normal flow. Dividing by zero, reading a file that doesn't exist or calling a method on null are all examples.

Let's see what happens when nobody handles one:

public class Demo {
    public static void main(String[] args) {
        int a = 10, b = 0;
        System.out.println("Before");
        System.out.println(a / b);
        System.out.println("After");
    }
}

Output:

Before
Exception in thread "main" java.lang.ArithmeticException: / by zero
    at Demo.main(Demo.java:5)

Three things to notice:

"Before" printed, but "After" never did. The program stopped at the problem.
The first line tells you the type (ArithmeticException) and a message (/ by zero).
The at Demo.main(Demo.java:5) line is the stack trace. It tells you where it happened: file Demo.java, line 5. When you read a crash, start at the top and look for the first line that points to your own code.

Behind the scenes: what the JVM does

When something goes wrong, the JVM creates an exception object, fills it with the details (type, message and the call stack) and throws it. The current method stops immediately. Then the JVM goes looking for code that can handle it, first in the current method, then in the method that called it, then the one that called that, moving up the call stack.

   main()  calls  process()  calls  divide()      <-- exception happens here
     ^               ^                 |
     |               |                 |
     +---------------+-----------------+
        the JVM unwinds UP the call stack, looking for a matching catch

   Nobody catches it?  The thread ends and the stack trace is printed.

Exception handling is simply the art of catching it on the way up so the program can continue.

The exception hierarchy

Exceptions are objects, so they're organized into a family tree of classes. Knowing this tree tells you which exceptions you must handle and which you can ignore.

                          Throwable
                         /         \
                    Error           Exception
        (OutOfMemoryError,         /          \
         StackOverflowError)   IOException      RuntimeException
                               SQLException      ArithmeticException
                               FileNotFound-     NullPointerException
                                 Exception       ArrayIndexOutOfBounds-
                               InterruptedException   Exception
                                                 IllegalArgumentException
                               (CHECKED)            NumberFormatException
                                                 InputMismatchException
                                                    (UNCHECKED)

Here's what each branch means:

Throwable is the root. Only objects of this class (or its children) can be thrown. It gives you getMessage(), printStackTrace() and getCause().
Error means a serious problem in the JVM itself, like running out of memory (OutOfMemoryError) or endless recursion (StackOverflowError). You normally don't catch these, because your program can't repair them.
Exception is for problems your program can reasonably handle. It splits into two kinds:

Checked exceptions are everything under Exception except RuntimeException. They're for things outside your program's control, like missing files or network failures (IOException, SQLException). The compiler forces you to handle them or declare them.

new FileReader("data.txt");

unreported exception FileNotFoundException; must be caught or declared to be thrown

Unchecked exceptions are RuntimeException and its children. They usually mean a bug in your code (a bad index, a null reference, a bad argument). The compiler does not force you to handle them, although you still can.

A simple way to remember it: checked means "the compiler checks that you dealt with it," and unchecked means "the compiler leaves it to you."

try and catch

To handle an exception, wrap the risky code in try and write the response in catch:

try {
    int result = 10 / 0;
    System.out.println("Result: " + result);
} catch (ArithmeticException e) {
    System.out.println("Cannot divide by zero: " + e.getMessage());
}
System.out.println("Program continues");

Output:

Cannot divide by zero: / by zero
Program continues

What happened:

Java ran the try block until the exception happened.
It skipped the rest of the try block (so "Result: ..." never printed).
It jumped to the matching catch and ran it.
The program continued normally after the try-catch. No crash.

The variable e is the exception object. Printing it directly gives the type and message together: java.lang.ArithmeticException: / by zero.

Multiple catch blocks

One try can have several catch blocks for different problems. Java runs only the first one that matches:

String[] data = {"10", "abc"};

try {
    int n = Integer.parseInt(data[1]);
    System.out.println(10 / n);
} catch (NumberFormatException e) {
    System.out.println("Not a number: " + e.getMessage());
} catch (ArithmeticException e) {
    System.out.println("Math problem");
} catch (Exception e) {
    System.out.println("Something else: " + e);
}

Output:

Not a number: For input string: "abc"

Order matters. Put the most specific exceptions first and the most general last. If you put Exception first, it would catch everything, and the later blocks could never run. The compiler notices and stops you:

exception ArithmeticException has already been caught

If two exceptions need the same handling, you can combine them with |:

catch (NumberFormatException | ArithmeticException e) {
    System.out.println("Bad input: " + e.getMessage());
}

(The two types can't be parent and child of each other.)

Behind the scenes

The compiler doesn't turn try-catch into extra checks that run on every line. Instead, it writes an exception table next to your bytecode. Each row says: "if an exception of this type happens between instruction A and instruction B, jump to the handler at instruction C." When nothing goes wrong, the table is never used, so a try block costs almost nothing. The real cost comes when an exception is created, because the JVM has to record the stack trace.

finally

Sometimes you need code that runs no matter what, like closing a file or releasing a lock. That's what finally is for:

static void test(int divisor) {
    try {
        System.out.println(10 / divisor);
    } catch (ArithmeticException e) {
        System.out.println("Caught");
    } finally {
        System.out.println("Cleanup");
    }
}

test(2);
test(0);

Output:

5
Cleanup
Caught
Cleanup

The finally block ran in both cases: when everything went fine, and when an exception happened. Here is the flow:

        try block
           |
     exception happened?
      /              \
    no               yes
     |                |
     |         matching catch? -- yes --> run the catch block
     |                |                          |
     |                no                         |
     |       (exception will keep going up)      |
     v                v                          v
   +--------------------------------------------------+
   |        finally block ALWAYS runs here            |
   +--------------------------------------------------+
           |
           v
   continue the program, or keep propagating the exception

try-catch-finally, try-finally

The combinations you can write:

try + catch (one or more)
try + catch + finally
try + finally (no catch at all)

The last one is valid, and it's useful when you want to clean up but let the exception continue to the caller:

try {
    System.out.println("working");
    throw new RuntimeException("boom");
} finally {
    System.out.println("cleanup");
}

Output:

working
cleanup
Exception in thread "main" java.lang.RuntimeException: boom

The cleanup ran first, and then the exception continued upward and crashed the program, because nobody caught it.

When does finally NOT run?

Almost never. It runs even if the try block has a return:

static int f() {
    try {
        return 1;
    } finally {
        System.out.println("finally runs");
    }
}

System.out.println(f());

Output:

finally runs
1

It will not run if the JVM stops (for example System.exit(0)), if the machine crashes or if the try block never ends (an infinite loop).

One warning: never write return or throw inside finally. It can silently replace the real result or hide an exception.

Behind the scenes

The compiler copies the finally code to every exit path: the normal end of try, the end of each catch, and every return. It also adds an "any exception" handler that runs the finally code and then rethrows. That's how Java promises it always runs.

throw vs throws

These two look almost the same and trip up everyone, but they do different jobs.

throw is a statement that actually throws an exception object. You use it inside a method body when you detect a problem.

static void setAge(int age) {
    if (age < 0) {
        throw new IllegalArgumentException("Age cannot be negative");
    }
    System.out.println("Age set to " + age);
}

try {
    setAge(25);
    setAge(-5);
} catch (IllegalArgumentException e) {
    System.out.println("Error: " + e.getMessage());
}

Output:

Age set to 25
Error: Age cannot be negative

throws is part of a method's signature. It warns callers that this method might throw certain exceptions, so they must be ready.

void readFile(String path) throws IOException, SQLException { ... }

Here's the difference in short:

throw throws one exception object, and it's written inside the method body, followed by new SomeException(...).
throws declares possible exceptions, and it's written after the parameter list, followed by class names (one or more, separated by commas).
throw is the action. throws is the warning label.
throws is required for checked exceptions (otherwise the compiler complains). For unchecked ones it's optional.

A trick to remember it: throw, singular, is one throw. throws, plural, can list many.

Custom exceptions

You can write your own exception by extending Exception (checked) or RuntimeException (unchecked). Let's make a checked one for a bank account:

class InsufficientFundsException extends Exception {
    InsufficientFundsException(String message) {
        super(message);
    }
}

class Account {
    private double balance = 500;

    void withdraw(double amount) throws InsufficientFundsException {
        if (amount > balance) {
            throw new InsufficientFundsException(
                "Balance " + balance + " is less than " + amount);
        }
        balance -= amount;
        System.out.println("Withdrawn " + amount);
    }
}

Account account = new Account();

try {
    account.withdraw(200);
    account.withdraw(600);
} catch (InsufficientFundsException e) {
    System.out.println("Failed: " + e.getMessage());
}

Output:

Withdrawn 200.0
Failed: Balance 300.0 is less than 600.0

Because InsufficientFundsException is checked, the compiler forced two things: withdraw had to declare throws, and the caller had to catch it (or declare it too).

Ducking an exception

Now the funny word. Ducking an exception means not handling it in this method, and passing it on to the caller by declaring it with throws. The method "ducks" out of the way, and the problem flies over its head to whoever called it.

static void level3() throws Exception {
    throw new Exception("Problem in level3");
}

static void level2() throws Exception {
    level3();                  // no try-catch here: level2 ducks it
}

static void level1() {
    try {
        level2();
    } catch (Exception e) {
        System.out.println("Handled in level1: " + e.getMessage());
    }
}

level1();

Output:

Handled in level1: Problem in level3

   level1()  --calls-->  level2()  --calls-->  level3()
      ^                     ^                     |
      |                     |                     | throw new Exception(...)
      |                     +----- DUCKS ---------+  (just declares "throws")
      |                                           
      +------- CATCHES it and handles the problem

When should you catch, and when should you duck?

Catch where you can do something useful: show a message, retry, use a default value or clean up.
Duck when this method can't decide what to do, and a higher-level method is in a better position. A low-level file reader doesn't know whether to show a popup or write a log, but the code that called it does.

Be careful with one case: if main ducks (public static void main(String[] args) throws Exception), the exception goes to the JVM, and your program crashes. That's fine for quick experiments, but not for real programs.

The Scanner class

Now let's apply this to something you'll use constantly. The Scanner class (in java.util) reads input: from the keyboard, from a file or from a string. It splits the input into pieces called tokens, separated by whitespace by default.

The most-used methods are:

nextInt(), nextDouble(), nextBoolean() read the next token as that type.
next() reads the next word (one token).
nextLine() reads the whole rest of the line.
hasNextInt(), hasNext() check whether the next token exists or has the right type, without reading it.
close() releases the resource.

import java.util.Scanner;

public class Greeting {
    public static void main(String[] args) {
        Scanner sc = new Scanner(System.in);

        System.out.print("Enter your name: ");
        String name = sc.nextLine();

        System.out.print("Enter your age: ");
        int age = sc.nextInt();

        System.out.println("Hello " + name + ", next year you will be " + (age + 1));
        sc.close();
    }
}

A sample run (the second part of each line is what the user types):

Enter your name: Asha
Enter your age: 25
Hello Asha, next year you will be 26

Behind the scenes

System.in is a stream of raw bytes from the keyboard. The Scanner wraps it, reads the bytes into a buffer, and hands them to you one token at a time:

   keyboard --> System.in (bytes) --> Scanner's buffer --> tokens --> your variables

   You type:   25 [Enter]
   Buffer:     2 5 \n
               ^^^^
               nextInt() takes the token "25" and checks it looks like an int
               The "\n" (the Enter key) stays behind in the buffer

Two details here matter for everything that follows:

nextInt() takes the token, but it leaves the newline (\n) in the buffer.
If the token isn't a valid number, nextInt() throws an InputMismatchException and leaves the bad token in the buffer (it does not consume it).

The famous nextLine trap

Let's flip the order of our program and read the age first, then the name:

System.out.print("Enter age: ");
int age = sc.nextInt();

System.out.print("Enter name: ");
String name = sc.nextLine();

System.out.println("Age: " + age + ", Name: [" + name + "]");

A sample run:

Enter age: 25
Enter name: Age: 25, Name: []

The program never waited for the name! After nextInt(), the buffer still held \n. Then nextLine() read from the current position to the end of the line, which is nothing, so it returned an empty string right away.

   Buffer after nextInt():     \n
                               ^^
   nextLine() reads "everything up to the newline", which is an empty text

The fix is to eat the leftover newline with an extra nextLine():

int age = sc.nextInt();
sc.nextLine();                 // consume the leftover newline
String name = sc.nextLine();   // now this waits for the real name

Another safe option is to read everything with nextLine() and convert yourself: int age = Integer.parseInt(sc.nextLine());.

Exceptions that Scanner can throw

InputMismatchException (unchecked): the token isn't the right type, like "abc" for nextInt().
NoSuchElementException (unchecked): there's no more input to read.
IllegalStateException (unchecked): you used the scanner after closing it.
FileNotFoundException (checked): when creating a Scanner from a File that doesn't exist.

Scanner with exception handling

Here's the classic job: keep asking until the user types a valid age.

import java.util.InputMismatchException;
import java.util.Scanner;

public class SafeInput {
    public static void main(String[] args) {
        Scanner sc = new Scanner(System.in);
        int age = 0;
        boolean valid = false;

        while (!valid) {
            try {
                System.out.print("Enter your age: ");
                age = sc.nextInt();

                if (age < 0 || age > 120) {
                    throw new IllegalArgumentException("Age must be between 0 and 120");
                }
                valid = true;

            } catch (InputMismatchException e) {
                System.out.println("Please enter digits only.");
                sc.nextLine();                    // throw away the bad input

            } catch (IllegalArgumentException e) {
                System.out.println(e.getMessage());
            }
        }

        System.out.println("Age accepted: " + age);
    }
}

A sample run, where the user types abc, then -5, then 25:

Enter your age: abc
Please enter digits only.
Enter your age: -5
Age must be between 0 and 120
Enter your age: 25
Age accepted: 25

Look at how our new tools work together:

nextInt() throws InputMismatchException for abc, and the catch handles it.
We used throw ourselves for a value that is a valid number but makes no sense (-5).
The sc.nextLine() inside the first catch is essential. Remember: the bad token stays in the buffer. Without that line, the next nextInt() would see abc again, throw again, and the loop would repeat forever.

An alternative without exceptions

When bad input is expected (users make typos all the time), you can check first instead of catching:

Scanner sc = new Scanner(System.in);

System.out.print("Enter a number: ");
while (!sc.hasNextInt()) {
    System.out.println("Digits only, please.");
    sc.next();                      // discard the bad token
    System.out.print("Enter a number: ");
}
int n = sc.nextInt();
System.out.println("You entered " + n);

A sample run:

Enter a number: hello
Digits only, please.
Enter a number: 7
You entered 7

Both approaches are fine. The hasNextInt() style treats bad input as normal, so it needs no exception at all.

try-with-resources

Many things you use must be closed when you're done: a Scanner, files, network connections, database connections. If you forget, they leak. The old way was a finally block:

Scanner sc = null;
try {
    sc = new Scanner(new File("data.txt"));
    System.out.println(sc.nextLine());
} catch (FileNotFoundException e) {
    System.out.println("File not found");
} finally {
    if (sc != null) {
        sc.close();
    }
}

That's a lot of code just to close something, and it's easy to get wrong. try-with-resources does it for you. You open the resource inside parentheses after try, and Java closes it automatically at the end:

try (Scanner sc = new Scanner(new File("data.txt"))) {
    System.out.println(sc.nextLine());
} catch (FileNotFoundException e) {
    System.out.println("File not found");
}

No finally, no null check, no close() call. The rules:

The resource's class must implement AutoCloseable (or Closeable, which extends it). Scanner does.
The resource variable is implicitly final.
You can open several resources, separated by semicolons.
catch and finally blocks are optional.
Since Java 9, you can use an existing effectively final variable: try (sc) { ... }.

What happens in what order?

Let's use a custom resource to see the exact order:

class Resource implements AutoCloseable {
    private final String name;

    Resource(String name) {
        this.name = name;
        System.out.println("Open " + name);
    }

    void use() {
        System.out.println("Using " + name);
    }

    @Override
    public void close() {
        System.out.println("Close " + name);
    }
}

try (Resource a = new Resource("A"); Resource b = new Resource("B")) {
    a.use();
    b.use();
    throw new RuntimeException("Oops");
} catch (RuntimeException e) {
    System.out.println("Caught " + e.getMessage());
} finally {
    System.out.println("Finally");
}

Output:

Open A
Open B
Using A
Using B
Close B
Close A
Caught Oops
Finally

Two rules are visible here:

Resources are closed in reverse order of opening (B before A), like unstacking plates.
They're closed before the catch and finally blocks run. So by the time your catch executes, the resources are already safely closed.

Behind the scenes

The compiler rewrites try-with-resources into a try-finally, roughly like this:

   try (Resource r = new Resource()) {          Resource r = new Resource();
       use(r);                          ==>     Throwable primary = null;
   }                                            try {
                                                    use(r);
                                                } catch (Throwable t) {
                                                    primary = t;  throw t;
                                                } finally {
                                                    if (r != null) {
                                                        if (primary != null) {
                                                            try { r.close(); }
                                                            catch (Throwable s) { primary.addSuppressed(s); }
                                                        } else {
                                                            r.close();
                                                        }
                                                    }
                                                }

You don't need to memorize this. The key part is the suppressed exception handling. What if your code throws an exception and close() also throws? With a hand-written finally, the second exception would replace the first one, and you'd lose the real cause. With try-with-resources, the original exception stays as the main one, and the close failure is attached to it as a suppressed exception that you can read with e.getSuppressed(). That's one more reason it's better than a manual finally.

Here's the earlier idea with a Scanner, fully contained, with no files and no keyboard, so you can run it right now:

try (Scanner sc = new Scanner("10 20 abc")) {
    int sum = 0;
    while (sc.hasNext()) {
        sum += sc.nextInt();
    }
    System.out.println(sum);
} catch (InputMismatchException e) {
    System.out.println("Bad number found");
}

Output:

Bad number found

A Scanner can read from a plain String, so "10 20 abc" is our fake input. It added 10 and 20, then hit abc and threw. The scanner was closed automatically, and the catch handled the problem.

One note about the keyboard: if you wrap new Scanner(System.in) in try-with-resources, closing it also closes System.in, and you can't read from the keyboard again later in the same program. For a console program that finishes right after, that's fine. Just don't create and close several scanners on System.in.

Which one should I use?

try-catch or just let it crash? Catch an exception when you can do something useful about it (retry, use a default, show a clear message). If you can't, let it travel up, or duck it.
Catch or duck? Catch it in the method that knows what to do. Duck it when a higher level is in a better position to decide.
try-catch-finally or try-with-resources? If the thing you're closing implements AutoCloseable (files, scanners, connections), use try-with-resources. Use a plain finally only for cleanup that isn't a closeable resource, like resetting a flag or unlocking a lock.
Checked or unchecked for my own exceptions? Make it checked when the caller can realistically recover from it (like InsufficientFundsException). Make it unchecked for programming mistakes (like a bad argument). Modern code leans toward unchecked, because checked ones force a lot of boilerplate.
Scanner: hasNextInt() or try-catch? Use hasNextInt() when bad input is a normal, expected thing. Use try-catch when you read many values and want a single place to handle failure.

Common mistakes

Empty catch blocks. catch (Exception e) { } hides the problem completely. At the very least, print or log the exception.
Catching Exception or Throwable everywhere. It also swallows bugs you wanted to see, and Throwable even catches serious Errors. Catch the most specific type you can handle.
Putting a general catch before a specific one. The compiler says the specific exception "has already been caught." Specific first, general last.
Forgetting to close resources. Use try-with-resources so you never have to remember.
Falling into the Scanner traps. Using nextLine() right after nextInt() without consuming the newline, and not clearing a bad token after InputMismatchException (which causes an infinite loop).
Mixing up throw and throws. throw goes in the body with an object (throw new X()). throws goes on the method signature with class names. Writing throws new X() or throw X is a compile error.

Another habit to avoid is using exceptions for normal flow, like looping until an exception happens. Exceptions are for exceptional situations, and they're slower than a simple if.

Quick recap

An exception is an object that represents a problem at run time. If nobody handles it, the program stops with a stack trace.
The tree: Throwable splits into Error (don't catch) and Exception. Under Exception, checked exceptions must be handled or declared, and unchecked ones (RuntimeException and children) are optional.
try wraps risky code, catch handles it (specific first, general last), and finally always runs.
throw throws one exception object inside a method. throws declares what a method might throw.
Ducking means declaring throws instead of catching, so the caller deals with it.
Scanner reads tokens from the keyboard, files or strings. nextInt() leaves the newline behind, and a bad token stays in the buffer.
Handle bad input with try-catch plus sc.nextLine() to clear it, or check ahead with hasNextInt().
try-with-resources closes AutoCloseable resources automatically, in reverse order, before catch and finally, and it keeps the original exception safe.

Try it yourself

Here's a small practice idea: build a console calculator. Ask the user for two numbers and an operator (+, -, *, /) using Scanner. Keep asking until the numbers are valid. Handle division by zero with try-catch, and throw your own InvalidOperatorException (a custom checked exception) if the operator isn't one of the four. Wrap the whole Scanner in try-with-resources.

For a bonus experiment, create a text file with a few numbers and read it using new Scanner(new File("numbers.txt")). Handle the FileNotFoundException, then try renaming the file to see the exception in action.

If this helped, or if you spotted something I should fix, tell me in the comments. I'm still learning too.

DEV Community: Mayur Bodhare

What Does SpringApplication.run Actually Do?

Table of contents

The problem: creating objects yourself

Tight coupling with new

Loose coupling with an interface

What is the Spring Framework?

A short history

The main modules

IoC and DI

Inversion of Control

Dependency Injection

IoC vs DI

The Spring container and beans

Spring with XML: the classic way

Project setup

The Java classes

Understanding spring.xml

Running the XML configuration

Injecting with property and constructor arguments

Autowiring in XML: byName and byType

Resolving conflicts with primary

Scope: singleton and prototype

Annotation and Java configuration

Stereotype annotations: @Component and friends

Java configuration: @Configuration and @bean

What is Spring Boot?

The base idea

What Spring Boot adds

Spring vs Spring Boot vs Spring Web

Spring Boot architecture

Inside Spring Boot

How @SpringBootApplication works

The layers of a Spring Boot application

Your first Spring Boot application

Creating the project with Spring Initializr

Understanding the starter code

Adding beans: Dev, Computer and Laptop

Running the application

The three types of dependency injection

Constructor injection

Setter injection

Field injection

Which injection to use

Resolving ambiguity: @primary and @Qualifier

The lifecycle of a bean

Building a web endpoint with Spring Web

Configuration with application.properties

Running, packaging and testing

Best practices

Which one should I use?

Common mistakes

Quick recap

Try it yourself

Why ORMs Exist: The Object-Relational Mismatch

Table of contents

What is an ORM?

The problem: objects and tables do not match

How an ORM solves it

The same job, with and without an ORM

Popular ORM tools

Pros and cons of ORMs

Advantages

Disadvantages

What is Hibernate?

How Hibernate fits in

The core pieces: SessionFactory, Session and Transaction

The life of an entity

Setting up PostgreSQL for the examples

The common code: entity and main class

The entity class

The main class

Using Hibernate without Maven

Step by step without Maven

Using Hibernate with Maven

Step by step with Maven

Common Hibernate methods

Saving, reading, updating and deleting

Queries with HQL

Managing the persistence context